lecodes-cli 0.17.2 → 0.18.0

package/runtime/sdk/core/Aspect.ts

@@ -1,244 +1,255 @@
-// The Aspect system: attachable capabilities (animation, collider, physics, and user behaviors)
-// that hang off a node WITHOUT bloating the node class. Composition with the terseness of methods.
-//
-//   const hero = new Sprite({ texture })
-//     .aspect(SpriteAnimation, { fps: 8, clips: { walk: [1, 2, 3] } })   // attach + configure
-//     .aspect(Shape2D, { box: [16, 8] })                                 // chains: returns the node
-//   hero.anim.play('walk')          // access by name (the chain result is typed as having it)
-//   if (hero.has(Physics)) hero.physics.velocity = [0, 0]                // has() is a type guard
-//
-// A user aspect declares its name + target node in the generic and reads `this.node`:
-//   class Health extends Aspect<'health', Sprite> { hp = 100; hurt(n: number) { this.hp -= n } }
-//   sprite.aspect(Health, { hp: 80 }).health.hurt(10)
-//
-// The accessor name lives in the generic (Aspect<'name', Node>). The `chisel` bundler extracts it at
-// compile time and injects the runtime `static aspect` on user aspects + the virtual type accessor;
-// the SDK's own built-in aspects declare `static readonly aspect` directly (see SpriteAnimation etc.).
-
-import { Emitter, type EventMap } from "./events"
-import type { InspectorUI } from "./InspectorUI"
-import type { Node } from "../gl/Node"
-
-// ---- type helpers -----------------------------------------------------------
-/** The class object of an aspect — accepted even when its constructor is protected/abstract. */
-export type AspectCtor<A extends Aspect<any, any>> = abstract new () => A
-/** The accessor name carried in the aspect's generic. */
-export type KeyOf<A> = A extends Aspect<infer K, any> ? K : never
-/** The node kind an aspect targets. */
-export type TargetOf<A> = A extends Aspect<any, infer P> ? P : never
-/** `{ name: Aspect }` — the field an aspect contributes to its node. */
-export type FieldOf<A extends Aspect<any, any>> = { [P in KeyOf<A>]: A }
-
-type UnionToIntersection<U> =
-  (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never
-
-/**
- * A variable typed as a node KNOWN to carry the given aspect(s). Union, not a tuple — reads as
- * English and mirrors the runtime guard `node.has(Health)`:
- *   let boss: With<Sprite, Health | Physics>
- */
-export type With<N, A extends Aspect<any, any>> =
-  N & UnionToIntersection<A extends any ? FieldOf<A> : never>
-
-// ---- per-frame update dispatch (two phases) ---------------------------------
-// Aspects that define update(dt) are ticked every frame in ONE of two phases, chosen by the aspect's
-// `updateBeforePhysics` field:
-//   • LATE (default): after the physics step + transform sync, right before the frame draws. Reads of
-//     node.worldPosition are the FINAL drawn position — cameras/followers land exactly, no 1-frame lag.
-//   • EARLY (updateBeforePhysics = true): before the physics step, so writing velocity/force/kinematic
-//     transforms is consumed by the SAME frame's step (zero input latency).
-// The FRAME SOURCE is pluggable so core never names a specific engine bridge (a 3D-only bundle must not
-// pull in the 2D one): the 2D layer installs a render-synced source via _installAspectFrames (the native
-// c2dRender early/late hooks), so dispatch is in lockstep with the draw. With none installed (3D-only,
-// or a runtime without the hooks) it falls back to a single host setLoop, early-then-late — no true
-// post-physics slot. Both lists stay sorted by the aspect's `order` field (default 0; ties keep
-// insertion order). Lazy: the first update-bearing aspect installs the dispatch; a project with none
-// starts nothing. No visibility culling yet — every registered aspect ticks regardless of on-screen state.
-type Updatable = Aspect<any, any>
-type PhaseFn = (dt: number) => void
-const earlyUpdaters: Updatable[] = []
-const lateUpdaters: Updatable[] = []
-let dispatchInstalled = false
-
-// A render-synced frame source: given the two phase runners, wire them to the engine and return true;
-// return false if unavailable (→ setLoop fallback). Installed by the 2D layer (see Scene2D) so core
-// never references a concrete engine bridge — that keeps the 2D bridge out of a 3D-only bundle.
-type FrameInstaller = (early: PhaseFn, late: PhaseFn) => boolean
-let frameInstaller: FrameInstaller | undefined
-/** @internal Install a render-synced frame source for aspect update(dt). Called from the 2D layer. */
-export const _installAspectFrames = (fn: FrameInstaller): void => { frameInstaller = fn }
-
-const policyOf = (a: Updatable): { early: boolean; order: number } =>
-  ({ early: a.updateBeforePhysics === true, order: a.order ?? 0 })
-
-// Stable insert by ascending order: place after the last element whose order is <= this one's.
-const addSorted = (list: Updatable[], a: Updatable, order: number): void => {
-  let i = list.length
-  while (i > 0 && list[i - 1].order > order) i--
-  list.splice(i, 0, a)
-}
-
-const runPhase = (list: Updatable[], dt: number): void => {
-  // iterate a snapshot so an update() that attaches/detaches aspects can't corrupt this frame's pass
-  for (const a of list.slice()) a.update?.(dt)
-}
-
-const ensureDispatch = (): void => {
-  if (dispatchInstalled) return
-  dispatchInstalled = true
-  const early: PhaseFn = (dt) => runPhase(earlyUpdaters, dt)
-  const late: PhaseFn = (dt) => runPhase(lateUpdaters, dt)
-  // render-synced source if the engine layer installed one; else one host loop (early then late).
-  if (!(frameInstaller && frameInstaller(early, late))) {
-    setLoop((dt) => { early(dt); late(dt) })
-  }
-}
-
-const registerUpdater = (a: Updatable): void => {
-  const { early, order } = policyOf(a)
-  addSorted(early ? earlyUpdaters : lateUpdaters, a, order)
-  ensureDispatch()
-}
-const unregisterUpdater = (a: Updatable): void => {
-  let i = earlyUpdaters.indexOf(a)
-  if (i >= 0) { earlyUpdaters.splice(i, 1); return }
-  i = lateUpdaters.indexOf(a)
-  if (i >= 0) lateUpdaters.splice(i, 1)
-}
-
-// ---- the host: mixed into every node kind (Node2D, Node) --------------------
-/**
- * Base for anything that can carry aspects. Extends Emitter, so node kinds get events too. Provides
- * the four verbs; the named accessor (node.physics, node.health, …) is set as an own property at
- * attach time, keyed by the aspect class's runtime `aspect` name.
- */
-export abstract class AspectHost<E extends EventMap = EventMap> extends Emitter<E> {
-  /** @internal class → instance, the authoritative store (named accessors mirror this). */
-  readonly _aspects = new Map<Function, Aspect<any, any>>()
-
-  /** Attach (and configure) an aspect, or reconfigure it if already present. Returns the node typed
-   *  as now-having that aspect (so no guard/`?.` is needed afterwards). Rejects a wrong target node. */
-  aspect<Self extends TargetOf<A>, A extends Aspect<any, any>>(
-    this: Self,
-    ctor: AspectCtor<A>,
-    opts?: Partial<A>,
-  ): Self & FieldOf<A> {
-    const host = this as unknown as AspectHost
-    let inst = host._aspects.get(ctor) as A | undefined
-    const fresh = inst === undefined
-    if (!inst) {
-      inst = new (ctor as unknown as new () => A)()
-      ;(inst as { node: unknown }).node = this
-      host._aspects.set(ctor, inst)
-      const name = (ctor as { aspect?: string }).aspect
-      if (name) (host as unknown as Record<string, unknown>)[name] = inst
-    }
-    if (opts) Object.assign(inst, opts)
-    if (fresh) {
-      inst.onAttach?.()
-      if (typeof inst.update === "function") registerUpdater(inst)
-    }
-    return this as Self & FieldOf<A>
-  }
-
-  /** Safe access — undefined if the aspect isn't attached. */
-  get<A extends Aspect<any, any>>(ctor: AspectCtor<A>): A | undefined {
-    return this._aspects.get(ctor) as A | undefined
-  }
-
-  /** Existence check AND type guard: inside `if (node.has(Physics))`, `node.physics` is present. */
-  has<A extends Aspect<any, any>>(ctor: AspectCtor<A>): this is this & FieldOf<A> {
-    return this._aspects.has(ctor)
-  }
-
-  /** Detach an aspect (runs its onDetach). Named `removeAspect` so it never collides with the
-   *  child-management `add`/`remove` semantics some node kinds expose. */
-  removeAspect<A extends Aspect<any, any>>(ctor: AspectCtor<A>): this {
-    const inst = this._aspects.get(ctor)
-    if (inst) {
-      inst.onDetach?.()
-      unregisterUpdater(inst)
-      this._aspects.delete(ctor)
-      const name = (ctor as { aspect?: string }).aspect
-      if (name) delete (this as unknown as Record<string, unknown>)[name]
-    }
-    return this
-  }
-}
-
-// ---- the aspect base --------------------------------------------------------
-/**
- * Base for everything you attach. `K` = accessor name (extracted by chisel for the runtime). `P` =
- * the target node kind: `this.node` is typed to it, AND attaching to a wrong node is a compile error.
- * Initialize in `onAttach` (the node is set by then) — not a constructor; aspects are created by the
- * engine via `node.aspect()`, never `new`.
- */
-export abstract class Aspect<K extends string, P = Node> {
-  /**
-   * Opt this aspect class into EDITOR-RUN mode (generators): while a scene is edited, the scene
-   * loader constructs the instance (refs resolved, `node`/`generated` set — never `onAttach`) and
-   * calls `rebuild()` — again on inspector prop edits and when a `ref()`-referenced node moves.
-   * `static editor = { rebuild: true }`.
-   */
-  static editor?: { rebuild?: boolean }
-
-  /**
-   * Custom inspector card for this aspect in the scene editor (immediate-mode — see
-   * core/InspectorUI.ts): re-runs on every edit/event and emits a widget list. Without it, the
-   * editor shows the inferred fields; `ui.auto()` emits those same fields, so a custom inspector
-   * usually starts with `ui.auto()` and appends status lines / buttons / dynamic dropdowns:
-   *
-   *   static inspector(ui: InspectorUI, self: MyAspect) {
-   *     ui.auto()
-   *     if (ui.button('Randomize')) self.rebuild()
-   *   }
-   */
-  static inspector?: (ui: InspectorUI, aspect: any) => void
-
-  // NOTE: P has no `extends AspectHost` constraint on purpose — Emitter<E>'s generic
-  // addEventListener makes a specific-event node (AspectHost<NodeEvents>) not assignable to
-  // AspectHost<any>, which would reject every real node. P only types `this.node`; target
-  // enforcement happens in aspect() via `this: Self extends TargetOf<A>`. Defaults to Node
-  // (3D is the default engine) — a 2D aspect declares its own P, e.g. Aspect<'x', Sprite>.
-  /** The node this aspect is attached to (set at attach time). */
-  readonly node!: P
-  /**
-   * GENERATOR aspects (`static editor = { rebuild: true }`, attached through a scene file): a
-   * scene-added container child for the aspect's generated output — `rebuild()` clears and refills
-   * it. Provided by the scene loader before `onAttach`/`rebuild` run; nodes `add()`ed to it join
-   * the scene's draw set automatically (membership is separate from parenting). Undefined for
-   * aspects attached by hand outside scene files. See docs/3d/scene-files.md.
-   */
-  readonly generated!: Node & { clear(): void }
-  /** @internal phantom — lets the type system recover the accessor name `K`. Never read at runtime. */
-  declare protected readonly __key__?: K
-  onAttach?(): void
-  onDetach?(): void
-  /**
-   * GENERATOR aspects: (re)build the derived output under `this.generated` — must be idempotent
-   * (clear, then create). Call it from `onAttach()` for play mode; a class opting in with
-   * `static editor = { rebuild: true }` ALSO runs it while a scene is being edited: once at load,
-   * and again whenever an inspector prop changes or a `ref()`-referenced node moves.
-   */
-  rebuild?(): void
-  /**
-   * Called every frame while attached (dt = seconds since the last frame). Render-synced: runs in the
-   * LATE phase by default — after the physics step + transform sync, right before the frame draws — so
-   * reads of `node.worldPosition` are the final drawn position (cameras/followers have no 1-frame lag).
-   * Set `updateBeforePhysics = true` (an instance field) to run in the EARLY phase (before the step)
-   * instead — for aspects that WRITE velocity/force/kinematic transforms and want the same frame's
-   * step to consume them. Cameras/followers READ, so they stay in the default LATE phase.
-   */
-  update?(dt: number): void
-
-  /** Run update(dt) in the EARLY phase (before the physics step) rather than the default LATE phase.
-   *  An instance field (like `updateWhenVisible`) — set it as a class field: `updateBeforePhysics = true`.
-   *  Use only when you FEED the simulation (velocity/force/kinematic transform). Read once, at attach. */
-  updateBeforePhysics = false
-  /** Tick order within a phase — ascending; default 0, ties keep attach order. Read once, at attach. */
-  order = 0
-
-  /** Opt-in: only run update(dt) while the node is on-screen. NOOP for now — visibility culling isn't
-   *  wired yet, so every updater ticks regardless; declared so aspects can opt in ahead of it. */
-  updateWhenVisible = false
-}
+// The Aspect system: attachable capabilities (animation, collider, physics, and user behaviors)
+// that hang off a node WITHOUT bloating the node class. Composition with the terseness of methods.
+//
+//   const hero = new Sprite({ texture })
+//     .aspect(SpriteAnimation, { fps: 8, clips: { walk: [1, 2, 3] } })   // attach + configure
+//     .aspect(Shape2D, { box: [16, 8] })                                 // chains: returns the node
+//   hero.anim.play('walk')          // access by name (the chain result is typed as having it)
+//   if (hero.has(Physics)) hero.physics.velocity = [0, 0]                // has() is a type guard
+//
+// A user aspect declares its name + target node in the generic and reads `this.node`:
+//   class Health extends Aspect<'health', Sprite> { hp = 100; hurt(n: number) { this.hp -= n } }
+//   sprite.aspect(Health, { hp: 80 }).health.hurt(10)
+//
+// The accessor name lives in the generic (Aspect<'name', Node>). The `chisel` bundler extracts it at
+// compile time and injects the runtime `static aspect` on user aspects + the virtual type accessor;
+// the SDK's own built-in aspects declare `static readonly aspect` directly (see SpriteAnimation etc.).
+
+import type { Scene } from "../gl/Scene"
+import { Emitter, type EventMap } from "./events"
+import type { InspectorUI } from "./InspectorUI"
+import type { Node } from "../gl/Node"
+
+// ---- type helpers -----------------------------------------------------------
+/** The class object of an aspect — accepted even when its constructor is protected/abstract. */
+export type AspectCtor<A extends Aspect<any, any>> = abstract new () => A
+/** The accessor name carried in the aspect's generic. */
+export type KeyOf<A> = A extends Aspect<infer K, any> ? K : never
+/** The node kind an aspect targets. */
+export type TargetOf<A> = A extends Aspect<any, infer P> ? P : never
+/** `{ name: Aspect }` — the field an aspect contributes to its node. */
+export type FieldOf<A extends Aspect<any, any>> = { [P in KeyOf<A>]: A }
+
+type UnionToIntersection<U> =
+  (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never
+
+/**
+ * A variable typed as a node KNOWN to carry the given aspect(s). Union, not a tuple — reads as
+ * English and mirrors the runtime guard `node.has(Health)`:
+ *   let boss: With<Sprite, Health | Physics>
+ */
+export type With<N, A extends Aspect<any, any>> =
+  N & UnionToIntersection<A extends any ? FieldOf<A> : never>
+
+// ---- per-frame update dispatch (two phases) ---------------------------------
+// Aspects that define update(dt) are ticked every frame in ONE of two phases, chosen by the aspect's
+// `updateBeforePhysics` field:
+//   • LATE (default): after the physics step + transform sync, right before the frame draws. Reads of
+//     node.worldPosition are the FINAL drawn position — cameras/followers land exactly, no 1-frame lag.
+//   • EARLY (updateBeforePhysics = true): before the physics step, so writing velocity/force/kinematic
+//     transforms is consumed by the SAME frame's step (zero input latency).
+// The FRAME SOURCE is pluggable so core never names a specific engine bridge (a 3D-only bundle must not
+// pull in the 2D one): the 2D layer installs a render-synced source via _installAspectFrames (the native
+// c2dRender early/late hooks), so dispatch is in lockstep with the draw. With none installed (3D-only,
+// or a runtime without the hooks) it falls back to a single host setLoop, early-then-late — no true
+// post-physics slot. Both lists stay sorted by the aspect's `order` field (default 0; ties keep
+// insertion order). Lazy: the first update-bearing aspect installs the dispatch; a project with none
+// starts nothing. No visibility culling yet — every registered aspect ticks regardless of on-screen state.
+type Updatable = Aspect<any, any>
+type PhaseFn = (dt: number) => void
+const earlyUpdaters: Updatable[] = []
+const lateUpdaters: Updatable[] = []
+let dispatchInstalled = false
+
+// A render-synced frame source: given the two phase runners, wire them to the engine and return true;
+// return false if unavailable (→ setLoop fallback). Installed by the 2D layer (see Scene2D) so core
+// never references a concrete engine bridge — that keeps the 2D bridge out of a 3D-only bundle.
+type FrameInstaller = (early: PhaseFn, late: PhaseFn) => boolean
+let frameInstaller: FrameInstaller | undefined
+/** @internal Install a render-synced frame source for aspect update(dt). Called from the 2D layer. */
+export const _installAspectFrames = (fn: FrameInstaller): void => { frameInstaller = fn }
+
+const policyOf = (a: Updatable): { early: boolean; order: number } =>
+  ({ early: a.updateBeforePhysics === true, order: a.order ?? 0 })
+
+// Stable insert by ascending order: place after the last element whose order is <= this one's.
+const addSorted = (list: Updatable[], a: Updatable, order: number): void => {
+  let i = list.length
+  while (i > 0 && list[i - 1].order > order) i--
+  list.splice(i, 0, a)
+}
+
+const runPhase = (list: Updatable[], dt: number): void => {
+  // iterate a snapshot so an update() that attaches/detaches aspects can't corrupt this frame's pass
+  for (const a of list.slice()) a.update?.(dt)
+}
+
+const ensureDispatch = (): void => {
+  if (dispatchInstalled) return
+  dispatchInstalled = true
+  const early: PhaseFn = (dt) => runPhase(earlyUpdaters, dt)
+  const late: PhaseFn = (dt) => runPhase(lateUpdaters, dt)
+  // render-synced source if the engine layer installed one; else one host loop (early then late).
+  if (!(frameInstaller && frameInstaller(early, late))) {
+    setLoop((dt) => { early(dt); late(dt) })
+  }
+}
+
+const registerUpdater = (a: Updatable): void => {
+  const { early, order } = policyOf(a)
+  addSorted(early ? earlyUpdaters : lateUpdaters, a, order)
+  ensureDispatch()
+}
+const unregisterUpdater = (a: Updatable): void => {
+  let i = earlyUpdaters.indexOf(a)
+  if (i >= 0) { earlyUpdaters.splice(i, 1); return }
+  i = lateUpdaters.indexOf(a)
+  if (i >= 0) lateUpdaters.splice(i, 1)
+}
+
+// ---- the host: mixed into every node kind (Node2D, Node) --------------------
+/**
+ * Base for anything that can carry aspects. Extends Emitter, so node kinds get events too. Provides
+ * the four verbs; the named accessor (node.physics, node.health, …) is set as an own property at
+ * attach time, keyed by the aspect class's runtime `aspect` name.
+ */
+export abstract class AspectHost<E extends EventMap = EventMap> extends Emitter<E> {
+  /** @internal class → instance, the authoritative store (named accessors mirror this). */
+  readonly _aspects = new Map<Function, Aspect<any, any>>()
+
+  /** Attach (and configure) an aspect, or reconfigure it if already present. Returns the node typed
+   *  as now-having that aspect (so no guard/`?.` is needed afterwards). Rejects a wrong target node. */
+  aspect<Self extends TargetOf<A>, A extends Aspect<any, any>>(
+    this: Self,
+    ctor: AspectCtor<A>,
+    opts?: Partial<A>,
+  ): Self & FieldOf<A> {
+    const host = this as unknown as AspectHost
+    let inst = host._aspects.get(ctor) as A | undefined
+    const fresh = inst === undefined
+    if (!inst) {
+      inst = new (ctor as unknown as new () => A)()
+      ;(inst as { node: unknown }).node = this
+      host._aspects.set(ctor, inst)
+      const name = (ctor as { aspect?: string }).aspect
+      if (name) (host as unknown as Record<string, unknown>)[name] = inst
+    }
+    if (opts) Object.assign(inst, opts)
+    if (fresh) {
+      inst.onAttach?.()
+      if (typeof inst.update === "function") registerUpdater(inst)
+    } else if (opts) inst.onReconfigure?.()
+    return this as Self & FieldOf<A>
+  }
+
+  /** Safe access — undefined if the aspect isn't attached. */
+  get<A extends Aspect<any, any>>(ctor: AspectCtor<A>): A | undefined {
+    return this._aspects.get(ctor) as A | undefined
+  }
+
+  /** Existence check AND type guard: inside `if (node.has(Physics))`, `node.physics` is present. */
+  has<A extends Aspect<any, any>>(ctor: AspectCtor<A>): this is this & FieldOf<A> {
+    return this._aspects.has(ctor)
+  }
+
+  /** Detach an aspect (runs its onDetach). Named `removeAspect` so it never collides with the
+   *  child-management `add`/`remove` semantics some node kinds expose. */
+  removeAspect<A extends Aspect<any, any>>(ctor: AspectCtor<A>): this {
+    const inst = this._aspects.get(ctor)
+    if (inst) {
+      inst.onDetach?.()
+      unregisterUpdater(inst)
+      this._aspects.delete(ctor)
+      const name = (ctor as { aspect?: string }).aspect
+      if (name) delete (this as unknown as Record<string, unknown>)[name]
+    }
+    return this
+  }
+}
+
+// ---- the aspect base --------------------------------------------------------
+/**
+ * Base for everything you attach. `K` = accessor name (extracted by chisel for the runtime). `P` =
+ * the target node kind: `this.node` is typed to it, AND attaching to a wrong node is a compile error.
+ * Initialize in `onAttach` (the node is set by then) — not a constructor; aspects are created by the
+ * engine via `node.aspect()`, never `new`.
+ */
+export abstract class Aspect<K extends string, P = Node> {
+  /**
+   * Opt this aspect class into EDITOR-RUN mode (generators): while a scene is edited, the scene
+   * loader constructs the instance (refs resolved, `node`/`generated` set — never `onAttach`) and
+   * calls `rebuild()` — again on inspector prop edits and when a `ref()`-referenced node moves.
+   * `static editor = { rebuild: true }`.
+   */
+  static editor?: { rebuild?: boolean }
+
+  /**
+   * Custom inspector card for this aspect in the scene editor (immediate-mode — see
+   * core/InspectorUI.ts): re-runs on every edit/event and emits a widget list. Without it, the
+   * editor shows the inferred fields; `ui.auto()` emits those same fields, so a custom inspector
+   * usually starts with `ui.auto()` and appends status lines / buttons / dynamic dropdowns:
+   *
+   *   static inspector(ui: InspectorUI, self: MyAspect) {
+   *     ui.auto()
+   *     if (ui.button('Randomize')) self.rebuild()
+   *   }
+   */
+  static inspector?: (ui: InspectorUI, aspect: any) => void
+
+  // NOTE: P has no `extends AspectHost` constraint on purpose — Emitter<E>'s generic
+  // addEventListener makes a specific-event node (AspectHost<NodeEvents>) not assignable to
+  // AspectHost<any>, which would reject every real node. P only types `this.node`; target
+  // enforcement happens in aspect() via `this: Self extends TargetOf<A>`. Defaults to Node
+  // (3D is the default engine) — a 2D aspect declares its own P, e.g. Aspect<'x', Sprite>.
+  /** The node this aspect is attached to (set at attach time). */
+  readonly node!: P
+  /**
+   * GENERATOR aspects (`static editor = { rebuild: true }`, attached through a scene file): a
+   * scene-added container child for the aspect's generated output — `rebuild()` clears and refills
+   * it. Provided by the scene loader before `onAttach`/`rebuild` run; nodes `add()`ed to it join
+   * the scene's draw set automatically (membership is separate from parenting). Undefined for
+   * aspects attached by hand outside scene files. See docs/3d/scene-files.md.
+   */
+  readonly generated!: Node & { clear(): void, readonly version: number }
+  /**
+   * GENERATOR aspects attached through a scene file: the `Scene` the host node was built into —
+   * what `handle.instantiate({ scene })` / `scene.add()` need inside `rebuild()`. Set by the scene
+   * loader (edit AND play mode); undefined for aspects attached by hand. 3D only (2D aspects own
+   * their `scene` field).
+   */
+  readonly scene!: P extends Node ? Scene : unknown
+  /** @internal phantom — lets the type system recover the accessor name `K`. Never read at runtime. */
+  declare protected readonly __key__?: K
+  onAttach?(): void
+  onDetach?(): void
+  /** Called after `node.aspect(Ctor, opts)` re-assigns options on an ALREADY attached aspect (a
+   *  pre-attached one like `model.anim`): rebuild whatever was derived from the options at attach. */
+  onReconfigure?(): void
+  /**
+   * GENERATOR aspects: (re)build the derived output under `this.generated` — must be idempotent
+   * (clear, then create). Call it from `onAttach()` for play mode; a class opting in with
+   * `static editor = { rebuild: true }` ALSO runs it while a scene is being edited: once at load,
+   * and again whenever an inspector prop changes or a `ref()`-referenced node moves.
+   */
+  rebuild?(): void
+  /**
+   * Called every frame while attached (dt = seconds since the last frame). Render-synced: runs in the
+   * LATE phase by default — after the physics step + transform sync, right before the frame draws — so
+   * reads of `node.worldPosition` are the final drawn position (cameras/followers have no 1-frame lag).
+   * Set `updateBeforePhysics = true` (an instance field) to run in the EARLY phase (before the step)
+   * instead — for aspects that WRITE velocity/force/kinematic transforms and want the same frame's
+   * step to consume them. Cameras/followers READ, so they stay in the default LATE phase.
+   */
+  update?(dt: number): void
+
+  /** Run update(dt) in the EARLY phase (before the physics step) rather than the default LATE phase.
+   *  An instance field (like `updateWhenVisible`) — set it as a class field: `updateBeforePhysics = true`.
+   *  Use only when you FEED the simulation (velocity/force/kinematic transform). Read once, at attach. */
+  updateBeforePhysics = false
+  /** Tick order within a phase — ascending; default 0, ties keep attach order. Read once, at attach. */
+  order = 0
+
+  /** Opt-in: only run update(dt) while the node is on-screen. NOOP for now — visibility culling isn't
+   *  wired yet, so every updater ticks regardless; declared so aspects can opt in ahead of it. */
+  updateWhenVisible = false
+}

package/runtime/sdk/g2/CharacterController2D.ts

@@ -6,8 +6,8 @@
 //     .aspect(Shape2D, { capsule: { from: [0, 6], to: [0, 26], radius: 6 } })
 //     .aspect(Physics2D, { motion: 'dynamic', fixedRotation: true })
 //     .aspect(CharacterController2D, { speed: 200, jumpSpeed: 520 })
-//   Input.on('left',  d => hero.controller.move(d ? -1 : 0))
-//   Input.on('jump',  () => hero.controller.jump())
+//   setLoop(() => hero.controller.move((Input.key('ArrowRight') ? 1 : 0) - (Input.key('ArrowLeft') ? 1 : 0)))
+//   Input.on('keydown', e => { if (e.code === 'Space') hero.controller.jump() })
 //
 // Velocity-control (set velocity each frame) is the standard, robust approach for platformers and
 // reuses the physics solver. For pixel-tight movement without any solver bounce/seam quirks, a

package/runtime/sdk/gl/Camera.ts

@@ -2,9 +2,23 @@
 // screen↔world ray helpers. Created and attached by Scene. Ported from worker/src/components/Camera.ts.
 
 import { Vec3 } from "../math/vec"
+import { Aspect } from "../core/Aspect"
 import { Node } from "./Node"
 import { Ray } from "./Ray"
 
+/** @internal `camera.follow(node)`: copies the node's world pose onto the camera every LATE frame
+ *  (order 1000 — after every other aspect has moved things). One per camera; lives on the target. */
+export class CameraFollowRig extends Aspect<"__cameraFollow"> {
+  static readonly aspect = "__cameraFollow"
+  /** @internal */ _camera!: Camera
+  constructor() { super(); this.order = 1000 }
+  update(): void {
+    const cam = this._camera
+    cam.position = this.node.worldPosition
+    cam.quaternion = this.node.worldQuaternion
+  }
+}
+
 /** Projection every host starts a scene with (creator-gl scene.cpp / the lite core agree on these). */
 export const CAMERA_DEFAULTS = { fov: 60, near: 0.01, far: 1000 }
 
@@ -60,6 +74,33 @@ export class Camera extends Node {
     if (this._sceneId < 0 || typeof _creator.setCameraProjection !== "function") return
     _creator.setCameraProjection(this._sceneId, this._fov, this._near, this._far)
   }
+  private _following: Node | null = null
+  /** The node the camera currently follows (`follow()`), or null. */
+  get following(): Node | null { return this._following }
+
+  /**
+   * Make the camera ride a node: every late frame the camera takes the node's WORLD pose (−Z =
+   * view direction), so movement aspects / animation on that node are camera moves — dolly shots,
+   * a cutscene path, a `CameraPlace` in a scene file. A node carrying a `CameraPlace` also hands
+   * over its projection (fov / near / far). `follow(null)` releases the camera where it is.
+   * One camera per scene: following a new node stops following the previous one.
+   */
+  follow(target: Node | { node: Node, applyTo(camera: Camera): void } | null): this {
+    const node = target === null ? null : target instanceof Node ? target : target.node
+    if (this._following && this._following !== node) this._following.removeAspect(CameraFollowRig)
+    this._following = node
+    if (!node) return this
+    // a CameraPlace on the node (or passed directly) sets the lens too
+    const place = target instanceof Node
+      ? (node as unknown as { cameraPlace?: { applyTo(camera: Camera): void } }).cameraPlace
+      : target as { applyTo(camera: Camera): void }
+    place?.applyTo(this)
+    node.aspect(CameraFollowRig, { _camera: this })
+    this.position = node.worldPosition
+    this.quaternion = node.worldQuaternion
+    return this
+  }
+
   get displaySize(): [number, number] {
     const s = _creator.getDisplaySize()
     return [ s[0], s[1] ]