lecodes-sdk 1.1.0 → 2.0.0

package/src/ui/tree.ts

@@ -0,0 +1,346 @@
+// The SDK's side of the tree of truth (docs/plans/hosts-unification-plan.md, phase 9): the numbers shared
+// with runtime/native (creator-pkg/tree-events.h — mirrored VERBATIM, `bun run check:tree-consts`),
+// the pin table that keeps the element of every attached node alive and findable by id, the
+// destination registry, and the ONE emitter every event of `_creatorTree` comes through.
+//
+// Ownership (tree.h): an attached node belongs to the runtime's tree and its element is PINNED here
+// (so `children` returns the same objects and listeners survive the app dropping its reference); a
+// detached root belongs to its element — when that is collected, the handle's finalizer frees the
+// node. The runtime tells us when it detaches a root (TREE_EVENT_DETACHED) or frees nodes underneath
+// their handles (TREE_EVENT_FREED); everything else we pin / unpin ourselves.
+
+// ---- emit kinds (id = the node, 0 for world-level events) ----------------------------------------
+export const TREE_EVENT_LAYOUT = 1
+export const TREE_EVENT_TOUCH_START = 2
+export const TREE_EVENT_CLICK = 3
+export const TREE_EVENT_LONG_PRESS = 4
+export const TREE_EVENT_TOUCH_MOVE = 5
+export const TREE_EVENT_TOUCH_END = 6
+export const TREE_EVENT_TOUCH_CANCEL = 7
+export const TREE_EVENT_SCROLL = 8
+export const TREE_EVENT_OVERSCROLL = 9
+export const TREE_EVENT_SCROLL_RELEASE = 10
+export const TREE_EVENT_REFRESH = 11
+export const TREE_EVENT_CHANGE = 12
+export const TREE_EVENT_FOCUS = 13
+export const TREE_EVENT_BLUR = 14
+export const TREE_EVENT_SUBMIT = 15
+export const TREE_EVENT_OVERLAY_TAP = 16
+export const TREE_EVENT_DETENT = 17
+export const TREE_EVENT_OPEN = 18
+export const TREE_EVENT_CLOSE = 19
+export const TREE_EVENT_BACK = 20
+export const TREE_EVENT_PAGER_SELECT = 21
+export const TREE_EVENT_PAGER_POP = 22
+export const TREE_EVENT_VLIST_SYNC = 23
+export const TREE_EVENT_VLIST_EDGE = 24
+export const TREE_EVENT_VIEW_EVENT = 25
+export const TREE_EVENT_RESIZE = 26
+export const TREE_EVENT_ROUTER_CHANGE = 27
+export const TREE_EVENT_SCENE_TOUCH_START = 28
+export const TREE_EVENT_SCENE_CLICK = 29
+export const TREE_EVENT_DETACHED = 30
+export const TREE_EVENT_FREED = 31
+export const TREE_EVENT_HOVER_ENTER = 32
+export const TREE_EVENT_HOVER_MOVE = 33
+export const TREE_EVENT_HOVER_END = 34
+export const TREE_EVENT_HOVER_CANCEL = 35
+
+// ---- setFlags(id, mask) ---------------------------------------------------------------------------
+export const TREE_FLAG_INTERACTIVE = 1 << 0
+export const TREE_FLAG_CLICK = 1 << 1
+export const TREE_FLAG_LONG_PRESS = 1 << 2
+export const TREE_FLAG_LAYOUT = 1 << 3
+export const TREE_FLAG_SCROLL = 1 << 4
+export const TREE_FLAG_OVERSCROLL = 1 << 5
+export const TREE_FLAG_SCROLL_RELEASE = 1 << 6
+export const TREE_FLAG_REFRESH = 1 << 7
+export const TREE_FLAG_CHANGE = 1 << 8
+export const TREE_FLAG_FOCUS = 1 << 9
+export const TREE_FLAG_BLUR = 1 << 10
+export const TREE_FLAG_SUBMIT = 1 << 11
+export const TREE_FLAG_OVERLAY_TAP = 1 << 12
+export const TREE_FLAG_DETENT = 1 << 13
+export const TREE_FLAG_KEEP_ALIVE = 1 << 14
+export const TREE_FLAG_BACK = 1 << 15
+export const TREE_FLAG_VLIST_END = 1 << 16
+export const TREE_FLAG_VLIST_START = 1 << 17
+export const TREE_FLAG_HOVER = 1 << 18
+
+// ---- the touchStart / longPress answer -------------------------------------------------------------
+export const TREE_TRACK_CLAIM_MASK = 0xFF
+export const TREE_TRACK_TRACKED = 1 << 8
+export const TREE_TRACK_MOVE = 1 << 9
+export const TREE_TRACK_HANDLED = 1 << 10
+
+// ---- destination kinds -------------------------------------------------------------------------------
+export const TREE_DEST_SCREEN = 0
+export const TREE_DEST_SCENE3D = 1
+export const TREE_DEST_SCENE2D = 2
+export const TREE_DEST_NATIVE = 3
+export const TREE_DEST_VIDEO = 4
+export const TREE_DEST_NONE = 0xFF
+
+// Owned-handle kinds (owned.h OwnedKind) — the `_creatorApp.setFreedEmitter` channel names the kind
+// whose resources the runtime freed underneath their wrappers (core/pins.ts).
+export const OWNED_KIND_TREE = 0
+export const OWNED_KIND_FETCH = 1
+export const OWNED_KIND_GL_MATERIAL = 2
+export const OWNED_KIND_GL_TEXTURE = 3
+export const OWNED_KIND_GL_ENTITY = 4
+export const OWNED_KIND_ENTITY_2D = 5
+export const OWNED_KIND_MEDIA = 6
+export const OWNED_KIND_TWEEN = 7
+export const OWNED_KIND_CANVAS = 8
+
+// PanDirection (creator-pkg.h) — the low byte of a track answer.
+import { DEAD_HANDLE } from "../core/pins"
+
+const PAN: Record<string, number> = { "pan-up": 1, "pan-right": 2, "pan-down": 4, "pan-left": 8, "pan-x": 10, "pan-y": 5 }
+
+// ---- the bridge ---------------------------------------------------------------------------------------
+/** @internal The tree bridge. Every host that runs bundles installs it before the bundle evaluates. */
+export const tree = (): typeof _creatorTree => _creatorTree
+
+// ---- what an element / presentable must offer the emitter (duck-typed, all `_`-prefixed so chisel keeps them)
+/** @internal */
+export interface TreeElement {
+  /** The owned handle (`_h.id` = the node id; DEAD_HANDLE once the node is gone). */
+  _h: Handle
+  _emitLayout?(box: { left: number, top: number, width: number, height: number }): void
+  _emitTouchStart?(pointerId: number, x: number, y: number): TrackLike | null
+  _emitClick?(pointerId: number, x: number, y: number): void
+  _emitLongPress?(pointerId: number, x: number, y: number): { track: TrackLike | null } | null
+  _emitMouseEnter?(x: number, y: number): HoverTrackLike | null
+  _emitScroll?(position: number): void
+  _emitOverscroll?(delta: number): void
+  _emitScrollRelease?(): void
+  _emitRefresh?(): unknown
+  _emitChange?(value: string): void
+  _emitFocus?(): void
+  _emitBlur?(): void
+  _emitSubmit?(value: string): void
+  _emitOverlayTap?(): void
+  _emitDetent?(index: number): void
+  _hostDidSelect?(index: number): void
+  _hostDidPop?(depth: number): void
+  _syncWindow?(unmountKeys: string[], mountKeys: string[]): void
+  _emitEdge?(end: boolean): void
+  _detached?(): void
+  _freed?(): void
+  /** The element's node got a native owner (it was inserted under a parent) / lost it. */
+  _pinned?(): void
+  _unpinned?(): void
+  _emitBack?(): boolean
+}
+
+/** @internal A track handler (runtime/touch.ts TrackHandler), as the emitter reads it. */
+export interface TrackLike {
+  onMove?(pos: { clientX: number, clientY: number, deltaX: number, deltaY: number }): void
+  onEnd?(pos: { clientX: number, clientY: number, deltaX: number, deltaY: number }): void
+  onCancel?(): void
+  claim?: boolean | string
+}
+/** @internal A hover track handler (runtime/touch.ts HoverTrackHandler): TrackLike without a claim. */
+export type HoverTrackLike = Omit<TrackLike, "claim">
+
+/** @internal What a destination offers: the presentation lifecycle + the back handler. */
+export interface TreeDest {
+  _emitOpen?(): void
+  _emitClose?(): void
+  _emitBack?(): boolean
+}
+
+export { DEAD_HANDLE }
+
+// ---- pins -------------------------------------------------------------------------------------------------
+const pins = new Map<number, TreeElement>()
+
+/** @internal Keep `el` alive and findable while its node is attached / presented / shown. */
+export const pin = (el: TreeElement | null | undefined): void => {
+  if (!el || el._h.id === 0) return
+  pins.set(el._h.id, el)
+  el._pinned?.()
+}
+/** @internal */
+export const unpin = (id: number): void => {
+  const el = pins.get(id)
+  if (!el) return
+  pins.delete(id)
+  el._unpinned?.()
+}
+/** @internal The pinned element of a node id (an attached node's element), or undefined. */
+export const byId = (id: number): TreeElement | undefined => pins.get(id)
+/** @internal The elements of a list of ids (attached nodes only). */
+export const elementsOf = (ids: number[]): any[] => {
+  const out: any[] = []
+  for (const id of ids) { const el = pins.get(id); if (el) out.push(el) }
+  return out
+}
+
+// ---- destinations ------------------------------------------------------------------------------------------
+// Non-screen presentables (scenes, native views) register here under their engine id; screens and
+// video nodes resolve through the pins (their destination id IS the node id).
+const dests = new Map<string, TreeDest>()
+const destKey = (kind: number, id: number): string => `${kind}:${id}`
+
+/** @internal */
+export const registerDest = (kind: number, id: number, p: TreeDest): void => { dests.set(destKey(kind, id), p) }
+/** @internal */
+export const unregisterDest = (kind: number, id: number): void => { dests.delete(destKey(kind, id)) }
+/** @internal The presentable a (kind, id) pair names. */
+export const resolveDest = (kind: number, id: number): (TreeDest & Partial<TreeElement>) | undefined => {
+  if (kind === TREE_DEST_SCREEN || kind === TREE_DEST_VIDEO) return pins.get(id) as any
+  return dests.get(destKey(kind, id)) as any
+}
+
+// ---- world-level hooks (set by the modules that own them) --------------------------------------------------
+type SceneTouchStart = (pointerId: number, x: number, y: number, entityId: number) => TrackLike | null
+type SceneClick = (pointerId: number, x: number, y: number, entityId: number) => void
+let sceneTouchStart: SceneTouchStart | null = null
+let sceneClick: SceneClick | null = null
+/** @internal gl/touch.ts: the scene-level pointer dispatch. */
+export const setSceneTouchHandlers = (start: SceneTouchStart | null, click: SceneClick | null): void => {
+  sceneTouchStart = start
+  sceneClick = click
+}
+
+const resizeListeners: ((width: number, height: number) => void)[] = []
+/** @internal runtime/device.ts */
+export const onTreeResize = (cb: (width: number, height: number) => void): (() => void) => {
+  resizeListeners.push(cb)
+  return () => { const i = resizeListeners.indexOf(cb); if (i >= 0) resizeListeners.splice(i, 1) }
+}
+
+let routerChange: ((kind: number, id: number) => void) | null = null
+/** @internal ui/router.ts */
+export const setRouterChangeHandler = (cb: ((kind: number, id: number) => void) | null): void => { routerChange = cb }
+
+let appBack: (() => void) | null = null
+/** @internal runtime/app.ts — the app-level back handler (the end of the runtime's back chain). */
+export const setAppBackHandler = (cb: (() => void) | null): void => { appBack = cb }
+
+const nativeViews = new Map<number, { _emitViewEvent(event: string, data?: unknown): void }>()
+/** @internal ui/NativeView.ts: the instance a viewId names (host → view events). */
+export const registerNativeView = (viewId: number, v: { _emitViewEvent(event: string, data?: unknown): void }): void => { nativeViews.set(viewId, v) }
+/** @internal */
+export const unregisterNativeView = (viewId: number): void => { nativeViews.delete(viewId) }
+
+// ---- 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.
+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
+// tracker under pointer 0 while the hover under the same cursor runs here, independently.
+let hoverTracker: HoverTrackLike | null = null
+
+const hoverAnswer = (handler: HoverTrackLike | null | undefined): number => {
+  hoverTracker = handler ?? null
+  if (!handler) return 0
+  return TREE_TRACK_TRACKED | (handler.onMove ? TREE_TRACK_MOVE : 0)
+}
+
+const trackAnswer = (pointerId: number, handler: TrackLike | null | undefined): number => {
+  if (!handler) return 0
+  trackers.set(pointerId, handler)
+  let r = TREE_TRACK_TRACKED
+  if (handler.onMove) r |= TREE_TRACK_MOVE
+  const claim = handler.claim
+  if (claim === true || claim === "all") r |= 15
+  else if (typeof claim === "string") r |= PAN[claim] ?? 0
+  return r
+}
+
+// ---- the emitter --------------------------------------------------------------------------------------------
+let installed = false
+const emit = (id: number, kind: number, a?: any, b?: any, c?: any, d?: any, e?: any): any => {
+  switch (kind) {
+    case TREE_EVENT_LAYOUT: pins.get(id)?._emitLayout?.({ left: a, top: b, width: c, height: d }); return
+    case TREE_EVENT_TOUCH_START: return trackAnswer(a, pins.get(id)?._emitTouchStart?.(a, b, c))
+    case TREE_EVENT_CLICK: pins.get(id)?._emitClick?.(a, b, c); return
+    case TREE_EVENT_LONG_PRESS: {
+      const r = pins.get(id)?._emitLongPress?.(a, b, c)
+      if (!r) return 0
+      return TREE_TRACK_HANDLED | trackAnswer(a, r.track)
+    }
+    case TREE_EVENT_TOUCH_MOVE: trackers.get(a)?.onMove?.({ clientX: b, clientY: c, deltaX: d, deltaY: e }); return
+    case TREE_EVENT_TOUCH_END: {
+      const t = trackers.get(a)
+      trackers.delete(a)
+      t?.onEnd?.({ clientX: b, clientY: c, deltaX: d, deltaY: e })
+      return
+    }
+    case TREE_EVENT_TOUCH_CANCEL: {
+      const t = trackers.get(a)
+      trackers.delete(a)
+      t?.onCancel?.()
+      return
+    }
+    case TREE_EVENT_HOVER_ENTER: return hoverAnswer(pins.get(id)?._emitMouseEnter?.(a, b))
+    case TREE_EVENT_HOVER_MOVE: hoverTracker?.onMove?.({ clientX: a, clientY: b, deltaX: c, deltaY: d }); return
+    case TREE_EVENT_HOVER_END: {
+      const t = hoverTracker
+      hoverTracker = null
+      t?.onEnd?.({ clientX: a, clientY: b, deltaX: c, deltaY: d })
+      return
+    }
+    case TREE_EVENT_HOVER_CANCEL: {
+      const t = hoverTracker
+      hoverTracker = null
+      t?.onCancel?.()
+      return
+    }
+    case TREE_EVENT_SCROLL: pins.get(id)?._emitScroll?.(a); return
+    case TREE_EVENT_OVERSCROLL: pins.get(id)?._emitOverscroll?.(a); return
+    case TREE_EVENT_SCROLL_RELEASE: pins.get(id)?._emitScrollRelease?.(); return
+    case TREE_EVENT_REFRESH: return pins.get(id)?._emitRefresh?.()
+    case TREE_EVENT_CHANGE: pins.get(id)?._emitChange?.(a); return
+    case TREE_EVENT_FOCUS: pins.get(id)?._emitFocus?.(); return
+    case TREE_EVENT_BLUR: pins.get(id)?._emitBlur?.(); return
+    case TREE_EVENT_SUBMIT: pins.get(id)?._emitSubmit?.(a); return
+    case TREE_EVENT_OVERLAY_TAP: pins.get(id)?._emitOverlayTap?.(); return
+    case TREE_EVENT_DETENT: pins.get(id)?._emitDetent?.(a); return
+    case TREE_EVENT_OPEN: resolveDest(a, b)?._emitOpen?.(); return
+    case TREE_EVENT_CLOSE: resolveDest(a, b)?._emitClose?.(); return
+    case TREE_EVENT_BACK: {
+      if (a === TREE_DEST_NONE) {
+        if (id !== 0) return pins.get(id)?._emitBack?.() === true   // a widget
+        if (!appBack) return false
+        appBack()
+        return true
+      }
+      return resolveDest(a, b)?._emitBack?.() === true
+    }
+    case TREE_EVENT_PAGER_SELECT: pins.get(id)?._hostDidSelect?.(a); return
+    case TREE_EVENT_PAGER_POP: pins.get(id)?._hostDidPop?.(a); return
+    case TREE_EVENT_VLIST_SYNC: pins.get(id)?._syncWindow?.(a, b); return
+    case TREE_EVENT_VLIST_EDGE: pins.get(id)?._emitEdge?.(!!a); return
+    case TREE_EVENT_VIEW_EVENT: nativeViews.get(a)?._emitViewEvent(b, c); return
+    case TREE_EVENT_RESIZE: for (const cb of resizeListeners.slice()) cb(a, b); return
+    case TREE_EVENT_ROUTER_CHANGE: routerChange?.(a, b); return
+    case TREE_EVENT_SCENE_TOUCH_START: return trackAnswer(a, sceneTouchStart?.(a, b, c, d))
+    case TREE_EVENT_SCENE_CLICK: sceneClick?.(a, b, c, d); return
+    case TREE_EVENT_DETACHED: {
+      const el = pins.get(id)
+      pins.delete(id)
+      el?._detached?.()
+      return
+    }
+    case TREE_EVENT_FREED: {
+      for (const fid of a as number[]) {
+        const el = pins.get(fid)
+        pins.delete(fid)
+        el?._freed?.()
+      }
+      return
+    }
+  }
+}
+
+/** @internal Install the emitter once per world (the first element / presentable calls it). */
+export const ensureEmitter = (): void => {
+  if (installed) return
+  installed = true
+  _creatorTree.setEmitter(emit)
+}

package/src/version.ts

@@ -0,0 +1,24 @@
+// GENERATED by scripts/release/set-version.ts from sdk/package.json — do not edit by hand.
+// The ONE version of the SDK + the runtime (the npm runtime set ships as one version; the C++
+// twin is CREATOR_PKG_SDK_VERSION in creator-pkg/host.gen.h, emitted by gen:bridges from the
+// 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.0.0"
+
+/** The major of a semver string, or null when it is not one. */
+export const sdkMajor = (version: string | null | undefined): number | null => {
+  const m = version?.match(/^(\d+)\.\d+\.\d+/)
+  return m ? Number(m[1]) : null
+}
+
+/** The `// sdk: <version>` line of a compiled bundle's header (sdk/src/compile/header.ts), read from
+ *  its first bytes; null for a bundle compiled before the line existed (SDK 0.x / 1.x — the
+ *  pre-tree contract, which no 2.x host runs). */
+export const bundleSdkVersion = (head: string): string | null =>
+  head.slice(0, 2000).match(/^\/\/ sdk: (\d+\.\d+\.\d+\S*)/m)?.[1] ?? null
+
+/** Whether a host embedding `hostVersion` can run a bundle whose header carries `bundleVersion`
+ *  (null = no line = pre-2.0 contract): the majors must match. */
+export const bundleRunsOn = (bundleVersion: string | null, hostVersion: string): boolean =>
+  sdkMajor(bundleVersion) !== null && sdkMajor(bundleVersion) === sdkMajor(hostVersion)

package/tests/helpers/engineWorld.ts

@@ -0,0 +1,11 @@
+// A test file's 3D engine world is its `_creator` stub, and it ends with the file. The runtime frees
+// a torn-down world's nodes and reports them (core/pins.ts); a stub does not, and every stub restarts
+// its entity ids — so a node the SDK still pins (parented / in a scene: gl/Node.ts `nodes`) would
+// answer for a later file's entity with the same id (`parent`, `children`, the rig an IK chain lands
+// on). A file whose nodes get pinned reports its entity ids freed in its afterAll.
+import { nodes } from "../../src/gl/Node"
+
+/** Report the entity ids `first`..`last`, plus `extra`, freed — the runtime's world teardown. */
+export const freeEntities = (first: number, last: number, ...extra: number[]): void => {
+  nodes.freed([ ...Array.from({ length: Math.max(0, last - first + 1) }, (_, i) => first + i), ...extra ])
+}