@captello/ulc-webview-sdk 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,110 @@
 # Changelog
 
+## 1.2.0
+
+### Minor Changes
+
+- aab3383: New entry `@captello/ulc-webview-sdk/app` for pages that run **inside the Captello mobile
+  app** (the meeting platform, Connexions): the page-side client for the app's `postMessage`
+  channel, which until now every page hand-rolled.
+
+    ```ts
+    import { CaptelloAppHost } from "@captello/ulc-webview-sdk/app";
+
+    const app = new CaptelloAppHost();
+    const token = await app.requestAuthToken();
+    app.notifyReady();
+
+    const people = await app.openScanner(); // one per scanned person; [] on cancel
+    ```
+
+    - **`openScanner()`** opens the app's badge scanner and resolves once the session ends with
+      every person it captured, in scan order — several for a group scan. Each is
+      `{ badgeId, fields }`; a badge with no lookup data still arrives with its `badgeId` and
+      empty `fields` so it can be linked to the attendee. Rejects with `ScannerError` when the
+      app reports a failure. Older app builds that post a single result and no close message
+      are handled transparently.
+    - **`requestAuthToken()`**, **`notifyReady()`**, **`notifyError()`**, **`navigateBack()`**
+      wrap the existing auth and navigation messages; `send()` posts any other `AppRequest`.
+    - **`AppRequestType` / `AppResponseType`** enumerate the channel's wire types (plain objects,
+      SCREAMING_CASE — unlike the capture-webview channel, which uses JSON strings), with
+      `parseAppResponse` and typed `on(type, listener)` subscriptions.
+
+- 4d7cdd7: Adds `attach()` — a global entry point that needs no iframe reference, for hosts replacing a
+  hand-rolled `window.addEventListener("message", …)` dispatcher:
+
+    ```js
+    const webview = CaptelloSdk.attach({ targetOrigin: CAPTURE_PORTAL_WEB_VIEW_BASE });
+    webview.on(CaptelloSdk.OutboundMessageType.FormErrorMessage, (m) => showError(m.data));
+    webview.onTranscribeScannerRequest((request, reply) => transcribe(request, reply));
+    ```
+
+    There is nothing to query from the DOM, no ordering to get right relative to when the iframe is
+    created, and no teardown to remember.
+
+    The first inbound message that clears the origin check **and** parses as a well-formed Captello
+    message identifies the webview; that sender becomes the target for sends and the window every
+    later message is source-matched against, so after the first message this is exactly as strict as
+    passing the iframe. Teardown stays automatic: a removed iframe's window reports `closed`, which is
+    readable cross-origin, so the client notices its form going away and destroys itself.
+
+    `new CaptelloWebview(iframe, …)` is unchanged and remains the better choice when you hold the
+    element and drive the form unprompted from page load — until the form speaks once, `attach()` has
+    no window to post to (sends are buffered by `queueUntilReady` in the meantime).
+
+    Also adds a Playwright browser-test layer (`pnpm e2e`) that drives the built IIFE bundle against a
+    genuinely cross-origin iframe, covering what jsdom cannot: real origin filtering, `event.source`
+    identity, and the `closed`-based teardown.
+
+- bc9baef: Three additions that let an existing hand-rolled `window.addEventListener("message")`
+  integration swap in the SDK without restructuring:
+
+    - **Transcribe handlers now get a reply handle** as their second argument, so a host that
+      can't hand back a promise never has to post a message itself:
+
+        ```js
+        webview.onTranscribeScannerRequest((request, reply) => {
+            transcribeService(
+                request.image_urls,
+                (fields) => reply.resolve({ fields, submissionType: "ocr_transcription" }),
+                () => reply.reject("Transcription failed."),
+            );
+        });
+        ```
+
+        `reply` is a plain `{ resolve, reject, answered }` object that can be passed straight to
+        whatever does the work, keeping that code free of any SDK reference. Returning the fields
+        still works exactly as before; a handler that returns nothing is taken to own the reply and
+        the request stays open until it answers. The first answer wins. Existing single-argument
+        handlers are unaffected.
+
+    - **`resolveTranscribeScannerRequest(request, data)` / `rejectTranscribeScannerRequest(request, error)`** —
+      the same two answers on the client, for when the reply happens outside the handler's
+      scope (a global bus, a module holding only the `request_id`). Both take the request or
+      its bare `request_id`, post immediately (never parked in the ready-queue), and are a
+      silent no-op once the client is destroyed or the iframe is detached.
+    - **The client tears itself down with its iframe.** The frame argument must be a mounted
+      iframe (the caller owns that ordering), and with the new `autoDestroy` option — default
+      `true` — the client calls `destroy()` on itself once that element leaves the document,
+      removing the `message` listener and dropping every subscription. Removal of an ancestor
+      counts, which is the common case: emptying a panel or modal takes the iframe with it.
+      Detection uses `MutationObserver`, so it is inert for a `{ contentWindow }` stand-in or
+      in a non-DOM environment. Pass `autoDestroy: false` to manage the lifetime yourself.
+    - **Every `on*` method now returns a subscription handle** — an object with
+      `unsubscribe()`:
+
+        ```js
+        const sub = webview.on(OutboundMessageType.SubmissionBody, save);
+        sub.unsubscribe();
+        ```
+
+        The handle is also directly callable, so existing `const off = ...; off()` code keeps
+        working unchanged.
+
+    - **`targetOrigin` accepts a full URL**, reduced to its origin via `new URL(value).origin`.
+      Hosts hold a webview base URL or embed URL rather than a bare origin, which never equals
+      `event.origin` — the usual reason a hand-rolled origin check ends up commented out.
+
 ## 1.1.0
 
 ### Minor Changes

package/README.md

@@ -18,6 +18,9 @@ It provides:
    utilities like `submitForm(iframe)` and `waitForFormLoad(iframe)`.
 6. **React adapter** (`@captello/ulc-webview-sdk/react`) — a `useCaptelloWebview` hook that
    manages the client lifecycle and returns an iframe ref plus typed senders.
+7. **App-host client** (`@captello/ulc-webview-sdk/app`) — for pages that run _inside_ the
+   Captello mobile app: `CaptelloAppHost` talks to the app for an auth token, the badge
+   scanner, and navigation.
 
 The core package is framework-agnostic with no runtime dependencies; React is an
 optional peer dependency used only by the `/react` entry point.
@@ -28,6 +31,31 @@ optional peer dependency used only by the `/react` entry point.
 pnpm add @captello/ulc-webview-sdk
 ```
 
+### No bundler? Use the hosted script
+
+The webview deployment also serves the SDK as a plain script — a single IIFE
+bundle exposing everything (core + promise helpers, minus the React adapter)
+on a `CaptelloSdk` global. Because it deploys with the webview, the hosted
+file always matches the protocol of the webview at the same origin.
+
+```html
+<script src="https://capture.captello.com/sdk/v1/captello-sdk.js"></script>
+<script>
+    const { buildEmbedUrl, CaptelloWebview, FormMode } = CaptelloSdk;
+
+    const src = buildEmbedUrl("https://capture.captello.com", {
+        formId: 1234,
+        mode: FormMode.Submit,
+    });
+    // ... point an iframe at `src` and wire up `new CaptelloWebview(iframe, ...)`
+    // exactly as in the quick start below.
+</script>
+```
+
+Use the same origin you embed (`capture.captello.com`, `capture-demo.…`, etc.).
+The `v1` path segment only changes on breaking protocol changes. Teams with a
+bundler should prefer the npm package for types and tree-shaking.
+
 ## Quick start
 
 ```ts
@@ -103,6 +131,89 @@ try {
 }
 ```
 
+### The transcribe button — host-side processing
+
+Hosts that can transcribe scanned badges/cards can put a **Transcribe** button in
+the form's badge element: enable it with `showTranscribeButton: true` in the embed
+URL, and answer the requests with `onTranscribeScannerRequest`. The button renders
+inside the badge/barcode element and only while the submission has no email (once
+an email lands — from the badge lookup or from a transcription — it disappears). When pressed, the form sends a
+`transcribe_scanner_request` carrying the scan's `element_id`, its `image_urls`, and
+the `draft_submission_token` the webview was loaded with; the handler's resolved
+fields are sent back and filled into the form (empty values are skipped, so they
+never blank already-filled inputs). Only enable the button when a handler is
+registered — otherwise it times out with an error for the user.
+
+```ts
+const src = buildEmbedUrl("https://capture.captello.com", {
+    formId: 1234,
+    mode: FormMode.Submit,
+    showTranscribeButton: true, // show_transcribe_button=1
+});
+
+webview.onTranscribeScannerRequest(async ({ image_urls, draft_submission_token }) => {
+    const fields = await transcribeService(image_urls, draft_submission_token);
+    // fields: [{ llFieldId: 16, llFieldIdentifier: "FirstName", value: "Patrick" }, ...]
+    return { fields, submissionType: "ocr_transcription" };
+});
+```
+
+A thrown `Error`'s message is shown to the user by the form, so throw display-ready
+messages. The wire shapes are exported as `TranscribeScannerRequestMessage`,
+`TranscribeScannerResultMessage`, `TranscribeScannerResultData`, and
+`TranscribedScannerField`. Host processing is a convention, not a one-off: future
+operations get their own `*_request` / `*_result` pairs shaped like this one. In
+React, pass the handler as the `onTranscribeScannerRequest` option/prop instead.
+
+#### Answering later, from callback-style code
+
+The handler's second argument is a **reply handle** — call it whenever the work
+finishes. Use it when the transcription can't hand back a promise: a callback-style
+AJAX wrapper, an event bus, a method that returns `void`. Nothing else changes, and the
+host never builds or posts a message itself:
+
+```ts
+webview.onTranscribeScannerRequest((request, reply) => {
+    ll_ajax_manager.send_request(
+        "DraftedSubmissions",
+        "transcribeDraftScannerElement",
+        { draft_submission_token: request.draft_submission_token, image_urls: request.image_urls },
+        (response) =>
+            response.success
+                ? reply.resolve({ fields: response.fields, submissionType: "ocr_transcription" })
+                : reply.reject(response.error),
+        () => reply.reject("Transcription failed."),
+    );
+});
+```
+
+Because `reply` is just an object with `resolve`/`reject`, you can hand it straight to
+whatever does the work and keep that code free of any SDK reference:
+
+```ts
+webview.onTranscribeScannerRequest((request, reply) => myTranscriber(request, reply));
+```
+
+A handler that returns nothing is taken to own the reply, so the request stays open
+until `reply` answers it — returning the fields and answering through `reply` are both
+first-class, and the **first answer wins** (a second is ignored, with a dev warning).
+`reply.answered` tells you whether one already landed. `reply.reject`'s text is shown
+to the user verbatim, so pass display-ready messages.
+
+If the reply happens somewhere with no access to the handler's scope — a global bus, a
+different module holding only the id — the client also exposes the same two answers
+directly, taking the request or its bare `request_id`:
+
+```ts
+webview.resolveTranscribeScannerRequest(request, { fields, submissionType: "ocr_transcription" });
+webview.rejectTranscribeScannerRequest(request.request_id, "Transcription failed.");
+```
+
+Either way the result posts immediately, never sitting in the ready-queue, so a client
+that attached after the form loaded still replies. Answering after `destroy()`, or once
+the iframe is detached, is a silent no-op rather than a throw: by then nobody is
+listening, and the form times its own button out.
+
 ## React — `@captello/ulc-webview-sdk/react`
 
 The React adapter is the smoothest way to integrate, in two flavors:
@@ -440,9 +551,19 @@ new CaptelloWebview(iframe, {
   hostWindow?: Window;        // defaults to global window
   matchSource?: boolean;      // default true: only accept messages from this iframe
   queueUntilReady?: boolean;  // default true: buffer sends until form_load_complete
+  autoDestroy?: boolean;      // default true: destroy() when the iframe leaves the DOM
 });
 ```
 
+Every `on*` method returns a subscription handle — an object with `unsubscribe()`,
+which is also directly callable:
+
+```ts
+const sub = webview.on(OutboundMessageType.SubmissionBody, save);
+sub.unsubscribe(); // preferred
+sub(); // equivalent, for the older off() style
+```
+
 - `isReady` — `true` once the form has reported `form_load_complete`.
 - `on(type, listener) => unsubscribe` — subscribe to one outbound type.
 - `once(type, listener) => unsubscribe` — fire at most once.
@@ -450,8 +571,28 @@ new CaptelloWebview(iframe, {
 - `submit()`, `reset()`, `updateDraft()`, `triggerValidation(target)` — inbound helpers.
 - `submitAndWait(timeoutMs?)` — submit and await `submission_body` / `form_error_message` (see above).
 - `prefill({ submission?, info? })` — pre-fill from a submission body, transcription items, or both.
+- `onTranscribeScannerRequest(handler) => unsubscribe` — answer transcribe requests. The
+  handler gets `(request, reply)`: return the fields, or call `reply.resolve(...)` /
+  `reply.reject(...)` when callback-style work finishes (see
+  [above](#the-transcribe-button--host-side-processing)).
+- `resolveTranscribeScannerRequest(request, data)` / `rejectTranscribeScannerRequest(request, error)`
+  — answer from outside the handler's scope. Takes the request or its bare `request_id`.
 - `send(message)` — low-level escape hatch for any `InboundMessage`.
-- `destroy()` — detach the listener and drop subscriptions (idempotent).
+- `destroy()` — detach the listener and drop subscriptions (idempotent; also runs itself when the iframe is removed).
+
+**The frame argument** (`FrameLike`) is the `<iframe>` element, or anything exposing a
+`contentWindow`. It must already be mounted — the caller owns that ordering. See
+[The client needs a mounted iframe](#the-client-needs-a-mounted-iframe).
+
+**Automatic teardown.** With `autoDestroy` (default `true`), the client calls
+`destroy()` on itself once the iframe leaves the document — including when an ancestor
+is removed — so a torn-down panel can't leak the `message` listener. Set it to `false`
+to manage the lifetime yourself.
+
+**`targetOrigin` accepts a full URL**, not just a bare origin: pass the embed URL or your
+webview base URL and the SDK reduces it with `new URL(value).origin`. This is the usual
+reason a hand-rolled origin check gets commented out — a base URL never equals
+`event.origin`.
 
 **Send queueing.** With `queueUntilReady` (default `true`), any send before the webview
 reports `form_load_complete` is buffered and flushed, in order, on load — so calling
@@ -506,6 +647,53 @@ internal listener before settling, including on timeout.
 > call `waitForFormLoad` (e.g. you attach late), create a long-lived `CaptelloWebview`
 > before the iframe navigates instead.
 
+## Inside the Captello app — `@captello/ulc-webview-sdk/app`
+
+The mobile app embeds web pages (the meeting platform, Connexions) and offers them native
+services over `postMessage`. `CaptelloAppHost` is the page-side client for that channel —
+the mirror image of `CaptelloWebview`: here the Captello **app** is the host and your page
+is the child.
+
+```ts
+import { CaptelloAppHost, ScannerError } from "@captello/ulc-webview-sdk/app";
+
+const app = new CaptelloAppHost(); // listens on window, posts to window.parent
+
+const token = await app.requestAuthToken(); // exchange it for a session, then:
+app.notifyReady(); // the app hides its spinner
+
+try {
+    const people = await app.openScanner(); // resolves when the scanner closes
+    const [first] = people; // undefined if the user cancelled
+    if (first) fillForm(first.fields, first.badgeId);
+} catch (e) {
+    if (e instanceof ScannerError) showToast(e.message);
+}
+```
+
+`openScanner()` resolves with every person the scanner captured, in scan order — several
+for a group scan. Each `ScannedPerson` is `{ badgeId, fields }`, where `fields` is a
+`PrefillInfoItem[]` keyed by `ll_field_unique_identifier`, so it can be fed straight into a
+capture form's `prefill({ info })`. A badge with no lookup data still arrives with its
+`badgeId` and empty `fields`.
+
+The wire format differs from the capture-webview channel: messages are **plain objects**
+(not JSON strings) with SCREAMING_CASE types. The client handles both directions; for
+anything without a dedicated method, `send(request)` posts any `AppRequest` and
+`on(AppResponseType.X, listener)` subscribes to any response.
+
+| Page → app (`AppRequestType`)                                                   | Method                 | App → page (`AppResponseType`)                                                   |
+| ------------------------------------------------------------------------------- | ---------------------- | -------------------------------------------------------------------------------- |
+| `APP_READY`                                                                     | `notifyReady()`        | —                                                                                |
+| `ERROR`                                                                         | `notifyError(message)` | —                                                                                |
+| `NAVIGATE_BACK`                                                                 | `navigateBack()`       | —                                                                                |
+| `REQUEST_AUTH_TOKEN`                                                            | `requestAuthToken()`   | `AUTH_TOKEN { token }`                                                           |
+| `OPEN_ULC_FORM_SCANNER`                                                         | `openScanner()`        | `ULC_FORM_SCANNER_RESULT { badgeId, result }` ×N, then `ULC_FORM_SCANNER_CLOSED` |
+| `OPEN_URL`, `COPY_TEXT`, `SHARE_URL`, `SAVE_VCARD`, `ADD_TO_WALLET`, `SYNC_APP` | `send({ type, ... })`  | `COPIED_*`, `SAVE_VCARD_*`, `ADD_TO_WALLET_*` acks                               |
+
+`targetOrigin` defaults to `"*"` here: the app's webview origin differs per platform and a
+page only uses this channel when it is running inside the app.
+
 ## Migrating an existing integration
 
 Host apps that integrated before this SDK typically hand-rolled the same three pieces:
@@ -549,6 +737,137 @@ const body = await client.submitAndWait(); // throws SubmissionError on form_err
 Hold the `CaptelloWebview` instance in a ref/context and call `submit()` / `reset()` /
 `prefill()` instead of re-querying the DOM and stringifying messages by hand.
 
+### Worked example: swapping in a global `message` listener
+
+The common pre-SDK shape is one listener registered at page setup that JSON-parses every
+event and dispatches on `type`. It swaps in wholesale — with one structural change: the
+client is created where the iframe is created, rather than once at page setup, since it
+needs a mounted iframe. In exchange it tears itself down with that iframe, so there is no
+teardown to remember.
+
+```js
+// before — one global listener, manual parse, if/else chain
+const messageListener = (event) => {
+    let dataParsed = {};
+    try {
+        dataParsed = JSON.parse(event.data);
+    } catch (e) {
+        return;
+    }
+    if (dataParsed.type === "form_error_message") {
+        show_error_message(dataParsed.data);
+        return;
+    }
+    if (dataParsed.type === "transcribe_scanner_request") {
+        ll_form_submits_manager.transcribe_draft_scanner_element(dataParsed);
+        return;
+    }
+    if (dataParsed.type === "submission_body") {
+        saveSubmission(dataParsed.data);
+    }
+};
+window.addEventListener("message", messageListener);
+```
+
+```js
+// after — created alongside the iframe; dies with it
+const webview = new CaptelloSdk.CaptelloWebview(panelIframe, {
+    targetOrigin: CAPTURE_PORTAL_WEB_VIEW_BASE, // a full URL is fine — reduced to its origin
+});
+
+webview.on(CaptelloSdk.OutboundMessageType.FormErrorMessage, (msg) => show_error_message(msg.data));
+
+webview.on(CaptelloSdk.OutboundMessageType.TranscribeScannerRequest, (request) =>
+    ll_form_submits_manager.transcribe_draft_scanner_element(request),
+);
+
+webview.on(CaptelloSdk.OutboundMessageType.SubmissionBody, (msg) => saveSubmission(msg.data));
+```
+
+What you get by dropping the hand-rolled listener: the origin check is enforced (the
+one usually commented out because the constant is a base URL, not a bare origin — the
+SDK reduces it for you), non-Captello and malformed `postMessage` traffic from other
+scripts on the page is filtered out instead of hitting your `try/catch`, unknown `type`
+values are ignored, and `webview.destroy()` removes everything in one call.
+
+Where the old code posted a reply by hand, use the client so it is stringified and
+origin-targeted for you — `transcribe_draft_scanner_element` ends with:
+
+```js
+webview.resolveTranscribeScannerRequest(request, { fields, submissionType: "ocr_transcription" });
+// …or, on failure:
+webview.rejectTranscribeScannerRequest(request, "Transcription failed.");
+```
+
+### `attach()` — no iframe reference needed
+
+If your integration is a global `message` listener rather than something that owns the
+iframe element, `attach()` is the whole thing. Call it once, register handlers, done —
+nothing to query from the DOM, no ordering to get right relative to when the iframe is
+created, and no teardown to remember:
+
+```js
+const webview = CaptelloSdk.attach({ targetOrigin: CAPTURE_PORTAL_WEB_VIEW_BASE });
+
+webview.on(CaptelloSdk.OutboundMessageType.FormErrorMessage, (m) => showError(m.data));
+webview.on(CaptelloSdk.OutboundMessageType.SubmissionBody, (m) => save(m.data));
+webview.onTranscribeScannerRequest((request, reply) => transcribe(request, reply));
+```
+
+**How it finds the form.** The first inbound message that clears the origin check _and_
+parses as a well-formed Captello message identifies the webview. That sender becomes the
+target for sends and the window every later message is source-matched against — so after
+the first message this is exactly as strict as passing the iframe. With `targetOrigin`
+set to the webview's origin, only the webview can ever be adopted; under the default
+`"*"` that gate is absent, which is one more reason to set it.
+
+**Teardown is still automatic.** A removed iframe's window reports `closed`, and `closed`
+is readable cross-origin, so the client notices its form going away and destroys itself.
+(Verified in Chromium against a genuinely cross-origin iframe.) Pass `autoDestroy: false`
+to own the lifetime yourself.
+
+**The one trade-off.** Until the form speaks once there is no window to post to, so an
+unprompted `submit()` or `prefill()` before then has nowhere to go. With the default
+`queueUntilReady` those sends are buffered and flushed on `form_load_complete`, which
+covers the normal case. If you drive the form unprompted from page load _and_ can hold
+the element, prefer the explicit form below.
+
+### Or pass the iframe directly
+
+Construct the client once the iframe is in the DOM — the caller owns that ordering. The
+client source-matches every inbound message against the iframe's `contentWindow` from
+the very first one, and posts straight to it.
+
+If your old listener was registered at page setup, before the panel's iframe existed,
+move client creation to the moment you create the iframe:
+
+```js
+// when the panel opens
+var panelIframe = document.createElement("iframe");
+panelIframe.src = captureUrl;
+panel.appendChild(panelIframe);
+
+var webview = new CaptelloSdk.CaptelloWebview(panelIframe, { targetOrigin: BASE });
+webview.on(CaptelloSdk.OutboundMessageType.FormErrorMessage, showError);
+// ...
+```
+
+**You do not need a matching `destroy()`.** The client watches for its iframe leaving
+the document and tears itself down when it does — removing the `message` listener and
+dropping every subscription. An ancestor being removed counts, which is the usual case:
+emptying a panel or modal takes the iframe with it, and the client goes too. Calling
+`destroy()` yourself still works and is idempotent, so belt-and-braces teardown is fine.
+
+Pass `autoDestroy: false` to own the lifetime entirely — e.g. if you deliberately detach
+and re-insert the same iframe element and want the client to survive it. Detection uses
+`MutationObserver`, so with a `{ contentWindow }` stand-in or in a non-DOM environment
+it is simply inert.
+
+If you'd rather keep your own listener for now, `parseOutboundMessage(event.data)` is
+exported on its own: it replaces the `try { JSON.parse } catch` guard and returns a
+typed message (or `null` for anything that isn't ours), so you can adopt the protocol
+types without restructuring anything.
+
 **Prefill notes for migrators.** `prefill({ info })` items are matched by
 `ll_field_unique_identifier`; `ll_field_id` is optional (number or string) and `value`
 may be a string or boolean — so existing payloads with numeric ids and boolean values
@@ -563,6 +882,27 @@ _its_ parent via `window.parent.postMessage` (e.g. relaying `email`/`clientId`,
 `NAVIGATE_BACK` / scanner messages), that is a separate channel from the capture-form
 contract — keep that code; this SDK only models host ↔ capture-webview messaging.
 
+## Testing
+
+Two layers, deliberately split:
+
+- **`pnpm test`** — vitest unit tests against a fake window. Fast, covers the client's
+  logic, queueing, and every branch of the message protocol.
+- **`pnpm e2e`** — Playwright browser tests that load the **built IIFE bundle** into a real
+  page and talk to a real iframe on a **different origin** (`localhost` and `127.0.0.1` on
+  one server). This is the only layer that can exercise genuine `postMessage` semantics:
+  origin filtering, `event.source` identity, and a removed iframe's `closed` flag — jsdom
+  reports `closed` as `undefined`, so `attach()`'s teardown is unprovable without a browser.
+  The webview here is a stub, so this proves the client's behaviour, not that both sides
+  agree. `e2e/app-host.spec.ts` does the same for `CaptelloAppHost`: a stub app on one
+  origin embeds a page on the other and the two exchange plain-object messages.
+- **`e2e/sdk-integration.spec.ts` in the app repo** (`pnpm exec playwright test e2e/sdk-integration.spec.ts`)
+  — the SDK against the **real webview**, cross-origin. This is the layer that catches
+  protocol drift between the two, because neither side is a stub: it waits for a real
+  `form_load_complete`, prefills and asserts the values land in real form inputs, and runs
+  `submitAndWait()` through to a real `submission_body` (and, separately, to a real
+  validation failure surfacing as `SubmissionError`).
+
 ## Development
 
 ```bash