lecodes-cli 0.17.2 → 0.18.0

package/runtime/sdk/inject.ts

@@ -26,13 +26,13 @@ export { Canvas, Bitmap } from "./canvas/Canvas"
 
 // ---- platform runtime (injected globals; the host provides the lower-level _creator* bridges) ----
 export { toast, openURL, SvgSource } from "./runtime/misc"
-export { app, type AppState } from "./runtime/app"
+export { app, type AppState, type OrientationLock } from "./runtime/app"
 export { clipboard } from "./runtime/clipboard"
 export { date, type DateValue, type DateInput, type Unit, type Locale } from "./runtime/datetime"
 export { fetch, fetchLocal, FormData, File, type FetchResponse } from "./runtime/fetch"
 export { localStorage } from "./runtime/storage"
 export { device, type HapticStyle, type MotionOptions } from "./runtime/device"
-export { Input } from "./runtime/input"
+export { Input, InputChannel, type InputKeyEvent, type InputGamepadEvent, type InputEventName, type GamepadState, type GamepadAxisName } from "./runtime/input"
 export { WebSocket } from "./runtime/net"
 // App-backend transport: the compiler-generated stubs of `*.server.ts` modules call these; user code
 // only ever imports its server functions (docs/backend-plan.md §4).
@@ -122,9 +122,14 @@ export { OAuth, type OAuthCredential, type OAuthProviderName } from "./plugins/o
 export { Service } from "./plugins/service"
 
 // ---- scenes as data (.scene.ts files — see src/scene/defineScene.ts) ----
-export { defineScene, use, ref, make, SceneHandle } from "./scene/defineScene"
-export type { SceneDef, SceneNodeDef, MeshDef, LightDef, MaterialDef, CameraNodeDef, AspectEntry, MakeEntry, LoadedScene } from "./scene/defineScene"
+export { defineScene, use, ref, make, SceneHandle, applyEditorPose as __applyEditorPose } from "./scene/defineScene"
+export type { SceneDef, SceneNodeDef, MeshDef, LightDef, MaterialDef, CameraNodeDef, AspectEntry, MakeEntry, LoadedScene, SceneInstance } from "./scene/defineScene"
+export { CameraPlace } from "./gl/CameraPlace"
 export type { FieldMeta } from "./core/fields"
+// Editor-only line drawing from generator rebuild() / make() factories / tool hooks — drawn by the
+// scene editor's viewport overlay, a no-op everywhere else (see src/scene/gizmos.ts).
+export { Gizmos, GizmoBuffer as __GizmoBuffer, withGizmoScope as __withGizmoScope } from "./scene/gizmos"
+export type { GizmoStyle } from "./scene/gizmos"
 
 // ---- no-code scenario aspects (attachable in the scene editor — see src/gl/scenarios.ts) ----
 export { MoveTo, FollowPath, Spin, LookAt, PlayAnimation } from "./gl/scenarios"
@@ -142,11 +147,15 @@ export { Shape } from "./gl/Shape"
 export { Physics } from "./gl/Physics"
 export { Trigger } from "./gl/Trigger"
 export { CharacterController } from "./gl/CharacterController"
-export { ModelAnimation } from "./gl/ModelAnimation"
-export { AnimationClip } from "./gl/AnimationClip"
-export type { ClipDef, ClipTrackDef, ClipKey } from "./gl/AnimationClip"
-export { Animator } from "./gl/Animator"
-export type { AnimatorPlayOptions } from "./gl/Animator"
+export { Vehicle } from "./gl/Vehicle"
+export type { WheelConfig, WheelState, DriveLayout, SuspensionConfig, EngineConfig } from "./gl/Vehicle"
+export { AnimationClip } from "./gl/animation/AnimationClip"
+export type { ClipDef, ClipTrackDef, ClipKey } from "./gl/animation/AnimationClip"
+export { Animator } from "./gl/animation/Animator"
+export { Playback } from "./gl/animation/Playback"
+export { Loop } from "./gl/animation/Loop"
+export { Layer } from "./gl/animation/Layer"
+export type { PlayOptions, StopOptions, LayerOptions, LoopOptions, LoopDef, BlendPosition } from "./gl/animation/core"
 export { IK } from "./gl/IK"
 export type { IKTwoBone, IKLookAt } from "./gl/IK"
 export { Light } from "./gl/Light"

package/runtime/sdk/runtime/app.ts

@@ -6,6 +6,10 @@ import { appEventsOn, appEventsOff, keyboardEventsOn, keyboardEventsOff } from "
 
 export type AppState = "active" | "background"
 
+/** `"landscape"` — either landscape direction (sensor landscape), `"portrait"` — upright only,
+ *  `"auto"` — released: the device's own rotation rules apply. */
+export type OrientationLock = "auto" | "portrait" | "landscape"
+
 type AppEventMap = {
   /** The app left the foreground (home button, tab hidden, another app on top). Delivered before
    *  the host halts the frame loop — the last chance to persist state / pause work. */
@@ -40,6 +44,15 @@ export const app = {
   get keyboardHeight(): number {
     return _creatorUtils.keyboardHeight?.() ?? 0
   },
+  /** Lock the screen orientation — `"landscape"` for a horizontal game (the device rotates to
+   *  landscape right away and stays there whichever way it is held), `"portrait"` for upright
+   *  only, `"auto"` to release. Call it once at startup; the lock is per app run (it resets
+   *  when the app quits or restarts), so there is nothing to undo. The rotation arrives as an
+   *  ordinary resize — layouts reflow, a scene's viewport follows. Silent no-op on hosts
+   *  without a rotatable screen (desktop, headless, web). */
+  setOrientation(mode: OrientationLock): void {
+    _creatorUtils.setOrientation?.(mode)
+  },
   /** Re-run this app's bundle in a fresh world — the platform's `location.reload()`. Pass `url`
    *  to reboot with different launch arguments (the new run reads them via `app.launchUrl`),
    *  `null` to reboot with a cleared one, or omit it to replay the current one. No-op on hosts

package/runtime/sdk/runtime/input.ts

@@ -1,12 +1,175 @@
-// Keyboard/pointer input. Replaces worker's bare `inputKey(code)` global with a small `Input`
-// namespace so the surface reads better and has room to grow (pointer, gamepad) without new globals.
+// Keyboard / mouse / gamepad input behind one `Input` global (docs/input-plan.md).
+//
+// Two kinds of signal, two shapes of API:
+//   - BUTTONS — anything that goes down and up: keyboard keys, mouse buttons, gamepad buttons. One
+//     code vocabulary ('KeyW', 'MouseLeft', 'GamepadSouth'), one held-poll (`Input.key`) and one
+//     event pair (`Input.on('keydown' | 'keyup')`). A mouse button IS a key.
+//   - CONTINUOUS — mouse motion/wheel, sticks, triggers: polled every frame (`Input.mouse.delta`,
+//     `Input.gamepad(0).axis('leftX')`), never events.
+// Bindings ("jump = Space | GamepadSouth") are app code: compare `e.code`, OR a few `Input.key`s.
+// Hosts report physical state only (`_creatorUtils.inputKey/inputRead/registerInputEvent`).
+
+/** Continuous channel ids — the `_creatorUtils.inputRead` contract (bridges.d.ts). */
+export const InputChannel = {
+  MouseX: 0, MouseY: 1, MouseDX: 2, MouseDY: 3, WheelX: 4, WheelY: 5, PointerLocked: 6,
+  GamepadCount: 7,
+  GamepadBase: 16, GamepadStride: 16,
+  PadConnected: 0, PadLeftX: 1, PadLeftY: 2, PadRightX: 3, PadRightY: 4, PadLeftTrigger: 5, PadRightTrigger: 6,
+} as const
+
+export type InputEventName = "keydown" | "keyup" | "gamepadconnected" | "gamepaddisconnected"
+
+/** `keydown` / `keyup` payload. `code` is the same string `Input.key()` takes. */
+export interface InputKeyEvent {
+  readonly type: "keydown" | "keyup"
+  /** Button code: KeyboardEvent.code ('KeyW', 'Space'), 'MouseLeft|Right|Middle|Back|Forward', or
+   *  'GamepadSouth|East|West|North|L1|R1|L2|R2|Select|Start|L3|R3|Up|Down|Left|Right'. */
+  readonly code: string
+  /** Which device: 'keyboard' | 'mouse' | 'gamepad'. */
+  readonly source: "keyboard" | "mouse" | "gamepad"
+  /** Pad index (0..3) for gamepad buttons, undefined otherwise. */
+  readonly gamepad?: number
+  /** OS auto-repeat keydown (key still held) — ignore for one-shot actions. */
+  readonly repeat: boolean
+}
+
+export interface InputGamepadEvent {
+  readonly type: "gamepadconnected" | "gamepaddisconnected"
+  readonly gamepad: number
+}
+
+type Listener<E> = (e: E) => void
+type InputEventMap = {
+  keydown: InputKeyEvent
+  keyup: InputKeyEvent
+  gamepadconnected: InputGamepadEvent
+  gamepaddisconnected: InputGamepadEvent
+}
+
+const listeners: { [K in InputEventName]?: Listener<InputEventMap[K]>[] } = {}
+let hostListenerInstalled = false
+
+const sourceOf = (code: string): InputKeyEvent["source"] =>
+  code.startsWith("Mouse") ? "mouse" : code.startsWith("Gamepad") ? "gamepad" : "keyboard"
+
+const emit = <K extends InputEventName>(name: K, e: InputEventMap[K]) => {
+  const list = listeners[name]
+  if (!list || list.length === 0) return
+  for (const fn of [...list]) fn(e as any)
+}
+
+// One fan-out for the host channel and the test/host `_emit` seam.
+const deliver = (kind: number, code: string, gamepad: number, repeat: number) => {
+  if (kind === 0 || kind === 1) {
+    const src = sourceOf(code)
+    emit(kind === 0 ? "keydown" : "keyup", {
+      type: kind === 0 ? "keydown" : "keyup", code, source: src,
+      gamepad: src === "gamepad" && gamepad >= 0 ? gamepad : undefined, repeat: repeat !== 0,
+    })
+  } else if (kind === 2 || kind === 3) {
+    emit(kind === 2 ? "gamepadconnected" : "gamepaddisconnected",
+         { type: kind === 2 ? "gamepadconnected" : "gamepaddisconnected", gamepad })
+  }
+}
+
+// Lazily claim the host's single listener slot (never at module scope — chisel drops top-level
+// side effects, and a host without the channel simply never fires).
+const ensureHostListener = () => {
+  if (hostListenerInstalled) return
+  hostListenerInstalled = true
+  _creatorUtils.registerInputEvent?.(deliver)
+}
+
+const read = (channel: number): number => _creatorUtils.inputRead?.(channel) ?? 0
+
+/** Mouse state — polled. Position is the cursor inside the viewport in logical px; `delta` is the
+ *  motion during the previous frame (raw where the OS offers it) and keeps counting while locked —
+ *  that's FPS look. Hosts without a mouse report zeros. */
+export const mouse = {
+  get position(): { x: number, y: number } { return { x: read(InputChannel.MouseX), y: read(InputChannel.MouseY) } },
+  get delta(): { x: number, y: number } { return { x: read(InputChannel.MouseDX), y: read(InputChannel.MouseDY) } },
+  /** Wheel notches during the previous frame (+y = wheel toward you / scroll down). */
+  get wheel(): { x: number, y: number } { return { x: read(InputChannel.WheelX), y: read(InputChannel.WheelY) } },
+  /** Pointer lock: cursor hidden + confined, `delta` keeps flowing. Web grants it only from a user
+   *  gesture (call it in a 'keydown' handler for MouseLeft); hosts drop it on focus loss and
+   *  re-acquire on focus. Escape does NOT unlock by itself on native hosts — call `unlock()`. */
+  get locked(): boolean { return read(InputChannel.PointerLocked) !== 0 },
+  lock(): boolean { return _creatorUtils.inputSetPointerLock?.(true) ?? false },
+  unlock(): void { _creatorUtils.inputSetPointerLock?.(false) },
+}
+
+export type GamepadAxisName = "leftX" | "leftY" | "rightX" | "rightY" | "leftTrigger" | "rightTrigger"
+const PAD_AXIS: Record<GamepadAxisName, number> = {
+  leftX: InputChannel.PadLeftX, leftY: InputChannel.PadLeftY, rightX: InputChannel.PadRightX,
+  rightY: InputChannel.PadRightY, leftTrigger: InputChannel.PadLeftTrigger, rightTrigger: InputChannel.PadRightTrigger,
+}
+
+export interface GamepadState {
+  readonly index: number
+  readonly connected: boolean
+  /** Stick axes −1..1 (+Y = down, like the web Gamepad API), triggers 0..1. `deadzone` (default
+   *  0.15) zeroes small stick drift — pass 0 for the raw value. */
+  axis(name: GamepadAxisName, deadzone?: number): number
+  /** Held? Same as `Input.key(code, index)`. */
+  button(code: string): boolean
+}
+
+const padCache: GamepadState[] = []
+const gamepadAt = (index: number): GamepadState => {
+  let g = padCache[index]
+  if (!g) {
+    const base = InputChannel.GamepadBase + InputChannel.GamepadStride * index
+    g = padCache[index] = {
+      index,
+      get connected() { return read(base + InputChannel.PadConnected) !== 0 },
+      axis(name, deadzone = 0.15) {
+        const v = read(base + PAD_AXIS[name])
+        return deadzone > 0 && Math.abs(v) < deadzone ? 0 : v
+      },
+      button(code) { return _creatorUtils.inputKey(code, index) },
+    }
+  }
+  return g
+}
 
 export const Input = {
   /**
-   * Is a key currently held? `code` is a KeyboardEvent.code-style string, e.g. 'ArrowRight',
-   * 'KeyW', 'Space'. Poll this inside setLoop for frame-independent movement.
+   * Is a button held? `code` is the physical key (`KeyboardEvent.code`: 'ArrowRight', 'KeyW',
+   * 'Space'), a mouse button ('MouseLeft', 'MouseRight', 'MouseMiddle') or a gamepad button
+   * ('GamepadSouth' = A/Cross, 'GamepadR2' = right trigger as a button …). Poll inside setLoop for
+   * frame-independent movement. `gamepad` scopes a Gamepad* code to one pad; omitted = any pad.
    */
-  key(code: string): boolean {
-    return _creatorUtils.inputKey(code)
+  key(code: string, gamepad?: number): boolean {
+    return _creatorUtils.inputKey(code, gamepad)
+  },
+
+  /** Listen for a discrete input moment. `keydown`/`keyup` cover EVERY button — keyboard, mouse,
+   *  gamepad — filter on `e.code`. Use these for one-shot actions (jump, shoot, charge-release);
+   *  `Input.key` for continuous ones (walk). */
+  on<K extends InputEventName>(name: K, listener: Listener<InputEventMap[K]>): void {
+    ensureHostListener()
+    const list = (listeners[name] ??= []) as Listener<InputEventMap[K]>[]
+    if (!list.includes(listener)) list.push(listener)
+  },
+  off<K extends InputEventName>(name: K, listener: Listener<InputEventMap[K]>): void {
+    const list = listeners[name] as Listener<InputEventMap[K]>[] | undefined
+    if (!list) return
+    const i = list.indexOf(listener)
+    if (i >= 0) list.splice(i, 1)
   },
+
+  mouse,
+
+  /** Gamepad `index` (0..3). Always returns an object — check `.connected`. */
+  gamepad(index = 0): GamepadState { return gamepadAt(index) },
+  /** Indices of the currently connected gamepads. */
+  gamepads(): number[] {
+    const out: number[] = []
+    const n = read(InputChannel.GamepadCount)
+    for (let i = 0; i < 4 && out.length < n; i++) if (gamepadAt(i).connected) out.push(i)
+    return out
+  },
+
+  /** @internal — hosts/tests: deliver an event exactly as the host listener would. */
+  _emit(kind: number, code: string, gamepad: number, repeat: number): void { deliver(kind, code, gamepad, repeat) },
 }

package/runtime/sdk/scene/defineScene.ts

@@ -43,6 +43,7 @@ import type { ColorInput } from "../core/color"
 import type { Vec3Like } from "../math/vec"
 import { Scene, type SceneOptions } from "../gl/Scene"
 import { CAMERA_DEFAULTS } from "../gl/Camera"
+import { CameraPlace } from "../gl/CameraPlace"
 import { Node } from "../gl/Node"
 import { Mesh } from "../gl/Mesh"
 import { Model } from "../gl/Model"
@@ -50,6 +51,7 @@ import { Light, type SunOptions } from "../gl/Light"
 import { Material, type LitMaterialOptions, type MaterialColorOptions } from "../gl/Material"
 import type { CylinderOptions, PlaneOptions, SphereOptions } from "../gl/Geometry"
 import { edgesMesh } from "../gl/scenarios"
+import { GizmoBuffer, withGizmoScope, type GizmoBatch } from "./gizmos"
 
 // ---- the literal grammar (what the visual editor reads and writes) -----------
 
@@ -134,6 +136,10 @@ export type SceneNodeDef = {
   visible?: boolean
   /** Editor-only: viewport manipulation won't target this node (fields still edit). No runtime effect. */
   locked?: boolean
+  /** Editor-only, `model` nodes: the POSE the scene editor shows — a clip looped while editing
+   *  (`time` freezes it at that second instead), so attachments / sight lines / a first-person eye
+   *  are placed against the animated pose, not the rest pose. Never applied when the scene runs. */
+  editor?: { clip?: string, time?: number }
   castShadows?: boolean
   receiveShadows?: boolean
   // -- capabilities / hierarchy --
@@ -204,6 +210,21 @@ export type LoadedScene<D extends SceneDef> = {
 // enumerates rows via `SceneHandle._modelParts` and writes the paths as `overrides` keys; the
 // loader resolves them back through the same enumeration, so writer and resolver can't drift.
 
+/** One instance of a scene file built as a subtree (`handle.instantiate`). */
+export type SceneInstance<D extends SceneDef> = {
+  /** The wrapper node the file's nodes build under — position it, parent it, hide it. */
+  root: Node
+  nodes: SceneNodes<D>
+  /** Anchor the instance on one of its own nodes: `root`'s local transform is set so that
+   *  `inner` coincides with the frame `root` is parented to (its origin and axes). One-shot,
+   *  from the CURRENT pose of `inner` — a rig's attachment frame (the eye place of a
+   *  first-person arms scene, the grip of a held prop). */
+  alignTo(inner: Node): void
+  get: LoadedScene<D>["get"]
+  /** Remove the subtree from the scene and destroy it. */
+  dispose(): void
+}
+
 /** One INTERNAL node of a loaded GLB (editor introspection). */
 export type ModelPartRow = { path: string, name: string, depth: number, node: Node }
 
@@ -298,6 +319,26 @@ const createSource = (path: string, def: SceneNodeDef): Node | Promise<Node> =>
   return new Node()
 }
 
+/** Edit mode: play the preview pose on a model node (`editor: { clip, time }`) — idempotent, the
+ *  harness re-applies it on inspector edits. No clip = back to the rest pose. */
+export const applyEditorPose = (node: Node, pose: { clip?: string, time?: number } | undefined): void => {
+  const anim = (node as unknown as { anim?: Model["anim"] }).anim
+  if (!anim) return
+  const clip = pose?.clip
+  if (!clip || !anim.clip(clip)) {
+    anim.speed = 1
+    anim.stop()
+    return
+  }
+  anim.speed = 1
+  if (pose?.time !== undefined) {
+    anim.play(clip, { restart: true }).seek(pose.time)
+    anim.speed = 0
+  } else {
+    anim.playLoop(clip)
+  }
+}
+
 const applyNode = (node: Node, name: string, def: SceneNodeDef): void => {
   node.name = name
   // def-built marker: part enumeration must skip this node (it is not asset-internal — it has
@@ -309,6 +350,7 @@ const applyNode = (node: Node, name: string, def: SceneNodeDef): void => {
   if (def.visible !== undefined) node.visible = def.visible
   // editor-only flag (the harness's manipulation layer consults it); inert at runtime
   if (def.locked !== undefined) (node as { _sceneLocked?: boolean })._sceneLocked = def.locked
+  if (def.editor !== undefined && isEditMode()) applyEditorPose(node, def.editor)
   if (def.camera !== undefined) (node as { _sceneCamera?: boolean })._sceneCamera = true
   // waypoint/def order for aspects that read children (FollowPath) — the engine's live child
   // order is insertion-based and may not match the file
@@ -353,17 +395,26 @@ const addEditorMarker = (node: Node, def: SceneNodeDef, scene: Scene): void => {
   scene.add(marker)
 }
 
-/** Play mode: `scene.camera` follows the camera node's world transform every frame (LATE phase,
- *  after every other aspect has moved things — order 1000). Attached by `instantiate`, internal. */
-class CameraRig extends Aspect<"__cameraRig"> {
-  static readonly aspect = "__cameraRig"
-  /** @internal */ _scene!: Scene
-  constructor() { super(); this.order = 1000 }
-  update(): void {
-    const cam = this._scene.camera
-    cam.position = this.node.worldPosition
-    cam.quaternion = this.node.worldQuaternion
+/** The ACTIVE `CameraPlace` entry in THIS file's own defs (depth-first; prefab / instance internals
+ *  are another file's business): its host path + props, or null. With no `active: true` anywhere,
+ *  the first place in file order is it — a file with a single place needn't say so. */
+const findCameraPlace = (defs?: Record<string, SceneNodeDef>): { path: string, props: Record<string, unknown> } | null => {
+  let first: { path: string, props: Record<string, unknown> } | null = null
+  const walk = (d: Record<string, SceneNodeDef> | undefined, prefix: string): { path: string, props: Record<string, unknown> } | null => {
+    for (const [ name, nd ] of Object.entries(d ?? {})) {
+      const path = prefix === "" ? name : `${prefix}/${name}`
+      for (const entry of nd.aspects ?? []) {
+        if (entry.ctor !== CameraPlace) continue
+        const props = (entry.props ?? {}) as Record<string, unknown>
+        if (props.active === true) return { path, props }
+        first ??= { path, props }
+      }
+      const inner = walk(nd.children, path)
+      if (inner) return inner
+    }
+    return null
   }
+  return walk(defs, "") ?? first
 }
 
 /** The first camera-source def in file order (depth-first) — its path and block — or null. */
@@ -402,6 +453,9 @@ const isEditorCtor = (ctor: unknown): boolean => !!(ctor as { editor?: unknown }
  *  from parenting — `addEntityToScene` only recurses over children that exist at add time). */
 class GeneratedGroup extends Node {
   /** @internal */ _scene!: Scene
+  /** Bumped by every `clear()`. An ASYNC rebuild captures it before awaiting and drops its own
+   *  result when the value moved on (a newer rebuild cleared the container in the meantime). */
+  version = 0
   add(...children: Node[]): this {
     super.add(...children)
     this._scene.add(...children)
@@ -409,7 +463,9 @@ class GeneratedGroup extends Node {
   }
   /** Destroy all generated children (rebuild() calls this first — idempotent regeneration). */
   clear(): this {
+    this.version++
     for (const c of [ ...this.children ]) {
+      dropForeignRuns(c)
       this._scene.remove(c)
       c.destroy()
     }
@@ -417,6 +473,19 @@ class GeneratedGroup extends Node {
   }
 }
 
+// Edit mode: generator runs inside scene INSTANCES built by `instantiate()` (a weapon under the
+// arms' gun socket) are not the edited handle's runs — not inspector-addressable, not
+// dep-tracked — but their gizmos (the weapon's sight line) must still draw. They register here
+// keyed by the instance root; `dispose()` / a hosting `generated.clear()` drops them.
+const foreignRuns = new Map<Node, EditorRun[]>()
+const dropForeignRuns = (root: Node): void => {
+  for (const key of [ ...foreignRuns.keys() ]) {
+    let n: Node | null = key
+    while (n && n !== root) n = n.parent
+    if (n === root) foreignRuns.delete(key)
+  }
+}
+
 const makeGenerated = (node: Node, scene: Scene): GeneratedGroup => {
   const group = new GeneratedGroup()
   group.name = "__generated"
@@ -433,7 +502,9 @@ type EditorRun = {
   node: Node
   /** Index within the def's `aspects` array — the doc's aspect index addresses it. */
   index: number
-  inst: { rebuild?(): void }
+  inst: { rebuild?(): void | Promise<void> }
+  /** Async rebuild() supersession counter (see safeRebuild). */
+  generation: number
   /** Mutable props snapshot — `_editorSetProp` updates it and re-derives `deps`. Holds the
    *  DOC-LITERAL `$ref` strings (never resolved paths): the inspector's doc-sync compares these
    *  against the file's props, so rewriting them would re-fire on every render. */
@@ -441,11 +512,32 @@ type EditorRun = {
   /** ABSOLUTE paths the ref() props resolved to — a change to any of them (or anything inside
    *  their subtrees) re-runs rebuild(). Re-derived after every structural change. */
   deps: Set<string>
+  /** Editor lines drawn by the last rebuild() (`Gizmos.*` calls — see scene/gizmos.ts). */
+  gizmos: GizmoBuffer
 }
 
-const safeRebuild = (run: EditorRun): void => {
-  // a throwing generator must not take the editor session down with it
-  try { run.inst.rebuild?.() } catch (e) { console.error(`[scene] editor aspect rebuild failed on "${run.hostPath}":`, e) }
+/** Bumped on every editor-run rebuild — the host compares it to know when to re-push gizmos. */
+let gizmoVersion = 0
+
+const safeRebuild = (run: EditorRun): Promise<void> | void => {
+  // a throwing generator must not take the editor session down with it; the gizmo scope is the
+  // SYNCHRONOUS part of the call — whatever rebuild draws replaces the run's previous lines. An
+  // async rebuild() (one that instantiates a scene file) is awaited; lines it wants to draw after
+  // its awaits go in an optional `draw()`, run in a fresh scope once the promise settles.
+  gizmoVersion++
+  let result: unknown
+  try { result = withGizmoScope(run.gizmos, () => run.inst.rebuild?.()) }
+  catch (e) { console.error(`[scene] editor aspect rebuild failed on "${run.hostPath}":`, e); return }
+  if (!(result instanceof Promise)) return
+  const gen = ++run.generation
+  return result.then(() => {
+    if (gen !== run.generation) return   // superseded by a newer rebuild
+    gizmoVersion++   // generated content changed — the host re-pushes overlays
+    const draw = (run.inst as { draw?(): void }).draw
+    if (typeof draw !== "function") return
+    try { withGizmoScope(run.gizmos, () => draw.call(run.inst)) }
+    catch (e) { console.error(`[scene] editor aspect draw failed on "${run.hostPath}":`, e) }
+  }, (e) => console.error(`[scene] editor aspect rebuild failed on "${run.hostPath}":`, e))
 }
 
 /** Re-assign every ref-carrying prop from the CURRENT nodes map — a live patch replaces node
@@ -506,7 +598,7 @@ const attachMake = (
     const props = { ...(entry.args ?? {}) } as Record<string, unknown>
     const inst = createMakeInst(path, entry, generated)
     Object.assign(inst, resolveRefs(props, nodes, path))
-    const run: EditorRun = { hostPath: path, node, index: MAKE_INDEX, inst, props, deps: collectRefDeps(props, nodes, path) }
+    const run: EditorRun = { hostPath: path, node, index: MAKE_INDEX, inst, props, deps: collectRefDeps(props, nodes, path), gizmos: new GizmoBuffer(), generation: 0 }
     editorRuns.push(run)
     safeRebuild(run)
     return undefined
@@ -520,8 +612,9 @@ const attachMake = (
 const attachAspects = (
   node: Node, path: string, def: SceneNodeDef,
   nodes: Record<string, Node>, scene: Scene, editorRuns: EditorRun[],
-): void => {
+): Promise<void> | void => {
   if (isEditMode()) {
+    const waits: Promise<void>[] = []
     // Data-only: the inspector reads [ctor, props] from here; nothing attaches, so no onAttach side
     // effects (physics bodies, loops) run while editing. `ref()` markers stay unresolved data too.
     // EXCEPT editor-run classes (generators) — they get a real, tracked instance (above).
@@ -529,21 +622,28 @@ const attachAspects = (
     ;(def.aspects ?? []).forEach((entry, index) => {
       if (!isEditorCtor(entry.ctor)) return
       const props = { ...(entry.props ?? {}) } as Record<string, unknown>
-      const inst = new (entry.ctor as unknown as new () => { rebuild?(): void })()
+      const inst = new (entry.ctor as unknown as new () => { rebuild?(): void | Promise<void> })()
       ;(inst as { node: unknown }).node = node
       ;(inst as { generated: unknown }).generated = makeGenerated(node, scene)
+      ;(inst as { scene: unknown }).scene = scene
       Object.assign(inst, resolveRefs(props, nodes, path))
+      // reachable through `node.get(Ctor)` like an attached aspect (a nested rig's contract is read
+      // by the generator that instantiated it) — registered, never attached: no onAttach/update
+      ;(node as unknown as { _aspects: Map<Function, unknown> })._aspects.set(entry.ctor as Function, inst)
+      const accessor = (entry.ctor as { aspect?: string }).aspect
+      if (accessor) (node as unknown as Record<string, unknown>)[accessor] = inst
       // the HOST node is a dep too: a generator that draws relative to its node (path lines)
       // must re-run when the node itself is dragged, not only when its ref() targets move
-      const run: EditorRun = { hostPath: path, node, index, inst, props, deps: collectRefDeps(props, nodes, path).add(path) }
+      const run: EditorRun = { hostPath: path, node, index, inst, props, deps: collectRefDeps(props, nodes, path).add(path), gizmos: new GizmoBuffer(), generation: 0 }
       editorRuns.push(run)
-      safeRebuild(run)
+      const wait = safeRebuild(run)
+      if (wait) waits.push(wait)
     })
-    return
+    return waits.length > 0 ? Promise.all(waits).then(() => undefined) : undefined
   }
   for (const entry of def.aspects ?? []) {
     const props = resolveRefs(entry.props as Record<string, unknown> | undefined, nodes, path)
-    const withGenerated = isEditorCtor(entry.ctor) ? { ...props, generated: makeGenerated(node, scene) } : props
+    const withGenerated = isEditorCtor(entry.ctor) ? { ...props, generated: makeGenerated(node, scene), scene } : props
     ;(node as Node & { aspect(c: unknown, p?: unknown): unknown }).aspect(entry.ctor, withGenerated)
   }
 }
@@ -631,7 +731,8 @@ const buildNodes = async (
   await Promise.all(Object.entries(defs).map(([ name, nd ]) => build(name, nd, parent, "")))
   const makeWaits: Promise<void>[] = []
   for (const p of pending) {
-    attachAspects(p.node, p.path, p.def, nodes, scene, editorRuns)
+    const aspectWait = attachAspects(p.node, p.path, p.def, nodes, scene, editorRuns)
+    if (aspectWait) makeWaits.push(aspectWait)
     const wait = attachMake(p.node, p.path, p.def, nodes, scene, editorRuns)
     if (wait) makeWaits.push(wait)
   }
@@ -647,15 +748,23 @@ const instantiate = async (def: SceneDef, editorRuns: EditorRun[]): Promise<{ sc
   // (CameraRig), in edit mode it only seeds the editor's starting viewpoint. The PROJECTION applies
   // in both modes — it is a property of the scene, not of the viewpoint, so the editor shows the
   // lens the running app will use.
+  const place = findCameraPlace(def.nodes)
+  const placeNode = place ? nodes[place.path] : undefined
   const cam = findCamera(def.nodes)
   const camNode = cam ? nodes[cam.path] : undefined
-  if (cam && camNode) {
+  if (place && placeNode) {
+    // the active CameraPlace (an ASPECT on any node — the preferred form; one per file)
+    const proj = { fov: place.props.fov as number | undefined, near: place.props.near as number | undefined, far: place.props.far as number | undefined }
+    scene.camera.position = placeNode.worldPosition
+    scene.camera.quaternion = placeNode.worldQuaternion
+    applyCameraProjection(scene, proj)
+    if (!isEditMode()) scene.camera.follow(placeNode)
+  } else if (cam && camNode) {
+    // legacy: the `camera: {}` node source block (still honoured — prefer a CameraPlace aspect)
     scene.camera.position = camNode.worldPosition
     scene.camera.quaternion = camNode.worldQuaternion
     applyCameraProjection(scene, cam.def)
-    if (!isEditMode()) {
-      ;(camNode as Node & { aspect(c: unknown, p?: unknown): unknown }).aspect(CameraRig, { _scene: scene })
-    }
+    if (!isEditMode()) scene.camera.follow(camNode)
   } else if (def.camera) {
     if (def.camera.position) scene.camera.position = def.camera.position
     if (def.camera.target) scene.camera.lookAt(def.camera.target)
@@ -698,6 +807,43 @@ export class SceneHandle<D extends SceneDef = SceneDef> {
     return loaded
   }
 
+  /**
+   * Build this scene file as a reusable SUBTREE inside an existing scene — a weapon under a hand
+   * bone, a streetlamp per street corner — as many times as you like (unlike `load()`, which is
+   * the one-instance "scene as a level" path). The nodes build under a fresh wrapper node (`root`)
+   * parented to `parent` (or left unparented); `env` / `camera` are ignored like a prefab's. The
+   * file's transforms are local to the wrapper, so author it with the wrapper as the attachment
+   * point. `ref()`s resolve per instance; aspects attach per instance. `dispose()` removes the
+   * subtree from the scene and destroys it.
+   */
+  async instantiate(opts: { scene: Scene, parent?: Node | null, name?: string }): Promise<SceneInstance<D>> {
+    const { scene } = opts
+    const root = new Node()
+    root.name = opts.name ?? "__instance"
+    if (opts.parent) opts.parent.add(root)
+    scene.add(root)
+    const nodes: Record<string, Node> = {}
+    // instance internals are not inspector-addressable (like prefab internals), but in edit mode
+    // their generators' gizmos still draw (foreignRuns — a nested rig's sight line)
+    const runs: EditorRun[] = []
+    await buildNodes(this.def.nodes ?? {}, root, scene, nodes, runs, new Set([ this.def ]))
+    if (isEditMode() && runs.length > 0) { foreignRuns.set(root, runs); gizmoVersion++ }
+    const get = (path: string): Node | null => nodes[path] ?? null
+    const dispose = (): void => {
+      foreignRuns.delete(root)
+      root.visible = false   // the visibility cascade retires the subtree's pick colliders first
+      scene.remove(root)
+      root.destroy()
+      for (const key of Object.keys(nodes)) delete nodes[key]
+    }
+    const alignTo = (inner: Node): void => {
+      // inner's pose in root's frame is independent of root's own local transform:
+      // rel = root.world⁻¹ · inner.world; root.local = rel⁻¹ puts inner on root's parent frame
+      root.matrix = root.worldMatrix.invert().mul(inner.worldMatrix).invert()
+    }
+    return { root, nodes, get, dispose, alignTo } as unknown as SceneInstance<D>
+  }
+
   /**
    * @internal Editor (edit mode): apply ONE node's change to the already-loaded scene without
    * recompiling — the same "scenes as data" grammar, but as a patch: `def` rebuilds the node at
@@ -725,6 +871,7 @@ export class SceneHandle<D extends SceneDef = SceneDef> {
       // editor-run aspect instances hosted in the doomed subtree go with it (generated children
       // are subtree children, so the destroy below reclaims them too)
       this._editorRuns = this._editorRuns.filter((r) => !doomed.has(r.node))
+      gizmoVersion++
       scene.remove(root)
       root.destroy()   // native destroyEntity recurses over remaining children
     }
@@ -775,6 +922,15 @@ export class SceneHandle<D extends SceneDef = SceneDef> {
     return fresh
   }
 
+  /** @internal Editor: every run's gizmo lines (world-space LINES batches) + a version that
+   *  changes whenever any rebuild ran — the host re-pushes to the engine only on a change. */
+  _editorGizmos(): { version: number, batches: GizmoBatch[] } {
+    const batches: GizmoBatch[] = []
+    for (const run of this._editorRuns) for (const b of run.gizmos.batches) if (b.segments.length > 0) batches.push(b)
+    for (const runs of foreignRuns.values()) for (const run of runs) for (const b of run.gizmos.batches) if (b.segments.length > 0) batches.push(b)
+    return { version: gizmoVersion, batches }
+  }
+
   /** @internal Re-derive every editor run's deps from the CURRENT record. Deps are RESOLVED
    *  absolute paths, so any structural change can invalidate them: an add can satisfy a
    *  previously-null ref, a remove/rename can re-bind one to a different scope (shadowing). */