lecodes-cli 0.6.3 → 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

@@ -0,0 +1,120 @@
+// 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", "updateBeforePhysics", "order", "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/gl/Material.ts

@@ -36,6 +36,14 @@ const applyUniform = (id: number, key: string, value: UniformValue): void => {
 
 export type MaterialColorOptions = { color?: ColorInput, map?: Texture | Canvas | null }
 
+/** `Material.lit` options — PBR scalars on top of the color/map pair. */
+export type LitMaterialOptions = MaterialColorOptions & {
+  /** Perceptual roughness, 0 (mirror) … 1 (matte). Unset = the shader's default. */
+  roughness?: number
+  /** Metallic factor, 0 (dielectric) … 1 (metal). Unset = the shader's default. */
+  metallic?: number
+}
+
 export class Material {
   /** @internal native material-instance handle. */
   _id: number
@@ -84,12 +92,14 @@ export class Material {
   // --- factories ---
 
   /** PBR lit material. */
-  static lit(options: MaterialColorOptions = {}): Material {
+  static lit(options: LitMaterialOptions = {}): Material {
     // The fetchLocal literal must be inline so the compiler's preload header captures the shader name.
     const m = new Material({ _id: _creatorUtils.fetchLocal("lit.filamat") } as any)
     m._colorKey = "baseColor"
     if (options.color !== undefined) m.color = options.color
     if (options.map) m.map = options.map
+    if (options.roughness !== undefined) m.uniforms.roughness = options.roughness
+    if (options.metallic !== undefined) m.uniforms.metallic = options.metallic
     return m
   }
 

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

@@ -66,11 +66,16 @@ export class Scene {
     if (parent) {
       this.camera = parent.camera
       this._id = _creator.createOverlayScene(parent._id)
+      // No camera re-attach: the native createOverlayScene wires the parent's camera into the
+      // overlay view. Re-attaching would (a) point camera._sceneId — the source for getRay /
+      // getViewDirection / fov — at the overlay's view, whose viewport/projection aren't
+      // maintained like the render view's, and (b) create a second native camera component on
+      // the shared entity. (Found via the scene editor: gizmo pick rays came out distorted.)
     } else {
       this.camera = new Camera()
       this._id = _creator.createScene()
+      this.camera._attach(this._id)
     }
-    this.camera._attach(this._id)
 
     if (options.ibl !== false) _creator.setDefaultIbl(this._id, options.environmentIntensity ?? 20000)
     if (options.bloom) _creator.setBloomOptions(this._id, true, options.bloomIntensity ?? 0.2, 1)