lecodes-cli 0.6.4 → 0.7.1

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/g2/Scene2D.ts

@@ -3,6 +3,7 @@
 
 import { Color, type ColorInput } from "../core/color"
 import { _installAspectFrames } from "../core/Aspect"
+import { _bumpNavEpoch, _navSupported, _setCurrent, Presentable, type PresentOptions } from "../ui/presentable"
 import { cx, cy, type Vec2Like } from "../math/vec"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 import { Camera2D } from "./Camera2D"
@@ -48,7 +49,7 @@ class LayerHandle {
   }
 }
 
-export class Scene2D {
+export class Scene2D implements Presentable {
   /** Native scene handle. */
   readonly id: number
   readonly camera: Camera2D
@@ -111,17 +112,62 @@ export class Scene2D {
     return this
   }
 
-  /** Make this the active scene (brings up the 2D engine on the canvas; closes any other). */
-  open(): this {
+  // ---- Presentable (docs/navigation-presentable-plan.md) ----
+
+  /** @internal presentation lifecycle — fired by the host on present/dismiss (new navigation),
+   *  or synchronously by open()/close() on legacy hosts. */
+  readonly ol: (() => void)[] = []
+  readonly cl: (() => void)[] = []
+  _backButtonCallback?: () => void
+  private _vd?: object
+
+  /** Fires when the scene becomes the visible destination (incl. a pop revealing it). */
+  onOpen(callback: () => void): this {
+    this.ol.push(callback)
+    return this
+  }
+  /** Fires when the scene stops being visible (closed, replaced, or covered by a push). */
+  onClose(callback: () => void): this {
+    this.cl.push(callback)
+    return this
+  }
+  onBackPressed(callback: () => void): this {
+    this._backButtonCallback = callback
+    return this
+  }
+
+  /** @internal stable wire descriptor; hosts hand it back via router onChange (`_p` = this). */
+  _viewDesc(): object {
+    return this._vd ??= { type: "scene2d", sceneId: this.id, _p: this }
+  }
+
+  /** Make this the active scene — shows it as the current destination (replaces a screen /
+   *  another scene; only the active scene renders). */
+  open(options?: PresentOptions): this {
+    _bumpNavEpoch()
     // Reassert this scene's texture filter (the sampler is global — see Scene2DOptions.filter).
     if (this._filter !== undefined) _creator2d.setDefaultFilter(this._filter === 'linear')
-    _creator2d.openScene(this.id)
+    if (_navSupported()) {
+      // The host activates the engine (openScene) as part of presenting the destination.
+      _creatorUI.openView!(this._viewDesc(), options?.transition ?? "none")
+    } else {
+      _creator2d.openScene(this.id)
+      for (const cb of this.ol) cb()
+    }
     Scene2D._active = this
+    _setCurrent(this)
     return this
   }
   close(): this {
-    _creator2d.closeScene()
+    _bumpNavEpoch()
+    if (_navSupported()) {
+      _creatorUI.closeView!()
+    } else {
+      _creator2d.closeScene()
+      for (const cb of this.cl) cb()
+    }
     if (Scene2D._active === this) Scene2D._active = null
+    if (Presentable.current === this) _setCurrent(null)
     return this
   }
   destroy(): void {

package/runtime/sdk/gl/Model.ts

@@ -17,6 +17,15 @@ export class Model extends Node {
     this.aspect(ModelAnimation)
   }
 
+  /** Duplicate this model — a deep copy of the GLB (meshes, skeleton, animation clips), attached to
+   *  the same parent and scene and sharing this model's current transform. The clone has its own
+   *  independent animation state (reach it via clone.anim). Mirrors Model.load's culling default. */
+  clone(): Model {
+    const id = _creator.cloneEntity(this.id)
+    _creator.setGlbCulling(id, false)
+    return new Model(id)
+  }
+
   /** Load a GLB model. Returns its root as a Model; play its baked clips via model.anim. */
   static load(
     source: string | FetchResponse,

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/Scene.ts

@@ -7,8 +7,10 @@
 
 import { Color, type ColorInput } from "../core/color"
 import { _installAspectFrames } from "../core/Aspect"
+import { _bumpNavEpoch, _navEpoch, _navSupported, _setCurrent, Presentable, type PresentOptions } from "../ui/presentable"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 import type { FetchResponse } from "../runtime/fetch"
+import { _requestCameraPermission } from "../plugins/permission"
 import { Camera } from "./Camera"
 import { attachControls, type ControlsHandle, type ControlsOptions } from "./controls"
 import { Material } from "./Material"
@@ -46,7 +48,7 @@ const installRenderSyncedFrames = (): void => {
   })
 }
 
-export class Scene {
+export class Scene implements Presentable {
   /** @internal native scene handle. */
   readonly _id: number
   readonly camera: Camera
@@ -115,16 +117,64 @@ export class Scene {
     return new Promise<void>((res) => _creator.warmRender(this._id, res))
   }
 
-  /** Make this the active scene (brings up the 3D engine; closes any other). */
-  open(): void {
-    _creator.openScene(this._id)
+  // ---- Presentable (docs/navigation-presentable-plan.md) ----
+  // A scene is a destination like a screen: opening it replaces whatever is visible (suspending
+  // an active Router until Router.restore()), and it can be pushed onto the Router stack. The
+  // scene graph survives while covered — only the view detaches and rendering pauses.
+
+  /** @internal presentation lifecycle — fired by the host on present/dismiss (new navigation),
+   *  or synchronously by open()/close() on legacy hosts. */
+  readonly ol: (() => void)[] = []
+  readonly cl: (() => void)[] = []
+  _backButtonCallback?: () => void
+  private _vd?: object
+
+  /** Fires when the scene becomes the visible destination (incl. a pop revealing it). */
+  onOpen(callback: () => void): this {
+    this.ol.push(callback)
+    return this
+  }
+  /** Fires when the scene stops being visible (closed, replaced, or covered by a push). */
+  onClose(callback: () => void): this {
+    this.cl.push(callback)
+    return this
+  }
+  onBackPressed(callback: () => void): this {
+    this._backButtonCallback = callback
+    return this
+  }
+
+  /** @internal stable wire descriptor; hosts hand it back via router onChange (`_p` = this). */
+  _viewDesc(): object {
+    return this._vd ??= { type: "scene3d", sceneId: this._id, _p: this }
+  }
+
+  /** Make this the active scene — shows it as the current destination (replaces a screen /
+   *  another scene; only the active scene renders). */
+  open(options?: PresentOptions): void | Promise<void> {
+    _bumpNavEpoch()
+    if (_navSupported()) {
+      // The host activates the engine (openScene) as part of presenting the destination.
+      _creatorUI.openView!(this._viewDesc(), options?.transition ?? "none")
+    } else {
+      _creator.openScene(this._id)
+      for (const cb of this.ol) cb()
+    }
     Scene._active = this
     glState.activeScene = this
+    _setCurrent(this)
   }
   close(): void {
-    _creator.closeScene()
+    _bumpNavEpoch()
+    if (_navSupported()) {
+      _creatorUI.closeView!()
+    } else {
+      _creator.closeScene()
+      for (const cb of this.cl) cb()
+    }
     if (Scene._active === this) Scene._active = null
     if (glState.activeScene === this) glState.activeScene = null
+    if (Presentable.current === this) _setCurrent(null)
   }
 
   addEventListener(channel: "click", callback: (ev: ClickEvent<Node | null>) => void): void
@@ -188,11 +238,26 @@ export class ARScene<T extends ARMode = "default"> extends Scene {
     return attachControls(this, target, options)
   }
 
-  override async open(): Promise<void> {
-    await new Promise<void>((res, rej) => _creator.requestCamera(res, rej))
-    if (this.useWarmRender) { _creator.createGLView(); await this.warmRender() }
+  override async open(options?: PresentOptions): Promise<void> {
+    await this._prepare()
+    super.open(options)
+  }
+
+  /** @internal Presentable prepare hook: camera permission + warm render + AR session, all while
+   *  the previous destination (typically a loading screen) stays visible — the swap to this scene
+   *  happens only after it resolves. Warm render is headless on every platform (offscreen
+   *  swapchain), so no GL view is created here — the host mounts the scene view at present time.
+   *  Rejects on camera denial / AR launch failure, or if another navigation happened while
+   *  preparing (superseded) — in every rejection case the current destination stays visible. */
+  async _prepare(): Promise<void> {
+    const epoch = _navEpoch()
+    await _requestCameraPermission()
+    if (this.useWarmRender) await this.warmRender()
     await new Promise<void>((res, rej) => _creator.launchAR(this._id, res, rej))
-    super.open()
+    if (_navEpoch() !== epoch) {
+      _creator.stopAR()
+      throw new Error("ARScene.open() superseded: another destination was opened while preparing")
+    }
   }
 
   override close(): void {
@@ -212,9 +277,9 @@ export class ARScene<T extends ARMode = "default"> extends Scene {
  * `open()` rejects on hosts without a VR runtime ("VR is not supported on this device").
  */
 export class VRScene extends Scene {
-  override async open(): Promise<void> {
+  override async open(options?: PresentOptions): Promise<void> {
     await new Promise<void>((res, rej) => _creator.launchVR(this._id, res, rej))
-    super.open()
+    super.open(options)
   }
 
   override close(): void {