@captello/ulc-webview-sdk 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,137 @@
 # Changelog
 
+## 1.3.0
+
+### Minor Changes
+
+- 2e7ba33: The mobile-app channel now has both sides, under names that say who hosts whom.
+
+    The SDK covers two different embedding directions, and 1.2.0's `/app` entry blurred
+    them. They are now named explicitly:
+
+    | Who embeds whom                         | Client                                                                         |
+    | --------------------------------------- | ------------------------------------------------------------------------------ |
+    | Your page embeds the capture webview    | `CaptelloWebview` (unchanged)                                                  |
+    | The Captello mobile app embeds your app | `MobileHostClient` in your app · **new** `EmbeddedAppClient` in the mobile app |
+
+    - **`@captello/ulc-webview-sdk/mobile-host`** — `MobileHostClient` replaces 1.2.0's
+      `CaptelloAppHost`; `MobileHostRequestType` / `MobileHostResponseType` replace
+      `AppRequestType` / `AppResponseType`. Options are `mobileHostWindow` / `embeddedWindow`.
+      Behaviour is unchanged.
+    - **`@captello/ulc-webview-sdk/embedded-app`** — new. `EmbeddedAppClient(iframe)` is the
+      mobile app's side: typed `onRequest(type, listener)` / `onAnyRequest`, and
+      `sendAuthToken`, `sendScannerResult`, `sendScannerError`, `sendScannerClosed`, or
+      `send(response)` for the rest. Requests are accepted only from the bound iframe and,
+      once known, its origin; the target origin is read from `iframe.src` unless given, and
+      the client refuses to send with neither rather than fall back to `"*"`.
+    - **`@captello/ulc-webview-sdk/app`** (1.2.0) is removed. It shipped hours earlier with no
+      consumer, so the rename is not carried as aliases.
+
+## 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,13 @@ 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. **The mobile-app channel** — the SDK's second, separate protocol, for when the
+   **Captello mobile app** is the host and embeds an application:
+    - `@captello/ulc-webview-sdk/mobile-host` — `MobileHostClient`, used by the _embedded
+      application_ (the meeting platform, Connexions) to reach the mobile app for an auth
+      token, the badge scanner, and navigation.
+    - `@captello/ulc-webview-sdk/embedded-app` — `EmbeddedAppClient`, used by the _mobile
+      app_ to serve those requests through the iframe it hosts.
 
 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 +35,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 +135,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 +555,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 +575,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 +651,79 @@ internal listener before settling, including on timeout.
 > call `waitForFormLoad` (e.g. you attach late), create a long-lived `CaptelloWebview`
 > before the iframe navigates instead.
 
+## The mobile-app channel — `/mobile-host` and `/embedded-app`
+
+The SDK covers two embedding directions, and they are different protocols. Keep them apart:
+
+| Who embeds whom                             | Host                | Embedded              | Client to use                                                             | Wire                            |
+| ------------------------------------------- | ------------------- | --------------------- | ------------------------------------------------------------------------- | ------------------------------- |
+| **Your page embeds the capture webview**    | your page           | Captello capture form | `CaptelloWebview` (everything above this section)                         | JSON strings, `snake_case`      |
+| **The Captello mobile app embeds your app** | Captello mobile app | your application      | `MobileHostClient` (in your app), `EmbeddedAppClient` (in the mobile app) | plain objects, `SCREAMING_CASE` |
+
+### In the embedded application — `MobileHostClient`
+
+```ts
+import { MobileHostClient, ScannerError } from "@captello/ulc-webview-sdk/mobile-host";
+
+const mobileHost = new MobileHostClient(); // listens on window, posts to window.parent
+
+const token = await mobileHost.requestAuthToken(); // exchange it for a session, then:
+mobileHost.notifyReady(); // the mobile app hides its spinner
+
+try {
+    const people = await mobileHost.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`. `send(request)` posts any other `MobileHostRequest`;
+`on(MobileHostResponseType.X, listener)` subscribes to any response. `targetOrigin`
+defaults to `"*"` here: the mobile app's webview origin differs per platform and an
+application only uses this channel when it is running inside the app.
+
+### In the mobile app — `EmbeddedAppClient`
+
+```ts
+import { EmbeddedAppClient, MobileHostRequestType } from "@captello/ulc-webview-sdk/embedded-app";
+
+const embedded = new EmbeddedAppClient(iframe); // target origin read from iframe.src
+
+embedded.onRequest(MobileHostRequestType.RequestAuthToken, async () => {
+    embedded.sendAuthToken(await mintMagicToken());
+});
+embedded.onRequest(MobileHostRequestType.OpenScanner, async () => {
+    for (const person of await runScanner()) embedded.sendScannerResult(person);
+    embedded.sendScannerClosed();
+});
+embedded.onRequest(MobileHostRequestType.NavigateBack, () => modal.dismiss());
+
+// when the iframe goes away:
+embedded.destroy();
+```
+
+Requests are only accepted from the bound iframe's window (`matchSource`) and, once a
+target origin is known, from that origin. Responses can carry an auth token, so with no
+`targetOrigin` option and no parsable `iframe.src` the client refuses to send rather than
+fall back to `"*"`.
+
+### Wire reference
+
+| Embedded app → mobile app (`MobileHostRequestType`)                             | `MobileHostClient`     | Mobile app → embedded app (`MobileHostResponseType`)                             | `EmbeddedAppClient`                                                         |
+| ------------------------------------------------------------------------------- | ---------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `APP_READY`                                                                     | `notifyReady()`        | —                                                                                | —                                                                           |
+| `ERROR { message }`                                                             | `notifyError(message)` | —                                                                                | —                                                                           |
+| `NAVIGATE_BACK`                                                                 | `navigateBack()`       | —                                                                                | —                                                                           |
+| `REQUEST_AUTH_TOKEN`                                                            | `requestAuthToken()`   | `AUTH_TOKEN { token }`                                                           | `sendAuthToken(token)`                                                      |
+| `OPEN_ULC_FORM_SCANNER`                                                         | `openScanner()`        | `ULC_FORM_SCANNER_RESULT { badgeId, result }` ×N, then `ULC_FORM_SCANNER_CLOSED` | `sendScannerResult(person)`, `sendScannerError(msg)`, `sendScannerClosed()` |
+| `OPEN_URL`, `COPY_TEXT`, `SHARE_URL`, `SAVE_VCARD`, `ADD_TO_WALLET`, `SYNC_APP` | `send({ type, ... })`  | `COPIED_*`, `SAVE_VCARD_*`, `ADD_TO_WALLET_*` acks                               | `send({ type })`                                                            |
+
 ## Migrating an existing integration
 
 Host apps that integrated before this SDK typically hand-rolled the same three pieces:
@@ -549,6 +767,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 +912,28 @@ _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/mobile-app-channel.spec.ts` does the same for the mobile-app channel: a stub
+  mobile app on one origin (`EmbeddedAppClient`) embeds an application on the other
+  (`MobileHostClient`), so both shipped clients are proven against each other.
+- **`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

package/dist/chunk-XI5MIDBA.js

@@ -0,0 +1,60 @@
+// src/mobile-app-protocol.ts
+var MobileHostRequestType = /* @__PURE__ */ ((MobileHostRequestType2) => {
+  MobileHostRequestType2["AppReady"] = "APP_READY";
+  MobileHostRequestType2["Error"] = "ERROR";
+  MobileHostRequestType2["NavigateBack"] = "NAVIGATE_BACK";
+  MobileHostRequestType2["RequestAuthToken"] = "REQUEST_AUTH_TOKEN";
+  MobileHostRequestType2["OpenScanner"] = "OPEN_ULC_FORM_SCANNER";
+  MobileHostRequestType2["OpenUrl"] = "OPEN_URL";
+  MobileHostRequestType2["CopyText"] = "COPY_TEXT";
+  MobileHostRequestType2["ShareUrl"] = "SHARE_URL";
+  MobileHostRequestType2["SaveVCard"] = "SAVE_VCARD";
+  MobileHostRequestType2["AddToWallet"] = "ADD_TO_WALLET";
+  MobileHostRequestType2["SyncApp"] = "SYNC_APP";
+  return MobileHostRequestType2;
+})(MobileHostRequestType || {});
+var MobileHostResponseType = /* @__PURE__ */ ((MobileHostResponseType2) => {
+  MobileHostResponseType2["AuthToken"] = "AUTH_TOKEN";
+  MobileHostResponseType2["ScannerResult"] = "ULC_FORM_SCANNER_RESULT";
+  MobileHostResponseType2["ScannerClosed"] = "ULC_FORM_SCANNER_CLOSED";
+  MobileHostResponseType2["CopiedSuccess"] = "COPIED_SUCCESS";
+  MobileHostResponseType2["CopiedError"] = "COPIED_ERROR";
+  MobileHostResponseType2["SaveVCardSuccess"] = "SAVE_VCARD_SUCCESS";
+  MobileHostResponseType2["SaveVCardError"] = "SAVE_VCARD_ERROR";
+  MobileHostResponseType2["AddToWalletSuccess"] = "ADD_TO_WALLET_SUCCESS";
+  MobileHostResponseType2["AddToWalletError"] = "ADD_TO_WALLET_ERROR";
+  return MobileHostResponseType2;
+})(MobileHostResponseType || {});
+var REQUEST_TYPES = new Set(Object.values(MobileHostRequestType));
+var RESPONSE_TYPES = new Set(Object.values(MobileHostResponseType));
+function parseTyped(data, types) {
+  let value = data;
+  if (typeof value === "string") {
+    try {
+      value = JSON.parse(value);
+    } catch {
+      return null;
+    }
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  const record = value;
+  if (typeof record["type"] !== "string" || !types.has(record["type"])) return null;
+  return record;
+}
+function parseMobileHostRequest(data) {
+  return parseTyped(data, REQUEST_TYPES);
+}
+function parseMobileHostResponse(data) {
+  return parseTyped(data, RESPONSE_TYPES);
+}
+function makeSubscription(off) {
+  const handle = () => {
+    off();
+  };
+  handle.unsubscribe = off;
+  return handle;
+}
+
+export { MobileHostRequestType, MobileHostResponseType, makeSubscription, parseMobileHostRequest, parseMobileHostResponse };
+//# sourceMappingURL=chunk-XI5MIDBA.js.map
+//# sourceMappingURL=chunk-XI5MIDBA.js.map

package/dist/chunk-XI5MIDBA.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/mobile-app-protocol.ts"],"names":["MobileHostRequestType","MobileHostResponseType"],"mappings":";AA2BO,IAAK,qBAAA,qBAAAA,sBAAAA,KAAL;AAEH,EAAAA,uBAAA,UAAA,CAAA,GAAW,WAAA;AAEX,EAAAA,uBAAA,OAAA,CAAA,GAAQ,OAAA;AAER,EAAAA,uBAAA,cAAA,CAAA,GAAe,eAAA;AAEf,EAAAA,uBAAA,kBAAA,CAAA,GAAmB,oBAAA;AAMnB,EAAAA,uBAAA,aAAA,CAAA,GAAc,uBAAA;AAEd,EAAAA,uBAAA,SAAA,CAAA,GAAU,UAAA;AAEV,EAAAA,uBAAA,UAAA,CAAA,GAAW,WAAA;AAEX,EAAAA,uBAAA,UAAA,CAAA,GAAW,WAAA;AAEX,EAAAA,uBAAA,WAAA,CAAA,GAAY,YAAA;AAEZ,EAAAA,uBAAA,aAAA,CAAA,GAAc,eAAA;AAEd,EAAAA,uBAAA,SAAA,CAAA,GAAU,UAAA;AA1BF,EAAA,OAAAA,sBAAAA;AAAA,CAAA,EAAA,qBAAA,IAAA,EAAA;AAgGL,IAAK,sBAAA,qBAAAC,uBAAAA,KAAL;AAEH,EAAAA,wBAAA,WAAA,CAAA,GAAY,YAAA;AAEZ,EAAAA,wBAAA,eAAA,CAAA,GAAgB,yBAAA;AAEhB,EAAAA,wBAAA,eAAA,CAAA,GAAgB,yBAAA;AAChB,EAAAA,wBAAA,eAAA,CAAA,GAAgB,gBAAA;AAChB,EAAAA,wBAAA,aAAA,CAAA,GAAc,cAAA;AACd,EAAAA,wBAAA,kBAAA,CAAA,GAAmB,oBAAA;AACnB,EAAAA,wBAAA,gBAAA,CAAA,GAAiB,kBAAA;AACjB,EAAAA,wBAAA,oBAAA,CAAA,GAAqB,uBAAA;AACrB,EAAAA,wBAAA,kBAAA,CAAA,GAAmB,qBAAA;AAZX,EAAA,OAAAA,uBAAAA;AAAA,CAAA,EAAA,sBAAA,IAAA,EAAA;AAoFZ,IAAM,gBAAqC,IAAI,GAAA,CAAI,MAAA,CAAO,MAAA,CAAO,qBAAqB,CAAC,CAAA;AACvF,IAAM,iBAAsC,IAAI,GAAA,CAAI,MAAA,CAAO,MAAA,CAAO,sBAAsB,CAAC,CAAA;AAEzF,SAAS,UAAA,CAAW,MAAe,KAAA,EAA4D;AAC3F,EAAA,IAAI,KAAA,GAAiB,IAAA;AACrB,EAAA,IAAI,OAAO,UAAU,QAAA,EAAU;AAC3B,IAAA,IAAI;AACA,MAAA,KAAA,GAAQ,IAAA,CAAK,MAAM,KAAK,CAAA;AAAA,IAC5B,CAAA,CAAA,MAAQ;AACJ,MAAA,OAAO,IAAA;AAAA,IACX;AAAA,EACJ;AACA,EAAA,IAAI,OAAO,UAAU,QAAA,IAAY,KAAA,KAAU,QAAQ,KAAA,CAAM,OAAA,CAAQ,KAAK,CAAA,EAAG,OAAO,IAAA;AAChF,EAAA,MAAM,MAAA,GAAS,KAAA;AACf,EAAA,IAAI,OAAO,MAAA,CAAO,MAAM,CAAA,KAAM,QAAA,IAAY,CAAC,KAAA,CAAM,GAAA,CAAI,MAAA,CAAO,MAAM,CAAC,CAAA,EAAG,OAAO,IAAA;AAC7E,EAAA,OAAO,MAAA;AACX;AAOO,SAAS,uBAAuB,IAAA,EAAyC;AAC5E,EAAA,OAAO,UAAA,CAAW,MAAM,aAAa,CAAA;AACzC;AAOO,SAAS,wBAAwB,IAAA,EAA0C;AAC9E,EAAA,OAAO,UAAA,CAAW,MAAM,cAAc,CAAA;AAC1C;AAGO,SAAS,iBAAiB,GAAA,EAA8B;AAC3D,EAAA,MAAM,SAAU,MAAM;AAClB,IAAA,GAAA,EAAI;AAAA,EACR,CAAA;AACA,EAAA,MAAA,CAAO,WAAA,GAAc,GAAA;AACrB,EAAA,OAAO,MAAA;AACX","file":"chunk-XI5MIDBA.js","sourcesContent":["/**\n * The message protocol between the **Captello mobile app** and an **application it\n * embeds** (the meeting platform, Connexions, …).\n *\n * This is the second of the SDK's two channels, and the roles are the reverse of the\n * capture-webview channel:\n *\n * | Channel                                   | Host                | Embedded            | Client on each side                                  |\n * | ----------------------------------------- | ------------------- | ------------------- | ---------------------------------------------------- |\n * | A host page embeds the capture webview    | your page           | capture webview     | `CaptelloWebview` (host side)                        |\n * | The mobile app embeds an application      | Captello mobile app | your application    | `EmbeddedAppClient` (app side), `MobileHostClient` (embedded side) |\n *\n * Wire format (match it exactly — it differs from the capture-webview channel):\n * - Messages are posted as **plain objects**, not JSON strings.\n * - `type` values are SCREAMING_CASE.\n * - {@link MobileHostRequestType} (embedded application → mobile app) and\n *   {@link MobileHostResponseType} (mobile app → embedded application) are disjoint.\n */\n\nimport type { Unsubscribe } from \"./client\";\nimport type { PrefillInfoItem } from \"./messages\";\n\n/* ------------------------------------------------------------------ *\n * Requests: embedded application → mobile app\n * ------------------------------------------------------------------ */\n\n/** Message `type` values an embedded application sends to the Captello mobile app. */\nexport enum MobileHostRequestType {\n    /** The application finished loading; the app hides its loading spinner. */\n    AppReady = \"APP_READY\",\n    /** A user-facing error; the app shows `message`. */\n    Error = \"ERROR\",\n    /** Close the application (the app dismisses the modal or pops the route). */\n    NavigateBack = \"NAVIGATE_BACK\",\n    /** Ask for a magic token; answered with {@link MobileHostResponseType.AuthToken}. */\n    RequestAuthToken = \"REQUEST_AUTH_TOKEN\",\n    /**\n     * Open the app's badge scanner. Answered with one\n     * {@link MobileHostResponseType.ScannerResult} per scanned person, then\n     * {@link MobileHostResponseType.ScannerClosed}.\n     */\n    OpenScanner = \"OPEN_ULC_FORM_SCANNER\",\n    /** Open `url` in the system browser. */\n    OpenUrl = \"OPEN_URL\",\n    /** Copy `text` to the clipboard; acknowledged with `COPIED_SUCCESS` / `COPIED_ERROR`. */\n    CopyText = \"COPY_TEXT\",\n    /** Open the native share sheet. */\n    ShareUrl = \"SHARE_URL\",\n    /** Save a vCard to the contacts; acknowledged with `SAVE_VCARD_SUCCESS` / `SAVE_VCARD_ERROR`. */\n    SaveVCard = \"SAVE_VCARD\",\n    /** Add a wallet pass; acknowledged with `ADD_TO_WALLET_SUCCESS` / `ADD_TO_WALLET_ERROR`. */\n    AddToWallet = \"ADD_TO_WALLET\",\n    /** Ask the app to synchronize its data. */\n    SyncApp = \"SYNC_APP\",\n}\n\nexport interface AppReadyRequest {\n    type: MobileHostRequestType.AppReady;\n}\nexport interface ErrorRequest {\n    type: MobileHostRequestType.Error;\n    message: string;\n}\nexport interface NavigateBackRequest {\n    type: MobileHostRequestType.NavigateBack;\n}\nexport interface RequestAuthTokenRequest {\n    type: MobileHostRequestType.RequestAuthToken;\n}\nexport interface OpenScannerRequest {\n    type: MobileHostRequestType.OpenScanner;\n}\nexport interface OpenUrlRequest {\n    type: MobileHostRequestType.OpenUrl;\n    url: string;\n}\nexport interface CopyTextRequest {\n    type: MobileHostRequestType.CopyText;\n    text: string;\n}\nexport interface ShareUrlRequest {\n    type: MobileHostRequestType.ShareUrl;\n    title: string;\n    text: string;\n}\nexport interface SaveVCardRequest {\n    type: MobileHostRequestType.SaveVCard;\n    /** vCard text. */\n    text: string;\n}\nexport interface AddToWalletRequest {\n    type: MobileHostRequestType.AddToWallet;\n    /** Base64 pass data, with or without a `data:` prefix. */\n    text: string;\n}\nexport interface SyncAppRequest {\n    type: MobileHostRequestType.SyncApp;\n}\n\n/** Discriminated union of every message an embedded application can send to the mobile app. */\nexport type MobileHostRequest =\n    | AppReadyRequest\n    | ErrorRequest\n    | NavigateBackRequest\n    | RequestAuthTokenRequest\n    | OpenScannerRequest\n    | OpenUrlRequest\n    | CopyTextRequest\n    | ShareUrlRequest\n    | SaveVCardRequest\n    | AddToWalletRequest\n    | SyncAppRequest;\n\n/** Maps each request `type` to its full message shape (used by {@link EmbeddedAppClient.onRequest}). */\nexport type MobileHostRequestMap = {\n    [M in MobileHostRequest as M[\"type\"]]: M;\n};\n\n/* ------------------------------------------------------------------ *\n * Responses: mobile app → embedded application\n * ------------------------------------------------------------------ */\n\n/** Message `type` values the Captello mobile app sends to an embedded application. */\nexport enum MobileHostResponseType {\n    /** Answer to {@link MobileHostRequestType.RequestAuthToken}. */\n    AuthToken = \"AUTH_TOKEN\",\n    /** One scanned person (or a scanner failure) after {@link MobileHostRequestType.OpenScanner}. */\n    ScannerResult = \"ULC_FORM_SCANNER_RESULT\",\n    /** The scanner session ended: every result was posted, or the user cancelled. */\n    ScannerClosed = \"ULC_FORM_SCANNER_CLOSED\",\n    CopiedSuccess = \"COPIED_SUCCESS\",\n    CopiedError = \"COPIED_ERROR\",\n    SaveVCardSuccess = \"SAVE_VCARD_SUCCESS\",\n    SaveVCardError = \"SAVE_VCARD_ERROR\",\n    AddToWalletSuccess = \"ADD_TO_WALLET_SUCCESS\",\n    AddToWalletError = \"ADD_TO_WALLET_ERROR\",\n}\n\n/** Mobile app → embedded application: the magic token requested with {@link MobileHostRequestType.RequestAuthToken}. */\nexport interface AuthTokenMessage {\n    type: MobileHostResponseType.AuthToken;\n    token: string;\n}\n\n/**\n * Mobile app → embedded application: one scanned person, or a scanner failure.\n *\n * The app posts one of these per person the scanner captured — several for a group\n * scan — then a {@link ScannerClosedMessage}. `result` holds the looked-up attendee\n * fields in the same shape {@link PrefillInfoItem} uses, so they can be fed straight to\n * a capture form's `prefill({ info })`. It is empty (not absent) when the badge had no\n * lookup data; the badge can still be linked via `badgeId`.\n *\n * On failure `result` is absent and `message` carries the error text.\n */\nexport interface ScannerResultMessage {\n    type: MobileHostResponseType.ScannerResult;\n    /**\n     * Badge ID the person was scanned from. Empty for business cards and manual search.\n     * Absent altogether on app builds that predate multi-person sessions — those post a\n     * single result and never a {@link ScannerClosedMessage}.\n     */\n    badgeId?: string;\n    /** Looked-up attendee fields (success). */\n    result?: PrefillInfoItem[];\n    /** Error text (failure) — `result` is absent. */\n    message?: string;\n}\n\n/** Mobile app → embedded application: the scanner session ended. Follows the last {@link ScannerResultMessage}. */\nexport interface ScannerClosedMessage {\n    type: MobileHostResponseType.ScannerClosed;\n}\n\ninterface AckMessage<T extends MobileHostResponseType> {\n    type: T;\n}\n\n/** Discriminated union of every message the mobile app can send to an embedded application. */\nexport type MobileHostResponse =\n    | AuthTokenMessage\n    | ScannerResultMessage\n    | ScannerClosedMessage\n    | AckMessage<MobileHostResponseType.CopiedSuccess>\n    | AckMessage<MobileHostResponseType.CopiedError>\n    | AckMessage<MobileHostResponseType.SaveVCardSuccess>\n    | AckMessage<MobileHostResponseType.SaveVCardError>\n    | AckMessage<MobileHostResponseType.AddToWalletSuccess>\n    | AckMessage<MobileHostResponseType.AddToWalletError>;\n\n/** Maps each response `type` to its full message shape (used by {@link MobileHostClient.on}). */\nexport type MobileHostResponseMap = {\n    [M in MobileHostResponse as M[\"type\"]]: M;\n};\n\n/** One person captured by the mobile app's scanner. */\nexport interface ScannedPerson {\n    /** Badge ID the person was scanned from; empty for business cards and manual search. */\n    badgeId: string;\n    /** Looked-up attendee fields; empty when the badge had no lookup data. */\n    fields: PrefillInfoItem[];\n}\n\n/* ------------------------------------------------------------------ *\n * Runtime guards / parsing\n * ------------------------------------------------------------------ */\n\nconst REQUEST_TYPES: ReadonlySet<string> = new Set(Object.values(MobileHostRequestType));\nconst RESPONSE_TYPES: ReadonlySet<string> = new Set(Object.values(MobileHostResponseType));\n\nfunction parseTyped(data: unknown, types: ReadonlySet<string>): Record<string, unknown> | null {\n    let value: unknown = data;\n    if (typeof value === \"string\") {\n        try {\n            value = JSON.parse(value);\n        } catch {\n            return null;\n        }\n    }\n    if (typeof value !== \"object\" || value === null || Array.isArray(value)) return null;\n    const record = value as Record<string, unknown>;\n    if (typeof record[\"type\"] !== \"string\" || !types.has(record[\"type\"])) return null;\n    return record;\n}\n\n/**\n * Parses a raw `MessageEvent.data` value into a typed {@link MobileHostRequest}, or\n * returns `null` if it is not a recognized request. Plain objects are the wire format;\n * a JSON string is accepted too for robustness.\n */\nexport function parseMobileHostRequest(data: unknown): MobileHostRequest | null {\n    return parseTyped(data, REQUEST_TYPES) as unknown as MobileHostRequest | null;\n}\n\n/**\n * Parses a raw `MessageEvent.data` value into a typed {@link MobileHostResponse}, or\n * returns `null` if it is not a recognized response. Plain objects are the wire format;\n * a JSON string is accepted too for robustness.\n */\nexport function parseMobileHostResponse(data: unknown): MobileHostResponse | null {\n    return parseTyped(data, RESPONSE_TYPES) as unknown as MobileHostResponse | null;\n}\n\n/** @internal Builds the callable-with-`unsubscribe()` handle every `on*` method returns. */\nexport function makeSubscription(off: () => void): Unsubscribe {\n    const handle = (() => {\n        off();\n    }) as Unsubscribe;\n    handle.unsubscribe = off;\n    return handle;\n}\n"]}