lecodes-sdk 0.19.0

package/dist/types/animate/animate.d.ts

@@ -0,0 +1,20 @@
+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 declare const animate: <T extends AnimateProps>(options: AnimateOptions<T>) => number;
+export declare const stopAnimation: (id: number) => void;
+export declare const pauseAnimation: (id: number) => void;
+export declare const resumeAnimation: (id: number) => void;
+export declare const animateMat4: (options: AnimateOptions<mat4>) => number;
+export {};

package/dist/types/animate/bezier.d.ts

@@ -0,0 +1,2 @@
+import type { Easing } from "./easings";
+export declare function cubicBezier(mX1: number, mY1: number, mX2: number, mY2: number): Easing;

package/dist/types/animate/easings.d.ts

@@ -0,0 +1,21 @@
+export type Easing = (v: number) => number;
+export type EasingModifier = (easing: Easing) => Easing;
+export declare function linear(p: number): number;
+export declare function bounceOut(p: number): number;
+export declare function bounceInOut(p: number): number;
+export declare function reverseEasing(easing: Easing): Easing;
+export declare function mirrorEasing(easing: Easing): Easing;
+export declare function createExpoIn(power: number): Easing;
+export declare function createBackIn(power: number): Easing;
+export declare function createAnticipate(power: number): Easing;
+export declare function bounceIn(p: number): number;
+export declare function easeIn(p: number): number;
+export declare function easeOut(p: number): number;
+export declare function easeInOut(p: number): number;
+export declare function circIn(p: number): number;
+export declare function circOut(p: number): number;
+export declare function circInOut(p: number): number;
+export declare function backIn(p: number): number;
+export declare function backOut(p: number): number;
+export declare function backInOut(p: number): number;
+export declare function anticipate(p: number): number;

package/dist/types/canvas/Canvas.d.ts

@@ -0,0 +1,168 @@
+import { Texture2D } from "../g2/Texture2D";
+import { File, type FetchResponse } from "../runtime/fetch";
+import type { SvgSourceValue } from "../runtime/misc";
+declare const ALIGN: {
+    readonly left: 0;
+    readonly center: 1;
+    readonly right: 2;
+    readonly start: 3;
+    readonly end: 4;
+};
+declare const BASELINE: {
+    readonly alphabetic: 0;
+    readonly top: 1;
+    readonly middle: 2;
+    readonly bottom: 3;
+    readonly hanging: 4;
+    readonly ideographic: 5;
+};
+declare const JOIN: {
+    readonly miter: 0;
+    readonly round: 1;
+    readonly bevel: 2;
+};
+declare const CAP: {
+    readonly butt: 0;
+    readonly round: 1;
+    readonly square: 2;
+};
+export type TextAlign = keyof typeof ALIGN;
+export type TextBaseline = keyof typeof BASELINE;
+export type LineJoin = keyof typeof JOIN;
+export type LineCap = keyof typeof CAP;
+export interface CanvasTextMetrics {
+    width: number;
+    ascent: number;
+    descent: number;
+}
+export declare class Canvas {
+    /** Brand so `Sprite`/`UIImage`/`Material` can accept a Canvas anywhere a texture source is expected. */
+    readonly __canvas: true;
+    width: number;
+    height: number;
+    /** Device-pixel multiplier (draw at 2 for crisp retina text). Applied by the backend. */
+    pixelRatio: number;
+    private _cmd;
+    private _refs;
+    private _globalAlpha;
+    private _fillStyle;
+    private _strokeStyle;
+    private _lineWidth;
+    private _lineJoin;
+    private _lineCap;
+    private _font;
+    private _textAlign;
+    private _textBaseline;
+    private _surfaceId;
+    private _tex2d?;
+    private _uiBound;
+    constructor(width: number, height: number, opts?: {
+        pixelRatio?: number;
+    });
+    private _ref;
+    /** Discard the recorded drawing to start a new one (for dynamic canvases). */
+    reset(): this;
+    /** Change the surface size; takes effect on the next bake. */
+    resize(width: number, height: number): this;
+    save(): this;
+    restore(): this;
+    translate(x: number, y: number): this;
+    scale(sx: number, sy: number): this;
+    rotate(rad: number): this;
+    get globalAlpha(): number;
+    set globalAlpha(a: number);
+    get fillStyle(): string;
+    set fillStyle(color: string);
+    get strokeStyle(): string;
+    set strokeStyle(color: string);
+    get lineWidth(): number;
+    set lineWidth(w: number);
+    get lineJoin(): LineJoin;
+    set lineJoin(j: LineJoin);
+    get lineCap(): LineCap;
+    set lineCap(c: LineCap);
+    get font(): string;
+    set font(f: string);
+    get textAlign(): TextAlign;
+    set textAlign(a: TextAlign);
+    get textBaseline(): TextBaseline;
+    set textBaseline(b: TextBaseline);
+    beginPath(): this;
+    closePath(): this;
+    moveTo(x: number, y: number): this;
+    lineTo(x: number, y: number): this;
+    quadraticCurveTo(cx: number, cy: number, x: number, y: number): this;
+    bezierCurveTo(c1x: number, c1y: number, c2x: number, c2y: number, x: number, y: number): this;
+    arc(x: number, y: number, r: number, a0: number, a1: number, ccw?: boolean): this;
+    rect(x: number, y: number, w: number, h: number): this;
+    roundRect(x: number, y: number, w: number, h: number, r: number): this;
+    fill(evenOdd?: boolean): this;
+    stroke(): this;
+    fillRect(x: number, y: number, w: number, h: number): this;
+    strokeRect(x: number, y: number, w: number, h: number): this;
+    clearRect(x: number, y: number, w: number, h: number): this;
+    fillText(text: string, x: number, y: number, maxWidth?: number): this;
+    strokeText(text: string, x: number, y: number, maxWidth?: number): this;
+    /** Blit a `Bitmap` (a snapshot from `toBitmap()`) onto this canvas. All coordinates are LOGICAL —
+     *  including the source sub-rect in the 9-arg form (it's scaled by the bitmap's pixelRatio here).
+     *  Records a DRAW_IMAGE op, so the blit runs at bake time: keep the Bitmap alive until the next
+     *  `update()`/`toBitmap()`/`texture()`. Three browser-style forms:
+     *    drawImage(bmp, dx, dy)                         — whole bitmap at its natural size
+     *    drawImage(bmp, dx, dy, dw, dh)                 — whole bitmap, scaled into dw×dh
+     *    drawImage(bmp, sx, sy, sw, sh, dx, dy, dw, dh) — a sub-rect of the bitmap, scaled into dw×dh */
+    drawImage(img: Bitmap, dx: number, dy: number): this;
+    drawImage(img: Bitmap, dx: number, dy: number, dw: number, dh: number): this;
+    drawImage(img: Bitmap, sx: number, sy: number, sw: number, sh: number, dx: number, dy: number, dw: number, dh: number): this;
+    /** Decode an image source into a standalone `Bitmap` you can blit with `drawImage()` — either an
+     *  `SvgSource(...)` (rasterized) or a `FetchResponse` holding already-fetched image bytes (decoded).
+     *  This is async because turning SVG markup / encoded bytes into pixels needs a decode step (on the
+     *  web, `createImageBitmap` / an `<img>` load); `await` it ONCE, then `drawImage(bitmap, …)` is
+     *  synchronous and the Bitmap is reusable. The returned Bitmap owns a native surface at the image's
+     *  natural pixel size (`pixelRatio` 1) — `destroy()` it when done. Typical use:
+     *    const logo = await canvas.loadImage(SvgSource(svg))   // or: await fetch(url) → the response
+     *    canvas.drawImage(logo, 0, 0)                          // sync, blit as often as you like */
+    loadImage(source: SvgSourceValue | FetchResponse): Promise<Bitmap>;
+    /** Measure `text` in the current font on THIS platform. The one synchronous round-trip. */
+    measureText(text: string): CanvasTextMetrics;
+    /** Bake and return the 2D texture (created once, then cached). */
+    texture(): Texture2D;
+    /** Re-rasterize and re-upload to every texture this canvas produced (call after redrawing) — the
+     *  cached 2D and/or 3D texture, whichever engines this canvas was baked into. */
+    update(): this;
+    /** Copy the current pixels into a standalone, immutable `Bitmap` — independent of this canvas, so
+     *  later drawing/`reset()` never touches it. Draw it back with `drawImage()`, export it with
+     *  `toDataURL()`, or use it to "flatten" an ever-growing drawing so re-bakes stay O(1):
+     *    const snap = canvas.toBitmap()
+     *    canvas.reset(); canvas.drawImage(snap, 0, 0)   // one op replaces the whole history
+     *    // …keep drawing on top; snap.destroy() once it's been drawn in. */
+    toBitmap(): Bitmap;
+    /** Encode the current pixels to an image `File` — 'image/png' (default) or 'image/jpeg'. The File
+     *  is an opaque host buffer handle (`name`/`size` only): append it to a FormData to upload, load it
+     *  as a texture (`Texture2D.load(file)`), or hand it to a share/save sheet. */
+    toFile(name?: string, type?: string): Promise<File>;
+    destroy(): void;
+}
+/** Duck-type guard so consumers can accept a Canvas anywhere a texture source is expected. */
+export declare const isCanvas: (v: unknown) => v is Canvas;
+/** An immutable RGBA8 snapshot of a canvas, produced by `Canvas.toBitmap()`. It owns its own baked
+ *  surface (a copy), so the source canvas can keep drawing or `reset()` without affecting it. Use it
+ *  to stamp/blit back (`canvas.drawImage(bitmap, …)`), to export (`bitmap.toDataURL()`), or as a
+ *  cheap "layer" you composite. Call `destroy()` when done — it holds a native surface. */
+export declare class Bitmap {
+    readonly __bitmap: true;
+    /** Logical width, matching the Canvas it was captured from (pixelRatio is crispness, not size). */
+    readonly width: number;
+    readonly height: number;
+    readonly pixelRatio: number;
+    constructor(surfaceId: number, width: number, height: number, pixelRatio: number);
+    /** Device-pixel dimensions of the stored bitmap (`width * pixelRatio`, rounded). */
+    get pixelWidth(): number;
+    get pixelHeight(): number;
+    /** Encode to an image `File` — 'image/png' (default) or 'image/jpeg'. See `Canvas.toFile`. */
+    toFile(name?: string, type?: string): Promise<File>;
+    /** Free the native surface. The bitmap must not be drawn or encoded afterwards. */
+    destroy(): void;
+}
+/** Duck-type guard for a Bitmap (see `isCanvas`). */
+export declare const isBitmap: (v: unknown) => v is Bitmap;
+export {};

package/dist/types/core/Aspect.d.ts

@@ -0,0 +1,171 @@
+import type { Scene } from "../gl/Scene";
+import { Emitter, type EventMap } from "./events";
+import type { InspectorUI } from "./InspectorUI";
+import type { Node } from "../gl/Node";
+/** The class object of an aspect — accepted even when its constructor is protected/abstract. */
+export type AspectCtor<A extends Aspect<any, any, any>> = abstract new () => A;
+/** The accessor name carried in the aspect's generic. */
+export type KeyOf<A> = A extends Aspect<infer K, any, any> ? K : never;
+/** The node kind an aspect targets (the scene kind for a System). */
+export type TargetOf<A> = A extends Aspect<any, infer P, any> ? P : never;
+/** `{ name: Aspect }` — the field an aspect contributes to its node. */
+export type FieldOf<A extends Aspect<any, 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, any>> = N & UnionToIntersection<A extends any ? FieldOf<A> : never>;
+/**
+ * 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 declare abstract class AspectHost<E extends EventMap = EventMap> extends Emitter<E> {
+    /** 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, any>>(this: Self, ctor: AspectCtor<A>, opts?: Partial<A>): Self & FieldOf<A>;
+    /** Safe access — undefined if the aspect isn't attached. */
+    get<A extends Aspect<any, any, any>>(ctor: AspectCtor<A>): A | undefined;
+    /** Existence check AND type guard: inside `if (node.has(Physics))`, `node.physics` is present. */
+    has<A extends Aspect<any, any, any>>(ctor: AspectCtor<A>): this is this & FieldOf<A>;
+    /** 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, any>>(ctor: AspectCtor<A>): this;
+}
+/**
+ * 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.
+ * `E` = the events this aspect emits (`{ explode: (b: Barrel) => void }`): `this.emit('explode', …)`
+ * inside, `node.barrel.on('explode', fn)` outside.
+ * Initialize in `onAttach` (the node is set by then) — not a constructor; aspects are created by the
+ * engine via `node.aspect()`, never `new`.
+ */
+export declare abstract class Aspect<K extends string, P = Node, E extends EventMap = {}> {
+    /**
+     * Opt this aspect class into EDITOR-RUN mode (generators): while a scene is edited, the scene
+     * loader constructs the instance (refs resolved, `node`/`generated` set — never `onAttach`) and
+     * calls `rebuild()` — again on inspector prop edits and when a `ref()`-referenced node moves.
+     * `static editor = { rebuild: true }`.
+     */
+    static editor?: {
+        rebuild?: boolean;
+    };
+    /**
+     * Custom inspector card for this aspect in the scene editor (immediate-mode — see
+     * core/InspectorUI.ts): re-runs on every edit/event and emits a widget list. Without it, the
+     * editor shows the inferred fields; `ui.auto()` emits those same fields, so a custom inspector
+     * usually starts with `ui.auto()` and appends status lines / buttons / dynamic dropdowns:
+     *
+     *   static inspector(ui: InspectorUI, self: MyAspect) {
+     *     ui.auto()
+     *     if (ui.button('Randomize')) self.rebuild()
+     *   }
+     */
+    static inspector?: (ui: InspectorUI, aspect: any) => void;
+    /** Tick AFTER these classes within the same phase (`static after = [Controls]`). A constraint
+     *  always beats the numeric `updateOrder`. Classes absent from the phase are ignored. */
+    static after?: Function[];
+    /** Tick BEFORE these classes within the same phase (`static before = [Camera]`). */
+    static before?: Function[];
+    /** Every live instance of an aspect/system class, in attach order — the registry a game used to
+     *  hand-roll as `static all[]`. Live, read-only: copy it (`[...Aspect.all(Barrel)]`) before a loop
+     *  that detaches. Empty in the scene editor (aspects are inert data there). */
+    static all<A extends Aspect<any, any, any>>(ctor: AspectCtor<A>): readonly A[];
+    /** The node this aspect is attached to (set at attach time). For a System: the scene. */
+    readonly node: P;
+    /**
+     * GENERATOR aspects (`static editor = { rebuild: true }`, attached through a scene file): a
+     * scene-added container child for the aspect's generated output — `rebuild()` clears and refills
+     * it. Provided by the scene loader before `onAttach`/`rebuild` run; nodes `add()`ed to it join
+     * the scene's draw set automatically (membership is separate from parenting). Undefined for
+     * aspects attached by hand outside scene files. See docs/3d/scene-files.md.
+     */
+    readonly generated: Node & {
+        clear(): void;
+        readonly version: number;
+    };
+    /**
+     * GENERATOR aspects attached through a scene file: the `Scene` the host node was built into —
+     * what `handle.instantiate({ scene })` / `scene.add()` need inside `rebuild()`. Set by the scene
+     * loader (edit AND play mode); undefined for aspects attached by hand. 3D only (2D aspects own
+     * their `scene` field). For a System: always set — the scene it is attached to.
+     */
+    readonly scene: P extends Node ? Scene : P extends SystemHost ? P : unknown;
+    protected readonly __key__?: K;
+    protected readonly __events__?: E;
+    private _listeners?;
+    /** The node (or scene) is set — initialize here, not in a constructor. */
+    protected onAttach?(): void;
+    /** Release what onAttach acquired. */
+    protected onDetach?(): void;
+    /** Called after `node.aspect(Ctor, opts)` re-assigns options on an ALREADY attached aspect (a
+     *  pre-attached one like `model.anim`): rebuild whatever was derived from the options at attach. */
+    protected onReconfigure?(): void;
+    /**
+     * GENERATOR aspects: (re)build the derived output under `this.generated` — must be idempotent
+     * (clear, then create). Call it from `onAttach()` for play mode; a class opting in with
+     * `static editor = { rebuild: true }` ALSO runs it while a scene is being edited: once at load,
+     * and again whenever an inspector prop changes or a `ref()`-referenced node moves.
+     */
+    rebuild?(): void;
+    /**
+     * LATE phase — every frame while attached, after the physics step + transform sync + animators,
+     * right before the frame draws: reads of `node.worldPosition` are the final drawn position
+     * (cameras/followers have no 1-frame lag) and what you write to a plain node is what this frame
+     * shows. The default home for game logic. `dt` = GAME seconds since the last frame (`Time.scale`
+     * applied; 0 while paused — see `updateWhilePaused`).
+     */
+    protected update?(dt: number): void;
+    /**
+     * EARLY phase — every frame BEFORE the physics step, so what you feed the simulation (velocity,
+     * `controller.move()`, forces, kinematic transforms) is consumed by this same frame's step: zero
+     * input latency. Use it only when you FEED the simulation. Reads here see last frame's settled
+     * state. A class rarely needs both phases — that is two aspects on one node.
+     */
+    protected updateBefore?(dt: number): void;
+    /**
+     * FIXED phase - once per physics substep, BEFORE that substep's Jolt step, with `dt = Time.fixedDt`
+     * (1/60) exactly, on every machine: under `Time.scale` the NUMBER of steps per frame changes, never
+     * the dt (0-4 calls per frame). The home of simulation that must match another machine's - a
+     * multiplayer player sim, dt-dependent motion that may not drift with the frame rate. `controller.move()`
+     * / velocity writes here feed the same step; between steps the world is consistent, so `Physics.raycast`
+     * is fine. Anything that looks at the screen (cameras, HUD, FX) stays in `updateBefore` / `update`.
+     */
+    protected updateFixed?(dt: number): void;
+    /** Tick order within a phase and rank — ascending; default 0, ties keep attach order. A declared
+     *  `static after` / `static before` constraint always beats this number. Read once, at attach —
+     *  set it as a class field. */
+    protected updateOrder: number;
+    /** Keep ticking while `Time.paused` (a HUD fade, the pause menu). `dt` is still 0 then — read
+     *  `Time.unscaledDt` for wall-clock motion. Checked every frame; may be toggled at any time. */
+    protected updateWhilePaused: boolean;
+    /** 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. */
+    protected updateWhenVisible: boolean;
+    /** Listen to one of this aspect's events. Chainable. Cleared on detach. */
+    on<C extends keyof E & string>(channel: C, callback: E[C]): this;
+    /** Remove a listener added with `on` (same function reference). */
+    off<C extends keyof E & string>(channel: C, callback: E[C]): this;
+    /** Fire one of this aspect's events. Protected: only the aspect itself emits. */
+    protected emit<C extends keyof E & string>(channel: C, ...args: Parameters<E[C]>): void;
+}
+/**
+ * An aspect of a SCENE: game logic with no single node to live on — input mapping, the FX pools, the
+ * HUD, the game mode. Same lifecycle (`onAttach`/`onDetach`), same phases (`updateFixed` / `updateBefore` /
+ * `update`), same ordering (`updateOrder`, `static after`) and events as a node aspect; `this.scene` is the
+ * scene it was attached to. `S` = the scene kind (`Scene` by default, `Scene2D` for 2D games).
+ *
+ *   class Hud extends System<'hud'> {
+ *     static after = [Player]
+ *     update(dt: number) { … }
+ *   }
+ *   scene.system(Hud)      // attach
+ *   scene.hud              // the typed accessor
+ */
+export declare abstract class System<K extends string, S extends SystemHost = Scene, E extends EventMap = {}> extends Aspect<K, S, E> {
+}
+export {};

package/dist/types/core/InspectorUI.d.ts

@@ -0,0 +1,88 @@
+import type { FieldEditor } from "./fields";
+/** One user interaction coming back from the editor panel: the widget's id (+ value for fields). */
+export type InspectorEvent = {
+    id: string;
+    value?: unknown;
+};
+export type InspectorFieldWidget = {
+    kind: "field";
+    id: string;
+    /** The bound key — an aspect field (doc-bound) or an editor-state key. */
+    key: string;
+    label: string;
+    editor: FieldEditor | undefined;
+    value: unknown;
+    /** True = persisted to the scene file by the editor; false = transient editor state. */
+    doc: boolean;
+    /** True = emitted by `ui.auto()` — the editor may overlay its syntactic hints (options/node). */
+    auto?: boolean;
+    min?: number;
+    max?: number;
+    step?: number;
+    options?: readonly (string | number)[];
+};
+export type InspectorWidget = InspectorFieldWidget | {
+    kind: "button";
+    id: string;
+    label: string;
+} | {
+    kind: "toolButton";
+    id: string;
+    label: string;
+    tool: string;
+} | {
+    kind: "header";
+    id: string;
+    label: string;
+} | {
+    kind: "info" | "warn";
+    id: string;
+    text: string;
+};
+type FieldOpts = {
+    label?: string;
+    min?: number;
+    max?: number;
+    step?: number;
+    /** Default for EDITOR-STATE keys (doc keys default from the class field). */
+    value?: unknown;
+};
+/**
+ * The widget builder handed to `static inspector(ui, aspect)` (and to editor windows/tools later).
+ * One instance lives per card and persists across runs — it carries the card's editor state.
+ */
+export declare class InspectorUI {
+    /** Numeric field (min/max/step render as a slider-style scrub range). */
+    number(key: string, opts?: FieldOpts): number;
+    /** Alias of `number` — give it min/max/step and the editor renders a scrubable range. */
+    slider(key: string, opts?: FieldOpts): number;
+    text(key: string, opts?: FieldOpts): string;
+    color(key: string, opts?: FieldOpts): string;
+    switch(key: string, opts?: FieldOpts): boolean;
+    /** Dropdown — `options` may be computed fresh every run (dynamic lists come free). */
+    select(key: string, options: readonly (string | number)[], opts?: FieldOpts): string | number;
+    vec2(key: string, opts?: FieldOpts): [number, number];
+    vec3(key: string, opts?: FieldOpts): [number, number, number];
+    vec4(key: string, opts?: FieldOpts): [number, number, number, number];
+    /** Scene-node reference (`ref()` fields): name dropdown + pick-in-viewport. Returns the RAW doc
+     *  value (`{ $ref }` marker or null) — read the resolved live node off the aspect instance. */
+    node(key: string, opts?: FieldOpts): unknown;
+    /** Project-asset path (the editor renders a dropdown of the project's GLBs). "" = none picked. */
+    asset(key: string, opts?: FieldOpts): string;
+    /** True on the run that consumes this button's click — do the action right there. */
+    button(label: string, opts?: {
+        id?: string;
+    }): boolean;
+    /** A toggle that activates/deactivates the named viewport tool (`registerEditorTool`). The
+     *  editor owns the active-tool state — the click never round-trips into the scene world. */
+    toolButton(label: string, tool: string): void;
+    header(label: string): void;
+    info(text: string): void;
+    warn(text: string): void;
+    /** Emit the inferred field widgets (all declared aspect fields, or just the named ones) — the
+     *  zero-ceremony baseline; append custom widgets around it. */
+    auto(...keys: string[]): void;
+    private _vec;
+    private _field;
+}
+export {};

package/dist/types/core/StateMachine.d.ts

@@ -0,0 +1,81 @@
+export type StateGuard<C> = (ctx: C, t: number) => boolean;
+export type StateHandler<C> = (ctx: C, ...args: any[]) => string | void;
+export interface StateDef<C> {
+    /** The child entered by default when this (compound) state is entered. */
+    initial?: string;
+    /** Child states — this becomes a compound state; only a leaf is ever "the" state. */
+    states?: Record<string, StateDef<C>>;
+    /** Entered (from = the previous leaf's path, '' at start). */
+    enter?: (ctx: C, from: string) => void;
+    /** Left (to = the next leaf's path). */
+    exit?: (ctx: C, to: string) => void;
+    /** Every step while active, outer states first; `t` = seconds in this state. Return a state name
+     *  to transition. */
+    update?: (ctx: C, dt: number, t: number) => string | void;
+    /** Guarded transitions, tested every step before `update` — key = target, first true wins. */
+    to?: Record<string, StateGuard<C>>;
+    /** Leave for `target` after `seconds` in this state. */
+    after?: [seconds: number, target: string];
+    /** Event handlers for `send(name, …args)`: a target name, or a function returning one (or nothing). */
+    on?: Record<string, string | StateHandler<C>>;
+}
+export interface StatesDef<C> {
+    initial: string;
+    states: Record<string, StateDef<C>>;
+    /** Any-state guards — tested first, in every state. */
+    to?: Record<string, StateGuard<C>>;
+    /** Any-state event handlers — the fallback when no active state handles the event. */
+    on?: Record<string, string | StateHandler<C>>;
+    /** Any-state update, runs before the active states' own. */
+    update?: (ctx: C, dt: number, t: number) => string | void;
+}
+export type StateMachineEvents = {
+    /** After a transition completed (both are leaf paths; `from` = '' for the initial entry). */
+    change: (to: string, from: string) => void;
+};
+/** Identity helper — names the context type once so every callback is typed. */
+export declare const defineStates: <C>(def: StatesDef<C>) => StatesDef<C>;
+export declare class StateMachine<C> {
+    readonly ctx: C;
+    private readonly root;
+    private readonly byPath;
+    /** the active branch, root's child (index 0) → leaf */
+    private chain;
+    private prev;
+    private listeners;
+    private changed;
+    constructor(def: StatesDef<C>, ctx: C);
+    /** The active leaf's path ('combat.shoot'). */
+    get state(): string;
+    /** The leaf we came from ('' before the first transition). */
+    get previous(): string;
+    /** Seconds in the active leaf. */
+    get time(): number;
+    /** Every active state's path, outermost first. */
+    get branch(): string[];
+    /** Is `name` (a state name or dotted path) active — as the leaf OR as one of its ancestors? */
+    is(name: string): boolean;
+    /** Seconds in the named active state (0 when it is not active). */
+    timeIn(name: string): number;
+    /** Force a transition (a spawn, a reset from outside the table). */
+    go(name: string): void;
+    /** Deliver an event. Innermost active state first, the root's `on` last. True if handled. */
+    send(event: string, ...args: unknown[]): boolean;
+    /** One tick: clocks, guards (outer first, chained), then updates (outer first). */
+    step(dt: number): void;
+    /** Listen for transitions. */
+    on(event: "change", fn: StateMachineEvents["change"]): this;
+    off(event: "change", fn: StateMachineEvents["change"]): this;
+    private build;
+    private link;
+    private resolveStrict;
+    /** Relative first (siblings of `from`, then of each ancestor), then a dotted path from the root. */
+    private resolve;
+    /** Guards never re-enter a state that is already active (a `dead` guard staying true does not
+     *  re-enter `dead` every step) — only an explicit `go()` / event does that. */
+    private findTransition;
+    private active;
+    private leafOf;
+    private transition;
+    private enterBranch;
+}

package/dist/types/core/color.d.ts

@@ -0,0 +1,13 @@
+export type ColorInput = string | number | readonly [number, number, number] | readonly [number, number, number, number];
+export declare const Color: {
+    /** [r,g,b] in 0..1 — for the 2D engine's float color setters. */
+    toRgb01(c: ColorInput): [number, number, number];
+    /** [r,g,b,a] in 0..1. */
+    toRgba01(c: ColorInput): [number, number, number, number];
+    /** 0xRRGGBB packed int — for the 3D engine's color uniforms / skybox. */
+    toPackedRgb(c: ColorInput): number;
+    /** 0xRRGGBBAA packed int (unsigned). */
+    toPackedRgba(c: ColorInput): number;
+    /** '#rrggbb' (or '#rrggbbaa' when alpha < 1) — for the 3D material color uniforms. */
+    toHexString(c: ColorInput): string;
+};

package/dist/types/core/compWrite.d.ts

@@ -0,0 +1,11 @@
+export type CompAxis = "x" | "y" | "z" | "w";
+/** Implemented by a class whose vector getters accept component writes (see above). The class also
+ *  carries `static _comps: string[]` naming those getters — compile-time data, absent at runtime. */
+export interface CompWriter {
+    _writeComp(prop: string, axis: CompAxis, value: number): void;
+}
+/** `<o>.<prop>.<axis> = value`, routed to the owner when it has the hook. Returns the value. */
+export declare const __compWrite: (o: any, prop: string, axis: CompAxis, value: number) => number;
+/** `<o>.<prop>.<axis> op= v` — `op`: 0 `+=`, 1 `-=`, 2 `*=`, 3 `/=`. The current component is read
+ *  through the normal getter (one fresh vector), the result written like `__compWrite`. */
+export declare const __compOp: (o: any, prop: string, axis: CompAxis, op: number, v: number) => number;

package/dist/types/core/events.d.ts

@@ -0,0 +1,11 @@
+export type EventMap = Record<string, (...args: any[]) => void>;
+export declare class Emitter<E extends EventMap> {
+    private _listeners;
+    addEventListener<K extends keyof E>(channel: K, callback: E[K]): void;
+    removeEventListener<K extends keyof E>(channel: K, callback: E[K]): void;
+    /** Fire all listeners on a channel. Protected: only the owning class emits. */
+    protected dispatch<K extends keyof E>(channel: K, ...args: Parameters<E[K]>): void;
+    protected hasListeners<K extends keyof E>(channel: K): boolean;
+    /** Drop every listener on every channel (used when the owning object is disposed). */
+    protected clearListeners(): void;
+}

package/dist/types/core/fields.d.ts

@@ -0,0 +1,58 @@
+/** Editor widget kinds the inspector knows how to render. `"node"` = a scene-node reference
+ *  (`ref('name')` in the file, name dropdown + pick-in-viewport in the inspector) — declare it via
+ *  `static fields` on fields typed `Node | null`; a `Node | null` type annotation is also picked
+ *  up syntactically by the editor's source scan. `"asset"` = a project-asset path (the editor
+ *  fills the dropdown with the project's GLBs — `ui.asset()` in windows/tools/cards). */
+export type FieldEditor = "number" | "text" | "color" | "switch" | "select" | "vec2" | "vec3" | "vec4" | "node" | "asset";
+export type FieldMetaEntry = {
+    /** Inspector label (default: the field name). */
+    label?: string;
+    min?: number;
+    max?: number;
+    step?: number;
+    /** Allowed values — renders a dropdown (editor "select"). */
+    options?: readonly (string | number)[];
+    /** Override the editor inferred from the default value. */
+    editor?: FieldEditor;
+    /** Exclude the field from the inspector. */
+    hidden?: boolean;
+};
+/** Declared on an aspect class as `static fields: FieldMeta<MyAspect> = { … }`. All optional. */
+export type FieldMeta<T = unknown> = {
+    [K in Extract<keyof T, string>]?: FieldMetaEntry;
+};
+/** One editable field: key + default value + resolved editor + merged metadata. */
+export type FieldDescriptor = {
+    key: string;
+    label: string;
+    /** The default value (from a freshly constructed instance; undefined if only declared in meta). */
+    value: unknown;
+    /** Resolved editor kind; undefined = no editor known (inspector shows it read-only). */
+    editor: FieldEditor | undefined;
+    min?: number;
+    max?: number;
+    step?: number;
+    options?: readonly (string | number)[];
+};
+export type AspectClassInfo = {
+    /** The accessor name (`static aspect`, injected by chisel for user aspects). */
+    name: string;
+    className: string;
+    fields: FieldDescriptor[];
+    /** True for editor-run classes (`static editor` — generators). The editor routes their
+     *  structural changes through a re-run instead of a live patch. */
+    editor?: boolean;
+    /** True when the class declares a custom `static inspector(ui, aspect)` card. */
+    inspector?: boolean;
+};
+/** Infer the editor widget from a default value's shape. */
+export declare const inferFieldEditor: (value: unknown) => FieldEditor | undefined;
+/**
+ * Enumerate the editable fields of a class: construct a default instance, take its own enumerable
+ * non-underscore fields (minus the Aspect base plumbing), infer editors from the default values, and
+ * merge the class's optional `static fields` metadata (which can also add keys that have no runtime
+ * default, e.g. fields declared without an initializer).
+ */
+export declare const describeFields: (ctor: abstract new () => unknown) => FieldDescriptor[];
+/** Describe an aspect class for the inspector: accessor name + class name + editable fields. */
+export declare const describeAspect: (ctor: abstract new () => unknown) => AspectClassInfo;