lecodes-sdk 2.6.0 → 2.8.1

package/package.json

@@ -40,10 +40,10 @@
     "@types/node": "^25.9.1",
     "typescript": "~5.8.3",
     "gl-matrix": "^3.4.4",
-    "marcidb-embedded": "^0.15.0",
+    "marcidb-embedded": "^0.18.0",
     "sharp": "^0.35.2"
   },
-  "version": "2.6.0",
+  "version": "2.8.1",
   "files": [
     "src",
     "dist",

package/src/bridges/tree.d.ts

@@ -217,6 +217,11 @@ declare global {
  *  listeners are a flag mask, events go back through the runtime's entry points with the node id.
  *  One implementation per platform: renderers/tgfx (desktop, Quest), the Kotlin views (Android),
  *  UIKit (Apple), the null renderer of lecodes-server.
+ *  The runtime calls it through a QUEUE (runtime/native src/host/hostqueue.h, docs/plans/
+ *  host-commit-plan.md): a write reaches the host at the next commit — the end of the tick, before
+ *  a layout, before a read — in the order the runtime made it; a slot with a result commits first
+ *  and answers at once; an `@immediate` slot commits first and is called at once (its callbacks and
+ *  borrowed values are never kept).
  *  @host ui HostUI */
 export interface HostUI {
   /** Create the host view for a node of `type` ("column", "text", "image", "input", "screen", …).
@@ -259,7 +264,8 @@ export interface HostUI {
   viewVersion?(name: string): i32
   /** NativeView channel: invoke `method` on the live instance `viewId`; `args` is the array of the
    *  call's arguments, valid for the call. Settle exactly one of the two callbacks through the
-   *  dispatch bridge — `onComplete` with the result as ONE value, or with none. */
+   *  dispatch bridge — `onComplete` with the result as ONE value, or with none.
+   *  @immediate its callbacks and the borrowed `args` cannot wait for a commit */
   viewCall?(viewId: i32, method: string, args: value, onComplete: (result?: value) => void, onReject: (message: string) => void): void
   /** A LAYER root is shown: a pass-through root the runtime lays out at the frame, above every
    *  destination (the app layer) or over the presented surface (a scene's / a native view's / a
@@ -272,8 +278,10 @@ export interface HostUI {
   /** The layer root is hidden (its view stays; releaseNode says when it is gone). */
   layerClose(node: nodeid): void
   /** Load a font face for `fontFamily` (weight 100–900, style 0 normal / 2 italic) from `url`; settle
-   *  one of the callbacks through the dispatch bridge. */
+   *  one of the callbacks through the dispatch bridge.
+   *  @immediate its callbacks cannot wait for a commit */
   registerFont(url: string, fontFamily: string, weight: i32, style: i32, onComplete: () => void, onReject: (err: string) => void): void
+  /** @immediate not a tree write */
   showToast(message: string, duration: i32): void
   /** Is the button node currently pressed (the UIButton.isPressed getter)? */
   getButtonPressed(node: nodeid): boolean
@@ -284,9 +292,11 @@ export interface HostUI {
    *  it. @out 4 */
   getBoundingRect?(node: nodeid): Float32Array | null
   /** A node's touchStart / longPress listener took the gesture (`ev.track`): keep feeding this
-   *  pointer's moves (`claim` = a PanDirection bitmask, `hasMove` = it wants onMove). */
+   *  pointer's moves (`claim` = a PanDirection bitmask, `hasMove` = it wants onMove).
+   *  @immediate the answer belongs to the gesture the host is tracking */
   touchHandler?(pointerId: i32, hasMove: boolean, claim: u8, node: nodeid): void
-  /** A long press was HANDLED: swallow the click that would follow the release. */
+  /** A long press was HANDLED: swallow the click that would follow the release.
+   *  @immediate the answer belongs to the gesture the host is tracking */
   longPressHandler?(pointerId: i32, node: nodeid): void
   /** Virtualized list: apply a scroll position (physical px). `animated` false = anchoring (idempotent,
    *  after the content height update), true = a user scroll command. */

package/src/compile/serverSplit.ts

@@ -2,14 +2,15 @@
  * The client/server split of a project (docs/backend-plan.md §4).
  *
  * `*.server.ts` files never reach the client bundle: `compileProject` swaps each one for a STUB
- * module whose exports are RPC/channel proxies (`__rpc`, `__channel`, `__pushChannel`, `__serverOnly` — client SDK
+ * module whose exports are RPC/channel proxies (`__rpc`, `__channel`, `__computed`, `__pushChannel`, `__serverOnly` — client SDK
  * globals, src/runtime/rpc.ts), so `import { listNotes } from "./notes.server"` in client code keeps
  * its types and calls the server. `compileServerBundle` bundles the same files with the SERVER inject
  * behind a synthetic entry that registers every module on `globalThis.__lecodesServer` (chisel keeps
  * side effects, not entry exports) — the runner reads that (src/server/runtime.ts).
  *
  * Export kinds are found by a static scan (no TS program needed): a function export is an
- * endpoint, a `channel<…>()…` export is a channel, a `pushChannel<…>()` export a push channel, anything else is server-only.
+ * endpoint, a `channel<…>()…` export is a channel, a `computed(…)` export a computed (an endpoint the app
+ * may also subscribe to), a `pushChannel<…>()` export a push channel, anything else is server-only.
  */
 
 import type { AppConfig } from "../server/auth/appConfig"
@@ -26,11 +27,12 @@ export const serverModuleId = (path: string) => path.split("\\").join("/").repla
 
 /**
  * What an export of a server module is to the app: `fn` = an endpoint — an ASYNC function, called
- * over the network; `channel` = a channel; `other` = server-only — a model, the db, a constant, or
+ * over the network; `channel` = a channel; `computed` = a computed (../server/computed.ts): called like
+ * an endpoint, or subscribed to; `push` = a push channel; `other` = server-only — a model, the db, a constant, or
  * a helper: a function that is not async is used by server files alone, and the app's import of
  * it is refused at compile time (serverTypes.ts), never a call that silently holds a promise.
  */
-export type ServerExportKind = "fn" | "channel" | "push" | "other"
+export type ServerExportKind = "fn" | "channel" | "computed" | "push" | "other"
 export type ServerExport = { name: string, kind: ServerExportKind }
 
 // ───────────────────────────── static export scan ─────────────────────────────
@@ -86,6 +88,7 @@ const IDENT = "[A-Za-z_$][\\w$]*"
 const classifyInit = (init: string): ServerExportKind => {
   const s = init.trimStart()
   if (/^channel\s*[<(]/.test(s)) return "channel"
+  if (/^computed\s*[<(]/.test(s)) return "computed"
   if (/^pushChannel\s*[<(]/.test(s)) return "push"
   if (/^async\s+function\b/.test(s)) return "fn"
   if (/^async\b/.test(s)) return "fn"                              // async (…) => / async x =>
@@ -164,6 +167,7 @@ export const serverStubSource = (path: string, exports: ServerExport[], serverUr
     const id = JSON.stringify(`${mod}#${name}`)
     if (kind === "fn") return `export const ${name} = __rpc(${url}, ${id})`
     if (kind === "channel") return `export const ${name} = __channel(${url}, ${id})`
+    if (kind === "computed") return `export const ${name} = __computed(${url}, ${id})`
     if (kind === "push") return `export const ${name} = __pushChannel(${url}, ${id})`
     return `export const ${name} = __serverOnly(${id})`
   })

package/src/compile/serverTypes.ts

@@ -14,7 +14,8 @@
  * "endpoint args must be JSON-serializable". Return types are not validated.
  *
  * A channel's `groupBy(fn)` is the same case: `fn` is called with what the app passed to
- * `subscribe`, so its parameters get a schema under the channel's id.
+ * `subscribe`, so its parameters get a schema under the channel's id; and so is a `computed(fn)` —
+ * called and subscribed to with the same arguments, under the computed's id.
  *
  * `typescript` is loaded lazily (it's a devDependency of the SDK and a dependency of the platform
  * compile step); the browser-safe parts of the compiler never import this module's runtime.
@@ -252,6 +253,11 @@ export const deriveEndpointParams = async (entries: CompileEntry[], modules: Rec
         if (!hook) { params[id] = []; continue }
         type = checker.getTypeAtLocation(hook)
         where = `${id}.groupBy`
+      } else if (ex.kind === "computed") {
+        // `computed` too: its function is the call's first argument
+        const fn = computedFn(ts, decl)
+        if (!fn) { params[id] = []; continue }
+        type = checker.getTypeAtLocation(fn)
       } else {
         type = checker.getTypeOfSymbolAtLocation(sym, decl)
       }
@@ -261,8 +267,8 @@ export const deriveEndpointParams = async (entries: CompileEntry[], modules: Rec
       for (const p of sig.getParameters()) {
         const pd = p.valueDeclaration as import("typescript").ParameterDeclaration | undefined
         // nothing here gives a hook's parameter a type but its own annotation — without one it is `any`, unchecked
-        if (ex.kind === "channel" && pd && !pd.type && !pd.initializer) {
-          problems.push(`${where}(${p.name}): give the parameter a type — it is what the app passes to subscribe, and it is checked against it`)
+        if ((ex.kind === "channel" || ex.kind === "computed") && pd && !pd.type && !pd.initializer) {
+          problems.push(`${where}(${p.name}): give the parameter a type — it is what the app passes to ${ex.kind === "channel" ? "subscribe" : "the call and to subscribe"}, and it is checked against it`)
           continue
         }
         const ptype = checker.getTypeOfSymbolAtLocation(p, pd ?? decl)
@@ -294,6 +300,14 @@ export const deriveEndpointParams = async (entries: CompileEntry[], modules: Rec
   return { params, warnings }
 }
 
+/** The function a computed export is made of (`computed(async (…) => …)`). */
+const computedFn = (ts: TS, decl: import("typescript").Declaration): import("typescript").Expression | null => {
+  let node: import("typescript").Expression | undefined = ts.isVariableDeclaration(decl) ? decl.initializer : undefined
+  while (node && (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isNonNullExpression(node))) node = node.expression
+  if (node && ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "computed") return node.arguments[0] ?? null
+  return null
+}
+
 /** The function given to `.groupBy(…)` in a channel export's initializer (`channel<M>().authorize(…).groupBy(fn)`). */
 const groupByHook = (ts: TS, decl: import("typescript").Declaration): import("typescript").Expression | null => {
   let node: import("typescript").Expression | undefined = ts.isVariableDeclaration(decl) ? decl.initializer : undefined

package/src/inject.ts

@@ -43,8 +43,9 @@ export { WebSocket } from "./runtime/net"
 // Multiplayer (docs/multiplayer-plan.md): roles, players, JSON messages over the _creatorNet transport.
 export { Net, NetPlayer, Replicated, NetEntity, type NetMessage, type NetRole, type NetStatus, type NetEvents, type NetLaunch, type NetInput, type NetKind, type NetTransform, type NetCorrection } from "./net"
 // App-backend transport: the compiler-generated stubs of `*.server.ts` modules call these; user code
-// only ever imports its server functions (docs/backend-plan.md §4).
-export { __rpc, __channel, __pushChannel, __serverOnly, RpcError } from "./runtime/rpc"
+// only ever imports its server functions (docs/backend-plan.md §4) — and reads `online`, whether the
+// transport reaches the backend.
+export { __rpc, __channel, __computed, __pushChannel, __serverOnly, RpcError, online } from "./runtime/rpc"
 // The font() compile macro's generated `.__fonts.ts` modules call this per face (UI tree + Font2D).
 export { __registerFont } from "./ui/fonts"
 // What a screen asks of the server, as reactive state: a request a screen follows, an action with its own busy / error.
@@ -62,6 +63,8 @@ export { audio, type PlaySoundOptions, type SpatialOptions, type Rolloff, type A
 export { openFilePicker, files, type FileData } from "./runtime/files"
 export { share } from "./runtime/share"
 export { ClickEvent, TouchStartEvent, LongPressEvent, MouseEnterEvent } from "./runtime/touch"
+// Pan, pinch and twist as one gesture over the per-pointer tracks (see src/runtime/gestures.ts).
+export { trackGesture, type Gesture, type GestureHandler, type GestureTarget } from "./runtime/gestures"
 
 // ---- 2D engine (creator-2d) ----
 export { Scene2D } from "./g2/Scene2D"

package/src/plugin.ts

@@ -31,7 +31,8 @@ export type { NativeView } from "./ui/NativeView"
 export type { FetchResponse } from "./runtime/fetch"
 // The 3D a wrapper builds on (the "ar" plugin's ARScene — docs/plans/ar-plugin-plan.md): the scene it
 // extends, the node its anchors are, the mesh it draws a plane's grid with, the math of a pose, the
-// touch a placement gesture follows, the System its per-frame work rides on (the scene's first frame).
+// touch a placement gesture follows (and `trackGesture`, the pan / pinch / twist over it), the System
+// its per-frame work rides on (the scene's first frame).
 // Re-exported, never copied, as the UI above.
 export { Scene, type SceneOptions } from "./gl/Scene"
 export { System } from "./core/Aspect"
@@ -43,6 +44,7 @@ export { Vec2, Vec3, type Vec3Like } from "./math/vec"
 export { Quat, type QuatLike } from "./math/quat"
 export { Mat4 } from "./math/mat4"
 export type { ClickEvent, TouchStartEvent } from "./runtime/touch"
+export { trackGesture, type Gesture, type GestureHandler, type GestureTarget } from "./runtime/gestures"
 export type { DismissOptions } from "./ui/presentable"
 /** The seam the push plugin's wrapper installs its runtime on (src/runtime/pushSeam.ts): what the app's transport
  *  reads the device's address from, registers through, and a push channel's handlers are kept by. */

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

@@ -12,8 +12,8 @@
 // the present (a host mounts and sizes the scene's view after it). A host without the plugin is
 // refused before anything is asked.
 //
-// `root` is a pose anchor like any other (`scene.anchor(pose)`): the wrapper pins it on the first
-// horizontal plane the session reports, so the halves know no root.
+// `root` is a pose anchor like any other (`scene.anchor(pose)`), placed by the wrapper — in front of
+// the user on the first floor the session reports (`_placeRoot`) — so the halves know no root.
 
 import {
   Geometry, Mat4, Material, Mesh, Node, Presentable, Quat, Router, Scene, System, Vec3, _ensurePermission, _navEpoch, _toFile,
@@ -63,6 +63,9 @@ export type ARSceneOptions = SceneOptions & {
   /** "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
+  /** How far in front of the user `root` is placed, metres (default 1): along the camera's heading,
+   *  on the floor. */
+  rootDistance?: number
 }
 
 export type AROpenOptions = PresentOptions & Omit<StartOptions, "mode" | "images" | "codes"> & {
@@ -269,6 +272,8 @@ export class ARScene extends Scene {
   static get isSupported(): boolean { return supports() }
 
   readonly mode: ARMode
+  /** Metres between the user and `root` when it is placed (`rootDistance` option, default 1). */
+  readonly rootDistance: number
   /** `open()` warm-renders the scene first (default true). */
   useWarmRender = true
 
@@ -291,8 +296,9 @@ export class ARScene extends Scene {
   private _codesWarned = false
   private _options: AROpenOptions = {}
   private _root: Anchor | null = null
-  /** The first horizontal plane's pose: where `root` is pinned. */
-  private _floor: ARPose | null = null
+  /** The floor's height (world Y, metres): the first horizontal plane below the camera this session
+   *  found. Null until one is; `root` is placed on it. */
+  private _floor: number | null = null
   /** The image targets. `source` is held for the bytes: a fetched response owns its buffer, which the
    *  host frees once the response is collected — the File the session is handed only names it. */
   private readonly _images: { anchor: ImageAnchor, image: File, width: number, source: FetchResponse | File }[] = []
@@ -310,6 +316,7 @@ export class ARScene extends Scene {
   constructor(options: ARSceneOptions = {}) {
     super(options)
     this.mode = options.mode ?? "world"
+    this.rootDistance = options.rootDistance ?? 1
   }
 
   /** The tracking quality: "notAvailable" before a session, "limited" (with `trackingReason`) while
@@ -328,8 +335,12 @@ export class ARScene extends Scene {
     for (const plane of this._planes.values()) this._drawPlane(plane)
   }
 
-  /** The floor: an anchor pinned on the first horizontal plane the session finds (it fires `track`
-   *  then). Until that it is the world's origin — where the session began. Not in "images" mode. */
+  /** The place in front of the user: an anchor `rootDistance` metres ahead of the camera along its
+   *  heading, on the floor — the first horizontal plane below the camera the session finds; it is
+   *  pinned there and fires `track` then — turned the way the user looks (its −Z along the heading,
+   *  so a model's front, +Z, faces the user). Until the floor is found (and on the web, which finds
+   *  none) it sits the same way at the camera's own height, not pinned. Made on first use; put
+   *  content under it. `placeRoot()` puts it in front of the user again. Not in "images" mode. */
   get root(): Anchor {
     if (this._root) return this._root
     if (this.mode === "images") throw new Error('ARScene.root: there is no root in the "images" mode')
@@ -337,10 +348,19 @@ export class ARScene extends Scene {
     root._scene = this
     this.add(root)
     this._root = root
-    if (this._floor) this._pinRoot(this._floor)
+    this._placeRoot()
     return root
   }
 
+  /** Put `root` in front of the user again — where they look now, `rootDistance` metres ahead, on the
+   *  floor if one is known (the camera's height otherwise), facing them: a "reset" button, or a
+   *  placement after the user has moved. Makes `root` when there is none yet. */
+  placeRoot(): Anchor {
+    if (!this._root) return this.root
+    this._placeRoot()
+    return this._root
+  }
+
   /** An anchor that follows an image (a printed marker, a poster): the session finds it in the camera
    *  image and keeps the anchor on it — a rigid pose in metres (its centre, Y out of the image, the
    *  image in XZ), its size `anchor.extent`. `physicalWidth` = the printed width in metres. Hidden
@@ -679,11 +699,34 @@ export class ARScene extends Scene {
     this._pin(anchor, pose)
   }
 
-  /** `root` onto the floor (the first horizontal plane of this session). */
-  private _pinRoot(pose: ARPose): void {
+  /** Where `root` goes now: `rootDistance` metres from the camera along its heading (its forward
+   *  flattened to the floor; looking straight down or up, the way the top of the screen points), at
+   *  the floor's height when one is known, else the camera's; turned so its −Z runs along the
+   *  heading — a model's front (+Z) faces the user. */
+  private _rootPose(): ARPose {
+    const camera = this.camera
+    const eye = camera.worldPosition
+    const forward = camera.forward
+    let heading = new Vec3(forward.x, 0, forward.z)
+    if (heading.lengthSq() < 1e-6) {
+      // straight down (the usual way to look at a floor) or up: the screen's top points the way
+      const up = Vec3.up.rotate(camera.worldMatrix.rotation)
+      heading = new Vec3(up.x, 0, up.z)
+      if (forward.y > 0) heading = heading.negate()
+      if (heading.lengthSq() < 1e-6) heading = new Vec3(0, 0, -1)
+    }
+    heading = heading.normalize()
+    const position = new Vec3(eye.x + heading.x * this.rootDistance, this._floor ?? eye.y, eye.z + heading.z * this.rootDistance)
+    return { position, rotation: Quat.lookRotation(heading) }
+  }
+
+  /** `root` in front of the user: moved there now, and pinned there when the floor is known (a
+   *  session holds a pin; without one `_pinAll` does not re-pin root — it waits for its own floor). */
+  private _placeRoot(): void {
     const root = this._root!
+    const pose = this._rootPose()
     root.worldMatrix = Mat4.compose(pose.position, pose.rotation)
-    this._pin(root, pose)
+    if (this._floor !== null) this._pin(root, pose)
   }
 
   private _pin(anchor: Anchor, pose: ARPoseLike): void {
@@ -741,10 +784,12 @@ export class ARScene extends Scene {
     plane._polygon = p.polygon
     plane._setTracked(true)
     this._drawPlane(plane)
-    // the floor: the first horizontal plane, where root is pinned
-    if (added && p.type === "horizontal" && !this._floor) {
-      this._floor = pose
-      if (this._root) this._pinRoot(pose)
+    // the floor: the first horizontal plane below the camera (a ceiling is "horizontal" too), where
+    // root is placed — in front of the user, at the plane's height; the plane's centre and turn are
+    // a patch's and say nothing about where the user is
+    if (added && p.type === "horizontal" && this._floor === null && pose.position.y < this.camera.worldPosition.y) {
+      this._floor = pose.position.y
+      if (this._root) this._placeRoot()
     }
     this._emit("plane", { plane, change: added ? "added" : "updated", mergedInto: null })
   }

package/src/runtime/firstCall.ts

@@ -0,0 +1,28 @@
+/**
+ * The client transport's first-call rule (./rpc.ts), kept apart so a host that calls a backend as a
+ * device — a flow's `call` step, `lecodes call` (tools/cli/src/dev/backendCall.ts) — follows the very
+ * same rule: a device with no token yet sends its first call alone and the calls behind it wait, so a
+ * backend that mints a token on first contact (`request.session`, a guest session) mints ONE — two
+ * calls in flight would each get their own and the device would end up with whichever landed last.
+ * Once per device per run: the gate opens for good when the first call is back, whether or not it
+ * brought a token. Pure: no bridges, no globals.
+ */
+
+export type FirstCallGate = <T>(hasToken: () => boolean, send: () => Promise<T>) => Promise<T>
+
+/** One gate per device (and backend): `gate(hasToken, send)` runs `send` under the rule. */
+export const firstCallGate = (): FirstCallGate => {
+  /** undefined: no call yet; a promise: the first call is out; null: it came back */
+  let first: Promise<void> | null | undefined
+  return async (hasToken, send) => {
+    if (!hasToken()) {
+      if (first) await first
+      else if (first === undefined) {
+        let release!: () => void
+        first = new Promise<void>((r) => { release = r })
+        try { return await send() } finally { first = null; release() }
+      }
+    }
+    return send()
+  }
+}

package/src/runtime/gestures.ts

@@ -0,0 +1,190 @@
+// trackGesture: one recognizer for pan, pinch and twist, built on the per-pointer tracks. Every
+// host already sends a touchstart per finger and the SDK keeps a TrackHandler per pointer id
+// (ui/tree.ts, gestures; g2/touch.ts for 2D scenes): this module only listens for those
+// touchstarts, `ev.track(...)`s each finger with its own handler, and turns the live set of
+// fingers into one reading. No runtime, contract or host part; the AR plugin's `attachControls`
+// (plugins/ar/sdk/controls.ts) is the same thing done by hand.
+//
+// Two target shapes, one adapter (`listen`):
+//   - `onTouchStart(cb)` — UIButton, UIScreen, UIWidget. Such a listener cannot be removed:
+//     `remove()` leaves the callback in place and it ignores every event from then on.
+//   - `addEventListener("touchstart", cb)` / `removeEventListener` — Scene, Scene2D, Node,
+//     Node2D. `remove()` takes the listener off.
+//
+// The reading (`Gesture`, a fresh object per callback — safe to keep) is an INCREMENT, like a
+// track's own deltaX / deltaY: every onMove reports the change since the previous onMove (or since
+// the gesture started), so applying it to the current camera / transform is one line and there is
+// no start state to keep. Moves arrive per finger, so increments compose: over any run of moves
+// the deltas sum and the scales multiply to the change of the whole set (rotations sum exactly for
+// two fingers, closely for more). Only positions are read, never a track's deltas (the web's are
+// measured from the touch-down).
+//   centerX / centerY  the centroid of the live fingers (the event's client coordinates, logical px)
+//   deltaX / deltaY    the centroid's move since the previous onMove
+//   scale              the mean finger distance to the centroid over the previous one
+//   rotation           the mean change of each finger's angle about the centroid, radians;
+//                      positive = clockwise on screen (y grows downward, so atan2(dy, dx) increasing)
+//   pointers           the number of live fingers
+// One finger is a gesture too: its moves are pans with scale 1 and rotation 0 (a finger AT the
+// centroid has no distance and no angle — that, not a finger count, is what makes them neutral;
+// three and more fingers run the same formulas). A finger joining or leaving re-bases silently: the
+// set's previous positions are its current ones, so the next onMove shows no jump. onStart (the
+// first finger) and onEnd (the last one lifted: the centroid is its end position, pointers 0) carry
+// deltas 0, scale 1, rotation 0. A cancel of any finger cancels the whole gesture: onCancel once,
+// then the remaining fingers are ignored (and a finger landing meanwhile is not taken) until all
+// have lifted; the next touch starts a new gesture. `claim` (default true) goes to every finger's
+// TrackHandler, so a scrollable above never takes the pan.
+
+import type { TouchStartEvent, TrackHandler } from "./touch"
+
+/** One reading of a gesture, handed to `onStart` / `onMove` / `onEnd` (a fresh object each time). */
+export interface Gesture {
+  /** The centroid of the live fingers, in the event's client coordinates (logical px). */
+  centerX: number
+  centerY: number
+  /** The centroid's move since the previous `onMove` (0 on start / end). */
+  deltaX: number
+  deltaY: number
+  /** Mean finger distance to the centroid over the previous one (1 with one finger, 1 on start / end). */
+  scale: number
+  /** The mean change of each finger's angle about the centroid since the previous `onMove`, radians,
+   *  positive = clockwise on screen (0 with one finger, 0 on start / end). */
+  rotation: number
+  /** The number of live fingers (0 in `onEnd`: the last one lifted). */
+  pointers: number
+}
+
+/** What `trackGesture` takes: the gesture's callbacks and the claim every finger's track makes. */
+export interface GestureHandler {
+  /** Passed to every finger's `ev.track(...)` (default `true`: a scrollable above never takes the pan). */
+  claim?: TrackHandler["claim"]
+  /** The first finger landed. */
+  onStart?(g: Gesture): void
+  /** Any finger moved: the change since the previous `onMove`. */
+  onMove?(g: Gesture): void
+  /** The last finger lifted. */
+  onEnd?(g: Gesture): void
+  /** The host cancelled one of the fingers: the whole gesture is over. */
+  onCancel?(): void
+}
+
+/** Anything that hands out touchstarts: a UI element (`onTouchStart`) or a scene / node
+ *  (`addEventListener("touchstart", …)`). */
+export type GestureTarget =
+  | { onTouchStart(callback: (ev: TouchStartEvent<any>) => void): unknown }
+  | {
+    addEventListener(channel: "touchstart", callback: (ev: TouchStartEvent<any>) => void): void
+    removeEventListener(channel: "touchstart", callback: (ev: TouchStartEvent<any>) => void): void
+  }
+
+type Finger = { id: number, x: number, y: number }
+
+// A finger this close to the centroid (logical px) has no angle, and a set this tight has no scale.
+const EPS = 1e-3
+
+/** Start listening on `target`; returns the off switch. */
+const listen = (target: GestureTarget, cb: (ev: TouchStartEvent<any>) => void): (() => void) => {
+  if ("addEventListener" in target) {
+    target.addEventListener("touchstart", cb)
+    return () => target.removeEventListener("touchstart", cb)
+  }
+  target.onTouchStart(cb)
+  return () => {}
+}
+
+/**
+ * Follow pan, pinch and twist on `target` as one gesture: every finger that lands on it is tracked,
+ * and `onMove` reports the change of the whole set since the previous move — the centroid's move,
+ * the spread's ratio, the twist's angle. One finger is a gesture too (a pan, scale 1, rotation 0).
+ *
+ * ```ts
+ * trackGesture(scene, {
+ *   onMove(g) { zoom *= g.scale; angle += g.rotation; panX += g.deltaX; panY += g.deltaY },
+ * })
+ * ```
+ */
+export const trackGesture = (target: GestureTarget, handler: GestureHandler): { remove(): void } => {
+  const fingers: Finger[] = []
+  let cancelled = false   // a finger was cancelled: ignore the rest until all have lifted
+  let removed = false
+
+  const drop = (f: Finger): boolean => {
+    const i = fingers.indexOf(f)
+    if (i < 0) return false
+    fingers.splice(i, 1)
+    if (fingers.length === 0) cancelled = false
+    return true
+  }
+
+  // One finger moved from where it was to (x, y): the set's change, before → after.
+  const step = (f: Finger, x: number, y: number): Gesture => {
+    const n = fingers.length
+    let sx = 0, sy = 0
+    for (const p of fingers) { sx += p.x; sy += p.y }
+    const c0x = sx / n, c0y = sy / n
+    const c1x = (sx - f.x + x) / n, c1y = (sy - f.y + y) / n
+    let d0 = 0, d1 = 0, turn = 0, turned = 0
+    for (const p of fingers) {
+      const ax = p.x - c0x, ay = p.y - c0y
+      const bx = (p === f ? x : p.x) - c1x, by = (p === f ? y : p.y) - c1y
+      const r0 = Math.hypot(ax, ay), r1 = Math.hypot(bx, by)
+      d0 += r0
+      d1 += r1
+      if (r0 > EPS && r1 > EPS) {
+        let a = Math.atan2(by, bx) - Math.atan2(ay, ax)
+        if (a > Math.PI) a -= 2 * Math.PI
+        else if (a <= -Math.PI) a += 2 * Math.PI
+        turn += a
+        turned++
+      }
+    }
+    f.x = x
+    f.y = y
+    return {
+      centerX: c1x, centerY: c1y, deltaX: c1x - c0x, deltaY: c1y - c0y,
+      scale: d0 > EPS * n ? d1 / d0 : 1, rotation: turned ? turn / turned : 0, pointers: n,
+    }
+  }
+
+  const onTouch = (ev: TouchStartEvent<any>): void => {
+    if (removed || cancelled) return
+    // A pointer id already in the set never got its end (its tracker was replaced): the new touch
+    // takes its place in the same gesture.
+    const stale = fingers.findIndex((p) => p.id === ev.pointerId)
+    if (stale >= 0) fingers.splice(stale, 1)
+    const first = fingers.length === 0 && stale < 0
+    const f: Finger = { id: ev.pointerId, x: ev.clientX, y: ev.clientY }
+    fingers.push(f)
+    ev.track({
+      claim: handler.claim ?? true,
+      // only when the gesture has an onMove: otherwise the host never crosses into JS for the moves
+      onMove: handler.onMove ? (pos) => {
+        if (removed || cancelled || fingers.indexOf(f) < 0) return
+        handler.onMove?.(step(f, pos.clientX, pos.clientY))
+      } : undefined,
+      onEnd: (pos) => {
+        if (removed) return
+        const live = !cancelled
+        if (!drop(f) || !live || fingers.length > 0) return
+        handler.onEnd?.({ centerX: pos.clientX, centerY: pos.clientY, deltaX: 0, deltaY: 0, scale: 1, rotation: 0, pointers: 0 })
+      },
+      onCancel: () => {
+        if (removed || fingers.indexOf(f) < 0) return
+        const was = cancelled
+        cancelled = true
+        drop(f)
+        if (!was) handler.onCancel?.()
+      },
+    })
+    if (first) handler.onStart?.({ centerX: f.x, centerY: f.y, deltaX: 0, deltaY: 0, scale: 1, rotation: 0, pointers: 1 })
+  }
+
+  const off = listen(target, onTouch)
+  return {
+    remove() {
+      if (removed) return
+      removed = true
+      fingers.length = 0
+      off()
+    },
+  }
+}