From 81e771c1b0959b8f9afa94302c52cdd767fef8e3 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 2 Nov 2026 13:14:09 +0000
Subject: [PATCH 1/4] =?UTF-8?q?feat(bridge):=20scan()=20=E2=80=94=20wip?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Claude-Session: https://claude.ai/code/session_01QSeKYnW1Xf6HDSWz1eGAqv
Co-authored-by: Claude <noreply@anthropic.com>
---
 __tests__/lib/shell/bridge-handler.test.ts | 111 +++++++++++++++++++++
 __tests__/lib/shell/bridge-scripts.test.ts |  71 ++++++++++++-
 app/bridge-scan.tsx                        |  81 +++++++++++++++
 app/console.tsx                            |   2 +
 components/shell/ConsoleWebView.tsx        |  11 +-
 components/shell/QrScanner.tsx             |  33 +++++-
 lib/shell/bridge/handler.ts                |  34 +++++++
 lib/shell/bridge/protocol.ts               |  22 ++++
 lib/shell/bridge/scan-session.ts           |  76 ++++++++++++++
 lib/shell/bridge/scripts.ts                |   7 +-
 locales/ar.json                            |   8 +-
 locales/en.json                            |   8 +-
 locales/zh.json                            |   8 +-
 13 files changed, 458 insertions(+), 14 deletions(-)
 create mode 100644 app/bridge-scan.tsx
 create mode 100644 lib/shell/bridge/scan-session.ts

diff --git a/__tests__/lib/shell/bridge-handler.test.ts b/__tests__/lib/shell/bridge-handler.test.ts
index dc91094..2dd4320 100644
--- a/__tests__/lib/shell/bridge-handler.test.ts
+++ b/__tests__/lib/shell/bridge-handler.test.ts
@@ -1,4 +1,13 @@
 import { createBridgeHandler, type BridgeDeps } from "~/lib/shell/bridge/handler";
+import { SCAN_FORMATS } from "~/lib/shell/bridge/protocol";
+import {
+  SCAN_BUSY_MESSAGE,
+  SCAN_DENIED_MESSAGE,
+  currentScan,
+  requestScan,
+  settleScan,
+  type ScanOutcome,
+} from "~/lib/shell/bridge/scan-session";
 
 const SERVER = "https://acme.example.com";
 const PAGE = `${SERVER}/_console/home`;
@@ -11,6 +20,7 @@ function setup(overrides: Partial<BridgeDeps> = {}) {
     openExternal: jest.fn().mockResolvedValue(undefined),
     navigate: jest.fn(),
     resetServer: jest.fn().mockResolvedValue(undefined),
+    scan: jest.fn().mockResolvedValue("4006381333931"),
     onEvent: jest.fn(),
     ...overrides,
   };
@@ -134,6 +144,107 @@ describe("bridge handler", () => {
     });
   });
 
+  describe("scan", () => {
+    it("reads every format when the call names none", async () => {
+      const { handle, deps } = setup();
+      for (const args of [undefined, null, {}]) {
+        await expect(handle(call("scan", args), PAGE)).resolves.toEqual({
+          id: "c1",
+          ok: true,
+          value: "4006381333931",
+        });
+      }
+      expect(deps.scan).toHaveBeenCalledTimes(3);
+      for (const [formats] of (deps.scan as jest.Mock).mock.calls) {
+        expect(formats).toEqual(SCAN_FORMATS);
+      }
+    });
+
+    it("reads only the formats the call names", async () => {
+      const { handle, deps } = setup();
+      await expect(
+        handle(call("scan", { formats: ["ean13", "qr", "ean13"] }), PAGE)
+      ).resolves.toMatchObject({ ok: true });
+      expect(deps.scan).toHaveBeenCalledWith(["qr", "ean13"]);
+    });
+
+    it.each([
+      ["an empty format list", { formats: [] }],
+      ["an unknown format", { formats: ["qr", "barcode"] }],
+      ["a format that is not a string", { formats: ["qr", 5] }],
+      ["formats that are not a list", { formats: "qr" }],
+      ["an unknown option", { format: ["qr"] }],
+      ["an extra option", { formats: ["qr"], torch: true }],
+      ["options that are a list", ["qr"]],
+      ["options that are a string", "qr"],
+    ])("refuses %s as bad_args without opening the scanner", async (_label, args) => {
+      const { handle, deps } = setup();
+      await expect(handle(call("scan", args), PAGE)).resolves.toMatchObject({
+        ok: false,
+        error: { code: "bad_args" },
+      });
+      expect(deps.scan).not.toHaveBeenCalled();
+    });
+
+    it("answers nothing, and opens no scanner, for a page on another origin", async () => {
+      const { handle, deps } = setup();
+      await expect(handle(call("scan"), "https://evil.example.com/")).resolves.toBeNull();
+      expect(deps.scan).not.toHaveBeenCalled();
+    });
+
+    describe("through the scan session", () => {
+      const show = jest.fn();
+      const scanThroughSession = () =>
+        setup({ scan: (formats) => requestScan(formats, show) }).handle;
+
+      /** Settle the open scan once the handler has opened it. */
+      async function settleOpen(outcome: ScanOutcome) {
+        await Promise.resolve();
+        const open = currentScan();
+        if (!open) throw new Error("no scan open");
+        settleScan(open.token, outcome);
+      }
+
+      beforeEach(() => show.mockReset());
+
+      it("resolves the decoded text", async () => {
+        const answer = scanThroughSession()(call("scan", { formats: ["code128"] }), PAGE);
+        await settleOpen({ kind: "result", text: "SKU-0042" });
+        await expect(answer).resolves.toEqual({ id: "c1", ok: true, value: "SKU-0042" });
+        expect(show).toHaveBeenCalledTimes(1);
+      });
+
+      it("resolves null on cancel", async () => {
+        const answer = scanThroughSession()(call("scan"), PAGE);
+        await settleOpen({ kind: "cancel" });
+        await expect(answer).resolves.toEqual({ id: "c1", ok: true, value: null });
+      });
+
+      it("fails when the camera permission is denied", async () => {
+        const answer = scanThroughSession()(call("scan"), PAGE);
+        await settleOpen({ kind: "denied" });
+        await expect(answer).resolves.toEqual({
+          id: "c1",
+          ok: false,
+          error: { code: "failed", message: SCAN_DENIED_MESSAGE },
+        });
+      });
+
+      it("refuses a second scan while one is open, and leaves the open one alone", async () => {
+        const handle = scanThroughSession();
+        const first = handle(call("scan", undefined, "c1"), PAGE);
+        await expect(handle(call("scan", undefined, "c2"), PAGE)).resolves.toEqual({
+          id: "c2",
+          ok: false,
+          error: { code: "failed", message: SCAN_BUSY_MESSAGE },
+        });
+        expect(show).toHaveBeenCalledTimes(1);
+        await settleOpen({ kind: "result", text: "first" });
+        await expect(first).resolves.toEqual({ id: "c1", ok: true, value: "first" });
+      });
+    });
+  });
+
   it("turns a thrown capability into a failed result", async () => {
     const { handle } = setup({ getPushToken: jest.fn().mockRejectedValue(new Error("APNs down")) });
     await expect(handle(call("getPushToken"), PAGE)).resolves.toEqual({
diff --git a/__tests__/lib/shell/bridge-scripts.test.ts b/__tests__/lib/shell/bridge-scripts.test.ts
index 97f50a1..9517d60 100644
--- a/__tests__/lib/shell/bridge-scripts.test.ts
+++ b/__tests__/lib/shell/bridge-scripts.test.ts
@@ -42,6 +42,9 @@ function makePage(origin = "https://acme.example.com") {
   return { window, posted, cssVars, listeners, run };
 }
 
+/** The id of a call the page posted. */
+const idOf = (message: unknown) => (message as { id: string }).id;
+
 describe("toScriptLiteral", () => {
   it("escapes characters that could break out of a script", () => {
     expect(toScriptLiteral("</script>\u2028\u2029")).toBe('"\\u003c/script>\\u2028\\u2029"');
@@ -112,18 +115,80 @@ describe("bootstrap script", () => {
     page.run(buildBootstrapScript(info, SERVER_URL));
     const pending = page.window.ObjectStackNative.haptic("success");
     expect(page.posted).toEqual([
-      { type: "call", id: "c1", method: "haptic", args: { kind: "success" } },
+      { type: "call", id: expect.any(String), method: "haptic", args: { kind: "success" } },
     ]);
-    page.run(buildResolveScript({ id: "c1", ok: true, value: null }));
+    page.run(buildResolveScript({ id: idOf(page.posted[0]), ok: true, value: null }));
     await expect(pending).resolves.toBeNull();
   });
 
+  it("gives every call of a document its own id, under a token of that document", () => {
+    const page = makePage();
+    page.run(buildBootstrapScript(info, SERVER_URL));
+    void page.window.ObjectStackNative.getPushToken();
+    void page.window.ObjectStackNative.getPushToken();
+    const [first, second] = page.posted.map(idOf);
+    expect(first).toMatch(/^[a-z0-9]+\.1$/);
+    expect(second).toBe(first.replace(/1$/, "2"));
+    expect(first.length).toBeLessThanOrEqual(64);
+  });
+
+  it("settles no call of a later document with an answer meant for an earlier one", async () => {
+    // A scan stays open while the page reloads, recovers or goes to a sign-in
+    // host; each new document numbers its calls from 1 again.
+    const before = makePage();
+    before.run(buildBootstrapScript(info, SERVER_URL));
+    void before.window.ObjectStackNative.scan();
+    const staleAnswer = buildResolveScript({ id: idOf(before.posted[0]), ok: true, value: "CODE" });
+
+    for (const origin of ["https://acme.example.com", "https://login.idp.example"]) {
+      const after = makePage(origin);
+      after.run(buildBootstrapScript(info, SERVER_URL));
+      let settled = false;
+      const pending = after.window.ObjectStackNative.getPushToken().then(() => (settled = true));
+      after.run(staleAnswer);
+      await Promise.resolve();
+      expect(settled).toBe(false);
+      after.run(buildResolveScript({ id: idOf(after.posted[0]), ok: true, value: null }));
+      await pending;
+      expect(settled).toBe(true);
+    }
+  });
+
+  it("posts scan calls with the caller's options, or none", () => {
+    const page = makePage();
+    page.run(buildBootstrapScript({ ...info, capabilities: ["scan"] }, SERVER_URL));
+    const api = page.window.ObjectStackNative;
+    expect(api.has("scan")).toBe(true);
+    void api.scan();
+    void api.scan({ formats: ["ean13", "qr"] });
+    expect(page.posted).toEqual([
+      { type: "call", id: expect.any(String), method: "scan" },
+      { type: "call", id: expect.any(String), method: "scan", args: { formats: ["ean13", "qr"] } },
+    ]);
+  });
+
+  it("resolves a scan with the decoded text, or null on cancel", async () => {
+    const page = makePage();
+    page.run(buildBootstrapScript(info, SERVER_URL));
+    const read = page.window.ObjectStackNative.scan();
+    const cancelled = page.window.ObjectStackNative.scan();
+    const [readId, cancelId] = page.posted.map(idOf);
+    page.run(buildResolveScript({ id: readId, ok: true, value: "4006381333931" }));
+    page.run(buildResolveScript({ id: cancelId, ok: true, value: null }));
+    await expect(read).resolves.toBe("4006381333931");
+    await expect(cancelled).resolves.toBeNull();
+  });
+
   it("rejects failed calls with the error code", async () => {
     const page = makePage();
     page.run(buildBootstrapScript(info, SERVER_URL));
     const pending = page.window.ObjectStackNative.navigate("bad");
     page.run(
-      buildResolveScript({ id: "c1", ok: false, error: { code: "bad_args", message: "nope" } })
+      buildResolveScript({
+        id: idOf(page.posted[0]),
+        ok: false,
+        error: { code: "bad_args", message: "nope" },
+      })
     );
     await expect(pending).rejects.toMatchObject({ message: "nope", code: "bad_args" });
   });
diff --git a/app/bridge-scan.tsx b/app/bridge-scan.tsx
new file mode 100644
index 0000000..6c0babe
--- /dev/null
+++ b/app/bridge-scan.tsx
@@ -0,0 +1,81 @@
+import React from "react";
+import { useRouter } from "expo-router";
+import { useTranslation } from "react-i18next";
+import type { PermissionStatus } from "expo-camera";
+import { QrScanner } from "~/components/shell/QrScanner";
+import { currentScan, settleScan, type ScanOutcome } from "~/lib/shell/bridge/scan-session";
+
+const acceptAny = (code: string) => (code.length > 0 ? code : null);
+
+/**
+ * The scanner a Console page opens with the bridge's `scan()`: reads the
+ * formats of the open scan (`lib/shell/bridge/scan-session.ts`) and settles it
+ * with the first code read, `null` when the user closes it, or a failure when
+ * the camera permission is refused.
+ *
+ * Every way out settles the scan — the close control, Android back and the
+ * iOS swipe alike, the last two through the unmount. Opened with no scan for
+ * it (a link to the route), it closes at once.
+ */
+export default function BridgeScanScreen() {
+  const router = useRouter();
+  const { t } = useTranslation();
+  const scan = React.useRef(currentScan()).current;
+  const deniedRef = React.useRef(false);
+
+  const leave = React.useCallback(() => {
+    if (router.canGoBack()) router.back();
+    else router.replace("/");
+  }, [router]);
+
+  const giveUp = React.useCallback((): ScanOutcome => {
+    return deniedRef.current ? { kind: "denied" } : { kind: "cancel" };
+  }, []);
+
+  React.useEffect(() => {
+    if (!scan) {
+      leave();
+      return;
+    }
+    return () => {
+      settleScan(scan.token, giveUp());
+    };
+  }, [scan, leave, giveUp]);
+
+  const onPermissionStatus = React.useCallback((status: PermissionStatus) => {
+    deniedRef.current = (status as string) === "denied";
+  }, []);
+
+  const onResult = React.useCallback(
+    (text: string) => {
+      if (scan) settleScan(scan.token, { kind: "result", text });
+      leave();
+    },
+    [scan, leave]
+  );
+
+  const onClose = React.useCallback(() => {
+    if (scan) settleScan(scan.token, giveUp());
+    leave();
+  }, [scan, leave, giveUp]);
+
+  const barcodeTypes = React.useMemo(() => (scan ? [...scan.formats] : []), [scan]);
+
+  if (!scan) return null;
+
+  return (
+    <QrScanner
+      accept={acceptAny}
+      onResult={onResult}
+      onClose={onClose}
+      barcodeTypes={barcodeTypes}
+      hint={t("scanner.codeHint")}
+      rejectMessage={t("scanner.unreadable")}
+      permissionText={{
+        body: t("scanner.permission.codeBody"),
+        blocked: t("scanner.permission.codeBlocked"),
+      }}
+      onPermissionStatus={onPermissionStatus}
+    />
+  );
+}
diff --git a/app/console.tsx b/app/console.tsx
index d585217..36a9bac 100644
--- a/app/console.tsx
+++ b/app/console.tsx
@@ -10,6 +10,7 @@ import { acquireDeviceToken } from "~/lib/push-notifications";
 import { triggerHaptic } from "~/lib/haptics";
 import { shellConfig } from "~/lib/shell/config";
 import { openExternalUrl } from "~/lib/shell/external";
+import { requestScan } from "~/lib/shell/bridge/scan-session";
 import { DEFAULT_ROUTE_RULES } from "~/lib/shell/route-owner";
 import { AVAILABLE_NATIVE_SCREENS, NATIVE_SCREENS } from "~/lib/shell/native-screens";
 import { useServerStore } from "~/stores/server-store";
@@ -48,6 +49,7 @@ export default function ConsoleScreen() {
         await reset();
         router.replace("/server-config");
       },
+      scan: (formats) => requestScan(formats, () => router.push("/bridge-scan")),
     }),
     [reset, router]
   );
diff --git a/components/shell/ConsoleWebView.tsx b/components/shell/ConsoleWebView.tsx
index 8724d3e..69422d7 100644
--- a/components/shell/ConsoleWebView.tsx
+++ b/components/shell/ConsoleWebView.tsx
@@ -114,6 +114,11 @@ export const ConsoleWebView = forwardRef<ConsoleWebViewHandle, ConsoleWebViewPro
     // The last Console route the page was on, so a re-created WebView resumes
     // there instead of at the start route.
     const lastRouteRef = useRef<string | null>(null);
+    // Counts documents: a new one starts on every load start and every
+    // re-created WebView. A call's answer goes only to the document that made
+    // the call. A `scan()` stays open as long as the user takes, and the page
+    // can be replaced meanwhile (a reload, recovery, a sign-in redirect).
+    const documentRef = useRef(0);
 
     const goTo = useCallback(
       (route: string) => {
@@ -175,6 +180,7 @@ export const ConsoleWebView = forwardRef<ConsoleWebViewHandle, ConsoleWebViewPro
       loadedRef.current = false;
       setFailure(null);
       setLoaded(false);
+      documentRef.current += 1;
       setInstance((i) => i + 1);
     }, []);
 
@@ -262,6 +268,7 @@ export const ConsoleWebView = forwardRef<ConsoleWebViewHandle, ConsoleWebViewPro
       if (held) sendPushToken(held);
     }, [sendPushToken]);
     const onDocumentStart = useCallback(() => {
+      documentRef.current += 1;
       consoleReadyRef.current = false;
     }, []);
 
@@ -282,8 +289,10 @@ export const ConsoleWebView = forwardRef<ConsoleWebViewHandle, ConsoleWebViewPro
 
     const onMessage = useCallback(
       (event: WebViewMessageEvent) => {
+        const caller = documentRef.current;
         void handleMessage(event.nativeEvent.data, event.nativeEvent.url).then((result) => {
-          if (result) webviewRef.current?.injectJavaScript(buildResolveScript(result));
+          if (!result || documentRef.current !== caller) return;
+          webviewRef.current?.injectJavaScript(buildResolveScript(result));
         });
       },
       [handleMessage]
diff --git a/components/shell/QrScanner.tsx b/components/shell/QrScanner.tsx
index c277796..97ea001 100644
--- a/components/shell/QrScanner.tsx
+++ b/components/shell/QrScanner.tsx
@@ -1,6 +1,12 @@
 import React from "react";
 import { Linking, Pressable, StyleSheet, Text, View } from "react-native";
-import { CameraView, useCameraPermissions, type BarcodeScanningResult } from "expo-camera";
+import {
+  CameraView,
+  useCameraPermissions,
+  type BarcodeScanningResult,
+  type BarcodeType,
+  type PermissionStatus,
+} from "expo-camera";
 import { SafeAreaView } from "react-native-safe-area-context";
 import { useTranslation } from "react-i18next";
 import { Flashlight, FlashlightOff, X } from "lucide-react-native";
@@ -27,8 +33,19 @@ export interface QrScannerProps<T> {
   note?: string;
   /** A way to finish without the camera, e.g. "Enter address manually". */
   manualAction?: { label: string; onPress: () => void };
+  /** Code formats the camera reads; defaults to QR codes only. */
+  barcodeTypes?: BarcodeType[];
+  /**
+   * The permission panel's copy when the default (which speaks of the QR code
+   * and of entering the address) does not fit the caller.
+   */
+  permissionText?: { body: string; blocked: string };
+  /** Told the camera permission's status each time it is read or changes. */
+  onPermissionStatus?: (status: PermissionStatus) => void;
 }
 
+const QR_ONLY: BarcodeType[] = ["qr"];
+
 const WHITE = "#ffffff";
 
 /**
@@ -48,6 +65,9 @@ export function QrScanner<T>({
   hint,
   note,
   manualAction,
+  barcodeTypes = QR_ONLY,
+  permissionText,
+  onPermissionStatus,
 }: QrScannerProps<T>) {
   const { t } = useTranslation();
   const [permission, requestPermission] = useCameraPermissions();
@@ -68,6 +88,11 @@ export function QrScanner<T>({
     void requestPermission();
   }, [permission, requestPermission]);
 
+  const status = permission?.status;
+  React.useEffect(() => {
+    if (status) onPermissionStatus?.(status);
+  }, [status, onPermissionStatus]);
+
   React.useEffect(
     () => () => {
       if (rejectTimer.current) clearTimeout(rejectTimer.current);
@@ -135,7 +160,9 @@ export function QrScanner<T>({
               {t("scanner.permission.title")}
             </Text>
             <Text className="text-center text-base text-white/80">
-              {t(blocked ? "scanner.permission.blocked" : "scanner.permission.body")}
+              {permissionText
+                ? permissionText[blocked ? "blocked" : "body"]
+                : t(blocked ? "scanner.permission.blocked" : "scanner.permission.body")}
             </Text>
             {blocked ? (
               <Button testID="qr-scanner-settings" onPress={() => void Linking.openSettings()}>
@@ -160,7 +187,7 @@ export function QrScanner<T>({
         style={StyleSheet.absoluteFill}
         facing="back"
         enableTorch={torch}
-        barcodeScannerSettings={{ barcodeTypes: ["qr"] }}
+        barcodeScannerSettings={{ barcodeTypes }}
         onBarcodeScanned={done ? undefined : handleScanned}
       />
       <SafeAreaView className="flex-1" pointerEvents="box-none">
diff --git a/lib/shell/bridge/handler.ts b/lib/shell/bridge/handler.ts
index 174bf2e..716886b 100644
--- a/lib/shell/bridge/handler.ts
+++ b/lib/shell/bridge/handler.ts
@@ -8,12 +8,14 @@
 import { originOf, safeConsoleRoute } from "../console-url";
 import {
   HAPTIC_KINDS,
+  SCAN_FORMATS,
   parseInbound,
   type BridgeErrorCode,
   type BridgeEventName,
   type BridgeResult,
   type HapticKind,
   type PushTokenResult,
+  type ScanFormat,
 } from "./protocol";
 
 export interface BridgeDeps {
@@ -26,11 +28,37 @@ export interface BridgeDeps {
   navigate: (route: string) => void;
   /** Forget the server and return to the server picker. */
   resetServer: () => Promise<void>;
+  /**
+   * Open the native scanner for `formats` (never empty). Resolves the decoded
+   * text, or `null` when the user cancels; rejects when the scan cannot run
+   * (camera permission refused, another scan already open).
+   */
+  scan: (formats: readonly ScanFormat[]) => Promise<string | null>;
   onEvent?: (name: BridgeEventName, payload: unknown) => void;
 }
 
 const EXTERNAL_SCHEMES = /^(https?|mailto|tel|sms):/i;
 
+const SCAN_ARGS_MESSAGE = `scan takes { formats?: string[] } with formats from ${SCAN_FORMATS.join(", ")}`;
+
+/**
+ * The formats a `scan` call asks for: every format when it names none, `null`
+ * when the arguments are not `{ formats?: ScanFormat[] }` with at least one
+ * format. Unknown keys are refused rather than ignored.
+ */
+function scanFormatsOf(args: unknown): readonly ScanFormat[] | null {
+  if (args === undefined || args === null) return SCAN_FORMATS;
+  if (typeof args !== "object" || Array.isArray(args)) return null;
+  const keys = Object.keys(args);
+  if (keys.some((key) => key !== "formats")) return null;
+  const formats = (args as { formats?: unknown }).formats;
+  if (formats === undefined) return SCAN_FORMATS;
+  if (!Array.isArray(formats) || formats.length === 0) return null;
+  const known = SCAN_FORMATS as readonly unknown[];
+  if (!formats.every((f) => known.includes(f))) return null;
+  return SCAN_FORMATS.filter((f) => formats.includes(f));
+}
+
 function fail(id: string, code: BridgeErrorCode, message: string): BridgeResult {
   return { id, ok: false, error: { code, message } };
 }
@@ -106,6 +134,12 @@ export function createBridgeHandler(deps: BridgeDeps): BridgeMessageHandler {
           await deps.resetServer();
           return { id, ok: true, value: null };
 
+        case "scan": {
+          const formats = scanFormatsOf(args);
+          if (formats === null) return fail(id, "bad_args", SCAN_ARGS_MESSAGE);
+          return { id, ok: true, value: await deps.scan(formats) };
+        }
+
         default:
           return fail(id, "unknown_method", `Unknown bridge method: ${method}`);
       }
diff --git a/lib/shell/bridge/protocol.ts b/lib/shell/bridge/protocol.ts
index 1253d81..653768e 100644
--- a/lib/shell/bridge/protocol.ts
+++ b/lib/shell/bridge/protocol.ts
@@ -59,9 +59,31 @@ export const BRIDGE_METHODS = [
   "openExternal",
   "navigate",
   "resetServer",
+  "scan",
 ] as const;
 export type BridgeMethod = (typeof BRIDGE_METHODS)[number];
 
+/**
+ * Code formats `scan()` reads, named as `expo-camera`'s `BarcodeType`. A call
+ * may narrow the set with `formats`; without it the scanner reads all of them.
+ */
+export const SCAN_FORMATS = [
+  "qr",
+  "aztec",
+  "datamatrix",
+  "pdf417",
+  "ean13",
+  "ean8",
+  "upc_a",
+  "upc_e",
+  "code39",
+  "code93",
+  "code128",
+  "codabar",
+  "itf14",
+] as const;
+export type ScanFormat = (typeof SCAN_FORMATS)[number];
+
 /** Everything the shell announces in `capabilities`: its methods and its events. */
 export const BRIDGE_CAPABILITIES: readonly string[] = [...BRIDGE_METHODS, ...SHELL_EVENTS];
 
diff --git a/lib/shell/bridge/scan-session.ts b/lib/shell/bridge/scan-session.ts
new file mode 100644
index 0000000..76e7ad4
--- /dev/null
+++ b/lib/shell/bridge/scan-session.ts
@@ -0,0 +1,76 @@
+/**
+ * The open `scan()` call, between the bridge and the scanner screen
+ * (`app/bridge-scan.tsx`).
+ *
+ * One scan at a time: a second `scan()` while one is open is refused and the
+ * open one is left alone, so a double tap in the Console cannot close the
+ * scanner under the user. The screen reads the formats from here, never from
+ * its URL, and closes itself when there is no scan for it (a link that opens
+ * the route directly).
+ */
+import type { ScanFormat } from "./protocol";
+
+export type ScanOutcome =
+  | { kind: "result"; text: string }
+  | { kind: "cancel" }
+  | { kind: "denied" };
+
+export const SCAN_BUSY_MESSAGE = "A scan is already open";
+export const SCAN_DENIED_MESSAGE = "Camera permission denied";
+
+interface OpenScan {
+  token: number;
+  formats: readonly ScanFormat[];
+  settle: (outcome: ScanOutcome) => void;
+}
+
+let open: OpenScan | null = null;
+let nextToken = 1;
+
+/**
+ * Start a scan for `formats` and show the scanner with `show`. Resolves the
+ * decoded text, or `null` on cancel; rejects with {@link SCAN_DENIED_MESSAGE}
+ * when the camera permission is refused, with {@link SCAN_BUSY_MESSAGE} when a
+ * scan is already open, and with `show`'s error when the screen cannot open.
+ */
+export function requestScan(
+  formats: readonly ScanFormat[],
+  show: () => void
+): Promise<string | null> {
+  if (open) return Promise.reject(new Error(SCAN_BUSY_MESSAGE));
+  return new Promise<string | null>((resolve, reject) => {
+    const token = nextToken++;
+    open = {
+      token,
+      formats,
+      settle: (outcome) => {
+        if (outcome.kind === "result") resolve(outcome.text);
+        else if (outcome.kind === "denied") reject(new Error(SCAN_DENIED_MESSAGE));
+        else resolve(null);
+      },
+    };
+    try {
+      show();
+    } catch (err) {
+      open = null;
+      reject(err);
+    }
+  });
+}
+
+/** The scan the screen should serve, or `null` when none is open. */
+export function currentScan(): { token: number; formats: readonly ScanFormat[] } | null {
+  return open ? { token: open.token, formats: open.formats } : null;
+}
+
+/**
+ * Settle the scan `token` names. Returns `false`, changing nothing, when that
+ * scan is no longer the open one — it was already settled.
+ */
+export function settleScan(token: number, outcome: ScanOutcome): boolean {
+  if (!open || open.token !== token) return false;
+  const { settle } = open;
+  open = null;
+  settle(outcome);
+  return true;
+}
diff --git a/lib/shell/bridge/scripts.ts b/lib/shell/bridge/scripts.ts
index c429662..41f7526 100644
--- a/lib/shell/bridge/scripts.ts
+++ b/lib/shell/bridge/scripts.ts
@@ -48,13 +48,17 @@ export function buildBootstrapScript(info: BridgeHostInfo, serverUrl: string): s
   var installId = onServer ? ${toScriptLiteral(gatedInstallId)} : null;
   var pending = {};
   var seq = 0;
+  // Call ids carry a token of this document. An answer the shell sends after
+  // the page was replaced (a reload, a re-created WebView, a sign-in redirect)
+  // then matches no call of the new document, which numbers its calls afresh.
+  var doc = Math.floor(Math.random() * 2176782336).toString(36) + Date.now().toString(36);
   function post(msg) {
     if (window.ReactNativeWebView) window.ReactNativeWebView.postMessage(JSON.stringify(msg));
   }
   function call(method, args) {
     return new Promise(function (resolve, reject) {
       seq += 1;
-      var id = "c" + seq;
+      var id = doc + "." + seq;
       pending[id] = { resolve: resolve, reject: reject };
       post({ type: "call", id: id, method: method, args: args });
     });
@@ -72,6 +76,7 @@ export function buildBootstrapScript(info: BridgeHostInfo, serverUrl: string): s
     openExternal: function (url) { return call("openExternal", { url: url }); },
     navigate: function (route) { return call("navigate", { route: route }); },
     resetServer: function () { return call("resetServer"); },
+    scan: function (opts) { return call("scan", opts); },
     ready: function () { post({ type: "event", name: "ready" }); },
     routeChanged: function (route) { post({ type: "event", name: "routeChanged", payload: { route: route } }); }
   };
diff --git a/locales/ar.json b/locales/ar.json
index 145a897..8de10c3 100644
--- a/locales/ar.json
+++ b/locales/ar.json
@@ -60,9 +60,11 @@
   },
   "scanner": {
     "hint": "ضع رمز QR داخل الإطار",
+    "codeHint": "ضع الرمز داخل الإطار",
     "connectNote": "يحتوي على عنوان الخادم فقط، ولا يتضمن أي معلومات حساب",
     "manual": "إدخال العنوان يدويًا",
     "notConnectCode": "هذا ليس رمز QR للاتصال",
+    "unreadable": "تعذّرت قراءة هذا الرمز",
     "close": "إغلاق",
     "torchOn": "تشغيل المصباح",
     "torchOff": "إيقاف المصباح",
@@ -71,10 +73,12 @@
       "body": "اسمح بالوصول إلى الكاميرا لمسح رمز QR.",
       "blocked": "الوصول إلى الكاميرا متوقف لتطبيق ObjectOS. فعّله من الإعدادات، أو أدخل العنوان يدويًا.",
       "allow": "السماح بالكاميرا",
-      "settings": "فتح الإعدادات"
+      "settings": "فتح الإعدادات",
+      "codeBody": "اسمح بالوصول إلى الكاميرا لمسح الرمز.",
+      "codeBlocked": "الوصول إلى الكاميرا متوقف لتطبيق ObjectOS. فعّله من الإعدادات لمسح الرموز."
     }
   },
   "permissions": {
-    "camera": "يستخدم ObjectOS الكاميرا لمسح رمز QR الذي يربطه بالخادم الخاص بك."
+    "camera": "يستخدم ObjectOS الكاميرا لمسح رموز QR والرموز الشريطية، مثل الرمز الذي يربطه بالخادم الخاص بك."
   }
 }
diff --git a/locales/en.json b/locales/en.json
index 02f2930..b2e2546 100644
--- a/locales/en.json
+++ b/locales/en.json
@@ -60,9 +60,11 @@
   },
   "scanner": {
     "hint": "Place the QR code inside the frame",
+    "codeHint": "Place the code inside the frame",
     "connectNote": "Contains only the server address, no account information",
     "manual": "Enter address manually",
     "notConnectCode": "This isn't a connect QR code",
+    "unreadable": "This code can't be read",
     "close": "Close",
     "torchOn": "Turn on flashlight",
     "torchOff": "Turn off flashlight",
@@ -71,10 +73,12 @@
       "body": "Allow camera access to scan the QR code.",
       "blocked": "Camera access is off for ObjectOS. Turn it on in Settings, or enter the address manually.",
       "allow": "Allow camera",
-      "settings": "Open Settings"
+      "settings": "Open Settings",
+      "codeBody": "Allow camera access to scan the code.",
+      "codeBlocked": "Camera access is off for ObjectOS. Turn it on in Settings to scan codes."
     }
   },
   "permissions": {
-    "camera": "ObjectOS uses the camera to scan the QR code that connects it to your server."
+    "camera": "ObjectOS uses the camera to scan QR codes and barcodes, such as the code that connects it to your server."
   }
 }
diff --git a/locales/zh.json b/locales/zh.json
index 04bf8a2..4c2ac6d 100644
--- a/locales/zh.json
+++ b/locales/zh.json
@@ -60,9 +60,11 @@
   },
   "scanner": {
     "hint": "将二维码放入框内",
+    "codeHint": "将条码或二维码放入框内",
     "connectNote": "只包含服务器地址，不含任何账号信息",
     "manual": "手动输入地址",
     "notConnectCode": "不是连接二维码",
+    "unreadable": "无法读取此码",
     "close": "关闭",
     "torchOn": "打开手电筒",
     "torchOff": "关闭手电筒",
@@ -71,10 +73,12 @@
       "body": "允许使用相机以扫描二维码。",
       "blocked": "ObjectOS 的相机权限已关闭。请在设置中开启，或手动输入地址。",
       "allow": "允许使用相机",
-      "settings": "打开设置"
+      "settings": "打开设置",
+      "codeBody": "允许使用相机以扫描条码或二维码。",
+      "codeBlocked": "ObjectOS 的相机权限已关闭。请在设置中开启后再扫描。"
     }
   },
   "permissions": {
-    "camera": "ObjectOS 使用相机扫描二维码，以连接到你的服务器。"
+    "camera": "ObjectOS 使用相机扫描二维码和条码，例如用于连接服务器的二维码。"
   }
 }

From 75a7da991d88ff25bd3cd4f764e86f614f690cb3 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 2 Nov 2026 13:16:16 +0000
Subject: [PATCH 2/4] =?UTF-8?q?feat(bridge):=20scan()=20=E2=80=94=20docume?=
 =?UTF-8?q?nt-scoped=20answers,=20tests,=20ten=20locales,=20RTL=20scanner?=
 =?UTF-8?q?=20root?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Claude-Session: https://claude.ai/code/session_01QSeKYnW1Xf6HDSWz1eGAqv
Co-authored-by: Claude <noreply@anthropic.com>
---
 __tests__/components/ConsoleWebView.test.tsx |  56 ++++++
 __tests__/components/QrScanner.test.tsx      | 178 ++++++++++++++++++-
 __tests__/lib/shell/bridge-protocol.test.ts  |   9 +
 __tests__/lib/shell/scan-session.test.ts     |  82 +++++++++
 components/shell/QrScanner.tsx               |   8 +-
 locales/de.json                              |   8 +-
 locales/es.json                              |   8 +-
 locales/fr.json                              |   8 +-
 locales/ja.json                              |   8 +-
 locales/ko.json                              |   8 +-
 locales/pt.json                              |   8 +-
 locales/ru.json                              |   8 +-
 12 files changed, 370 insertions(+), 19 deletions(-)
 create mode 100644 __tests__/lib/shell/scan-session.test.ts

diff --git a/__tests__/components/ConsoleWebView.test.tsx b/__tests__/components/ConsoleWebView.test.tsx
index 8b2c687..a42da5a 100644
--- a/__tests__/components/ConsoleWebView.test.tsx
+++ b/__tests__/components/ConsoleWebView.test.tsx
@@ -71,6 +71,7 @@ function renderConsole(overrides: Partial<ConsoleWebViewProps> = {}) {
       haptic: jest.fn(),
       openExternal: jest.fn().mockResolvedValue(undefined),
       resetServer: jest.fn().mockResolvedValue(undefined),
+      scan: jest.fn().mockResolvedValue(null),
     },
     onOpenNative: jest.fn(),
     onOpenExternal: jest.fn(),
@@ -271,6 +272,60 @@ describe("ConsoleWebView", () => {
     );
   });
 
+  describe("an answer whose document is gone", () => {
+    /** A `scan()` from the loaded page, left open until the test settles it. */
+    function openScan() {
+      let settle: (text: string | null) => void = () => {};
+      const scan = jest.fn(
+        () => new Promise<string | null>((resolve) => (settle = resolve))
+      );
+      renderConsole({
+        capabilities: {
+          getPushToken: jest.fn().mockResolvedValue(null),
+          haptic: jest.fn(),
+          openExternal: jest.fn().mockResolvedValue(undefined),
+          resetServer: jest.fn().mockResolvedValue(undefined),
+          scan,
+        },
+      });
+      act(() => mockWebView.props.onLoadStart());
+      finishLoad();
+      act(() => {
+        mockWebView.props.onMessage({
+          nativeEvent: {
+            data: JSON.stringify({ type: "call", id: "d1.1", method: "scan" }),
+            url: `${SERVER}/_console/apps/crm`,
+          },
+        });
+      });
+      expect(scan).toHaveBeenCalledTimes(1);
+      return (text: string | null) => act(async () => settle(text));
+    }
+
+    it("is injected into the page that asked while that page is still there", async () => {
+      const settle = openScan();
+      await settle("4006381333931");
+      expect(mockWebView.injectJavaScript).toHaveBeenCalledWith(
+        expect.stringContaining('"id":"d1.1","ok":true,"value":"4006381333931"')
+      );
+    });
+
+    it("is dropped when a new document started meanwhile (a reload, a redirect)", async () => {
+      const settle = openScan();
+      act(() => mockWebView.props.onLoadStart());
+      await settle("4006381333931");
+      expect(mockWebView.injectJavaScript).not.toHaveBeenCalled();
+    });
+
+    it("is dropped when the WebView was re-created meanwhile", async () => {
+      const settle = openScan();
+      act(() => mockWebView.props.onRenderProcessGone());
+      expect(mockWebView.mounts).toBe(2);
+      await settle("4006381333931");
+      expect(mockWebView.injectJavaScript).not.toHaveBeenCalled();
+    });
+  });
+
   it("injects nothing in answer to a page from another origin", async () => {
     renderConsole();
     await act(async () => {
@@ -378,6 +433,7 @@ describe("ConsoleWebView", () => {
         haptic: jest.fn(),
         openExternal: jest.fn(),
         resetServer: jest.fn(),
+        scan: jest.fn(),
       },
       onOpenNative: jest.fn(),
       onOpenExternal: jest.fn(),
diff --git a/__tests__/components/QrScanner.test.tsx b/__tests__/components/QrScanner.test.tsx
index 2cfbb1d..8184c2b 100644
--- a/__tests__/components/QrScanner.test.tsx
+++ b/__tests__/components/QrScanner.test.tsx
@@ -1,9 +1,9 @@
 import React from "react";
-import { Linking } from "react-native";
+import { Linking, StyleSheet } from "react-native";
 import { act, fireEvent, render, screen } from "@testing-library/react-native";
 // Types for the matchers jest.config registers through setupFilesAfterEnv.
 import type {} from "@testing-library/react-native/extend-expect";
-import "~/lib/i18n";
+import i18n from "~/lib/i18n";
 
 interface MockPermission {
   granted: boolean;
@@ -41,12 +41,27 @@ jest.mock("react-native-safe-area-context", () => {
 
 const mockBack = jest.fn();
 const mockDismissTo = jest.fn();
+const mockReplace = jest.fn();
+let mockCanGoBack = true;
 jest.mock("expo-router", () => ({
-  useRouter: () => ({ back: mockBack, dismissTo: mockDismissTo, push: jest.fn() }),
+  useRouter: () => ({
+    back: mockBack,
+    dismissTo: mockDismissTo,
+    push: jest.fn(),
+    replace: mockReplace,
+    canGoBack: () => mockCanGoBack,
+  }),
 }));
 
 import { QrScanner, REJECT_MESSAGE_MS } from "~/components/shell/QrScanner";
 import ConnectScanScreen from "~/app/connect-scan";
+import BridgeScanScreen from "~/app/bridge-scan";
+import {
+  SCAN_DENIED_MESSAGE,
+  currentScan,
+  requestScan,
+  settleScan,
+} from "~/lib/shell/bridge/scan-session";
 
 const GRANTED: MockPermission = { granted: true, canAskAgain: true, status: "granted" };
 const UNDETERMINED: MockPermission = { granted: false, canAskAgain: true, status: "undetermined" };
@@ -95,6 +110,18 @@ beforeEach(() => {
   mockCamera.request.mockReset().mockResolvedValue(GRANTED);
   mockBack.mockReset();
   mockDismissTo.mockReset();
+  mockReplace.mockReset();
+  mockCanGoBack = true;
+});
+
+afterEach(async () => {
+  const open = currentScan();
+  if (open) settleScan(open.token, { kind: "cancel" });
+  if (i18n.language !== "en") {
+    await act(async () => {
+      await i18n.changeLanguage("en");
+    });
+  }
 });
 
 describe("QrScanner — camera allowed", () => {
@@ -188,6 +215,37 @@ describe("QrScanner — camera allowed", () => {
   });
 });
 
+describe("QrScanner — caller options", () => {
+  it("reads the code formats the caller names", () => {
+    renderScanner({ barcodeTypes: ["ean13", "code128"] });
+    expect(mockCamera.props?.barcodeScannerSettings).toEqual({
+      barcodeTypes: ["ean13", "code128"],
+    });
+  });
+
+  it("shows the caller's permission copy, asking and refused for good", () => {
+    const permissionText = { body: "Allow it for codes", blocked: "Off; Settings only" };
+    mockCamera.permission = UNDETERMINED;
+    renderScanner({ permissionText });
+    expect(screen.getByTestId("qr-scanner-permission")).toHaveTextContent("Allow it for codes", {
+      exact: false,
+    });
+    screen.unmount();
+    mockCamera.permission = BLOCKED;
+    renderScanner({ permissionText });
+    expect(screen.getByTestId("qr-scanner-permission")).toHaveTextContent("Off; Settings only", {
+      exact: false,
+    });
+  });
+
+  it("tells the caller the permission status it read", () => {
+    const onPermissionStatus = jest.fn();
+    mockCamera.permission = BLOCKED;
+    renderScanner({ onPermissionStatus });
+    expect(onPermissionStatus).toHaveBeenLastCalledWith("denied");
+  });
+});
+
 describe("QrScanner — camera permission", () => {
   it("shows no camera while the permission is still being read", () => {
     mockCamera.permission = null;
@@ -274,3 +332,117 @@ describe("ConnectScanScreen (screen 6)", () => {
     expect(mockBack).toHaveBeenCalledTimes(2);
   });
 });
+
+describe("BridgeScanScreen (bridge scan())", () => {
+  /** Open a scan through the session, as the Console screen's capability does. */
+  function openScan(formats: Parameters<typeof requestScan>[0] = ["ean13", "qr"]) {
+    const answer = requestScan(formats, () => {});
+    render(<BridgeScanScreen />);
+    return answer;
+  }
+
+  it("reads the formats of the open scan, with the code copy and no manual way out", () => {
+    void openScan(["ean13", "code128"]);
+    expect(mockCamera.props?.barcodeScannerSettings).toEqual({
+      barcodeTypes: ["ean13", "code128"],
+    });
+    expect(screen.getByTestId("qr-scanner-hint")).toHaveTextContent(
+      "Place the code inside the frame"
+    );
+    expect(screen.queryByTestId("qr-scanner-manual")).toBeNull();
+    expect(screen.getByTestId("qr-scanner-torch")).toBeTruthy();
+  });
+
+  it("resolves the first code read, once, and closes", async () => {
+    const answer = openScan();
+    scan("4006381333931");
+    scan("other");
+    await expect(answer).resolves.toBe("4006381333931");
+    expect(mockBack).toHaveBeenCalledTimes(1);
+    expect(currentScan()).toBeNull();
+  });
+
+  it("resolves null when closed", async () => {
+    const answer = openScan();
+    fireEvent.press(screen.getByTestId("qr-scanner-close"));
+    await expect(answer).resolves.toBeNull();
+    expect(mockBack).toHaveBeenCalledTimes(1);
+  });
+
+  it("resolves null when left another way (Android back, the iOS swipe)", async () => {
+    const answer = requestScan(["qr"], () => {});
+    const view = render(<BridgeScanScreen />);
+    view.unmount();
+    await expect(answer).resolves.toBeNull();
+  });
+
+  it("fails when the camera permission is refused, with the code copy", async () => {
+    mockCamera.permission = BLOCKED;
+    const answer = openScan();
+    expect(screen.getByTestId("qr-scanner-permission")).toHaveTextContent(
+      "Turn it on in Settings to scan codes",
+      { exact: false }
+    );
+    fireEvent.press(screen.getByTestId("qr-scanner-close"));
+    await expect(answer).rejects.toThrow(SCAN_DENIED_MESSAGE);
+  });
+
+  it("fails when left another way after the permission was refused", async () => {
+    mockCamera.permission = BLOCKED;
+    const answer = requestScan(["qr"], () => {});
+    render(<BridgeScanScreen />).unmount();
+    await expect(answer).rejects.toThrow(SCAN_DENIED_MESSAGE);
+  });
+
+  it("resolves null when closed before the permission was answered", async () => {
+    mockCamera.permission = UNDETERMINED;
+    const answer = openScan();
+    fireEvent.press(screen.getByTestId("qr-scanner-close"));
+    await expect(answer).resolves.toBeNull();
+  });
+
+  it("closes at once when opened with no scan for it (a link to the route)", () => {
+    mockCanGoBack = false;
+    render(<BridgeScanScreen />);
+    expect(screen.queryByTestId("qr-scanner-camera")).toBeNull();
+    expect(mockReplace).toHaveBeenCalledWith("/");
+  });
+});
+
+describe("scanner layout direction", () => {
+  /** The direction on the outermost host view the screen renders. */
+  function rootDirection(): unknown {
+    const tree = screen.toJSON();
+    const root = Array.isArray(tree) ? tree[0] : tree;
+    return StyleSheet.flatten(root?.props.style)?.direction;
+  }
+
+  it.each([
+    ["the camera", GRANTED],
+    ["the permission panel", BLOCKED],
+  ])("lays out %s right-to-left under ar and left-to-right under en", async (_label, permission) => {
+    mockCamera.permission = permission;
+    renderScanner();
+    expect(rootDirection()).toBe("ltr");
+    await act(async () => {
+      await i18n.changeLanguage("ar");
+    });
+    expect(rootDirection()).toBe("rtl");
+    expect(screen.getByTestId("qr-scanner-close").props.accessibilityLabel).toBe("إغلاق");
+  });
+
+  it("sets it on the connect scan and the bridge scan screen roots, in Arabic", async () => {
+    await act(async () => {
+      await i18n.changeLanguage("ar");
+    });
+    render(<ConnectScanScreen />);
+    expect(rootDirection()).toBe("rtl");
+    expect(screen.getByTestId("qr-scanner-manual")).toHaveTextContent("إدخال العنوان يدويًا");
+    screen.unmount();
+
+    void requestScan(["qr"], () => {});
+    render(<BridgeScanScreen />);
+    expect(rootDirection()).toBe("rtl");
+    expect(screen.getByTestId("qr-scanner-hint")).toHaveTextContent("ضع الرمز داخل الإطار");
+  });
+});
diff --git a/__tests__/lib/shell/bridge-protocol.test.ts b/__tests__/lib/shell/bridge-protocol.test.ts
index d5701a4..c66ce83 100644
--- a/__tests__/lib/shell/bridge-protocol.test.ts
+++ b/__tests__/lib/shell/bridge-protocol.test.ts
@@ -2,11 +2,13 @@ import {
   BRIDGE_CAPABILITIES,
   BRIDGE_METHODS,
   MAX_MESSAGE_LENGTH,
+  SCAN_FORMATS,
   PUSH_TOKEN_CHANGED_EVENT,
   SHELL_EVENTS,
   parseInbound,
   shellEventType,
 } from "~/lib/shell/bridge/protocol";
+import type { BarcodeType } from "expo-camera";
 
 describe("capabilities", () => {
   it("announces every method and every shell event", () => {
@@ -14,6 +16,13 @@ describe("capabilities", () => {
     expect(BRIDGE_CAPABILITIES).toContain("pushTokenChanged");
   });
 
+  it("announces scan, with formats named as the camera names them", () => {
+    expect(BRIDGE_CAPABILITIES).toContain("scan");
+    // Compile-time: every scan format is a format expo-camera reads.
+    const readable: readonly BarcodeType[] = SCAN_FORMATS;
+    expect(new Set(readable).size).toBe(SCAN_FORMATS.length);
+  });
+
   it("names a shell event's DOM type after its capability", () => {
     expect(shellEventType("pushTokenChanged")).toBe(PUSH_TOKEN_CHANGED_EVENT);
     expect(PUSH_TOKEN_CHANGED_EVENT).toBe("objectstack-native:pushTokenChanged");
diff --git a/__tests__/lib/shell/scan-session.test.ts b/__tests__/lib/shell/scan-session.test.ts
new file mode 100644
index 0000000..eda81ab
--- /dev/null
+++ b/__tests__/lib/shell/scan-session.test.ts
@@ -0,0 +1,82 @@
+import {
+  SCAN_BUSY_MESSAGE,
+  SCAN_DENIED_MESSAGE,
+  currentScan,
+  requestScan,
+  settleScan,
+} from "~/lib/shell/bridge/scan-session";
+
+/** Settle whatever scan is open; fails the test when none is. */
+function settleOpen(outcome: Parameters<typeof settleScan>[1]) {
+  const open = currentScan();
+  if (!open) throw new Error("no scan open");
+  expect(settleScan(open.token, outcome)).toBe(true);
+}
+
+afterEach(() => {
+  const open = currentScan();
+  if (open) settleScan(open.token, { kind: "cancel" });
+});
+
+describe("scan session", () => {
+  it("shows the scanner with the formats asked for, and resolves the decoded text", async () => {
+    const show = jest.fn(() => {
+      expect(currentScan()?.formats).toEqual(["ean13"]);
+    });
+    const scan = requestScan(["ean13"], show);
+    expect(show).toHaveBeenCalledTimes(1);
+    settleOpen({ kind: "result", text: "4006381333931" });
+    await expect(scan).resolves.toBe("4006381333931");
+    expect(currentScan()).toBeNull();
+  });
+
+  it("resolves null on cancel", async () => {
+    const scan = requestScan(["qr"], jest.fn());
+    settleOpen({ kind: "cancel" });
+    await expect(scan).resolves.toBeNull();
+  });
+
+  it("rejects when the camera permission is denied", async () => {
+    const scan = requestScan(["qr"], jest.fn());
+    settleOpen({ kind: "denied" });
+    await expect(scan).rejects.toThrow(SCAN_DENIED_MESSAGE);
+  });
+
+  it("refuses a second scan while one is open, without showing it or touching the first", async () => {
+    const show = jest.fn();
+    const first = requestScan(["qr"], show);
+    const token = currentScan()?.token;
+    await expect(requestScan(["ean13"], show)).rejects.toThrow(SCAN_BUSY_MESSAGE);
+    expect(show).toHaveBeenCalledTimes(1);
+    expect(currentScan()).toEqual({ token, formats: ["qr"] });
+    settleOpen({ kind: "result", text: "first" });
+    await expect(first).resolves.toBe("first");
+  });
+
+  it("settles once: a second settle of the same scan changes nothing", async () => {
+    const scan = requestScan(["qr"], jest.fn());
+    const token = currentScan()!.token;
+    expect(settleScan(token, { kind: "result", text: "a" })).toBe(true);
+    expect(settleScan(token, { kind: "cancel" })).toBe(false);
+    await expect(scan).resolves.toBe("a");
+  });
+
+  it("ignores a settle for a scan that is no longer the open one", async () => {
+    const old = requestScan(["qr"], jest.fn());
+    const oldToken = currentScan()!.token;
+    settleScan(oldToken, { kind: "cancel" });
+    await old;
+    const next = requestScan(["qr"], jest.fn());
+    expect(settleScan(oldToken, { kind: "result", text: "stale" })).toBe(false);
+    settleOpen({ kind: "result", text: "fresh" });
+    await expect(next).resolves.toBe("fresh");
+  });
+
+  it("rejects, and leaves nothing open, when the scanner cannot be shown", async () => {
+    const scan = requestScan(["qr"], () => {
+      throw new Error("no navigator");
+    });
+    await expect(scan).rejects.toThrow("no navigator");
+    expect(currentScan()).toBeNull();
+  });
+});
diff --git a/components/shell/QrScanner.tsx b/components/shell/QrScanner.tsx
index 97ea001..d48f693 100644
--- a/components/shell/QrScanner.tsx
+++ b/components/shell/QrScanner.tsx
@@ -11,6 +11,7 @@ import { SafeAreaView } from "react-native-safe-area-context";
 import { useTranslation } from "react-i18next";
 import { Flashlight, FlashlightOff, X } from "lucide-react-native";
 import { Button } from "~/components/ui/Button";
+import { useLayoutDirection } from "~/lib/rtl";
 
 /** How long "not a … code" stays up after a refused code leaves the frame. */
 export const REJECT_MESSAGE_MS = 3000;
@@ -70,6 +71,9 @@ export function QrScanner<T>({
   onPermissionStatus,
 }: QrScannerProps<T>) {
   const { t } = useTranslation();
+  // On the screen root, as every native screen does: right-to-left under `ar`
+  // without relying on the app root's direction reaching a pushed screen.
+  const direction = useLayoutDirection();
   const [permission, requestPermission] = useCameraPermissions();
   const [torch, setTorch] = React.useState(false);
   const [rejected, setRejected] = React.useState(false);
@@ -152,7 +156,7 @@ export function QrScanner<T>({
   if (!permission || !permission.granted) {
     const blocked = !!permission && !permission.canAskAgain;
     return (
-      <SafeAreaView className="flex-1 bg-black">
+      <SafeAreaView className="flex-1 bg-black" style={{ direction }}>
         <View className="flex-row px-4 pt-2">{closeButton}</View>
         {permission ? (
           <View testID="qr-scanner-permission" className="flex-1 justify-center gap-4 px-8">
@@ -181,7 +185,7 @@ export function QrScanner<T>({
   }
 
   return (
-    <View className="flex-1 bg-black">
+    <View className="flex-1 bg-black" style={{ direction }}>
       <CameraView
         testID="qr-scanner-camera"
         style={StyleSheet.absoluteFill}
diff --git a/locales/de.json b/locales/de.json
index de97090..2ea2cea 100644
--- a/locales/de.json
+++ b/locales/de.json
@@ -60,9 +60,11 @@
   },
   "scanner": {
     "hint": "Halten Sie den QR-Code in den Rahmen",
+    "codeHint": "Halten Sie den Code in den Rahmen",
     "connectNote": "Enthält nur die Serveradresse, keine Kontodaten",
     "manual": "Adresse manuell eingeben",
     "notConnectCode": "Das ist kein Verbindungs-QR-Code",
+    "unreadable": "Dieser Code kann nicht gelesen werden",
     "close": "Schließen",
     "torchOn": "Taschenlampe einschalten",
     "torchOff": "Taschenlampe ausschalten",
@@ -71,10 +73,12 @@
       "body": "Erlauben Sie den Kamerazugriff, um den QR-Code zu scannen.",
       "blocked": "Der Kamerazugriff für ObjectOS ist deaktiviert. Aktivieren Sie ihn in den Einstellungen oder geben Sie die Adresse manuell ein.",
       "allow": "Kamera erlauben",
-      "settings": "Einstellungen öffnen"
+      "settings": "Einstellungen öffnen",
+      "codeBody": "Erlauben Sie den Kamerazugriff, um den Code zu scannen.",
+      "codeBlocked": "Der Kamerazugriff für ObjectOS ist deaktiviert. Aktivieren Sie ihn in den Einstellungen, um Codes zu scannen."
     }
   },
   "permissions": {
-    "camera": "ObjectOS verwendet die Kamera, um den QR-Code zu scannen, der die App mit Ihrem Server verbindet."
+    "camera": "ObjectOS verwendet die Kamera, um QR-Codes und Barcodes zu scannen, etwa den Code, der die App mit Ihrem Server verbindet."
   }
 }
diff --git a/locales/es.json b/locales/es.json
index d6e6d6f..5f13e08 100644
--- a/locales/es.json
+++ b/locales/es.json
@@ -60,9 +60,11 @@
   },
   "scanner": {
     "hint": "Coloque el código QR dentro del marco",
+    "codeHint": "Coloque el código dentro del marco",
     "connectNote": "Solo contiene la dirección del servidor, sin datos de la cuenta",
     "manual": "Introducir la dirección manualmente",
     "notConnectCode": "Este no es un código QR de conexión",
+    "unreadable": "No se puede leer este código",
     "close": "Cerrar",
     "torchOn": "Encender la linterna",
     "torchOff": "Apagar la linterna",
@@ -71,10 +73,12 @@
       "body": "Permita el acceso a la cámara para escanear el código QR.",
       "blocked": "El acceso a la cámara está desactivado para ObjectOS. Actívelo en Configuración o introduzca la dirección manualmente.",
       "allow": "Permitir la cámara",
-      "settings": "Abrir Configuración"
+      "settings": "Abrir Configuración",
+      "codeBody": "Permita el acceso a la cámara para escanear el código.",
+      "codeBlocked": "El acceso a la cámara está desactivado para ObjectOS. Actívelo en Configuración para escanear códigos."
     }
   },
   "permissions": {
-    "camera": "ObjectOS usa la cámara para escanear el código QR que lo conecta a su servidor."
+    "camera": "ObjectOS usa la cámara para escanear códigos QR y códigos de barras, como el código que lo conecta a su servidor."
   }
 }
diff --git a/locales/fr.json b/locales/fr.json
index d1650ca..78e03c4 100644
--- a/locales/fr.json
+++ b/locales/fr.json
@@ -60,9 +60,11 @@
   },
   "scanner": {
     "hint": "Placez le code QR dans le cadre",
+    "codeHint": "Placez le code dans le cadre",
     "connectNote": "Contient uniquement l'adresse du serveur, aucune information de compte",
     "manual": "Saisir l'adresse manuellement",
     "notConnectCode": "Ce n'est pas un code QR de connexion",
+    "unreadable": "Impossible de lire ce code",
     "close": "Fermer",
     "torchOn": "Allumer la lampe torche",
     "torchOff": "Éteindre la lampe torche",
@@ -71,10 +73,12 @@
       "body": "Autorisez l'accès à l'appareil photo pour scanner le code QR.",
       "blocked": "L'accès à l'appareil photo est désactivé pour ObjectOS. Activez-le dans les Paramètres ou saisissez l'adresse manuellement.",
       "allow": "Autoriser l'appareil photo",
-      "settings": "Ouvrir les Paramètres"
+      "settings": "Ouvrir les Paramètres",
+      "codeBody": "Autorisez l'accès à l'appareil photo pour scanner le code.",
+      "codeBlocked": "L'accès à l'appareil photo est désactivé pour ObjectOS. Activez-le dans les Paramètres pour scanner des codes."
     }
   },
   "permissions": {
-    "camera": "ObjectOS utilise l'appareil photo pour scanner le code QR qui le connecte à votre serveur."
+    "camera": "ObjectOS utilise l'appareil photo pour scanner des codes QR et des codes-barres, comme le code qui le connecte à votre serveur."
   }
 }
diff --git a/locales/ja.json b/locales/ja.json
index 5d9af6b..43152fd 100644
--- a/locales/ja.json
+++ b/locales/ja.json
@@ -60,9 +60,11 @@
   },
   "scanner": {
     "hint": "QR コードを枠内に合わせてください",
+    "codeHint": "コードを枠内に合わせてください",
     "connectNote": "サーバーのアドレスのみが含まれ、アカウント情報は含まれません",
     "manual": "アドレスを手動で入力",
     "notConnectCode": "接続用の QR コードではありません",
+    "unreadable": "このコードは読み取れません",
     "close": "閉じる",
     "torchOn": "ライトをオン",
     "torchOff": "ライトをオフ",
@@ -71,10 +73,12 @@
       "body": "QR コードをスキャンするには、カメラへのアクセスを許可してください。",
       "blocked": "ObjectOS のカメラへのアクセスがオフになっています。設定でオンにするか、アドレスを手動で入力してください。",
       "allow": "カメラを許可",
-      "settings": "設定を開く"
+      "settings": "設定を開く",
+      "codeBody": "コードをスキャンするには、カメラへのアクセスを許可してください。",
+      "codeBlocked": "ObjectOS のカメラへのアクセスがオフになっています。コードをスキャンするには、設定でオンにしてください。"
     }
   },
   "permissions": {
-    "camera": "ObjectOS は、サーバーに接続するための QR コードをスキャンするためにカメラを使用します。"
+    "camera": "ObjectOS は、QR コードやバーコード（サーバーに接続するための QR コードなど）をスキャンするためにカメラを使用します。"
   }
 }
diff --git a/locales/ko.json b/locales/ko.json
index 6f25506..5367d28 100644
--- a/locales/ko.json
+++ b/locales/ko.json
@@ -60,9 +60,11 @@
   },
   "scanner": {
     "hint": "QR 코드를 프레임 안에 맞춰 주세요",
+    "codeHint": "코드를 프레임 안에 맞춰 주세요",
     "connectNote": "서버 주소만 포함되며 계정 정보는 포함되지 않습니다",
     "manual": "주소 직접 입력",
     "notConnectCode": "연결용 QR 코드가 아닙니다",
+    "unreadable": "이 코드를 읽을 수 없습니다",
     "close": "닫기",
     "torchOn": "손전등 켜기",
     "torchOff": "손전등 끄기",
@@ -71,10 +73,12 @@
       "body": "QR 코드를 스캔하려면 카메라 접근을 허용하세요.",
       "blocked": "ObjectOS의 카메라 접근이 꺼져 있습니다. 설정에서 켜거나 주소를 직접 입력하세요.",
       "allow": "카메라 허용",
-      "settings": "설정 열기"
+      "settings": "설정 열기",
+      "codeBody": "코드를 스캔하려면 카메라 접근을 허용하세요.",
+      "codeBlocked": "ObjectOS의 카메라 접근이 꺼져 있습니다. 코드를 스캔하려면 설정에서 켜세요."
     }
   },
   "permissions": {
-    "camera": "ObjectOS는 서버에 연결하기 위한 QR 코드를 스캔하는 데 카메라를 사용합니다."
+    "camera": "ObjectOS는 QR 코드와 바코드(서버에 연결하기 위한 QR 코드 등)를 스캔하는 데 카메라를 사용합니다."
   }
 }
diff --git a/locales/pt.json b/locales/pt.json
index a3d6ec0..e1b44dd 100644
--- a/locales/pt.json
+++ b/locales/pt.json
@@ -60,9 +60,11 @@
   },
   "scanner": {
     "hint": "Posicione o código QR dentro da moldura",
+    "codeHint": "Posicione o código dentro da moldura",
     "connectNote": "Contém apenas o endereço do servidor, sem dados da conta",
     "manual": "Digitar o endereço manualmente",
     "notConnectCode": "Este não é um código QR de conexão",
+    "unreadable": "Não é possível ler este código",
     "close": "Fechar",
     "torchOn": "Ligar a lanterna",
     "torchOff": "Desligar a lanterna",
@@ -71,10 +73,12 @@
       "body": "Permita o acesso à câmera para escanear o código QR.",
       "blocked": "O acesso à câmera está desativado para o ObjectOS. Ative-o em Configurações ou digite o endereço manualmente.",
       "allow": "Permitir câmera",
-      "settings": "Abrir Configurações"
+      "settings": "Abrir Configurações",
+      "codeBody": "Permita o acesso à câmera para escanear o código.",
+      "codeBlocked": "O acesso à câmera está desativado para o ObjectOS. Ative-o em Configurações para escanear códigos."
     }
   },
   "permissions": {
-    "camera": "O ObjectOS usa a câmera para escanear o código QR que o conecta ao seu servidor."
+    "camera": "O ObjectOS usa a câmera para escanear códigos QR e códigos de barras, como o código que o conecta ao seu servidor."
   }
 }
diff --git a/locales/ru.json b/locales/ru.json
index 4392d9a..e9e4ca0 100644
--- a/locales/ru.json
+++ b/locales/ru.json
@@ -60,9 +60,11 @@
   },
   "scanner": {
     "hint": "Поместите QR-код в рамку",
+    "codeHint": "Поместите код в рамку",
     "connectNote": "Содержит только адрес сервера, без данных учётной записи",
     "manual": "Ввести адрес вручную",
     "notConnectCode": "Это не QR-код для подключения",
+    "unreadable": "Не удаётся прочитать этот код",
     "close": "Закрыть",
     "torchOn": "Включить фонарик",
     "torchOff": "Выключить фонарик",
@@ -71,10 +73,12 @@
       "body": "Разрешите доступ к камере, чтобы отсканировать QR-код.",
       "blocked": "Доступ к камере для ObjectOS отключён. Включите его в настройках или введите адрес вручную.",
       "allow": "Разрешить доступ к камере",
-      "settings": "Открыть настройки"
+      "settings": "Открыть настройки",
+      "codeBody": "Разрешите доступ к камере, чтобы отсканировать код.",
+      "codeBlocked": "Доступ к камере для ObjectOS отключён. Включите его в настройках, чтобы сканировать коды."
     }
   },
   "permissions": {
-    "camera": "ObjectOS использует камеру, чтобы отсканировать QR-код для подключения к вашему серверу."
+    "camera": "ObjectOS использует камеру, чтобы сканировать QR-коды и штрихкоды, например QR-код для подключения к вашему серверу."
   }
 }

From f856d04e6d9e58beb2c576bc6de1844cedf40f92 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 2 Nov 2026 13:17:24 +0000
Subject: [PATCH 3/4] docs(bridge): document scan(); changeset

Claude-Session: https://claude.ai/code/session_01QSeKYnW1Xf6HDSWz1eGAqv
Co-authored-by: Claude <noreply@anthropic.com>
---
 .changeset/146-bridge-scan.md | 29 ++++++++++++++++++++
 docs/HYBRID-SHELL.md          | 50 ++++++++++++++++++++++++++++++++---
 2 files changed, 75 insertions(+), 4 deletions(-)
 create mode 100644 .changeset/146-bridge-scan.md

diff --git a/.changeset/146-bridge-scan.md b/.changeset/146-bridge-scan.md
new file mode 100644
index 0000000..4196944
--- /dev/null
+++ b/.changeset/146-bridge-scan.md
@@ -0,0 +1,29 @@
+---
+"mobile": patch
+---
+
+Clause-②: no
+Metadata-protocol: none
+
+The bridge can scan codes for the Console. `ObjectStackNative.scan(opts?)`,
+announced as the `scan` capability, opens the native full-screen scanner (the
+same one as "connect by QR code", with close and torch) and resolves the
+decoded text, or `null` when the user closes it.
+
+- `formats` narrows what the camera reads, with `expo-camera`'s names (`qr`,
+  `ean13`, `code128`, …); without it every listed format is read. An empty list,
+  an unknown format or any other option is refused as `bad_args`.
+- A refused camera permission fails the call with `failed`
+  ("Camera permission denied"); a second `scan()` while one is open fails with
+  "A scan is already open" and leaves the first alone.
+- Only pages on the configured server's origin can call it, like every method.
+
+Bridge answers now go only to the document that made the call. A call id
+carries a per-document token, and the shell drops an answer whose page was
+replaced while the call was open (a reload, the WebView re-created after a
+failure, a redirect). Before, an answer meant for the old page could settle a
+call of the new one.
+
+The scanner screen lays out right-to-left under Arabic on its own root. The
+camera prompt text now names both uses (connect code, and codes for Console
+fields) in all ten languages.
diff --git a/docs/HYBRID-SHELL.md b/docs/HYBRID-SHELL.md
index 6288c26..c9c6bed 100644
--- a/docs/HYBRID-SHELL.md
+++ b/docs/HYBRID-SHELL.md
@@ -27,6 +27,7 @@ app/
   index.tsx           waits for the stored server, then redirects
   server-config.tsx   native server picker: address step, then confirm step
   connect-scan.tsx    QR scanner for the server address (screen 6)
+  bridge-scan.tsx     scanner for the bridge's `scan()` (Console fields)
   console.tsx         the Console screen (one long-lived WebView)
   +native-intent.tsx  app links → Console routes
 components/shell/
@@ -174,8 +175,9 @@ server's Console and saves nothing.
   configured for the camera only (no microphone, no `RECORD_AUDIO`).
 
 `QrScanner` knows nothing about servers: the caller passes `accept`, the
-refusal text and the optional note and manual action, so the bridge's `scan()`
-for Console fields can reuse it.
+refusal text, the optional note and manual action, and optionally the code
+formats and the permission panel's copy. The bridge's `scan()` for Console
+fields reuses it (see "Scanning codes"). The iOS prompt text names both uses.
 
 Sign-in through an external identity provider: the IdP's host must be listed in
 `EXPO_PUBLIC_TRUSTED_HOSTS`, or the navigation policy opens it in the system
@@ -250,6 +252,7 @@ interface ObjectStackNative {
   openExternal(url: string): Promise<null>; // http(s), mailto, tel, sms
   navigate(route: string): Promise<null>; // Console route; route ownership applies
   resetServer(): Promise<null>; // forget the server, back to the picker
+  scan(opts?: { formats?: string[] }): Promise<string | null>; // see "Scanning codes"
 
   ready(): void; // event: page is interactive (hides the loading cover)
   routeChanged(route: string): void; // event: SPA route changed
@@ -280,6 +283,39 @@ re-registration refreshes the device's row instead of minting a second one.
   only when `window.location.origin` is the configured server's origin; any
   other page reads `null`. Sub-frames never see host info (Known limits).
 
+### Scanning codes
+
+`scan()` opens a native full-screen scanner (`app/bridge-scan.tsx`, the same
+`QrScanner` as screen 6) with close and torch controls. It resolves the decoded
+text of the first code read, or `null` when the user closes the scanner
+(the close control, Android back or the iOS swipe).
+
+- `formats` narrows what the camera reads. The names are `expo-camera`'s:
+  `qr`, `aztec`, `datamatrix`, `pdf417`, `ean13`, `ean8`, `upc_a`, `upc_e`,
+  `code39`, `code93`, `code128`, `codabar`, `itf14` (`SCAN_FORMATS`). Without
+  `formats` it reads all of them. An empty list, an unknown name or any other
+  option is `bad_args`, and no scanner opens.
+- Camera permission refused: the scanner shows its permission panel (with
+  Settings when the refusal is final), and leaving it rejects the call with
+  `failed` ("Camera permission denied"). Closed before the prompt was
+  answered, it resolves `null`.
+- One scan at a time: a `scan()` while another is open rejects with `failed`
+  ("A scan is already open") and leaves the open one alone.
+- The answer goes only to the document that called. If the page is replaced
+  while the scanner is up (a reload, the WebView re-created after a failure,
+  a redirect), the shell drops the answer, and the new page's calls cannot
+  match it either (call ids carry a per-document token). The Console's
+  pending promise went away with the old page.
+- Like every method, only a page on the configured server's origin is
+  answered. The scanner never opens for anything else.
+
+```js
+if (ObjectStackNative.has("scan")) {
+  const text = await ObjectStackNative.scan({ formats: ["ean13", "code128"] });
+  if (text !== null) field.value = text;
+}
+```
+
 ### Shell → Console events
 
 When a notification tap, an app link or a bridge `navigate()` asks for a
@@ -333,7 +369,9 @@ Calls are posted as
 `{ type: 'call', id, method, args }` through
 `window.ReactNativeWebView.postMessage`; the shell answers by calling
 `window.__objectstackNativeResolve({ id, ok, value | error })`. Errors carry a
-`code`: `unknown_method`, `bad_args`, `failed`.
+`code`: `unknown_method`, `bad_args`, `failed`. A call id is a per-document
+token and a counter (`<token>.<n>`), and an answer is injected only while the
+document that made the call is still the one loaded.
 
 Security:
 
@@ -412,7 +450,9 @@ The Console needs, in `@object-ui/mobile`:
   sign-out;
 - listen for `objectstack-native:pushTokenChanged` when
   `has("pushTokenChanged")` and re-register `event.detail` while signed in;
-- register no Service Worker inside the shell (see above).
+- register no Service Worker inside the shell (see above);
+- offer a scan affordance on text and lookup fields when `has("scan")`, and
+  fill the field with what `scan()` resolves (nothing on `null`).
 
 Until then the shell works without it: the loading cover lifts on the WebView's
 own load event and the shell pads the WebView with the safe area itself.
@@ -432,6 +472,8 @@ See [PUSH-NOTIFICATIONS.md](./PUSH-NOTIFICATIONS.md).
   `__tests__/components/RtlLayout.test.tsx`.
 - The scanner and screen 6 — `__tests__/components/QrScanner.test.tsx`, with a
   mocked `expo-camera` (permission states, refused and accepted codes, torch).
+- The bridge's `scan()`: the handler (`bridge-handler.test.ts`), the session
+  (`scan-session.test.ts`) and the scanner screen (`QrScanner.test.tsx`).
 - The bootstrap and navigate scripts are executed against a fake `window` in
   `__tests__/lib/shell/bridge-scripts.test.ts`.
 - `ConsoleWebView` is tested with a mocked `react-native-webview`

From f5f32256c6b2affd6cfe4a61b7ca8b5b09d264b5 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 2 Nov 2026 13:23:27 +0000
Subject: [PATCH 4/4] fix(bridge): count only re-created WebViews for answer
 delivery

Answers go only to the document that made the call: the per-document call
id covers a replaced page, and a re-created WebView is never sent one. An
in-app navigation keeps its open calls.

Claude-Session: https://claude.ai/code/session_01QSeKYnW1Xf6HDSWz1eGAqv
Co-authored-by: Claude <noreply@anthropic.com>
---
 .changeset/146-bridge-scan.md                |  6 +-----
 __tests__/components/ConsoleWebView.test.tsx |  9 +++++++--
 components/shell/ConsoleWebView.tsx          | 10 +++++-----
 docs/HYBRID-SHELL.md                         | 14 +++++++-------
 4 files changed, 20 insertions(+), 19 deletions(-)

diff --git a/.changeset/146-bridge-scan.md b/.changeset/146-bridge-scan.md
index 4196944..4c476dd 100644
--- a/.changeset/146-bridge-scan.md
+++ b/.changeset/146-bridge-scan.md
@@ -18,11 +18,7 @@ decoded text, or `null` when the user closes it.
   "A scan is already open" and leaves the first alone.
 - Only pages on the configured server's origin can call it, like every method.
 
-Bridge answers now go only to the document that made the call. A call id
-carries a per-document token, and the shell drops an answer whose page was
-replaced while the call was open (a reload, the WebView re-created after a
-failure, a redirect). Before, an answer meant for the old page could settle a
-call of the new one.
+Bridge answers now go only to the document that made the call.
 
 The scanner screen lays out right-to-left under Arabic on its own root. The
 camera prompt text now names both uses (connect code, and codes for Console
diff --git a/__tests__/components/ConsoleWebView.test.tsx b/__tests__/components/ConsoleWebView.test.tsx
index a42da5a..b480793 100644
--- a/__tests__/components/ConsoleWebView.test.tsx
+++ b/__tests__/components/ConsoleWebView.test.tsx
@@ -310,11 +310,16 @@ describe("ConsoleWebView", () => {
       );
     });
 
-    it("is dropped when a new document started meanwhile (a reload, a redirect)", async () => {
+    it("still settles the call after a load start in the same WebView (an in-app navigation)", async () => {
+      // Android reports a load start for every SPA history change. A page that
+      // really was replaced cannot match the answer: its call ids carry a
+      // token of their own document (bridge-scripts.test.ts).
       const settle = openScan();
       act(() => mockWebView.props.onLoadStart());
       await settle("4006381333931");
-      expect(mockWebView.injectJavaScript).not.toHaveBeenCalled();
+      expect(mockWebView.injectJavaScript).toHaveBeenCalledWith(
+        expect.stringContaining('"id":"d1.1","ok":true,"value":"4006381333931"')
+      );
     });
 
     it("is dropped when the WebView was re-created meanwhile", async () => {
diff --git a/components/shell/ConsoleWebView.tsx b/components/shell/ConsoleWebView.tsx
index 69422d7..4da0a2a 100644
--- a/components/shell/ConsoleWebView.tsx
+++ b/components/shell/ConsoleWebView.tsx
@@ -114,10 +114,11 @@ export const ConsoleWebView = forwardRef<ConsoleWebViewHandle, ConsoleWebViewPro
     // The last Console route the page was on, so a re-created WebView resumes
     // there instead of at the start route.
     const lastRouteRef = useRef<string | null>(null);
-    // Counts documents: a new one starts on every load start and every
-    // re-created WebView. A call's answer goes only to the document that made
-    // the call. A `scan()` stays open as long as the user takes, and the page
-    // can be replaced meanwhile (a reload, recovery, a sign-in redirect).
+    // Counts WebView instances: a call's answer is never sent to a re-created
+    // WebView. A `scan()` stays open as long as the user takes, and recovery
+    // can re-create the WebView meanwhile. Load starts do not count: Android
+    // reports one for every SPA history change too. A page replaced within the
+    // same WebView is covered by the bootstrap's per-document call ids.
     const documentRef = useRef(0);
 
     const goTo = useCallback(
@@ -268,7 +269,6 @@ export const ConsoleWebView = forwardRef<ConsoleWebViewHandle, ConsoleWebViewPro
       if (held) sendPushToken(held);
     }, [sendPushToken]);
     const onDocumentStart = useCallback(() => {
-      documentRef.current += 1;
       consoleReadyRef.current = false;
     }, []);
 
diff --git a/docs/HYBRID-SHELL.md b/docs/HYBRID-SHELL.md
index c9c6bed..feafdda 100644
--- a/docs/HYBRID-SHELL.md
+++ b/docs/HYBRID-SHELL.md
@@ -301,11 +301,11 @@ text of the first code read, or `null` when the user closes the scanner
   answered, it resolves `null`.
 - One scan at a time: a `scan()` while another is open rejects with `failed`
   ("A scan is already open") and leaves the open one alone.
-- The answer goes only to the document that called. If the page is replaced
-  while the scanner is up (a reload, the WebView re-created after a failure,
-  a redirect), the shell drops the answer, and the new page's calls cannot
-  match it either (call ids carry a per-document token). The Console's
-  pending promise went away with the old page.
+- The answer goes only to the document that called. Call ids carry a
+  per-document token, so a page that replaced it while the scanner was up (a
+  reload, a redirect) cannot match the answer, and a WebView re-created after
+  a failure is not sent it at all. The Console's pending promise went away
+  with the old page.
 - Like every method, only a page on the configured server's origin is
   answered. The scanner never opens for anything else.
 
@@ -370,8 +370,8 @@ Calls are posted as
 `window.ReactNativeWebView.postMessage`; the shell answers by calling
 `window.__objectstackNativeResolve({ id, ok, value | error })`. Errors carry a
 `code`: `unknown_method`, `bad_args`, `failed`. A call id is a per-document
-token and a counter (`<token>.<n>`), and an answer is injected only while the
-document that made the call is still the one loaded.
+token and a counter (`<token>.<n>`), so an answer settles only a call of the
+document that made it.
 
 Security: