lecodes-cli 0.1.6 → 0.2.0

package/runtime/sdk/animate/animate.ts

@@ -0,0 +1,238 @@
+// animate self-implements its matrix decompose/recompose; these are just the numeric-array shapes.
+type mat4 = Float32Array | number[]
+type quat = Float32Array | number[]
+type vec2 = Float32Array | number[]
+type vec3 = Float32Array | number[]
+import type { Easing } from "./easings"
+
+type AnimateProps = number | string | vec2 | vec3 | quat
+
+export type AnimateOptions<T> = {
+  from: T,
+  to: T,
+  duration: number,
+  onUpdate(val: T): void,
+  onComplete?(): void,
+  easing?: Easing,
+}
+
+export const animate = <T extends AnimateProps>(options: AnimateOptions<T>): number => {
+  
+  let onRawUpdate
+  if (typeof options.to === "number") {
+    const { onUpdate, from, to } = options as AnimateOptions<number>
+    onRawUpdate = (t: number) => onUpdate(from + (to - from) * t)
+  } else if (options.to === "string") {
+    // TODO: Make color animate here
+    const { onUpdate, from, to } = options as AnimateOptions<string>
+    onRawUpdate = (t: number) => onUpdate(from)
+    
+    // onRawUpdate = (val: number) => onUpdate(from + (to - from) * val)
+  } else if (options.to.length === 2) {
+    const { onUpdate, from, to } = options as AnimateOptions<vec2>
+    const tempVec = new Float32Array(3)
+    onRawUpdate = (t: number) => onUpdate(lerp2(tempVec, from, to, t))
+
+  } else if (options.to.length === 3) {
+    const { onUpdate, from, to } = options as AnimateOptions<vec3>
+    const tempVec = new Float32Array(3)
+
+    onRawUpdate = (t: number) => onUpdate(lerp(tempVec, from, to, t))
+  } else if (options.to.length === 4) { 
+    const { onUpdate, from, to } = options as AnimateOptions<quat>
+
+    const tempQuat = new Float32Array(4)
+    onRawUpdate = (t: number) => onUpdate(slerp(tempQuat, from, to, t))
+  } else {
+    onRawUpdate = () => {}
+  }
+
+  const animationId = _creatorUtils.animate(val => {
+    const _val = options.easing? options.easing(val): val
+    onRawUpdate(_val)
+    if (val === 1 && options.onComplete) {
+      options.onComplete()
+    }
+  }, options.duration)
+
+  return animationId
+}
+
+export const stopAnimation = (id: number): void =>  _creatorUtils.stopAnimation(id)
+export const pauseAnimation = (id: number): void => _creatorUtils.pauseAnimation(id)
+export const resumeAnimation = (id: number): void => _creatorUtils.resumeAnimation(id)
+
+export const animateMat4 = (options: AnimateOptions<mat4>): number => {
+  const fromPosition = new Float32Array(3)
+  const fromQuaternion = new Float32Array(4)
+  const fromScale = new Float32Array(3)
+  const toPosition = new Float32Array(3)
+  const toQuaternion = new Float32Array(4)
+  const toScale = new Float32Array(3)
+  decompose(fromQuaternion, fromPosition, fromScale, (options as AnimateOptions<mat4>).from)
+  decompose(toQuaternion, toPosition, toScale, (options as AnimateOptions<mat4>).to)
+
+  const tempPosition = new Float32Array(3)
+  const tempQuat = new Float32Array(4)
+  const tempScale = new Float32Array(3)
+  const tempMat = new Float32Array(16)
+
+  const onUpdate = (options as AnimateOptions<mat4>).onUpdate
+  const onRawUpdate = (t: number) => {
+    lerp(tempPosition, fromPosition, toPosition, t)
+    slerp(tempQuat, fromQuaternion, toQuaternion, t)
+    lerp(tempScale, fromScale, toScale, t)
+
+    onUpdate(fromRotationTranslationScale(tempMat, tempQuat, tempPosition, tempScale))
+  }
+
+  const animationId = _creatorUtils.animate(val => {
+    const _val = options.easing? options.easing(val): val
+    onRawUpdate(_val)
+    if (val === 1 && options.onComplete) {
+      options.onComplete()
+    }
+  }, options.duration)
+
+  return animationId
+}
+
+const EPSILON = 1e-6;
+function slerp(out: quat, a: quat, b: quat, t: number) {
+  const ax = a[0], ay = a[1], az = a[2], aw = a[3];
+  let bx = b[0], by = b[1], bz = b[2], bw = b[3];
+  let omega, cosom, sinom, scale0, scale1;
+  cosom = ax * bx + ay * by + az * bz + aw * bw;
+  if (cosom < 0) {
+    cosom = -cosom;
+    bx = -bx;
+    by = -by;
+    bz = -bz;
+    bw = -bw;
+  }
+  if (1 - cosom > EPSILON) {
+    omega = Math.acos(cosom);
+    sinom = Math.sin(omega);
+    scale0 = Math.sin((1 - t) * omega) / sinom;
+    scale1 = Math.sin(t * omega) / sinom;
+  } else {
+    scale0 = 1 - t;
+    scale1 = t;
+  }
+  out[0] = scale0 * ax + scale1 * bx;
+  out[1] = scale0 * ay + scale1 * by;
+  out[2] = scale0 * az + scale1 * bz;
+  out[3] = scale0 * aw + scale1 * bw;
+  return out;
+}
+function lerp(out: vec3, a: vec3, b: vec3, t: number) {
+  const ax = a[0];
+  const ay = a[1];
+  const az = a[2];
+  out[0] = ax + t * (b[0] - ax);
+  out[1] = ay + t * (b[1] - ay);
+  out[2] = az + t * (b[2] - az);
+  return out;
+}
+
+function lerp2(out: vec2, a: vec2, b: vec2, t: number) {
+  const ax = a[0];
+  const ay = a[1];
+  const az = a[2];
+  out[0] = ax + t * (b[0] - ax);
+  out[1] = ay + t * (b[1] - ay);
+  return out;
+}
+function fromRotationTranslationScale(out: mat4, q: quat, v: vec3, s: vec3) {
+  const x = q[0], y = q[1], z = q[2], w = q[3];
+  const x2 = x + x;
+  const y2 = y + y;
+  const z2 = z + z;
+  const xx = x * x2;
+  const xy = x * y2;
+  const xz = x * z2;
+  const yy = y * y2;
+  const yz = y * z2;
+  const zz = z * z2;
+  const wx = w * x2;
+  const wy = w * y2;
+  const wz = w * z2;
+  const sx = s[0];
+  const sy = s[1];
+  const sz = s[2];
+  out[0] = (1 - (yy + zz)) * sx;
+  out[1] = (xy + wz) * sx;
+  out[2] = (xz - wy) * sx;
+  out[3] = 0;
+  out[4] = (xy - wz) * sy;
+  out[5] = (1 - (xx + zz)) * sy;
+  out[6] = (yz + wx) * sy;
+  out[7] = 0;
+  out[8] = (xz + wy) * sz;
+  out[9] = (yz - wx) * sz;
+  out[10] = (1 - (xx + yy)) * sz;
+  out[11] = 0;
+  out[12] = v[0];
+  out[13] = v[1];
+  out[14] = v[2];
+  out[15] = 1;
+  return out;
+}
+
+function decompose(out_r: mat4, out_t: vec3, out_s: vec3, mat: mat4) {
+  out_t[0] = mat[12];
+  out_t[1] = mat[13];
+  out_t[2] = mat[14];
+  const m11 = mat[0];
+  const m12 = mat[1];
+  const m13 = mat[2];
+  const m21 = mat[4];
+  const m22 = mat[5];
+  const m23 = mat[6];
+  const m31 = mat[8];
+  const m32 = mat[9];
+  const m33 = mat[10];
+  out_s[0] = Math.hypot(m11, m12, m13);
+  out_s[1] = Math.hypot(m21, m22, m23);
+  out_s[2] = Math.hypot(m31, m32, m33);
+  const is1 = 1 / out_s[0];
+  const is2 = 1 / out_s[1];
+  const is3 = 1 / out_s[2];
+  const sm11 = m11 * is1;
+  const sm12 = m12 * is2;
+  const sm13 = m13 * is3;
+  const sm21 = m21 * is1;
+  const sm22 = m22 * is2;
+  const sm23 = m23 * is3;
+  const sm31 = m31 * is1;
+  const sm32 = m32 * is2;
+  const sm33 = m33 * is3;
+  const trace = sm11 + sm22 + sm33;
+  let S = 0;
+  if (trace > 0) {
+    S = Math.sqrt(trace + 1) * 2;
+    out_r[3] = 0.25 * S;
+    out_r[0] = (sm23 - sm32) / S;
+    out_r[1] = (sm31 - sm13) / S;
+    out_r[2] = (sm12 - sm21) / S;
+  } else if (sm11 > sm22 && sm11 > sm33) {
+    S = Math.sqrt(1 + sm11 - sm22 - sm33) * 2;
+    out_r[3] = (sm23 - sm32) / S;
+    out_r[0] = 0.25 * S;
+    out_r[1] = (sm12 + sm21) / S;
+    out_r[2] = (sm31 + sm13) / S;
+  } else if (sm22 > sm33) {
+    S = Math.sqrt(1 + sm22 - sm11 - sm33) * 2;
+    out_r[3] = (sm31 - sm13) / S;
+    out_r[0] = (sm12 + sm21) / S;
+    out_r[1] = 0.25 * S;
+    out_r[2] = (sm23 + sm32) / S;
+  } else {
+    S = Math.sqrt(1 + sm33 - sm11 - sm22) * 2;
+    out_r[3] = (sm12 - sm21) / S;
+    out_r[0] = (sm31 + sm13) / S;
+    out_r[1] = (sm23 + sm32) / S;
+    out_r[2] = 0.25 * S;
+  }
+  return out_r;
+}

package/runtime/sdk/animate/bezier.ts

@@ -0,0 +1,138 @@
+/*
+  Bezier function generator
+
+  Gaëtan Renaudeau's BezierEasing
+  https://github.com/gre/bezier-easing/blob/master/src/index.js
+  https://github.com/gre/bezier-easing/blob/master/LICENSE
+  You're a hero
+
+  Use
+
+    const easeOut = cubicBezier(.17,.67,.83,.67);
+    const x = easeOut(0.5); // returns 0.627...
+*/
+
+import type { Easing } from "./easings"
+
+const a = (a1: number, a2: number) => 1.0 - 3.0 * a2 + 3.0 * a1
+const b = (a1: number, a2: number) => 3.0 * a2 - 6.0 * a1
+const c = (a1: number) => 3.0 * a1
+
+// Returns x(t) given t, x1, and x2, or y(t) given t, y1, and y2.
+const calcBezier = (t: number, a1: number, a2: number) =>
+    ((a(a1, a2) * t + b(a1, a2)) * t + c(a1)) * t
+
+// Returns dx/dt given t, x1, and x2, or dy/dt given t, y1, and y2.
+const getSlope = (t: number, a1: number, a2: number) =>
+    3.0 * a(a1, a2) * t * t + 2.0 * b(a1, a2) * t + c(a1)
+
+const subdivisionPrecision = 0.0000001
+const subdivisionMaxIterations = 10
+
+function binarySubdivide(
+    aX: number,
+    aA: number,
+    aB: number,
+    mX1: number,
+    mX2: number
+) {
+    let currentX: number
+    let currentT: number
+    let i: number = 0
+
+    do {
+        currentT = aA + (aB - aA) / 2.0
+        currentX = calcBezier(currentT, mX1, mX2) - aX
+        if (currentX > 0.0) {
+            aB = currentT
+        } else {
+            aA = currentT
+        }
+    } while (
+        Math.abs(currentX) > subdivisionPrecision &&
+        ++i < subdivisionMaxIterations
+    )
+
+    return currentT
+}
+
+const newtonIterations = 8
+const newtonMinSlope = 0.001
+function newtonRaphsonIterate(
+    aX: number,
+    aGuessT: number,
+    mX1: number,
+    mX2: number
+) {
+    for (let i = 0; i < newtonIterations; ++i) {
+        const currentSlope = getSlope(aGuessT, mX1, mX2)
+        if (currentSlope === 0.0) {
+            return aGuessT
+        }
+        const currentX = calcBezier(aGuessT, mX1, mX2) - aX
+        aGuessT -= currentX / currentSlope
+    }
+    return aGuessT
+}
+
+const kSplineTableSize = 11
+const kSampleStepSize = 1.0 / (kSplineTableSize - 1.0)
+
+const linear: Easing = p => p
+
+export function cubicBezier(
+    mX1: number,
+    mY1: number,
+    mX2: number,
+    mY2: number
+): Easing {
+    // If this is a linear gradient, return linear easing
+    if (mX1 === mY1 && mX2 === mY2) return linear
+
+    // Precompute samples table
+    const sampleValues = new Float32Array(kSplineTableSize)
+
+    for (let i = 0; i < kSplineTableSize; ++i) {
+        sampleValues[i] = calcBezier(i * kSampleStepSize, mX1, mX2)
+    }
+
+    function getTForX(aX: number) {
+        let intervalStart = 0.0
+        let currentSample = 1
+        const lastSample = kSplineTableSize - 1
+
+        for (
+            ;
+            currentSample !== lastSample && sampleValues[currentSample] <= aX;
+            ++currentSample
+        ) {
+            intervalStart += kSampleStepSize
+        }
+        --currentSample
+
+        // Interpolate to provide an initial guess for t
+        const dist =
+            (aX - sampleValues[currentSample]) /
+            (sampleValues[currentSample + 1] - sampleValues[currentSample])
+        const guessForT = intervalStart + dist * kSampleStepSize
+
+        const initialSlope = getSlope(guessForT, mX1, mX2)
+        if (initialSlope >= newtonMinSlope) {
+            return newtonRaphsonIterate(aX, guessForT, mX1, mX2)
+        } else if (initialSlope === 0.0) {
+            return guessForT
+        } else {
+            return binarySubdivide(
+                aX,
+                intervalStart,
+                intervalStart + kSampleStepSize,
+                mX1,
+                mX2
+            )
+        }
+    }
+
+    // If animation is at start/end, return t without easing
+    return (t: number) =>
+        t === 0 || t === 1 ? t : calcBezier(getTForX(t), mY1, mY2)
+}

package/runtime/sdk/animate/easings.ts

@@ -0,0 +1,126 @@
+export type Easing = (v: number) => number
+export type EasingModifier = (easing: Easing) => Easing
+
+const DEFAULT_OVERSHOOT_STRENGTH = 1.525
+const BOUNCE_FIRST_THRESHOLD = 4.0 / 11.0
+const BOUNCE_SECOND_THRESHOLD = 8.0 / 11.0
+const BOUNCE_THIRD_THRESHOLD = 9.0 / 10.0
+
+// helper constants
+const ca = 4356.0 / 361.0
+const cb = 35442.0 / 1805.0
+const cc = 16061.0 / 1805.0
+
+export function linear(p: number): number {
+  return p
+}
+
+export function bounceOut(p: number): number {
+  if (p === 1 || p === 0) return p
+  const p2 = p * p
+
+  return p < BOUNCE_FIRST_THRESHOLD
+    ? 7.5625 * p2
+    : p < BOUNCE_SECOND_THRESHOLD
+      ? 9.075 * p2 - 9.9 * p + 3.4
+      : p < BOUNCE_THIRD_THRESHOLD
+        ? ca * p2 - cb * p + cc
+        : 10.8 * p * p - 20.52 * p + 10.72
+}
+
+export function bounceInOut(p: number): number {
+  return p < 0.5
+    ? 0.5 * (1.0 - bounceOut(1.0 - p * 2.0))
+    : 0.5 * bounceOut(p * 2.0 - 1.0) + 0.5
+}
+
+// Accepts an easing function and returns a new one that outputs reversed values.
+// Turns easeIn into easeOut.
+export function reverseEasing(easing: Easing): Easing {
+  return p => 1 - easing(1 - p)
+}
+
+// Accepts an easing function and returns a new one that outputs mirrored values for
+// the second half of the animation. Turns easeIn into easeInOut.
+export function mirrorEasing(easing: Easing): Easing {
+  return p => (p <= 0.5 ? easing(2 * p) / 2 : (2 - easing(2 * (1 - p))) / 2)
+}
+
+// Creates an easing function that is based on the exponent of the provided `power`.
+// The higher the `power`, the stronger the easing.
+export function createExpoIn(power: number): Easing {
+  return p => p ** power
+}
+
+// Creates an easing function that has a stronger overshoot the higher the provided `power`.
+export function createBackIn(power: number): Easing {
+  return p => p * p * ((power + 1) * p - power)
+}
+
+// Creates an easing function that pulls back a little before moving, and then
+// has a `createBackIn`-based overshoot
+export function createAnticipate(power: number): Easing {
+  const backEasing = createBackIn(power)
+
+  return p =>
+    (p *= 2) < 1
+      ? 0.5 * backEasing(p)
+      : 0.5 * (2 - Math.pow(2, -10 * (p - 1)))
+}
+
+export function bounceIn(p: number): number {
+  return 1 - bounceOut(1 - p)
+}
+
+export function easeIn(p: number): number {
+  return p * p
+}
+
+export function easeOut(p: number): number {
+  return 1 - easeIn(1 - p)
+}
+
+export function easeInOut(p: number): number {
+  return p <= 0.5
+    ? easeIn(2 * p) / 2
+    : (2 - easeIn(2 * (1 - p))) / 2
+}
+
+export function circIn(p: number): number {
+  return 1 - Math.sin(Math.acos(p))
+}
+
+export function circOut(p: number): number {
+  return 1 - circIn(1 - p)
+}
+
+export function circInOut(p: number): number {
+  return p <= 0.5
+    ? circOut(2 * p) / 2
+    : (2 - circOut(2 * (1 - p))) / 2
+}
+
+export function backIn(p: number): number {
+  const power = DEFAULT_OVERSHOOT_STRENGTH
+  return p * p * ((power + 1) * p - power)
+}
+
+export function backOut(p: number): number {
+  return 1 - backIn(1 - p)
+}
+
+export function backInOut(p: number): number {
+  return p <= 0.5
+    ? backIn(2 * p) / 2
+    : (2 - backIn(2 * (1 - p))) / 2
+}
+
+export function anticipate(p: number): number {
+  const doubled = p * 2
+
+  if (doubled < 1) {
+    return 0.5 * backIn(doubled)
+  }
+
+  return 0.5 * (2 - Math.pow(2, -10 * (doubled - 1)))
+}

package/runtime/sdk/core/Aspect.ts

@@ -0,0 +1,151 @@
+// 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 ----------------------------------------------
+// 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)
+    }
+  })
+}
+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)
+}
+
+// ---- 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), via a lazy global loop. */
+  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. */
+  updateWhenVisible = false
+}