lecodes-cli 0.6.4 → 0.7.0

package/runtime/sdk/core/InspectorUI.ts

@@ -0,0 +1,212 @@
+// 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/fields.ts

@@ -8,10 +8,14 @@
 //   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. */
+/** 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"
+  | "vec2" | "vec3" | "vec4" | "node" | "asset"
 
 export type FieldMetaEntry = {
   /** Inspector label (default: the field name). */
@@ -49,10 +53,16 @@ export type AspectClassInfo = {
   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.
-const BASE_FIELDS = new Set([ "node", "updateBeforePhysics", "order", "updateWhenVisible" ])
+// `generated` is declare-only in TS, but the bundler lowers it to a real (undefined) class field.
+const BASE_FIELDS = new Set([ "node", "generated", "updateBeforePhysics", "order", "updateWhenVisible" ])
 
 /** Infer the editor widget from a default value's shape. */
 export const inferFieldEditor = (value: unknown): FieldEditor | undefined => {
@@ -105,4 +115,6 @@ export const describeAspect = (ctor: abstract new () => unknown): AspectClassInf
   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/gl/Node.ts

@@ -130,7 +130,10 @@ export class Node extends AspectHost<NodeEvents> {
   set quaternion(v: QuatLike) { this._lastSync = 0; _creator.setQuaternion(this.id, cx(v), cy(v), cz(v), cw(v)) }
 
   get eulerAngles(): Vec3 { return new Mat4(this._sync()).eulerAngles }
-  set eulerAngles(v: Vec3Like) { this._lastSync = 0; _creator.setEulerAngles(this.id, cx(v), cy(v), cz(v), 0) }
+  // order 1 = YXZ — the SDK's euler convention (math/quat.ts); the getter also extracts YXZ, so
+  // the pair round-trips. (Historically this passed 0/XYZ AND the engine stored the euler matrix
+  // transposed — the setter applied the INVERSE rotation. Both fixed 2026-07-10.)
+  set eulerAngles(v: Vec3Like) { this._lastSync = 0; _creator.setEulerAngles(this.id, cx(v), cy(v), cz(v), 1) }
 
   // --- world-space reads ---
   get forward(): Vec3 {

package/runtime/sdk/gl/scenarios.ts

@@ -0,0 +1,349 @@
+// No-code scenario aspects: ready-made behaviors a scene builder attaches in the editor without
+// writing any code — move to a target, travel a waypoint path, spin, face something, start a GLB
+// animation. They are ordinary aspects (work from hand-written code too); in the scene editor the
+// movement ones double as `static editor` generators that draw their paths as editor-only lines
+// (edges meshes under `this.generated` — play mode never calls rebuild(), so the lines cost
+// nothing at runtime).
+//
+// Conventions shared by the family:
+//   • targets/waypoints are scene nodes — place an Empty, then pick it in the inspector (`ref()`);
+//   • times are seconds, angles degrees; all motion runs in `update(dt)` (play mode only);
+//   • orientation is quaternion-composed — never euler-incremented (see math/quat.ts).
+
+import { Aspect } from "../core/Aspect"
+import type { FieldMeta } from "../core/fields"
+import type { InspectorUI } from "../core/InspectorUI"
+import { Vec3 } from "../math/vec"
+import { Quat } from "../math/quat"
+import { Node } from "./Node"
+import { Mesh } from "./Mesh"
+import { Model } from "./Model"
+import { Geometry } from "./Geometry"
+import { Material } from "./Material"
+
+const MOVE_LINE = "#5b8ef0"
+const LOOK_LINE = "#d9a13f"
+const DEG2RAD = Math.PI / 180
+
+type LoopMode = "once" | "loop" | "pingpong"
+
+/** Normalized phase for elapsed time `t` over one trip of `duration`: once clamps at 1, loop
+ *  wraps, pingpong triangles 0→1→0. */
+const phase = (t: number, duration: number, mode: LoopMode): number => {
+  if (duration <= 0) return 1
+  const u = t / duration
+  if (mode === "once") return Math.min(u, 1)
+  if (mode === "loop") return u - Math.floor(u)
+  const v = u % 2
+  return v <= 1 ? v : 2 - v
+}
+
+const ease = (k: number, easing: "smooth" | "linear"): number =>
+  easing === "smooth" ? k * k * (3 - 2 * k) : k
+
+/** A world point in `node`'s PARENT space — what `node.position` is expressed in. */
+const toParentLocal = (node: Node, world: Vec3): Vec3 => {
+  const parent = node.parent
+  return parent ? parent.worldMatrix.invert().transformPoint(world) : world
+}
+
+// ---- editor line drawing (edit mode only — see rebuild() on the aspects below) -------------------
+
+/** @internal An "edges" line mesh from flat segment endpoints ([x,y,z, x,y,z] per segment) —
+ *  editor-only visuals (path lines here, node markers in defineScene). */
+export const edgesMesh = (segments: number[], color: string): Mesh => {
+  const vertices = new Float32Array(segments)
+  const count = vertices.length / 3
+  const normals = new Float32Array(count * 3)
+  for (let i = 0; i < count; i++) normals[i * 3 + 1] = 1
+  const indices = new Uint16Array(count)
+  for (let i = 0; i < count; i++) indices[i] = i
+  const geo = new Geometry(vertices, normals, indices, new Float32Array(count * 2))
+  geo.kind = "edges"
+  const mesh = Mesh.from(geo, { material: Material.unlit({ color }), name: "__editor_line" })
+  mesh.castShadows = false
+  mesh.receiveShadows = false
+  return mesh
+}
+
+const pushCross = (segments: number[], p: Vec3, s: number): void => {
+  segments.push(p.x - s, p.y, p.z, p.x + s, p.y, p.z)
+  segments.push(p.x, p.y - s, p.z, p.x, p.y + s, p.z)
+  segments.push(p.x, p.y, p.z - s, p.x, p.y, p.z + s)
+}
+
+/** `this.generated` hangs UNDER the host node, so line points (world space) must be expressed in
+ *  the host's local frame; the host is an editor-run dep of its own aspects, so dragging it
+ *  re-runs rebuild() and the conversion stays fresh. */
+const worldSegmentsToLocal = (node: Node, segments: number[]): number[] => {
+  const inv = node.worldMatrix.invert()
+  const out: number[] = []
+  for (let i = 0; i < segments.length; i += 3) {
+    const p = inv.transformPoint([ segments[i]!, segments[i + 1]!, segments[i + 2]! ])
+    out.push(p.x, p.y, p.z)
+  }
+  return out
+}
+
+/** A path node's waypoints: its children in scene-FILE order (`_sceneChildOrder`, stamped by
+ *  defineScene — the engine's live child order is insertion-based and may differ), editor helper
+ *  nodes (`__`-prefixed) excluded. Runtime-added children append in engine order. */
+const pathWaypoints = (path: Node): Node[] => {
+  const children = path.children.filter((c) => !(c.name ?? "").startsWith("__"))
+  const order = (path as { _sceneChildOrder?: string[] })._sceneChildOrder
+  if (!order) return children
+  const byName = new Map(children.map((c) => [ c.name, c ]))
+  const sorted: Node[] = []
+  for (const n of order) { const c = byName.get(n); if (c) sorted.push(c) }
+  const seen = new Set(sorted)
+  for (const c of children) if (!seen.has(c)) sorted.push(c)
+  return sorted
+}
+
+// ---- the aspects ---------------------------------------------------------------------------------
+
+/** Travel from the node's starting position to a target node in `duration` seconds. */
+export class MoveTo extends Aspect<"moveTo"> {
+  /** Where to travel — place an Empty node and pick it. */
+  target: Node | null = null
+
+  /** Seconds for the full trip. */
+  duration = 2
+
+  /** Seconds to wait before starting. */
+  delay = 0
+
+  /** once = stop at the target · loop = restart from the start point · pingpong = back and forth. */
+  mode: LoopMode = "once"
+
+  /** Motion curve. */
+  easing: "smooth" | "linear" = "smooth"
+
+  static readonly aspect = "moveTo"
+  static editor = { rebuild: true }
+  static fields: FieldMeta<MoveTo> = {
+    target: { editor: "node" },
+    duration: { min: 0.05, max: 120, step: 0.05 },
+    delay: { min: 0, max: 120, step: 0.05 },
+    mode: { options: [ "once", "loop", "pingpong" ] },
+    easing: { options: [ "smooth", "linear" ] },
+  }
+
+  private _t = 0
+  private _start: Vec3 | null = null
+
+  update(dt: number): void {
+    if (!this.target) return
+    this._start ??= this.node.position
+    this._t += dt
+    const k = ease(phase(Math.max(0, this._t - this.delay), this.duration, this.mode), this.easing)
+    const end = toParentLocal(this.node, this.target.worldPosition)
+    this.node.position = new Vec3(this._start).add(end.sub(this._start).scale(k))
+  }
+
+  /** Editor-only path line (edit mode; play mode never calls this). */
+  rebuild(): void {
+    this.generated.clear()
+    if (!this.target) return
+    const segments: number[] = []
+    const a = this.node.worldPosition
+    const b = this.target.worldPosition
+    segments.push(a.x, a.y, a.z, b.x, b.y, b.z)
+    pushCross(segments, b, 0.09)
+    this.generated.add(edgesMesh(worldSegmentsToLocal(this.node, segments), MOVE_LINE))
+  }
+}
+
+/** Travel through the children of a path node (add an Empty per waypoint) in `duration` seconds.
+ *  `loop` runs the circuit closed (last → first); `pingpong` goes back and forth along the open
+ *  path; `once` stops at the last waypoint. */
+export class FollowPath extends Aspect<"followPath"> {
+  /** A node whose CHILDREN are the waypoints, in file order. */
+  path: Node | null = null
+
+  /** Seconds for one full pass of the path. */
+  duration = 6
+
+  /** Seconds to wait before starting. */
+  delay = 0
+
+  mode: LoopMode = "loop"
+
+  /** Turn to face the direction of travel. */
+  orient = true
+
+  /** Which local axis leads when orienting. */
+  forward: "-z" | "z" | "x" | "-x" = "-z"
+
+  static readonly aspect = "followPath"
+  static editor = { rebuild: true }
+  static fields: FieldMeta<FollowPath> = {
+    path: { editor: "node" },
+    duration: { min: 0.05, max: 300, step: 0.05 },
+    delay: { min: 0, max: 120, step: 0.05 },
+    mode: { options: [ "loop", "once", "pingpong" ] },
+    forward: { options: [ "-z", "z", "x", "-x" ] },
+  }
+
+  private _t = 0
+
+  private _points(): Vec3[] {
+    if (!this.path) return []
+    const points = pathWaypoints(this.path).map((c) => c.worldPosition)
+    if (this.mode === "loop" && points.length > 1) points.push(points[0]!.clone())
+    return points
+  }
+
+  update(dt: number): void {
+    const points = this._points()
+    if (points.length < 2) return
+    this._t += dt
+    const k = phase(Math.max(0, this._t - this.delay), this.duration, this.mode === "loop" ? "loop" : this.mode)
+
+    const lengths: number[] = []
+    let total = 0
+    for (let i = 0; i < points.length - 1; i++) {
+      const l = points[i + 1]!.sub(points[i]!).length()
+      lengths.push(l)
+      total += l
+    }
+    if (total <= 0) return
+
+    let dist = k * total
+    let i = 0
+    while (i < lengths.length - 1 && dist > lengths[i]!) { dist -= lengths[i]!; i++ }
+    const a = points[i]!
+    const b = points[i + 1]!
+    const seg = b.sub(a)
+    const u = lengths[i]! > 0 ? Math.min(dist / lengths[i]!, 1) : 0
+    const world = a.add(seg.scale(u))
+    this.node.position = toParentLocal(this.node, world)
+    if (this.orient && seg.lengthSq() > 1e-12) this.node.lookAt(world.add(seg), this.forward)
+  }
+
+  /** Editor-only waypoint polyline (edit mode; play mode never calls this). */
+  rebuild(): void {
+    this.generated.clear()
+    const points = this._points()
+    if (points.length < 2) return
+    const segments: number[] = []
+    for (let i = 0; i < points.length - 1; i++) {
+      const a = points[i]!, b = points[i + 1]!
+      segments.push(a.x, a.y, a.z, b.x, b.y, b.z)
+    }
+    for (const p of points) pushCross(segments, p, 0.07)
+    this.generated.add(edgesMesh(worldSegmentsToLocal(this.node, segments), MOVE_LINE))
+  }
+}
+
+/** Continuous rotation about one of the node's local axes, degrees per second. */
+export class Spin extends Aspect<"spin"> {
+  /** Degrees per second. */
+  speed = 45
+
+  /** Local axis to spin around. */
+  axis: "x" | "y" | "z" = "y"
+
+  static readonly aspect = "spin"
+  static fields: FieldMeta<Spin> = {
+    speed: { min: -720, max: 720, step: 5 },
+    axis: { options: [ "x", "y", "z" ] },
+  }
+
+  update(dt: number): void {
+    const axis: [number, number, number] = this.axis === "x" ? [ 1, 0, 0 ] : this.axis === "y" ? [ 0, 1, 0 ] : [ 0, 0, 1 ]
+    // compose in quaternion space about the LOCAL axis (q ⊗ dq) — never euler-increment
+    this.node.quaternion = this.node.quaternion.mul(Quat.fromAxisAngle(axis, this.speed * dt * DEG2RAD))
+  }
+}
+
+/** Keep the node facing a target node (a turret tracking, a signpost, a camera aimed at a hero).
+ *  Accessor `node.facing` — NOT `lookAt`, which would shadow the `Node.lookAt()` method. */
+export class LookAt extends Aspect<"facing"> {
+  /** The node to face. */
+  target: Node | null = null
+
+  /** Which local axis points at the target. */
+  forward: "-z" | "z" | "x" | "-x" = "-z"
+
+  /** 0 = snap instantly; otherwise seconds of turn lag (bigger = slower, smoother). */
+  smoothing = 0
+
+  static readonly aspect = "facing"
+  static editor = { rebuild: true }
+  static fields: FieldMeta<LookAt> = {
+    target: { editor: "node" },
+    forward: { options: [ "-z", "z", "x", "-x" ] },
+    smoothing: { min: 0, max: 5, step: 0.05 },
+  }
+
+  update(dt: number): void {
+    if (!this.target) return
+    const point = this.target.worldPosition
+    if (this.smoothing <= 0) { this.node.lookAt(point, this.forward); return }
+    const q0 = this.node.quaternion
+    this.node.lookAt(point, this.forward)
+    const q1 = this.node.quaternion
+    this.node.quaternion = q0.slerp(q1, 1 - Math.exp(-dt / this.smoothing))
+  }
+
+  /** Editor-only sight line (edit mode; play mode never calls this). */
+  rebuild(): void {
+    this.generated.clear()
+    if (!this.target) return
+    const segments: number[] = []
+    const a = this.node.worldPosition
+    const b = this.target.worldPosition
+    segments.push(a.x, a.y, a.z, b.x, b.y, b.z)
+    pushCross(segments, b, 0.07)
+    this.generated.add(edgesMesh(worldSegmentsToLocal(this.node, segments), LOOK_LINE))
+  }
+}
+
+/** Start a GLB animation clip when the scene runs. Attach to a `model:` node; the inspector card
+ *  lists the model's clips live and can preview them while editing. */
+export class PlayAnimation extends Aspect<"playAnimation", Model> {
+  /** Clip name; empty = the model's first clip. */
+  clip = ""
+
+  loop = true
+
+  /** Playback rate (1 = authored speed). */
+  speed = 1
+
+  static readonly aspect = "playAnimation"
+  static fields: FieldMeta<PlayAnimation> = {
+    speed: { min: 0.05, max: 5, step: 0.05 },
+  }
+
+  onAttach(): void {
+    const anim = (this.node as Model | undefined)?.anim
+    if (!anim) return
+    anim.speed = this.speed
+    anim.play(this.clip === "" ? 0 : this.clip, { loop: this.loop })
+  }
+
+  static inspector(ui: InspectorUI, a: PlayAnimation): void {
+    const anim = (a.node as Model | undefined)?.anim
+    const clips = anim?.clips ?? []
+    if (clips.length === 0) {
+      ui.warn("No animation clips — attach this to a GLB model node")
+      return
+    }
+    ui.select("clip", clips.map((c) => c.name))
+    ui.auto("loop", "speed")
+    if (anim) {
+      if (ui.button(anim.playing ? "Restart preview" : "Preview")) {
+        anim.speed = a.speed
+        anim.play(a.clip === "" ? 0 : a.clip, { loop: a.loop })
+      }
+      if (anim.playing && ui.button("Stop")) {
+        anim.stop()
+        anim.time = 0
+      }
+      const clip = a.clip === "" ? clips[0]?.name : a.clip
+      const duration = clips.find((c) => c.name === clip)?.duration
+      ui.info(anim.playing ? "previewing…" : duration !== undefined ? `${duration.toFixed(2)}s` : "")
+    }
+  }
+}

package/runtime/sdk/inject.ts

@@ -16,6 +16,7 @@ export { Color } from "./core/color"
 
 // ---- aspects (attachable node capabilities) ----
 export { Aspect, type With } from "./core/Aspect"
+export { InspectorUI } from "./core/InspectorUI"
 
 // ---- reactivity (signals; UI text/style props also accept `() => value` bindings) ----
 export { signal, computed, effect, type Signal, type Computed } from "./core/signals"
@@ -60,6 +61,7 @@ export {
   UIVideo, type UIVideoStyle,
   UIInput, UITextArea, type UIInputStyle,
   UIScrollable, type UIScrollableStyle,
+  UIScreenHost, type UIScreenHostStyle,
   UIWidget, type UIWidgetStyle,
   UISpacer, type UISpacerStyle,
   UIVirtualizedList,
@@ -71,6 +73,9 @@ export {
 // UIColumn/UIRow/append/etc., so they must be global (type-only; erased at runtime).
 export type { UINode, UINodeChild } from "./ui/UINode"
 
+// ---- UI kit (pure-TS components built on the core UI globals; see packages/sdk/src/kit/) ----
+export { UITabs, type UITabItem } from "./kit/UITabs"
+
 // ---- animate ----
 export { animate, animateMat4, stopAnimation, pauseAnimation, resumeAnimation } from "./animate/animate"
 export { cubicBezier } from "./animate/bezier"
@@ -80,10 +85,17 @@ export { easeIn, easeOut, easeInOut } from "./animate/easings"
 export { QRScanner } from "./plugins/qr"
 
 // ---- scenes as data (.scene.ts files — see src/scene/defineScene.ts) ----
-export { defineScene, use, SceneHandle } from "./scene/defineScene"
-export type { SceneDef, SceneNodeDef, MeshDef, LightDef, MaterialDef, AspectEntry, LoadedScene } from "./scene/defineScene"
+export { defineScene, use, ref, make, SceneHandle } from "./scene/defineScene"
+export type { SceneDef, SceneNodeDef, MeshDef, LightDef, MaterialDef, CameraNodeDef, AspectEntry, MakeEntry, LoadedScene } from "./scene/defineScene"
 export type { FieldMeta } from "./core/fields"
 
+// ---- no-code scenario aspects (attachable in the scene editor — see src/gl/scenarios.ts) ----
+export { MoveTo, FollowPath, Spin, LookAt, PlayAnimation } from "./gl/scenarios"
+
+// ---- editor plugins (called from `*.editor.ts` files — editor bundles only; DCE'd from apps) ----
+export { registerEditorWindow, registerEditorTool, __editorPlugins } from "./scene/editorPlugins"
+export type { EditorApi, EditorRayHit, EditorToolHooks, EditorWindowFn } from "./scene/editorPlugins"
+
 // ---- 3D engine (creator-gl) ----
 export { Scene, ARScene, VRScene } from "./gl/Scene"
 export { Node } from "./gl/Node"