local-browser-bridge 0.1.0

package/dist/tests/browser-attach-ux-helper.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/browser-attach-ux-helper.test.js

@@ -0,0 +1,139 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_test_1 = __importDefault(require("node:test"));
+const browser_attach_ux_helper_1 = require("../src/browser-attach-ux-helper");
+(0, node_test_1.default)("interpretBrowserAttachUxFromDiagnostics maps chrome relay readiness into a shared-tab-scoped blocked state", () => {
+    const interpretation = (0, browser_attach_ux_helper_1.interpretBrowserAttachUxFromDiagnostics)({
+        browser: "chrome",
+        attachMode: "relay",
+        diagnostics: {
+            browser: "chrome",
+            checkedAt: "2026-03-30T12:00:00.000Z",
+            runtime: {
+                platform: "darwin",
+                arch: "arm64",
+                nodeVersion: "v25.8.0",
+                safariRunning: false
+            },
+            host: {
+                osascriptAvailable: true,
+                screencaptureAvailable: true,
+                safariApplicationAvailable: true
+            },
+            supportedFeatures: {
+                inspectTabs: true,
+                attach: true,
+                activate: false,
+                navigate: false,
+                screenshot: false,
+                savedSessions: true,
+                cli: true,
+                httpApi: true
+            },
+            constraints: [],
+            attach: {
+                direct: {
+                    mode: "direct",
+                    source: "user-browser",
+                    scope: "browser",
+                    supported: true,
+                    ready: true,
+                    state: "ready",
+                    blockers: []
+                },
+                relay: {
+                    mode: "relay",
+                    source: "extension-relay",
+                    scope: "tab",
+                    supported: true,
+                    ready: false,
+                    state: "attention-required",
+                    blockers: [{ code: "relay_share_required", message: "share the tab first" }]
+                }
+            }
+        }
+    });
+    strict_1.default.deepEqual(interpretation, {
+        state: "blocked",
+        browser: "chrome",
+        attachMode: "relay",
+        operation: "attach",
+        label: "Chrome (shared tab, read-only)",
+        readOnly: true,
+        sharedTabScoped: true,
+        readiness: "attention-required",
+        prompt: "Chrome relay only works for a tab you explicitly share. Share the tab first, then retry.",
+        scopeNote: "Scope note: Chrome relay is still limited to the currently shared tab and remains read-only.",
+        retryGuidance: undefined,
+        retryable: undefined,
+        userActionRequired: undefined,
+        relayFailureCategory: undefined
+    });
+});
+(0, node_test_1.default)("interpretBrowserAttachUxFromSession preserves shared-tab resume honesty", () => {
+    const interpretation = (0, browser_attach_ux_helper_1.interpretBrowserAttachUxFromSession)({
+        operation: "resumeSession",
+        session: {
+            browser: "chrome",
+            kind: "chrome-readonly",
+            attach: {
+                mode: "relay",
+                source: "extension-relay",
+                scope: "tab",
+                resumable: false,
+                resumeRequiresUserGesture: true
+            },
+            semantics: {
+                inspect: "shared-tab-only",
+                list: "saved-session",
+                resume: "current-shared-tab",
+                tabReference: {
+                    windowIndex: "synthetic-shared-tab-position",
+                    tabIndex: "synthetic-shared-tab-position"
+                }
+            },
+            status: { state: "read-only", canAct: false }
+        }
+    });
+    strict_1.default.equal(interpretation.state, "resumed");
+    strict_1.default.equal(interpretation.label, "Chrome (shared tab, read-only)");
+    strict_1.default.equal(interpretation.readOnly, true);
+    strict_1.default.equal(interpretation.sharedTabScoped, true);
+    strict_1.default.equal(interpretation.prompt, "That shared-tab grant is no longer active. Click the relay extension again on the original tab, then retry resume.");
+    strict_1.default.equal(interpretation.scopeNote, "Scope note: Chrome relay is still limited to the currently shared tab and remains read-only.");
+});
+(0, node_test_1.default)("interpretBrowserAttachUxFromError reuses structured relay failure interpretation", () => {
+    const interpretation = (0, browser_attach_ux_helper_1.interpretBrowserAttachUxFromError)({
+        details: {
+            context: { browser: "chrome", attachMode: "relay", operation: "resumeSession" },
+            relay: {
+                branch: "use-current-shared-tab",
+                retryable: true,
+                userActionRequired: true,
+                phase: "shared-tab-match",
+                sharedTabScope: "current-shared-tab",
+                currentSharedTabMatches: false
+            }
+        }
+    });
+    strict_1.default.deepEqual(interpretation, {
+        state: "user-action-required",
+        browser: "chrome",
+        attachMode: "relay",
+        operation: "resumeSession",
+        label: "Chrome (shared tab, read-only)",
+        readOnly: true,
+        sharedTabScoped: true,
+        readiness: undefined,
+        prompt: "Chrome relay attach only works for the tab that is currently shared. Use the shared tab or share a different tab first.",
+        scopeNote: "Scope note: Chrome relay is still limited to the currently shared tab and remains read-only.",
+        retryGuidance: "Retry guidance: Wait for the user action to complete, then retry the same relay path.",
+        retryable: true,
+        userActionRequired: true,
+        relayFailureCategory: "shared-tab-read-only-scope-limitation"
+    });
+});

package/dist/tests/chrome-relay-error-helper.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/chrome-relay-error-helper.test.js

@@ -0,0 +1,67 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_test_1 = __importDefault(require("node:test"));
+const chrome_relay_error_helper_1 = require("../src/chrome-relay-error-helper");
+(0, node_test_1.default)("interpretChromeRelayFailure maps stable consumer categories without implying browser-wide access", () => {
+    const sharedTabScopeFailure = (0, chrome_relay_error_helper_1.interpretChromeRelayFailure)({
+        relay: {
+            branch: "use-current-shared-tab",
+            retryable: true,
+            userActionRequired: true,
+            phase: "target-selection",
+            sharedTabScope: "current-shared-tab",
+            currentSharedTabMatches: false
+        }
+    });
+    strict_1.default.deepEqual(sharedTabScopeFailure, {
+        category: "shared-tab-read-only-scope-limitation",
+        retryable: true,
+        userActionRequired: true,
+        branch: "use-current-shared-tab",
+        sharedTabScope: "current-shared-tab",
+        scopeLimitedToCurrentSharedTab: true,
+        readOnly: true
+    });
+    const shareRequired = (0, chrome_relay_error_helper_1.interpretChromeRelayFailure)({
+        relay: {
+            branch: "share-original-tab-again",
+            retryable: true,
+            userActionRequired: true,
+            phase: "session-precondition",
+            sharedTabScope: "current-shared-tab"
+        }
+    });
+    strict_1.default.equal(shareRequired?.category, "share-required");
+    strict_1.default.equal((0, chrome_relay_error_helper_1.chromeRelayBranchPrompt)(shareRequired?.branch), "That shared-tab grant is no longer active. Click the relay extension again on the original tab, then retry resume.");
+    strict_1.default.equal((0, chrome_relay_error_helper_1.chromeRelayRetryGuidance)(shareRequired), "Retry guidance: Wait for the user action to complete, then retry the same relay path.");
+    strict_1.default.equal((0, chrome_relay_error_helper_1.chromeRelayScopeNote)(shareRequired), "Scope note: Chrome relay is still limited to the currently shared tab and remains read-only.");
+});
+(0, node_test_1.default)("interpretChromeRelayFailure returns retryability fallbacks and handles missing relay details", () => {
+    strict_1.default.equal((0, chrome_relay_error_helper_1.interpretChromeRelayFailure)(undefined), undefined);
+    const retryable = (0, chrome_relay_error_helper_1.interpretChromeRelayFailure)({
+        relay: {
+            branch: "unsupported",
+            retryable: true,
+            userActionRequired: false,
+            phase: "diagnostics",
+            sharedTabScope: "current-shared-tab"
+        }
+    });
+    strict_1.default.equal(retryable?.category, "retryable-relay-failure");
+    strict_1.default.equal((0, chrome_relay_error_helper_1.chromeRelayRetryGuidance)(retryable), "Retry guidance: A targeted retry on the same relay path is reasonable.");
+    const nonRetryable = (0, chrome_relay_error_helper_1.interpretChromeRelayFailure)({
+        relay: {
+            branch: "repair-relay-probe",
+            retryable: false,
+            userActionRequired: false,
+            phase: "diagnostics",
+            sharedTabScope: "current-shared-tab"
+        }
+    });
+    strict_1.default.equal(nonRetryable?.category, "non-retryable-relay-failure");
+    strict_1.default.equal((0, chrome_relay_error_helper_1.chromeRelayRetryGuidance)(nonRetryable), "Retry guidance: Stop automatic retries and surface the relay failure directly.");
+});

package/dist/tests/chrome-relay-helper.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/chrome-relay-helper.test.js

@@ -0,0 +1,142 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const strict_1 = __importDefault(require("node:assert/strict"));
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const node_test_1 = __importDefault(require("node:test"));
+const chrome_relay_state_1 = require("../src/chrome-relay-state");
+const chrome_relay_helper_1 = require("../src/chrome-relay-helper");
+const chrome_relay_helper_cli_1 = require("../src/chrome-relay-helper-cli");
+async function withCapturedStreams(run) {
+    let stdout = "";
+    let stderr = "";
+    const stdoutWrite = process.stdout.write.bind(process.stdout);
+    const stderrWrite = process.stderr.write.bind(process.stderr);
+    process.stdout.write = ((chunk) => {
+        stdout += typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+        return true;
+    });
+    process.stderr.write = ((chunk) => {
+        stderr += typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+        return true;
+    });
+    try {
+        await run();
+        return { stdout, stderr };
+    }
+    finally {
+        process.stdout.write = stdoutWrite;
+        process.stderr.write = stderrWrite;
+    }
+}
+(0, node_test_1.default)("chrome relay helper fixture flows validate and preserve truthful relay semantics", () => {
+    const flows = [
+        "extension-missing",
+        "disconnected",
+        "click-required",
+        "share-required",
+        "shared-tab",
+        "expired-share",
+        "clear-shared-tab"
+    ];
+    for (const flow of flows) {
+        const state = (0, chrome_relay_helper_1.buildChromeRelayFixtureState)({ flow });
+        const validation = (0, chrome_relay_state_1.validateChromeRelayState)(state);
+        strict_1.default.equal(validation.ok, true, flow);
+        strict_1.default.equal(validation.probe?.version, state.version, flow);
+        strict_1.default.equal(validation.probe?.updatedAt, state.updatedAt, flow);
+    }
+    const sharedTab = (0, chrome_relay_helper_1.buildChromeRelayFixtureState)({ flow: "shared-tab" });
+    strict_1.default.equal(sharedTab.connected, true);
+    strict_1.default.equal(sharedTab.shareRequired, false);
+    strict_1.default.ok(sharedTab.sharedTab?.id);
+    strict_1.default.ok(sharedTab.expiresAt);
+    const expiredShare = (0, chrome_relay_helper_1.buildChromeRelayFixtureState)({ flow: "expired-share" });
+    strict_1.default.ok(expiredShare.sharedTab?.id);
+    strict_1.default.ok(expiredShare.expiresAt);
+    strict_1.default.equal(Date.parse(expiredShare.expiresAt ?? ""), Date.parse(expiredShare.expiresAt ?? ""));
+    strict_1.default.ok(Date.parse(expiredShare.expiresAt ?? "") <= Date.now());
+    strict_1.default.equal(expiredShare.resumable, false);
+    strict_1.default.equal(expiredShare.resumeRequiresUserGesture, true);
+    const cleared = (0, chrome_relay_helper_1.buildChromeRelayFixtureState)({ flow: "clear-shared-tab" });
+    strict_1.default.equal(cleared.connected, true);
+    strict_1.default.equal(cleared.sharedTab, null);
+});
+(0, node_test_1.default)("chrome relay helper writes full snapshots to the configured path and overwrites atomically", async () => {
+    const baseDir = (0, node_path_1.resolve)(process.cwd(), ".tmp-tests", "relay-helper-write");
+    await (0, promises_1.rm)(baseDir, { recursive: true, force: true });
+    await (0, promises_1.mkdir)(baseDir, { recursive: true });
+    const outputPath = (0, node_path_1.resolve)(baseDir, "chrome-relay-state.json");
+    await (0, promises_1.writeFile)(outputPath, '{"stale":true}', "utf8");
+    const first = await (0, chrome_relay_helper_1.writeChromeRelayFixtureState)({
+        flow: "shared-tab",
+        outputPath,
+        tabId: "relay-1",
+        url: "https://example.com/one",
+        title: "One"
+    });
+    const second = await (0, chrome_relay_helper_1.writeChromeRelayFixtureState)({
+        flow: "clear-shared-tab",
+        outputPath
+    });
+    strict_1.default.equal(first.path, outputPath);
+    strict_1.default.equal(second.path, outputPath);
+    const persisted = JSON.parse(await (0, promises_1.readFile)(outputPath, "utf8"));
+    strict_1.default.equal(persisted.sharedTab, null);
+    const dirEntries = await (0, promises_1.readdir)(baseDir);
+    strict_1.default.deepEqual(dirEntries.sort(), ["chrome-relay-state.json"]);
+});
+(0, node_test_1.default)("chrome relay helper CLI writes a documented flow and emits the final snapshot", async () => {
+    const baseDir = (0, node_path_1.resolve)(process.cwd(), ".tmp-tests", "relay-helper-cli");
+    await (0, promises_1.rm)(baseDir, { recursive: true, force: true });
+    await (0, promises_1.mkdir)(baseDir, { recursive: true });
+    const outputPath = (0, node_path_1.resolve)(baseDir, "chrome-relay-state.json");
+    const captured = await withCapturedStreams(async () => {
+        await (0, chrome_relay_helper_cli_1.runChromeRelayHelperCli)([
+            "shared-tab",
+            "--output",
+            outputPath,
+            "--tab-id",
+            "relay-42",
+            "--title",
+            "Shared Docs",
+            "--url",
+            "https://example.com/docs",
+            "--resumable",
+            "true",
+            "--resume-requires-user-gesture",
+            "false"
+        ]);
+    });
+    strict_1.default.equal(captured.stderr, "");
+    const payload = JSON.parse(captured.stdout);
+    strict_1.default.equal(payload.ok, true);
+    strict_1.default.equal(payload.flow, "shared-tab");
+    strict_1.default.equal(payload.path, outputPath);
+    strict_1.default.equal(payload.state.sharedTab?.id, "relay-42");
+    strict_1.default.equal(payload.state.sharedTab?.title, "Shared Docs");
+    strict_1.default.equal(payload.state.sharedTab?.url, "https://example.com/docs");
+    const persisted = JSON.parse(await (0, promises_1.readFile)(outputPath, "utf8"));
+    strict_1.default.equal(persisted.sharedTab?.url, "https://example.com/docs");
+});
+(0, node_test_1.default)("chrome relay helper output path resolution honors explicit path then env then conventional default", () => {
+    const explicit = (0, node_path_1.resolve)(process.cwd(), ".tmp-tests", "explicit.json");
+    strict_1.default.equal((0, chrome_relay_helper_1.resolveChromeRelayStateOutputPath)(explicit), explicit);
+    const previous = process.env[chrome_relay_helper_1.CHROME_RELAY_STATE_PATH_ENV];
+    process.env[chrome_relay_helper_1.CHROME_RELAY_STATE_PATH_ENV] = (0, node_path_1.resolve)(process.cwd(), ".tmp-tests", "env.json");
+    try {
+        strict_1.default.equal((0, chrome_relay_helper_1.resolveChromeRelayStateOutputPath)(), (0, node_path_1.resolve)(process.cwd(), ".tmp-tests", "env.json"));
+    }
+    finally {
+        if (previous === undefined) {
+            delete process.env[chrome_relay_helper_1.CHROME_RELAY_STATE_PATH_ENV];
+        }
+        else {
+            process.env[chrome_relay_helper_1.CHROME_RELAY_STATE_PATH_ENV] = previous;
+        }
+    }
+    strict_1.default.match((0, chrome_relay_helper_1.resolveChromeRelayStateOutputPath)(), /\.local-browser-bridge\/chrome-relay-state\.json$/);
+});

package/dist/tests/chrome-relay-state-schema.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/chrome-relay-state-schema.test.js

@@ -0,0 +1,96 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const promises_1 = require("node:fs/promises");
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_test_1 = __importDefault(require("node:test"));
+const node_path_1 = require("node:path");
+const chrome_relay_state_1 = require("../src/chrome-relay-state");
+async function readJson(path) {
+    return JSON.parse(await (0, promises_1.readFile)(path, "utf8"));
+}
+(0, node_test_1.default)("chrome relay schema artifact stays present and documented", async () => {
+    const root = process.cwd();
+    const schema = await readJson((0, node_path_1.resolve)(root, "schema", "chrome-relay-state.schema.json"));
+    const producerDoc = await (0, promises_1.readFile)((0, node_path_1.resolve)(root, "docs", "chrome-relay-producer-contract.md"), "utf8");
+    const readme = await (0, promises_1.readFile)((0, node_path_1.resolve)(root, "README.md"), "utf8");
+    strict_1.default.match(schema.$schema, /json-schema.org/);
+    strict_1.default.match(schema.$id, /chrome-relay-state\.schema\.json$/);
+    strict_1.default.equal(schema.title, "Local Browser Bridge Chrome Relay State");
+    strict_1.default.ok(schema.properties.sharedTab);
+    strict_1.default.match(producerDoc, /schema\/chrome-relay-state\.schema\.json/);
+    strict_1.default.match(readme, /schema\/chrome-relay-state\.schema\.json/);
+});
+(0, node_test_1.default)("chrome relay example fixture validates as a ready shared-tab probe", async () => {
+    const root = process.cwd();
+    const example = await readJson((0, node_path_1.resolve)(root, "examples", "chrome-relay-state.example.json"));
+    const result = (0, chrome_relay_state_1.validateChromeRelayState)(example);
+    strict_1.default.equal(result.ok, true);
+    strict_1.default.equal(result.probe?.version, "1.1.0");
+    strict_1.default.equal(result.probe?.connected, true);
+    strict_1.default.equal(result.probe?.sharedTab?.id, "tab-123");
+    strict_1.default.equal(result.probe?.sharedTab?.url, "https://example.com/shared");
+});
+(0, node_test_1.default)("chrome relay validation rejects malformed or contradictory producer payloads", () => {
+    const cases = [
+        {
+            name: "shared tab must carry at least one identity field",
+            payload: { extensionInstalled: true, connected: true, sharedTab: {} },
+            expected: /sharedTab must include at least one of id, url, or title/
+        },
+        {
+            name: "gesture required cannot also expose a shared tab",
+            payload: {
+                extensionInstalled: true,
+                connected: true,
+                userGestureRequired: true,
+                sharedTab: { id: "tab-1" }
+            },
+            expected: /userGestureRequired=true cannot be combined with sharedTab/
+        },
+        {
+            name: "share required cannot also expose a shared tab",
+            payload: {
+                extensionInstalled: true,
+                connected: true,
+                shareRequired: true,
+                sharedTab: { url: "https://example.com" }
+            },
+            expected: /shareRequired=true cannot be combined with sharedTab/
+        },
+        {
+            name: "missing extension cannot report connected",
+            payload: {
+                extensionInstalled: false,
+                connected: true
+            },
+            expected: /extensionInstalled=false cannot be combined with connected=true/
+        },
+        {
+            name: "timestamps must be parseable",
+            payload: {
+                extensionInstalled: true,
+                connected: true,
+                updatedAt: "not-a-date",
+                sharedTab: { id: "tab-1" }
+            },
+            expected: /updatedAt must be an ISO 8601 timestamp/
+        },
+        {
+            name: "sharedTab must be object or null",
+            payload: {
+                extensionInstalled: true,
+                connected: true,
+                sharedTab: "tab-1"
+            },
+            expected: /sharedTab must be an object or null/
+        }
+    ];
+    for (const testCase of cases) {
+        const result = (0, chrome_relay_state_1.validateChromeRelayState)(testCase.payload);
+        strict_1.default.equal(result.ok, false, testCase.name);
+        strict_1.default.match(result.errors.join(" | "), testCase.expected, testCase.name);
+    }
+});

package/dist/tests/claude-code-wrapper.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/claude-code-wrapper.test.js

@@ -0,0 +1,170 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_test_1 = __importDefault(require("node:test"));
+const src_1 = require("../src");
+function createSharedTabSession() {
+    return {
+        id: "sess-relay",
+        schemaVersion: 1,
+        browser: "chrome",
+        kind: "chrome-readonly",
+        target: { type: "front" },
+        tab: {
+            browser: "chrome",
+            windowIndex: 1,
+            tabIndex: 1,
+            title: "Shared tab",
+            url: "https://example.com",
+            attachedAt: "2026-03-30T12:00:00.000Z",
+            identity: {
+                signature: "sig",
+                urlKey: "https://example.com",
+                titleKey: "Shared tab",
+                origin: "https://example.com",
+                pathname: "/"
+            }
+        },
+        frontTab: {
+            browser: "chrome",
+            windowIndex: 1,
+            tabIndex: 1,
+            title: "Shared tab",
+            url: "https://example.com",
+            attachedAt: "2026-03-30T12:00:00.000Z",
+            identity: {
+                signature: "sig",
+                urlKey: "https://example.com",
+                titleKey: "Shared tab",
+                origin: "https://example.com",
+                pathname: "/"
+            }
+        },
+        attach: {
+            mode: "relay",
+            source: "extension-relay",
+            scope: "tab",
+            resumable: false,
+            resumeRequiresUserGesture: true
+        },
+        semantics: {
+            inspect: "shared-tab-only",
+            list: "saved-session",
+            resume: "current-shared-tab",
+            tabReference: {
+                windowIndex: "synthetic-shared-tab-position",
+                tabIndex: "synthetic-shared-tab-position"
+            }
+        },
+        capabilities: { resume: true, activate: false, navigate: false, screenshot: false },
+        status: { state: "read-only", canAct: false },
+        createdAt: "2026-03-30T12:00:00.000Z"
+    };
+}
+(0, node_test_1.default)("normalizeClaudeCodeRoute maps named Claude Code routes onto the shared bridge route contract", () => {
+    strict_1.default.deepEqual((0, src_1.normalizeClaudeCodeRoute)({ route: "safari" }), {
+        browser: "safari",
+        attachMode: "direct"
+    });
+    strict_1.default.deepEqual((0, src_1.normalizeClaudeCodeRoute)({ route: "chrome-direct" }), {
+        browser: "chrome",
+        attachMode: "direct"
+    });
+    strict_1.default.deepEqual((0, src_1.normalizeClaudeCodeRoute)({ route: "chrome-relay", sessionId: "sess-relay" }), {
+        browser: "chrome",
+        attachMode: "relay",
+        sessionId: "sess-relay"
+    });
+});
+(0, node_test_1.default)("prepareClaudeCodeRoute returns a prompt and skips attach when the selected route is blocked", async () => {
+    const calls = [];
+    const adapter = (0, src_1.createBridgeAdapter)({
+        async getCapabilities() {
+            calls.push("capabilities");
+            return { schemaVersion: 1 };
+        },
+        async getDiagnostics(browser) {
+            calls.push(`diagnostics:${browser}`);
+            return {
+                browser,
+                checkedAt: "2026-03-30T12:00:00.000Z",
+                runtime: { platform: "darwin", arch: "arm64", nodeVersion: "v25.8.0" },
+                host: {},
+                supportedFeatures: {},
+                constraints: [],
+                attach: {
+                    direct: {
+                        mode: "direct",
+                        ready: false,
+                        state: "unavailable",
+                        blockers: [
+                            {
+                                code: "direct_unavailable_attach_endpoint_missing",
+                                message: "missing local DevTools endpoint"
+                            }
+                        ]
+                    },
+                    relay: { mode: "relay", ready: true, state: "ready", blockers: [] }
+                }
+            };
+        },
+        async attach() {
+            calls.push("attach");
+            throw new Error("attach should not run");
+        },
+        async resume() {
+            calls.push("resume");
+            throw new Error("resume should not run");
+        }
+    });
+    const prepared = await (0, src_1.prepareClaudeCodeRoute)(adapter, { route: "chrome-direct" });
+    strict_1.default.equal(prepared.blocked, true);
+    strict_1.default.equal(prepared.routeUx.state, "blocked");
+    strict_1.default.match(prepared.prompt ?? "", /Chrome direct attach needs a local DevTools endpoint/i);
+    strict_1.default.equal(prepared.connection, undefined);
+    strict_1.default.deepEqual(calls, ["capabilities", "diagnostics:chrome"]);
+});
+(0, node_test_1.default)("prepareClaudeCodeRoute returns a connected shared-tool result for the Claude Code relay path", async () => {
+    const calls = [];
+    const adapter = (0, src_1.createBridgeAdapter)({
+        async getCapabilities() {
+            calls.push("capabilities");
+            return { schemaVersion: 1, product: { name: "local-browser-bridge" } };
+        },
+        async getDiagnostics(browser) {
+            calls.push(`diagnostics:${browser}`);
+            return {
+                browser,
+                checkedAt: "2026-03-30T12:00:00.000Z",
+                runtime: { platform: "darwin", arch: "arm64", nodeVersion: "v25.8.0" },
+                host: {},
+                supportedFeatures: {},
+                constraints: [],
+                attach: {
+                    direct: { mode: "direct", ready: false, state: "unavailable", blockers: [] },
+                    relay: { mode: "relay", ready: true, state: "ready", blockers: [] }
+                }
+            };
+        },
+        async attach(route) {
+            calls.push(`attach:${route.browser}:${route.attachMode}`);
+            return {
+                session: createSharedTabSession()
+            };
+        },
+        async resume() {
+            calls.push("resume");
+            throw new Error("resume should not run");
+        }
+    });
+    const prepared = await (0, src_1.prepareClaudeCodeRoute)(adapter, { route: "chrome-relay" });
+    strict_1.default.equal(prepared.blocked, false);
+    strict_1.default.equal(prepared.connection?.operation, "attach");
+    strict_1.default.equal(prepared.connection?.routeUx.label, "Chrome (shared tab, read-only)");
+    strict_1.default.equal(prepared.connection?.sessionUx.sharedTabScoped, true);
+    strict_1.default.match(prepared.prompt ?? "", /shared-tab grant is no longer active/i);
+    strict_1.default.deepEqual(calls, ["capabilities", "diagnostics:chrome", "attach:chrome:relay"]);
+});

package/dist/tests/codex.test.d.ts

@@ -0,0 +1 @@
+export {};