lecodes-sdk 2.4.1 → 2.4.3

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

@@ -16,14 +16,14 @@
 // horizontal plane the session reports, so the halves know no root.
 
 import {
-  Geometry, Mat4, Material, Mesh, Node, Presentable, Quat, Scene, System, Vec3, _ensurePermission, _navEpoch, _toFile,
+  Geometry, Mat4, Material, Mesh, Node, Presentable, Quat, Router, Scene, System, Vec3, _ensurePermission, _navEpoch, _toFile,
   type ClickEvent, type DismissOptions, type FetchResponse, type File, type NodeEvents, type PresentOptions,
   type QuatLike, type SceneOptions, type TouchStartEvent, type Vec3Like,
 } from "../../../../plugin"
 import { ARBase, supports } from "./ar.gen"
 import { attachControls, type ControlsHandle, type ControlsOptions } from "./controls"
 import type {
-  ARErrorCode, ARMode, HitTarget, ImageTarget, PlaneChange, PlaneDetection, PlaneType, Pose, StartOptions,
+  ARErrorCode, ARMode, HitTarget, ImageTarget, PlaneChange, PlaneDetection, PlaneType, Pose, QRTarget, StartOptions,
   TrackingReason, TrackingState, WorldAlignment,
 } from "../contract"
 
@@ -60,12 +60,12 @@ export type ARError = { code: ARErrorCode, message: string }
 export type ARPlaneEvent = { plane: ARPlane, change: PlaneChange, mergedInto: ARPlane | null }
 
 export type ARSceneOptions = SceneOptions & {
-  /** "world" (default): planes, hit tests, anchors, image targets. "images": image targets only —
-   *  lighter on iOS; no planes, no hit test, no `root`. */
+  /** "world" (default): planes, hit tests, anchors, image and QR targets. "images": image and QR
+   *  targets only — lighter on iOS; no planes, no hit test, no `root`. */
   mode?: ARMode
 }
 
-export type AROpenOptions = PresentOptions & Omit<StartOptions, "mode" | "images"> & {
+export type AROpenOptions = PresentOptions & Omit<StartOptions, "mode" | "images" | "codes"> & {
   /** The scene's ambient (its `environmentIntensity`) follows the estimated light; turns
    *  `lightEstimation` on. */
   followLight?: boolean
@@ -76,6 +76,13 @@ export type ARSceneEvents = {
   plane: (event: ARPlaneEvent) => void
   light: (estimate: ARLightEstimate) => void
   error: (error: ARError) => void
+  /** The session ended on its own — the user left it (the back gesture of an immersive web session)
+   *  or the system took it — and the scene leaves: popped when it is the router's top, else closed
+   *  (`onClose` is where an app opens what comes next, as after `scene.close()`). Not an error. Sent
+   *  before the scene leaves. (A `Router.pop()` of an AR scene by the app does NOT end its session:
+   *  a covered scene comes back with it — on the web an immersive session then stays on; `close()`
+   *  ends it.) */
+  end: (reason: "user" | "system") => void
 }
 
 export type AnchorEvents = NodeEvents & {
@@ -97,9 +104,10 @@ const wirePose = (p: ARPoseLike): Pose => {
 }
 
 /**
- * A node the AR session drives: it follows a place in the room (`scene.anchor(pose)`, `scene.root`)
- * or an image (`scene.createAnchor(image)`). Put content under it. `tracked` says whether the session
- * holds it now; `track` / `untrack` fire when that changes.
+ * A node the AR session drives: it follows a place in the room (`scene.anchor(pose)`, `scene.root`),
+ * an image (`scene.createAnchor(image)`) or a QR code (`scene.createQRAnchor(text, size)`). Put
+ * content under it. `tracked` says whether the session holds it now; `track` / `untrack` fire when
+ * that changes.
  */
 export class Anchor extends Node {
   /** @internal */
@@ -134,13 +142,16 @@ export class Anchor extends Node {
 }
 
 /**
- * An anchor that follows an image (`scene.createAnchor(image, physicalWidth)`): while tracked it sits on
- * the image — a rigid pose in metres, no scale: its centre, Y out of the image, the image in X (its
- * width) and Z (towards its bottom). How big the image is, is `extent`.
+ * An anchor that follows an image (`scene.createAnchor(image, physicalWidth)`) or a printed QR code
+ * (`scene.createQRAnchor(text, size)`, `code` its text): while tracked it sits on it — a rigid pose
+ * in metres, no scale: its centre, Y out of it, the image in X (its width; a code's top edge) and Z
+ * (towards its bottom). How big it is, is `extent`.
  */
 export class ImageAnchor extends Anchor {
   /** @internal */
   _extent: [number, number]
+  /** @internal The text of the QR code it follows; null for an image's. */
+  _code: string | null = null
 
   constructor(physicalWidth: number) {
     super()
@@ -149,8 +160,12 @@ export class ImageAnchor extends Anchor {
 
   /** [width, height] in metres, along the anchor's X and Z: the session's estimate of the printed
    *  image, refined while it tracks it. Before the image is first found: [physicalWidth, 0] — the
-   *  height comes with the image's proportions, which the session reads, at the first `track`. */
+   *  height comes with the image's proportions, which the session reads, at the first `track`. A QR
+   *  code's is [size, size] from the start (a code is square). */
   get extent(): [number, number] { return [this._extent[0], this._extent[1]] }
+
+  /** The text of the QR code the anchor follows (`createQRAnchor`); null for an image's. */
+  get code(): string | null { return this._code }
 }
 
 /** A surface the session found: a floor, a table, a wall. Its node sits at the plane's centre with Y
@@ -265,11 +280,15 @@ export class ARScene extends Scene {
   private _shown: { promise: Promise<void>, resolve: () => void, reject: (error: Error) => void, epoch: number } | null = null
   /** The open's start while it is out (`_begin`). `closed`: close() ended its session meanwhile — the
    *  half refuses a start its close cut short ("failed"), which is the close's doing: the open was
-   *  superseded, not failed. `images`: the image targets changed meanwhile, which the start did not
-   *  carry (it read them when it was sent) — the set goes to the session once it runs. */
-  private _startOut: { session: ARBase, closed: boolean, images: boolean } | null = null
-  /** A `setImages` is due at the end of this turn (`_setImages`). */
-  private _imagesDue = false
+   *  superseded, not failed. `images` / `codes`: the image / QR targets changed meanwhile, which the
+   *  start did not carry (it read them when it was sent) — the set goes to the session once it runs. */
+  private _startOut: { session: ARBase, closed: boolean, images: boolean, codes: boolean } | null = null
+  /** A `setImages` / `setCodes` is due at the end of this turn (`_setTargets`). */
+  private readonly _due = { images: false, codes: false }
+  /** The QR targets (`createQRAnchor`). */
+  private readonly _codes: { anchor: ImageAnchor, text: string, size: number }[] = []
+  /** This host's half is older than the QR targets: said once. */
+  private _codesWarned = false
   private _options: AROpenOptions = {}
   private _root: Anchor | null = null
   /** The first horizontal plane's pose: where `root` is pinned. */
@@ -335,7 +354,34 @@ export class ARScene extends Scene {
     this.add(anchor)
     const id = (source as unknown as { _h: Handle })._h.id
     this._images.push({ anchor, image: _toFile({ systemId: id, name: "image", size: 0 }), width: physicalWidth, source })
-    this._setImages()
+    this._setTargets("images")
+    return anchor
+  }
+
+  /** An anchor that follows a printed QR code whose text is `text`: the session finds the symbol in
+   *  the camera image and keeps the anchor on it, as on an image — a rigid pose in metres (its centre,
+   *  Y out of the symbol, X along its top edge, Z towards its bottom), `anchor.extent` = [size, size].
+   *  `size` = the printed side of the symbol in metres (its modules, no quiet zone): how far it is
+   *  comes from it. Hidden while not tracked. Before `open()`, or any time: on a running scene the set
+   *  of codes is updated in place. The web finds codes first (WebXR); on a host whose `ar` plugin does
+   *  not track them the anchor is never tracked, and the console says so. `text` null or "" = ANY
+   *  code: the first symbol decoded (a test, a plaque whose text the app does not know). */
+  createQRAnchor(text: string | null, size: number): ImageAnchor {
+    const anchor = new ImageAnchor(size)
+    anchor._code = text ?? ""
+    anchor._extent = [size, size]
+    anchor._scene = this
+    anchor._hideUntracked = true
+    anchor.visible = false
+    this.add(anchor)
+    // a half older than the codes (contract version 2) has no setCodes, and its start reads no codes
+    if (ARScene.isSupported && !supports("setCodes")) {
+      if (!this._codesWarned) console.warn('ARScene: this host\'s "ar" plugin tracks no QR codes (it is older than contract version 2) — their anchors are never tracked')
+      this._codesWarned = true
+      return anchor
+    }
+    this._codes.push({ anchor, text: text ?? "", size })
+    this._setTargets("codes")
     return anchor
   }
 
@@ -486,6 +532,7 @@ export class ARScene extends Scene {
     const options: StartOptions = { ...rest, mode: this.mode }
     if (followLight) options.lightEstimation = true
     if (this._images.length) options.images = this._targets()
+    if (this._codes.length) options.codes = this._codeTargets()
     return options
   }
 
@@ -493,6 +540,10 @@ export class ARScene extends Scene {
     return this._images.map(t => ({ image: t.image, physicalWidth: t.width, entity: t.anchor }))
   }
 
+  private _codeTargets(): QRTarget[] {
+    return this._codes.map(t => ({ text: t.text, size: t.size, entity: t.anchor }))
+  }
+
   private async _begin(): Promise<void> {
     const epoch = _navEpoch()
     const superseded = (why = "another destination was opened") => new Error(`ARScene.open() superseded: ${why} while preparing`)
@@ -524,9 +575,19 @@ export class ARScene extends Scene {
       this._drop(session)
       this._emit("error", { code: p.code, message: p.message })
     })
+    session.on("ended", p => {
+      if (this._session !== session || !p) return
+      // over, not by close(): the scene goes with it — the user's back gesture, as the router's:
+      // popped when it is the router's top (the page under it shows), else closed (what it replaced
+      // comes back through its onClose — `open()` took that destination's place)
+      this._drop(session)
+      this._emit("end", p.reason)
+      if (Router.current === this) Router.pop()
+      else this.close()
+    })
     this._session = session
     this._baseIntensity = this.environmentIntensity
-    const out = { session, closed: false, images: false }
+    const out = { session, closed: false, images: false, codes: false }
     this._startOut = out
     try {
       await session.start(this._startOptions())
@@ -545,8 +606,9 @@ export class ARScene extends Scene {
       throw superseded()
     }
     this._pinAll()
-    // the image targets changed while the start was out: the running session takes the set now
-    if (out.images) this._setImages()
+    // the image / QR targets changed while the start was out: the running session takes the set now
+    if (out.images) this._setTargets("images")
+    if (out.codes) this._setTargets("codes")
   }
 
   /** The session is over (closed, failed): every anchor untracked, the planes gone. */
@@ -571,32 +633,34 @@ export class ARScene extends Scene {
     this._planes.clear()
     for (const anchor of this._pinned) anchor._setTracked(false)
     for (const image of this._images) image.anchor._setTracked(false)
+    for (const code of this._codes) code.anchor._setTracked(false)
     this._root?._setTracked(false)
     if (this._options.followLight) this.environmentIntensity = this._baseIntensity
   }
 
-  /** The image targets changed (one added or removed): a running session takes the whole set in place
-   *  (`setImages` — the tracking, the planes and the anchors stay). Sent at the end of the turn: several
-   *  targets added in a row are one set. While the open's start is out it waits for it (the start
-   *  carried the set it read when it was sent); before a session there is nothing to tell — the start
-   *  carries the set. Nothing waits for it: a set the half refuses is a console line, and an anchor
-   *  whose image the session did not take never tracks. */
-  private _setImages(): void {
+  /** The image targets or the QR targets changed (one added or removed): a running session takes the
+   *  whole set in place (`setImages` / `setCodes` — the tracking, the planes and the anchors stay). Sent
+   *  at the end of the turn: several targets added in a row are one set. While the open's start is out
+   *  it waits for it (the start carried the set it read when it was sent); before a session there is
+   *  nothing to tell — the start carries the set. Nothing waits for it: a set the half refuses is a
+   *  console line, and an anchor whose target the session did not take never tracks. */
+  private _setTargets(kind: "images" | "codes"): void {
     const session = this._session
     if (!session) return
     const out = this._startOut
-    if (out && out.session === session) { out.images = true; return }
-    if (this._imagesDue) return
-    this._imagesDue = true
+    if (out && out.session === session) { out[kind] = true; return }
+    if (this._due[kind]) return
+    this._due[kind] = true
     void Promise.resolve().then(() => {
-      this._imagesDue = false
+      this._due[kind] = false
       // closed meanwhile: a call on the closed channel would open a new session (the next open's start
       // carries the set)
       if (this._session !== session) return
-      session.setImages(this._targets()).catch((e: unknown) => {
+      const sent = kind === "images" ? session.setImages(this._targets()) : session.setCodes(this._codeTargets())
+      sent.catch((e: unknown) => {
         // a close while it was out: the half's refusal is the close's, nothing failed
         if (this._session !== session) return
-        console.warn(`ARScene: the session did not take the image targets (${e instanceof Error ? e.message : String(e)}) — their anchors are not tracked`)
+        console.warn(`ARScene: the session did not take the ${kind === "images" ? "image targets" : "QR codes"} (${e instanceof Error ? e.message : String(e)}) — their anchors are not tracked`)
       })
     })
   }
@@ -643,10 +707,13 @@ export class ARScene extends Scene {
     if (anchor === this._root) this._root = null
     const image = this._images.findIndex(t => t.anchor === anchor)
     if (image >= 0) this._images.splice(image, 1)
+    const code = this._codes.findIndex(t => t.anchor === anchor)
+    if (code >= 0) this._codes.splice(code, 1)
     this._wire("release", s => s.release(anchor)).catch(() => {})
     anchor._setTracked(false)
     this.remove(anchor)
-    if (image >= 0) this._setImages()
+    if (image >= 0) this._setTargets("images")
+    if (code >= 0) this._setTargets("codes")
   }
 
   private _onPlane(p: { change: PlaneChange, id: number, type: PlaneType, pose: Pose, extent: number[], polygon: number[], mergedInto?: number }): void {

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

@@ -8,6 +8,9 @@
 //   const back = await Browser.open(checkoutUrl, { returnUrl: [paid, failed], embedded: true })
 //                                                                  a checkout in an embedded page,
 //                                                                  resolved with the URL it reached
+//                                                                  (navigated to in the page, or
+//                                                                  opened by a bank's app through
+//                                                                  the app's verified link)
 //
 // 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;
@@ -38,7 +41,8 @@ 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. */
+   *  verified links (app.json `appLinks`). Embedded, the view intercepts the navigation itself,
+   *  and a verified https return from another app (a bank's) ends the page too. */
   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. */
@@ -157,10 +161,16 @@ const openEmbedded = (url: string, options: BrowserOpenOptions): Promise<string
     if (routed) Router.pop()
     else { screen.close(); previous?.open() }
   }
+  // Two ways the return URL arrives: the page navigates to it inside the view (`stop`), or
+  // another app does — a bank's app the checkout handed off to sends the person back through the
+  // app's verified link (app.json "appLinks"), which reaches the app as its "url" event while the
+  // page still shows the bank's form. Both end the flow; `done` makes the second a no-op.
   let done = false
+  const off = stops.length ? _onAppUrl(back => { if (matching(back, stops)) finish(back) }) : () => {}
   const finish = (back: string | null): void => {
     if (done) return
     done = true
+    off()
     leave()
     resolve(back)
   }

package/src/version.ts

@@ -4,7 +4,7 @@
 // same manifest). Its MAJOR is the bundle ↔ runtime contract: a bundle's `// sdk:` header line
 // and a host's embedded version must agree on the major for the host to run the bundle; minor
 // and patch never gate anything (features are detected, never versioned).
-export const SDK_VERSION = "2.4.1"
+export const SDK_VERSION = "2.4.3"
 
 /** The major of a semver string, or null when it is not one. */
 export const sdkMajor = (version: string | null | undefined): number | null => {