lecodes-cli 0.3.0 → 0.5.0

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))

package/runtime/sdk/g2/Scene2D.ts

@@ -28,6 +28,12 @@ const installRenderSyncedFrames = (): void => {
 export type Scene2DOptions = {
   /** Background color — '#10131a', 0x10131a, or [r,g,b]/[r,g,b,a] in 0..1. */
   background?: ColorInput
+  /** Texture sampling for the 2D renderer: `'nearest'` (default — crisp pixel art) or `'linear'`
+   *  (smooth — for hi-res / non-pixel-art assets). Applied when the scene is opened, so switching
+   *  scenes restores the active scene's choice. NOTE: this is a GLOBAL renderer setting (one sampler
+   *  for ALL textures, not per-texture), so the currently-open scene's filter wins. Omit to leave the
+   *  current setting (engine default is nearest). */
+  filter?: 'nearest' | 'linear'
 }
 
 /** Returned by scene2d.layer(n); chain .ySort() to enable top-down depth sorting for that layer. */
@@ -54,10 +60,14 @@ export class Scene2D {
   readonly _clickListeners: Array<(ev: ClickEvent<Node2D | null>) => void> = []
   readonly _touchStartListeners: Array<(ev: TouchStartEvent<Node2D | null>) => void> = []
 
+  /** Texture filter to (re)assert on open(); the sampler is global, so each scene reclaims it. */
+  private readonly _filter?: 'nearest' | 'linear'
+
   constructor(options: Scene2DOptions = {}) {
     installRenderSyncedFrames()
     this.id = _creator2d.createScene()
     this.camera = new Camera2D(this.id)
+    this._filter = options.filter
     if (options.background !== undefined) this.background = options.background
   }
 
@@ -103,6 +113,8 @@ export class Scene2D {
 
   /** Make this the active scene (brings up the 2D engine on the canvas; closes any other). */
   open(): this {
+    // Reassert this scene's texture filter (the sampler is global — see Scene2DOptions.filter).
+    if (this._filter !== undefined) _creator2d.setDefaultFilter(this._filter === 'linear')
     _creator2d.openScene(this.id)
     Scene2D._active = this
     return this

package/runtime/sdk/g2/{Shape.ts → Shape2D.ts}

@@ -1,19 +1,19 @@
-// A collider shape, as an aspect on a Node2D. PURE GEOMETRY — attaching a Shape does not by itself
-// make the node rigid or a sensor; pair it with a Physics2D (rigid body) or a Trigger (sensor), both
-// of which require a Shape and turn its geometry into a Box2D fixture. The shape is also what pointer
-// picking hits, so a node is clickable once it has a Shape + Physics2D/Trigger (a body to query).
+// A collider shape, as an aspect on a Node2D. PURE GEOMETRY — attaching a Shape2D does not by itself
+// make the node rigid or a sensor; pair it with a Physics2D (rigid body) or a Trigger2D (sensor), both
+// of which require a Shape2D and turn its geometry into a Box2D fixture. The shape is also what pointer
+// picking hits, so a node is clickable once it has a Shape2D + Physics2D/Trigger2D (a body to query).
 //
-//   wall.aspect(Shape, { box: [200, 16] }).aspect(Physics2D, { motion: 'static' })
-//   goal.aspect(Shape, { circle: 20 }).aspect(Trigger)
-//   hero.aspect(Shape, { capsule: { from: [0, 6], to: [0, 26], radius: 6 } }).aspect(Physics2D, { motion: 'dynamic' })
+//   wall.aspect(Shape2D, { box: [200, 16] }).aspect(Physics2D, { motion: 'static' })
+//   goal.aspect(Shape2D, { circle: 20 }).aspect(Trigger2D)
+//   hero.aspect(Shape2D, { capsule: { from: [0, 6], to: [0, 26], radius: 6 } }).aspect(Physics2D, { motion: 'dynamic' })
 //
-// With no geometry set, Shape derives a box from the node's sprite size ("auto").
+// With no geometry set, Shape2D derives a box from the node's sprite size ("auto").
 
 import { Aspect } from "../core/Aspect"
 import { Vec2, cx, cy, type Vec2Like } from "../math/vec"
 import type { Node2D } from "./Node2D"
 
-export class Shape extends Aspect<"shape", Node2D> {
+export class Shape2D extends Aspect<"shape", Node2D> {
   static readonly aspect = "shape"
 
   /** Box half-extents [hw, hh] (world units). */
@@ -30,7 +30,7 @@ export class Shape extends Aspect<"shape", Node2D> {
   offset?: Vec2Like
 
   /**
-   * @internal — add this geometry as a fixture to `handle` (a body created by Physics2D/Trigger).
+   * @internal — add this geometry as a fixture to `handle` (a body created by Physics2D/Trigger2D).
    * `sensor` selects a sensor (trigger) vs solid fixture; density/friction/restitution are the
    * material (ignored for sensors / segments only use friction+restitution).
    */

package/runtime/sdk/g2/Sprite.ts

@@ -52,11 +52,16 @@ export class Sprite extends Node2D {
     const tex = isCanvas(t) ? t.texture() : t   // a Canvas bakes to a texture on assign
     this._texture = tex
     if (!tex) return
-    _creator2d.setSprite(this.id, tex.id) // native resets UV + size to the full texture
+    _creator2d.setSprite(this.id, tex.id) // native resets UV + size to the full (pixel) texture
+    // A Canvas is authored in LOGICAL units but baked at logical × pixelRatio, so default the sprite's
+    // WORLD size to the canvas's LOGICAL size — pixelRatio then only affects crispness, not on-screen
+    // size. (A plain texture keeps the native default: the texture's pixel dimensions.)
+    if (!this._size && isCanvas(t)) this._size = new Vec2(t.width, t.height)
     if (this._size) _creator2d.setSpriteSize(this.id, this._size.x, this._size.y)
   }
 
-  /** Current world size: explicit override if set, else the texture's pixel dimensions. */
+  /** Current world size: explicit override if set, else the texture's pixel dimensions (a Canvas-backed
+   *  sprite defaults to the canvas's LOGICAL size, so pixelRatio is crispness only, not size). */
   get size(): Vec2 { return this._size ?? (this._texture ? new Vec2(this._texture.width, this._texture.height) : new Vec2(0, 0)) }
   set size(v: Vec2Like) { this._size = new Vec2(v); _creator2d.setSpriteSize(this.id, this._size.x, this._size.y) }
 

package/runtime/sdk/g2/Texture2D.ts

@@ -3,7 +3,7 @@
 
 // Internal SDK code imports injected globals explicitly (the bare-global inject is only for USER
 // code; here `fetch` would otherwise resolve to the node/bun ambient one).
-import { fetch, type FetchResponse } from "../runtime/fetch"
+import { fetch, type FetchResponse, type File } from "../runtime/fetch"
 
 export class Texture2D {
   /** Native texture handle. */
@@ -25,7 +25,9 @@ export class Texture2D {
     return new Texture2D(texId, Math.round(canvas.width * canvas.pixelRatio), Math.round(canvas.height * canvas.pixelRatio))
   }
 
-  static load(source: string | FetchResponse): Promise<Texture2D> {
+  // Accepts a URL, an already-fetched response, or a File (e.g. from Canvas.toFile() / openFilePicker) —
+  // anything backed by a host buffer. The buffer's encoded bytes are decoded + uploaded by the engine.
+  static load(source: string | FetchResponse | File): Promise<Texture2D> {
     if (typeof source === "string") {
       return fetch(source, { useOnce: true }).then((resp) => {
         if (resp.status >= 400) {

package/runtime/sdk/g2/{Trigger.ts → Trigger2D.ts}

@@ -1,10 +1,10 @@
-// A trigger zone, as an aspect on a Node2D. Requires a Shape (its geometry); creates a static SENSOR
+// A trigger zone, as an aspect on a Node2D. Requires a Shape2D (its geometry); creates a static SENSOR
 // body from it, so a physics body overlapping the zone fires the node's 'enter' / 'exit' events
 // instead of colliding. A trigger does not block movement.
 //
 //   const goal = new Node2D({ ... })
-//     .aspect(Shape, { box: [32, 64] })
-//     .aspect(Trigger)
+//     .aspect(Shape2D, { box: [32, 64] })
+//     .aspect(Trigger2D)
 //   goal.addEventListener('enter', other => win(other))
 //   goal.addEventListener('exit',  other => ...)
 //
@@ -13,21 +13,21 @@
 import { Aspect } from "../core/Aspect"
 import { cx, cy, type Vec2Like } from "../math/vec"
 import { ensurePhysicsEvents } from "./loop"
-import { Shape } from "./Shape"
+import { Shape2D } from "./Shape2D"
 import type { Node2D } from "./Node2D"
 
-export class Trigger extends Aspect<"trigger", Node2D> {
+export class Trigger2D extends Aspect<"trigger", Node2D> {
   static readonly aspect = "trigger"
 
   private _h = 0
-  /** Native body handle (0 if no physics support). */
-  get handle(): number { return this._h }
+  /** Native physics body id (0 if no physics support). Mirrors 3D `Trigger.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("Trigger requires a Shape aspect — add it first: node.aspect(Shape, {…}).aspect(Trigger)")
+      throw new Error("Trigger2D requires a Shape2D aspect — add it first: node.aspect(Shape2D, {…}).aspect(Trigger2D)")
     }
     this._h = _creator2d.physicsCreateBody(this.node.id, 0 /* static */)
     if (!this._h) return

package/runtime/sdk/gl/CharacterController.ts

@@ -0,0 +1,101 @@
+// A character controller, as an aspect on a 3D Node, backed by Jolt's CharacterVirtual — a kinematic
+// collide-and-slide controller (NOT a rigid body: no bouncing/tipping, crisp control, built-in stair
+// stepping + slope handling). Requires a Shape (a capsule is recommended) and does NOT use Physics.
+//
+//   const hero = new Mesh(capsuleGeometry(), material)
+//     .aspect(Shape, { capsule: { halfHeight: 0.6, radius: 0.3 } })
+//     .aspect(CharacterController, { speed: 6, jumpSpeed: 8 })
+//   Input.on('move', (x, z) => hero.controller.move(x, z))
+//   Input.on('jump', () => hero.controller.jump())
+//
+// You drive horizontal intent + jump; the controller integrates gravity and Jolt handles collision
+// against the world. `grounded` reports whether it's on walkable ground. It runs in the EARLY update
+// phase (feeds this frame's step). Note: it collides with solid bodies but PASSES THROUGH triggers,
+// and (v1) is not itself detected by triggers and isn't pointer-pickable while active.
+
+import { Aspect } from "../core/Aspect"
+import { Vec3 } from "../math/vec"
+import { Shape } from "./Shape"
+import type { Node } from "./Node"
+
+const clamp1 = (v: number): number => (v < -1 ? -1 : v > 1 ? 1 : v)
+
+export class CharacterController extends Aspect<"controller", Node> {
+  static readonly aspect = "controller"
+
+  /** Horizontal move speed (world units/s). */
+  speed = 5
+  /** Jump take-off speed (world units/s). */
+  jumpSpeed = 7
+  /** Character-tuned gravity (world units/s²), separate from the world gravity — usually stronger for
+   *  snappier feel. Applied to the vertical velocity each frame. */
+  gravity = -20
+  /** Max ground slope (degrees) the character treats as walkable. Set before attach. */
+  maxSlope = 45
+
+  updateBeforePhysics = true // EARLY phase — set velocity so THIS frame's step consumes it
+
+  private _charId = 0
+  private _mx = 0
+  private _mz = 0
+  private _jumpQueued = false
+  private _vy = 0
+
+  onAttach(): void {
+    if (!_creator.physicsHasSupport || !_creator.physicsHasSupport()) return
+    const shape = this.node.get(Shape)
+    if (!shape) {
+      throw new Error("CharacterController requires a Shape aspect (a capsule is recommended) — add it first: node.aspect(Shape, { capsule: {…} }).aspect(CharacterController)")
+    }
+    const shapeId = shape._claim() // the character owns the shape; it is not a rigid body
+    this._charId = _creator.characterCreate(this.node.id, shapeId, this.maxSlope)
+  }
+
+  onDetach(): void {
+    if (this._charId) { _creator.characterDestroy(this._charId); this._charId = 0 }
+    this.node.get(Shape)?._recreatePickBody()
+  }
+
+  /** Native character id (0 until attached / no physics support). */
+  get id(): number { return this._charId }
+
+  /** Horizontal move intent; each component in [-1, 1] (e.g. from input). Sticky — set 0 to stop. */
+  move(x: number, z: number): void { this._mx = clamp1(x); this._mz = clamp1(z) }
+
+  /** Queue a jump; consumed on the next frame if grounded. */
+  jump(): void { this._jumpQueued = true }
+
+  /** True while standing on walkable ground (OnGround). */
+  get grounded(): boolean {
+    return this._charId ? _creator.characterGetGroundState(this._charId) === 0 : false
+  }
+
+  /** Ground state: 0 on-ground, 1 on-steep-slope, 2 touching-but-unsupported, 3 in-air. */
+  get groundState(): number {
+    return this._charId ? _creator.characterGetGroundState(this._charId) : 3
+  }
+
+  /** Current velocity (world units/s, fresh Vec3). */
+  get velocity(): Vec3 {
+    const o = new Float32Array(3)
+    if (this._charId) _creator.characterGetVelocity(this._charId, o)
+    return new Vec3(o[0], o[1], o[2])
+  }
+
+  /** Teleport to a world position (clears vertical velocity). */
+  teleport(x: number, y: number, z: number): this {
+    if (this._charId) _creator.characterSetPosition(this._charId, x, y, z)
+    this._vy = 0
+    return this
+  }
+
+  update(dt: number): void {
+    if (!this._charId) return
+    const grounded = _creator.characterGetGroundState(this._charId) === 0
+    if (grounded && this._vy < 0) this._vy = 0          // landed
+    if (this._jumpQueued && grounded) this._vy = this.jumpSpeed
+    this._jumpQueued = false
+    this._vy += this.gravity * dt                        // integrate gravity (CharacterVirtual is kinematic)
+    _creator.characterSetVelocity(this._charId, this._mx * this.speed, this._vy, this._mz * this.speed)
+  }
+}