lecodes-sdk 2.8.0 → 2.8.1

package/package.json

@@ -43,7 +43,7 @@
     "marcidb-embedded": "^0.18.0",
     "sharp": "^0.35.2"
   },
-  "version": "2.8.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/inject.ts

@@ -63,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/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()
+    },
+  }
+}

package/src/ui/UIModal.ts

@@ -23,6 +23,14 @@ export type UIModalShow = (() => boolean) | Signal<boolean>
 const MODAL_ANIM_MS = 200
 const SHOW_BINDING = "#show"
 
+// The transition period's `display` on a modal: said once per run, not per write.
+let displayWarned = false
+function warnDisplayDeprecated(): void {
+  if (displayWarned) return
+  displayWarned = true
+  console.warn("deprecated: a modal's `display` — show it with show() / hide(), or bind it with bindShow(() => …) (+ onDismiss for the scrim tap / back); `display` on a modal will throw again")
+}
+
 /**
  * A dialog: a `UIWidget` with the modal boilerplate built in. Comes with a scrim
  * (`overlayColor: "rgba(0, 0, 0, 0.5)"` unless overridden), is HIDDEN until shown, animates on
@@ -38,9 +46,10 @@ const SHOW_BINDING = "#show"
  * request, `onDismiss`. By default it hides an unbound modal and writes `false` into a bound
  * signal; a bound function has nowhere to write, so a modal bound to one without `onDismiss`
  * cannot be dismissed (a forced choice — the same as `dismissible(false)`). `display` is not a
- * modal's switch: a `.style({ display })` on it throws (a bound display died on the first
- * dismissal, which wrote a static `display: "none"` over the binding — the dialog never opened
- * again).
+ * modal's switch (a bound display died on the first dismissal, which wrote a static
+ * `display: "none"` over the binding — the dialog never opened again). Deprecated, for the
+ * transition period a `.style({ display })` is still accepted, with a warning: a function becomes
+ * `bindShow(() => fn() !== "none")`, a value a show() / hide(); it will throw again.
  */
 export interface UIModal extends UIWidget {
   /**
@@ -107,14 +116,40 @@ export class ModalElement extends WidgetElement {
     this._syncPose()
   }
 
-  /** @internal `display` is not a modal's switch. Refused on every write of the app's — `.style({
-   *  display })`, `el.style.display =` — and let through for the widget's own (`_ownWrite`). During
-   *  the constructor the field is still undefined (it is initialised after `super()`), which lets
-   *  the default `display: "none"` through. */
+  /** @internal `display` is not a modal's switch — DEPRECATED, accepted for the transition period
+   *  and translated: a function → `bindShow(() => fn() !== "none")`, a value → the start state of
+   *  an unplaced modal or a show() / hide() of a placed one (replacing a binding, as a static write
+   *  did). The widget's own writes (`_ownWrite`) pass untouched. During the constructor the field is
+   *  still undefined (it is initialised after `super()`), which lets the default `display: "none"`
+   *  through. */
   _mapStyle(style: any): void {
-    if ("display" in style && this._ownWrite === false) {
-      throw new Error("a modal's `display` is not its switch — a dialog, a sheet or a menu is shown with show() / hide(), or bound to the data with bindShow(…), never by its display")
+    if (!("display" in style) || this._ownWrite !== false) return
+    const value = style.display
+    delete style.display
+    warnDisplayDeprecated()
+    if (typeof value === "function") { this._bindDisplay(value); return }
+    if (this._bound) {
+      disposeBinding(this, SHOW_BINDING)
+      this._bound = false
+      this._showSignal = undefined
+      this._syncDismissible()
     }
+    const shown = value !== "none"
+    if (this._h.id === 0) return
+    if (tree().parent(this._h.id) === 0 && !this._shown) this._writeDisplay(shown ? "flex" : "none")   // the start state
+    else this._setOpen(shown)
+  }
+
+  /** @internal `el.style.display = () => …` (the style proxy's binding form) — DEPRECATED, as `_mapStyle`. */
+  _bindStyle(key: string, fn: () => any): boolean {
+    if (key !== "display") return false
+    warnDisplayDeprecated()
+    this._bindDisplay(fn)
+    return true
+  }
+
+  private _bindDisplay(fn: () => any): void {
+    this.bindShow(() => fn() !== "none")
   }
 
   // The pose the runtime plays on a display flip: the hidden pose + its duration, plus the scrim

package/src/ui/UINode.ts

@@ -399,6 +399,7 @@ const handler: ProxyHandler<any> = {
       // dispose the binding (this is the hot path) — override statically via `.style({ prop })`.
       const el = target._el
       const fn = value as unknown as () => any
+      if (el._bindStyle?.(key, fn) === true) return true   // the element took the binding itself
       createBinding(el, key, () => { el.style[key] = fn() })
       return true
     }
@@ -518,6 +519,9 @@ export class Element<T extends string> implements TreeElement {
    *  `type: "phone"` → `"tel"`), mutating the style in place before it is stored or sent. Runs on
    *  every entry point: the constructor's style, `.style()`, and single-key `el.style.k =` writes. */
   _mapStyle?(style: any): void
+  /** @internal A function written as `el.style.key = () => …`: true when the element bound it
+   *  itself (a modal's deprecated `display`), false for the ordinary per-key binding. */
+  _bindStyle?(key: string, fn: () => any): boolean
 
   // Per-type default styles are inlined at each component's construction site (spread UNDER the
   // user's style — e.g. UIRow's `flexDirection: "row"`), so every node reaches the host with

package/src/ui/tree.ts

@@ -233,6 +233,14 @@ export const unregisterNativeView = (viewId: number): void => { nativeViews.dele
 // ---- gestures -----------------------------------------------------------------------------------------------
 // The track handler of every pointer a listener claimed (`ev.track(...)`): the runtime feeds the
 // pointer's moves / end / cancel here by pointer id — nothing of it is retained natively.
+//
+// Several fingers on one node — the rule every host keeps (renderers/uikit + renderers/android
+// TouchPipeline, renderers/tgfx ui_internal.h Gesture, renderers/web-lite events.ts, web-canvas
+// TreeUI): every finger is its own pointer — its own touchStart and so its own `ev.track`, its own
+// moves and end / cancel at its own point, keyed here by its id. The click and the long press are the
+// node's PRIMARY finger's, the one that pressed it while no other held it: a two-finger tap is ONE
+// click, a second finger landing cancels a hold still pending (a pinch is not a hold). `$pressed`
+// holds until the last finger lifts.
 const trackers = new Map<number, TrackLike>()
 
 // The hover's own slot — the cursor is one, and it is NOT a gesture: a mouse drag keeps its touch

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.8.0"
+export const SDK_VERSION = "2.8.1"
 
 /** The major of a semver string, or null when it is not one. */
 export const sdkMajor = (version: string | null | undefined): number | null => {