lecodes-cli 0.6.2 → 0.6.4

package/runtime/sdk/runtime/datetime.ts

@@ -0,0 +1,331 @@
+// Locale-aware dates, dayjs-style: `date(value).format(...)`. Pure JS (no `Intl` — QuickJS hosts
+// don't ship it reliably), so output is byte-identical on every platform. Two locales: English and
+// Russian.
+//
+// ── Designed for chisel fusion ──────────────────────────────────────────────────────────────────
+// A date is a *single-scalar* value (epoch milliseconds), which is the 1-component analog of a Vec3
+// chain. The wrapper is written so a future chisel date-fuser can lower `date(root).<chain>()` to
+// scalar ms arithmetic and drop the wrapper allocation, the same way Vec3 chains fuse:
+//   • IMMUTABLE — every method returns a NEW `DateValue`, never mutates `t` (aliasing safety).
+//   • ONE canonical scalar — `t` (epoch ms), also reachable via `valueOf()`; that's the "component".
+//   • Terminals DELEGATE to the module-private free functions `formatImpl` / `timeAgoImpl`, taking
+//     `(ms, …)`. So `date(x).format(p)` can fuse to `formatImpl(toMs(x), p)` with no wrapper.
+//   • Linear-unit arithmetic (ms…week) is closed-form scalar math → fusable; calendar units
+//     (month/year) and local-tz `startOf`/`endOf` use `Date` and are left to the real method.
+// Even before that pass lands, each method is a class method, so chisel's method-granular DCE drops
+// whichever ones a project doesn't use.
+
+export type Locale = "en" | "ru"
+export type DateInput = Date | number | string | DateValue
+export type Unit = "ms" | "second" | "minute" | "hour" | "day" | "week" | "month" | "year"
+
+// ---- locale data -------------------------------------------------------------------------------
+// Russian needs the month in two grammatical cases: genitive ("5 сентября") when a day number is
+// present, nominative ("Сентябрь 2024") when it stands alone. `format` picks by whether the pattern
+// contains a day (`D`) token — the same rule day.js's ru locale uses.
+
+type LocaleData = {
+  months: readonly string[]
+  monthsGenitive: readonly string[]
+  monthsShort: readonly string[]
+  weekdays: readonly string[] // Sunday..Saturday (JS getDay() order)
+  weekdaysShort: readonly string[]
+  am: string
+  pm: string
+}
+
+const EN: LocaleData = {
+  months: ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"],
+  monthsGenitive: ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"],
+  monthsShort: ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"],
+  weekdays: ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"],
+  weekdaysShort: ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"],
+  am: "AM",
+  pm: "PM",
+}
+
+const RU: LocaleData = {
+  months: ["Январь", "Февраль", "Март", "Апрель", "Май", "Июнь", "Июль", "Август", "Сентябрь", "Октябрь", "Ноябрь", "Декабрь"],
+  monthsGenitive: ["января", "февраля", "марта", "апреля", "мая", "июня", "июля", "августа", "сентября", "октября", "ноября", "декабря"],
+  monthsShort: ["янв", "фев", "мар", "апр", "мая", "июн", "июл", "авг", "сен", "окт", "ноя", "дек"],
+  weekdays: ["Воскресенье", "Понедельник", "Вторник", "Среда", "Четверг", "Пятница", "Суббота"],
+  weekdaysShort: ["вс", "пн", "вт", "ср", "чт", "пт", "сб"],
+  am: "AM",
+  pm: "PM",
+}
+
+const DATA: Record<Locale, LocaleData> = { en: EN, ru: RU }
+
+const resolveLocale = (locale?: Locale): Locale => {
+  if (locale) return locale === "ru" ? "ru" : "en"
+  const lang = typeof _creatorUtils !== "undefined" ? _creatorUtils.language : ""
+  return lang && lang.toLowerCase().indexOf("ru") === 0 ? "ru" : "en"
+}
+
+// Milliseconds per linear unit. Absent keys (month/year) mark the non-fusable calendar units.
+const MS: Partial<Record<Unit, number>> = {
+  ms: 1,
+  second: 1000,
+  minute: 60_000,
+  hour: 3_600_000,
+  day: 86_400_000,
+  week: 604_800_000,
+}
+
+const toMs = (value: DateInput): number => {
+  if (value instanceof DateValue) return value.t
+  if (value instanceof Date) return value.getTime()
+  if (typeof value === "number") return value
+  return new Date(value).getTime()
+}
+
+// ---- formatting (the fusion escape target: takes a scalar ms, holds the heavy tables) -----------
+
+const pad2 = (n: number): string => (n < 10 ? "0" + n : "" + n)
+
+// Longest tokens first so `MMMM` matches before `MM`, `YYYY` before `YY`, etc.
+const TOKEN = /YYYY|YY|MMMM|MMM|MM|M|DD|D|dddd|ddd|HH|H|hh|h|mm|m|ss|s|A|a/g
+
+const formatImpl = (ms: number, pattern: string, locale?: Locale): string => {
+  const d = new Date(ms)
+  const L = DATA[resolveLocale(locale)]
+  const hasDay = /D/.test(pattern) // genitive month only when a day number accompanies it
+  const months = hasDay ? L.monthsGenitive : L.months
+
+  const year = d.getFullYear()
+  const month = d.getMonth()
+  const day = d.getDate()
+  const weekday = d.getDay()
+  const hours = d.getHours()
+  const hour12 = hours % 12 || 12
+  const minutes = d.getMinutes()
+  const seconds = d.getSeconds()
+
+  return pattern.replace(TOKEN, (t) => {
+    switch (t) {
+      case "YYYY": return "" + year
+      case "YY": return pad2(year % 100)
+      case "MMMM": return months[month]
+      case "MMM": return L.monthsShort[month]
+      case "MM": return pad2(month + 1)
+      case "M": return "" + (month + 1)
+      case "DD": return pad2(day)
+      case "D": return "" + day
+      case "dddd": return L.weekdays[weekday]
+      case "ddd": return L.weekdaysShort[weekday]
+      case "HH": return pad2(hours)
+      case "H": return "" + hours
+      case "hh": return pad2(hour12)
+      case "h": return "" + hour12
+      case "mm": return pad2(minutes)
+      case "m": return "" + minutes
+      case "ss": return pad2(seconds)
+      case "s": return "" + seconds
+      case "A": return hours < 12 ? L.am : L.pm
+      case "a": return (hours < 12 ? L.am : L.pm).toLowerCase()
+      default: return t
+    }
+  })
+}
+
+// Russian plural picks one of three forms by the number: 1 минута / 2 минуты / 5 минут.
+const ruPlural = (n: number, one: string, few: string, many: string): string => {
+  const mod10 = n % 10
+  const mod100 = n % 100
+  if (mod10 === 1 && mod100 !== 11) return one
+  if (mod10 >= 2 && mod10 <= 4 && (mod100 < 10 || mod100 >= 20)) return few
+  return many
+}
+
+type RelUnit = { limit: number; secs: number; en: [string, string]; ru: [string, string, string] }
+
+// Ordered thresholds. `limit` is the upper bound (in seconds) this unit covers; `secs` is the unit's
+// length used to compute the count.
+const REL_UNITS: readonly RelUnit[] = [
+  { limit: 60, secs: 1, en: ["second", "seconds"], ru: ["секунду", "секунды", "секунд"] },
+  { limit: 3600, secs: 60, en: ["minute", "minutes"], ru: ["минуту", "минуты", "минут"] },
+  { limit: 86400, secs: 3600, en: ["hour", "hours"], ru: ["час", "часа", "часов"] },
+  { limit: 2592000, secs: 86400, en: ["day", "days"], ru: ["день", "дня", "дней"] },
+  { limit: 31536000, secs: 2592000, en: ["month", "months"], ru: ["месяц", "месяца", "месяцев"] },
+  { limit: Infinity, secs: 31536000, en: ["year", "years"], ru: ["год", "года", "лет"] },
+]
+
+const timeAgoImpl = (ms: number, locale: Locale | undefined, nowMs: number): string => {
+  const loc = resolveLocale(locale)
+  const diffSecs = (nowMs - ms) / 1000
+  const future = diffSecs < 0
+  const abs = Math.abs(diffSecs)
+
+  if (abs < 45) return loc === "ru" ? "только что" : "just now"
+
+  let count = 1
+  let unit = REL_UNITS[REL_UNITS.length - 1]
+  for (const u of REL_UNITS) {
+    if (abs < u.limit) { unit = u; count = Math.max(1, Math.round(abs / u.secs)); break }
+  }
+
+  if (loc === "ru") {
+    const word = ruPlural(count, unit.ru[0], unit.ru[1], unit.ru[2])
+    return future ? `через ${count} ${word}` : `${count} ${word} назад`
+  }
+  const word = count === 1 ? unit.en[0] : unit.en[1]
+  return future ? `in ${count} ${word}` : `${count} ${word} ago`
+}
+
+// ---- the immutable wrapper ---------------------------------------------------------------------
+
+/**
+ * An immutable moment in time — the value returned by [`date()`]. Wraps a single epoch-millisecond
+ * scalar (`t`); every method returns a new `DateValue` or a plain scalar, never mutating. Construct
+ * it with `date(...)`, not `new`.
+ */
+export class DateValue {
+  /** Epoch milliseconds — the one canonical scalar. Prefer `valueOf()`; this is public so `date(a)`
+   *  can read it back cheaply and so tooling can treat it as the value's single component. */
+  readonly t: number
+
+  constructor(ms: number) {
+    this.t = ms
+  }
+
+  // -- materialize (delegate to the free functions; the fuser can inline these to `*Impl(t, …)`) --
+
+  /**
+   * Format against a `day.js`-style token pattern (default `"D MMMM YYYY"`). Locale defaults to the
+   * current device language.
+   *
+   * Tokens: `YYYY`/`YY` year · `MMMM`/`MMM`/`MM`/`M` month · `DD`/`D` day · `dddd`/`ddd` weekday ·
+   * `HH`/`H` 24-hour · `hh`/`h` 12-hour · `mm`/`m` minute · `ss`/`s` second · `A`/`a` AM/PM.
+   *
+   * ```ts
+   * date().format()                     // "10 July 2026"  /  "10 июля 2026"
+   * date(ts).format("DD.MM.YYYY HH:mm") // "10.07.2026 14:05"
+   * date(ts).format("MMMM YYYY", "ru")  // "Июль 2026"  (nominative — no day token)
+   * ```
+   */
+  format(pattern = "D MMMM YYYY", locale?: Locale): string {
+    return formatImpl(this.t, pattern, locale)
+  }
+
+  /**
+   * Human relative time vs `now` (default: the current time) — "5 minutes ago", "in 2 days",
+   * "5 минут назад", "через 2 дня". Reads as "just now" under ~45 seconds; handles Russian number
+   * agreement (`1 минуту` / `2 минуты` / `5 минут`). Locale defaults to the device language.
+   */
+  timeAgo(locale?: Locale, now: DateInput = Date.now()): string {
+    return timeAgoImpl(this.t, locale, toMs(now))
+  }
+
+  // -- arithmetic (pure, chainable; linear units are closed-form scalar math → fusable) -----------
+
+  /** Add `n` of a unit, returning a new value. Linear units (`ms`…`week`) are scalar ms math;
+   *  `month`/`year` are calendar-aware (clamp on short months, like day.js). */
+  add(n: number, unit: Unit): DateValue {
+    const ms = MS[unit]
+    if (ms !== undefined) return new DateValue(this.t + n * ms)
+    // Calendar units: shift month/year but clamp the day so Jan 31 + 1 month → Feb 28 (not Mar 3).
+    const d = new Date(this.t)
+    const day = d.getDate()
+    d.setDate(1)
+    if (unit === "year") d.setFullYear(d.getFullYear() + n)
+    else d.setMonth(d.getMonth() + n) // "month"
+    const daysInMonth = new Date(d.getFullYear(), d.getMonth() + 1, 0).getDate()
+    d.setDate(Math.min(day, daysInMonth))
+    return new DateValue(d.getTime())
+  }
+
+  /** Subtract `n` of a unit. Equivalent to `add(-n, unit)`. */
+  subtract(n: number, unit: Unit): DateValue {
+    return this.add(-n, unit)
+  }
+
+  /** Snap down to the start of a unit (local time): start of day/hour/month/year, etc. */
+  startOf(unit: Unit): DateValue {
+    const d = new Date(this.t)
+    switch (unit) {
+      case "year": d.setMonth(0)
+      // falls through
+      case "month": d.setDate(1)
+      // falls through
+      case "day": d.setHours(0, 0, 0, 0); break
+      case "hour": d.setMinutes(0, 0, 0); break
+      case "minute": d.setSeconds(0, 0); break
+      case "second": d.setMilliseconds(0); break
+      case "week": {
+        d.setHours(0, 0, 0, 0)
+        d.setDate(d.getDate() - d.getDay()) // week starts Sunday
+        break
+      }
+    }
+    return new DateValue(d.getTime())
+  }
+
+  /** Snap up to the end of a unit (local time): the last millisecond of the day/hour/month/… */
+  endOf(unit: Unit): DateValue {
+    return this.startOf(unit).add(1, unit).add(-1, "ms")
+  }
+
+  // -- scalar terminals (bare number / boolean → allocate nothing when fused) ---------------------
+
+  /** Epoch milliseconds. Enables `+date(x)`, `date(a) < date(b)`, `date(a) - date(b)` via coercion. */
+  valueOf(): number {
+    return this.t
+  }
+
+  /** Whole seconds since the epoch (Unix time). */
+  unix(): number {
+    return Math.floor(this.t / 1000)
+  }
+
+  /** Signed difference to `other`, in whole `unit`s (default `ms`), truncated toward zero. */
+  diff(other: DateInput, unit: Unit = "ms"): number {
+    const raw = this.t - toMs(other)
+    const per = MS[unit]
+    if (per !== undefined) return Math.trunc(raw / per)
+    // month/year: count calendar steps.
+    const a = new Date(this.t)
+    const b = new Date(toMs(other))
+    let months = (a.getFullYear() - b.getFullYear()) * 12 + (a.getMonth() - b.getMonth())
+    if (a.getDate() < b.getDate()) months -= Math.sign(months) || 0
+    return unit === "year" ? Math.trunc(months / 12) : months
+  }
+
+  isBefore(other: DateInput): boolean { return this.t < toMs(other) }
+  isAfter(other: DateInput): boolean { return this.t > toMs(other) }
+  isSame(other: DateInput): boolean { return this.t === toMs(other) }
+
+  // -- field accessors (scalar terminals) ---------------------------------------------------------
+
+  year(): number { return new Date(this.t).getFullYear() }
+  /** 0-based month (0 = January), matching `Date.getMonth`. */
+  month(): number { return new Date(this.t).getMonth() }
+  /** Day of the month, 1–31. */
+  day(): number { return new Date(this.t).getDate() }
+  /** Day of the week, 0 (Sunday)–6 (Saturday), matching `Date.getDay`. */
+  weekday(): number { return new Date(this.t).getDay() }
+  hour(): number { return new Date(this.t).getHours() }
+  minute(): number { return new Date(this.t).getMinutes() }
+  second(): number { return new Date(this.t).getSeconds() }
+
+  /** A native `Date` snapshot of this value. */
+  toDate(): Date {
+    return new Date(this.t)
+  }
+}
+
+/**
+ * Create a `DateValue` — a locale-aware, immutable moment, dayjs-style. Accepts a `Date`, a
+ * millisecond timestamp (`Date.now()`), a parseable string, or another `DateValue`; with no argument
+ * it's the current time. Chain arithmetic and finish with `format` / `timeAgo`, both of which
+ * understand **English** and **Russian** and default to the current device language
+ * ([`device.language`](../runtime/device.ts)).
+ *
+ * ```ts
+ * date().format("dddd, D MMMM")            // "Friday, 10 July"  /  "пятница, 10 июля"
+ * date(ts).timeAgo()                       // "5 minutes ago"    /  "5 минут назад"
+ * date().add(3, "day").startOf("day").format("D MMMM")
+ * date(a).diff(b, "hour")                  // signed whole hours
+ * date(a).isBefore(b)                      // boolean
+ * ```
+ */
+export const date = (value: DateInput = Date.now()): DateValue => new DateValue(toMs(value))

package/runtime/sdk/scene/defineScene.ts

@@ -0,0 +1,269 @@
+// Scenes as data: the runtime behind `.scene.ts` files (docs/scene-editor-plan.md in the repo root).
+//
+// A scene file default-exports one `defineScene({...})` call whose argument is a plain literal —
+// nodes keyed by name, each with one source block (mesh / model / light, or none = group), a
+// transform, an optional material, `aspects: [use(Ctor, props), …]` and `children`. The visual
+// editor parses and rewrites that literal; at runtime it lowers to ordinary SDK calls (Mesh.box,
+// node.aspect, scene.add), so scenes run identically on every platform with no loader ABI.
+//
+//   // city.scene.ts
+//   export default defineScene({
+//     env: { skybox: '#10131a' },
+//     nodes: {
+//       ground: {
+//         mesh: { kind: 'box', size: [20, 1, 20] },
+//         material: { lit: { color: '#444444' } },
+//         aspects: [use(Shape, { box: [10, 0.5, 10] }), use(Physics, { motion: 'static' })],
+//       },
+//     },
+//   })
+//
+//   // main.ts
+//   import city from './city.scene'
+//   const { scene, nodes } = await city.open()
+//
+// Aspects are referenced by class — the import IS the registration (typechecked, DCE-safe, zero
+// ceremony for user aspects). Behavior never lives in the scene file: write a custom Aspect and
+// attach it via `use(...)`.
+//
+// EDIT MODE (`globalThis.__lecodesSceneEdit`, set by the scene editor before running the bundle):
+// sources are instantiated for real so the viewport shows the scene, but aspects are held as data
+// (`node._sceneAspects`) WITHOUT attaching — no onAttach side effects (physics bodies, timers), no
+// update() ticks. Defined handles register on `globalThis.__lecodesScenes` for the host to pick up.
+
+import { Aspect, type AspectCtor, type With } from "../core/Aspect"
+import { describeAspect, type AspectClassInfo } from "../core/fields"
+import type { ColorInput } from "../core/color"
+import type { Vec3Like } from "../math/vec"
+import { Scene, type SceneOptions } from "../gl/Scene"
+import { Node } from "../gl/Node"
+import { Mesh } from "../gl/Mesh"
+import { Model } from "../gl/Model"
+import { Light, type SunOptions } from "../gl/Light"
+import { Material, type LitMaterialOptions, type MaterialColorOptions } from "../gl/Material"
+import type { CylinderOptions, PlaneOptions, SphereOptions } from "../gl/Geometry"
+
+// ---- the literal grammar (what the visual editor reads and writes) -----------
+
+export type MeshDef =
+  | { kind: "box", size?: Vec3Like | number }
+  | ({ kind: "sphere" } & SphereOptions)
+  | ({ kind: "cylinder" } & CylinderOptions)
+  | ({ kind: "plane" } & PlaneOptions)
+
+export type LightDef = { kind: "sun" } & SunOptions
+
+export type MaterialDef =
+  | { lit: LitMaterialOptions }
+  | { unlit: MaterialColorOptions }
+  | { shadow: ColorInput }
+  // An imported/shared Material instance — valid at runtime; the editor shows it read-only.
+  | Material
+
+/** 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 })
+
+export type SceneNodeDef = {
+  // -- source (at most one; none = plain group node) --
+  mesh?: MeshDef
+  /** GLB url — `asset('./hero.glb')`. */
+  model?: string
+  light?: LightDef
+  /** Material for a `mesh` source. */
+  material?: MaterialDef
+  // -- transform / render --
+  position?: Vec3Like
+  eulerAngles?: Vec3Like
+  scale?: Vec3Like | number
+  visible?: boolean
+  castShadows?: boolean
+  receiveShadows?: boolean
+  // -- capabilities / hierarchy --
+  aspects?: readonly AspectEntry<any>[]
+  children?: Record<string, SceneNodeDef>
+}
+
+export type SceneCameraDef = {
+  position?: Vec3Like
+  /** Point the camera looks at. */
+  target?: Vec3Like
+}
+
+export type SceneDef = {
+  env?: SceneOptions
+  camera?: SceneCameraDef
+  nodes?: Record<string, SceneNodeDef>
+}
+
+// ---- typed handle -------------------------------------------------------------
+
+type SourceNodeOf<N extends SceneNodeDef> =
+  N extends { model: string } ? Model
+  : N extends { mesh: MeshDef } ? Mesh
+  : N extends { light: LightDef } ? Light
+  : Node
+
+type AspectsOf<N extends SceneNodeDef> =
+  N extends { aspects: readonly AspectEntry<infer A>[] } ? A : never
+
+type NodeOf<N extends SceneNodeDef> =
+  [AspectsOf<N>] extends [never] ? SourceNodeOf<N> : With<SourceNodeOf<N>, AspectsOf<N>>
+
+type UnionToIntersection<U> =
+  (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never
+
+// The child maps of a def level, as a union (never when no node has children — guarded below,
+// since `unknown` would absorb the union and `never` would poison the intersection).
+type ChildMapsOf<T extends Record<string, SceneNodeDef>> =
+  { [K in keyof T]: T[K] extends { children: infer C extends Record<string, SceneNodeDef> } ? NodesOf<C> : never }[keyof T]
+
+// All nodes of a def tree, flattened into one name → node map (names are unique per scene file —
+// the editor enforces it; at runtime a duplicate key simply overwrites in the map).
+type NodesOf<T extends Record<string, SceneNodeDef>> =
+  { [K in keyof T]: NodeOf<T[K]> } &
+  ([ChildMapsOf<T>] extends [never] ? unknown : UnionToIntersection<ChildMapsOf<T>>)
+
+export type SceneNodes<D extends SceneDef> =
+  D["nodes"] extends Record<string, SceneNodeDef> ? NodesOf<D["nodes"]> : Record<string, Node>
+
+export type LoadedScene<D extends SceneDef> = {
+  scene: Scene
+  nodes: SceneNodes<D>
+}
+
+// ---- runtime -------------------------------------------------------------------
+
+const EDIT_FLAG = "__lecodesSceneEdit"
+const isEditMode = (): boolean => (globalThis as Record<string, unknown>)[EDIT_FLAG] === true
+
+const resolveMaterial = (def: MaterialDef): Material => {
+  if (def instanceof Material) return def
+  if ("lit" in def) return Material.lit(def.lit)
+  if ("unlit" in def) return Material.unlit(def.unlit)
+  return Material.shadow(def.shadow)
+}
+
+const createMesh = (def: MeshDef, material?: MaterialDef): Mesh => {
+  const mat = material !== undefined ? resolveMaterial(material) : undefined
+  switch (def.kind) {
+    case "box": return Mesh.box({ size: def.size, material: mat })
+    case "sphere": { const { kind: _k, ...opts } = def; return Mesh.sphere({ ...opts, material: mat }) }
+    case "cylinder": { const { kind: _k, ...opts } = def; return Mesh.cylinder({ ...opts, material: mat }) }
+    case "plane": { const { kind: _k, ...opts } = def; return Mesh.plane({ ...opts, material: mat }) }
+  }
+}
+
+const createSource = (name: string, def: SceneNodeDef): Node | Promise<Node> => {
+  const sources = [ def.mesh, def.model, def.light ].filter((s) => s !== undefined).length
+  if (sources > 1) throw new Error(`Scene node "${name}" declares more than one source (mesh/model/light)`)
+  if (def.model !== undefined) return Model.load(def.model)
+  if (def.mesh !== undefined) return createMesh(def.mesh, def.material)
+  if (def.light !== undefined) { const { kind: _k, ...opts } = def.light; return Light.sun(opts) }
+  return new Node()
+}
+
+const applyNode = (node: Node, name: string, def: SceneNodeDef): void => {
+  node.name = name
+  if (def.position) node.position = def.position
+  if (def.eulerAngles) node.eulerAngles = def.eulerAngles
+  if (def.scale !== undefined) node.scale = def.scale
+  if (def.visible !== undefined) node.visible = def.visible
+  if (node instanceof Mesh) {
+    if (def.castShadows !== undefined) node.castShadows = def.castShadows
+    if (def.receiveShadows !== undefined) node.receiveShadows = def.receiveShadows
+  }
+}
+
+const attachAspects = (node: Node, def: SceneNodeDef): void => {
+  if (isEditMode()) {
+    // Data-only: the inspector reads [ctor, props] from here; nothing attaches, so no onAttach side
+    // effects (physics bodies, loops) run while editing. Play mode = the normal branch below.
+    ;(node as unknown as { _sceneAspects: readonly AspectEntry<any>[] })._sceneAspects = def.aspects ?? []
+    return
+  }
+  for (const entry of def.aspects ?? []) {
+    ;(node as Node & { aspect(c: unknown, p?: unknown): unknown }).aspect(entry.ctor, entry.props)
+  }
+}
+
+const instantiate = async (def: SceneDef): Promise<{ scene: Scene, nodes: Record<string, Node> }> => {
+  const scene = new Scene(def.env)
+  const nodes: Record<string, Node> = {}
+
+  const build = async (name: string, nd: SceneNodeDef, parent: Node | null): Promise<void> => {
+    const node = await createSource(name, nd)
+    if (parent) parent.add(node)
+    // Draw-set membership is separate from parenting (see docs/3d/node.md) — every def node joins.
+    scene.add(node)
+    applyNode(node, name, nd)
+    attachAspects(node, nd)
+    nodes[name] = node
+    await Promise.all(Object.entries(nd.children ?? {}).map(([ childName, child ]) => build(childName, child, node)))
+  }
+
+  await Promise.all(Object.entries(def.nodes ?? {}).map(([ name, nd ]) => build(name, nd, null)))
+
+  if (def.camera) {
+    if (def.camera.position) scene.camera.position = def.camera.position
+    if (def.camera.target) scene.camera.lookAt(def.camera.target)
+  }
+
+  return { scene, nodes }
+}
+
+export class SceneHandle<D extends SceneDef = SceneDef> {
+  readonly def: D
+  private _loading?: Promise<LoadedScene<D>>
+
+  constructor(def: D) { this.def = def }
+
+  /** Instantiate the scene (idempotent — subsequent calls return the same instance). Does not open. */
+  load(): Promise<LoadedScene<D>> {
+    if (!this._loading) this._loading = instantiate(this.def) as Promise<LoadedScene<D>>
+    return this._loading
+  }
+
+  /** Load and make active. */
+  async open(): Promise<LoadedScene<D>> {
+    const loaded = await this.load()
+    loaded.scene.open()
+    return loaded
+  }
+
+  /** @internal Editor: describe every aspect class this scene references (fields + defaults). */
+  _describeAspects(): AspectClassInfo[] {
+    const ctors = new Set<AspectCtor<any>>()
+    const walk = (defs?: Record<string, SceneNodeDef>): void => {
+      for (const nd of Object.values(defs ?? {})) {
+        for (const e of nd.aspects ?? []) ctors.add(e.ctor)
+        walk(nd.children)
+      }
+    }
+    walk(this.def.nodes)
+    return [ ...ctors ].map((c) => describeAspect(c))
+  }
+}
+
+/**
+ * Define a scene as data — the default export of a `.scene.ts` file. Returns a typed handle:
+ * `const { scene, nodes } = await handle.open()` gives `nodes.<name>` typed by its source block
+ * (Mesh / Model / Light / Node) with its `use(...)`d aspects attached.
+ */
+export const defineScene = <const D extends SceneDef>(def: D): SceneHandle<D> => {
+  const handle = new SceneHandle(def)
+  const g = globalThis as unknown as { [EDIT_FLAG]?: boolean, __lecodesScenes?: SceneHandle[] }
+  // Editor hook: expose defined handles to the host (the scene editor runs the bundle, then picks
+  // up the handle to load it in edit mode and drive the inspector).
+  if (g[EDIT_FLAG]) (g.__lecodesScenes ??= []).push(handle as SceneHandle)
+  return handle
+}