local-browser-bridge 0.1.0

package/dist/tests/docs-fixtures.test.js

@@ -0,0 +1,255 @@
+"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");
+async function readJson(path) {
+    return JSON.parse(await (0, promises_1.readFile)(path, "utf8"));
+}
+(0, node_test_1.default)("documentation fixtures preserve the stable contract examples", async () => {
+    const root = process.cwd();
+    const capabilities = await readJson((0, node_path_1.resolve)(root, "examples", "capabilities.example.json"));
+    strict_1.default.equal(capabilities.capabilities.schemaVersion, 1);
+    strict_1.default.equal(capabilities.capabilities.product.summary, "Reusable, agent-agnostic local browser bridge with honest capability signaling. Safari is actionable; Chrome/Chromium is read-only in v1.");
+    const safari = capabilities.capabilities.browsers.find((browser) => browser.browser === "safari");
+    const chrome = capabilities.capabilities.browsers.find((browser) => browser.browser === "chrome");
+    strict_1.default.ok(safari);
+    strict_1.default.ok(chrome);
+    strict_1.default.equal(safari.kind, "safari-actionable");
+    strict_1.default.equal(safari.attachModes?.[0]?.mode, "direct");
+    strict_1.default.equal(safari.attachModes?.[0]?.source, "user-browser");
+    strict_1.default.equal(safari.attachModes?.[0]?.scope, "browser");
+    strict_1.default.equal(safari.operations.resumeSession, true);
+    strict_1.default.equal(safari.operations.activate, true);
+    strict_1.default.equal(safari.operations.navigate, true);
+    strict_1.default.equal(safari.operations.screenshot, true);
+    strict_1.default.equal(chrome.kind, "chrome-readonly");
+    strict_1.default.match(chrome.bridge.implementation, /read-only in v1/i);
+    strict_1.default.equal(chrome.attachModes?.[0]?.mode, "direct");
+    strict_1.default.equal(chrome.attachModes?.[1]?.mode, "relay");
+    strict_1.default.equal(chrome.attachModes?.[1]?.scope, "tab");
+    strict_1.default.equal(chrome.operations.resumeSession, true);
+    strict_1.default.equal(chrome.operations.activate, false);
+    strict_1.default.equal(chrome.operations.navigate, false);
+    strict_1.default.equal(chrome.operations.screenshot, false);
+    const safariSession = await readJson((0, node_path_1.resolve)(root, "examples", "session.safari-actionable.example.json"));
+    strict_1.default.equal(safariSession.session.schemaVersion, 1);
+    strict_1.default.equal(safariSession.session.kind, "safari-actionable");
+    strict_1.default.equal(safariSession.session.attach.mode, "direct");
+    strict_1.default.equal(safariSession.session.attach.scope, "browser");
+    strict_1.default.equal(safariSession.session.semantics.inspect, "browser-tabs");
+    strict_1.default.equal(safariSession.session.semantics.resume, "saved-browser-target");
+    strict_1.default.equal(safariSession.session.semantics.tabReference.windowIndex, "browser-position");
+    strict_1.default.equal(safariSession.session.status.state, "actionable");
+    strict_1.default.equal(safariSession.session.status.canAct, true);
+    strict_1.default.equal(safariSession.session.capabilities.resume, true);
+    strict_1.default.equal(safariSession.session.capabilities.activate, true);
+    strict_1.default.equal(safariSession.session.capabilities.navigate, true);
+    strict_1.default.equal(safariSession.session.capabilities.screenshot, true);
+    const chromeSession = await readJson((0, node_path_1.resolve)(root, "examples", "session.chrome-readonly.example.json"));
+    strict_1.default.equal(chromeSession.session.schemaVersion, 1);
+    strict_1.default.equal(chromeSession.session.kind, "chrome-readonly");
+    strict_1.default.equal(chromeSession.session.attach.mode, "direct");
+    strict_1.default.equal(chromeSession.session.attach.source, "user-browser");
+    strict_1.default.equal(chromeSession.session.semantics.inspect, "browser-tabs");
+    strict_1.default.equal(chromeSession.session.semantics.resume, "saved-browser-target");
+    strict_1.default.equal(chromeSession.session.semantics.tabReference.tabIndex, "browser-position");
+    strict_1.default.equal(chromeSession.session.status.state, "read-only");
+    strict_1.default.equal(chromeSession.session.status.canAct, false);
+    strict_1.default.equal(chromeSession.session.capabilities.resume, true);
+    strict_1.default.equal(chromeSession.session.capabilities.activate, false);
+    strict_1.default.equal(chromeSession.session.capabilities.navigate, false);
+    strict_1.default.equal(chromeSession.session.capabilities.screenshot, false);
+    const chromeRelaySession = await readJson((0, node_path_1.resolve)(root, "examples", "session.chrome-relay-readonly.example.json"));
+    strict_1.default.equal(chromeRelaySession.session.schemaVersion, 1);
+    strict_1.default.equal(chromeRelaySession.session.kind, "chrome-readonly");
+    strict_1.default.equal(chromeRelaySession.session.attach.mode, "relay");
+    strict_1.default.equal(chromeRelaySession.session.attach.source, "extension-relay");
+    strict_1.default.equal(chromeRelaySession.session.attach.scope, "tab");
+    strict_1.default.equal(chromeRelaySession.session.attach.resumeRequiresUserGesture, true);
+    strict_1.default.equal(chromeRelaySession.session.semantics.inspect, "shared-tab-only");
+    strict_1.default.equal(chromeRelaySession.session.semantics.resume, "current-shared-tab");
+    strict_1.default.equal(chromeRelaySession.session.semantics.tabReference.windowIndex, "synthetic-shared-tab-position");
+    strict_1.default.match(chromeRelaySession.session.semantics.notes?.[0] ?? "", /last tab explicitly shared/i);
+    strict_1.default.equal(chromeRelaySession.session.status.state, "read-only");
+    strict_1.default.equal(chromeRelaySession.session.status.canAct, false);
+    strict_1.default.equal(chromeRelaySession.session.capabilities.resume, true);
+    strict_1.default.equal(chromeRelaySession.session.capabilities.activate, false);
+    strict_1.default.equal(chromeRelaySession.session.capabilities.navigate, false);
+    strict_1.default.equal(chromeRelaySession.session.capabilities.screenshot, false);
+    const chromeRelayError = await readJson((0, node_path_1.resolve)(root, "examples", "error.chrome-relay-share-required.example.json"));
+    strict_1.default.equal(chromeRelayError.error.code, "relay_share_required");
+    strict_1.default.equal(chromeRelayError.error.statusCode, 503);
+    strict_1.default.equal(chromeRelayError.error.details.context.browser, "chrome");
+    strict_1.default.equal(chromeRelayError.error.details.context.attachMode, "relay");
+    strict_1.default.equal(chromeRelayError.error.details.context.operation, "attach");
+    strict_1.default.equal(chromeRelayError.error.details.relay.branch, "share-tab");
+    strict_1.default.equal(chromeRelayError.error.details.relay.retryable, true);
+    strict_1.default.equal(chromeRelayError.error.details.relay.userActionRequired, true);
+    strict_1.default.equal(chromeRelayError.error.details.relay.phase, "diagnostics");
+    strict_1.default.equal(chromeRelayError.error.details.relay.sharedTabScope, "current-shared-tab");
+});
+(0, node_test_1.default)("consumer sample stays aligned with the stable contract guidance", async () => {
+    const root = process.cwd();
+    const sample = await (0, promises_1.readFile)((0, node_path_1.resolve)(root, "examples", "clients", "http-node.ts"), "utf8");
+    const httpConsumer = await (0, promises_1.readFile)((0, node_path_1.resolve)(root, "examples", "clients", "http-consumer.ts"), "utf8");
+    const cliConsumer = await (0, promises_1.readFile)((0, node_path_1.resolve)(root, "examples", "clients", "cli-consumer.ts"), "utf8");
+    const doctorConnectWrapper = await (0, promises_1.readFile)((0, node_path_1.resolve)(root, "examples", "clients", "doctor-connect-wrapper.ts"), "utf8");
+    const claudeCodeInstalledPackageMcpConfig = await (0, promises_1.readFile)((0, node_path_1.resolve)(root, "examples", "mcp", "claude-code.installed-package.mcp.json"), "utf8");
+    const genericRepoCheckoutMcpConfig = await (0, promises_1.readFile)((0, node_path_1.resolve)(root, "examples", "mcp", "generic-stdio.repo-checkout.json"), "utf8");
+    const consumerGuide = await (0, promises_1.readFile)((0, node_path_1.resolve)(root, "docs", "consuming-the-bridge.md"), "utf8");
+    const adapterPatterns = await (0, promises_1.readFile)((0, node_path_1.resolve)(root, "docs", "adapter-patterns.md"), "utf8");
+    const readme = await (0, promises_1.readFile)((0, node_path_1.resolve)(root, "README.md"), "utf8");
+    strict_1.default.match(sample, /schemaVersion !== 1/);
+    strict_1.default.match(sample, /chrome-direct/);
+    strict_1.default.match(sample, /chrome-relay/);
+    strict_1.default.match(sample, /\/v1\/diagnostics\?browser=/);
+    strict_1.default.match(sample, /Safari \(actionable\)/);
+    strict_1.default.match(sample, /Chrome \(direct, read-only\)/);
+    strict_1.default.match(sample, /Chrome \(shared tab, read-only\)/);
+    strict_1.default.match(sample, /Chrome direct attach needs a local DevTools endpoint/);
+    strict_1.default.match(sample, /Chrome relay only works for a tab you explicitly share/);
+    strict_1.default.match(sample, /does not silently fall back between Chrome direct and relay/);
+    strict_1.default.match(sample, /Derive relay behavior from attach\.mode=relay plus the returned semantics fields\./);
+    strict_1.default.match(sample, /Tab reference semantics: windowIndex=/);
+    strict_1.default.match(sample, /Relay failure branch:/);
+    strict_1.default.match(sample, /Relay user prompt:/);
+    strict_1.default.match(sample, /sharedTabScope\?: "current-shared-tab"/);
+    strict_1.default.match(sample, /LOCAL_BROWSER_BRIDGE_SESSION_ID/);
+    strict_1.default.match(sample, /Hide activate\/navigate\/screenshot\./);
+    strict_1.default.match(sample, /require\("\.\.\/\.\.\/dist\/src"\) as typeof import\("\.\.\/\.\.\/src"\)/);
+    strict_1.default.match(httpConsumer, /createHttpBridgeAdapter/);
+    strict_1.default.match(httpConsumer, /connectViaBridge/);
+    strict_1.default.match(httpConsumer, /interpretBrowserAttachUxFromError/);
+    strict_1.default.match(httpConsumer, /chrome-direct/);
+    strict_1.default.match(httpConsumer, /chrome-relay/);
+    strict_1.default.match(httpConsumer, /LOCAL_BROWSER_BRIDGE_SESSION_ID/);
+    strict_1.default.match(httpConsumer, /transport: http/);
+    strict_1.default.match(cliConsumer, /createCliBridgeAdapter/);
+    strict_1.default.match(cliConsumer, /connectViaBridge/);
+    strict_1.default.match(cliConsumer, /interpretBrowserAttachUxFromError/);
+    strict_1.default.match(cliConsumer, /chrome-direct/);
+    strict_1.default.match(cliConsumer, /chrome-relay/);
+    strict_1.default.match(cliConsumer, /LOCAL_BROWSER_BRIDGE_SESSION_ID/);
+    strict_1.default.match(cliConsumer, /transport: cli/);
+    strict_1.default.match(doctorConnectWrapper, /runBridgeJson<DoctorPayload>\(\["doctor"/);
+    strict_1.default.match(doctorConnectWrapper, /runBridgeJson<ConnectPayload>\(\["connect"/);
+    strict_1.default.match(doctorConnectWrapper, /LOCAL_BROWSER_BRIDGE_SESSION_ID/);
+    strict_1.default.match(doctorConnectWrapper, /LOCAL_BROWSER_BRIDGE_BIN/);
+    strict_1.default.match(doctorConnectWrapper, /wrapper: "doctor-connect"/);
+    strict_1.default.match(doctorConnectWrapper, /outcome: "success"/);
+    strict_1.default.match(doctorConnectWrapper, /category: "session-connected"/);
+    strict_1.default.match(doctorConnectWrapper, /payload\.reason/);
+    strict_1.default.match(doctorConnectWrapper, /"chrome-relay"/);
+    strict_1.default.match(doctorConnectWrapper, /"safari"/);
+    strict_1.default.match(doctorConnectWrapper, /sharedTabScoped/);
+    strict_1.default.match(doctorConnectWrapper, /suggestedActions/);
+    strict_1.default.match(claudeCodeInstalledPackageMcpConfig, /node_modules\/\.bin\/local-browser-bridge-mcp/);
+    strict_1.default.doesNotMatch(claudeCodeInstalledPackageMcpConfig, /dist\/src\/mcp-stdio\.js/);
+    strict_1.default.match(genericRepoCheckoutMcpConfig, /"command": "node"/);
+    strict_1.default.match(genericRepoCheckoutMcpConfig, /dist\/src\/mcp-stdio\.js/);
+    strict_1.default.doesNotMatch(genericRepoCheckoutMcpConfig, /node_modules\/\.bin\/local-browser-bridge-mcp/);
+    strict_1.default.match(consumerGuide, /src\/index\.ts/);
+    strict_1.default.match(consumerGuide, /import \{ interpretChromeRelayFailure \} from "\.\.\/src"/);
+    strict_1.default.match(consumerGuide, /interpretBrowserAttachUxFromSession[\s\S]*from "\.\.\/src"/);
+    strict_1.default.match(consumerGuide, /Chrome relay parity example/);
+    strict_1.default.match(consumerGuide, /Adapter Patterns/);
+    strict_1.default.match(consumerGuide, /\.\/adapter-patterns\.md/);
+    strict_1.default.match(consumerGuide, /schema\/chrome-relay-error\.schema\.json/);
+    strict_1.default.match(consumerGuide, /examples\/error\.chrome-relay-share-required\.example\.json/);
+    strict_1.default.match(consumerGuide, /attach --browser chrome --attach-mode relay/);
+    strict_1.default.match(consumerGuide, /"attach":\{"mode":"relay"\}/);
+    strict_1.default.match(consumerGuide, /session\.attach/);
+    strict_1.default.match(consumerGuide, /session\.semantics/);
+    strict_1.default.match(consumerGuide, /error\.details\.relay\.branch/);
+    strict_1.default.match(consumerGuide, /error\.details\.relay\.sharedTabScope = "current-shared-tab"/);
+    strict_1.default.match(consumerGuide, /interpretChromeRelayFailure/);
+    strict_1.default.match(consumerGuide, /retryable/);
+    strict_1.default.match(consumerGuide, /examples\/clients\/http-consumer\.ts/);
+    strict_1.default.match(consumerGuide, /examples\/clients\/cli-consumer\.ts/);
+    strict_1.default.match(consumerGuide, /examples\/clients\/doctor-connect-wrapper\.ts/);
+    strict_1.default.match(consumerGuide, /examples\/clients\/codex-consumer\.ts/);
+    strict_1.default.match(consumerGuide, /examples\/clients\/claude-code-tool\.ts/);
+    strict_1.default.match(consumerGuide, /createHttpBridgeAdapter/);
+    strict_1.default.match(consumerGuide, /createCliBridgeAdapter/);
+    strict_1.default.match(consumerGuide, /connectViaBridge/);
+    strict_1.default.match(consumerGuide, /normalizeCodexRoute/);
+    strict_1.default.match(consumerGuide, /connectCodexViaCli/);
+    strict_1.default.match(consumerGuide, /connectCodexViaHttp/);
+    strict_1.default.match(consumerGuide, /normalizeClaudeCodeRoute/);
+    strict_1.default.match(consumerGuide, /prepareClaudeCodeRoute/);
+    strict_1.default.match(consumerGuide, /node --experimental-strip-types examples\/clients\/doctor-connect-wrapper\.ts safari/);
+    strict_1.default.match(consumerGuide, /outcome`, `status`, `category`, and optional `reason`/);
+    strict_1.default.match(consumerGuide, /"outcome": "blocked"/);
+    strict_1.default.match(consumerGuide, /"category": "session-connected"/);
+    strict_1.default.match(consumerGuide, /Chrome relay only works for a tab you explicitly share/);
+    strict_1.default.match(consumerGuide, /suggestedActions/);
+    strict_1.default.doesNotMatch(consumerGuide, /OpenClaw\/browser-style consumer demo/);
+    strict_1.default.match(adapterPatterns, /OpenClaw/);
+    strict_1.default.match(adapterPatterns, /AWOS/);
+    strict_1.default.match(adapterPatterns, /Codex/);
+    strict_1.default.match(adapterPatterns, /Claude Code/);
+    strict_1.default.match(adapterPatterns, /transport-neutral/i);
+    strict_1.default.match(adapterPatterns, /agent-agnostic/i);
+    strict_1.default.match(adapterPatterns, /CLI for one-shot invocation/);
+    strict_1.default.match(adapterPatterns, /local HTTP for long-running connectors/);
+    strict_1.default.match(adapterPatterns, /Shared consumer surface/);
+    strict_1.default.match(adapterPatterns, /from "local-browser-bridge"/);
+    strict_1.default.match(adapterPatterns, /Minimal adapter skeleton:/);
+    strict_1.default.match(adapterPatterns, /connectBrowserRoute/);
+    strict_1.default.match(adapterPatterns, /runBrowserTool/);
+    strict_1.default.match(adapterPatterns, /runAgentStep/);
+    strict_1.default.match(adapterPatterns, /normalizeCodexRoute/);
+    strict_1.default.match(adapterPatterns, /connectCodexViaCli/);
+    strict_1.default.match(adapterPatterns, /connectCodexViaHttp/);
+    strict_1.default.match(adapterPatterns, /prepareToolPrompt/);
+    strict_1.default.match(adapterPatterns, /export async function connect\(/);
+    strict_1.default.match(adapterPatterns, /examples\/clients\/doctor-connect-wrapper\.ts/);
+    strict_1.default.match(adapterPatterns, /outcome` \/ `status` \/ `category` \/ `reason`/);
+    strict_1.default.match(readme, /examples\/clients\/doctor-connect-wrapper\.ts/);
+    strict_1.default.match(readme, /local-browser-bridge doctor --route/);
+    strict_1.default.match(readme, /outcome` \/ `status` \/ `category` \/ `reason`/);
+    strict_1.default.match(readme, /chrome-relay` read-only plus shared-tab scoped/);
+    strict_1.default.match(readme, /`browser_tabs` is available for Safari and `chrome-direct`/);
+    strict_1.default.match(readme, /structured non-error blocked result/);
+    strict_1.default.match(readme, /Runtime action tools such as `activate`, `navigate`, or `screenshot` are intentionally not part of this RC MCP surface/);
+    strict_1.default.match(readme, /examples\/mcp\/claude-code\.installed-package\.mcp\.json/);
+    strict_1.default.match(readme, /examples\/mcp\/generic-stdio\.repo-checkout\.json/);
+    strict_1.default.match(readme, /npm run cli -- --help/);
+    strict_1.default.doesNotMatch(readme, /npm run bridge -- --help/);
+    strict_1.default.match(readme, /consumer project[\s\S]*node_modules\/\.bin\/local-browser-bridge-mcp/);
+    strict_1.default.match(readme, /Equivalent direct repo-checkout command after `npm run build`:\s*```bash\s*node \.\/dist\/src\/mcp-stdio\.js\s*```/);
+    strict_1.default.match(readme, /node \.\/dist\/src\/mcp-stdio\.js/);
+    strict_1.default.doesNotMatch(readme, /Equivalent direct repo-checkout command after `npm run build`:\s*```bash\s*\.\/node_modules\/\.bin\/local-browser-bridge-mcp\s*```/);
+});
+(0, node_test_1.default)("chrome relay error schema artifact stays documented and aligned with the example", async () => {
+    const root = process.cwd();
+    const schema = await readJson((0, node_path_1.resolve)(root, "schema", "chrome-relay-error.schema.json"));
+    const readme = await (0, promises_1.readFile)((0, node_path_1.resolve)(root, "README.md"), "utf8");
+    const consumerGuide = await (0, promises_1.readFile)((0, node_path_1.resolve)(root, "docs", "consuming-the-bridge.md"), "utf8");
+    const adapterPatterns = await (0, promises_1.readFile)((0, node_path_1.resolve)(root, "docs", "adapter-patterns.md"), "utf8");
+    const integrationContract = await (0, promises_1.readFile)((0, node_path_1.resolve)(root, "docs", "agent-integration-contract.md"), "utf8");
+    const prd = await (0, promises_1.readFile)((0, node_path_1.resolve)(root, "PRD.md"), "utf8");
+    strict_1.default.match(schema.$id, /chrome-relay-error\.schema\.json$/);
+    strict_1.default.equal(schema.properties?.error?.properties?.details?.$ref, "#/$defs/chromeRelayErrorDetails");
+    strict_1.default.match(readme, /schema\/chrome-relay-error\.schema\.json/);
+    strict_1.default.match(readme, /examples\/error\.chrome-relay-share-required\.example\.json/);
+    strict_1.default.match(readme, /docs\/adapter-patterns\.md/);
+    strict_1.default.match(readme, /src\/index\.ts/);
+    strict_1.default.match(consumerGuide, /\.\/adapter-patterns\.md/);
+    strict_1.default.match(adapterPatterns, /Agent Integration Contract/);
+    strict_1.default.match(adapterPatterns, /Consuming local-browser-bridge/);
+    strict_1.default.match(consumerGuide, /schema\/chrome-relay-error\.schema\.json/);
+    strict_1.default.match(consumerGuide, /examples\/error\.chrome-relay-share-required\.example\.json/);
+    strict_1.default.match(integrationContract, /schema\/chrome-relay-error\.schema\.json/);
+    strict_1.default.match(integrationContract, /examples\/error\.chrome-relay-share-required\.example\.json/);
+    strict_1.default.match(integrationContract, /additive transport-neutral error envelope/i);
+    strict_1.default.match(integrationContract, /shared-tab read-only path/i);
+    strict_1.default.match(prd, /Chrome relay structured failure contract/);
+    strict_1.default.match(prd, /transport-neutral structured error details aligned across CLI and local HTTP/);
+    strict_1.default.match(prd, /error\.details\.relay\.sharedTabScope = "current-shared-tab"/);
+});

package/dist/tests/doctor-connect-wrapper.test.d.ts

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

package/dist/tests/doctor-connect-wrapper.test.js

@@ -0,0 +1,62 @@
+"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_child_process_1 = require("node:child_process");
+const node_path_1 = require("node:path");
+const node_util_1 = require("node:util");
+const node_test_1 = __importDefault(require("node:test"));
+const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
+(0, node_test_1.default)("doctor/connect wrapper example surfaces blocked relay prompts", async () => {
+    const wrapperPath = (0, node_path_1.resolve)(process.cwd(), "examples/clients/doctor-connect-wrapper.ts");
+    const stubPath = (0, node_path_1.resolve)(process.cwd(), "dist/tests/fixtures/doctor-connect-cli-stub.js");
+    const result = await execFileAsync(process.execPath, ["--experimental-strip-types", wrapperPath, "chrome-relay"], {
+        cwd: process.cwd(),
+        env: {
+            ...process.env,
+            LOCAL_BROWSER_BRIDGE_BIN: process.execPath,
+            LOCAL_BROWSER_BRIDGE_CLI_PATH: stubPath
+        }
+    });
+    const payload = JSON.parse(result.stdout);
+    strict_1.default.equal(payload.result.ok, false);
+    strict_1.default.equal(payload.result.stage, "doctor");
+    strict_1.default.equal(payload.result.outcome, "blocked");
+    strict_1.default.equal(payload.result.status, "blocked");
+    strict_1.default.equal(payload.result.category, "route-blocked");
+    strict_1.default.equal(payload.result.reason?.code, "relay_share_required");
+    strict_1.default.equal(payload.result.route, "chrome-relay");
+    strict_1.default.equal(payload.result.label, "Chrome (shared tab, read-only)");
+    strict_1.default.match(payload.result.prompt, /Share the tab first/i);
+    strict_1.default.equal(payload.result.nextStep.action, "fix-blocker");
+    strict_1.default.equal(payload.result.readOnly, true);
+    strict_1.default.equal(payload.result.sharedTabScoped, true);
+});
+(0, node_test_1.default)("doctor/connect wrapper example returns concise session results for Safari", async () => {
+    const wrapperPath = (0, node_path_1.resolve)(process.cwd(), "examples/clients/doctor-connect-wrapper.ts");
+    const stubPath = (0, node_path_1.resolve)(process.cwd(), "dist/tests/fixtures/doctor-connect-cli-stub.js");
+    const result = await execFileAsync(process.execPath, ["--experimental-strip-types", wrapperPath, "safari"], {
+        cwd: process.cwd(),
+        env: {
+            ...process.env,
+            LOCAL_BROWSER_BRIDGE_BIN: process.execPath,
+            LOCAL_BROWSER_BRIDGE_CLI_PATH: stubPath
+        }
+    });
+    const payload = JSON.parse(result.stdout);
+    strict_1.default.equal(payload.wrapper, "doctor-connect");
+    strict_1.default.equal(payload.result.ok, true);
+    strict_1.default.equal(payload.result.stage, "connect");
+    strict_1.default.equal(payload.result.outcome, "success");
+    strict_1.default.equal(payload.result.status, "connected");
+    strict_1.default.equal(payload.result.category, "session-connected");
+    strict_1.default.equal(payload.result.route, "safari");
+    strict_1.default.equal(payload.result.label, "Safari (actionable)");
+    strict_1.default.equal(payload.result.readOnly, false);
+    strict_1.default.equal(payload.result.session?.id, "session-safari-demo");
+    strict_1.default.equal(payload.result.session?.kind, "safari-actionable");
+    strict_1.default.equal(payload.result.session?.canAct, true);
+    strict_1.default.deepEqual(payload.result.session?.suggestedActions, ["resume", "activate", "navigate", "screenshot"]);
+});

package/dist/tests/fixtures/doctor-connect-cli-stub.d.ts

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

package/dist/tests/fixtures/doctor-connect-cli-stub.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+function writeJson(payload) {
+    process.stdout.write(JSON.stringify(payload));
+}
+const [command, ...args] = process.argv.slice(2);
+const route = args[1];
+if (command === "doctor" && args[0] === "--route" && route === "chrome-relay") {
+    writeJson({
+        ok: false,
+        command: "doctor",
+        outcome: "blocked",
+        status: "blocked",
+        category: "route-blocked",
+        reason: {
+            code: "relay_share_required",
+            message: "Share the tab first."
+        },
+        summary: "Chrome (shared tab, read-only) is not ready yet. It remains read-only and only covers the currently shared tab.",
+        prompt: "Chrome relay only works for a tab you explicitly share. Share the tab first, then retry.",
+        nextStep: {
+            action: "fix-blocker",
+            prompt: "Chrome relay only works for a tab you explicitly share. Share the tab first, then retry."
+        },
+        routeUx: {
+            label: "Chrome (shared tab, read-only)",
+            state: "blocked",
+            readOnly: true,
+            sharedTabScoped: true
+        }
+    });
+}
+else if (command === "doctor" && args[0] === "--route" && route === "safari") {
+    writeJson({
+        ok: true,
+        command: "doctor",
+        outcome: "success",
+        status: "ready",
+        category: "route-ready",
+        summary: "Safari (actionable) is ready for attach. It is actionable.",
+        nextStep: {
+            action: "connect",
+            prompt: "Run local-browser-bridge connect --route safari to continue.",
+            command: "local-browser-bridge connect --route safari"
+        },
+        routeUx: {
+            label: "Safari (actionable)",
+            state: "ready",
+            readOnly: false,
+            sharedTabScoped: false
+        }
+    });
+}
+else if (command === "connect" && args[0] === "--route" && route === "safari") {
+    writeJson({
+        ok: true,
+        command: "connect",
+        connected: true,
+        outcome: "success",
+        status: "connected",
+        category: "session-connected",
+        summary: "Connected Safari (actionable) session session-safari-demo. It is actionable.",
+        nextStep: {
+            action: "session-ready",
+            prompt: "Use session session-safari-demo for follow-up actions like activate, navigate, or screenshot."
+        },
+        routeUx: {
+            label: "Safari (actionable)",
+            state: "ready",
+            readOnly: false,
+            sharedTabScoped: false
+        },
+        sessionUx: {
+            label: "Safari (actionable)",
+            state: "ready",
+            readOnly: false,
+            sharedTabScoped: false
+        },
+        session: {
+            id: "session-safari-demo",
+            kind: "safari-actionable",
+            capabilities: {
+                activate: true,
+                navigate: true,
+                screenshot: true
+            }
+        }
+    });
+}
+else {
+    process.stderr.write(`Unexpected args: ${[command, ...args].join(" ")}`);
+    process.exitCode = 1;
+}

package/dist/tests/fixtures/public-root-cli-stub.d.ts

@@ -0,0 +1,210 @@
+declare const capabilities: {
+    schemaVersion: number;
+    kind: string;
+    product: {
+        name: string;
+        version: string;
+    };
+};
+declare const diagnostics: {
+    browser: "chrome";
+    checkedAt: string;
+    runtime: {
+        platform: string;
+        arch: string;
+        nodeVersion: string;
+        safariRunning: boolean;
+    };
+    host: {
+        osascriptAvailable: boolean;
+        screencaptureAvailable: boolean;
+        safariApplicationAvailable: boolean;
+    };
+    supportedFeatures: {
+        inspectTabs: boolean;
+        attach: boolean;
+        activate: boolean;
+        navigate: boolean;
+        screenshot: boolean;
+        savedSessions: boolean;
+        cli: boolean;
+        httpApi: boolean;
+    };
+    constraints: never[];
+    attach: {
+        direct: {
+            mode: "direct";
+            source: "user-browser";
+            scope: "browser";
+            supported: boolean;
+            ready: boolean;
+            state: "ready";
+            blockers: never[];
+        };
+        relay: {
+            mode: "relay";
+            source: "extension-relay";
+            scope: "tab";
+            supported: boolean;
+            ready: boolean;
+            state: "ready";
+            blockers: never[];
+        };
+    };
+};
+declare const session: {
+    schemaVersion: 1;
+    id: string;
+    kind: "chrome-readonly";
+    browser: "chrome";
+    target: {
+        type: "front";
+    };
+    tab: {
+        browser: "chrome";
+        windowIndex: number;
+        tabIndex: number;
+        title: string;
+        url: string;
+        attachedAt: string;
+        identity: {
+            signature: string;
+            urlKey: string;
+            titleKey: string;
+            origin: string;
+            pathname: string;
+        };
+    };
+    frontTab: {
+        browser: "chrome";
+        windowIndex: number;
+        tabIndex: number;
+        title: string;
+        url: string;
+        attachedAt: string;
+        identity: {
+            signature: string;
+            urlKey: string;
+            titleKey: string;
+            origin: string;
+            pathname: string;
+        };
+    };
+    attach: {
+        mode: "relay";
+        source: "extension-relay";
+        scope: "tab";
+        resumable: boolean;
+    };
+    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: boolean;
+        navigate: boolean;
+        screenshot: boolean;
+    };
+    status: {
+        state: "read-only";
+        canAct: boolean;
+    };
+    createdAt: string;
+};
+declare const resumedSession: {
+    session: {
+        schemaVersion: 1;
+        id: string;
+        kind: "chrome-readonly";
+        browser: "chrome";
+        target: {
+            type: "front";
+        };
+        tab: {
+            browser: "chrome";
+            windowIndex: number;
+            tabIndex: number;
+            title: string;
+            url: string;
+            attachedAt: string;
+            identity: {
+                signature: string;
+                urlKey: string;
+                titleKey: string;
+                origin: string;
+                pathname: string;
+            };
+        };
+        frontTab: {
+            browser: "chrome";
+            windowIndex: number;
+            tabIndex: number;
+            title: string;
+            url: string;
+            attachedAt: string;
+            identity: {
+                signature: string;
+                urlKey: string;
+                titleKey: string;
+                origin: string;
+                pathname: string;
+            };
+        };
+        attach: {
+            mode: "relay";
+            source: "extension-relay";
+            scope: "tab";
+            resumable: boolean;
+        };
+        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: boolean;
+            navigate: boolean;
+            screenshot: boolean;
+        };
+        status: {
+            state: "read-only";
+            canAct: boolean;
+        };
+        createdAt: string;
+    };
+    tab: {
+        browser: "chrome";
+        windowIndex: number;
+        tabIndex: number;
+        title: string;
+        url: string;
+        attachedAt: string;
+        identity: {
+            signature: string;
+            urlKey: string;
+            titleKey: string;
+            origin: string;
+            pathname: string;
+        };
+    };
+    resumedAt: string;
+    resolution: {
+        strategy: "front";
+        matched: boolean;
+        attachMode: "relay";
+        semantics: "current-shared-tab";
+    };
+};
+declare function writeJson(payload: unknown): void;
+declare const command: string, args: string[];