lecodes-sdk 2.2.6 → 2.2.8

package/package.json

@@ -45,7 +45,7 @@
     "marcidb-embedded": "^0.15.0",
     "sharp": "^0.35.2"
   },
-  "version": "2.2.6",
+  "version": "2.2.8",
   "files": [
     "src",
     "dist",

package/src/chisel.ts

@@ -118,7 +118,7 @@ export const chiselVocab: ChiselVocab = {
     },
     leaves: [
       "UIText", "UIImage", "UIVideo", "UIInput", "UITextArea", "UISpacer",
-      "UITabs", "UIVirtualizedList", "NativeView", "CameraView", "MapView", "QRScanner",
+      "UITabs", "UIVirtualizedList", "NativeView", "CameraView", "MapView", "QRScanner", "WebView", "RTCVideoView",
     ],
     containers: [ "UIColumn", "UIRow", "UIBox", "UIButton", "UIScrollable", "UIScreen", "UIWidget" ],
     text: "UIText",
@@ -133,7 +133,7 @@ export const chiselVocab: ChiselVocab = {
       "append", "insert", "remove", "setContent", "widgets", "keepAlive", "url",
       "detents", "dismissible", "transition", "setSourceRect",
       "push", "pop", "popToRoot", "replace", "select",
-      // UITabs / UIVirtualizedList's hand feed / the native views (NativeView, CameraView, MapView, QRScanner)
+      // UITabs / UIVirtualizedList's hand feed / the native views (NativeView, CameraView, MapView, QRScanner, WebView, RTCVideoView)
       "badge", "setData", "update", "prepend", "removeByKey",
       "on", "off", "onReady", "onError", "onTap", "onMove", "onScan",
       "flyTo", "jumpTo", "fitPoints", "setPadding", "setUserLocation",

package/src/inject.ts

@@ -151,6 +151,14 @@ export {
   type LineLayer, type LineLayerOptions, type UserLocationOptions,
 } from "./plugins/gen/map/sdk/map"
 export { Push, type PushPayload, type PushStatus, type PushRegisterOptions, type PushEvent } from "./plugins/gen/push/sdk/push"
+export { Browser, WebView, type BrowserOpenOptions, type WebViewParams, type WebViewEvents } from "./plugins/gen/browser/sdk/browser"
+export {
+  RTCPeerConnection, MediaStream, MediaStreamTrack, RTCDataChannel, RTCRtpSender, RTCRtpReceiver, RTCRtpTransceiver,
+  RTCSessionDescription, RTCIceCandidate, RTCEventTarget, mediaDevices, RTCVideoView,
+  type RTCConfiguration, type RTCVideoViewOptions, type MediaStreamConstraints, type RTCIceCandidateInit,
+  type RTCPeerConnectionIceEvent, type RTCTrackEvent, type RTCDataChannelEvent, type RTCMessageEvent, type RTCErrorEvent, type RTCEvent,
+  type RTCEventListener,
+} from "./plugins/gen/webrtc/sdk/webrtc"
 export { Service } from "./plugins/service"
 
 // ---- scenes as data (.scene.ts files — see src/scene/defineScene.ts) ----

package/src/plugin.ts

@@ -13,8 +13,13 @@ import { ServiceClient } from "./runtime/service"
 import { NativeView, NativeViewElement } from "./ui/NativeView"
 import { _navEpoch } from "./ui/presentable"
 import { _requestCameraPermission } from "./plugins/permission"
+import { appEventsOff, appEventsOn } from "./runtime/appEvents"
 
 export type { PresentOptions } from "./ui/presentable"
+// The SDK UI a wrapper builds its own chrome with (the browser plugin's bar over an embedded page) and
+// the navigation it presents through. Re-exported, never copied: chisel keys on these names.
+export { Presentable, Router, UIBox, UIButton, UIColumn, UIRow, UIScreen, UIText } from "./ui/UI"
+export { theme } from "./ui/theme"
 export type { NativeView } from "./ui/NativeView"
 export type { FetchResponse } from "./runtime/fetch"
 
@@ -172,6 +177,14 @@ export const _fromFile = (file: File): { systemId: number, name: string, size: n
 
 // ---- for the hand-written part ---------------------------------------------------------------------
 
+/** Hear the app's "url" events (a deep link while the app runs — an OAuth redirect, a checkout's
+ *  return) until the returned function is called. The listener the `app` global fans out from. */
+export const _onAppUrl = (callback: (url: string) => void): (() => void) => {
+  const listener = (data?: string): void => { if (data) callback(data) }
+  appEventsOn("url", listener)
+  return () => appEventsOff("url", listener)
+}
+
 /** The text of a host buffer — what a bundled `asset()` is in a shell compile (`"id:N"`): the host
  *  already holds the bytes. Empty when there is no such buffer. */
 export const bufferText = (systemId: number): string => _creatorFetch.toText(systemId)

package/src/plugins/gen/browser/contract.d.ts

@@ -0,0 +1,108 @@
+// GENERATED by scripts/vendor-plugins.ts from lecodes-plugins/plugins/browser/contract.d.ts — do not edit here.
+// Change it in the plugin repo and run `bun run vendor:plugins`; `bun run check:plugins` fails when this copy is stale.
+// browser — web content inside the app, on the two surfaces the platforms give:
+//   - the SYSTEM SHEET (the "browser" service): SFSafariViewController / ASWebAuthenticationSession on
+//     iOS, Chrome Custom Tabs on Android, a popup on the web. It shares the system browser's logins,
+//     passkeys and Apple Pay, and OAuth providers accept it. The app sees nothing of the page.
+//   - the EMBEDDED PAGE (the "webView" view): WKWebView / android.webkit.WebView / an iframe. A tree
+//     node the app embeds or presents fullscreen, with navigation events the app acts on.
+//
+// The hosts are dumb on purpose: they intercept a URL prefix and report it, forward the platform's
+// callback URL, hand a non-http link to the system. Which URL ends a flow and what it means is the
+// app's side (`Browser.open` in sdk/).
+
+import type { Json, Service, View } from "../../../plugin"
+
+// ---- the sheet ------------------------------------------------------------------------------------
+
+export interface BrowserParams {}
+
+export interface BrowserOpenOptions {
+  /** An auth flow: the scheme the provider redirects back to (`myshop` of `myshop://oauth`). iOS
+   *  runs an ASWebAuthenticationSession and resolves `open` with the callback URL itself. Android
+   *  and the web have nothing to do here: the redirect reaches the app as its "url" event. */
+  callbackScheme?: string
+  /** A private session: no cookies shared with the system browser. Honored on iOS (with a
+   *  callbackScheme), ignored elsewhere. Default false. */
+  ephemeral?: boolean
+  /** The sheet's tint, "#RRGGBB". */
+  color?: string
+}
+
+export interface BrowserResult {
+  /** The callback URL the platform intercepted (iOS, with a callbackScheme); absent when the sheet
+   *  was dismissed. */
+  url?: string
+}
+
+export interface BrowserEvents {
+  /** The sheet went away: the user dismissed it, the platform handed back the callback, or
+   *  close(). */
+  closed: void
+}
+
+export interface Browser extends Service<"browser", BrowserParams, BrowserEvents> {
+  /** Show `url` in the system's in-app browser sheet. Resolves when the sheet is dismissed — with
+   *  the callback URL when the platform intercepted one. One sheet at a time.
+   *  @rejects busy invalid */
+  show(url: string, options?: BrowserOpenOptions): Promise<BrowserResult>
+  /** Dismiss the sheet; a no-op without one. */
+  dismiss(): Promise<void>
+}
+
+// ---- the embedded page ----------------------------------------------------------------------------
+
+export interface WebViewParams {
+  /** What to load first. */
+  url?: string
+  /** Main-frame URLs that END a flow: a navigation whose URL starts with one is NOT loaded, the
+   *  view emits `stop` instead. */
+  stops?: string[]
+  /** Install `window.lecodes.postMessage(data)` for the page (the `message` event) and let
+   *  `postMessage` reach it (`window.lecodes.onMessage`). Default false — a user script disables
+   *  Apple Pay in that WKWebView, so a checkout page wants it off. */
+  bridge?: boolean
+  /** A navigation to a non-http(s) URL — tel:, mailto:, intent:, a bank's app in a checkout:
+   *  "open" hands it to the system, "block" drops it. Default "open". */
+  externalLinks?: "open" | "block"
+  userAgent?: string
+  /** A private session: no cookies or storage kept after the view goes. Default false. */
+  ephemeral?: boolean
+}
+
+export interface WebViewEvents {
+  /** A main-frame navigation started. */
+  navigate: { url: string }
+  /** The page finished loading. */
+  load: { url: string, title: string }
+  /** The page failed to load. */
+  error: { url: string, message: string }
+  /** A stop URL was reached: the navigation was cancelled, the page did not load. */
+  stop: { url: string }
+  /** The page called `window.lecodes.postMessage(data)` (with `bridge`). */
+  message: { data: Json }
+  /** The page called `window.close()`. */
+  exit: void
+}
+
+export interface WebView extends View<"webView", WebViewParams, WebViewEvents> {
+  /** Load `url`, with extra request headers for the first request. @rejects invalid */
+  load(url: string, headers?: { [name: string]: string }): Promise<void>
+  /** Show `html` as the page; relative URLs in it resolve against `baseUrl`. */
+  loadHtml(html: string, baseUrl?: string): Promise<void>
+  /** Replace the stop list (see WebViewParams.stops). */
+  setStops(stops: string[]): Promise<void>
+  reload(): Promise<void>
+  /** Stop the current load. */
+  stopLoading(): Promise<void>
+  goBack(): Promise<void>
+  goForward(): Promise<void>
+  canGoBack(): Promise<boolean>
+  /** Run `js` in the page and return what it evaluates to, as JSON. On iOS this disables Apple Pay
+   *  in the view until its next navigation. @rejects failed */
+  evaluate(js: string): Promise<Json>
+  /** Deliver `data` to the page's `window.lecodes.onMessage(data)` (with `bridge`). */
+  postMessage(data: Json): Promise<void>
+  /** Clear the cookies and the storage of this view's session. */
+  clearData(): Promise<void>
+}

package/src/plugins/gen/browser/sdk/browser.Browser.gen.ts

@@ -0,0 +1,48 @@
+// GENERATED by scripts/vendor-plugins.ts from lecodes-plugins/plugins/browser/sdk/browser.Browser.gen.ts — do not edit here.
+// Change it in the plugin repo and run `bun run vendor:plugins`; `bun run check:plugins` fails when this copy is stale.
+// GENERATED by `lecodes plugin gen` from contract.d.ts — do not edit.
+// browser: the service "browser", contract version 1.
+
+import { ServiceChannel } from "../../../../plugin"
+import type { BrowserEvents, BrowserOpenOptions, BrowserParams, BrowserResult } from "../contract"
+
+/** What the halves register under. */
+export const NAME = "browser"
+/** The contract's version: the highest `@since` of its members. */
+export const VERSION = 1
+
+// ---- the wire, call by call ----------------------------------------------------------------------
+
+/** Show `url` in the system's in-app browser sheet. Resolves when the sheet is dismissed — with
+ *  the callback URL when the platform intercepted one. One sheet at a time.
+ *  Rejects with "busy" / "invalid". */
+export const show = (service: ServiceChannel<BrowserEvents>, url: string, options?: BrowserOpenOptions): Promise<BrowserResult> =>
+  service._call("show", [url, options])
+
+/** Dismiss the sheet; a no-op without one. */
+export const dismiss = (service: ServiceChannel<BrowserEvents>): Promise<void> =>
+  service._call("dismiss", [])
+
+// ---- what the host's half has --------------------------------------------------------------------
+
+/** A method of the contract. */
+export type Method = "show" | "dismiss"
+
+/** Whether this host has the service "browser" — and, given a method, a half new enough for it
+ *  (a method added after the first version of the contract is tagged `@since`). */
+export const supports = (method?: Method): boolean =>
+  ServiceChannel.supports(NAME)   // every method is of version 1
+
+// ---- the client -----------------------------------------------------------------------------------
+
+/** The service "browser" with the wire's methods as its own. */
+export class BrowserBase extends ServiceChannel<BrowserEvents> {
+  constructor(params: BrowserParams = {}) { super("Browser", NAME, params) }
+
+  /** Show `url` in the system's in-app browser sheet. Resolves when the sheet is dismissed — with
+   *  the callback URL when the platform intercepted one. One sheet at a time.
+   *  Rejects with "busy" / "invalid". */
+  show(url: string, options?: BrowserOpenOptions): Promise<BrowserResult> { return show(this, url, options) }
+  /** Dismiss the sheet; a no-op without one. */
+  dismiss(): Promise<void> { return dismiss(this) }
+}

package/src/plugins/gen/browser/sdk/browser.WebView.gen.ts

@@ -0,0 +1,96 @@
+// GENERATED by scripts/vendor-plugins.ts from lecodes-plugins/plugins/browser/sdk/browser.WebView.gen.ts — do not edit here.
+// Change it in the plugin repo and run `bun run vendor:plugins`; `bun run check:plugins` fails when this copy is stale.
+// GENERATED by `lecodes plugin gen` from contract.d.ts — do not edit.
+// browser: the view "webView", contract version 1.
+
+import { ViewChannel, type Json } from "../../../../plugin"
+import type { WebViewEvents, WebViewParams } from "../contract"
+
+/** What the halves register under. */
+export const NAME = "webView"
+/** The contract's version: the highest `@since` of its members. */
+export const VERSION = 1
+
+// ---- the wire, call by call ----------------------------------------------------------------------
+
+/** Load `url`, with extra request headers for the first request.
+ *  Rejects with "invalid". */
+export const load = (view: ViewChannel<WebViewEvents>, url: string, headers?: { [key: string]: string }): Promise<void> =>
+  view._call("load", [url, headers])
+
+/** Show `html` as the page; relative URLs in it resolve against `baseUrl`. */
+export const loadHtml = (view: ViewChannel<WebViewEvents>, html: string, baseUrl?: string): Promise<void> =>
+  view._call("loadHtml", [html, baseUrl])
+
+/** Replace the stop list (see WebViewParams.stops). */
+export const setStops = (view: ViewChannel<WebViewEvents>, stops: string[]): Promise<void> =>
+  view._call("setStops", [stops])
+
+export const reload = (view: ViewChannel<WebViewEvents>): Promise<void> =>
+  view._call("reload", [])
+
+/** Stop the current load. */
+export const stopLoading = (view: ViewChannel<WebViewEvents>): Promise<void> =>
+  view._call("stopLoading", [])
+
+export const goBack = (view: ViewChannel<WebViewEvents>): Promise<void> =>
+  view._call("goBack", [])
+
+export const goForward = (view: ViewChannel<WebViewEvents>): Promise<void> =>
+  view._call("goForward", [])
+
+export const canGoBack = (view: ViewChannel<WebViewEvents>): Promise<boolean> =>
+  view._call("canGoBack", [])
+
+/** Run `js` in the page and return what it evaluates to, as JSON. On iOS this disables Apple Pay
+ *  in the view until its next navigation.
+ *  Rejects with "failed". */
+export const evaluate = (view: ViewChannel<WebViewEvents>, js: string): Promise<Json> =>
+  view._call("evaluate", [js])
+
+/** Deliver `data` to the page's `window.lecodes.onMessage(data)` (with `bridge`). */
+export const postMessage = (view: ViewChannel<WebViewEvents>, data: Json): Promise<void> =>
+  view._call("postMessage", [data])
+
+/** Clear the cookies and the storage of this view's session. */
+export const clearData = (view: ViewChannel<WebViewEvents>): Promise<void> =>
+  view._call("clearData", [])
+
+// ---- what the host's half has --------------------------------------------------------------------
+
+/** A method of the contract. */
+export type Method = "load" | "loadHtml" | "setStops" | "reload" | "stopLoading" | "goBack" | "goForward" | "canGoBack" | "evaluate" | "postMessage" | "clearData"
+
+/** Whether this host has the view "webView" — and, given a method, a half new enough for it
+ *  (a method added after the first version of the contract is tagged `@since`). */
+export const supports = (method?: Method): boolean =>
+  ViewChannel.supports(NAME)   // every method is of version 1
+
+// ---- the element ----------------------------------------------------------------------------------
+
+/** The view "webView" with the wire's methods as its own. */
+export class WebViewBase extends ViewChannel<WebViewEvents> {
+  constructor(params: WebViewParams = {}) { super("WebView", NAME, params) }
+
+  /** Load `url`, with extra request headers for the first request.
+   *  Rejects with "invalid". */
+  load(url: string, headers?: { [key: string]: string }): Promise<void> { return load(this, url, headers) }
+  /** Show `html` as the page; relative URLs in it resolve against `baseUrl`. */
+  loadHtml(html: string, baseUrl?: string): Promise<void> { return loadHtml(this, html, baseUrl) }
+  /** Replace the stop list (see WebViewParams.stops). */
+  setStops(stops: string[]): Promise<void> { return setStops(this, stops) }
+  reload(): Promise<void> { return reload(this) }
+  /** Stop the current load. */
+  stopLoading(): Promise<void> { return stopLoading(this) }
+  goBack(): Promise<void> { return goBack(this) }
+  goForward(): Promise<void> { return goForward(this) }
+  canGoBack(): Promise<boolean> { return canGoBack(this) }
+  /** Run `js` in the page and return what it evaluates to, as JSON. On iOS this disables Apple Pay
+   *  in the view until its next navigation.
+   *  Rejects with "failed". */
+  evaluate(js: string): Promise<Json> { return evaluate(this, js) }
+  /** Deliver `data` to the page's `window.lecodes.onMessage(data)` (with `bridge`). */
+  postMessage(data: Json): Promise<void> { return postMessage(this, data) }
+  /** Clear the cookies and the storage of this view's session. */
+  clearData(): Promise<void> { return clearData(this) }
+}

package/src/plugins/gen/browser/sdk/browser.ts

@@ -0,0 +1,218 @@
+// GENERATED by scripts/vendor-plugins.ts from lecodes-plugins/plugins/browser/sdk/browser.ts — do not edit here.
+// Change it in the plugin repo and run `bun run vendor:plugins`; `bun run check:plugins` fails when this copy is stale.
+// Browser.open — a URL on the surface the scenario needs, ONE verb for the three of them:
+//
+//   await Browser.open(url)                                        a page, in the system sheet
+//   const back = await Browser.open(authUrl, { returnUrl: "myshop://oauth" })      OAuth: the sheet,
+//                                                                  resolved with the redirect URL
+//   const back = await Browser.open(checkoutUrl, { returnUrl: [paid, failed], embedded: true })
+//                                                                  a checkout in an embedded page,
+//                                                                  resolved with the URL it reached
+//
+// It resolves with the return URL reached, or null when the user left. `returnUrl` says what ENDS
+// the page; `embedded` says WHERE it runs — the system sheet (shared logins, passkeys, Apple Pay;
+// the only surface OAuth providers accept) or a WebView presented fullscreen under a bar the SDK
+// draws (an https return without verified app links, a 3DS flow, no system chrome).
+//
+// Hand-written over the generated wire because the flows are the SDK's, not the hosts':
+//   - the sheet's return is ONE of two paths — iOS intercepts the scheme itself and resolves `show`
+//     with the URL, Android and the web deliver the redirect as the app's "url" event. The wrapper
+//     races both and the host does nothing it would not do for a plain deep link;
+//   - the embedded flow is a WebView with the return URLs as its `stops`, inside a screen with a
+//     close bar, pushed through the Router when one is showing and opened directly otherwise.
+//
+// WebView() is the element itself: embed it among a screen's children, push it with your own
+// chrome, drive it (`load`, `evaluate`, `postMessage`) and listen (`navigate`, `load`, `stop`,
+// `message`).
+
+import {
+  Presentable, Router, UIBox, UIButton, UIRow, UIScreen, UIText, theme, _onAppUrl, type Json, type Listener, type NativeView,
+} from "../../../../plugin"
+import { BrowserBase, NAME as SHEET_NAME } from "./browser.Browser.gen"
+import { WebViewBase, NAME as VIEW_NAME, supports as viewSupports, type Method as WebViewMethod } from "./browser.WebView.gen"
+import type { WebViewEvents, WebViewParams } from "../contract"
+
+export type { WebViewEvents, WebViewParams } from "../contract"
+
+export interface BrowserOpenOptions {
+  /** What ends the page: a URL prefix, or several (a checkout's success and failure URLs). The
+   *  promise resolves with the URL reached. In the sheet every prefix must share one scheme — the
+   *  platform intercepts one; a custom scheme needs app.json `urlScheme`, an https one the app's
+   *  verified links. */
+  returnUrl?: string | string[]
+  /** Run the page in an embedded WebView under a close bar instead of the system sheet. The
+   *  WebView intercepts any return URL itself, https included. */
+  embedded?: boolean
+  /** A private session: no cookies shared with the system browser, nothing kept after. */
+  ephemeral?: boolean
+  /** The sheet's tint, "#RRGGBB". */
+  color?: string
+  /** Embedded: the bar's title until the page reports its own. */
+  title?: string
+}
+
+/** The embedded page — the element of the "webView" view: embeddable among a screen's children,
+ *  presentable (`open()`, `Router.push`), with the page's controls and events. */
+export interface WebView extends NativeView {
+  /** Load `url`, with extra request headers for the first request. Rejects "invalid" for a URL
+   *  that is not a web one. */
+  load(url: string, headers?: { [name: string]: string }): Promise<void>
+  /** Show `html` as the page; relative URLs in it resolve against `baseUrl`. */
+  loadHtml(html: string, baseUrl?: string): Promise<void>
+  /** Replace the URL prefixes that end a navigation with the `stop` event. */
+  setStops(stops: string[]): Promise<void>
+  reload(): Promise<void>
+  /** Stop the current load. */
+  stopLoading(): Promise<void>
+  goBack(): Promise<void>
+  goForward(): Promise<void>
+  canGoBack(): Promise<boolean>
+  /** Run `js` in the page and get what it evaluates to, as JSON. On iOS this disables Apple Pay
+   *  in the view until its next navigation. */
+  evaluate(js: string): Promise<Json>
+  /** Deliver `data` to the page's `window.lecodes.onMessage(data)` (a view created with `bridge`). */
+  postMessage(data: Json): Promise<void>
+  /** Clear the cookies and the storage of this view's session. */
+  clearData(): Promise<void>
+  /** The page's events: `navigate`, `load`, `error`, `stop`, `message`, `exit`. */
+  on<K extends keyof WebViewEvents & string>(event: K, callback: Listener<WebViewEvents, K>): this
+  off<K extends keyof WebViewEvents & string>(event: K, callback: Listener<WebViewEvents, K>): this
+}
+
+const returnUrls = (options: BrowserOpenOptions): string[] =>
+  options.returnUrl === undefined ? [] : Array.isArray(options.returnUrl) ? options.returnUrl : [options.returnUrl]
+
+const matching = (url: string, prefixes: string[]): string | undefined =>
+  prefixes.some(p => url.startsWith(p)) ? url : undefined
+
+const schemeOf = (url: string): string => {
+  const m = /^([a-z][a-z0-9+.-]*):/i.exec(url)
+  return m ? m[1]!.toLowerCase() : ""
+}
+
+const unsupported = (what: string, channel: string): Error =>
+  new Error(`${what} isn't available on this host — it needs the "browser" plugin (app.json "plugins"), a registered "${channel}" ${channel === SHEET_NAME ? "service" : "view"}.`)
+
+// ---- the sheet -------------------------------------------------------------------------------------
+
+let sheet: BrowserBase | null = null
+const service = (): BrowserBase => sheet ??= new BrowserBase()
+
+const openSheet = (url: string, options: BrowserOpenOptions): Promise<string | null> => new Promise((resolve, reject) => {
+  if (!BrowserBase.supports(SHEET_NAME)) return reject(unsupported("Browser.open", SHEET_NAME))
+  const stops = returnUrls(options)
+  const schemes = new Set(stops.map(schemeOf))
+  if (schemes.size > 1) return reject(new Error("Browser.open: every returnUrl must share one scheme — the platform intercepts one."))
+  const scheme = stops.length ? [...schemes][0]! : ""
+  const wire: { callbackScheme?: string, ephemeral?: boolean, color?: string } = {}
+  // A custom scheme is what a platform can intercept; an https return is the app's verified link,
+  // which reaches it as a "url" event like any deep link.
+  if (scheme && scheme !== "http" && scheme !== "https") wire.callbackScheme = scheme
+  if (options.ephemeral) wire.ephemeral = true
+  if (options.color) wire.color = options.color
+
+  let done = false
+  const off = stops.length ? _onAppUrl(back => {
+    if (!matching(back, stops)) return
+    finish(back)
+    service().dismiss().catch(() => {})
+  }) : () => {}
+  const finish = (back: string | null): void => {
+    if (done) return
+    done = true
+    off()
+    resolve(back)
+  }
+  service().show(url, wire).then(
+    result => finish(result?.url ?? null),
+    error => { if (done) return; done = true; off(); reject(error) },
+  )
+})
+
+// ---- the embedded page ----------------------------------------------------------------------------
+
+const openEmbedded = (url: string, options: BrowserOpenOptions): Promise<string | null> => new Promise((resolve, reject) => {
+  if (!WebViewBase.supports(VIEW_NAME)) return reject(unsupported("Browser.open({ embedded: true })", VIEW_NAME))
+  const stops = returnUrls(options)
+  const params: WebViewParams = { url, stops }
+  if (options.ephemeral) params.ephemeral = true
+  const view = new WebViewBase(params)
+
+  const title = UIText(options.title ?? "")
+    .style({ flex: 1, fontSize: 16, fontWeight: "600", color: theme.text, textAlign: "center", lineClamp: 1 })
+  const close = UIButton(UIText("✕").style({ fontSize: 20, color: theme.text }))
+    .style({ width: 44, height: 44, alignItems: "center", justifyContent: "center" })
+  const bar = UIRow(close, title, UIBox().style({ width: 44 }))
+    .style({ pt: "safe-top", alignItems: "center", bgColor: theme.surface, borderBottomWidth: 1, borderColor: theme.border })
+  const screen = UIScreen(bar, view.style({ flex: 1 })).style({ bgColor: theme.bg })
+
+  // Where it goes: onto the Router when its page is what is on screen, else in place of what is —
+  // and back to it after.
+  const previous = Presentable.current
+  const routed = previous !== null && previous === Router.current
+  let left = false
+  const leave = (): void => {
+    if (left) return
+    left = true
+    if (routed) Router.pop()
+    else { screen.close(); previous?.open() }
+  }
+  let done = false
+  const finish = (back: string | null): void => {
+    if (done) return
+    done = true
+    leave()
+    resolve(back)
+  }
+  view.on("stop", ({ url: back }) => finish(back))
+  view.on("exit", () => finish(null))
+  view.on("load", ({ title: loaded }) => { if (loaded) title.text = loaded })
+  close.onClick(() => finish(null))
+  screen.onBack(() => finish(null))
+  // Gone by another hand (the back swipe popped it, another destination replaced it): the flow is
+  // over and there is nothing left to leave.
+  screen.onClose(() => { left = true; finish(null) })
+
+  if (routed) Router.push(screen)
+  else screen.open()
+})
+
+// ---- the app's side -------------------------------------------------------------------------------
+
+/**
+ * Web content inside the app. `Browser.isSupported` reports whether this host registered the
+ * system sheet; `WebView.isSupported` the embedded page.
+ */
+// PURE IIFE so an app that never opens a page tree-shakes the whole plugin away.
+export const Browser: {
+  /** Whether this host registered the "browser" service — the system sheet. */
+  readonly isSupported: boolean
+  /** Open `url`: in the system sheet, or (`embedded`) in a WebView under a close bar. Resolves
+   *  with the return URL reached (`returnUrl`), or null when the user left. */
+  open(url: string, options?: BrowserOpenOptions): Promise<string | null>
+} = /*#__PURE__*/ (() => {
+  const browser = {
+    open: (url: string, options: BrowserOpenOptions = {}): Promise<string | null> =>
+      options.embedded ? openEmbedded(url, options) : openSheet(url, options),
+  }
+  Object.defineProperty(browser, "isSupported", { get: (): boolean => BrowserBase.supports(SHEET_NAME) })
+  return browser as any
+})()
+
+/**
+ * Create an embedded page. `WebView.isSupported` reports whether this host has the capability —
+ * check it before offering the feature.
+ */
+// PURE IIFE so an app that never embeds a page tree-shakes the view away.
+export const WebView: {
+  (params?: WebViewParams): WebView
+  /** Whether this host registered a "webView" view. */
+  readonly isSupported: boolean
+  /** Whether the host's half has `method`: false on a host whose half is older than it. */
+  supports(method: WebViewMethod): boolean
+} = /*#__PURE__*/ (() => {
+  const factory = (params?: WebViewParams): WebView => new WebViewBase(params) as unknown as WebView
+  Object.defineProperty(factory, "isSupported", { get: (): boolean => viewSupports() })
+  factory.supports = viewSupports
+  return factory as any
+})()