lecodes-sdk 2.8.0 → 2.8.2

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/scene/defineScene.ts

@@ -53,7 +53,7 @@ import { Model, foliageKindOf, type FoliageKind } from "../gl/Model"
 import { Physics } from "../gl/physics/Physics"
 import { CharacterController } from "../gl/physics/CharacterController"
 import { Lightmap, type LightmapDef, type LightmapPrepared } from "../gl/Lightmap"
-import { coveredRoots, defsDigest, bakeDigest, findNode, open as staticsOpen, build as staticsBuild, snapshot as staticsSnapshot, staticsConfig, toolRun, type CoveredRoot, type OpenedCache } from "../gl/Statics"
+import { coveredRoots, defsDigest, bakeDigest, findNode, open as staticsOpen, build as staticsBuild, snapshot as staticsSnapshot, staticsConfig, toolRun, attachPassive, type CoveredRoot, type OpenedCache } from "../gl/Statics"
 import { Foliage, type FoliageOptions } from "../gl/Foliage"
 import { NavMesh } from "../gl/nav/NavMesh"
 import { Terrain, type TerrainLayer, type TerrainRegion, type TerrainOptions } from "../gl/terrain/Terrain"
@@ -918,6 +918,9 @@ const buildNodes = async (
       if (parentNode) attachHost(parentNode, nd, path).add(node)
       scene.add(node)
       applyNode(node, name, nd)
+      // a root with a model is itself a placement: its clone takes the tags on the first hit (Statics.ts). A group
+      // root has no clone — its tags go here, one `parent` up from a hit on a wall under it
+      if (nd.model === undefined) attachPassive(node, nd)
       cov.node = node
       nodes[path] = node
       return
@@ -1028,7 +1031,7 @@ const instantiate = async (def: SceneDef, editorRuns: EditorRun[]): Promise<{ sc
   let cachedMade = 0
   if (opened) {
     const pages = prepared ? Lightmap.pageIds(prepared) : new Uint32Array(0)
-    cachedMade = await staticsBuild(opened, scene, roots.map((r) => covered.get(r.path)!.node!), pages, templateModel)
+    cachedMade = await staticsBuild(opened, scene, roots.map((r) => covered.get(r.path)!.node!), pages, templateModel, roots, def)
   }
   const nodesMs = Date.now() - tLoad
   if (navmesh && !(EDITOR && isEditMode())) registerNavOverrides(def.nodes, nodes)

package/src/scene/grammar.ts

@@ -17,8 +17,16 @@ export type AspectEntry<A extends Aspect<any, any> = Aspect<any, any>> = {
 
 /** Reference an aspect in a scene file: `aspects: [use(Physics, { motion: 'static' })]`. Props are
  *  typechecked against the aspect's fields, exactly like `node.aspect(Ctor, props)`. */
-export const use = <A extends Aspect<any, any>>(ctor: AspectCtor<A>, props?: Partial<A>): AspectEntry<A> =>
-  ({ __use: true, ctor, props })
+export const use = <A extends Aspect<any, any>>(ctor: AspectCtor<A>, props?: Partial<A>): AspectEntry<A> => {
+  // a passive aspect (Aspect.passive) is data: the level cache attaches it on the first hit, so an update() on it
+  // would never have run from the level's first frame — refused here, at the scene's own line, not in a raycast
+  if ((ctor as { passive?: boolean }).passive === true) {
+    const proto = (ctor as unknown as { prototype: Record<string, unknown> }).prototype
+    if (typeof proto.update === "function" || typeof proto.updateBefore === "function" || typeof proto.updateFixed === "function")
+      throw new Error(`use(${(ctor as { name?: string }).name ?? "?"}): a passive aspect carries data only — it cannot have update(); drop \`static passive\` or the update`)
+  }
+  return { __use: true, ctor, props }
+}
 
 /** A `make(fn, args)` source entry — see {@link make}. `N` is the node family the factory returns
  *  (3D `Node` by default; a `.scene2d.ts` file's factories return `Node2D`). */

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