lecodes-cli 0.1.7 → 0.3.0

package/runtime/sdk/core/Aspect.ts

@@ -0,0 +1,207 @@
+// The Aspect system: attachable capabilities (animation, collider, physics, and user behaviors)
+// that hang off a node WITHOUT bloating the node class. Composition with the terseness of methods.
+//
+//   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
+//   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
+//
+// A user aspect declares its name + target node in the generic and reads `this.node`:
+//   class Health extends Aspect<'health', Sprite> { hp = 100; hurt(n: number) { this.hp -= n } }
+//   sprite.aspect(Health, { hp: 80 }).health.hurt(10)
+//
+// The accessor name lives in the generic (Aspect<'name', Node>). The `chisel` bundler extracts it at
+// compile time and injects the runtime `static aspect` on user aspects + the virtual type accessor;
+// the SDK's own built-in aspects declare `static readonly aspect` directly (see SpriteAnimation etc.).
+
+import { Emitter, type EventMap } from "./events"
+import type { Node } from "../gl/Node"
+
+// ---- type helpers -----------------------------------------------------------
+/** The class object of an aspect — accepted even when its constructor is protected/abstract. */
+export type AspectCtor<A extends Aspect<any, any>> = abstract new () => A
+/** The accessor name carried in the aspect's generic. */
+export type KeyOf<A> = A extends Aspect<infer K, any> ? K : never
+/** The node kind an aspect targets. */
+export type TargetOf<A> = A extends Aspect<any, infer P> ? P : never
+/** `{ name: Aspect }` — the field an aspect contributes to its node. */
+export type FieldOf<A extends Aspect<any, any>> = { [P in KeyOf<A>]: A }
+
+type UnionToIntersection<U> =
+  (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never
+
+/**
+ * A variable typed as a node KNOWN to carry the given aspect(s). Union, not a tuple — reads as
+ * English and mirrors the runtime guard `node.has(Health)`:
+ *   let boss: With<Sprite, Health | Physics>
+ */
+export type With<N, A extends Aspect<any, any>> =
+  N & UnionToIntersection<A extends any ? FieldOf<A> : never>
+
+// ---- 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 && policyOf(list[i - 1]).order > order) i--
+  list.splice(i, 0, a)
+}
+
+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) --------------------
+/**
+ * Base for anything that can carry aspects. Extends Emitter, so node kinds get events too. Provides
+ * the four verbs; the named accessor (node.physics, node.health, …) is set as an own property at
+ * attach time, keyed by the aspect class's runtime `aspect` name.
+ */
+export abstract class AspectHost<E extends EventMap = EventMap> extends Emitter<E> {
+  /** @internal class → instance, the authoritative store (named accessors mirror this). */
+  readonly _aspects = new Map<Function, Aspect<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. */
+  aspect<Self extends TargetOf<A>, A extends Aspect<any, any>>(
+    this: Self,
+    ctor: AspectCtor<A>,
+    opts?: Partial<A>,
+  ): Self & FieldOf<A> {
+    const host = this as unknown as AspectHost
+    let inst = host._aspects.get(ctor) as A | undefined
+    const fresh = inst === undefined
+    if (!inst) {
+      inst = new (ctor as unknown as new () => A)()
+      ;(inst as { node: unknown }).node = this
+      host._aspects.set(ctor, inst)
+      const name = (ctor as { aspect?: string }).aspect
+      if (name) (host as unknown as Record<string, unknown>)[name] = inst
+    }
+    if (opts) Object.assign(inst, opts)
+    if (fresh) {
+      inst.onAttach?.()
+      if (typeof inst.update === "function") registerUpdater(inst)
+    }
+    return this as Self & FieldOf<A>
+  }
+
+  /** Safe access — undefined if the aspect isn't attached. */
+  get<A extends Aspect<any, any>>(ctor: AspectCtor<A>): A | undefined {
+    return this._aspects.get(ctor) as A | undefined
+  }
+
+  /** Existence check AND type guard: inside `if (node.has(Physics))`, `node.physics` is present. */
+  has<A extends Aspect<any, any>>(ctor: AspectCtor<A>): this is this & FieldOf<A> {
+    return this._aspects.has(ctor)
+  }
+
+  /** Detach an aspect (runs its onDetach). Named `removeAspect` so it never collides with the
+   *  child-management `add`/`remove` semantics some node kinds expose. */
+  removeAspect<A extends Aspect<any, any>>(ctor: AspectCtor<A>): this {
+    const inst = this._aspects.get(ctor)
+    if (inst) {
+      inst.onDetach?.()
+      unregisterUpdater(inst)
+      this._aspects.delete(ctor)
+      const name = (ctor as { aspect?: string }).aspect
+      if (name) delete (this as unknown as Record<string, unknown>)[name]
+    }
+    return this
+  }
+}
+
+// ---- the aspect base --------------------------------------------------------
+/**
+ * Base for everything you attach. `K` = accessor name (extracted by chisel for the runtime). `P` =
+ * the target node kind: `this.node` is typed to it, AND attaching to a wrong node is a compile error.
+ * Initialize in `onAttach` (the node is set by then) — not a constructor; aspects are created by the
+ * engine via `node.aspect()`, never `new`.
+ */
+export abstract class Aspect<K extends string, P = Node> {
+  // NOTE: P has no `extends AspectHost` constraint on purpose — Emitter<E>'s generic
+  // addEventListener makes a specific-event node (AspectHost<NodeEvents>) not assignable to
+  // AspectHost<any>, which would reject every real node. P only types `this.node`; target
+  // enforcement happens in aspect() via `this: Self extends TargetOf<A>`. Defaults to Node
+  // (3D is the default engine) — a 2D aspect declares its own P, e.g. Aspect<'x', Sprite>.
+  /** The node this aspect is attached to (set at attach time). */
+  readonly node!: P
+  /** @internal phantom — lets the type system recover the accessor name `K`. Never read at runtime. */
+  declare protected readonly __key__?: K
+  onAttach?(): void
+  onDetach?(): void
+  /**
+   * 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
+
+  /** 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/g2/Camera2D.ts

@@ -1,16 +1,8 @@
-// Orthographic camera for a Scene2D. Position/zoom/rotation live natively; `follow` adds a
-// render-synced per-frame update that tracks a node.
+// Orthographic camera for a Scene2D. Position / zoom / rotation live natively. To make the camera
+// track a node, attach a small update(dt) aspect that eases camera.position toward the node — there's
+// no built-in follow() (and so nothing to dispose).
 
 import { Vec2, cx, cy, type Vec2Like } from "../math/vec"
-import type { Node2D } from "./Node2D"
-import { offUpdate, onUpdate } from "./loop"
-
-export type FollowOptions = {
-  /** World-space offset added to the target's position. */
-  offset?: Vec2Like
-  /** 0 = snap (default). >0 = exponential smoothing time constant in seconds (smaller = snappier). */
-  smooth?: number
-}
 
 export class Camera2D {
   private _x = 0
@@ -18,10 +10,6 @@ export class Camera2D {
   private _zoom = 1
   private _rotation = 0
 
-  private _followTarget: Node2D | null = null
-  private _followOpts: FollowOptions = {}
-  private _followCb: ((dt: number) => void) | null = null
-
   private readonly sceneId: number
   constructor(sceneId: number) { this.sceneId = sceneId }
 
@@ -42,32 +30,4 @@ export class Camera2D {
     const o = _creator2d.cameraWorldToScreen(this.sceneId, worldX, worldY)
     return new Vec2(o[0], o[1])
   }
-
-  /** Track a node each frame (snaps by default; pass `smooth` for eased follow). */
-  follow(node: Node2D, options: FollowOptions = {}): this {
-    this._followTarget = node
-    this._followOpts = options
-    if (this._followCb) return this
-    this._followCb = (dt: number) => {
-      const t = this._followTarget
-      if (!t) return
-      const [ ox, oy ] = this._followOpts.offset ?? [ 0, 0 ]
-      const tx = t.x + ox
-      const ty = t.y + oy
-      const s = this._followOpts.smooth ?? 0
-      if (s > 0) {
-        const k = 1 - Math.exp(-dt / s)
-        this.position = [ this._x + (tx - this._x) * k, this._y + (ty - this._y) * k ]
-      } else {
-        this.position = [ tx, ty ]
-      }
-    }
-    onUpdate(this._followCb)
-    return this
-  }
-
-  unfollow(): void {
-    this._followTarget = null
-    if (this._followCb) { offUpdate(this._followCb); this._followCb = null }
-  }
 }

package/runtime/sdk/g2/CharacterController2D.ts

@@ -0,0 +1,75 @@
+// A platformer-friendly character controller, as an aspect on a Node2D. Built on a fixed-rotation
+// dynamic Physics2D body: you drive horizontal intent + jump, and Box2D handles gravity, falling, and
+// 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(CharacterController2D, { speed: 200, jumpSpeed: 520 })
+//   Input.on('left',  d => hero.controller.move(d ? -1 : 0))
+//   Input.on('jump',  () => hero.controller.jump())
+//
+// Velocity-control (set velocity each frame) is the standard, robust approach for platformers and
+// reuses the physics solver. For pixel-tight movement without any solver bounce/seam quirks, a
+// kinematic move-and-slide controller can be added later (see creator-2d PLAN.md, Phase G).
+
+import { Aspect } from "../core/Aspect"
+import { Vec2 } from "../math/vec"
+import { Physics2D } from "./Physics2D"
+import { Shape } from "./Shape"
+import type { Node2D } from "./Node2D"
+
+export class CharacterController2D extends Aspect<"controller", Node2D> {
+  static readonly aspect = "controller"
+
+  /** Horizontal move speed (world units/s). */
+  speed = 200
+  /** Jump take-off speed (world units/s). */
+  jumpSpeed = 500
+  /** Extra probe distance below the body's feet used for the grounded check (world units). */
+  groundProbe = 6
+  /** Distance from the node origin down to the feet. Defaults to half the sprite height. */
+  footOffset?: number
+
+  private _moveX = 0
+  private _jumpQueued = false
+  private _grounded = false
+
+  /** Horizontal intent in [-1, 1] (e.g. from input). Sticky — set 0 to stop. Applied next frame. */
+  move(dir: number): void { this._moveX = dir < -1 ? -1 : dir > 1 ? 1 : dir }
+  /** Queue a jump; consumed on the next frame if grounded. */
+  jump(): void { this._jumpQueued = true }
+  /** True while standing on something (updated each frame). */
+  get grounded(): boolean { return this._grounded }
+
+  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, {})
+    if (!this.node.has(Physics2D)) this.node.aspect(Physics2D, { motion: "dynamic", fixedRotation: true })
+  }
+
+  update(_dt: number): void {
+    const phys = this.phys
+    if (!phys) return
+
+    // Grounded probe: a short ray straight down from the feet. The ray originates inside the body,
+    // so Box2D won't report the body's own shape; we exclude self defensively too.
+    const pos = this.node.worldPosition
+    const foot = this.footOffset ?? this._spriteHalfHeight()
+    const hit = Physics2D.raycast([pos.x, pos.y - foot * 0.5], [pos.x, pos.y - foot - this.groundProbe])
+    this._grounded = !!hit && hit.node !== this.node
+
+    let vy = phys.velocity.y
+    if (this._jumpQueued && this._grounded) { vy = this.jumpSpeed; this._grounded = false }
+    this._jumpQueued = false
+
+    // Drive horizontal velocity directly; let the sim own vertical (gravity / jump / landing).
+    phys.velocity = new Vec2(this._moveX * this.speed, vy)
+  }
+
+  private _spriteHalfHeight(): number {
+    const size = (this.node as { size?: Vec2 }).size
+    return size ? size.y * 0.5 : 8
+  }
+}

package/runtime/sdk/g2/Node2D.ts

@@ -1,13 +1,19 @@
 // Base 2D scene node — an empty transform. Sprite and Tilemap extend it, so every node operation
 // (position, layer, visibility, events) works on them. Native (creator-2d) owns the authoritative
-// transform; JS is the sole writer (no 2D physics yet) so a local cache makes reads free.
+// transform. JS caches it for free reads (JS is normally the sole writer); the exception is a node
+// driven by a dynamic/kinematic Physics2D body — there the native physics step also writes the
+// transform, so such nodes are flagged `_physicsDriven` and their transform getters sync the cache
+// from native first (lazy: only on read, only for moving bodies). So node.position stays correct
+// under physics without any per-frame bookkeeping.
 //
-// Empty Node2Ds are useful as: grouping parents, world-space markers/spawn points, and trigger /
-// logic objects you attach a .collider() to.
+// 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).
 
-import { Emitter } from "../core/events"
+import { AspectHost } from "../core/Aspect"
 import { Registry } from "../core/registry"
 import { Vec2, cx, cy, type Vec2Like } from "../math/vec"
+import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
+import { ensurePointerEvents } from "./touch"
 
 // re-exported so existing `import { Vec2 } from "./Node2D"` sites keep working; the canonical home is math/.
 export { Vec2, type Vec2Like }
@@ -17,24 +23,19 @@ export type Node2DEvents = {
   loopReached: (clip: string) => void
   /** A non-looping animation clip finished. */
   completed: (clip: string) => void
-  /** A collider overlap began / ended (deferred — native 2D triggers are not built yet). */
+  /** A physics contact / sensor overlap began / ended (the other node). */
   enter: (other: Node2D) => void
   exit: (other: Node2D) => void
+  /** Pointer up over this node's Physics2D shape (a tap/click). */
+  click: (ev: ClickEvent<Node2D | null>) => void
+  /** Pointer down on this node's Physics2D shape. Call ev.track(...) to capture the drag. */
+  touchstart: (ev: TouchStartEvent<Node2D | null>) => void
 }
 
 /** id → Node2D, so host callbacks (animation events) route back to the owning JS object. */
 export const node2dRegistry = new Registry<Node2D>()
 
-export type ColliderOptions = {
-  /** Box half-extents (world units). Defaults to the sprite size when omitted. */
-  size?: Vec2Like
-  /** Center offset. */
-  offset?: Vec2Like
-  /** Report overlaps via 'enter'/'exit' instead of blocking (always true for now). */
-  trigger?: boolean
-}
-
-export class Node2D extends Emitter<Node2DEvents> {
+export class Node2D extends AspectHost<Node2DEvents> {
   /** Native entity handle. */
   readonly id: number
 
@@ -47,23 +48,34 @@ export class Node2D extends Emitter<Node2DEvents> {
   protected _z = 0
   protected _visible = true
 
+  /** @internal — set by Physics2D for a dynamic/kinematic body: the native step owns this node's
+   *  transform, so the transform getters re-sync the cache from native before returning. */
+  _physicsDriven = false
+
+  private _parent: Node2D | null = null
+  private _children: Node2D[] = []
+
   constructor(internalId?: number) {
     super()
     this.id = internalId ?? _creator2d.createEntity()
     node2dRegistry.set(this.id, this)
   }
 
-  // --- transform (Y-up world; at zoom 1, units == pixels) ---
-  get x(): number { return this._x }
-  set x(v: number) { this._x = v; _creator2d.setPosition(this.id, v, this._y) }
-  get y(): number { return this._y }
-  set y(v: number) { this._y = v; _creator2d.setPosition(this.id, this._x, v) }
+  // --- transform (Y-up, LOCAL to the parent; at zoom 1, units == logical pixels) ---
+  // Pull the native transform into the cache iff physics owns it. No-op for the common case (plain
+  // nodes keep free reads); one native read for a moving body, and only when actually read.
+  private _pull(): void { if (this._physicsDriven) this._syncLocalFromNative() }
 
-  get position(): Vec2 { return new Vec2(this._x, this._y) }
+  get x(): number { this._pull(); return this._x }
+  set x(v: number) { this._pull(); this._x = v; _creator2d.setPosition(this.id, v, this._y) }
+  get y(): number { this._pull(); return this._y }
+  set y(v: number) { this._pull(); this._y = v; _creator2d.setPosition(this.id, this._x, v) }
+
+  get position(): Vec2 { this._pull(); return new Vec2(this._x, this._y) }
   set position(v: Vec2Like) { this._x = cx(v); this._y = cy(v); _creator2d.setPosition(this.id, this._x, this._y) }
 
   /** Rotation in degrees (CCW). */
-  get rotation(): number { return this._rotation }
+  get rotation(): number { this._pull(); return this._rotation }
   set rotation(deg: number) { this._rotation = deg; _creator2d.setRotation(this.id, deg) }
 
   get scale(): Vec2 { return new Vec2(this._sx, this._sy) }
@@ -85,20 +97,98 @@ export class Node2D extends Emitter<Node2DEvents> {
   get visible(): boolean { return this._visible }
   set visible(v: boolean) { this._visible = v; _creator2d.setVisible(this.id, v) }
 
+  // --- hierarchy (parent/child; transforms above are LOCAL to the parent) ---
+  get parent(): Node2D | null { return this._parent }
+  set parent(p: Node2D | null) { this.setParent(p) }
+
+  get children(): readonly Node2D[] { return this._children }
+
+  /** Attach children to this node (each keeps its current world transform). Returns this. */
+  add(...children: Node2D[]): this {
+    for (const c of children) c.setParent(this)
+    return this
+  }
+
+  /** Detach a direct child (reparents it to root, keeping its world transform). Returns this. */
+  remove(child: Node2D): this {
+    if (child._parent === this) child.setParent(null)
+    return this
+  }
+
   /**
-   * Attach a collider for overlap detection. DEFERRED: native 2D physics/triggers are not built yet,
-   * so this records intent and is a no-op until the engine lands — the 'enter'/'exit' events won't
-   * fire. The API is here so game code that uses it compiles and stays stable.
+   * Reparent this node. `keepWorld` (default true) recomputes the local transform so the on-screen
+   * position/rotation/scale is unchanged; pass false to keep the local transform and move with the
+   * new parent. Self/descendant parents are rejected natively (no cycles).
    */
-  collider(_options: ColliderOptions = {}): this {
+  setParent(parent: Node2D | null, keepWorld = true): this {
+    if (parent === this) return this
+    if (this._parent) {
+      const arr = this._parent._children
+      const i = arr.indexOf(this)
+      if (i >= 0) arr.splice(i, 1)
+    }
+    this._parent = parent
+    if (parent) parent._children.push(this)
+    _creator2d.setParent(this.id, parent?.id ?? 0, keepWorld)
+    if (keepWorld) this._syncLocalFromNative()   // native recomputed our local transform
     return this
   }
 
-  /** @internal — overridden by Sprite to translate native clip ids into named animation events. */
+  /** World-space position (composes all ancestors). */
+  get worldPosition(): Vec2 {
+    const o = _creator2d.getWorldPosition(this.id)
+    return new Vec2(o[0], o[1])
+  }
+
+  /** Convert a world-space point into this node's local space (and back). */
+  worldToLocal(p: Vec2Like): Vec2 {
+    const o = _creator2d.worldToLocal(this.id, cx(p), cy(p))
+    return new Vec2(o[0], o[1])
+  }
+  localToWorld(p: Vec2Like): Vec2 {
+    const o = _creator2d.localToWorld(this.id, cx(p), cy(p))
+    return new Vec2(o[0], o[1])
+  }
+
+  private _syncLocalFromNative(): void {
+    const t = _creator2d.getLocalTransform(this.id)   // [x, y, rotDeg, sx, sy]
+    this._x = t[0]; this._y = t[1]; this._rotation = t[2]; this._sx = t[3]; this._sy = t[4]
+  }
+
+  /** @internal — host animation events route here by id; the SpriteAnimation aspect installs an
+   *  instance override that translates clip ids to names and emits 'loopReached' / 'completed'. */
   _dispatchAnimEvent(_clipId: number, _type: number): void {}
 
+  /** @internal — emit a translated animation event (the SpriteAnimation aspect can't reach the
+   *  protected dispatch directly). */
+  _emitAnim(channel: "loopReached" | "completed", clip: string): void { this.dispatch(channel, clip) }
+
+  /** @internal — physics contact/sensor events route here (loop.ts) → the node's 'enter'/'exit'. */
+  _emitCollision(channel: "enter" | "exit", other: Node2D): void { this.dispatch(channel, other) }
+
+  // Lazily register the host pointer callback when the first click/touchstart listener is added.
+  override addEventListener<K extends keyof Node2DEvents>(channel: K, callback: Node2DEvents[K]): void {
+    if (channel === "click" || channel === "touchstart") ensurePointerEvents()
+    super.addEventListener(channel, callback)
+  }
+
+  /** @internal — the pointer system (g2/touch.ts) fires click/touchstart here. */
+  _dispatchEvent<K extends keyof Node2DEvents>(channel: K, ...args: Parameters<Node2DEvents[K]>): void {
+    this.dispatch(channel, ...args)
+  }
+
   destroy(): void {
+    // Detach from parent; native reparents our children to root (keepWorld), so resync their caches.
+    if (this._parent) {
+      const arr = this._parent._children
+      const i = arr.indexOf(this)
+      if (i >= 0) arr.splice(i, 1)
+      this._parent = null
+    }
+    const orphans = this._children.slice()
+    this._children.length = 0
     node2dRegistry.delete(this.id)
     _creator2d.destroyEntity(this.id)
+    for (const c of orphans) { c._parent = null; c._syncLocalFromNative() }
   }
 }