lecodes-cli 0.2.0 → 0.5.0

package/runtime/sdk/compile/header.ts

@@ -0,0 +1,46 @@
+// The metadata header the launcher reads from the compiled bundle: name / icon / preload / gl / 2d /
+// ar. Single source of truth — the backend and CLI both call this (today they mirror it by hand).
+//
+// Detection keys on the *bundled* `_creator*` calls, which the SDK's thin wrappers still emit
+// (new Scene() → _creator.createScene, new Scene2D() → _creator2d.createScene), so the re-skin keeps
+// the exact same signals the old worker bundles produced.
+
+export type HeaderOptions = {
+  /** Generated-icon URL (backend supplies it; the CLI omits it). */
+  icon?: string
+}
+
+export const buildHeader = (name: string, code: string, opts: HeaderOptions = {}): string => {
+  let header = `// name: ${name.slice(0, 20)}\n`
+  if (opts.icon) header += `// icon: ${opts.icon}\n`
+  header += `// last-updated: ${new Date().toISOString()}\n`
+
+  // Local assets to preload: explicit fetchLocal() calls + implicit engine archives.
+  const localAssets = new Set<string>()
+  for (const m of code.matchAll(/_creatorUtils\.fetchLocal\((.+?)\)/g)) {
+    localAssets.add(m[1].replaceAll(/['"]/g, "").trim())
+  }
+  if (/_creator\.createGlb/.test(code)) localAssets.add("uberarchive")
+  if (/_creator\.captureImage/.test(code)) localAssets.add("capture")
+  if (localAssets.size > 0) header += `// preload: ${[ ...localAssets ].join(";")}\n`
+
+  // GL: disabled unless the project touches the 3D engine; deferred if it lazily creates the engine.
+  if (!code.includes("_creator.createScene") && !code.includes("_creator.createEntity")) header += `// gl: disable\n`
+  else if (code.includes("_creator.createEngine")) header += `// gl: defer\n`
+
+  // 2D (creator-2d) — non-exclusive: emitted alongside `gl: disable` so hosts skip Filament and a
+  // 2D-aware host brings up the lightweight sokol engine instead.
+  if (code.includes("_creator2d.")) header += `// 2d: enable\n`
+
+  if (code.includes("_creator.createARController")) header += "// ar: enable"
+  header += "\n"
+  return header
+}
+
+/** Same engine signals the header uses, for callers that need the project kind (e.g. icon type). */
+export const detectProjectKind = (code: string): "ar" | "ui" | "2d" | "3d" => {
+  if (code.includes("_creator.createARController")) return "ar"
+  if (code.includes("_creator2d.")) return "2d"
+  if (!code.includes("_creator.")) return "ui"
+  return "3d"
+}

package/runtime/sdk/compile/index.ts

@@ -0,0 +1,12 @@
+// The public entry of the SDK's bundle build system. The backend, CLI, and local renderer import
+// from here instead of re-forking a bundler. (Node + Bun safe — no top-level host globals.)
+
+export { bundleProject, bundleProjectWithMap, type MemoryFiles } from "./bundler"
+export { offsetSourceMap, inlineSourceMapComment } from "./sourcemap"
+export { buildHeader, detectProjectKind, type HeaderOptions } from "./header"
+export {
+  compileProject,
+  type CompileEntry,
+  type CompileOptions,
+  type CompileFileType,
+} from "./compileProject"

package/runtime/sdk/compile/sourcemap.ts

@@ -0,0 +1,25 @@
+// Helpers for serving the bundler's source map alongside the bundle. The map's generated positions
+// are relative to the bundle code; when the deploy/preview prepends a comment header, the map must be
+// shifted down by that many lines, then inlined into the bundle as a data URL (the preview executes
+// the bundle via `new Function(string)`, which has no URL identity, so an external `.map` can't be
+// fetched — it must be inline).
+
+/** Shift every generated position in `mapJson` down by `lines` (each VLQ line is `;`-separated). */
+export const offsetSourceMap = (mapJson: string, lines: number): string => {
+  if (lines <= 0) return mapJson
+  const map = JSON.parse(mapJson) as { mappings: string }
+  map.mappings = ";".repeat(lines) + map.mappings
+  return JSON.stringify(map)
+}
+
+/**
+ * Inline the map into a bundle string under a **non-standard** directive (`lecodesMap`, not
+ * `sourceMappingURL`), so the browser does NOT auto-apply it. The bundle runs via `new Function`, and
+ * the browser maps the raw stack position *including* the `new Function` wrapper (~2-3 lines) which the
+ * map can't subtract — so its native source location would be off by those lines. Our preview mapper
+ * reads `lecodesMap` and subtracts the (calibrated) wrapper itself, so its locations are correct.
+ */
+export const inlineSourceMapComment = (mapJson: string): string => {
+  const b64 = Buffer.from(mapJson, "utf8").toString("base64")
+  return `//# lecodesMap=data:application/json;charset=utf-8;base64,${b64}`
+}

package/runtime/sdk/core/Aspect.ts

@@ -3,7 +3,7 @@
 //
 //   const hero = new Sprite({ texture })
 //     .aspect(SpriteAnimation, { fps: 8, clips: { walk: [1, 2, 3] } })   // attach + configure
-//     .aspect(Collider, { box: [16, 8], trigger: true })                 // chains: returns the node
+//     .aspect(Shape2D, { box: [16, 8] })                                 // chains: returns the node
 //   hero.anim.play('walk')          // access by name (the chain result is typed as having it)
 //   if (hero.has(Physics)) hero.physics.velocity = [0, 0]                // has() is a type guard
 //
@@ -39,28 +39,70 @@ type UnionToIntersection<U> =
 export type With<N, A extends Aspect<any, any>> =
   N & UnionToIntersection<A extends any ? FieldOf<A> : never>
 
-// ---- per-frame update dispatch ----------------------------------------------
-// Aspects that define update(dt) are ticked every frame from a SINGLE global loop, created LAZILY on
-// the first such aspect (a project with no behavior aspects starts no loop). dt is seconds, like
-// setLoop. No visibility/frustum culling yet — every registered aspect ticks regardless of on-screen
-// state.
-const updaters: Aspect<any, any>[] = []
-let updateLoopId: number | undefined
-
-const ensureUpdateLoop = (): void => {
-  if (updateLoopId !== undefined) return
-  updateLoopId = setLoop((dt) => {
-    // iterate a snapshot so an update() that attaches/detaches aspects can't corrupt this frame's pass
-    for (const a of updaters.slice()) {
-      // later (visibility culling): if (a.updateWhenVisible && nodeOffScreen(a)) continue
-      a.update?.(dt)
-    }
-  })
+// ---- per-frame update dispatch (two phases) ---------------------------------
+// Aspects that define update(dt) are ticked every frame in ONE of two phases, chosen by the aspect's
+// `updateBeforePhysics` field:
+//   • LATE (default): after the physics step + transform sync, right before the frame draws. Reads of
+//     node.worldPosition are the FINAL drawn position — cameras/followers land exactly, no 1-frame lag.
+//   • EARLY (updateBeforePhysics = true): before the physics step, so writing velocity/force/kinematic
+//     transforms is consumed by the SAME frame's step (zero input latency).
+// The FRAME SOURCE is pluggable so core never names a specific engine bridge (a 3D-only bundle must not
+// pull in the 2D one): the 2D layer installs a render-synced source via _installAspectFrames (the native
+// c2dRender early/late hooks), so dispatch is in lockstep with the draw. With none installed (3D-only,
+// or a runtime without the hooks) it falls back to a single host setLoop, early-then-late — no true
+// post-physics slot. Both lists stay sorted by the aspect's `order` field (default 0; ties keep
+// insertion order). Lazy: the first update-bearing aspect installs the dispatch; a project with none
+// starts nothing. No visibility culling yet — every registered aspect ticks regardless of on-screen state.
+type Updatable = Aspect<any, any>
+type PhaseFn = (dt: number) => void
+const earlyUpdaters: Updatable[] = []
+const lateUpdaters: Updatable[] = []
+let dispatchInstalled = false
+
+// A render-synced frame source: given the two phase runners, wire them to the engine and return true;
+// return false if unavailable (→ setLoop fallback). Installed by the 2D layer (see Scene2D) so core
+// never references a concrete engine bridge — that keeps the 2D bridge out of a 3D-only bundle.
+type FrameInstaller = (early: PhaseFn, late: PhaseFn) => boolean
+let frameInstaller: FrameInstaller | undefined
+/** @internal Install a render-synced frame source for aspect update(dt). Called from the 2D layer. */
+export const _installAspectFrames = (fn: FrameInstaller): void => { frameInstaller = fn }
+
+const policyOf = (a: Updatable): { early: boolean; order: number } =>
+  ({ early: a.updateBeforePhysics === true, order: a.order ?? 0 })
+
+// Stable insert by ascending order: place after the last element whose order is <= this one's.
+const addSorted = (list: Updatable[], a: Updatable, order: number): void => {
+  let i = list.length
+  while (i > 0 && list[i - 1].order > order) i--
+  list.splice(i, 0, a)
 }
-const registerUpdater = (a: Aspect<any, any>): void => { updaters.push(a); ensureUpdateLoop() }
-const unregisterUpdater = (a: Aspect<any, any>): void => {
-  const i = updaters.indexOf(a)
-  if (i >= 0) updaters.splice(i, 1)
+
+const runPhase = (list: Updatable[], dt: number): void => {
+  // iterate a snapshot so an update() that attaches/detaches aspects can't corrupt this frame's pass
+  for (const a of list.slice()) a.update?.(dt)
+}
+
+const ensureDispatch = (): void => {
+  if (dispatchInstalled) return
+  dispatchInstalled = true
+  const early: PhaseFn = (dt) => runPhase(earlyUpdaters, dt)
+  const late: PhaseFn = (dt) => runPhase(lateUpdaters, dt)
+  // render-synced source if the engine layer installed one; else one host loop (early then late).
+  if (!(frameInstaller && frameInstaller(early, late))) {
+    setLoop((dt) => { early(dt); late(dt) })
+  }
+}
+
+const registerUpdater = (a: Updatable): void => {
+  const { early, order } = policyOf(a)
+  addSorted(early ? earlyUpdaters : lateUpdaters, a, order)
+  ensureDispatch()
+}
+const unregisterUpdater = (a: Updatable): void => {
+  let i = earlyUpdaters.indexOf(a)
+  if (i >= 0) { earlyUpdaters.splice(i, 1); return }
+  i = lateUpdaters.indexOf(a)
+  if (i >= 0) lateUpdaters.splice(i, 1)
 }
 
 // ---- the host: mixed into every node kind (Node2D, Node) --------------------
@@ -142,10 +184,24 @@ export abstract class Aspect<K extends string, P = Node> {
   declare protected readonly __key__?: K
   onAttach?(): void
   onDetach?(): void
-  /** Called every frame while attached (dt = seconds since the last frame), via a lazy global loop. */
+  /**
+   * Called every frame while attached (dt = seconds since the last frame). Render-synced: runs in the
+   * LATE phase by default — after the physics step + transform sync, right before the frame draws — so
+   * reads of `node.worldPosition` are the final drawn position (cameras/followers have no 1-frame lag).
+   * Set `updateBeforePhysics = true` (an instance field) to run in the EARLY phase (before the step)
+   * instead — for aspects that WRITE velocity/force/kinematic transforms and want the same frame's
+   * step to consume them. Cameras/followers READ, so they stay in the default LATE phase.
+   */
   update?(dt: number): void
-  /** Opt-in: only run update(dt) while the node is on-screen. Lives on the aspect (not the node) so
-   *  aspects on the same node can choose independently. NOOP for now — visibility culling isn't wired
-   *  yet, so every updater ticks regardless; declared so aspects can opt in ahead of it. */
+
+  /** Run update(dt) in the EARLY phase (before the physics step) rather than the default LATE phase.
+   *  An instance field (like `updateWhenVisible`) — set it as a class field: `updateBeforePhysics = true`.
+   *  Use only when you FEED the simulation (velocity/force/kinematic transform). Read once, at attach. */
+  updateBeforePhysics = false
+  /** Tick order within a phase — ascending; default 0, ties keep attach order. Read once, at attach. */
+  order = 0
+
+  /** Opt-in: only run update(dt) while the node is on-screen. NOOP for now — visibility culling isn't
+   *  wired yet, so every updater ticks regardless; declared so aspects can opt in ahead of it. */
   updateWhenVisible = false
 }

package/runtime/sdk/core/signals.ts

@@ -0,0 +1,277 @@
+// Fine-grained reactivity for the retained-mode UI: signal() / computed() / effect() globals plus
+// the element-binding helpers UINode/UIText use for function-valued style props and text.
+//
+// Design notes (the parts that are deliberate, not incidental):
+// - Dependents (effects, computeds) hold their sources STRONGLY; sources hold dependents WEAKLY
+//   (a WeakRef in the subscriber set). An element owns its binding effects, the effect's closure
+//   owns the element — so when user code drops a subtree, the whole element+effect subgraph
+//   becomes unreachable and collects, and the signal prunes the dead WeakRef on its next write.
+//   No unmount hook is needed and re-appending a kept subtree keeps its bindings alive.
+// - Free-standing effect() computations are additionally held in a strong root set (otherwise a
+//   `effect(() => ...)` whose handle the user discards would be GC'd mid-flight); dispose()
+//   releases them. Element bindings are NOT in the root set — the element is their owner.
+// - Writes are batched: a signal write schedules a microtask flush; each dirty effect runs once
+//   per flush. The first run of any effect/binding is synchronous, so element styles hold
+//   concrete values immediately after construction (hosts serialize _style at mount).
+// - QuickJS-safe: promise microtasks (the hosts drain pending jobs), WeakRef with a strong-ref
+//   fallback for engines without it (then stale subscribers just live until the run ends —
+//   every run executes in a fresh JSRuntime anyway).
+
+interface WeakRefLike<T extends object> { deref(): T | undefined }
+
+const WeakRefImpl: new <T extends object>(target: T) => WeakRefLike<T> =
+  typeof WeakRef !== "undefined" ? WeakRef : class StrongRef<T extends object> {
+    private _t: T
+    constructor(target: T) { this._t = target }
+    deref(): T | undefined { return this._t }
+  }
+
+interface Computation {
+  _ref: WeakRefLike<Computation>
+  _deps: Dep[]
+  _disposed: boolean
+  _invalidate(): void
+}
+
+let activeComputation: Computation | null = null
+
+/** Removes `c` from every source it subscribed to on its last run. */
+const cleanupDeps = (c: Computation) => {
+  for (const dep of c._deps) dep._subs.delete(c._ref)
+  c._deps.length = 0
+}
+
+class Dep {
+  _subs = new Set<WeakRefLike<Computation>>()
+
+  _track() {
+    const c = activeComputation
+    if (c === null || this._subs.has(c._ref)) return
+    this._subs.add(c._ref)
+    c._deps.push(this)
+  }
+
+  _notify() {
+    for (const ref of [ ...this._subs ]) {
+      const c = ref.deref()
+      if (c === undefined || c._disposed) {
+        this._subs.delete(ref)   // lazy pruning of collected/disposed subscribers
+      } else {
+        c._invalidate()
+      }
+    }
+  }
+}
+
+// ---- effect scheduling (microtask batch) ----
+
+const queue = new Set<EffectImpl>()
+let flushScheduled = false
+
+const flush = () => {
+  // Effects may write signals, re-filling the queue mid-flush; drain until empty with a guard
+  // against write-loops (effect A invalidating itself / a cycle of effects).
+  let runs = 0
+  while (queue.size > 0) {
+    if (++runs > 10000) {
+      queue.clear()
+      console.warn("signals: effect flush exceeded 10000 runs — possible infinite update loop, remaining effects dropped")
+      break
+    }
+    const first: EffectImpl = queue.values().next().value!
+    queue.delete(first)
+    first._run()
+  }
+  flushScheduled = false
+}
+
+const schedule = (fx: EffectImpl) => {
+  queue.add(fx)
+  if (!flushScheduled) {
+    flushScheduled = true
+    Promise.resolve().then(flush)
+  }
+}
+
+/** Runs every pending effect now instead of waiting for the microtask (test/host hook). */
+export const flushEffects = (): void => {
+  if (queue.size > 0) flush()
+}
+
+class EffectImpl implements Computation {
+  _ref: WeakRefLike<Computation>
+  _deps: Dep[] = []
+  _disposed = false
+  private _fn: () => void
+
+  constructor(fn: () => void) {
+    this._fn = fn
+    this._ref = new WeakRefImpl(this)
+  }
+
+  _run() {
+    if (this._disposed) return
+    cleanupDeps(this)
+    const prev = activeComputation
+    activeComputation = this
+    try {
+      this._fn()
+    } finally {
+      activeComputation = prev
+    }
+  }
+
+  _invalidate() {
+    schedule(this)
+  }
+
+  _dispose() {
+    if (this._disposed) return
+    this._disposed = true
+    cleanupDeps(this)
+    queue.delete(this)
+    rootEffects.delete(this)
+  }
+}
+
+// Free-standing effect() handles the user may never store — kept alive here until disposed.
+const rootEffects = new Set<EffectImpl>()
+
+// ---- public surface ----
+
+export interface Signal<T> {
+  value: T,
+  /** Read without subscribing the current effect/computed. */
+  peek(): T,
+}
+
+export interface Computed<T> {
+  readonly value: T,
+  /** Read without subscribing the current effect/computed (still recomputes if stale). */
+  peek(): T,
+}
+
+class SignalImpl<T> {
+  private _dep = new Dep()
+  private _v: T
+
+  constructor(value: T) {
+    this._v = value
+  }
+
+  get value(): T {
+    this._dep._track()
+    return this._v
+  }
+
+  set value(next: T) {
+    if (Object.is(next, this._v)) return
+    this._v = next
+    this._dep._notify()
+  }
+
+  peek(): T {
+    return this._v
+  }
+}
+
+class ComputedImpl<T> implements Computation {
+  _ref: WeakRefLike<Computation>
+  _deps: Dep[] = []
+  _disposed = false
+  private _dep = new Dep()
+  private _fn: () => T
+  private _stale = true
+  private _v!: T
+
+  constructor(fn: () => T) {
+    this._fn = fn
+    this._ref = new WeakRefImpl(this)
+  }
+
+  get value(): T {
+    this._dep._track()
+    if (this._stale) this._recompute()
+    return this._v
+  }
+
+  peek(): T {
+    if (this._stale) this._recompute()
+    return this._v
+  }
+
+  private _recompute() {
+    cleanupDeps(this)
+    const prev = activeComputation
+    activeComputation = this
+    try {
+      this._v = this._fn()
+      this._stale = false
+    } finally {
+      activeComputation = prev
+    }
+  }
+
+  // Lazy: a dep change only marks the memo stale and passes the wave downstream; the next read
+  // recomputes.
+  _invalidate() {
+    if (this._stale) return
+    this._stale = true
+    this._dep._notify()
+  }
+}
+
+/**
+ * A reactive value. Reading `.value` inside an `effect`/`computed` (or a function-valued style
+ * prop / `UIText` content) subscribes it; writing `.value` re-runs subscribers (batched — once
+ * per microtask).
+ */
+export function signal<T>(initialValue: T): Signal<T>
+export function signal<T = undefined>(): Signal<T | undefined>
+export function signal<T>(initialValue?: T): Signal<T | undefined> {
+  return new SignalImpl(initialValue)
+}
+
+/** A lazily-cached derived value: recomputes on read after any of its dependencies changed. */
+export function computed<T>(fn: () => T): Computed<T> {
+  return new ComputedImpl(fn)
+}
+
+/**
+ * Runs `fn` now and again whenever any signal/computed it read changes (batched per microtask).
+ * Returns a dispose function; an undisposed effect lives for the rest of the app run.
+ */
+export function effect(fn: () => void): () => void {
+  const fx = new EffectImpl(fn)
+  rootEffects.add(fx)
+  fx._run()
+  return () => fx._dispose()
+}
+
+// ---- element bindings (internal — used by UINode/UIText for function-valued props) ----
+
+/** The shape UINode's Element exposes for binding ownership. */
+export interface BindingHost {
+  /** @internal */ _fx?: Map<string, EffectImpl>
+}
+
+/**
+ * @internal Creates (or replaces) the reactive binding stored under `key` on the element. The
+ * effect is owned by the element (strong ref in `_fx`), NOT by the root set — discard the element
+ * and the binding collects with it. Runs synchronously once.
+ */
+export function createBinding(el: BindingHost, key: string, run: () => void): void {
+  const map = el._fx ?? (el._fx = new Map())
+  map.get(key)?._dispose()
+  const fx = new EffectImpl(run)
+  map.set(key, fx)
+  fx._run()
+}
+
+/** @internal Disposes the binding stored under `key`, if any (static value overriding a binding). */
+export function disposeBinding(el: BindingHost, key: string): void {
+  const fx = el._fx?.get(key)
+  if (fx === undefined) return
+  fx._dispose()
+  el._fx!.delete(key)
+}

package/runtime/sdk/g2/CharacterController2D.ts

@@ -3,7 +3,8 @@
 // wall/floor collision response; a short downward ray reports `grounded`.
 //
 //   const hero = new Sprite({ texture, anchor: [0.5, 1] })
-//     .aspect(Physics2D, { motion: 'dynamic', fixedRotation: true, shape: { type: 'capsule', from:[0,6], to:[0,26], radius:6 } })
+//     .aspect(Shape2D, { capsule: { from: [0, 6], to: [0, 26], radius: 6 } })
+//     .aspect(Physics2D, { motion: 'dynamic', fixedRotation: true })
 //     .aspect(CharacterController2D, { speed: 200, jumpSpeed: 520 })
 //   Input.on('left',  d => hero.controller.move(d ? -1 : 0))
 //   Input.on('jump',  () => hero.controller.jump())
@@ -15,7 +16,7 @@
 import { Aspect } from "../core/Aspect"
 import { Vec2 } from "../math/vec"
 import { Physics2D } from "./Physics2D"
-import { Shape } from "./Shape"
+import { Shape2D } from "./Shape2D"
 import type { Node2D } from "./Node2D"
 
 export class CharacterController2D extends Aspect<"controller", Node2D> {
@@ -44,8 +45,8 @@ export class CharacterController2D extends Aspect<"controller", Node2D> {
   private get phys(): Physics2D | undefined { return this.node.get(Physics2D) }
 
   onAttach(): void {
-    // Ensure a Shape (auto box from the sprite) + a dynamic, fixed-rotation body if not already set up.
-    if (!this.node.has(Shape)) this.node.aspect(Shape, {})
+    // Ensure a Shape2D (auto box from the sprite) + a dynamic, fixed-rotation body if not already set up.
+    if (!this.node.has(Shape2D)) this.node.aspect(Shape2D, {})
     if (!this.node.has(Physics2D)) this.node.aspect(Physics2D, { motion: "dynamic", fixedRotation: true })
   }
 

package/runtime/sdk/g2/Node2D.ts

@@ -7,7 +7,7 @@
 // under physics without any per-frame bookkeeping.
 //
 // Empty Node2Ds are useful as: grouping parents, world-space markers/spawn points, and physics /
-// trigger objects — attach a Shape (geometry) plus a Physics2D (rigid body) or Trigger (sensor).
+// trigger objects — attach a Shape2D (geometry) plus a Physics2D (rigid body) or Trigger2D (sensor).
 
 import { AspectHost } from "../core/Aspect"
 import { Registry } from "../core/registry"

package/runtime/sdk/g2/Physics2D.ts

@@ -1,9 +1,9 @@
 // A rigid body, as an aspect on a Node2D, backed by Box2D v3 in creator-2d. Mirrors the 3D Physics
-// aspect. Requires a Shape aspect on the same node (its geometry becomes the body's solid fixture).
+// aspect. Requires a Shape2D aspect on the same node (its geometry becomes the body's solid fixture).
 //
 //   Physics2D.configure({ gravity: [0, -980] })          // once, before creating bodies
-//   ground.aspect(Shape, { segment: { from: [-500,0], to: [500,0] } }).aspect(Physics2D, { motion: 'static' })
-//   hero.aspect(Shape, { box: [12, 20] }).aspect(Physics2D, { motion: 'dynamic', fixedRotation: true })
+//   ground.aspect(Shape2D, { segment: { from: [-500,0], to: [500,0] } }).aspect(Physics2D, { motion: 'static' })
+//   hero.aspect(Shape2D, { box: [12, 20] }).aspect(Physics2D, { motion: 'dynamic', fixedRotation: true })
 //   hero.physics.applyImpulse([0, 400])                   // jump
 //   hero.addEventListener('enter', other => …)            // contact / sensor overlap began
 //
@@ -15,7 +15,7 @@
 import { Aspect } from "../core/Aspect"
 import { Vec2, cx, cy, type Vec2Like } from "../math/vec"
 import { node2dRegistry, type Node2D } from "./Node2D"
-import { Shape } from "./Shape"
+import { Shape2D } from "./Shape2D"
 
 export type MotionType = "static" | "kinematic" | "dynamic"
 const MOTION: Record<MotionType, number> = { static: 0, kinematic: 1, dynamic: 2 }
@@ -50,20 +50,20 @@ export class Physics2D extends Aspect<"physics", Node2D> {
   restitution = 0
   /** Lock rotation (essential for platformer characters). */
   fixedRotation = false
-  gravityScale = 1
   /** Continuous collision for fast-moving bodies (projectiles). */
   bullet = false
 
-  private _h = 0   // native body handle (0 = none / no physics support)
+  private _gravityScale = 1
+  private _h = 0   // native body id (0 = none / no physics support)
 
-  /** Native body handle. 0 until attached, or if the build has no physics support. */
-  get handle(): number { return this._h }
+  /** Native physics body id. 0 until attached, or if the build has no physics support. Mirrors 3D `Physics.id`. */
+  get id(): number { return this._h }
 
   onAttach(): void {
     if (!_creator2d.physicsHasSupport || !_creator2d.physicsHasSupport()) return
-    const shape = this.node.get(Shape)
+    const shape = this.node.get(Shape2D)
     if (!shape) {
-      throw new Error("Physics2D requires a Shape aspect — add it first: node.aspect(Shape, {…}).aspect(Physics2D, {…})")
+      throw new Error("Physics2D requires a Shape2D aspect — add it first: node.aspect(Shape2D, {…}).aspect(Physics2D, {…})")
     }
     this._h = _creator2d.physicsCreateBody(this.node.id, MOTION[this.motion])
     if (!this._h) return
@@ -72,7 +72,7 @@ export class Physics2D extends Aspect<"physics", Node2D> {
     // cache from native on read. Static bodies never move, so they keep the free cache.
     if (this.motion !== "static") this.node._physicsDriven = true
     if (this.fixedRotation) _creator2d.physicsSetFixedRotation(this._h, true)
-    if (this.gravityScale !== 1) _creator2d.physicsSetGravityScale(this._h, this.gravityScale)
+    if (this._gravityScale !== 1) _creator2d.physicsSetGravityScale(this._h, this._gravityScale)
     if (this.bullet) _creator2d.physicsSetBullet(this._h, true)
   }
 
@@ -91,7 +91,10 @@ export class Physics2D extends Aspect<"physics", Node2D> {
   /** Angular velocity in degrees/second. */
   set angularVelocity(degPerSec: number) { if (this._h) _creator2d.physicsSetAngularVelocity(this._h, degPerSec) }
 
-  set gravityFactor(scale: number) { this.gravityScale = scale; if (this._h) _creator2d.physicsSetGravityScale(this._h, scale) }
+  /** Per-body gravity multiplier: 1 = full world gravity, 0 = floats, <0 = repelled. Set at attach
+   *  time (as an option) or live. */
+  get gravityScale(): number { return this._gravityScale }
+  set gravityScale(scale: number) { this._gravityScale = scale; if (this._h) _creator2d.physicsSetGravityScale(this._h, scale) }
   set linearDamping(d: number) { if (this._h) _creator2d.physicsSetLinearDamping(this._h, d) }
   set enabled(v: boolean) { if (this._h) _creator2d.physicsSetEnabled(this._h, v) }
 
@@ -112,6 +115,13 @@ export class Physics2D extends Aspect<"physics", Node2D> {
   /** Whether this build has physics support (CREATOR_2D_PHYSICS). */
   static get supported(): boolean { return !!_creator2d.physicsHasSupport && _creator2d.physicsHasSupport() }
 
+  /** Render interpolation of body transforms between the fixed 60 Hz steps (global; default on). Turn
+   *  off to save per-frame transform writes when you have many moving bodies / don't need >60 Hz
+   *  smoothness — bodies then advance in discrete steps. */
+  private static _interpolation = true
+  static get interpolation(): boolean { return Physics2D._interpolation }
+  static set interpolation(on: boolean) { Physics2D._interpolation = on; _creator2d.setInterpolation(on) }
+
   /** Closest body hit by the segment from→to, or null. `node` resolves the hit entity. */
   static raycast(from: Vec2Like, to: Vec2Like): RayHit | null {
     const o = _creator2d.physicsRaycastClosest(cx(from), cy(from), cx(to), cy(to))