lecodes-cli 0.19.0 → 0.20.0

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)
-  }
-}

package/runtime/sdk/core/signals.ts

@@ -1,277 +0,0 @@
-// Fine-grained reactivity for the retained-mode UI: signal() / computed() / effect() globals plus
-// the element-binding helpers UINode/UIText use for function-valued style props and text.
-//
-// Design notes (the parts that are deliberate, not incidental):
-// - Dependents (effects, computeds) hold their sources STRONGLY; sources hold dependents WEAKLY
-//   (a WeakRef in the subscriber set). An element owns its binding effects, the effect's closure
-//   owns the element — so when user code drops a subtree, the whole element+effect subgraph
-//   becomes unreachable and collects, and the signal prunes the dead WeakRef on its next write.
-//   No unmount hook is needed and re-appending a kept subtree keeps its bindings alive.
-// - Free-standing effect() computations are additionally held in a strong root set (otherwise a
-//   `effect(() => ...)` whose handle the user discards would be GC'd mid-flight); dispose()
-//   releases them. Element bindings are NOT in the root set — the element is their owner.
-// - Writes are batched: a signal write schedules a microtask flush; each dirty effect runs once
-//   per flush. The first run of any effect/binding is synchronous, so element styles hold
-//   concrete values immediately after construction (hosts serialize _style at mount).
-// - QuickJS-safe: promise microtasks (the hosts drain pending jobs), WeakRef with a strong-ref
-//   fallback for engines without it (then stale subscribers just live until the run ends —
-//   every run executes in a fresh JSRuntime anyway).
-
-interface WeakRefLike<T extends object> { deref(): T | undefined }
-
-const WeakRefImpl: new <T extends object>(target: T) => WeakRefLike<T> =
-  typeof WeakRef !== "undefined" ? WeakRef : class StrongRef<T extends object> {
-    private _t: T
-    constructor(target: T) { this._t = target }
-    deref(): T | undefined { return this._t }
-  }
-
-interface Computation {
-  _ref: WeakRefLike<Computation>
-  _deps: Dep[]
-  _disposed: boolean
-  _invalidate(): void
-}
-
-let activeComputation: Computation | null = null
-
-/** Removes `c` from every source it subscribed to on its last run. */
-const cleanupDeps = (c: Computation) => {
-  for (const dep of c._deps) dep._subs.delete(c._ref)
-  c._deps.length = 0
-}
-
-class Dep {
-  _subs = new Set<WeakRefLike<Computation>>()
-
-  _track() {
-    const c = activeComputation
-    if (c === null || this._subs.has(c._ref)) return
-    this._subs.add(c._ref)
-    c._deps.push(this)
-  }
-
-  _notify() {
-    for (const ref of [ ...this._subs ]) {
-      const c = ref.deref()
-      if (c === undefined || c._disposed) {
-        this._subs.delete(ref)   // lazy pruning of collected/disposed subscribers
-      } else {
-        c._invalidate()
-      }
-    }
-  }
-}
-
-// ---- effect scheduling (microtask batch) ----
-
-const queue = new Set<EffectImpl>()
-let flushScheduled = false
-
-const flush = () => {
-  // Effects may write signals, re-filling the queue mid-flush; drain until empty with a guard
-  // against write-loops (effect A invalidating itself / a cycle of effects).
-  let runs = 0
-  while (queue.size > 0) {
-    if (++runs > 10000) {
-      queue.clear()
-      console.warn("signals: effect flush exceeded 10000 runs — possible infinite update loop, remaining effects dropped")
-      break
-    }
-    const first: EffectImpl = queue.values().next().value!
-    queue.delete(first)
-    first._run()
-  }
-  flushScheduled = false
-}
-
-const schedule = (fx: EffectImpl) => {
-  queue.add(fx)
-  if (!flushScheduled) {
-    flushScheduled = true
-    Promise.resolve().then(flush)
-  }
-}
-
-/** Runs every pending effect now instead of waiting for the microtask (test/host hook). */
-export const flushEffects = (): void => {
-  if (queue.size > 0) flush()
-}
-
-class EffectImpl implements Computation {
-  _ref: WeakRefLike<Computation>
-  _deps: Dep[] = []
-  _disposed = false
-  private _fn: () => void
-
-  constructor(fn: () => void) {
-    this._fn = fn
-    this._ref = new WeakRefImpl(this)
-  }
-
-  _run() {
-    if (this._disposed) return
-    cleanupDeps(this)
-    const prev = activeComputation
-    activeComputation = this
-    try {
-      this._fn()
-    } finally {
-      activeComputation = prev
-    }
-  }
-
-  _invalidate() {
-    schedule(this)
-  }
-
-  _dispose() {
-    if (this._disposed) return
-    this._disposed = true
-    cleanupDeps(this)
-    queue.delete(this)
-    rootEffects.delete(this)
-  }
-}
-
-// Free-standing effect() handles the user may never store — kept alive here until disposed.
-const rootEffects = new Set<EffectImpl>()
-
-// ---- public surface ----
-
-export interface Signal<T> {
-  value: T,
-  /** Read without subscribing the current effect/computed. */
-  peek(): T,
-}
-
-export interface Computed<T> {
-  readonly value: T,
-  /** Read without subscribing the current effect/computed (still recomputes if stale). */
-  peek(): T,
-}
-
-class SignalImpl<T> {
-  private _dep = new Dep()
-  private _v: T
-
-  constructor(value: T) {
-    this._v = value
-  }
-
-  get value(): T {
-    this._dep._track()
-    return this._v
-  }
-
-  set value(next: T) {
-    if (Object.is(next, this._v)) return
-    this._v = next
-    this._dep._notify()
-  }
-
-  peek(): T {
-    return this._v
-  }
-}
-
-class ComputedImpl<T> implements Computation {
-  _ref: WeakRefLike<Computation>
-  _deps: Dep[] = []
-  _disposed = false
-  private _dep = new Dep()
-  private _fn: () => T
-  private _stale = true
-  private _v!: T
-
-  constructor(fn: () => T) {
-    this._fn = fn
-    this._ref = new WeakRefImpl(this)
-  }
-
-  get value(): T {
-    this._dep._track()
-    if (this._stale) this._recompute()
-    return this._v
-  }
-
-  peek(): T {
-    if (this._stale) this._recompute()
-    return this._v
-  }
-
-  private _recompute() {
-    cleanupDeps(this)
-    const prev = activeComputation
-    activeComputation = this
-    try {
-      this._v = this._fn()
-      this._stale = false
-    } finally {
-      activeComputation = prev
-    }
-  }
-
-  // Lazy: a dep change only marks the memo stale and passes the wave downstream; the next read
-  // recomputes.
-  _invalidate() {
-    if (this._stale) return
-    this._stale = true
-    this._dep._notify()
-  }
-}
-
-/**
- * A reactive value. Reading `.value` inside an `effect`/`computed` (or a function-valued style
- * prop / `UIText` content) subscribes it; writing `.value` re-runs subscribers (batched — once
- * per microtask).
- */
-export function signal<T>(initialValue: T): Signal<T>
-export function signal<T = undefined>(): Signal<T | undefined>
-export function signal<T>(initialValue?: T): Signal<T | undefined> {
-  return new SignalImpl(initialValue)
-}
-
-/** A lazily-cached derived value: recomputes on read after any of its dependencies changed. */
-export function computed<T>(fn: () => T): Computed<T> {
-  return new ComputedImpl(fn)
-}
-
-/**
- * Runs `fn` now and again whenever any signal/computed it read changes (batched per microtask).
- * Returns a dispose function; an undisposed effect lives for the rest of the app run.
- */
-export function effect(fn: () => void): () => void {
-  const fx = new EffectImpl(fn)
-  rootEffects.add(fx)
-  fx._run()
-  return () => fx._dispose()
-}
-
-// ---- element bindings (internal — used by UINode/UIText for function-valued props) ----
-
-/** The shape UINode's Element exposes for binding ownership. */
-export interface BindingHost {
-  /** @internal */ _fx?: Map<string, EffectImpl>
-}
-
-/**
- * @internal Creates (or replaces) the reactive binding stored under `key` on the element. The
- * effect is owned by the element (strong ref in `_fx`), NOT by the root set — discard the element
- * and the binding collects with it. Runs synchronously once.
- */
-export function createBinding(el: BindingHost, key: string, run: () => void): void {
-  const map = el._fx ?? (el._fx = new Map())
-  map.get(key)?._dispose()
-  const fx = new EffectImpl(run)
-  map.set(key, fx)
-  fx._run()
-}
-
-/** @internal Disposes the binding stored under `key`, if any (static value overriding a binding). */
-export function disposeBinding(el: BindingHost, key: string): void {
-  const fx = el._fx?.get(key)
-  if (fx === undefined) return
-  fx._dispose()
-  el._fx!.delete(key)
-}

package/runtime/sdk/core/time.ts

@@ -1,84 +0,0 @@
-// The game clock: one place that owns "how fast does the game run" — `Time.scale` (slow-motion, 0.5),
-// `Time.paused` (a menu over a frozen world) — and what a frame is worth (`Time.dt`).
-//
-// The aspect dispatcher (core/Aspect.ts) calls `_beginFrame(rawDt)` once per frame with the host's
-// wall-clock delta; `update*(dt)` callbacks then receive the SCALED delta (0 while paused). The same
-// scale is pushed to every engine that registered a sink (creator-gl / creator-2d `setTimeScale`),
-// so physics, animators and particles slow down and freeze together with the game code — a paused
-// aspect and a paused rigid body agree. `Time.unscaledDt` is the wall-clock delta for things that
-// must keep moving while the game is paused (a HUD fade, a pause-menu animation): those aspects set
-// `updateWhilePaused = true` and read it themselves, exactly like Unity's unscaledDeltaTime.
-
-type ScaleSink = (scale: number) => void
-const sinks: ScaleSink[] = []
-
-class TimeClock {
-  private _scale = 1
-  private _paused = false
-  /** The fixed step: what `updateFixed(dt)` receives, every time, on every machine (1/60). Under
-   *  `scale` the NUMBER of fixed steps per frame changes, never this value. */
-  readonly fixedDt = 1 / 60
-  /** Seconds of GAME time since the app started (scaled; stops while paused). */
-  now = 0
-  /** Seconds of wall-clock time since the app started (never stops). */
-  unscaledNow = 0
-  /** This frame's delta in game seconds — what `update(dt)` receives. 0 while paused. */
-  dt = 0
-  /** This frame's wall-clock delta in seconds (the host's frame time, clamped by the engine). */
-  unscaledDt = 0
-  /** Frames dispatched since the app started (counts paused frames too). */
-  frame = 0
-
-  /** Speed of the game relative to wall-clock: 1 normal, 0.5 half speed, 2 double. Applied to
-   *  `dt`, `now` AND the engines' physics / animation / particle clocks. Negative or NaN → 0. */
-  get scale(): number { return this._scale }
-  set scale(v: number) {
-    const s = Number.isFinite(v) && v > 0 ? v : 0
-    if (s === this._scale) return
-    this._scale = s
-    this._push()
-  }
-
-  /** Freeze the game: `dt` reads 0, aspects without `updateWhilePaused` are skipped, the engines'
-   *  simulations stop. `scale` is remembered and restored on resume. */
-  get paused(): boolean { return this._paused }
-  set paused(v: boolean) {
-    if (v === this._paused) return
-    this._paused = v
-    this._push()
-  }
-
-  /** The scale the engines currently run at (0 while paused). */
-  get effectiveScale(): number { return this._paused ? 0 : this._scale }
-
-  private _push(): void {
-    const s = this.effectiveScale
-    for (const sink of sinks) sink(s)
-  }
-
-  /** @internal Called by the aspect dispatcher at the top of every frame with the host's raw delta. */
-  _beginFrame(rawDt: number): void {
-    const raw = Number.isFinite(rawDt) && rawDt > 0 ? rawDt : 0
-    this.frame++
-    this.unscaledNow += raw
-    this.now += this._phaseDt(raw)
-  }
-  /** @internal A phase's scaled delta from its raw one; records both as this frame's `dt`. */
-  _phaseDt(rawDt: number): number {
-    const raw = Number.isFinite(rawDt) && rawDt > 0 ? rawDt : 0
-    this.unscaledDt = raw
-    this.dt = raw * this.effectiveScale
-    return this.dt
-  }
-}
-
-/** The game clock — scale / pause the whole game, read `dt` / `now` anywhere. */
-export const Time = new TimeClock()
-
-/** @internal Engine layers (Scene / Scene2D) register the bridge call that forwards the effective
- *  scale to their native clocks. Pushed immediately with the current value so a scene created after
- *  `Time.paused = true` starts frozen. */
-export const _registerTimeScaleSink = (sink: ScaleSink): void => {
-  sinks.push(sink)
-  sink(Time.effectiveScale)
-}

package/runtime/sdk/g2/Camera2D.ts

@@ -1,40 +0,0 @@
-// Orthographic camera for a Scene2D. Position / zoom / rotation live natively. To make the camera
-// track a node, attach a small update(dt) aspect that eases camera.position toward the node — there's
-// no built-in follow() (and so nothing to dispose).
-
-import { Vec2, cx, cy, type Vec2Like } from "../math/vec"
-import type { CompAxis, CompWriter } from "../core/compWrite"
-
-export class Camera2D implements CompWriter {
-  private _x = 0
-  private _y = 0
-  private _zoom = 1
-  private _rotation = 0
-
-  private readonly sceneId: number
-  constructor(sceneId: number) { this.sceneId = sceneId }
-
-  get position(): Vec2 { return new Vec2(this._x, this._y) }
-  set position(v: Vec2Like) { this._x = cx(v); this._y = cy(v); _creator2d.cameraSetPosition(this.sceneId, this._x, this._y) }
-  /** @internal chisel `comp_write` (see core/compWrite.ts): `camera.position.<axis> = v` compiles to a call here. */
-  static _comps = [ "position" ]
-  _writeComp(_prop: string, axis: CompAxis, v: number): void {
-    if (axis === "x") this.position = [ v, this._y ]
-    else if (axis === "y") this.position = [ this._x, v ]
-  }
-
-  get zoom(): number { return this._zoom }
-  set zoom(z: number) { this._zoom = z; _creator2d.cameraSetZoom(this.sceneId, z) }
-
-  get rotation(): number { return this._rotation }
-  set rotation(deg: number) { this._rotation = deg; _creator2d.cameraSetRotation(this.sceneId, deg) }
-
-  screenToWorld(screenX: number, screenY: number): Vec2 {
-    const o = _creator2d.cameraScreenToWorld(this.sceneId, screenX, screenY)
-    return new Vec2(o[0], o[1])
-  }
-  worldToScreen(worldX: number, worldY: number): Vec2 {
-    const o = _creator2d.cameraWorldToScreen(this.sceneId, worldX, worldY)
-    return new Vec2(o[0], o[1])
-  }
-}