lecodes-sdk 0.19.0

package/src/scene/editorPlugins.ts

@@ -0,0 +1,110 @@
+// Editor plugins: `registerEditorWindow` / `registerEditorTool` (docs/scene-editor-plan.md,
+// phase 11). Registrations live in `*.editor.ts` files — compiled and executed ONLY in
+// scene-editor bundles (phase 10), so none of this reaches shipped app.js (nothing references it
+// there, and method-granular DCE drops it).
+//
+// The scene-editor harness (packages/projects/src/scene-editor) reads the registry through the
+// injected `__editorPlugins` global — the harness, the scene, and the editor files compile into
+// ONE bundle, so they share this module instance. Windows and tools describe their UI through the
+// same immediate-mode `InspectorUI` protocol custom inspector cards use (one widget vocabulary,
+// three mount points), and mutate the scene ONLY through the `editor` doc API — every plugin write
+// lands in the scene document (undoable, diffable), never in live engine state.
+
+import type { InspectorUI } from "../core/InspectorUI"
+
+/** A geometry hit under the viewport pointer, handed to tools. Physics builds raycast the scene's
+ *  meshes (precise); otherwise (and on misses) the hit falls back to the ground plane (y = 0). */
+export type EditorRayHit = {
+  point: [number, number, number]
+  normal: [number, number, number]
+  /** Absolute path of the scene-file node the hit belongs to ("city/in1/pt1") — null for
+   *  ground-plane fallback hits. */
+  node: string | null
+}
+
+/**
+ * The editor scripting API handed to windows and tools. Nodes are addressed by ABSOLUTE PATH —
+ * '/'-joined names from the scene root; a root node's path is its bare name. Doc-op methods write
+ * the scene DOCUMENT through the editor's normal commit path (undo, file, live patching all
+ * included); they return false / no-op when the document can't take the edit (sibling-name
+ * collision, unknown path).
+ */
+export type EditorApi = {
+  /** The currently selected node path (or `path::part` key for asset internals), null when
+   *  nothing is selected. */
+  readonly selection: string | null
+  select(path: string | null): void
+  /** The scene document's nodes: absolute path, sibling-unique display name, source kind
+   *  (mesh / model / light / group / …). */
+  nodes(): { path: string, name: string, kind: string }[]
+  /** First unused "base", "base2", "base3", … name among the SIBLINGS under `parentPath`
+   *  (scene root when omitted). */
+  uniqueName(base: string, parentPath?: string): string
+  /** Add a ROOT node from plain def data (scene-file grammar; a string `model` value means an
+   *  asset path). `name` may not contain '/' or ':'. One undo step unless grouped by `transact`. */
+  addNode(name: string, def: Record<string, unknown>): boolean
+  /** Write one def prop (transforms apply live; anything else patches/re-runs the node). */
+  setProp(path: string, key: string, value: unknown): boolean
+  removeNode(path: string): void
+  /** Duplicate a node; returns the copy's path (null when it can't). */
+  duplicate(path: string): string | null
+  /** Raycast the scene under a viewport pixel (same hit rules as tool clicks). */
+  raycast(screenX: number, screenY: number): EditorRayHit | null
+  /** Group every doc edit inside `fn` into ONE undo step. */
+  transact(fn: () => void): void
+  /** Read one def prop of a node as document data (`asset()` refs come as `{ $asset: "./x" }`);
+   *  undefined when the node or key doesn't exist. */
+  getProp(path: string, key: string): unknown
+  /** Write a BINARY asset file for a node (a terrain's `.terrain`, a baked mask…). `ref` = the
+   *  node's existing def-relative `asset()` ref to overwrite, or null to create `./<name>` at the
+   *  project root (a free name is picked on collisions). Resolves to the ref to store in the node's
+   *  def (`{ $asset: ref }` via `setProp`), null when the host can't write files. Not a doc edit —
+   *  it is not undoable; keep the doc pointing at the file. */
+  writeAsset(path: string, ref: string | null, name: string, bytes: Uint8Array): Promise<string | null>
+}
+
+export type EditorWindowFn = (ui: InspectorUI, editor: EditorApi) => void
+
+export type EditorToolHooks = {
+  /** CSS cursor for the viewport while this tool is active (default "crosshair"). */
+  cursor?: string
+  /** A short glyph (one character / emoji) for the tool's toolbar button — tools without one all
+   *  share the generic wand icon, so any editor with two or more tools should set it. */
+  icon?: string
+  /** A viewport click while the tool is active — `hit` is the raycast result under the pointer.
+   *  Viewport clicks route to the tool while it is active. */
+  onViewportClick?(hit: EditorRayHit, editor: EditorApi): void
+  /** Drag tools (brushes): a primary-button drag in the viewport routes here instead of orbiting
+   *  the camera — start / every pointer move (with the hit under it, null while off-world) /
+   *  release. A tool with `onDragStart` gets NO `onViewportClick` for the same gesture. */
+  onDragStart?(hit: EditorRayHit, editor: EditorApi): void
+  onDrag?(hit: EditorRayHit | null, editor: EditorApi): void
+  onDragEnd?(editor: EditorApi): void
+  /** The pointer moved over the viewport with no button down (throttled to the frame) — draw a
+   *  brush cursor through `Gizmos`; null when nothing is under it. */
+  onHover?(hit: EditorRayHit | null, editor: EditorApi): void
+}
+
+/** @internal The registry the scene-editor harness reads (windows/tools in registration order). */
+export const __editorPlugins = {
+  windows: [] as { title: string, render: EditorWindowFn }[],
+  tools: [] as { name: string, hooks: EditorToolHooks }[],
+}
+
+/** Register an editor panel — a collapsible overlay docked over the viewport (the inspector rail
+ *  stays selection-scoped). A window that emits `ui.toolButton` for a tool becomes that tool's
+ *  settings panel: activating the tool expands and highlights it. `render` re-runs immediate-mode
+ *  on every interaction — same protocol as `static inspector` cards. */
+export const registerEditorWindow = (title: string, render: EditorWindowFn): void => {
+  const existing = __editorPlugins.windows.find((w) => w.title === title)
+  if (existing) existing.render = render
+  else __editorPlugins.windows.push({ title, render })
+}
+
+/** Register a viewport tool — a toolbar entry beside move/rotate/scale (activate it there or via
+ *  `ui.toolButton(label, name)`). While active, viewport clicks arrive as raycast hits. */
+export const registerEditorTool = (name: string, hooks: EditorToolHooks): void => {
+  const existing = __editorPlugins.tools.find((t) => t.name === name)
+  if (existing) existing.hooks = hooks
+  else __editorPlugins.tools.push({ name, hooks })
+}

package/src/scene/gizmos.ts

@@ -0,0 +1,148 @@
+// Editor gizmos: immediate-mode line drawing for code that runs while a scene is EDITED — a
+// generator aspect's `rebuild()`, a `make()` factory, an editor tool's hooks. Nothing here touches
+// the scene: calls accumulate WORLD-space line segments into the buffer of the run that is
+// currently executing (an ambient scope the scene loader opens around each synchronous call), and
+// the scene editor pushes those buffers to the lite engine's overlay layer, which draws them over
+// the picture — never outlined, never picked, never rendered by Filament, absent in play mode.
+//
+//   rebuild() {
+//     Gizmos.polyline(points, { color: "#5b8ef0", closed: true })
+//     for (const p of points) Gizmos.cross(p, 0.07)
+//   }
+//
+// Every run starts with an EMPTY buffer — what a call draws is the whole picture (like
+// `generated.clear()`, only implicit). Outside any scope (play mode, hand-attached aspects, a call
+// after an `await` inside rebuild) the calls are no-ops: rebuild is synchronous by contract.
+//
+// ANCHORED gizmos (`{ node }` in the style): points are in that node's LOCAL frame and the engine
+// follows the node live — through a gizmo drag, not only after it — with the node's scale
+// stripped (an empty scaled ×10 for its children keeps a normal-sized cross). An anchored picture
+// is the node's own: clicking it in the viewport selects the node, and it draws in the selection
+// accent while selected. World-space calls (path lines) are never pickable.
+
+import { Mat4, type Mat4Like } from "../math/mat4"
+import type { Vec3Like } from "../math/vec"
+
+/** The anchor of a gizmo call: any object with an engine entity id (a `Node`). */
+export type GizmoAnchor = { readonly id: number }
+
+export type GizmoStyle = {
+  /** CSS hex color (`#rgb` / `#rrggbb`); default a neutral light gray. */
+  color?: string
+  /** 0..1, default 1. */
+  alpha?: number
+  /** Anchor: points are in this node's LOCAL frame (scale ignored); the lines follow the node
+   *  live, are pickable (a click selects the node) and turn the selection accent when it is
+   *  selected. Omit for world-space lines (not pickable). */
+  node?: GizmoAnchor | null
+}
+
+/** One color batch of LINES (flat `[x,y,z, x,y,z]` per segment) — what a host hands the engine.
+ *  With `entityId` the segments are in that entity's local frame (see GizmoStyle.node). */
+export type GizmoBatch = { color: string, alpha: number, segments: number[], entityId?: number }
+
+const DEFAULT_COLOR = "#cfd4dd"
+
+/** The per-run collector (owned by the scene loader's EditorRun). Batches are keyed by style so a
+ *  hundred same-colored segments cost one draw. */
+export class GizmoBuffer {
+  batches: GizmoBatch[] = []
+  private _byStyle = new Map<string, GizmoBatch>()
+
+  clear(): void {
+    this.batches = []
+    this._byStyle.clear()
+  }
+
+  segments(style: GizmoStyle | undefined): number[] {
+    const color = style?.color ?? DEFAULT_COLOR
+    const alpha = Math.max(0, Math.min(1, style?.alpha ?? 1))
+    const entityId = style?.node?.id
+    const key = `${color}@${alpha}@${entityId ?? ""}`
+    let b = this._byStyle.get(key)
+    if (!b) {
+      b = entityId ? { color, alpha, segments: [], entityId } : { color, alpha, segments: [] }
+      this._byStyle.set(key, b)
+      this.batches.push(b)
+    }
+    return b.segments
+  }
+}
+
+let current: GizmoBuffer | null = null
+let warnedOutOfScope = false
+
+const xyz = (p: Vec3Like): [number, number, number] =>
+  Array.isArray(p) ? [ p[0] ?? 0, p[1] ?? 0, p[2] ?? 0 ] : [ (p as { x: number }).x, (p as { y: number }).y, (p as { z: number }).z ]
+
+const target = (style: GizmoStyle | undefined): number[] | null => {
+  if (current) return current.segments(style)
+  if (!warnedOutOfScope && (globalThis as { __lecodesSceneEdit?: boolean }).__lecodesSceneEdit) {
+    warnedOutOfScope = true
+    console.warn("[Gizmos] draw call outside an editor run — gizmos must be drawn synchronously inside rebuild() / a make() factory / a tool hook")
+  }
+  return null
+}
+
+/** @internal Run `fn` with `buffer` as the ambient gizmo target (cleared first). Nested scopes
+ *  restore the outer one. */
+export const withGizmoScope = <T>(buffer: GizmoBuffer, fn: () => T): T => {
+  const prev = current
+  buffer.clear()
+  current = buffer
+  try { return fn() } finally { current = prev }
+}
+
+/**
+ * Editor-only line drawing, available inside generator `rebuild()`, `make()` factories and editor
+ * tool hooks. Points are WORLD space. Drawn by the scene editor's viewport overlay (depth-test
+ * off — a path through a wall is still a path); invisible everywhere else.
+ */
+export const Gizmos = {
+  /** One segment from `a` to `b`. */
+  line(a: Vec3Like, b: Vec3Like, style?: GizmoStyle): void {
+    const out = target(style)
+    if (!out) return
+    out.push(...xyz(a), ...xyz(b))
+  },
+
+  /** Consecutive segments through `points`; `closed` joins the last point back to the first. */
+  polyline(points: readonly Vec3Like[], style?: GizmoStyle & { closed?: boolean }): void {
+    if (points.length < 2) return
+    const out = target(style)
+    if (!out) return
+    const n = points.length
+    const last = style?.closed ? n : n - 1
+    for (let i = 0; i < last; i++) out.push(...xyz(points[i]!), ...xyz(points[(i + 1) % n]!))
+  },
+
+  /** A wireframe camera frustum looking down −Z: the four edges from the origin to a rect
+   *  `length` metres ahead sized by `fov` (vertical, degrees) × `aspect` (default 16:9), plus an
+   *  "up" fin above the rect. Anchor it (`{ node }`) for a camera node's marker — the frustum
+   *  then follows the node's pose; `matrix` places an unanchored one in world space. */
+  frustum(fov: number, style?: GizmoStyle & { aspect?: number, length?: number, matrix?: Mat4Like }): void {
+    const out = target(style)
+    if (!out) return
+    const aspect = style?.aspect ?? 16 / 9, length = style?.length ?? 0.6
+    const m = style?.matrix ? new Mat4(style.matrix) : null
+    const h = Math.tan((fov * Math.PI) / 360) * length, w = h * aspect, z = -length
+    const P = (x: number, y: number, zz: number): [number, number, number] => {
+      if (!m) return [ x, y, zz ]
+      const v = m.transformPoint([ x, y, zz ])
+      return [ v.x, v.y, v.z ]
+    }
+    const o = P(0, 0, 0)
+    const c = [ P(-w, -h, z), P(w, -h, z), P(w, h, z), P(-w, h, z) ]
+    for (const q of c) out.push(...o, ...q)
+    for (let i = 0; i < 4; i++) out.push(...c[i]!, ...c[(i + 1) % 4]!)
+    out.push(...P(-w * 0.4, h, z), ...P(0, h * 1.6, z), ...P(0, h * 1.6, z), ...P(w * 0.4, h, z))
+  },
+
+  /** A three-axis cross centred on `p` (a point marker); `size` = half extent, default 0.1. */
+  cross(p: Vec3Like, size = 0.1, style?: GizmoStyle): void {
+    const out = target(style)
+    if (!out) return
+    const [ x, y, z ] = xyz(p)
+    out.push(x - size, y, z, x + size, y, z, x, y - size, z, x, y + size, z, x, y, z - size, x, y, z + size)
+  },
+}

package/src/scene/grammar.ts

@@ -0,0 +1,120 @@
+// The scene-file literal grammar markers, shared by `.scene.ts` (defineScene, 3D) and
+// `.scene2d.ts` (defineScene2d, 2D): `use(Ctor, props)` aspect entries, `ref('name')` node
+// references, `make(fn, args)` code-built sources — plus the ref-resolution helpers both loaders
+// run. One implementation so the two formats can't drift; the engine-specific node/def types stay
+// in their own modules (defineScene.ts / defineScene2d.ts), which re-export these for user code.
+
+import type { Aspect, AspectCtor } from "../core/Aspect"
+import type { Node } from "../gl/Node"
+
+/** One aspect to attach, created by `use(Ctor, props)`. */
+export type AspectEntry<A extends Aspect<any, any> = Aspect<any, any>> = {
+  /** @internal grammar marker. */
+  readonly __use: true
+  ctor: AspectCtor<A>
+  props?: Partial<A>
+}
+
+/** Reference an aspect in a scene file: `aspects: [use(Physics, { motion: 'static' })]`. Props are
+ *  typechecked against the aspect's fields, exactly like `node.aspect(Ctor, props)`. */
+export const use = <A extends Aspect<any, any>>(ctor: AspectCtor<A>, props?: Partial<A>): AspectEntry<A> =>
+  ({ __use: true, ctor, props })
+
+/** A `make(fn, args)` source entry — see {@link make}. `N` is the node family the factory returns
+ *  (3D `Node` by default; a `.scene2d.ts` file's factories return `Node2D`). */
+export type MakeEntry<A extends Record<string, unknown> = Record<string, unknown>, N = Node> = {
+  /** @internal grammar marker. */
+  readonly __make: true
+  fn: (args: A) => N | Promise<N>
+  args?: A
+}
+
+/**
+ * A code-created source in a scene file: `tower: { make: make(buildTower, { floors: 5 }), … }`.
+ * The factory runs after every scene node exists (so `ref()` args resolve, forward references
+ * included) and its returned subtree mounts under the def node — the def's transform stays
+ * editor-owned, so moving the node never re-calls the factory. Args must be literal data (same
+ * grammar as aspect props); in the editor they edit as fields, and an arg change re-CALLS the
+ * factory live — the code is already in the bundle, so no compile happens. Keep factories pure
+ * builders: same args → same subtree, no side effects outside the returned nodes.
+ */
+export const make = <A extends Record<string, unknown>, N>(
+  fn: (args: A) => N | Promise<N>, args?: A,
+): MakeEntry<A, N> => ({ __make: true, fn, args })
+
+/**
+ * Reference another scene node by PATH in an aspect's props:
+ * `use(Road, { from: ref('pointA'), to: ref('lane/pointB') })`. Resolves to the live node when
+ * aspects attach — after EVERY node of the scene exists, so declaration order doesn't matter.
+ * Resolution is scoped upward from the host node (like variable scoping): the host's own children
+ * first, then its siblings, then each ancestor's scope up to the scene root. The FIRST segment
+ * binds the scope; the remaining segments descend from there. Refs address def nodes only (no
+ * `::`/`name[i]` asset-internal segments); an unknown path resolves to `null` (type your aspect
+ * field `Node | null`). Scene files only — hand-written code passes nodes directly:
+ * `node.aspect(Road, { from: nodes.pointA })`.
+ */
+export const ref = <T = Node>(path: string): T => ({ $ref: path } as unknown as T)
+
+export const isNodeRef = (v: unknown): v is { $ref: string } =>
+  typeof v === "object" && v !== null && typeof (v as { $ref?: unknown }).$ref === "string"
+
+/** Resolve one ref string against a path-keyed nodes record, scoped upward from `hostPath` (own
+ *  children → parent's scope (siblings + the host itself) → each ancestor scope → root, `""`).
+ *  The ref's FIRST segment binds the scope — a match there is final even when the rest of the
+ *  path doesn't exist (lexical shadowing). Returns the target's ABSOLUTE path, or null.
+ *  `Object.hasOwn`, not indexing: a node named `constructor` must not resolve via the prototype. */
+export const resolveRefPath = (
+  nodes: Record<string, unknown>, hostPath: string, ref: string,
+): string | null => {
+  const i = ref.indexOf("/")
+  const first = i < 0 ? ref : ref.slice(0, i)
+  for (let scope = hostPath; ; ) {
+    const base = scope === "" ? "" : `${scope}/`
+    if (Object.hasOwn(nodes, base + first)) return Object.hasOwn(nodes, base + ref) ? base + ref : null
+    if (scope === "") return null
+    const cut = scope.lastIndexOf("/")
+    scope = cut < 0 ? "" : scope.slice(0, cut)
+  }
+}
+
+/** Swap `ref()` markers in aspect props for the live nodes (top level + one array level deep),
+ *  resolved scoped-upward from `hostPath` ("" = root scope only — the 2D flat-map case). */
+export const resolveRefs = <N>(
+  props: Record<string, unknown> | undefined, nodes: Record<string, N>, hostPath = "",
+): Record<string, unknown> | undefined => {
+  if (!props) return props
+  const lookup = (r: string): N | null => {
+    const p = resolveRefPath(nodes, hostPath, r)
+    return p === null ? null : nodes[p]
+  }
+  let out: Record<string, unknown> | undefined
+  for (const [ k, v ] of Object.entries(props)) {
+    if (isNodeRef(v)) {
+      ;(out ??= { ...props })[k] = lookup(v.$ref)
+    } else if (Array.isArray(v) && v.some(isNodeRef)) {
+      ;(out ??= { ...props })[k] = v.map((el) => (isNodeRef(el) ? lookup(el.$ref) : el))
+    }
+  }
+  return out ?? props
+}
+
+/** ABSOLUTE paths of the nodes a props record's ref() values resolve to (editor dep tracking).
+ *  An unresolved ref contributes no dep — the handle re-derives deps after structural changes. */
+export const collectRefDeps = (
+  props: Record<string, unknown>, nodes: Record<string, unknown>, hostPath: string,
+): Set<string> => {
+  const deps = new Set<string>()
+  const add = (r: string): void => {
+    const p = resolveRefPath(nodes, hostPath, r)
+    if (p !== null) deps.add(p)
+  }
+  for (const v of Object.values(props)) {
+    if (isNodeRef(v)) add(v.$ref)
+    else if (Array.isArray(v)) for (const el of v) if (isNodeRef(el)) add(el.$ref)
+  }
+  return deps
+}
+
+/** The edit-mode flag an editor host sets before running the bundle (shared by both formats). */
+export const EDIT_FLAG = "__lecodesSceneEdit"
+export const isEditMode = (): boolean => (globalThis as Record<string, unknown>)[EDIT_FLAG] === true

package/src/scene/level.ts

@@ -0,0 +1,296 @@
+// Level — procedural placement helpers for building large maps in code. Designed for `make()`
+// factories in scene files (scene-files.md): a factory calls Level.line / grid / ring / scatter /
+// place and returns the group, so a fence line or a scattered forest is one scene node with
+// editable args instead of hundreds of hand-written coordinate entries.
+//
+// Contracts:
+//  · All coordinates are LOCAL to the returned group — the make def node owns the world transform.
+//  · Deterministic: same options (incl. `seed`) → the same layout, so a map is reproducible and a
+//    re-run in the editor never shuffles what you saw.
+//  · `build` is a GLB url (loaded once, cloned per spot) or a function `(spot) => Node | null` for
+//    full control — primitives via Mesh.*, per-spot variation via `spot.rng`.
+//  · Helpers only place. Colliders come from `collider:` (string builds) or from whatever the
+//    `build` function attaches itself.
+
+import { Node } from "../gl/Node"
+import { Model } from "../gl/Model"
+import { Shape } from "../gl/Shape"
+import { Physics } from "../gl/Physics"
+import { cx, cy, cz, type Vec3Like } from "../math/vec"
+
+/** One placement handed to a `build` function (all coordinates local to the group). */
+export type LevelSpot = {
+  /** 0-based placement index. */
+  index: number
+  /** Local position the node will be placed at (before jitter was already applied). */
+  position: [number, number, number]
+  /** Yaw in degrees the node will face (already resolved from the `yaw` option). */
+  yaw: number
+  /** Deterministic per-call random stream (seeded) — use for per-spot variation. */
+  rng: () => number
+}
+
+/** What to place: a GLB url (loaded once, cloned per spot), or a builder function. A builder
+ *  returning `null` skips that spot (thin a line, punch a gap in a grid). */
+export type LevelBuild = string | ((spot: LevelSpot) => Node | null | Promise<Node | null>)
+
+/** Static collision for url builds: 'mesh' = exact triangles, 'convex' = convex hull,
+ *  'box' = auto box from the mesh bounds, 'none' (default) = no collider. */
+export type LevelCollider = "mesh" | "convex" | "box" | "none"
+
+type PlaceCommon = {
+  build: LevelBuild
+  /** Static Shape+Physics attached to url-built nodes (default 'none'). Function builds attach
+   *  their own aspects instead. */
+  collider?: LevelCollider
+  /** Facing: degrees, 'random', 'face' (forward +Z toward the helper's direction), or 'align'
+   *  (the model's X length-axis along the direction — what fence/wall panels want). Each helper
+   *  picks its natural default. */
+  yaw?: number | "random" | "face" | "align"
+  /** Random XZ offset per spot, meters: a radius, or [maxX, maxZ]. */
+  jitter?: number | [number, number]
+  /** Seed for the deterministic random stream (default 1). */
+  seed?: number
+  /** Child name prefix (default: the url's basename, else 'item'). */
+  name?: string
+}
+
+export type LevelLineOptions = PlaceCommon & {
+  from: Vec3Like
+  to: Vec3Like
+  /** Fixed number of placements (endpoints included when count > 1)… */
+  count?: number
+  /** …or a spacing in meters (placements from `from` toward `to`, last one ≤ `to`). */
+  step?: number
+}
+
+export type LevelGridOptions = PlaceCommon & {
+  /** Grid center (default [0,0,0]). */
+  center?: Vec3Like
+  cols: number
+  rows: number
+  /** Cell size in meters: one number or [alongX, alongZ]. */
+  spacing: number | [number, number]
+}
+
+export type LevelRingOptions = PlaceCommon & {
+  /** Ring center (default [0,0,0]). */
+  center?: Vec3Like
+  radius: number
+  count: number
+  /** Start angle in degrees (default 0 = +X). */
+  start?: number
+  /** Arc to cover in degrees (default 360 = full ring, end exclusive). */
+  arc?: number
+  /** 'face' orientation for rings: toward the center ('in', default) or away ('out'). */
+  facing?: "in" | "out"
+}
+
+export type LevelScatterOptions = PlaceCommon & {
+  /** Rectangle center (default [0,0,0]). */
+  center?: Vec3Like
+  /** Rectangle extent in meters: [sizeX, sizeZ] or one number for a square. */
+  size: number | [number, number]
+  count: number
+  /** Minimum distance between any two placements (rejection-sampled; the helper places as many
+   *  as fit within the attempt budget and logs when it falls short). */
+  minSpacing?: number
+  /** Keep-out circles `{ x, z, r }` (local), or a predicate — return true to REJECT a point. */
+  avoid?: { x: number, z: number, r: number }[] | ((x: number, z: number) => boolean)
+  /** Y for every placement (default 0 — scatter is planar; vary height in a build fn). */
+  y?: number
+}
+
+export type LevelPlaceOptions = PlaceCommon & {
+  /** Explicit spots: [x, y, z] or [x, y, z, yawDegrees]. */
+  at: (readonly number[])[]
+}
+
+/** mulberry32 — tiny deterministic PRNG, good enough for layout jitter. */
+const mulberry32 = (seed: number): (() => number) => {
+  let a = seed >>> 0
+  return () => {
+    a = (a + 0x6D2B79F5) >>> 0
+    let t = a
+    t = Math.imul(t ^ (t >>> 15), t | 1)
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61)
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+  }
+}
+
+const v3 = (v: Vec3Like | undefined, dflt: [number, number, number] = [0, 0, 0]): [number, number, number] =>
+  v === undefined ? dflt : [cx(v), cy(v), cz(v)]
+
+const baseName = (build: LevelBuild, name: string | undefined): string => {
+  if (name) return name
+  if (typeof build === "string") {
+    // asset() urls arrive percent-encoded (the whole local path is one token) — decode first so
+    // the basename regex sees real separators, then strip the extension.
+    let s = build
+    try { s = decodeURIComponent(build) } catch { /* keep the raw url */ }
+    const m = /([^/\\]+?)(\.[a-z0-9]+)?$/i.exec(s)
+    if (m) return m[1]!
+  }
+  return "item"
+}
+
+const attachCollider = (node: Node, collider: LevelCollider | undefined): void => {
+  if (!collider || collider === "none") return
+  const props = collider === "mesh" ? { mesh: true as const } : collider === "convex" ? { mesh: "convex" as const } : {}
+  node.aspect(Shape, props).aspect(Physics, { motion: "static" })
+}
+
+/** A resolved spot list → the placed group. Url builds load the GLB once and clone per spot. */
+const buildSpots = async (
+  spots: { position: [number, number, number], yaw: number }[],
+  opts: PlaceCommon,
+): Promise<Node> => {
+  const group = new Node()
+  const rng = mulberry32(opts.seed ?? 1)
+  const prefix = baseName(opts.build, opts.name)
+  let template: Model | null = null
+  for (let i = 0; i < spots.length; i++) {
+    const spot = spots[i]!
+    let node: Node | null
+    if (typeof opts.build === "string") {
+      if (template === null) template = await Model.load(opts.build)
+      node = i === spots.length - 1 ? template : template.clone()
+      attachCollider(node, opts.collider)
+    } else {
+      node = await opts.build({ index: i, position: spot.position, yaw: spot.yaw, rng })
+      if (node === null) continue
+    }
+    node.name = `${prefix}${i + 1}`
+    node.position = spot.position
+    if (spot.yaw !== 0) node.eulerAngles = [0, spot.yaw, 0]
+    group.add(node)
+  }
+  // an all-skipped url build never used the template — but the template IS the last spot, so it
+  // only leaks when a function build was used (function builds own their nodes; nothing to do).
+  return group
+}
+
+const resolveYaw = (opt: PlaceCommon["yaw"], face: number, rng: () => number, dflt: "face" | "align" = "face"): number => {
+  const mode = opt ?? dflt
+  if (mode === "face") return face
+  if (mode === "align") return face - 90
+  if (mode === "random") return Math.floor(rng() * 360)
+  return mode
+}
+
+const applyJitter = (p: [number, number, number], jitter: PlaceCommon["jitter"], rng: () => number): [number, number, number] => {
+  if (!jitter) return p
+  const [jx, jz] = typeof jitter === "number" ? [jitter, jitter] : jitter
+  return [p[0] + (rng() * 2 - 1) * jx, p[1], p[2] + (rng() * 2 - 1) * jz]
+}
+
+/** Placements along a segment — fences, walls, lamp rows, guard rails. Default yaw: 'align'
+ *  (the model's X length-axis follows the segment — a wall of panels); use `yaw: 'face'` to point
+ *  each node's forward (+Z) along the direction instead. */
+const line = async (opts: LevelLineOptions): Promise<Node> => {
+  const from = v3(opts.from), to = v3(opts.to)
+  const d = [to[0] - from[0], to[1] - from[1], to[2] - from[2]]
+  const len = Math.hypot(d[0]!, d[2]!)
+  const count = opts.count ?? (opts.step && opts.step > 0 ? Math.floor(len / opts.step) + 1 : 2)
+  const faceYaw = (Math.atan2(d[0]!, d[2]!) * 180) / Math.PI
+  const rng = mulberry32((opts.seed ?? 1) ^ 0x1eaf)
+  const spots: { position: [number, number, number], yaw: number }[] = []
+  for (let i = 0; i < count; i++) {
+    const t = opts.step && opts.step > 0 && len > 0 ? (i * opts.step) / len : count > 1 ? i / (count - 1) : 0
+    const p: [number, number, number] = [from[0] + d[0]! * t, from[1] + d[1]! * t, from[2] + d[2]! * t]
+    spots.push({ position: applyJitter(p, opts.jitter, rng), yaw: resolveYaw(opts.yaw, faceYaw, rng, "align") })
+  }
+  return buildSpots(spots, opts)
+}
+
+/** A cols × rows lattice centered on `center` — crate stacks, plantations, parking lots. */
+const grid = async (opts: LevelGridOptions): Promise<Node> => {
+  const center = v3(opts.center)
+  const [sx, sz] = typeof opts.spacing === "number" ? [opts.spacing, opts.spacing] : opts.spacing
+  const rng = mulberry32((opts.seed ?? 1) ^ 0x941d)
+  const spots: { position: [number, number, number], yaw: number }[] = []
+  for (let r = 0; r < opts.rows; r++) {
+    for (let c = 0; c < opts.cols; c++) {
+      const p: [number, number, number] = [
+        center[0] + (c - (opts.cols - 1) / 2) * sx,
+        center[1],
+        center[2] + (r - (opts.rows - 1) / 2) * sz,
+      ]
+      spots.push({ position: applyJitter(p, opts.jitter, rng), yaw: resolveYaw(opts.yaw, 0, rng) })
+    }
+  }
+  return buildSpots(spots, opts)
+}
+
+/** Placements on a circle (or arc) — arena pillars, camp fires, stone circles. Default facing:
+ *  toward the center (`facing: 'out'` flips it). */
+const ring = async (opts: LevelRingOptions): Promise<Node> => {
+  const center = v3(opts.center)
+  const start = ((opts.start ?? 0) * Math.PI) / 180
+  const arc = ((opts.arc ?? 360) * Math.PI) / 180
+  const full = Math.abs((opts.arc ?? 360) - 360) < 1e-6
+  const rng = mulberry32((opts.seed ?? 1) ^ 0x71e6)
+  const spots: { position: [number, number, number], yaw: number }[] = []
+  for (let i = 0; i < opts.count; i++) {
+    // full ring: end exclusive (count even slices); arc: endpoints included
+    const t = opts.count > 1 ? i / (full ? opts.count : opts.count - 1) : 0
+    const a = start + arc * t
+    const x = center[0] + Math.cos(a) * opts.radius
+    const z = center[2] + Math.sin(a) * opts.radius
+    const inward = (Math.atan2(center[0] - x, center[2] - z) * 180) / Math.PI
+    const face = opts.facing === "out" ? inward + 180 : inward
+    spots.push({ position: applyJitter([x, center[1], z], opts.jitter, rng), yaw: resolveYaw(opts.yaw, face, rng) })
+  }
+  return buildSpots(spots, opts)
+}
+
+/** Seeded random placements in a rectangle — forests, rubble fields, prop clutter. Default yaw:
+ *  random. `minSpacing` + `avoid` keep spawns, roads and each other clear. */
+const scatter = async (opts: LevelScatterOptions): Promise<Node> => {
+  const center = v3(opts.center)
+  const [sizeX, sizeZ] = typeof opts.size === "number" ? [opts.size, opts.size] : opts.size
+  const rng = mulberry32((opts.seed ?? 1) ^ 0x5ca7)
+  const rejected = (x: number, z: number): boolean => {
+    if (!opts.avoid) return false
+    if (typeof opts.avoid === "function") return opts.avoid(x, z)
+    return opts.avoid.some((c) => (x - c.x) * (x - c.x) + (z - c.z) * (z - c.z) < c.r * c.r)
+  }
+  const placed: [number, number][] = []
+  const spots: { position: [number, number, number], yaw: number }[] = []
+  const minSq = (opts.minSpacing ?? 0) * (opts.minSpacing ?? 0)
+  let attempts = 0
+  const maxAttempts = opts.count * 30
+  while (spots.length < opts.count && attempts < maxAttempts) {
+    attempts++
+    const x = center[0] + (rng() - 0.5) * sizeX
+    const z = center[2] + (rng() - 0.5) * sizeZ
+    if (rejected(x, z)) continue
+    if (minSq > 0 && placed.some(([px, pz]) => (x - px) * (x - px) + (z - pz) * (z - pz) < minSq)) continue
+    placed.push([x, z])
+    spots.push({ position: [x, opts.y ?? center[1], z], yaw: resolveYaw(opts.yaw ?? "random", 0, rng) })
+  }
+  if (spots.length < opts.count) {
+    console.warn(`[Level.scatter] placed ${spots.length}/${opts.count} — the area is too tight for minSpacing/avoid`)
+  }
+  return buildSpots(spots, opts)
+}
+
+/** Explicit spot list — `at: [[x, y, z], [x, y, z, yaw], …]` when the layout is hand-designed but
+ *  the per-node boilerplate (load, clone, collider, naming) shouldn't be. */
+const place = async (opts: LevelPlaceOptions): Promise<Node> => {
+  const rng = mulberry32((opts.seed ?? 1) ^ 0x91ac)
+  const spots = opts.at.map((a) => ({
+    position: [a[0] ?? 0, a[1] ?? 0, a[2] ?? 0] as [number, number, number],
+    yaw: a.length > 3 ? a[3]! : resolveYaw(opts.yaw, 0, rng),
+  }))
+  return buildSpots(spots, opts)
+}
+
+/** Procedural level building — see the module header. All helpers return a Promise<Node> group to
+ *  return from a `make()` factory (or add to a scene from plain code). */
+export const Level = {
+  line, grid, ring, scatter, place,
+  /** The seeded PRNG the helpers use (mulberry32) — for custom generators that must stay
+   *  deterministic alongside them. */
+  rng: mulberry32,
+}