From d50bfedb4e0c1245292b398b9f0cbc539697073b Mon Sep 17 00:00:00 2001
From: 0xpantera <0xpantera@proton.me>
Date: Fri, 19 Jun 2026 13:52:23 +0200
Subject: [PATCH 1/2] docs: require branch hygiene preflight

---
 AGENTS.md | 15 +++++++++++++++
 CLAUDE.md | 16 ++++++++++++++++
 2 files changed, 31 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 71db85f..2a4a266 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -28,6 +28,21 @@ Treat key material with care.
 - Test: `cargo test --workspace`.
 - Bump the git GPUI stack: `just bump-gpui` (the ONLY way to change those pins).
 
+## Branch hygiene — required before edits
+Before changing files, always establish the current branch and its source-of-truth status:
+
+1. Run `git status --short --branch`.
+2. If on `main`, run `git fetch origin --prune`, fast-forward from `origin/main`, then create a new
+   feature branch before editing.
+3. If not on `main`, run `git fetch origin --prune` and check whether the branch has already been
+   merged into current `origin/main`.
+   - If it has been merged, switch back to `main`, fast-forward from `origin/main`, and create a new
+     feature branch before editing.
+   - If it has not been merged, inspect the branch's upstream/ahead/behind state and update local
+     state before editing. Do not stack unrelated work on a stale or merged branch.
+4. If there are uncommitted changes, identify whether they are user changes before switching,
+   rebasing, stashing, or applying patches.
+
 ## Definition of done (all must hold; show command output as evidence)
 1. `cargo fmt --all --check` clean
 2. `just check` green (both feature configs)
diff --git a/CLAUDE.md b/CLAUDE.md
index f209c70..44988a4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -32,6 +32,22 @@ before you're done. (For UI work you must build the app: `just check`.)
 4. No new or changed dependencies (`Cargo.toml` / `Cargo.lock`) unless explicitly approved
    (the git GPUI stack is bumped only via `just bump-gpui` — never hand-edit those pins)
 
+## Branch hygiene — required before edits
+
+Before changing files, always establish the current branch and its source-of-truth status:
+
+1. Run `git status --short --branch`.
+2. If on `main`, run `git fetch origin --prune`, fast-forward from `origin/main`, then create a new
+   feature branch before editing.
+3. If not on `main`, run `git fetch origin --prune` and check whether the branch has already been
+   merged into current `origin/main`.
+   - If it has been merged, switch back to `main`, fast-forward from `origin/main`, and create a new
+     feature branch before editing.
+   - If it has not been merged, inspect the branch's upstream/ahead/behind state and update local
+     state before editing. Do not stack unrelated work on a stale or merged branch.
+4. If there are uncommitted changes, identify whether they are user changes before switching,
+   rebasing, stashing, or applying patches.
+
 ## Code constraints
 
 **Enforced workspace-wide** by `[workspace.lints]` + `clippy.toml` (CI fails the build):

From b543e433cd28421e90ebb5c4a7c39e3683359232 Mon Sep 17 00:00:00 2001
From: 0xpantera <0xpantera@proton.me>
Date: Fri, 19 Jun 2026 13:52:38 +0200
Subject: [PATCH 2/2] test: add browser extension QA harness

---
 .gitignore                                    |   7 +
 docs/browser-extension-qa.md                  |  89 +++++++
 examples/browser-bridge-dapp/index.html       |   1 +
 package-lock.json                             |  76 ++++++
 package.json                                  |  13 +
 playwright.extension.config.ts                |  28 +++
 .../browser-bridge-extension.spec.ts          |  76 ++++++
 tests/extension/fixtures.ts                   | 238 ++++++++++++++++++
 8 files changed, 528 insertions(+)
 create mode 100644 docs/browser-extension-qa.md
 create mode 100644 package-lock.json
 create mode 100644 package.json
 create mode 100644 playwright.extension.config.ts
 create mode 100644 tests/extension/browser-bridge-extension.spec.ts
 create mode 100644 tests/extension/fixtures.ts

diff --git a/.gitignore b/.gitignore
index af1b6bf..39c6b9f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -9,3 +9,10 @@
 
 # gstack local reports
 .gstack/
+
+# Playwright extension QA artifacts
+/node_modules/
+/playwright-report/
+/test-results/
+/blob-report/
+/.playwright/
diff --git a/docs/browser-extension-qa.md b/docs/browser-extension-qa.md
new file mode 100644
index 0000000..c345307
--- /dev/null
+++ b/docs/browser-extension-qa.md
@@ -0,0 +1,89 @@
+# Browser extension QA
+
+Deckard's browser connector is a local-only, experimental extension. This QA harness is a
+small Playwright smoke suite, not a full end-to-end wallet test suite. It checks that the
+unpacked extension loads in Chromium, injects the EIP-1193 provider, and can connect the local
+test dapp through the Deckard browser bridge.
+
+The suite follows Playwright's Chrome extension guidance: extensions run in Chromium through a
+persistent browser context, loaded with `--disable-extensions-except` and `--load-extension`.
+Manifest V3 uses a service worker, so the extension id is derived from the service worker URL.
+
+## Install
+
+Install the Node dependencies:
+
+```sh
+npm install
+```
+
+Install Playwright's bundled Chromium:
+
+```sh
+npm run qa:browser:install
+```
+
+Use the bundled Playwright Chromium for this harness. Do not switch it to system Chrome or Edge;
+those browsers no longer support the extension sideload flags that this local QA path needs.
+
+## Run
+
+Run the extension smoke tests headless:
+
+```sh
+npm run qa:extension
+```
+
+Run headed while debugging:
+
+```sh
+npm run qa:extension:headed
+```
+
+The test starts `deckard-browser-bridge` in dev/mock mode on `127.0.0.1:8765`, serves
+`examples/browser-bridge-dapp` on `127.0.0.1:8777`, loads `extension/` unpacked, and verifies:
+
+- the Manifest V3 service worker loads
+- `window.ethereum` is injected into the local test dapp
+- `eth_accounts` returns `[]` before permission
+- `eth_requestAccounts` returns the deterministic dev/mock address
+- `eth_accounts` returns that address after permission
+- `eth_chainId` returns Sepolia (`0xaa36a7`)
+
+If you already have a compatible bridge running on `127.0.0.1:8765`, stop it before running the
+suite. To intentionally reuse it instead, set:
+
+```sh
+DECKARD_QA_REUSE_BRIDGE=1 npm run qa:extension
+```
+
+## Artifacts
+
+Generated artifacts are ignored by git:
+
+- `playwright-report/` — HTML reports
+- `test-results/` — screenshots, traces, and videos
+- `.playwright/` — persistent Chromium profiles
+- `blob-report/` — Playwright blob reports
+
+The passing dapp-connection test writes `connected-dapp.png` under `test-results/extension/...`.
+On failure, Playwright retains traces, screenshots, and videos according to
+`playwright.extension.config.ts`.
+
+## Security
+
+- Never use or commit a real seed phrase, private key, production wallet, browser profile, or
+  mainnet-funded account in this harness.
+- The checked-in test uses only a deterministic mock address:
+  `0xdeC0ded0000000000000000000000000000001193`.
+- The extension has no keys and performs no signing.
+- Keep transaction and signing flows out of this harness until Deckard has reviewed approval UI
+  and local-chain-only signing tests.
+- Do not log extension storage, browser profile contents, cookies, local storage, seeds, keys, or
+  wallet state.
+
+## Scope
+
+This suite proves the browser connector slice. It does not replace Rust unit/integration tests,
+the real daemon proof for `deckard-signerd`, or a future transaction/signature test suite on a
+local chain.
diff --git a/examples/browser-bridge-dapp/index.html b/examples/browser-bridge-dapp/index.html
index 631479a..0786859 100644
--- a/examples/browser-bridge-dapp/index.html
+++ b/examples/browser-bridge-dapp/index.html
@@ -3,6 +3,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="icon" href="data:," />
     <title>Deckard EIP-1193 bridge test dapp</title>
     <style>
       :root { color-scheme: dark; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
diff --git a/package-lock.json b/package-lock.json
new file mode 100644
index 0000000..84294db
--- /dev/null
+++ b/package-lock.json
@@ -0,0 +1,76 @@
+{
+  "name": "deckard",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "deckard",
+      "devDependencies": {
+        "@playwright/test": "^1.61.0"
+      }
+    },
+    "node_modules/@playwright/test": {
+      "version": "1.61.0",
+      "resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.61.0.tgz",
+      "integrity": "sha512-cKA5B6lpFEMyMGjxF54QihfYpB4FkEGH+qZhtArDEG+wezQAJY8Pq6C7T1SjWz+FFzt3TbyoXBQYk/0292TdJA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "playwright": "1.61.0"
+      },
+      "bin": {
+        "playwright": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/fsevents": {
+      "version": "2.3.2",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz",
+      "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
+    "node_modules/playwright": {
+      "version": "1.61.0",
+      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.61.0.tgz",
+      "integrity": "sha512-Z+7BeeqQPRRzklHsVFP4KTGIyMxKUmfeRA4WisM6G3/XW6nwGeX6fX9qYaDa+CiUqpOkb2f6X3nar05R3kSuJQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "playwright-core": "1.61.0"
+      },
+      "bin": {
+        "playwright": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "fsevents": "2.3.2"
+      }
+    },
+    "node_modules/playwright-core": {
+      "version": "1.61.0",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.61.0.tgz",
+      "integrity": "sha512-caX7TrY3Ml6egyDX0WUcTHDxodl/b51y5wJOdCEA36QviK/s2g081hvmGs8eaE3DWb6NYZQ6BjO/QkNRPenoPA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "playwright-core": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    }
+  }
+}
diff --git a/package.json b/package.json
new file mode 100644
index 0000000..e6c5abb
--- /dev/null
+++ b/package.json
@@ -0,0 +1,13 @@
+{
+  "name": "deckard",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "qa:browser:install": "playwright install chromium",
+    "qa:extension": "playwright test --config=playwright.extension.config.ts",
+    "qa:extension:headed": "playwright test --config=playwright.extension.config.ts --headed"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.61.0"
+  }
+}
diff --git a/playwright.extension.config.ts b/playwright.extension.config.ts
new file mode 100644
index 0000000..c5029f1
--- /dev/null
+++ b/playwright.extension.config.ts
@@ -0,0 +1,28 @@
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests/extension',
+  fullyParallel: false,
+  workers: 1,
+  timeout: 30_000,
+  reporter: [
+    ['list'],
+    ['html', { outputFolder: 'playwright-report/extension', open: 'never' }],
+  ],
+  outputDir: 'test-results/extension',
+  use: {
+    baseURL: 'http://127.0.0.1:8777',
+    screenshot: 'only-on-failure',
+    trace: 'retain-on-failure',
+    video: 'retain-on-failure',
+    serviceWorkers: 'allow',
+  },
+  webServer: {
+    command: 'python3 -m http.server 8777 --directory examples/browser-bridge-dapp',
+    url: 'http://127.0.0.1:8777',
+    reuseExistingServer: !process.env.CI,
+    stdout: 'pipe',
+    stderr: 'pipe',
+    timeout: 10_000,
+  },
+});
diff --git a/tests/extension/browser-bridge-extension.spec.ts b/tests/extension/browser-bridge-extension.spec.ts
new file mode 100644
index 0000000..cb6201b
--- /dev/null
+++ b/tests/extension/browser-bridge-extension.spec.ts
@@ -0,0 +1,76 @@
+import { test, expect } from './fixtures';
+
+const mockAccount = '0xdeC0ded0000000000000000000000000000001193';
+
+test('extension service worker loads', async ({ context, extensionId }) => {
+  const worker = context
+    .serviceWorkers()
+    .find((serviceWorker) => serviceWorker.url().startsWith(`chrome-extension://${extensionId}/`));
+
+  expect(extensionId).toMatch(/^[a-p]{32}$/);
+  expect(worker?.url()).toBe(`chrome-extension://${extensionId}/background.js`);
+});
+
+test('local dapp can connect through the injected provider', async ({ page }, testInfo) => {
+  const pageErrors: string[] = [];
+  page.on('pageerror', (error) => pageErrors.push(error.message));
+  page.on('console', (message) => {
+    if (message.type() === 'error') {
+      pageErrors.push(message.text());
+    }
+  });
+
+  await page.goto('/');
+  await expect(page.locator('#output')).toContainText('window.ethereum detected');
+
+  const providerState = await page.evaluate(async () => {
+    const provider = window.ethereum;
+    if (!provider) {
+      throw new Error('window.ethereum missing');
+    }
+    const accountsBefore = await provider.request({ method: 'eth_accounts' });
+    const requestAccounts = await provider.request({ method: 'eth_requestAccounts' });
+    const accountsAfter = await provider.request({ method: 'eth_accounts' });
+    const chainId = await provider.request({ method: 'eth_chainId' });
+    return {
+      accountsBefore,
+      requestAccounts,
+      accountsAfter,
+      chainId,
+      isDeckard: Boolean(provider.isDeckard),
+      selectedAddress: provider.selectedAddress,
+    };
+  });
+
+  expect(providerState).toEqual({
+    accountsBefore: [],
+    requestAccounts: [mockAccount],
+    accountsAfter: [mockAccount],
+    chainId: '0xaa36a7',
+    isDeckard: true,
+    selectedAddress: mockAccount,
+  });
+  expect(pageErrors).toEqual([]);
+
+  await page.evaluate((state) => {
+    const output = document.querySelector('#output');
+    if (output) {
+      output.textContent = JSON.stringify(state, null, 2);
+    }
+  }, providerState);
+
+  await page.screenshot({
+    path: testInfo.outputPath('connected-dapp.png'),
+    fullPage: true,
+  });
+});
+
+declare global {
+  interface Window {
+    ethereum?: {
+      isDeckard?: boolean;
+      selectedAddress?: string | null;
+      request(args: { method: string; params?: unknown[] }): Promise<unknown>;
+    };
+  }
+}
diff --git a/tests/extension/fixtures.ts b/tests/extension/fixtures.ts
new file mode 100644
index 0000000..eb588dd
--- /dev/null
+++ b/tests/extension/fixtures.ts
@@ -0,0 +1,238 @@
+import { test as base, chromium, expect, type BrowserContext, type Page } from '@playwright/test';
+import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const repoRoot = path.resolve(__dirname, '../..');
+const extensionDir = path.join(repoRoot, 'extension');
+const bridgeUrl = 'http://127.0.0.1:8765/rpc';
+const dappOrigin = 'http://127.0.0.1:8777';
+const mockAccount = '0xdeC0ded0000000000000000000000000000001193';
+
+type ExtensionManifest = {
+  action?: { default_popup?: string };
+  browser_action?: { default_popup?: string };
+};
+
+type ExtensionFixtures = {
+  extensionId: string;
+  extensionManifest: ExtensionManifest;
+  openExtensionPage: (extensionPath: string) => Promise<Page>;
+  openPopupPage: () => Promise<Page>;
+};
+
+type WorkerFixtures = {
+  bridgeEndpoint: string;
+};
+
+export const test = base.extend<ExtensionFixtures, WorkerFixtures>({
+  bridgeEndpoint: [
+    async ({}, use) => {
+      const bridge = await ensureBridge();
+      await use(bridgeUrl);
+      await bridge?.stop();
+    },
+    { scope: 'worker', auto: true },
+  ],
+
+  context: async ({ headless }, use, testInfo) => {
+    validateExtension();
+    const userDataDir = path.join(
+      repoRoot,
+      '.playwright',
+      'profiles',
+      `worker-${testInfo.workerIndex}-${Date.now()}`,
+    );
+    fs.mkdirSync(userDataDir, { recursive: true });
+
+    const context = await chromium.launchPersistentContext(userDataDir, {
+      channel: 'chromium',
+      headless,
+      serviceWorkers: 'allow',
+      args: [
+        `--disable-extensions-except=${extensionDir}`,
+        `--load-extension=${extensionDir}`,
+      ],
+    });
+
+    await use(context);
+    await context.close();
+  },
+
+  extensionManifest: async ({}, use) => {
+    const manifest = JSON.parse(
+      fs.readFileSync(path.join(extensionDir, 'manifest.json'), 'utf8'),
+    ) as ExtensionManifest;
+    await use(manifest);
+  },
+
+  extensionId: async ({ context }, use) => {
+    const serviceWorker = await extensionServiceWorker(context);
+    const extensionId = serviceWorker.url().split('/')[2];
+    expect(extensionId).toBeTruthy();
+    await use(extensionId);
+  },
+
+  openExtensionPage: async ({ context, extensionId }, use) => {
+    await use(async (extensionPath: string) => {
+      const normalizedPath = extensionPath.replace(/^\/+/, '');
+      const page = await context.newPage();
+      await page.goto(`chrome-extension://${extensionId}/${normalizedPath}`);
+      return page;
+    });
+  },
+
+  openPopupPage: async ({ extensionManifest, openExtensionPage }, use) => {
+    await use(async () => {
+      const popupPath =
+        extensionManifest.action?.default_popup ??
+        extensionManifest.browser_action?.default_popup;
+      if (!popupPath) {
+        throw new Error('Deckard extension manifest does not define a popup page');
+      }
+      return openExtensionPage(popupPath);
+    });
+  },
+});
+
+export { expect };
+
+async function extensionServiceWorker(context: BrowserContext) {
+  const existing = context
+    .serviceWorkers()
+    .find((worker) => worker.url().startsWith('chrome-extension://'));
+  if (existing) {
+    return existing;
+  }
+  return context.waitForEvent('serviceworker', {
+    predicate: (worker) => worker.url().startsWith('chrome-extension://'),
+    timeout: 10_000,
+  });
+}
+
+function validateExtension() {
+  const manifestPath = path.join(extensionDir, 'manifest.json');
+  for (const required of [manifestPath, path.join(extensionDir, 'background.js')]) {
+    if (!fs.existsSync(required)) {
+      throw new Error(`missing extension file: ${required}`);
+    }
+  }
+}
+
+type BridgeHandle = {
+  stop: () => Promise<void>;
+};
+
+async function ensureBridge(): Promise<BridgeHandle | undefined> {
+  if (await bridgeReady()) {
+    if (process.env.DECKARD_QA_REUSE_BRIDGE === '1') {
+      return undefined;
+    }
+    throw new Error(
+      'Deckard browser bridge is already listening on 127.0.0.1:8765; stop it or set DECKARD_QA_REUSE_BRIDGE=1',
+    );
+  }
+
+  const child = spawn(
+    'cargo',
+    [
+      'run',
+      '--quiet',
+      '--locked',
+      '-p',
+      'deckard-browser-bridge',
+      '--no-default-features',
+      '--',
+      '--bind',
+      '127.0.0.1:8765',
+      '--dev-mock-account',
+      mockAccount,
+    ],
+    {
+      cwd: repoRoot,
+      env: {
+        ...process.env,
+        DECKARD_CHAIN_ID: '11155111',
+      },
+    },
+  );
+
+  const logs: string[] = [];
+  collectBridgeLogs(child, logs);
+  await waitForBridge(child, logs);
+
+  return {
+    stop: () => stopBridge(child),
+  };
+}
+
+function collectBridgeLogs(child: ChildProcessWithoutNullStreams, logs: string[]) {
+  const collect = (chunk: Buffer) => {
+    logs.push(chunk.toString());
+    if (logs.length > 30) {
+      logs.shift();
+    }
+  };
+  child.stdout.on('data', collect);
+  child.stderr.on('data', collect);
+}
+
+async function waitForBridge(child: ChildProcessWithoutNullStreams, logs: string[]) {
+  const deadline = Date.now() + 30_000;
+  while (Date.now() < deadline) {
+    if (child.exitCode !== null) {
+      throw new Error(`Deckard browser bridge exited early:\n${logs.join('')}`);
+    }
+    if (await bridgeReady()) {
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+  throw new Error(`Deckard browser bridge did not become ready:\n${logs.join('')}`);
+}
+
+async function bridgeReady() {
+  try {
+    const response = await fetch(bridgeUrl, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'x-deckard-origin': dappOrigin,
+      },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'eth_chainId',
+        params: [],
+      }),
+      signal: AbortSignal.timeout(1_000),
+    });
+    if (!response.ok) {
+      return false;
+    }
+    const payload = await response.json();
+    return payload.result === '0xaa36a7';
+  } catch {
+    return false;
+  }
+}
+
+async function stopBridge(child: ChildProcessWithoutNullStreams) {
+  if (child.exitCode !== null) {
+    return;
+  }
+  child.kill('SIGTERM');
+  await new Promise<void>((resolve) => {
+    const timeout = setTimeout(() => {
+      child.kill('SIGKILL');
+      resolve();
+    }, 2_000);
+    child.once('exit', () => {
+      clearTimeout(timeout);
+      resolve();
+    });
+  });
+}