lecodes-cli 0.18.2 → 0.19.2

package/runtime/sdk/core/InspectorUI.ts

@@ -1,212 +0,0 @@
-// The scene editor's immediate-mode inspector protocol (docs/scene-editor-plan.md, phase 9).
-//
-// Custom editor UI never renders into the editor panel directly — the live data (aspect instances,
-// nodes, `model.anim.clips`, generated meshes) lives in the SCENE WORLD (the compiled bundle), on
-// the other side of the controller. So a custom view is an imgui-style function running in the
-// world: it re-runs on every change/event and emits a WIDGET LIST (plain data); the editor panel is
-// a dumb renderer of that list; user events `{ id, value }` come back and trigger the next run —
-// `ui.button()` returns `true` on the run that consumes the click.
-//
-//   class Road extends Aspect<'road'> {
-//     from: Node | null = null
-//     to: Node | null = null
-//     width = 2
-//     static editor = { rebuild: true }
-//     static inspector(ui: InspectorUI, road: Road) {
-//       ui.auto()                                   // the inferred fields, as usual
-//       if (road.from && road.to) ui.info(`${road.generated.children.length} pieces`)
-//       else ui.warn('Assign both endpoints')
-//       if (ui.button('Shuffle')) road.rebuild()
-//     }
-//   }
-//
-// BINDING RULE: a field whose key is a declared aspect field (a public class field) is DOC-BOUND —
-// the editor persists edits to the scene file through its normal commit/undo path. Any other key is
-// EDITOR STATE — transient, kept on this InspectorUI instance across runs, never written to a file
-// (the animation card's clip choice, a tool's brush size). One vocabulary, two lifetimes.
-
-import type { FieldDescriptor, FieldEditor } from "./fields"
-
-/** One user interaction coming back from the editor panel: the widget's id (+ value for fields). */
-export type InspectorEvent = { id: string, value?: unknown }
-
-export type InspectorFieldWidget = {
-  kind: "field"
-  id: string
-  /** The bound key — an aspect field (doc-bound) or an editor-state key. */
-  key: string
-  label: string
-  editor: FieldEditor | undefined
-  value: unknown
-  /** True = persisted to the scene file by the editor; false = transient editor state. */
-  doc: boolean
-  /** True = emitted by `ui.auto()` — the editor may overlay its syntactic hints (options/node). */
-  auto?: boolean
-  min?: number
-  max?: number
-  step?: number
-  options?: readonly (string | number)[]
-}
-
-export type InspectorWidget =
-  | InspectorFieldWidget
-  | { kind: "button", id: string, label: string }
-  | { kind: "toolButton", id: string, label: string, tool: string }
-  | { kind: "header", id: string, label: string }
-  | { kind: "info" | "warn", id: string, text: string }
-
-type FieldOpts = {
-  label?: string
-  min?: number
-  max?: number
-  step?: number
-  /** Default for EDITOR-STATE keys (doc keys default from the class field). */
-  value?: unknown
-}
-
-/**
- * The widget builder handed to `static inspector(ui, aspect)` (and to editor windows/tools later).
- * One instance lives per card and persists across runs — it carries the card's editor state.
- */
-export class InspectorUI {
-  /** @internal This run's emitted widgets. */
-  _widgets: InspectorWidget[] = []
-  /** @internal Transient editor state (non-doc field keys), kept across runs. */
-  _state: Record<string, unknown> = {}
-  /** @internal The aspect entry's doc props (live reference — the runner keeps it current). */
-  _props: Record<string, unknown> = {}
-  /** @internal Keys that are declared aspect fields → doc-bound. Empty for node/window cards. */
-  _docKeys = new Set<string>()
-  /** @internal Field descriptors for auto() + doc-key defaults (describeFields output). */
-  _fields: FieldDescriptor[] = []
-  /** @internal The unconsumed button event of the current run. */
-  _event: InspectorEvent | null = null
-
-  // ---- fields (each emits one widget AND returns the current value) ---------------------------
-
-  /** Numeric field (min/max/step render as a slider-style scrub range). */
-  number(key: string, opts?: FieldOpts): number {
-    const v = this._field("number", key, opts)
-    return typeof v === "number" ? v : 0
-  }
-  /** Alias of `number` — give it min/max/step and the editor renders a scrubable range. */
-  slider(key: string, opts?: FieldOpts): number { return this.number(key, opts) }
-
-  text(key: string, opts?: FieldOpts): string {
-    const v = this._field("text", key, opts)
-    return typeof v === "string" ? v : ""
-  }
-
-  color(key: string, opts?: FieldOpts): string {
-    const v = this._field("color", key, opts)
-    return typeof v === "string" ? v : "#ffffff"
-  }
-
-  switch(key: string, opts?: FieldOpts): boolean {
-    return this._field("switch", key, opts) === true
-  }
-
-  /** Dropdown — `options` may be computed fresh every run (dynamic lists come free). */
-  select(key: string, options: readonly (string | number)[], opts?: FieldOpts): string | number {
-    const v = this._field("select", key, { ...opts, value: opts?.value ?? options[0] }, options)
-    return (typeof v === "string" || typeof v === "number") && options.includes(v) ? v : options[0]
-  }
-
-  vec2(key: string, opts?: FieldOpts): [number, number] { return this._vec("vec2", key, 2, opts) as [number, number] }
-  vec3(key: string, opts?: FieldOpts): [number, number, number] { return this._vec("vec3", key, 3, opts) as [number, number, number] }
-  vec4(key: string, opts?: FieldOpts): [number, number, number, number] { return this._vec("vec4", key, 4, opts) as [number, number, number, number] }
-
-  /** Scene-node reference (`ref()` fields): name dropdown + pick-in-viewport. Returns the RAW doc
-   *  value (`{ $ref }` marker or null) — read the resolved live node off the aspect instance. */
-  node(key: string, opts?: FieldOpts): unknown {
-    return this._field("node", key, opts)
-  }
-
-  /** Project-asset path (the editor renders a dropdown of the project's GLBs). "" = none picked. */
-  asset(key: string, opts?: FieldOpts): string {
-    const v = this._field("asset", key, { ...opts, value: opts?.value ?? "" })
-    return typeof v === "string" ? v : ""
-  }
-
-  // ---- everything else --------------------------------------------------------------------------
-
-  /** True on the run that consumes this button's click — do the action right there. */
-  button(label: string, opts?: { id?: string }): boolean {
-    const id = opts?.id ?? `b:${label}`
-    this._widgets.push({ kind: "button", id, label })
-    if (this._event?.id === id) {
-      this._event = null
-      return true
-    }
-    return false
-  }
-
-  /** A toggle that activates/deactivates the named viewport tool (`registerEditorTool`). The
-   *  editor owns the active-tool state — the click never round-trips into the scene world. */
-  toolButton(label: string, tool: string): void {
-    this._widgets.push({ kind: "toolButton", id: `t:${tool}`, label, tool })
-  }
-
-  header(label: string): void { this._widgets.push({ kind: "header", id: `h:${label}`, label }) }
-  info(text: string): void { this._widgets.push({ kind: "info", id: `i:${this._widgets.length}`, text }) }
-  warn(text: string): void { this._widgets.push({ kind: "warn", id: `w:${this._widgets.length}`, text }) }
-
-  /** Emit the inferred field widgets (all declared aspect fields, or just the named ones) — the
-   *  zero-ceremony baseline; append custom widgets around it. */
-  auto(...keys: string[]): void {
-    for (const f of this._fields) {
-      if (keys.length > 0 && !keys.includes(f.key)) continue
-      const value = this._props[f.key] !== undefined ? this._props[f.key] : f.value
-      this._widgets.push({
-        kind: "field", id: `f:${f.key}`, key: f.key, label: f.label, editor: f.editor,
-        value, doc: true, auto: true, min: f.min, max: f.max, step: f.step, options: f.options,
-      })
-    }
-  }
-
-  // ---- internals ----------------------------------------------------------------------------
-
-  private _vec(editor: FieldEditor, key: string, size: number, opts?: FieldOpts): number[] {
-    const v = this._field(editor, key, opts)
-    const arr = Array.isArray(v) ? v : []
-    return Array.from({ length: size }, (_, i) => (typeof arr[i] === "number" ? arr[i] as number : 0))
-  }
-
-  private _field(
-    editor: FieldEditor, key: string, opts?: FieldOpts, options?: readonly (string | number)[],
-  ): unknown {
-    const doc = this._docKeys.has(key)
-    const fallback = doc ? this._fields.find((f) => f.key === key)?.value : opts?.value
-    const stored = doc ? this._props[key] : this._state[key]
-    const value = stored !== undefined ? stored : fallback
-    this._widgets.push({
-      kind: "field", id: `f:${key}`, key, label: opts?.label ?? key, editor, value, doc,
-      min: opts?.min, max: opts?.max, step: opts?.step, options,
-    })
-    return value
-  }
-
-  /**
-   * @internal One immediate-mode pass: deliver `event`, run `fn`, return the widget list.
-   * Editor-state field events are applied here; DOC-key field events must be applied by the
-   * caller beforehand (they go through the scene loader's prop machinery — rebuilds, ref
-   * resolution); button events are consumed by the matching `button()` call during the run.
-   * A throwing inspector logs and shows the error as a warn line — it can't take the editor down.
-   */
-  _run(fn: (ui: this) => void, event?: InspectorEvent): InspectorWidget[] {
-    if (event && event.id.startsWith("f:") && !this._docKeys.has(event.id.slice(2))) {
-      this._state[event.id.slice(2)] = event.value
-      event = undefined
-    }
-    this._event = event ?? null
-    this._widgets = []
-    try {
-      fn(this)
-    } catch (e) {
-      console.error("[scene] inspector render failed:", e)
-      this.warn(String((e as Error)?.message ?? e))
-    }
-    this._event = null
-    return this._widgets
-  }
-}

package/runtime/sdk/core/color.ts

@@ -1,66 +0,0 @@
-// Shared color parsing for both engines. Users pass colors the natural ways — a CSS-ish hex string
-// ('#10131a', '#abc', '#rrggbbaa'), a packed number (0xff0000), or normalized components
-// ([r,g,b] / [r,g,b,a] in 0..1). The engines want different forms (2D wants 0..1 floats, 3D wants a
-// packed int), so this module is the single place that converts.
-
-export type ColorInput =
-  | string
-  | number
-  | readonly [number, number, number]
-  | readonly [number, number, number, number]
-
-const parseHexString = (input: string): [number, number, number, number] => {
-  let s = input.trim()
-  if (s[0] === "#") s = s.slice(1)
-  // #rgb / #rgba shorthand → double each nibble
-  if (s.length === 3 || s.length === 4) s = s.split("").map((c) => c + c).join("")
-  const int = parseInt(s, 16)
-  if (s.length === 8) return [ (int >>> 24) & 255, (int >> 16) & 255, (int >> 8) & 255, int & 255 ]
-  // default 6-digit (rrggbb); anything malformed falls back to opaque black
-  if (s.length === 6) return [ (int >> 16) & 255, (int >> 8) & 255, int & 255, 255 ]
-  return [ 0, 0, 0, 255 ]
-}
-
-/** Normalize any ColorInput to four 0..1 float components (array inputs pass through losslessly). */
-const toFloats = (c: ColorInput): [number, number, number, number] => {
-  if (typeof c === "number") return [ ((c >> 16) & 255) / 255, ((c >> 8) & 255) / 255, (c & 255) / 255, 1 ]
-  if (typeof c === "string") {
-    const b = parseHexString(c)
-    return [ b[0] / 255, b[1] / 255, b[2] / 255, b[3] / 255 ]
-  }
-  return [ c[0], c[1], c[2], (c as readonly number[])[3] ?? 1 ]
-}
-
-const toBytes = (c: ColorInput): [number, number, number, number] => {
-  const f = toFloats(c)
-  return [ Math.round(f[0] * 255), Math.round(f[1] * 255), Math.round(f[2] * 255), Math.round(f[3] * 255) ]
-}
-
-export const Color = {
-  /** [r,g,b] in 0..1 — for the 2D engine's float color setters. */
-  toRgb01(c: ColorInput): [number, number, number] {
-    const f = toFloats(c)
-    return [ f[0], f[1], f[2] ]
-  },
-  /** [r,g,b,a] in 0..1. */
-  toRgba01(c: ColorInput): [number, number, number, number] {
-    return toFloats(c)
-  },
-  /** 0xRRGGBB packed int — for the 3D engine's color uniforms / skybox. */
-  toPackedRgb(c: ColorInput): number {
-    const b = toBytes(c)
-    return (b[0] << 16) | (b[1] << 8) | b[2]
-  },
-  /** 0xRRGGBBAA packed int (unsigned). */
-  toPackedRgba(c: ColorInput): number {
-    const b = toBytes(c)
-    return ((b[0] << 24) | (b[1] << 16) | (b[2] << 8) | b[3]) >>> 0
-  },
-  /** '#rrggbb' (or '#rrggbbaa' when alpha < 1) — for the 3D material color uniforms. */
-  toHexString(c: ColorInput): string {
-    const b = toBytes(c)
-    const hex = (n: number) => n.toString(16).padStart(2, "0")
-    const base = `#${hex(b[0])}${hex(b[1])}${hex(b[2])}`
-    return b[3] >= 255 ? base : base + hex(b[3])
-  },
-}

package/runtime/sdk/core/compWrite.ts

@@ -1,42 +0,0 @@
-// Component writes on SDK-owned vectors — the runtime half of chisel's `comp_write` pass.
-//
-//   hero.controller.velocity.y = 7     →  __compWrite(hero.controller, "velocity", "y", 7)
-//   hero.controller.velocity.y += 3    →  __compOp(hero.controller, "velocity", "y", 0, 3)
-//
-// A getter like `velocity` hands out a fresh Vec3, so the literal spelling would write to a copy and
-// silently do nothing. chisel rewrites the exact `<owner>.<prop>.<x|y|z|w> = v` shape into these
-// helpers, which ask the OWNER to apply the component write (no getter call, no allocation) and
-// fall back to the plain write on anything else, so a user record `{ velocity: { x, y } }` behaves
-// exactly as written. Only the direct spelling is covered: `const v = c.velocity; v.y = 7` is still
-// a write to a copy.
-//
-// Owners today: Node / Node2D / Camera2D (`position` → the scalar setters, physics routing included),
-// Physics (`velocity`, `angularVelocity`), CharacterController / CharacterController2D (`velocity`).
-//
-// An owner declares WHICH getters qualify as compile-time data and answers them at runtime:
-//
-//   static _comps = ["velocity"]                 // chisel reads the list, then strips it (0 bytes shipped)
-//   _writeComp(prop, axis, value) { … }          // called for listed props only; a hook without the
-//                                                // list is a build diagnostic and routes nothing
-
-export type CompAxis = "x" | "y" | "z" | "w"
-
-/** Implemented by a class whose vector getters accept component writes (see above). The class also
- *  carries `static _comps: string[]` naming those getters — compile-time data, absent at runtime. */
-export interface CompWriter {
-  _writeComp(prop: string, axis: CompAxis, value: number): void
-}
-
-/** `<o>.<prop>.<axis> = value`, routed to the owner when it has the hook. Returns the value. */
-export const __compWrite = (o: any, prop: string, axis: CompAxis, value: number): number => {
-  if (o._writeComp !== undefined) o._writeComp(prop, axis, value)   // a direct call, not .call — cheaper on QuickJS
-  else o[prop][axis] = value
-  return value
-}
-
-/** `<o>.<prop>.<axis> op= v` — `op`: 0 `+=`, 1 `-=`, 2 `*=`, 3 `/=`. The current component is read
- *  through the normal getter (one fresh vector), the result written like `__compWrite`. */
-export const __compOp = (o: any, prop: string, axis: CompAxis, op: number, v: number): number => {
-  const cur = o[prop][axis] as number
-  return __compWrite(o, prop, axis, op === 0 ? cur + v : op === 1 ? cur - v : op === 2 ? cur * v : cur / v)
-}

package/runtime/sdk/core/events.ts

@@ -1,38 +0,0 @@
-// Tiny typed event dispatcher shared by media players, sockets, and (later) nodes. Keeps the
-// addEventListener / removeEventListener / dispatch boilerplate in one place.
-
-export type EventMap = Record<string, (...args: any[]) => void>
-
-export class Emitter<E extends EventMap> {
-  private _listeners: { [K in keyof E]?: E[K][] } = {}
-
-  addEventListener<K extends keyof E>(channel: K, callback: E[K]): void {
-    const list = this._listeners[channel]
-    if (list) list.push(callback)
-    else this._listeners[channel] = [ callback ]
-  }
-
-  removeEventListener<K extends keyof E>(channel: K, callback: E[K]): void {
-    const list = this._listeners[channel]
-    if (!list) return
-    const i = list.indexOf(callback)
-    if (i >= 0) list.splice(i, 1)
-  }
-
-  /** Fire all listeners on a channel. Protected: only the owning class emits. */
-  protected dispatch<K extends keyof E>(channel: K, ...args: Parameters<E[K]>): void {
-    const list = this._listeners[channel]
-    if (!list) return
-    for (const fn of list.slice()) fn(...args)
-  }
-
-  protected hasListeners<K extends keyof E>(channel: K): boolean {
-    const list = this._listeners[channel]
-    return !!list && list.length > 0
-  }
-
-  /** Drop every listener on every channel (used when the owning object is disposed). */
-  protected clearListeners(): void {
-    this._listeners = {}
-  }
-}

package/runtime/sdk/core/fields.ts

@@ -1,120 +0,0 @@
-// Field introspection for the scene-editor inspector: what's editable on an aspect, and with which
-// editor widget. Engine-agnostic (works for 2D and 3D aspects alike).
-//
-// The editable surface of an aspect is its public class fields with defaults — the same convention
-// aspects already follow for `node.aspect(Ctor, opts)` configuration. Editors are layered:
-//   1. inference from the default value's shape (number → number field, '#rrggbb' → color, …), free
-//      for every user aspect with zero ceremony;
-//   2. optional `static fields: FieldMeta<T>` on the class for ranges/labels/options/overrides
-//      (mirrors how `static aspect` declares the accessor name).
-
-/** Editor widget kinds the inspector knows how to render. `"node"` = a scene-node reference
- *  (`ref('name')` in the file, name dropdown + pick-in-viewport in the inspector) — declare it via
- *  `static fields` on fields typed `Node | null`; a `Node | null` type annotation is also picked
- *  up syntactically by the editor's source scan. `"asset"` = a project-asset path (the editor
- *  fills the dropdown with the project's GLBs — `ui.asset()` in windows/tools/cards). */
-export type FieldEditor =
-  | "number" | "text" | "color" | "switch" | "select"
-  | "vec2" | "vec3" | "vec4" | "node" | "asset"
-
-export type FieldMetaEntry = {
-  /** Inspector label (default: the field name). */
-  label?: string
-  min?: number
-  max?: number
-  step?: number
-  /** Allowed values — renders a dropdown (editor "select"). */
-  options?: readonly (string | number)[]
-  /** Override the editor inferred from the default value. */
-  editor?: FieldEditor
-  /** Exclude the field from the inspector. */
-  hidden?: boolean
-}
-
-/** Declared on an aspect class as `static fields: FieldMeta<MyAspect> = { … }`. All optional. */
-export type FieldMeta<T = unknown> = { [K in Extract<keyof T, string>]?: FieldMetaEntry }
-
-/** One editable field: key + default value + resolved editor + merged metadata. */
-export type FieldDescriptor = {
-  key: string
-  label: string
-  /** The default value (from a freshly constructed instance; undefined if only declared in meta). */
-  value: unknown
-  /** Resolved editor kind; undefined = no editor known (inspector shows it read-only). */
-  editor: FieldEditor | undefined
-  min?: number
-  max?: number
-  step?: number
-  options?: readonly (string | number)[]
-}
-
-export type AspectClassInfo = {
-  /** The accessor name (`static aspect`, injected by chisel for user aspects). */
-  name: string
-  className: string
-  fields: FieldDescriptor[]
-  /** True for editor-run classes (`static editor` — generators). The editor routes their
-   *  structural changes through a re-run instead of a live patch. */
-  editor?: boolean
-  /** True when the class declares a custom `static inspector(ui, aspect)` card. */
-  inspector?: boolean
-}
-
-// Instance fields every aspect inherits from the Aspect base — configuration plumbing, not content.
-// `generated` is declare-only in TS, but the bundler lowers it to a real (undefined) class field.
-const BASE_FIELDS = new Set([ "node", "generated", "updateOrder", "updateWhilePaused", "updateWhenVisible" ])
-
-/** Infer the editor widget from a default value's shape. */
-export const inferFieldEditor = (value: unknown): FieldEditor | undefined => {
-  if (typeof value === "boolean") return "switch"
-  if (typeof value === "number") return "number"
-  if (typeof value === "string") return value.startsWith("#") ? "color" : "text"
-  if (Array.isArray(value) && value.length >= 2 && value.length <= 4 && value.every((n) => typeof n === "number")) {
-    return value.length === 2 ? "vec2" : value.length === 3 ? "vec3" : "vec4"
-  }
-  return undefined
-}
-
-const cloneValue = (v: unknown): unknown => (Array.isArray(v) ? [ ...v ] : v)
-
-/**
- * Enumerate the editable fields of a class: construct a default instance, take its own enumerable
- * non-underscore fields (minus the Aspect base plumbing), infer editors from the default values, and
- * merge the class's optional `static fields` metadata (which can also add keys that have no runtime
- * default, e.g. fields declared without an initializer).
- */
-export const describeFields = (ctor: abstract new () => unknown): FieldDescriptor[] => {
-  let defaults: Record<string, unknown> = {}
-  // Aspects have no-arg constructors by convention (the engine creates them via node.aspect()); a
-  // class that throws here just loses default-value inference, it doesn't break the inspector.
-  try { defaults = new (ctor as new () => Record<string, unknown>)() } catch { /* meta-only */ }
-
-  const meta = ((ctor as { fields?: FieldMeta }).fields ?? {}) as Record<string, FieldMetaEntry>
-
-  const keys = new Set<string>()
-  for (const k of Object.keys(defaults)) {
-    if (BASE_FIELDS.has(k) || k.startsWith("_")) continue
-    if (typeof defaults[k] === "function") continue
-    keys.add(k)
-  }
-  for (const k of Object.keys(meta)) keys.add(k)
-
-  const out: FieldDescriptor[] = []
-  for (const key of keys) {
-    const m = meta[key] ?? {}
-    if (m.hidden) continue
-    const value = defaults[key]
-    const editor = m.editor ?? (m.options ? "select" : inferFieldEditor(value))
-    out.push({ key, label: m.label ?? key, value: cloneValue(value), editor, min: m.min, max: m.max, step: m.step, options: m.options })
-  }
-  return out
-}
-
-/** Describe an aspect class for the inspector: accessor name + class name + editable fields. */
-export const describeAspect = (ctor: abstract new () => unknown): AspectClassInfo => ({
-  name: (ctor as { aspect?: string }).aspect ?? "",
-  className: (ctor as { name?: string }).name ?? "",
-  fields: describeFields(ctor),
-  editor: (ctor as { editor?: unknown }).editor ? true : undefined,
-  inspector: typeof (ctor as { inspector?: unknown }).inspector === "function" ? true : undefined,
-})

package/runtime/sdk/core/registry.ts

@@ -1,23 +0,0 @@
-// Maps a native handle (the integer id the engine returns) back to its JS wrapper, so callbacks
-// the host fires by id (animation events, touch hits, media events) can be routed to the owning
-// object. Each engine/domain keeps its own Registry instance.
-
-export class Registry<T> {
-  private map = new Map<number, T>()
-
-  set(id: number, value: T): void {
-    this.map.set(id, value)
-  }
-
-  get(id: number): T | undefined {
-    return this.map.get(id)
-  }
-
-  delete(id: number): void {
-    this.map.delete(id)
-  }
-
-  has(id: number): boolean {
-    return this.map.has(id)
-  }
-}