murow 0.0.70 → 0.0.72

package/dist/types/renderer/prefab-bucket/index.d.ts

@@ -0,0 +1,113 @@
+/**
+ * BasePrefabBucket — generic, renderer-agnostic registry of reusable spawn
+ * templates. Backends (e.g. `@murow/webgpu`) extend this with specialized
+ * spec/prefab unions; most users want the concrete `PrefabBucket` class
+ * exported alongside this one (see `./prefab-bucket-concrete.ts`).
+ *
+ * Lifecycle:
+ *   1. `add()` / `addAll()` collect specs (sync, no I/O)
+ *   2. `load()` resolves all async work (fetch, parse) in parallel
+ *   3. `get()` returns parsed prefabs by id; the bucket is now frozen
+ *
+ * Typed ids: with `const` generics, `bucket.get('typo')` is a compile-time
+ * error once the bucket has been populated. The id-to-spec mapping is
+ * threaded through generics so subclasses can narrow `get()`'s return type
+ * to the specific prefab variant for that id (not just the union).
+ */
+import { EventSystem } from '../../core/events';
+export type PrefabMode = '2d' | '3d';
+/**
+ * `T | (string & {})` — accept a literal `T` (for autocomplete) but don't
+ * collapse to plain `string`. Lets callers pass any string while still getting
+ * suggestions for the known set.
+ */
+export type StringOr<T extends string> = T | (string & {});
+export interface PrefabSpecBase {
+    readonly type: string;
+    readonly id: string;
+    /** Optional user-defined sidecar data carried through to the parsed prefab. */
+    readonly metadata?: Record<string, unknown>;
+}
+export interface PrefabBase {
+    readonly type: string;
+    readonly id: string;
+    /** User-defined sidecar data passed through from the spec. */
+    readonly metadata?: Record<string, unknown>;
+}
+/** `clips-changed` fires when a prefab's animation set is mutated by lazy load/unload. */
+export type PrefabBucketEvents = [
+    [
+        'clips-changed',
+        {
+            prefabId: string;
+            added: readonly string[];
+            removed: readonly string[];
+        }
+    ]
+];
+/** Context passed to each parser at load time, carrying the bucket's shared event channel. */
+export interface PrefabParserContext {
+    readonly events: EventSystem<PrefabBucketEvents>;
+}
+/**
+ * Pluggable parser registry — keyed by spec `type`. Each entry knows how to turn
+ * one variant of spec into its parsed prefab. The bucket itself is mode-agnostic;
+ * the webgpu package (or any other backend) registers parsers at construction.
+ */
+export type PrefabParser<Spec extends PrefabSpecBase = PrefabSpecBase, Prefab extends PrefabBase = PrefabBase> = (spec: Spec, ctx: PrefabParserContext) => Promise<Prefab> | Prefab;
+export type PrefabParserMap<Spec extends PrefabSpecBase, Prefab extends PrefabBase> = Record<string, PrefabParser<Spec, Prefab>>;
+export declare class BasePrefabBucket<M extends PrefabMode = PrefabMode, Spec extends PrefabSpecBase = PrefabSpecBase, Prefab extends PrefabBase = PrefabBase, Specs extends Record<string, Spec> = {}> {
+    readonly mode: M;
+    /** Shared notification channel — see `PrefabBucketEvents`. */
+    readonly events: EventSystem<PrefabBucketEvents>;
+    private parsers;
+    private pending;
+    private pendingIds;
+    private prefabs;
+    constructor(mode: M, parsers?: PrefabParserMap<Spec, Prefab>);
+    /** Add a single spec. Throws if id is a duplicate or if the bucket is already loaded. */
+    add<const S extends Spec>(spec: S): BasePrefabBucket<M, Spec, Prefab, Specs & {
+        [K in S['id']]: S;
+    }>;
+    /**
+     * Add multiple specs. Validates the whole batch (ids unique, not loaded) before
+     * committing, so the bucket never lands in a half-applied state.
+     */
+    addAll<const Ss extends readonly Spec[]>(specs: Ss): BasePrefabBucket<M, Spec, Prefab, Specs & {
+        [K in Ss[number]['id']]: Extract<Ss[number], {
+            id: K;
+        }>;
+    }>;
+    /** Load all pending specs in parallel. Idempotent if already loaded. */
+    load(): Promise<void>;
+    /**
+     * Returns the parsed prefab by id. The default return type is the prefab
+     * union; subclasses may pass a second generic `R` to narrow the return
+     * type per-id (e.g. mapping `Specs[K]` to its concrete prefab variant).
+     *
+     * Accepts any string at runtime but offers autocomplete for the known ids.
+     */
+    get<K extends keyof Specs & string, R extends Prefab = Prefab>(id: StringOr<K>): R;
+    /** True once `load()` has resolved. */
+    get loaded(): boolean;
+    /** Number of prefabs in the bucket (pending if not loaded, parsed if loaded). */
+    get size(): number;
+    /** All parsed prefabs. Throws if not loaded yet. Order is registration order. */
+    entries(): Prefab[];
+    /**
+     * Return all parsed prefabs whose `type` matches the given discriminator.
+     * The default return type is the prefab union narrowed structurally;
+     * subclasses may pass a second generic `R` to narrow further per-type.
+     *
+     * Accepts any string at runtime; offers autocomplete for the known types.
+     */
+    getAllByType<T extends Prefab['type'] & string, R extends Prefab = Extract<Prefab, {
+        type: T;
+    }>>(type: StringOr<T>): R[];
+    /**
+     * Drop every runtime-loaded clip across all prefabs, restoring each to
+     * its parse-time animation set. Called by the renderer on destroy so
+     * a kept-alive bucket doesn't carry runtime state into the next session.
+     */
+    resetAnimations(): void;
+}

package/dist/types/renderer/prefab-bucket/parsers.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Spec parsers — pure functions that turn a prefab spec into its parsed prefab.
+ * Used by createPrefabBucket; not part of the public surface.
+ */
+import type { PrefabParserMap } from './index';
+import type { Prefab2D, Prefab2DSpec, Prefab3D, Prefab3DSpec } from './specs';
+export declare const parsers3d: PrefabParserMap<Prefab3DSpec, Prefab3D>;
+export declare const parsers2d: PrefabParserMap<Prefab2DSpec, Prefab2D>;

package/dist/types/renderer/prefab-bucket/specs.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Prefab spec / prefab type unions.
+ *
+ * Specs describe what to load (URLs, sizes, options). Prefabs are the
+ * parsed CPU-side result — the renderer reads these at init() to size
+ * GPU buffers and uploads them; user code retrieves them by id and
+ * passes them to `addInstance` / `addSprite`.
+ *
+ * These types are renderer-agnostic. The actual GPU upload lives in
+ * specific backends (e.g. `@murow/webgpu`).
+ */
+import type { ParsedGltf } from '../gltf/parser';
+import type { ParsedSpritesheet } from '../spritesheet/parser';
+/**
+ * Extracts the spec's `metadata` literal type for the parsed prefab.
+ * Missing metadata defaults to `{}` at parse time, so the parsed prefab's
+ * `metadata` field is always present — no `?.` needed.
+ *
+ * - Required field → exact literal type (e.g. `{ scale: 0.5 }`)
+ * - Optional field → `NonNullable<M>` (you know the field is there at runtime,
+ *                    but its shape isn't pinned because the spec didn't pin it)
+ * - Absent         → `Record<string, unknown>` (default open shape)
+ */
+type MetadataOf<S> = S extends {
+    readonly metadata: infer M;
+} ? M : S extends {
+    readonly metadata?: infer M;
+} ? NonNullable<M> : Record<string, unknown>;
+export interface GltfSpec {
+    readonly type: 'gltf';
+    /** Unique identifier for the prefab. */
+    readonly id: string;
+    /** URL to the .gltf or .glb file. */
+    readonly src: string;
+    /** Optional whitelist of animation clip names to keep. Defaults to all. Filter them here and get type-safety and more performance. */
+    readonly animations?: readonly string[];
+    /**
+     * Release the source glTF JSON + accessor reader after parse. Saves
+     * memory but removes `loadAnimations` / `unloadAnimations` at runtime
+     * and the type level.
+     */
+    readonly freezeAnimations?: boolean;
+    /** Optional user-defined sidecar data (scale, speed, gameplay hints, etc). */
+    readonly metadata?: Record<string, unknown>;
+}
+export interface GridSpec {
+    readonly type: 'grid';
+    /** Unique identifier for the prefab. */
+    readonly id: string;
+    readonly size: number;
+    readonly step: number;
+    readonly lineWidth: number;
+    /** Optional user-defined sidecar data (scale, speed, gameplay hints, etc). */
+    readonly metadata?: Record<string, unknown>;
+}
+export type Prefab3DSpec = GltfSpec | GridSpec;
+/**
+ * Map a spec's `animations` tuple to a record-keyed-by-name. Used to type
+ * `GltfPrefab.animations` so `prefab.animations.Run` is a string literal
+ * (and `prefab.animations.Typo` is a compile-time error).
+ */
+export type AnimationsRecord<A extends readonly string[]> = {
+    readonly [K in A[number]]: K;
+};
+/** Animation fields for a spec with a non-empty literal `animations` tuple. */
+type NarrowAnimations<S extends GltfSpec> = {
+    readonly animations: AnimationsRecord<Extract<S['animations'], readonly string[]>>;
+    readonly animationList: Extract<S['animations'], readonly string[]>;
+};
+/** Animation fields for a spec where `animations` was declared optional (default). */
+type WideAnimations = {
+    readonly animations?: Record<string, string>;
+    readonly animationList?: readonly string[];
+};
+/** Lazy clip-management methods. Present when the spec didn't set `freezeAnimations: true`. */
+export type UnfrozenAnimationMethods = {
+    /** Decode and pack clips by name. Already-loaded names are no-ops; unknown names throw. */
+    loadAnimations(names: readonly string[]): Promise<void>;
+    /** Drop clips from the packed buffer. No-op for clips that aren't loaded. */
+    unloadAnimations(names: readonly string[]): void;
+    /** Restore the prefab to its spec-declared (parse-time) animation set. */
+    resetAnimations(): void;
+};
+/** Optional-method version of `UnfrozenAnimationMethods`, used on the wide-union `GltfPrefab<GltfSpec>`. */
+type OptionalAnimationMethods = {
+    loadAnimations?: UnfrozenAnimationMethods['loadAnimations'];
+    unloadAnimations?: UnfrozenAnimationMethods['unloadAnimations'];
+    resetAnimations?: UnfrozenAnimationMethods['resetAnimations'];
+};
+/** Common (non-conditional) fields of every parsed glTF prefab. */
+type GltfPrefabBase<S extends GltfSpec> = {
+    readonly type: 'gltf';
+    readonly id: S['id'];
+    readonly parsed: ParsedGltf;
+    readonly skinnedPartCount: number;
+    readonly jointCount: number;
+    /** Total vertices across all primitives. */
+    readonly totalVertexCount: number;
+    /** Passed through from the spec. */
+    readonly metadata: MetadataOf<S>;
+};
+/**
+ * Animation record/list fields, narrowed by what the spec declared:
+ *   - literal `animations` tuple → narrow record + tuple
+ *   - `animations?` (declared optional) → wide record + array
+ *   - field absent → no animation fields
+ */
+type GltfPrefabAnimationFields<S extends GltfSpec> = S extends {
+    animations: readonly [string, ...string[]];
+} ? NarrowAnimations<S> : S extends {
+    animations?: readonly string[] | undefined;
+} ? WideAnimations : {};
+/** Pull out the `freezeAnimations` literal: `true`/`false` if pinned, `boolean` if wide, `never` if absent. */
+type FreezeFlagOf<S> = S extends {
+    freezeAnimations?: infer F;
+} ? F : never;
+/**
+ * Lazy-method narrowing:
+ *   - wide spec (`freezeAnimations?: boolean`) → optional methods, so the
+ *     union `Prefab3D` doesn't re-add them to a narrowed-frozen variant
+ *   - literal `true` → no methods
+ *   - literal `false` or absent → required methods
+ */
+type GltfPrefabLazyMethods<S extends GltfSpec> = boolean extends FreezeFlagOf<S> ? OptionalAnimationMethods : S extends {
+    freezeAnimations: true;
+} ? {} : UnfrozenAnimationMethods;
+/** Parsed glTF prefab, with `id`, `metadata`, `animations`, and `freezeAnimations` narrowed by the spec literal. */
+export type GltfPrefab<S extends GltfSpec = GltfSpec> = GltfPrefabBase<S> & GltfPrefabAnimationFields<S> & GltfPrefabLazyMethods<S>;
+export interface GridPrefab<S extends GridSpec = GridSpec> {
+    readonly type: 'grid';
+    readonly id: S['id'];
+    readonly size: number;
+    readonly step: number;
+    readonly lineWidth: number;
+    readonly metadata: MetadataOf<S>;
+}
+export type Prefab3D = GltfPrefab | GridPrefab;
+export interface SpritesheetSpec {
+    readonly type: 'spritesheet';
+    readonly id: string;
+    /** URL to the image. */
+    readonly src: string;
+    readonly frameWidth?: number;
+    readonly frameHeight?: number;
+    /** URL to a texture-packer JSON file. Mutually exclusive with frameWidth/frameHeight. */
+    readonly data?: string;
+    readonly metadata?: Record<string, unknown>;
+}
+export type Prefab2DSpec = SpritesheetSpec;
+export interface SpritesheetPrefab<S extends SpritesheetSpec = SpritesheetSpec> {
+    readonly type: 'spritesheet';
+    readonly id: S['id'];
+    readonly parsed: ParsedSpritesheet;
+    readonly frameCount: number;
+    readonly width: number;
+    readonly height: number;
+    readonly metadata: MetadataOf<S>;
+}
+export type Prefab2D = SpritesheetPrefab;
+/**
+ * Maps a spec variant to its concrete parsed prefab variant. Used by the
+ * bucket's `get()` so `bucket.get('minion')` returns `GltfPrefab` directly,
+ * not the discriminated union.
+ */
+export type PrefabFor<S> = S extends GltfSpec ? GltfPrefab<S> : S extends GridSpec ? GridPrefab<S> : S extends SpritesheetSpec ? SpritesheetPrefab<S> : never;
+export {};

package/dist/types/renderer/spritesheet/helpers.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Pure spritesheet helpers — UV math and image loading.
+ *
+ * Renderer-agnostic. The actual GPU-bound `Spritesheet` class (with `GPUTexture` /
+ * `GPUSampler`) lives in the webgpu package.
+ */
+import type { SpriteUV } from '../types';
+export interface GridSpritesheetConfig {
+    image: string;
+    frameWidth: number;
+    frameHeight: number;
+}
+export interface TexturePackerFrame {
+    frame: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+}
+export interface TexturePackerData {
+    frames: Record<string, TexturePackerFrame>;
+    meta: {
+        size: {
+            w: number;
+            h: number;
+        };
+    };
+}
+export interface SpritesheetConfig {
+    image: string;
+    frameWidth?: number;
+    frameHeight?: number;
+    data?: string;
+}
+export declare function computeGridUVs(imageWidth: number, imageHeight: number, frameWidth: number, frameHeight: number): SpriteUV[];
+export declare function computeTexturePackerUVs(data: TexturePackerData): SpriteUV[];
+export declare function loadImage(url: string): Promise<ImageBitmap>;

package/dist/types/renderer/spritesheet/parser.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Spritesheet parser — fetches an image (and optionally a texture-packer JSON)
+ * and returns CPU-side data ready for GPU upload. Pure: no device, no GPU buffers.
+ *
+ * The renderer's `loadSpritesheet` is a thin wrapper that calls this then uploads.
+ * Splitting parse from upload lets callers fetch all spritesheets in parallel
+ * (via `Promise.all`) before a renderer exists.
+ */
+import type { SpriteUV, SpritesheetSource } from '../types';
+/** CPU-side result of parsing a spritesheet source. */
+export interface ParsedSpritesheet {
+    bitmap: ImageBitmap;
+    uvs: SpriteUV[];
+    width: number;
+    height: number;
+}
+/**
+ * Parse a spritesheet source: fetch the image, decode it, and resolve UVs.
+ * Does no GPU work. Safe to call in parallel; safe to call before a renderer exists.
+ */
+export declare function parseSpritesheet(source: SpritesheetSource): Promise<ParsedSpritesheet>;

package/dist/types/renderer/types.d.ts

@@ -0,0 +1,89 @@
+import type { Ray3D } from '../core/ray/ray-3d';
+export type ClearColor = [r: number, g: number, b: number, a: number];
+export interface RendererOptions {
+    clearColor?: ClearColor;
+    /** Automatically resize the canvas and reconfigure the GPU context on window resize. */
+    autoResize?: boolean;
+}
+export interface Renderer2DOptions extends RendererOptions {
+    /**
+     * Sprite instance budget. Optional when a prefab bucket is provided —
+     * the renderer will derive a sensible default from `maxInstances`.
+     */
+    maxSprites?: number;
+}
+export interface Renderer3DOptions extends RendererOptions {
+    /**
+     * Non-skinned instance budget. Optional when a prefab bucket is provided —
+     * the renderer will derive a sensible default from the bucket.
+     */
+    maxModels?: number;
+    enableLighting?: boolean;
+}
+export interface Camera2DState {
+    x: number;
+    y: number;
+    zoom: number;
+    rotation: number;
+    setPosition(x: number, y: number): void;
+    move(x: number, y: number): void;
+    screenToWorld(screenX: number, screenY: number): [number, number];
+}
+export interface Camera3DState {
+    position: [x: number, y: number, z: number];
+    target: [x: number, y: number, z: number];
+    up: [x: number, y: number, z: number];
+    fov: number;
+    near: number;
+    far: number;
+    aspect: number;
+    movement: 'local' | 'grounded' | 'global';
+    setPosition(x: number, y: number, z: number): void;
+    move(right: number, up: number, forward: number): void;
+    screenToRay(screenX: number, screenY: number): Ray3D;
+}
+export interface SpritesheetSource {
+    image: string;
+    frameWidth?: number;
+    frameHeight?: number;
+    data?: string;
+}
+export interface SpriteOptions {
+    sheet: SpritesheetHandle;
+    /** Frame index into the spritesheet. Defaults to 0. */
+    sprite?: number;
+    /** World position. Defaults to `[0, 0]`. */
+    position?: readonly [x: number, y: number];
+    layer?: number;
+    /** Per-axis scale. Pass a single number to scale uniformly. Defaults to `[1, 1]`. */
+    scale?: number | readonly [x: number, y: number];
+    /** Rotation in radians. Defaults to 0. */
+    rotation?: number;
+    opacity?: number;
+    flipX?: boolean;
+    flipY?: boolean;
+    tint?: readonly [r: number, g: number, b: number, a: number];
+}
+export interface SpritesheetHandle {
+    readonly id: number;
+    readonly frameCount: number;
+    getUV(spriteIndex: number): SpriteUV;
+}
+export interface SpriteUV {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+export interface SpriteHandle {
+    readonly slot: number;
+    x: number;
+    y: number;
+    rotation: number;
+    scaleX: number;
+    scaleY: number;
+    opacity: number;
+    layer: number;
+    flipX: boolean;
+    flipY: boolean;
+}