lecodes-sdk 2.4.1 → 2.4.2

package/package.json

@@ -43,7 +43,7 @@
     "marcidb-embedded": "^0.15.0",
     "sharp": "^0.35.2"
   },
-  "version": "2.4.1",
+  "version": "2.4.2",
   "files": [
     "src",
     "dist",

package/src/bridges/gl.d.ts

@@ -949,9 +949,11 @@ declare global {
      *  wakes a sleeping car. @ifdef CREATOR_GL_PHYSICS */
     vehicleSetInput(vehicleId: u32, input: Float32Array): void
     /** Re-apply the TUNABLE half of the blob (same layout) to a live car — differential, per-wheel tire
-     *  curves / traction / circle, engine torque/RPM/curve, clutch strength + capacity, steer lock, the
-     *  column, anti-roll stiffness, tilt limit. Structural values (mass, centre of mass, wheel geometry,
-     *  the driven shares, suspension, whether an axle has a bar) are ignored: those need a re-create. @ifdef CREATOR_GL_PHYSICS */
+     *  curves / traction / circle, per-wheel radius and spring (stiffness, damping), engine
+     *  torque/RPM/curve, clutch strength + capacity, steer lock, the column, anti-roll stiffness, tilt
+     *  limit; a changed radius or spring wakes a sleeping car. Structural values (mass, centre of mass,
+     *  where the wheels hang, their width and travel, the driven shares, whether an axle has a bar) are
+     *  ignored: those need a re-create. @ifdef CREATOR_GL_PHYSICS */
     vehicleSetTuning?(vehicleId: u32, settings: Float32Array): void
     /** out = [speed, rpm, wheelsInContact, vx, vy, vz, wx, wy, wz, steerDeg, steerTorque] (w = chassis
      *  angular velocity, rad/s; steerDeg = where the road wheels are, right-positive; steerTorque = the

package/src/compile/compileProject.ts

@@ -168,20 +168,55 @@ export const entriesToFiles = (entries: CompileEntry[], opts: { publicUrl: strin
   return files
 }
 
-/** app.json's `"plugins"` in either shape — `{ "camera": "*" }` (id → version spec) or
- *  `["camera"]` (ids, every version `*`) — as id → spec. Anything else is no plugin. The list
- *  form is what CLAUDE.md and most hands write first; reading it as "no plugins" dropped the
- *  plugin from a web build and a shell with one warning nobody tied to the shape. */
-export const pluginSpecsOf = (plugins: unknown): Record<string, string> => {
+/** The platforms an entry of app.json's `"plugins"` may give a spec of their own. */
+export const PLUGIN_PLATFORMS = ["ios", "android", "web"] as const
+export type PluginPlatform = (typeof PLUGIN_PLATFORMS)[number]
+
+/** One entry of app.json's `"plugins"`: ONE spec for every platform (`"*"`, `"^2.0.0"`,
+ *  `"github:owner/repo@v1"`, `"./plugins/<id>"`), or a spec per platform —
+ *  `{ "web": "./plugins/ar-8thwall" }`: the project's own web half of a first-party plugin, the
+ *  first-party halves elsewhere. A platform the object does not name is `"*"`. */
+export type PluginEntry = string | { [P in PluginPlatform]?: string }
+
+/** app.json's `"plugins"` in any shape — `["camera"]` (ids, every spec `*`), `{ "camera": "*" }`
+ *  (id → spec), `{ "ar": { "web": "./plugins/ar-8thwall" } }` (id → a spec per platform) — as
+ *  id → entry. Anything else is no plugin; a value of no known shape is `"*"` (whoever reads
+ *  app.json as a config reports it). The list form is what CLAUDE.md and most hands write first;
+ *  reading it as "no plugins" dropped the plugin from a web build and a shell with one warning
+ *  nobody tied to the shape. */
+export const pluginEntriesOf = (plugins: unknown): Record<string, PluginEntry> => {
   if (Array.isArray(plugins)) return Object.fromEntries(plugins.filter((p): p is string => typeof p === "string").map((id) => [id, "*"]))
-  if (plugins && typeof plugins === "object") {
-    return Object.fromEntries(Object.entries(plugins as Record<string, unknown>).map(([id, v]) => [id, typeof v === "string" ? v : "*"]))
+  if (!plugins || typeof plugins !== "object") return {}
+  const entry = (v: unknown): PluginEntry => {
+    if (typeof v === "string") return v
+    if (!v || typeof v !== "object" || Array.isArray(v)) return "*"
+    const own: { [P in PluginPlatform]?: string } = {}
+    for (const p of PLUGIN_PLATFORMS) {
+      const spec = (v as Record<string, unknown>)[p]
+      if (typeof spec === "string") own[p] = spec
+    }
+    return own
   }
-  return {}
+  return Object.fromEntries(Object.entries(plugins as Record<string, unknown>).map(([id, v]) => [id, entry(v)]))
 }
 
-/** The ids of app.json's `"plugins"` (either shape), in its order. */
-export const pluginIdsOf = (plugins: unknown): string[] => Object.keys(pluginSpecsOf(plugins))
+/** The spec `platform` takes from one entry: the entry's own for it, else `"*"`. A platform an
+ *  entry cannot name (the desktop's libraries) takes `"*"` of a per-platform entry. */
+export const pluginSpecOf = (entry: PluginEntry, platform: string): string =>
+  typeof entry === "string" ? entry : (entry as Record<string, string | undefined>)[platform] ?? "*"
+
+/** app.json's `"plugins"` (any shape) as id → the spec `platform` takes. */
+export const pluginSpecsOf = (plugins: unknown, platform: string): Record<string, string> =>
+  Object.fromEntries(Object.entries(pluginEntriesOf(plugins)).map(([id, entry]) => [id, pluginSpecOf(entry, platform)]))
+
+/** A plugin spec that names a folder of the project (`./plugins/x`, `../x`, `/abs`, `file:x`): a
+ *  plugin of the project's own, or its half of a first-party one (webHalf.ts). */
+export const isLocalPluginSpec = (spec: string): boolean =>
+  spec.startsWith("./") || spec.startsWith("../") || spec.startsWith("/") || spec.startsWith("file:")
+
+/** The ids of app.json's `"plugins"` (any shape), in its order: the `// plugins:` line lists the
+ *  KEY of a per-platform entry too (`ar`), whatever builds each of its halves. */
+export const pluginIdsOf = (plugins: unknown): string[] => Object.keys(pluginEntriesOf(plugins))
 
 /** The ids app.json lists under `"plugins"`, in its order. */
 export const pluginsOfAppJson = (entries: CompileEntry[]): string[] => {

package/src/compile/index.ts

@@ -68,8 +68,14 @@ export {
   compileProject,
   compileProjectWithMap,
   pluginsOfAppJson,
+  pluginEntriesOf,
+  pluginSpecOf,
   pluginSpecsOf,
   pluginIdsOf,
+  isLocalPluginSpec,
+  PLUGIN_PLATFORMS,
+  type PluginEntry,
+  type PluginPlatform,
   pluginsOfBundle,
   entriesToFiles,
   localAssetNames,
@@ -79,6 +85,7 @@ export {
   type CompileFileType,
   type CompileResult,
 } from "./compileProject"
+export { bundleWebHalf, webHalfManifestOf, webHalfSpecsOf, type WebHalfBuild, type WebHalfManifest } from "./webHalf"
 export {
   sceneEditorEntries,
   sceneImportsOf,

package/src/compile/webHalf.ts

@@ -0,0 +1,255 @@
+// A project's OWN web half of a plugin, built for Web Lite: a folder of the project app.json names
+// for a plugin on the web — a half folder over a first-party plugin (`"ar": { "web":
+// "./plugins/ar-8thwall" }`, its manifest `implements: "ar"`) or a plugin of the project's own with a
+// web half (`"dial": "./plugins/dial"`). ONE implementation of what such a half is built into, for the
+// two that build one: the CLI (`lecodes web build | dev`, from the project's folder) and the build
+// service (`POST /compile/project` with `webHalves`, from the entries it is sent, staged in a folder
+// of its own) — so the page the platform deploys runs the half `web build` would have built.
+//
+// The half is plain TypeScript of its own folder, bundled by Bun into ONE ES module that exports
+// `register(host)`:
+//   - an import of a package (a LeCodes one too) is refused: the half runs on the page by itself —
+//     the browser and the host it is handed are its world; `lecodes plugin gen` writes the glue it
+//     imports (`web/<id>.gen.ts`);
+//   - an import of a file OUTSIDE the folder is refused: a half is built from its folder, and the
+//     build service stages only that — a path out of it would read the build machine's files;
+//   - a macro import is refused, never run: a Bun macro is code run AT BUILD TIME on the machine that
+//     builds, and the build service builds what any project sends it. `macros: false` alone does not
+//     hold — Bun 1.3 (the build service's image) ignores it — so every file goes through the
+//     plugin's onLoad, parsed with macros off before Bun parses it;
+//   - the build machine's environment is never inlined (`process.env.X` stays what it is).
+// What a first-party half asks of its bundler (`web.dependencies`, `web.resources`) is Web Lite's
+// page build's, not a project's: a file the half fetches goes in its `web.static` folder, put beside
+// the module as it is by whoever serves the page.
+//
+// Bun is reached at call time, never at import time: the module stays importable on Node and in
+// the editor (index.ts), and only a build needs Bun.
+
+import { realpathSync } from "node:fs"
+import { readFile } from "node:fs/promises"
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path"
+import { isLocalPluginSpec, pluginSpecsOf } from "./compileProject"
+
+/** The plugins app.json names a folder of the project for on the web, in its order: id → the spec
+ *  (`./plugins/ar-8thwall`, `file:plugins/dial`). `appJson` is app.json's parsed value, in any of its
+ *  `"plugins"` shapes; anything else names none. */
+export const webHalfSpecsOf = (appJson: unknown): { id: string, spec: string }[] => {
+  const plugins = appJson && typeof appJson === "object" ? (appJson as { plugins?: unknown }).plugins : undefined
+  return Object.entries(pluginSpecsOf(plugins, "web"))
+    .filter(([, spec]) => isLocalPluginSpec(spec))
+    .map(([id, spec]) => ({ id, spec }))
+}
+
+/** What a build takes of a half folder's manifest. */
+export type WebHalfManifest = {
+  /** The first-party plugin the folder implements (a half folder); null for a plugin of the
+   *  project's own (its folder's name is its id). */
+  implements: string | null
+  /** The module that exports `register(host)`, by its path in the folder (`web/ar.ts`). */
+  register: string
+  /** `web.static`: a folder of the half, by its path in it, put beside the built module as it is
+   *  (names unhashed — a runtime the half loads by its own url fetches its files relative to
+   *  itself); null when none. */
+  static: string | null
+}
+
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+
+/** A path INSIDE the folder: relative, no empty / `.` / `..` segment. */
+const isInnerPath = (path: string): boolean =>
+  path.trim() !== "" && !/^[\\/]/.test(path) && !/^[A-Za-z]:/.test(path) &&
+  path.split(/[\\/]/).every((s) => s !== "" && s !== "." && s !== "..")
+
+/**
+ * The manifest of the half folder `folder` (its name) that app.json names for the plugin `id`, as a
+ * build reads it: the checks that decide what is built, and nothing else — a manifest is validated
+ * whole by `lecodes plugin gen` and the CLI (tools/cli/src/plugin/manifest.ts), which name every
+ * problem of the file at once. Throws an Error that says what to change.
+ */
+export const webHalfManifestOf = (text: string, folder: string, id: string): WebHalfManifest => {
+  const file = `Plugin "${id}": ${folder}/lecodes-plugin.json`
+  let raw: unknown
+  try { raw = JSON.parse(text.replace(/^/, "")) } catch (e) {
+    throw new Error(`${file} is not JSON: ${e instanceof Error ? e.message : String(e)}`)
+  }
+  if (!isObject(raw)) throw new Error(`${file}: a manifest is an object`)
+
+  const impl = raw.implements
+  if (impl !== undefined && typeof impl !== "string") throw new Error(`${file}: implements is the id of the first-party plugin whose contract the folder implements ("ar")`)
+  if (impl !== undefined ? impl !== id : folder !== id) {
+    throw new Error(impl !== undefined
+      ? `Plugin "${id}": the folder "${folder}" implements "${impl}" — app.json names it under that plugin: "${impl}": { "web": "./…/${folder}" }`
+      : `Plugin "${id}": the folder "${folder}" is the plugin "${folder}" — app.json names a plugin of the project by its folder's name`)
+  }
+
+  const web = raw.web
+  if (web === null || web === undefined) throw new Error(`Plugin "${id}": the folder "${folder}" has no web half (its manifest says "web": null) — app.json names it for the web.`)
+  if (!isObject(web)) throw new Error(`${file}: web is an object, or null`)
+  if (web.dependencies !== undefined || web.resources !== undefined) {
+    throw new Error(`Plugin "${id}": a project's web half is built with no packages — web.dependencies and web.resources are the first-party halves' (built in Web Lite's page); a file the half fetches goes in its web.static folder.`)
+  }
+  const register = web.register
+  if (typeof register !== "string" || !register.startsWith("web/") || !isInnerPath(register)) {
+    throw new Error(`${file}: web.register ${JSON.stringify(register)} — the module of the folder's web/ that exports register(host) ("web/${impl ?? id}.ts")`)
+  }
+  const folderStatic = web.static
+  if (folderStatic !== undefined) {
+    if (typeof folderStatic !== "string" || !isInnerPath(folderStatic)) throw new Error(`${file}: web.static — a folder of the plugin, by its path in it ("xr-runtime")`)
+    if (folderStatic === "index.js") throw new Error(`${file}: web.static "index.js" is the built module's name`)
+  }
+  return { implements: impl ?? null, register, static: folderStatic ?? null }
+}
+
+/** What of Bun a half's build uses — typed here rather than by bun-types, so the module type-checks
+ *  wherever lecodes-sdk/compile is imported (the editor's world has no Bun). */
+type ResolveArgs = { path: string, importer: string, kind: string }
+type LoadArgs = { path: string, loader: string }
+type Loaded = { contents: string | Uint8Array, loader: string }
+type BuildPlugin = {
+  name: string
+  setup(build: {
+    onResolve(options: { filter: RegExp }, callback: (args: ResolveArgs) => { path: string, external: boolean } | undefined): void
+    onLoad(options: { filter: RegExp }, callback: (args: LoadArgs) => Promise<Loaded>): void
+  }): void
+}
+type BuildConfig = {
+  entrypoints: string[]
+  format: "esm"
+  target: "browser"
+  minify: boolean
+  sourcemap: "inline" | "none"
+  env: "disable"
+  /** Not in bun-types; read by Bun.build from 1.4 (`bun build --no-macros`), IGNORED by 1.3 — the
+   *  onLoad gate below is what holds on every Bun. */
+  macros: false
+  plugins: BuildPlugin[]
+}
+type BuildResult = { success: boolean, logs: { message: string }[], outputs: { kind: string, text(): Promise<string> }[] }
+/** `macro: false` is not in bun-types either: the parse refuses a macro import ("Macros are
+ *  disabled") instead of running it, on 1.3 and 1.4 alike. */
+type Transpiler = new (options: { loader: string, target: "browser", macro: false }) => { transformSync(code: string): string }
+type BunApi = { build(config: BuildConfig): Promise<BuildResult>, Transpiler: Transpiler }
+
+/** A file's loader, by its extension alone (Bun's defaults; anything else is a `file`, an asset):
+ *  onLoad's own `args.loader` says "js" for an extension it does not know. */
+const LOADERS: Record<string, string> = {
+  js: "jsx", jsx: "jsx", mjs: "js", cjs: "js", ts: "ts", mts: "ts", cts: "ts", tsx: "tsx",
+  json: "json", jsonc: "json", toml: "toml", txt: "text", css: "css",
+}
+const loaderOf = (path: string): string => LOADERS[/\.([^./\\]+)$/.exec(path)?.[1]?.toLowerCase() ?? ""] ?? "file"
+/** The loaders that parse a file as code — where an import, and so a macro, can be. */
+const CODE_LOADERS = new Set(["js", "jsx", "ts", "tsx"])
+
+/** A build's or a parse's errors, one line each (`web/ar.ts:2:10: Expected ";"`). */
+const messagesOf = (e: unknown, file?: string): string[] =>
+  ((e as { errors?: unknown[] }).errors ?? [e]).map((m) => {
+    const { message, position } = m as { message?: unknown, position?: { line?: number, column?: number } | null }
+    const text = String(message ?? m).replace(/^BuildMessage: /, "")
+    return file ? `${file}${position?.line ? `:${position.line}:${position.column ?? 0}` : ""}: ${text}` : text
+  })
+
+export type WebHalfBuild = {
+  /** The plugin's id (app.json's key), named in every error. */
+  id: string
+  /** The half's folder: what it is built from, and all it may import. */
+  dir: string
+  /** The module that exports `register(host)` (the manifest's `web.register`): a path in `dir`, or
+   *  relative to it. */
+  entry: string
+  /** Not minified, its source map inline (`lecodes web dev`). */
+  dev?: boolean
+  /** Default true; `dev` turns it off. */
+  minify?: boolean
+}
+
+/** The half as ONE ES module's text. Throws an Error that names the plugin and what to change. */
+export const bundleWebHalf = async (half: WebHalfBuild): Promise<string> => {
+  // (through unknown: where bun-types are loaded, their `Bun` is not this structural one)
+  const bun = (globalThis as unknown as { Bun?: BunApi }).Bun
+  if (!bun) throw new Error(`Plugin "${half.id}": a project's web half is built with Bun — run the CLI of a checkout or the standalone binary (bun), not on Node.`)
+  // The folder as the path given AND as the file system names it: Bun reports a module by its real
+  // path (macOS's temporary folders are /var → /private/var).
+  const roots = [resolve(half.dir)]
+  try { roots.push(realpathSync(half.dir)) } catch { /* no such folder: the build says so */ }
+  const inner = (path: string): string | null => {
+    for (const root of roots) {
+      const rel = relative(root, path)
+      if (rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel))) return rel.split(sep).join("/")
+    }
+    return null
+  }
+  const entry = resolve(half.dir, half.entry)
+  if (inner(entry) === null) throw new Error(`Plugin "${half.id}": its web.register ${half.entry} is no file of its folder`)
+  const shown = (path: string) => inner(path) || path
+  const foreign: string[] = []      // packages, by the module that imports one
+  const outside: string[] = []      // files out of the folder
+  const macros: string[] = []       // modules that import a macro
+  const unparsed: string[] = []     // modules the macro-free parse refused otherwise
+  let result: BuildResult
+  try {
+    result = await bun.build({
+      entrypoints: [entry],
+      format: "esm",
+      target: "browser",
+      minify: half.dev ? false : half.minify !== false,
+      sourcemap: half.dev ? "inline" : "none",
+      env: "disable",
+      macros: false,
+      plugins: [{
+        name: "lecodes-project-half",
+        setup(build) {
+          build.onResolve({ filter: /.*/ }, (args) => {
+            if (args.kind.startsWith("entry-point")) return undefined
+            if (/^\.{0,2}\//.test(args.path)) {
+              if (inner(resolve(dirname(args.importer), args.path)) !== null) return undefined
+              outside.push(`${shown(args.importer)}: "${args.path}"`)
+            } else {
+              foreign.push(`${shown(args.importer)}: "${args.path}"`)
+            }
+            return { path: args.path, external: true }
+          })
+          // Every file the build reads is read HERE, never by Bun: one out of the folder is not read
+          // (a resolution that left it — a package.json `browser` map — is caught by its path); a
+          // file is read by its extension's loader, whatever an import attribute asks (`with { type:
+          // "ts" }` would parse a .txt as code); code is parsed with macros off first, and a module
+          // that fails it is handed over EMPTY, so no Bun ever parses it with macros on.
+          build.onLoad({ filter: /.*/ }, async (args) => {
+            const name = inner(args.path)
+            if (name === null) { outside.push(`"${args.path}"`); return { contents: "", loader: "js" } }
+            const bytes = await readFile(args.path)
+            const loader = loaderOf(args.path)
+            if (CODE_LOADERS.has(loader)) {
+              try {
+                new bun.Transpiler({ loader, target: "browser", macro: false }).transformSync(bytes.toString("utf8"))
+              } catch (e) {
+                const messages = messagesOf(e, name)
+                if (messages.some((m) => /macros are disabled/i.test(m))) macros.push(name)
+                else unparsed.push(...messages)
+                return { contents: "", loader: "js" }
+              }
+            }
+            return { contents: bytes, loader }
+          })
+        },
+      }],
+    })
+  } catch (e) {
+    // what the gate refused is said first (a module it emptied fails the build after it); else these
+    result = { success: false, logs: messagesOf(e).map((message) => ({ message })), outputs: [] }
+  }
+  if (macros.length) {
+    throw new Error(`Plugin "${half.id}": its web half imports a macro (\`with { type: "macro" }\` — code Bun runs at build time, on the machine that builds); a half imports its own modules:\n${macros.map((f) => `  ${f}`).join("\n")}`)
+  }
+  if (foreign.length) {
+    throw new Error(`Plugin "${half.id}": its web half imports a package — a project's half is built from its own files (the generated web/*.gen.ts, the host it is handed, the browser):\n${foreign.map((f) => `  ${f}`).join("\n")}`)
+  }
+  if (outside.length) {
+    throw new Error(`Plugin "${half.id}": its web half imports a file outside its folder — a half is built from its folder's files alone:\n${outside.map((f) => `  ${f}`).join("\n")}`)
+  }
+  if (unparsed.length) throw new Error(`Plugin "${half.id}": its web half did not build:\n${unparsed.map((m) => `  ${m}`).join("\n")}`)
+  if (!result.success) throw new Error(`Plugin "${half.id}": its web half did not build:\n${result.logs.map((l) => `  ${l.message}`).join("\n")}`)
+  if (result.outputs.length !== 1 || result.outputs[0]!.kind !== "entry-point") {
+    throw new Error(`Plugin "${half.id}": its web half builds into ${result.outputs.length} files — a half is ONE module: it imports its own .ts / .js only (a file it fetches goes in its web.static folder).`)
+  }
+  return await result.outputs[0]!.text()
+}

package/src/core/Aspect.ts

@@ -75,6 +75,7 @@ export type With<N, A extends Aspect<any, any, any>> =
 interface Updatable {
   _phaseSeq: number
   _phases: number
+  _live: boolean
   updateOrder: number
   updateWhilePaused: boolean
   update?(dt: number): void
@@ -82,7 +83,7 @@ interface Updatable {
   updateFixed?(dt: number): void
   onAttach?(): void
   onDetach?(): void
-  onReconfigure?(): void
+  flush?(): void
 }
 const internals = (a: Aspect<any, any, any>): Updatable => a as unknown as Updatable
 type PhaseFn = (dt: number) => void
@@ -218,6 +219,31 @@ const rankConstraints = (items: (Updatable | null)[]): Map<Function, number> =>
 const earlyUpdaters = new PhaseList()
 const lateUpdaters = new PhaseList()
 const fixedUpdaters = new PhaseList()
+
+// ---- the dirty set: a live property changed, its aspect flushes ONCE, before the step ------------
+// A setter of a live property stores the value and calls `this.dirty()`; the aspect lands here and
+// its `flush()` runs before the physics step: the set is drained at the start of the early phase
+// (writes made since the last frame — events, the late phase) and again right after the early
+// updaters (writes made in an `updateBefore`), so the step runs on the new numbers however many
+// properties changed. A flush may dirty another aspect (a Wheel hands its change to its Vehicle):
+// a drain repeats until the set is empty, so a dependent flushes in the SAME pass. A write before
+// attach only stores (onAttach sends everything); a detach drops the aspect from the set.
+const dirtyAspects = new Set<Updatable>()
+const MAX_FLUSH_ROUNDS = 8
+const drainDirty = (): void => {
+  for (let round = 0; dirtyAspects.size > 0; round++) {
+    if (round === MAX_FLUSH_ROUNDS) {
+      warnOnce("[aspects] flush() keeps dirtying aspects — the remaining ones flush next frame")
+      return
+    }
+    const batch = [ ...dirtyAspects ]
+    dirtyAspects.clear()
+    for (const a of batch) if (a._live) a.flush?.()
+  }
+}
+/** @internal Tests: run the pending flushes now, the way the next early phase would. */
+export const _flushDirtyAspects = (): void => drainDirty()
+
 let dispatchInstalled = false
 let fixedInstalled = false
 let fixedFallbackOn = false
@@ -240,23 +266,29 @@ const fixedFallback = (): void => {
   if (steps === 4) fixedFallbackAcc = 0
 }
 
+// The two phase passes. Both scale their OWN raw dt (the engine hands the same value to both; a host
+// or test that drives them apart still gets each phase's dt right). The frame counter / clocks
+// advance once, early. The pending flushes go out right before the early updaters.
+const early: PhaseFn = (dt) => {
+  _phaseStamp.value++
+  Time._beginFrame(dt)
+  _phaseHooks.early?.(dt)
+  drainDirty()
+  earlyUpdaters.run("updateBefore", Time.dt)
+  drainDirty()
+  if (fixedFallbackOn) fixedFallback()
+}
+const late: PhaseFn = (dt) => {
+  _phaseStamp.value++   // the physics step + transform sync ran since the early pass
+  lateUpdaters.run("update", Time._phaseDt(dt))
+  _phaseHooks.late?.(dt)
+}
+/** @internal Tests: the phase passes themselves, whatever frame source is installed. */
+export const _runPhase = { early, late }
+
 const ensureDispatch = (): void => {
   if (dispatchInstalled) return
   dispatchInstalled = true
-  // Both phases scale their OWN raw dt (the engine hands the same value to both; a host or test that
-  // drives them apart still gets each phase's dt right). The frame counter / clocks advance once, early.
-  const early: PhaseFn = (dt) => {
-    _phaseStamp.value++
-    Time._beginFrame(dt)
-    _phaseHooks.early?.(dt)
-    earlyUpdaters.run("updateBefore", Time.dt)
-    if (fixedFallbackOn) fixedFallback()
-  }
-  const late: PhaseFn = (dt) => {
-    _phaseStamp.value++   // the physics step + transform sync ran since the early pass
-    lateUpdaters.run("update", Time._phaseDt(dt))
-    _phaseHooks.late?.(dt)
-  }
   // render-synced source if an engine layer installed one; else one host loop (early then late).
   if (!(frameInstaller && frameInstaller(early, late))) {
     setLoop((dt) => { early(dt); late(dt) })
@@ -317,25 +349,26 @@ const untrackInstance = (a: Aspect<any, any, any>): void => {
 // (a node's `_aspects`, a scene's `_systems`).
 type Store = Map<Function, Aspect<any, any, any>>
 
+// `aspect(Ctor, opts)` always BUILDS: a class already on the host is detached first and a fresh
+// instance is made from exactly `opts` (every other field at its class default). Changing a live
+// value is a property write on the instance — a setter, or `Object.assign(node.x, {…})` for several
+// at once — never a second `aspect()` call, which resets the aspect's state (and strands any
+// reference to the old instance: take `node.<accessor>` again).
 const attachTo = <Self, A extends Aspect<any, any, any>>(
   host: Self, store: Store, ctor: AspectCtor<A>, opts: Partial<A> | undefined, scene: unknown,
 ): Self & FieldOf<A> => {
-  let inst = store.get(ctor) as A | undefined
-  const fresh = inst === undefined
-  if (!inst) {
-    inst = new (ctor as unknown as new () => A)()
-    ;(inst as { node: unknown }).node = host
-    if (scene !== undefined) (inst as { scene: unknown }).scene = scene
-    store.set(ctor, inst)
-    const name = (ctor as Ctor).aspect
-    if (name) (host as unknown as Record<string, unknown>)[name] = inst
-  }
+  if (store.has(ctor)) detachFrom(host, store, ctor)
+  const inst = new (ctor as unknown as new () => A)()
+  ;(inst as { node: unknown }).node = host
+  if (scene !== undefined) (inst as { scene: unknown }).scene = scene
+  store.set(ctor, inst)
+  const name = (ctor as Ctor).aspect
+  if (name) (host as unknown as Record<string, unknown>)[name] = inst
   if (opts) Object.assign(inst, opts)
-  if (fresh) {
-    trackInstance(inst)
-    internals(inst).onAttach?.()
-    registerUpdater(inst)
-  } else if (opts) internals(inst).onReconfigure?.()
+  trackInstance(inst)
+  internals(inst)._live = true
+  internals(inst).onAttach?.()
+  registerUpdater(inst)
   return host as Self & FieldOf<A>
 }
 
@@ -343,6 +376,8 @@ const detachFrom = (host: unknown, store: Store, ctor: Function): void => {
   const inst = store.get(ctor)
   if (!inst) return
   internals(inst).onDetach?.()
+  internals(inst)._live = false
+  dirtyAspects.delete(internals(inst))
   unregisterUpdater(inst)
   untrackInstance(inst)
   inst._clearEvents()
@@ -368,8 +403,10 @@ export abstract class AspectHost<E extends EventMap = EventMap> extends Emitter<
   /** @internal class → instance, the authoritative store (named accessors mirror this). */
   readonly _aspects = new Map<Function, Aspect<any, any, any>>()
 
-  /** Attach (and configure) an aspect, or reconfigure it if already present. Returns the node typed
-   *  as now-having that aspect (so no guard/`?.` is needed afterwards). Rejects a wrong target node. */
+  /** Attach an aspect built from `opts` (a class already on the node is detached first and REBUILT
+   *  from exactly these options — a structural change; a live value is a property write on
+   *  `node.<accessor>`). Returns the node typed as now-having that aspect (so no guard/`?.` is
+   *  needed afterwards). Rejects a wrong target node. */
   aspect<Self extends TargetOf<A>, A extends Aspect<any, any, any>>(
     this: Self,
     ctor: AspectCtor<A>,
@@ -496,6 +533,8 @@ export abstract class Aspect<K extends string, P = Node, E extends EventMap = {}
   _phaseSeq = 0
   /** @internal bit 1 = registered early, bit 2 = registered late. */
   _phases = 0
+  /** @internal true between onAttach and onDetach: the only time `dirty()` schedules a flush. */
+  _live = false
   private _listeners?: Map<string, Function[]>
 
   // ---- lifecycle: the engine calls these, game code never does (hence `protected`; a subclass may
@@ -504,9 +543,53 @@ export abstract class Aspect<K extends string, P = Node, E extends EventMap = {}
   protected onAttach?(): void
   /** Release what onAttach acquired. */
   protected onDetach?(): void
-  /** Called after `node.aspect(Ctor, opts)` re-assigns options on an ALREADY attached aspect (a
-   *  pre-attached one like `model.anim`): rebuild whatever was derived from the options at attach. */
-  protected onReconfigure?(): void
+  /**
+   * LIVE PROPERTIES. A value the engine must hear about is a get/set pair whose setter stores it and
+   * calls `this.dirty()`; `flush()` then runs ONCE before the next physics step — at the start of
+   * the early phase for a write made since the last frame, right after the early updaters for one
+   * made in an `updateBefore` — however many properties changed, one send. `node.aspect(Ctor, opts)`
+   * and the scene file write the same setters. Before attach a setter only stores (onAttach sends
+   * everything); after detach nothing flushes. A value with a bridge call of its own, or one whose
+   * result the caller reads back at once (a Shape's dimensions: `controller.resizing`), skips the
+   * batch and pushes from its setter.
+   *
+   *   get radius(): number { return this._radius }
+   *   set radius(v: number) { this._radius = v; this.dirty() }
+   *   protected flush(): void { _creator.thingSetTuning(this._id, this._settings()) }
+   */
+  protected dirty(): void {
+    if (!this._live) return
+    dirtyAspects.add(internals(this))
+    ensureDispatch()
+  }
+  /** Send what the setters changed — see `dirty()`. */
+  protected flush?(): void
+  /**
+   * A nested config object as a LIVE VIEW: every key of `defaults` becomes an accessor whose setter
+   * stores and calls `this.dirty()`, so `wheel.suspension.stiffness = 2` reaches the engine like any
+   * live property. `value` is taken WHOLE: a key it leaves out is the default, nothing of a previous
+   * object survives (`wheel.suspension = { stiffness: 2 }` is stiffness 2 and the default travel and
+   * damping). Writing `undefined` to a key restores its default. One level deep: a value that is
+   * itself an object is replaced, not watched.
+   *
+   *   private _suspension = this.live(SUSPENSION_DEFAULTS)
+   *   get suspension(): WheelSuspension { return this._suspension }
+   *   set suspension(v: WheelSuspension) { this._suspension = this.live(SUSPENSION_DEFAULTS, v); this.dirty() }
+   */
+  protected live<T extends object>(defaults: T, value?: Partial<T>): T {
+    const view = {} as Record<string, unknown>
+    const store = { ...defaults } as Record<string, unknown>
+    const given = value as Record<string, unknown> | undefined
+    for (const key of Object.keys(defaults)) {
+      if (given && given[key] !== undefined) store[key] = given[key]
+      Object.defineProperty(view, key, {
+        enumerable: true,
+        get: () => store[key],
+        set: (v: unknown) => { store[key] = v === undefined ? (defaults as Record<string, unknown>)[key] : v; this.dirty() },
+      })
+    }
+    return view as T
+  }
   /**
    * GENERATOR aspects: (re)build the derived output under `this.generated` — must be idempotent
    * (clear, then create). Call it from `onAttach()` for play mode; a class opting in with

package/src/g2/OneWay2D.ts

@@ -55,8 +55,6 @@ export class OneWay2D extends Aspect<"oneWay", Node2D> {
     if (id) _creator2d.physicsSetOneWay(id, 0, 1, 90, false)
   }
 
-  onReconfigure(): void { this._push() }
-
   private _push(): void {
     const id = this.node.get(Physics2D)?.id
     // via the public accessors on purpose: an accessor pair that is only ever an object-literal key

package/src/g2/Physics2D.ts

@@ -65,10 +65,14 @@ export class Physics2D extends Aspect<"physics", Node2D> {
     this.node._physicsDriven = m !== "static"
     if (this._h) _creator2d.physicsSetMotionType(this._h, MOTION[m])
   }
-  /** Lock rotation (essential for platformer characters). */
-  fixedRotation = false
-  /** Continuous collision for fast-moving bodies (projectiles). */
-  bullet = false
+  private _fixedRotation = false
+  /** Lock rotation (essential for platformer characters). Live. */
+  get fixedRotation(): boolean { return this._fixedRotation }
+  set fixedRotation(v: boolean) { this._fixedRotation = v; if (this._h) _creator2d.physicsSetFixedRotation(this._h, v) }
+  private _bullet = false
+  /** Continuous collision for fast-moving bodies (projectiles). Live. */
+  get bullet(): boolean { return this._bullet }
+  set bullet(v: boolean) { this._bullet = v; if (this._h) _creator2d.physicsSetBullet(this._h, v) }
 
   private _mass = 0            // 0 = derive from the collider area
   private _friction = DEFAULT_FRICTION
@@ -164,18 +168,6 @@ export class Physics2D extends Aspect<"physics", Node2D> {
     this.node._xfKind = 0
   }
 
-  /** Re-applying options (`node.aspect(Physics2D, {…})`) pushes the live ones through. */
-  onReconfigure(): void {
-    if (!this._h) return
-    this._pushMaterial()
-    _creator2d.physicsSetFixedRotation(this._h, this.fixedRotation)
-    _creator2d.physicsSetBullet(this._h, this.bullet)
-    _creator2d.physicsSetGravityScale(this._h, this.gravityScale)
-    _creator2d.physicsSetLinearDamping(this._h, this.linearDamping)
-    _creator2d.physicsSetAngularDamping(this._h, this.angularDamping)
-    if (this._mass > 0) _creator2d.physicsSetMass(this._h, this.mass)
-  }
-
   /** Linear velocity in world units/second (fresh Vec2 on read). */
   get velocity(): Vec2 {
     const o = this._h ? _creator2d.physicsGetLinearVelocity(this._h) : null