lecodes-sdk 1.2.0 → 2.0.0

package/tests/helpers/fakeTree.ts

@@ -0,0 +1,353 @@
+// A TypeScript stand-in for `_creatorTree` (sdk/src/bridges/tree.d.ts) for the SDK's unit tests:
+// an in-memory tree with the runtime's semantics the SDK relies on (ids, insert / remove, parent /
+// children, the pager's pages, the vlist window, destinations + the router stack, widgets) and a
+// call recorder. Events reach the SDK through the emitter it installs (`fake.emit(...)` fires one
+// by hand; the fake itself fires open / close / routerChange / detached / vlistSync the way the
+// runtime does, synchronously). Installed for every test file by tests/helpers/preload.ts.
+import {
+  TREE_DEST_NONE, TREE_DEST_SCREEN, TREE_DEST_VIDEO,
+  TREE_EVENT_CLOSE, TREE_EVENT_DETACHED, TREE_EVENT_FREED, TREE_EVENT_OPEN, TREE_EVENT_ROUTER_CHANGE, TREE_EVENT_VLIST_SYNC,
+} from "../../src/ui/tree"
+import { _resetTransitions } from "../../src/ui/transitions"
+
+export type FakeNode = {
+  id: number, type: string, parent: number, children: number[],
+  strings: Record<string, string | null>, ints: Record<string, number>, flags: number,
+  style: Record<string, unknown>, classes: Set<string>,
+  pages?: number[], lens?: number[], index?: number, pagerOwner?: number,
+  vlist?: { keys: string[], mounted: Map<string, number> },
+}
+export type Call = { method: string, args: any[] }
+type Dest = { kind: number, id: number, viewName: string, paramsJson: string }
+
+export class FakeTree {
+  nodes = new Map<number, FakeNode>()
+  calls: Call[] = []
+  emitter: ((id: number, kind: number, ...args: any[]) => any) | null = null
+  rects = new Map<number, [number, number, number, number]>()
+  displaySize: [number, number] = [0, 0]
+  current: Dest | null = null
+  stack: Dest[] = []
+  widgets: number[] = []
+  freed: number[] = []
+  tweens: { id: number, data: Float32Array, strings: string[], targets: number[] }[] = []
+  tweenEvent: ((id: number, kind: number, index: number, ...lanes: number[]) => void) | null = null
+  /** What `defineTransition` registered; `transitions[id - 1]` is the transition of a wire id. */
+  transitions: { id: number, data: Float32Array, strings: string[], roles: number[], flags: number }[] = []
+  fontFormat?: "woff2" | "ttf"
+  private nextId = 1
+  private nextTween = 1
+
+  // ---- helpers for tests ---------------------------------------------------------------------------
+  node(id: number): FakeNode { const n = this.nodes.get(id); if (!n) throw new Error(`fakeTree: no node ${id}`); return n }
+  names(): string[] { return this.calls.map((c) => c.method) }
+  find(method: string): Call | undefined { return this.calls.find((c) => c.method === method) }
+  filter(method: string): Call[] { return this.calls.filter((c) => c.method === method) }
+  reset(): void { this.calls = [] }
+  /** Every node id this fake ever handed out (alive or not). */
+  allIds(): number[] { return Array.from({ length: this.nextId - 1 }, (_, i) => i + 1) }
+  /** Fire an event at the SDK the way the runtime would. */
+  emit(id: number, kind: number, ...args: any[]): any { return this.emitter?.(id, kind, ...args) }
+  private rec(method: string, ...args: any[]): void { this.calls.push({ method, args }) }
+  private destId(d: Dest): number { return d.id }
+  private fireDest(d: Dest | null, kind: number): void {
+    if (!d) return
+    const node = d.kind === TREE_DEST_SCREEN || d.kind === TREE_DEST_VIDEO ? d.id : 0
+    this.emitter?.(node, kind, d.kind, this.destId(d))
+  }
+  private sameDest(a: Dest | null, b: Dest | null): boolean {
+    return !!a && !!b && a.kind === b.kind && a.id === b.id
+  }
+  private inStack(d: Dest): boolean { return this.stack.some((s) => this.sameDest(s, d)) }
+
+  // ---- nodes -----------------------------------------------------------------------------------------
+  create = (type: string): Handle => {
+    const id = this.nextId++
+    this.nodes.set(id, { id, type, parent: 0, children: [], strings: {}, ints: {}, flags: 0, style: {}, classes: new Set() })
+    this.rec("create", type, id)
+    return { id }
+  }
+  destroy = (id: number): void => {
+    this.rec("destroy", id)
+    const n = this.nodes.get(id)
+    if (!n) return
+    const freeRec = (m: FakeNode) => {
+      for (const c of m.children) { const cn = this.nodes.get(c); if (cn) freeRec(cn) }
+      this.nodes.delete(m.id)
+      if (m.id !== id) this.freed.push(m.id)
+    }
+    freeRec(n)
+  }
+  insert = (parent: number, child: number, index: number): void => {
+    this.rec("insert", parent, child, index)
+    const p = this.nodes.get(parent), c = this.nodes.get(child)
+    if (!p || !c) return
+    if (c.parent !== 0) return
+    c.parent = parent
+    const i = Math.max(0, Math.min(index, p.children.length))
+    p.children.splice(i, 0, child)
+  }
+  remove = (parent: number, child: number): void => {
+    this.rec("remove", parent, child)
+    const p = this.nodes.get(parent), c = this.nodes.get(child)
+    if (!p || !c || c.parent !== parent) return
+    c.parent = 0
+    p.children = p.children.filter((x) => x !== child)
+  }
+  parent = (id: number): number => {
+    const n = this.nodes.get(id)
+    return n ? (n.pagerOwner ?? n.parent) : 0
+  }
+  children = (id: number): number[] => {
+    const n = this.nodes.get(id)
+    if (!n) return []
+    return n.pages ? n.pages.slice() : n.children.slice()
+  }
+
+  // ---- content / style -------------------------------------------------------------------------------
+  setString = (id: number, key: string, value: string | null): void => { this.rec("setString", id, key, value); const n = this.nodes.get(id); if (n) n.strings[key] = value }
+  setInt = (id: number, key: string, value: number): void => { this.rec("setInt", id, key, value); const n = this.nodes.get(id); if (n) n.ints[key] = value }
+  setFlags = (id: number, mask: number): void => { this.rec("setFlags", id, mask); const n = this.nodes.get(id); if (n) n.flags = mask }
+  getTextValue = (id: number): string => this.nodes.get(id)?.strings.value ?? ""
+  setStyle = (id: number, key: string, value: any): void => { this.rec("setStyle", id, key, value); const n = this.nodes.get(id); if (n) n.style[key] = value }
+  mergeStyle = (id: number, style: object): void => { this.rec("mergeStyle", id, style); const n = this.nodes.get(id); if (n) Object.assign(n.style, style) }
+  setClass = (id: number, name: string, enabled: boolean): void => {
+    this.rec("setClass", id, name, enabled)
+    const n = this.nodes.get(id); if (!n) return
+    if (enabled) n.classes.add(name); else n.classes.delete(name)
+  }
+  setTheme = (values: Record<string, any>): void => { this.rec("setTheme", values) }
+
+  // ---- presentation ----------------------------------------------------------------------------------
+  private present(d: Dest, transition: number): void {
+    if (this.sameDest(this.current, d)) return
+    const prev = this.current
+    this.fireDest(prev, TREE_EVENT_CLOSE)
+    this.current = d
+    this.fireDest(d, TREE_EVENT_OPEN)
+    if (prev && !this.inStack(prev)) this.retire(prev)
+  }
+  private retire(d: Dest): void {
+    if (d.kind === TREE_DEST_SCREEN && !this.inStack(d) && !this.sameDest(this.current, d)) this.emitter?.(d.id, TREE_EVENT_DETACHED)
+  }
+  defineTransition = (data: Float32Array, strings: string[], roles: number[], flags: number): number => {
+    const id = this.transitions.length + 1
+    this.transitions.push({ id, data, strings: strings.slice(), roles: roles.slice(), flags })
+    this.rec("defineTransition", id, roles.slice(), flags)
+    return id
+  }
+  open = (kind: number, id: number, viewName: string, paramsJson: string, transition: number): void => {
+    this.rec("open", kind, id, viewName, paramsJson, transition)
+    this.present({ kind, id, viewName, paramsJson }, transition)
+  }
+  // Like the runtime's closeViewOf: only the destination on screen closes.
+  close = (kind: number, id: number, transition: number): void => {
+    this.rec("close", kind, id, transition)
+    const prev = this.current
+    if (!prev || prev.kind !== kind || prev.id !== id) return
+    this.closeCurrent()
+  }
+  private closeCurrent(): void {
+    const prev = this.current
+    if (!prev) return
+    this.fireDest(prev, TREE_EVENT_CLOSE)
+    this.current = null
+    if (!this.inStack(prev)) this.retire(prev)
+  }
+  private change(d: Dest, transition: number): void {
+    this.present(d, transition)
+    this.emitter?.(0, TREE_EVENT_ROUTER_CHANGE, d.kind, this.destId(d))
+  }
+  routerOpen = (kind: number, id: number, viewName: string, paramsJson: string, showBack: boolean): void => {
+    this.rec("routerOpen", kind, id, viewName, paramsJson, showBack)
+    const old = this.stack
+    this.stack = []
+    for (const d of old) if (!this.sameDest(d, this.current)) this.retire(d)
+    const d = { kind, id, viewName, paramsJson }
+    this.stack.push(d)
+    this.present(d, 0)
+  }
+  routerPush = (kind: number, id: number, viewName: string, paramsJson: string, transition: number, back: number): void => {
+    this.rec("routerPush", kind, id, viewName, paramsJson, transition, back)
+    const d = { kind, id, viewName, paramsJson }
+    this.stack.push(d)
+    this.change(d, transition)
+  }
+  routerReplace = (kind: number, id: number, viewName: string, paramsJson: string, transition: number, back: number): void => {
+    this.rec("routerReplace", kind, id, viewName, paramsJson, transition, back)
+    const d = { kind, id, viewName, paramsJson }
+    const evicted = this.stack.pop()
+    this.stack.push(d)
+    this.change(d, transition)
+    if (evicted) this.retire(evicted)
+  }
+  routerPop = (index: number, transition: number): void => {
+    this.rec("routerPop", index, transition)
+    if (this.stack.length <= 1) return
+    const count = this.stack.length
+    const target = index === -1 ? count - 2 : index < -1 ? Math.max(count - 1 + index, 0) : index === 0 ? 0 : Math.min(index, count - 1)
+    const evicted = this.stack.splice(target + 1)
+    this.change(this.stack[this.stack.length - 1]!, transition)
+    for (const d of evicted) this.retire(d)
+  }
+  routerHide = (transition: number): void => { this.rec("routerHide", transition); this.closeCurrent() }
+  routerRestore = (transition: number): void => { this.rec("routerRestore", transition); const top = this.stack[this.stack.length - 1]; if (top) this.present(top, transition) }
+  isViewSupported = (name: string): boolean => { this.rec("isViewSupported", name); return this.supportedViews.has(name) }
+  supportedViews = new Set<string>()
+  /** The contract version of a supported view (1 unless a test says otherwise). */
+  viewVersions = new Map<string, number>()
+  viewVersion = (name: string): number => this.supportedViews.has(name) ? this.viewVersions.get(name) ?? 1 : 0
+  viewCall = (viewId: number, method: string, args: unknown[], onComplete: (r?: unknown) => void, onReject: (m: string) => void): void => {
+    this.rec("viewCall", viewId, method, args)
+    const h = this.viewCallHandler
+    if (h) h(viewId, method, args, onComplete, onReject)
+    else onReject(`no view ${viewId}`)
+  }
+  viewCallHandler: ((viewId: number, method: string, args: any[], res: (r?: unknown) => void, rej: (m: string) => void) => void) | null = null
+  showWidget = (id: number, ownerKind: number, ownerId: number): void => { this.rec("showWidget", id, ownerKind, ownerId); if (!this.widgets.includes(id)) this.widgets.push(id) }
+  hideWidget = (id: number): void => { this.rec("hideWidget", id); this.widgets = this.widgets.filter((w) => w !== id) }
+
+  // ---- pager -----------------------------------------------------------------------------------------
+  private pagerTop(p: FakeNode): number | null {
+    if (!p.pages || !p.lens) return null
+    let off = 0
+    for (let t = 0; t < (p.index ?? 0); t++) off += p.lens[t] ?? 0
+    const len = p.lens[p.index ?? 0] ?? 0
+    return len > 0 ? p.pages[off + len - 1] ?? null : null
+  }
+  private pagerOpen = new Map<number, number>()   // pager → the open page
+  private pagerRefresh(p: FakeNode): void {
+    const top = this.pagerTop(p)
+    const open = this.pagerOpen.get(p.id) ?? null
+    if (top === open) return
+    if (open !== null) { this.pagerOpen.delete(p.id); this.emitter?.(open, TREE_EVENT_CLOSE, TREE_DEST_SCREEN, open) }
+    if (top !== null) { this.pagerOpen.set(p.id, top); this.emitter?.(top, TREE_EVENT_OPEN, TREE_DEST_SCREEN, top) }
+  }
+  pagerSetContent = (id: number, pages: number[], lens: number[], index: number): void => {
+    this.rec("pagerSetContent", id, pages.slice(), lens.slice(), index)
+    const p = this.nodes.get(id); if (!p) return
+    const gone = (p.pages ?? []).filter((old) => !pages.includes(old))
+    p.pages = pages.slice(); p.lens = lens.slice(); p.index = Math.max(0, Math.min(index, lens.length - 1))
+    for (const pg of pages) { const n = this.nodes.get(pg); if (n) n.pagerOwner = id }
+    this.pagerRefresh(p)   // the old top's CLOSE fires BEFORE its DETACHED, like the runtime
+    for (const old of gone) { const n = this.nodes.get(old); if (n) n.pagerOwner = undefined; this.emitter?.(old, TREE_EVENT_DETACHED) }
+  }
+  pagerSelect = (id: number, index: number, animated: boolean): void => {
+    this.rec("pagerSelect", id, index, animated)
+    const p = this.nodes.get(id); if (!p || !p.lens) return
+    p.index = Math.max(0, Math.min(index, p.lens.length - 1))
+    this.pagerRefresh(p)
+  }
+  private pagerOffset(p: FakeNode): number { let off = 0; for (let t = 0; t < (p.index ?? 0); t++) off += p.lens![t] ?? 0; return off }
+  pagerPush = (id: number, page: number, transition: number, back: number): void => {
+    this.rec("pagerPush", id, page, transition, back)
+    const p = this.nodes.get(id); if (!p || !p.pages || !p.lens) return
+    p.pages.splice(this.pagerOffset(p) + p.lens[p.index!]!, 0, page); p.lens[p.index!]!++
+    const n = this.nodes.get(page); if (n) n.pagerOwner = id
+    this.pagerRefresh(p)
+  }
+  pagerPop = (id: number, transition: number): void => {
+    this.rec("pagerPop", id, transition)
+    const p = this.nodes.get(id); if (!p || !p.pages || !p.lens || p.lens[p.index!]! <= 1) return
+    const [gone] = p.pages.splice(this.pagerOffset(p) + p.lens[p.index!]! - 1, 1); p.lens[p.index!]!--
+    this.pagerRefresh(p)
+    if (gone !== undefined) { const n = this.nodes.get(gone); if (n) n.pagerOwner = undefined; this.emitter?.(gone, TREE_EVENT_DETACHED) }
+  }
+  pagerPopToRoot = (id: number, transition: number): void => {
+    this.rec("pagerPopToRoot", id, transition)
+    const p = this.nodes.get(id); if (!p || !p.pages || !p.lens) return
+    const len = p.lens[p.index!]!; if (len <= 1) return
+    const gone = p.pages.splice(this.pagerOffset(p) + 1, len - 1); p.lens[p.index!] = 1
+    this.pagerRefresh(p)
+    for (const g of gone) { const n = this.nodes.get(g); if (n) n.pagerOwner = undefined; this.emitter?.(g, TREE_EVENT_DETACHED) }
+  }
+  pagerReplace = (id: number, page: number, transition: number, back: number): void => {
+    this.rec("pagerReplace", id, page, transition, back)
+    const p = this.nodes.get(id); if (!p || !p.pages || !p.lens) return
+    const at = this.pagerOffset(p) + p.lens[p.index!]! - 1
+    const old = p.pages[at]
+    p.pages[at] = page
+    const n = this.nodes.get(page); if (n) n.pagerOwner = id
+    this.pagerRefresh(p)
+    if (old !== undefined) { const on = this.nodes.get(old); if (on) on.pagerOwner = undefined; this.emitter?.(old, TREE_EVENT_DETACHED) }
+  }
+
+  // ---- vlist (the window = every key: tests don't scroll) --------------------------------------------
+  private vl(id: number): FakeNode["vlist"] | undefined { const n = this.nodes.get(id); if (!n) return; return n.vlist ??= { keys: [], mounted: new Map() } }
+  private vlistSync(id: number): void {
+    const v = this.vl(id); if (!v) return
+    const unmount = [...v.mounted.keys()].filter((k) => !v.keys.includes(k))
+    const mount = v.keys.filter((k) => !v.mounted.has(k))
+    for (const k of unmount) v.mounted.delete(k)
+    if (unmount.length || mount.length) this.emitter?.(id, TREE_EVENT_VLIST_SYNC, unmount, mount)
+  }
+  vlistInit = (id: number, overscan: number, inverted: boolean, start: number, end: number): void => { this.rec("vlistInit", id, overscan, inverted, start, end); this.vl(id) }
+  vlistSetKeys = (id: number, keys: string[], estimates: number[]): void => { this.rec("vlistSetKeys", id, keys.slice(), estimates.slice()); const v = this.vl(id); if (!v) return; v.keys = keys.slice(); this.vlistSync(id) }
+  vlistInsertKeys = (id: number, index: number, keys: string[], estimates: number[]): void => {
+    this.rec("vlistInsertKeys", id, index, keys.slice(), estimates.slice())
+    const v = this.vl(id); if (!v) return
+    if (index < 0) v.keys.push(...keys); else v.keys.splice(index, 0, ...keys)
+    this.vlistSync(id)
+  }
+  vlistRemoveKeys = (id: number, keys: string[]): void => { this.rec("vlistRemoveKeys", id, keys.slice()); const v = this.vl(id); if (!v) return; v.keys = v.keys.filter((k) => !keys.includes(k)); this.vlistSync(id) }
+  vlistInvalidate = (id: number, key: string): void => { this.rec("vlistInvalidate", id, key) }
+  vlistMount = (id: number, key: string, item: number): void => { this.rec("vlistMount", id, key, item); const v = this.vl(id); if (v) v.mounted.set(key, item) }
+  vlistScrollTo = (id: number, offset: number, animated: boolean): void => { this.rec("vlistScrollTo", id, offset, animated) }
+  vlistScrollToKey = (id: number, key: string, animated: boolean): void => { this.rec("vlistScrollToKey", id, key, animated) }
+  vlistScrollToEnd = (id: number, animated: boolean): void => { this.rec("vlistScrollToEnd", id, animated) }
+
+  // ---- misc ------------------------------------------------------------------------------------------
+  registerFont = (family: string, url: string, weight: number, style: number, onComplete: () => void, onReject: () => void): void => { this.rec("registerFont", family, url, weight, style); void onReject; onComplete() }
+  toast = (message: string, durationMs: number): void => { this.rec("toast", message, durationMs) }
+  pressed = 0   // the node a test declares pressed (isButtonPressed)
+  isButtonPressed = (id: number): boolean => { this.rec("isButtonPressed", id); return id === this.pressed }
+  hovered = 0   // the node a test declares under the cursor (isHovered)
+  isHovered = (id: number): boolean => { this.rec("isHovered", id); return id === this.hovered }
+  getBoundingClientRect = (id: number): [number, number, number, number] | null => this.rects.get(id) ?? null
+  getDisplaySize = (): [number, number] => this.displaySize
+  tweenCreate = (data: Float32Array, strings: string[], targets: number[]): Handle => { const id = this.nextTween++; this.tweens.push({ id, data, strings, targets }); this.rec("tweenCreate", id, targets.slice()); return { id } }
+  tweenControl = (id: number, op: number): void => { this.rec("tweenControl", id, op) }
+  tweenSeek = (id: number, ms: number): void => { this.rec("tweenSeek", id, ms) }
+  tweenSetRate = (id: number, rate: number): void => { this.rec("tweenSetRate", id, rate) }
+  tweenGetTime = (id: number): number => 0
+  tweenGetElapsed = (id: number): number => 0
+  registerTweenEvent = (cb: (id: number, kind: number, index: number, ...lanes: number[]) => void): void => { this.tweenEvent = cb }
+  setEmitter = (fn: (id: number, kind: number, ...args: any[]) => any): void => {
+    this.emitter = fn
+    if (!FakeTree.primary) FakeTree.primary = fn
+  }
+  /** The FIRST emitter ever installed in this process: the test SDK's (the preload calls
+   *  `ensureEmitter()` right after installing the first fake). A test that compiles an app bundle
+   *  and imports it runs a SECOND SDK copy whose first element calls `setEmitter` too, hijacking
+   *  the shared fake for the rest of the process — every later file's tree events would land in
+   *  that dead copy's pins. `installFakeTree()` therefore restores the primary, not whatever the
+   *  previous fake last had; within the bundle test itself the bundle's emitter stays active. */
+  static primary: ((id: number, kind: number, ...args: any[]) => any) | null = null
+}
+
+/** Install a fresh fake as `_creatorTree`. The SDK installs its emitter / tween callback once per
+ *  world, so the fake carries them forward: the PRIMARY emitter (the test SDK's — see
+ *  `FakeTree.primary`), and the tween callback the previous fake had. The previous fake's nodes are
+ *  all reported freed first (TREE_EVENT_FREED, as the runtime reports a torn-down subtree): the new
+ *  fake restarts the ids at 1, and an element the SDK still pinned from an earlier test or file
+ *  would otherwise answer for the new node with the same id (`parent`, `children`, events). */
+export const installFakeTree = (): FakeTree => {
+  const prev = (globalThis as any)._creatorTree as FakeTree | undefined
+  if (prev) FakeTree.primary?.(0, TREE_EVENT_FREED, prev.allIds())
+  const fake = new FakeTree()
+  fake.emitter = FakeTree.primary ?? prev?.emitter ?? null
+  if (prev?.tweenEvent) fake.tweenEvent = prev.tweenEvent   // registered once per world too
+  _resetTransitions()   // …while a transition is registered per RUNTIME: the new fake has none
+  ;(globalThis as any)._creatorTree = fake
+  return fake
+}
+
+/** The fake currently installed. */
+export const fakeTree = (): FakeTree => (globalThis as any)._creatorTree as FakeTree
+
+/** Hand the installed fake back to the test SDK's emitter (`FakeTree.primary`). A file that evaluates
+ *  an app bundle runs a second SDK copy whose first element calls `setEmitter` on the SHARED fake:
+ *  it calls this in its afterAll, or every later file's tree events land in that dead copy. */
+export const restorePrimaryEmitter = (): void => {
+  if (FakeTree.primary) fakeTree().emitter = FakeTree.primary
+}

package/tests/helpers/hostStubs.ts

@@ -0,0 +1,31 @@
+// The split host tables (sdk/src/bridges: `_creatorApp _creatorDevice _creatorFetch _creatorStorage
+// _creatorMedia _creatorInput`) as MUTABLE stub objects, installed by the preload (bunfig.toml) BEFORE
+// any SDK module loads. The SDK reads the globals at call time, but bun test shares one module
+// registry across every test file, and the SDK's once-per-process registrations (the app-event
+// dispatcher, the media emitter) hand their callback to whichever table was current at that moment.
+// A test therefore MUTATES a stub (add / replace / delete members, or `Object.assign`), never
+// replaces the global; `resetHostStubs()` empties them all (call it from a beforeEach that installs
+// its own members, or `beforeAll` in a file that sets them once). `_creatorService`, `_creatorSocket`
+// and `_creatorFiles` are feature-detected at CALL time (typeof), so a test sets / deletes those
+// globals itself.
+export const appStub: any = {}
+export const deviceStub: any = {}
+export const fetchStub: any = {}
+export const storageStub: any = {}
+export const mediaStub: any = {}
+export const inputStub: any = {}
+
+const g = globalThis as any
+g._creatorApp = appStub
+g._creatorDevice = deviceStub
+g._creatorFetch = fetchStub
+g._creatorStorage = storageStub
+g._creatorMedia = mediaStub
+g._creatorInput = inputStub
+
+/** Empty every stub table (the members a previous test / file installed). */
+export const resetHostStubs = () => {
+  for (const s of [appStub, deviceStub, fetchStub, storageStub, mediaStub, inputStub]) {
+    for (const k of Object.keys(s)) delete s[k]
+  }
+}

package/tests/helpers/index.ts

@@ -0,0 +1,14 @@
+// `lecodes-sdk/testing` — the fake host of the SDK's own unit tests, for a test OUTSIDE this repo
+// that evaluates a compiled bundle with no runtime around (the scene editor's harness test in
+// lecodes-tools): the in-memory tree bridge, the host tables as mutable stubs, the entity world's
+// teardown. Such a suite preloads `lecodes-sdk/testing/preload` (bunfig.toml), exactly as this
+// package's does (tests/README.md has the rules: one process, leave nothing behind).
+//
+// Also what a `_creator` stub needs of the SDK to answer the way an engine does: the tree's event
+// constants and the quaternion (the euler order is the SDK's).
+
+export { fakeTree, installFakeTree, restorePrimaryEmitter, FakeTree, type FakeNode, type Call } from "./fakeTree"
+export { appStub, deviceStub, fetchStub, inputStub, mediaStub, storageStub, resetHostStubs } from "./hostStubs"
+export { freeEntities } from "./engineWorld"
+export * from "../../src/ui/tree"
+export { Quat } from "../../src/math/quat"

package/tests/helpers/memoryMarci.ts

@@ -0,0 +1,124 @@
+/**
+ * An in-memory `MarciTransport` for tests: enough of marcidb's query language for the auth runtime and
+ * simple endpoint tests (equality `$where` on scalars and `one` relations, `$and`, `$order`/`$limit`/
+ * `$skip`, select shapes with nested `one` selects, `$increment`, updateMany/deleteMany, count, batch).
+ * Defaults come from the model definitions. Not a marcidb — the e2e test against the real engine is
+ * the source of truth; this makes the flows runnable everywhere.
+ */
+import type { MarciOp, MarciTransport } from "../../src/server/db/marci/query"
+import type { Field, FieldDef } from "../../src/server/db/fields"
+import type { Model } from "../../src/server/db/types"
+
+type Row = Record<string, any>
+
+export const memoryMarci = (models: Record<string, Model> | (() => Record<string, Model>)) => {
+  const modelsOf = typeof models === "function" ? models : () => models
+  const tables = new Map<string, Row[]>()
+  const nextId = new Map<string, number>()
+  const defs = (model: string): Record<string, FieldDef> =>
+    Object.fromEntries(Object.entries(modelsOf()[model]?.fields ?? {}).map(([k, f]) => [k, (f as Field<any, any>).def]))
+  const rows = (model: string) => { let t = tables.get(model); if (!t) { t = []; tables.set(model, t) } return t }
+  const ops: MarciOp[] = []
+
+  const matchesField = (row: Row, key: string, cond: any, d: FieldDef | undefined): boolean => {
+    const v = row[key]
+    if (d && (d.kind === "one")) {
+      if (cond === null) return v === null || v === undefined
+      if (typeof cond === "object" && "id" in cond) return v?.id === cond.id
+      if (typeof cond === "object" && "$not" in cond) return !matchesField(row, key, cond.$not, d)
+      throw new Error(`memoryMarci: unsupported relation condition ${JSON.stringify(cond)}`)
+    }
+    if (cond !== null && typeof cond === "object" && !Array.isArray(cond)) {
+      for (const [op, x] of Object.entries(cond)) {
+        switch (op) {
+          case "$eq": if (v !== x) return false; break
+          case "$ne": case "$not": if (v === x) return false; break
+          case "$in": if (!(x as any[]).includes(v)) return false; break
+          case "$gt": if (!(v > (x as any))) return false; break
+          case "$gte": if (!(v >= (x as any))) return false; break
+          case "$lt": if (!(v < (x as any))) return false; break
+          case "$lte": if (!(v <= (x as any))) return false; break
+          default: throw new Error(`memoryMarci: unsupported operator ${op}`)
+        }
+      }
+      return true
+    }
+    return v === cond
+  }
+  const matches = (model: string, row: Row, where: any): boolean => {
+    if (!where) return true
+    if (where.$and) return where.$and.every((w: any) => matches(model, row, w))
+    if (where.$or) return where.$or.some((w: any) => matches(model, row, w))
+    if (where.$not) return !matches(model, row, where.$not)
+    const d = defs(model)
+    return Object.entries(where).every(([k, c]) => matchesField(row, k, c, d[k]))
+  }
+  const project = (model: string, row: Row, shape: Record<string, any>): Row => {
+    const out: Row = {}
+    const d = defs(model)
+    for (const [k, v] of Object.entries(shape)) {
+      if (k.startsWith("$") || v === false || v === undefined) continue
+      const def = d[k]
+      if (def?.kind === "one") {
+        const ref = row[k]
+        if (!ref) { out[k] = null; continue }
+        const target = rows(def.model!).find(r => r.id === ref.id)
+        out[k] = target ? (v === true ? { id: target.id } : project(def.model!, target, v)) : null
+        continue
+      }
+      out[k] = row[k] === undefined ? null : row[k]
+    }
+    return out
+  }
+  const select = (model: string, q: Record<string, any>): Row[] => {
+    let list = rows(model).filter(r => matches(model, r, q.$where))
+    if (q.$order) {
+      const [[f, dir]] = Object.entries(q.$order) as [string, string][]
+      list = [...list].sort((a, b) => (a[f] < b[f] ? -1 : a[f] > b[f] ? 1 : 0) * (dir === "desc" ? -1 : 1))
+    }
+    if (q.$skip) list = list.slice(q.$skip)
+    if (q.$limit !== undefined) list = list.slice(0, q.$limit)
+    return list.map(r => project(model, r, q))
+  }
+  const applyUpdate = (model: string, row: Row, data: Row) => {
+    const d = defs(model)
+    for (const [k, v] of Object.entries(data)) {
+      if (v !== null && typeof v === "object" && "$increment" in v) { row[k] = (row[k] ?? 0) + v.$increment; continue }
+      if (d[k]?.kind === "one") { row[k] = v === null ? null : { id: (v as any).id ?? (v as any).$connect?.id }; continue }
+      row[k] = v
+    }
+  }
+  const insert = (model: string, data: Row): Row => {
+    const d = defs(model)
+    const id = (nextId.get(model) ?? 0) + 1
+    nextId.set(model, id)
+    const row: Row = { id }
+    for (const [k, def] of Object.entries(d)) {
+      if (def.kind === "many" || def.kind === "list") continue
+      if (k in data && data[k] !== undefined) { row[k] = def.kind === "one" ? { id: data[k].id } : data[k]; continue }
+      if (def.hasDefault) { row[k] = def.default === "now" ? Date.now() : def.default; continue }
+      row[k] = null
+    }
+    rows(model).push(row)
+    return row
+  }
+  const idOf = (id: any) => (typeof id === "object" ? id.id : id)
+
+  const exec = async (op: MarciOp): Promise<any> => {
+    ops.push(op)
+    const { model, action } = op
+    switch (action) {
+      case "insert": return { id: insert(model, op.data).id }
+      case "findMany": return select(model, op.query ?? {})
+      case "findFirst": return select(model, { ...(op.query ?? {}), $limit: 1 })[0] ?? null
+      case "update": { const r = rows(model).find(r => r.id === idOf(op.id)); if (!r) throw new Error("not found"); applyUpdate(model, r, op.data); return null }
+      case "updateMany": { let n = 0; for (const r of rows(model)) if (matches(model, r, op.query?.$where)) { applyUpdate(model, r, op.data); n++ } return n }
+      case "delete": { const t = rows(model); const i = t.findIndex(r => r.id === idOf(op.id)); if (i >= 0) t.splice(i, 1); return i >= 0 }
+      case "deleteMany": { const t = rows(model); const keep = t.filter(r => !matches(model, r, op.query?.$where)); const n = t.length - keep.length; tables.set(model, keep); return n }
+      case "count": return rows(model).filter(r => matches(model, r, op.query?.$where)).length
+      default: throw new Error(`memoryMarci: unsupported action ${action}`)
+    }
+  }
+  const transport: MarciTransport = { exec, batch: async (batch) => { const out = []; for (const op of batch) out.push(await exec(op)); return out } }
+  return { transport, ops, rows, tables }
+}

package/tests/helpers/phases.ts

@@ -0,0 +1,23 @@
+// The aspect frame source for every test file, installed by the preload (bunfig.toml) BEFORE any
+// SDK module runs. core/Aspect.ts wires its phase runners ONCE per process: the first engine layer's
+// installer wins (`_installAspectFrames`, called by the first Scene / Scene2D), and the first
+// attached updater hands the runners to it — or, with no installer yet, to the `setLoop` of that
+// moment. bun test shares one module registry across files, so a file's own
+// `_creator.setEarlyUpdate` stub only ever saw them if that file happened to attach first (a
+// DynamicBone attached with no Scene, in an earlier file, sent them into its `setLoop = () => 1`).
+// A file that drives the phases by hand ticks through `tick` here instead.
+//
+// No fixed hook is installed: the SDK's own 1/60 accumulator steps `updateFixed` inside the early
+// phase, as on a host without setFixedUpdate. Files that compile a bundle (aspect-update,
+// aspect-lifecycle) run their own copy of the SDK and still capture the bridges' hooks themselves.
+import { _installAspectFrames } from "../../src/core/Aspect"
+
+type PhaseFn = (dt: number) => void
+
+/** The two render-synced phase runners, set on the first updater's attach (undefined until then). */
+export const phases: { early?: PhaseFn; late?: PhaseFn } = {}
+
+/** One frame: the early phase (updateBefore + the fixed fallback), then the late one (update). */
+export const tick = (dt: number): void => { phases.early?.(dt); phases.late?.(dt) }
+
+_installAspectFrames((early, late) => { phases.early = early; phases.late = late; return true })

package/tests/helpers/preload.ts

@@ -0,0 +1,18 @@
+// bun test preload (sdk/bunfig.toml): every test file starts with the split host tables installed as
+// mutable stubs (./hostStubs.ts — they MUST exist before the first SDK import, see there) and a fake
+// tree bridge, so UI elements can be constructed anywhere (the tree of truth: an element IS a runtime
+// node). Tests that inspect bridge traffic call `installFakeTree()` in their beforeEach for a fresh
+// recorder, and mutate / `resetHostStubs()` the host stubs for their own members. The aspect phase
+// runners go to ./phases.ts (once per process — see there); a file drives frames with its `tick`.
+//
+// `EDITOR` is a compile-time define (bundler.ts), so SDK source run as it is — here — has to be
+// given one: `true`, the editor bundle's value, which leaves edit mode to the run-time flag a test
+// sets (`__lecodesSceneEdit`) exactly as before.
+;(globalThis as { EDITOR?: boolean }).EDITOR = true
+import "./hostStubs"
+import "./phases"
+import { installFakeTree } from "./fakeTree"
+import { ensureEmitter } from "../../src/ui/tree"
+
+installFakeTree()
+ensureEmitter()   // the test SDK's emitter becomes the fake's PRIMARY (see FakeTree.primary)

package/tests/helpers/stubApp.ts

@@ -0,0 +1,2 @@
+// The `_creatorApp` stub — installed by the preload (see ./hostStubs.ts); mutate it, never replace the global.
+export { appStub } from "./hostStubs"

package/tests/helpers/stubDevice.ts

@@ -0,0 +1,2 @@
+// The `_creatorDevice` stub — installed by the preload (see ./hostStubs.ts); mutate it, never replace the global.
+export { deviceStub } from "./hostStubs"

package/tests/helpers/stubFetch.ts

@@ -0,0 +1,2 @@
+// The `_creatorFetch` stub — installed by the preload (see ./hostStubs.ts); mutate it, never replace the global.
+export { fetchStub } from "./hostStubs"

package/tests/helpers/stubInput.ts

@@ -0,0 +1,2 @@
+// The `_creatorInput` stub — installed by the preload (see ./hostStubs.ts); mutate it, never replace the global.
+export { inputStub } from "./hostStubs"