murow 0.0.70 → 0.0.72

package/dist/{game → types/game}/loop/loop.d.ts

@@ -4,12 +4,12 @@ import { InputManager } from "../../core/input";
  * GameLoop class that manages the main game loop with tick events and optional rendering.
  * It supports both client and server types, emitting appropriate events for both.
  */
-export declare class GameLoop<T extends DriverType = DriverType> {
-    options: GameLoopOptions & {
-        type: T;
-    };
-    private _driver;
+export declare class GameLoop<T extends GameLoopType = DriverType> {
+    options: GameLoopOptions<T>;
+    private _driver?;
     private _input;
+    private readonly _isClient;
+    private readonly _isManual;
     /**
      * FixedTicker instance that handles tick timing and updates.
      */
@@ -17,7 +17,7 @@ export declare class GameLoop<T extends DriverType = DriverType> {
     /**
      * Event emitter system for the game loop, emitting various lifecycle events.
      */
-    events: Events;
+    events: EventSystem<BaseEvents> & T extends ClientLike ? EventSystem<ClientEvents> : EventSystem<ServerEvents>;
     /**
      * Current frames per second (FPS) measurement.
      */
@@ -25,10 +25,12 @@ export declare class GameLoop<T extends DriverType = DriverType> {
     /**
      * Current status of the game loop: 'running', 'paused', or 'stopped'.
      */
-    status: 'running' | 'paused' | 'stopped';
-    constructor(options: GameLoopOptions & {
-        type: T;
-    });
+    status: "running" | "paused" | "stopped";
+    private _tickData;
+    private _skipData;
+    private _renderData;
+    constructor(options: GameLoopOptions<T>);
+    step(deltaTime: number): void;
     /**
      * Pauses the game ticker and emits a 'toggle-pause' event.
      */
@@ -46,15 +48,15 @@ export declare class GameLoop<T extends DriverType = DriverType> {
      */
     stop(): void;
 }
-interface GameLoopOptions {
+interface GameLoopOptions<T extends GameLoopType> {
     tickRate: number;
-    type: DriverType;
-    onTick?: (dt: number, tick: number, input: ReturnType<InputManager['snapshot']>) => void;
-    onRender?: (dt: number, alpha: number, input: ReturnType<InputManager['snapshot']>) => void;
+    type: T;
+    onTick?: (dt: number, tick: number, input: ReturnType<InputManager["snapshot"]>) => void;
+    onRender?: (dt: number, alpha: number, input: ReturnType<InputManager["peek"]>) => void;
 }
 type BaseEvents = [
     [
-        'start',
+        "start",
         {
             /**
              * Timestamp when the loop was started.
@@ -63,7 +65,7 @@ type BaseEvents = [
         }
     ],
     [
-        'pre-tick',
+        "pre-tick",
         {
             /**
              * Current tick number.
@@ -78,11 +80,11 @@ type BaseEvents = [
              *
              * **Only available in client loops.**
              */
-            input: ReturnType<InputManager['snapshot']>;
+            input: ReturnType<InputManager["snapshot"]>;
         }
     ],
     [
-        'tick',
+        "tick",
         {
             /**
              * Current tick number.
@@ -97,15 +99,15 @@ type BaseEvents = [
              *
              * **Only available in client loops.**
              */
-            input: ReturnType<InputManager['snapshot']>;
+            input: ReturnType<InputManager["snapshot"]>;
         }
     ],
     [
-        'post-tick',
+        "post-tick",
         {
             /**
-            * Current tick number.
-            */
+             * Current tick number.
+             */
             tick: number;
             /**
              * Delta time since the last tick.
@@ -116,11 +118,11 @@ type BaseEvents = [
              *
              * **Only available in client loops.**
              */
-            input: ReturnType<InputManager['snapshot']>;
+            input: ReturnType<InputManager["snapshot"]>;
         }
     ],
     [
-        'skip',
+        "skip",
         {
             /**
              * Number of ticks that were skipped.
@@ -129,7 +131,7 @@ type BaseEvents = [
         }
     ],
     [
-        'stop',
+        "stop",
         {
             /**
              * Timestamp when the loop was stopped.
@@ -138,7 +140,7 @@ type BaseEvents = [
         }
     ],
     [
-        'toggle-pause',
+        "toggle-pause",
         {
             /**
              * Current paused state of the loop.
@@ -158,14 +160,16 @@ type BaseEvents = [
 type ClientEvents = [
     ...BaseEvents,
     [
-        'render',
+        "render",
         {
             deltaTime: number;
             alpha: number;
-            input: ReturnType<InputManager['snapshot']>;
+            input: ReturnType<InputManager["peek"]>;
         }
     ]
 ];
 type ServerEvents = BaseEvents;
-type Events = EventSystem<ClientEvents | ServerEvents>;
+type Manual = "manual-client" | "manual-server";
+type ClientLike = "client" | "manual-client";
+export type GameLoopType = DriverType | Manual;
 export {};

package/dist/{index.d.ts → types/index.d.ts}

@@ -19,3 +19,4 @@ export * from "./protocol";
 export * from "./net";
 export * from "./ecs";
 export * from "./game";
+export * from "./renderer";

package/dist/{net → types/net}/index.d.ts

@@ -14,8 +14,8 @@
  *
  * @example
  * ```typescript
- * import { ServerNetwork, ClientNetwork } from '@mococa/net';
- * import { BunWebSocketServerTransport } from '@mococa/net/transports/bun-websocket';
+ * import { ServerNetwork, ClientNetwork } from 'murow/net';
+ * import { BunWebSocketServerTransport } from 'murow/net/transports/bun-websocket';
  * import { IntentRegistry, SnapshotRegistry } from '@mococa/protocol';
  *
  * // Server setup

package/dist/types/renderer/base/renderer-2d.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Abstract base for 2D renderers. Defines the sprite-based rendering API.
+ */
+import { BaseRenderer } from "./renderer";
+import type { Camera2DState, Renderer2DOptions, SpriteHandle, SpriteOptions, SpritesheetHandle, SpritesheetSource } from "../types";
+export declare abstract class Base2DRenderer extends BaseRenderer<Renderer2DOptions> {
+    readonly maxSprites: number;
+    abstract readonly camera: Camera2DState;
+    constructor(canvas: HTMLCanvasElement, options: Renderer2DOptions);
+    abstract loadSpritesheet(source: SpritesheetSource): Promise<SpritesheetHandle>;
+    abstract addSprite(options: SpriteOptions): SpriteHandle;
+    abstract removeSprite(sprite: SpriteHandle): void;
+}

package/dist/types/renderer/base/renderer-3d.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Abstract base for 3D renderers. Defines the model/instance-based rendering API.
+ */
+import { BaseRenderer } from "./renderer";
+import type { Camera3DState, Renderer3DOptions } from "../types";
+export declare abstract class Base3DRenderer extends BaseRenderer<Renderer3DOptions> {
+    readonly maxModels: number;
+    abstract readonly camera: Camera3DState;
+    constructor(canvas: HTMLCanvasElement, options: Renderer3DOptions);
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Abstract base for all renderers. Provides lifecycle and canvas management.
+ */
+import type { ClearColor, RendererOptions } from "../types";
+export declare abstract class BaseRenderer<TOptions extends RendererOptions = RendererOptions> {
+    readonly canvas: HTMLCanvasElement;
+    protected readonly options: TOptions;
+    protected _clearColor: ClearColor;
+    protected _width: number;
+    protected _height: number;
+    protected _initialized: boolean;
+    constructor(canvas: HTMLCanvasElement, options: TOptions);
+    get clearColor(): ClearColor;
+    set clearColor(value: ClearColor);
+    get width(): number;
+    get height(): number;
+    get initialized(): boolean;
+    abstract init(): Promise<void>;
+    abstract render(alpha: number): void;
+    abstract destroy(): void;
+}

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

@@ -0,0 +1,43 @@
+/**
+ * Pure glTF parsing helpers — container decoding, primitive extraction, and
+ * transform baking. No fetch, no GPU, no closure state.
+ */
+import type { SkinData, AccessorReader } from './skin-parser';
+/**
+ * Decode a fetched glTF payload — either a JSON .gltf or a binary .glb container —
+ * into the parsed JSON object and (for .glb) the embedded binary chunk.
+ */
+export declare function decodeGltfContainer(arrayBuffer: ArrayBuffer, url: string): {
+    gltf: any;
+    glbBinaryChunk: ArrayBuffer | null;
+};
+/**
+ * Validate that every skin referenced by a mesh node is equivalent to the
+ * canonical skin (same joint nodes in any order, same IBMs) and build a joint
+ * remap from each non-canonical skin's index space into canonical's.
+ *
+ * Throws if any skin is structurally incompatible — truly independent skeletons
+ * in one file are not supported yet.
+ */
+export declare function validateAndBuildSkinRemaps(gltf: any, canonicalSkinIndex: number, skinData: SkinData, skinJointRemaps: Map<number, Uint16Array>, getAccessorData: AccessorReader): void;
+/** Remap a primitive's joint indices into canonical joint space, if needed. */
+export declare function remapSkinAttributes(attrs: {
+    joints: Uint16Array;
+    weights: Float32Array;
+}, meshSkinIndex: number | undefined, canonicalSkinIndex: number | undefined, skinJointRemaps: Map<number, Uint16Array>): {
+    joints: Uint16Array;
+    weights: Float32Array;
+};
+/** Extract per-primitive vertex attributes (positions, normals, UVs, indices) from glTF accessors. */
+export declare function extractPrimitiveAttributes(primitive: any, getAccessorData: AccessorReader): {
+    positions: Float32Array;
+    normals: Float32Array | undefined;
+    uvs: Float32Array | undefined;
+    indices: Uint16Array | Uint32Array | undefined;
+};
+/**
+ * Bake a column-major mat4 into positions (in place) and re-orient + renormalize
+ * normals. Used to fold a non-skinned mesh node's transform into its vertices
+ * so the renderer doesn't need to know about per-mesh node transforms.
+ */
+export declare function bakeTransformIntoVertices(positions: Float32Array, normals: Float32Array | undefined, mm: Float32Array): void;

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

@@ -0,0 +1,49 @@
+import { type SkinData, type AnimationClipData, type PrimitiveSkinAttributes } from './skin-parser';
+/** Per-primitive CPU data ready for upload. */
+export interface ParsedGltfPrimitive {
+    positions: Float32Array;
+    normals?: Float32Array;
+    uvs?: Float32Array;
+    indices?: Uint16Array | Uint32Array;
+    texture?: ImageBitmap;
+    /** Present iff the primitive belongs to a skinned mesh. */
+    skinAttrs?: PrimitiveSkinAttributes;
+    /** True iff this primitive should be loaded as a skinned model. */
+    skinned: boolean;
+}
+/**
+ * Retained parser state for decoding more clips after the initial `parseGltf`.
+ * Null when the spec opted out via `freezeAnimations: true`.
+ */
+export interface ParsedGltfSource {
+    readonly availableAnimations: readonly string[];
+    /** Returns null if the clip has no channels targeting joints in this skin. Throws on unknown name. */
+    decodeAnimation(name: string): AnimationClipData | null;
+}
+/** Skin + filtered animation clips. Mutated by lazy `loadAnimations` / `unloadAnimations`. */
+export interface ParsedGltfSkin {
+    data: SkinData;
+    animClips: AnimationClipData[];
+}
+/** CPU-side result of parsing a glTF / glb URL. */
+export interface ParsedGltf {
+    /** Source URL the model was loaded from. */
+    src: string;
+    /** One entry per primitive that should become a model part. */
+    primitives: ParsedGltfPrimitive[];
+    /** Skin + filtered animation clips, or null if the model has no skin. */
+    skin: ParsedGltfSkin | null;
+    /** Retained parser state for lazy clip decoding. Null when the spec passed `freezeAnimations: true`. */
+    source: ParsedGltfSource | null;
+}
+export interface ParseGltfOptions {
+    /** Whitelist of clip names to keep. */
+    animations?: string[];
+    /** Release the source JSON + accessor reader after parse. Disables lazy load. */
+    freezeAnimations?: boolean;
+}
+/**
+ * Parse a glTF / .glb file from a URL into CPU-side data.
+ * Does no GPU work. Safe to call in parallel; safe to call before a renderer exists.
+ */
+export declare function parseGltf(url: string, opts?: ParseGltfOptions): Promise<ParsedGltf>;

package/dist/types/renderer/gltf/skeletal-animation.d.ts

@@ -0,0 +1,96 @@
+/**
+ * SkeletalAnimation — CPU-side bone matrix evaluation for skinned meshes.
+ *
+ * Evaluates animation clips by sampling keyframes, computing joint local transforms,
+ * walking the hierarchy, and writing final bone matrices into a pre-allocated buffer.
+ * Zero per-frame allocations.
+ *
+ * Usage:
+ * ```ts
+ * const anim = new SkeletalAnimation(skinData, clips);
+ * const state = anim.createState('walk');
+ *
+ * // Each tick:
+ * anim.update(state, deltaTime, outputMatrices);
+ *
+ * // outputMatrices is a Float32Array view into the bone matrix buffer
+ * ```
+ */
+import type { SkinData, AnimationClipData, AnimationChannel } from './skin-parser';
+export interface SkeletalClip {
+    readonly id: number;
+    readonly name: string;
+    readonly duration: number;
+    readonly channels: AnimationChannel[];
+    readonly loop: boolean;
+}
+export interface PlayOptions {
+    speed?: number;
+    /** Crossfade duration in seconds. 0 = instant switch (default). */
+    crossfade?: number;
+    /** Whether the animation should loop. Default: true. */
+    loop?: boolean;
+    /** Called when the animation clip ends (reaches duration). Fires each loop for looping clips. */
+    onEnd?: () => void;
+}
+export interface SkeletalAnimState {
+    clipId: number;
+    time: number;
+    speed: number;
+    playing: boolean;
+    loop: boolean;
+    prevClipId: number;
+    prevTime: number;
+    prevSpeed: number;
+    blendWeight: number;
+    blendDuration: number;
+    onEnd: () => void;
+}
+export declare class SkeletalAnimation {
+    private clips;
+    private clipsByName;
+    readonly skinData: SkinData;
+    private readonly localMatrices;
+    private readonly worldMatrices;
+    private readonly blendScratch;
+    private readonly originalRestPoseTRS;
+    private readonly currentTRS;
+    private readonly topoOrder;
+    private readonly skelRootMat;
+    constructor(skinData: SkinData, clips: AnimationClipData[]);
+    loadClip(clip: AnimationClipData, loop?: boolean): number;
+    /**
+     * Replace the clip list wholesale. Returns an old-id → new-id remap so
+     * callers can fix in-flight `SkeletalAnimState.clipId` / `prevClipId`
+     * references. Removed clips map to -1.
+     */
+    replaceClips(clips: AnimationClipData[], loop?: boolean): Int32Array;
+    getClipId(name: string): number;
+    getClipNames(): string[];
+    getClip(id: number): SkeletalClip | null;
+    get clipCount(): number;
+    createState(clipIdOrName: number | string, speed?: number, playing?: boolean): SkeletalAnimState;
+    play(state: SkeletalAnimState, clipIdOrName: number | string, opts?: PlayOptions): void;
+    stop(state: SkeletalAnimState): void;
+    resume(state: SkeletalAnimState): void;
+    /**
+     * Advance time and compute bone matrices.
+     * Writes jointCount mat4s into `output` starting at float index `outputOffset`.
+     * Handles crossfade blending automatically.
+     */
+    update(state: SkeletalAnimState, deltaTime: number, output: Float32Array, outputOffset?: number): void;
+    /** Advance clip time with looping/clamping. */
+    private advanceTime;
+    /** Evaluate a clip at a specific time and write bone matrices. */
+    private evaluateClip;
+    /**
+     * Compute bone matrices for the rest/bind pose (no animation).
+     */
+    computeRestPose(output: Float32Array, outputOffset?: number): void;
+    /** Sample an animation channel at time t. Returns 3 or 4 floats. */
+    private sampleChannel;
+    private readonly _scratchVec3;
+    private readonly _scratchQuat;
+    /** Normalized lerp for quaternions (nlerp). */
+    private nlerpQuat;
+}

package/dist/types/renderer/gltf/skin-parser.d.ts

@@ -0,0 +1,107 @@
+export interface SkinData {
+    jointCount: number;
+    /** Node indices for each joint (into the glTF node array). */
+    jointNodeIndices: Uint16Array;
+    /** Inverse bind matrices — jointCount * 16 floats (column-major mat4). */
+    inverseBindMatrices: Float32Array;
+    /** Parent joint index for each joint (-1 for roots). Index into *this* joint list, not the node array. */
+    parentJointIndices: Int16Array;
+    /** World matrix of the skeleton root (non-joint ancestors of root joints). Column-major mat4, 16 floats. Null if identity. */
+    skeletonRootMatrix: Float32Array | null;
+    /** Rest-pose TRS for each joint, packed as [tx, ty, tz, qx, qy, qz, qw, sx, sy, sz]. jointCount * 10 floats. */
+    restPoseTRS: Float32Array;
+}
+export interface AnimationChannel {
+    /** Index into the skin's joint list (not node index). */
+    jointIndex: number;
+    path: 'translation' | 'rotation' | 'scale';
+    timestamps: Float32Array;
+    /** vec3 for translation/scale, vec4 (quaternion xyzw) for rotation. */
+    values: Float32Array;
+    interpolation: 'LINEAR' | 'STEP';
+}
+export interface AnimationClipData {
+    name: string;
+    duration: number;
+    channels: AnimationChannel[];
+}
+export interface PrimitiveSkinAttributes {
+    /** Joint indices — vertexCount * 4. */
+    joints: Uint16Array;
+    /** Joint weights — vertexCount * 4. */
+    weights: Float32Array;
+}
+export type AccessorReader = (accessorIndex: number) => {
+    data: Float32Array | Uint16Array | Uint32Array | Uint8Array;
+    count: number;
+    elementSize: number;
+};
+/**
+ * Parse skin data from a glTF skin definition.
+ */
+export declare function parseSkin(gltf: any, skinIndex: number, getAccessorData: AccessorReader): SkinData;
+/**
+ * Decode one glTF animation entry into an `AnimationClipData`.
+ * Returns null if no channels target joints in this skin, or all channels use
+ * an unsupported interpolation mode.
+ */
+export declare function decodeAnimationClip(anim: any, nameFallback: string, nodeToJoint: ReadonlyMap<number, number>, getAccessorData: AccessorReader): AnimationClipData | null;
+/** Node→joint index map for a parsed skin. Build once and reuse when decoding clips lazily. */
+export declare function buildNodeToJointMap(skinData: SkinData): Map<number, number>;
+/**
+ * Parse animation clips that target joints in a skin.
+ */
+export declare function parseAnimations(gltf: any, skinData: SkinData, getAccessorData: AccessorReader): AnimationClipData[];
+export declare function parsePrimitiveSkinAttributes(primitive: any, getAccessorData: AccessorReader): PrimitiveSkinAttributes | null;
+/**
+ * Get a node's local TRS as [tx, ty, tz, qx, qy, qz, qw, sx, sy, sz].
+ */
+export declare function getNodeTRS(node: any): Float32Array;
+/** Packed GPU-ready animation data for all skins/clips loaded so far. */
+export interface PackedAnimationData {
+    /** Flat channel descriptors: [jointIndex, pathAndInterp, keyframeCount, dataOffset] per channel */
+    channels: {
+        jointIndex: number;
+        pathAndInterp: number;
+        keyframeCount: number;
+        dataOffset: number;
+    }[];
+    /** Flat keyframe data: timestamps then values for each channel */
+    keyframeData: number[];
+    /** Clip descriptors: [channelStart, channelCount, duration, loop] */
+    clips: {
+        channelStart: number;
+        channelCount: number;
+        duration: number;
+        looping: number;
+    }[];
+    /** Per-skin entries */
+    skins: {
+        jointCount: number;
+        parentOffset: number;
+        topoOffset: number;
+        ibmOffset: number;
+        restTRSOffset: number;
+        skelRootMatIndex: number;
+        clipOffset: number;
+        jointLookupStart: number;
+    }[];
+    /** Flat parent joint indices (i32), all skins concatenated */
+    parentIndices: number[];
+    /** Flat topological order (u32), all skins concatenated */
+    topoOrder: number[];
+    /** Flat inverse bind matrices (mat4x4, 16 floats each), all skins concatenated */
+    ibmData: number[];
+    /** Flat rest pose TRS (10 floats per joint), all skins concatenated */
+    restTRS: number[];
+    /** Skeleton root matrices (16 floats each), one per skin */
+    skelRootMats: number[];
+    /** Per-joint channel lookup: [clipIdx * maxJoints * 2 + joint * 2] = (channelStart, channelCount) */
+    jointChannelLookup: number[];
+}
+export declare function createPackedAnimationData(): PackedAnimationData;
+/**
+ * Pack a skin + its animations into the flat GPU buffers.
+ * Returns the skin index within the packed data.
+ */
+export declare function packSkinAndAnimations(packed: PackedAnimationData, skinData: SkinData, clips: AnimationClipData[]): number;

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

@@ -0,0 +1,15 @@
+export * from "./types";
+export * from "./base/renderer";
+export * from "./base/renderer-2d";
+export * from "./base/renderer-3d";
+export * from "./math";
+export * from "./gltf/skin-parser";
+export * from "./gltf/parser";
+export { SkeletalAnimation } from "./gltf/skeletal-animation";
+export type { SkeletalClip, SkeletalAnimState, PlayOptions } from "./gltf/skeletal-animation";
+export * from "./spritesheet/helpers";
+export * from "./spritesheet/parser";
+export * from "./prefab-bucket";
+export * from "./prefab-bucket/specs";
+export { PrefabBucket } from "./prefab-bucket/concrete";
+export type { PrefabBucket2D, PrefabBucket3D } from "./prefab-bucket/concrete";

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

@@ -0,0 +1,37 @@
+/**
+ * Shared 3D math utilities for the WebGPU renderer.
+ * All functions operate on Float32Arrays with explicit offsets — zero allocations in hot paths.
+ */
+/**
+ * Write a 4x4 identity matrix into `dst` at `offset`.
+ */
+export declare function mat4Identity(dst: Float32Array, offset: number): void;
+/**
+ * Create a new 4x4 identity matrix.
+ */
+export declare function mat4IdentityNew(): Float32Array;
+/**
+ * Write a column-major 4x4 matrix from TRS (translation, quaternion rotation, scale)
+ * into `dst` at `offset`.
+ */
+export declare function trsToMat4(tx: number, ty: number, tz: number, qx: number, qy: number, qz: number, qw: number, sx: number, sy: number, sz: number, dst: Float32Array, offset: number): void;
+/**
+ * Build a column-major 4x4 matrix from a glTF node's TRS or matrix property.
+ * Allocates and returns a new Float32Array(16).
+ */
+export declare function nodeToMat4(node: {
+    translation?: number[];
+    rotation?: number[];
+    scale?: number[];
+    matrix?: number[];
+}): Float32Array;
+/**
+ * 4x4 matrix multiply: dst[dO..+16] = a[aO..+16] * b[bO..+16]. Column-major.
+ * Safe when a, b, dst overlap (uses internal temp buffer).
+ */
+export declare function mat4Mul(a: Float32Array, aO: number, b: Float32Array, bO: number, dst: Float32Array, dO: number): void;
+/**
+ * 4x4 matrix multiply that allocates and returns a new Float32Array(16).
+ * Use for load-time operations, not per-frame hot paths.
+ */
+export declare function mat4MulNew(a: Float32Array, b: Float32Array): Float32Array;

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

@@ -0,0 +1,55 @@
+/**
+ * PrefabBucket — typed registry of reusable spawn templates.
+ *
+ * Pass `'2d'` or `'3d'` to the constructor to pick the spec/prefab universe.
+ * Parsers are wired implicitly; user code only sees `add`, `addAll`, `load`, `get`.
+ *
+ * ```ts
+ * const bucket = new PrefabBucket('3d')
+ *     .add({ type: 'gltf', id: 'minion', url: '/minion.glb' })
+ *     .add({ type: 'grid', id: 'floor', size: 20, step: 0.33, lineWidth: 0.001 });
+ *
+ * await bucket.load();
+ *
+ * bucket.get('minion');  // typed as GltfPrefab — `.animations`, `.jointCount`, …
+ * bucket.get('floor');   // typed as GridPrefab — `.size`, `.step`, `.lineWidth`
+ * bucket.get('typo');    // ❌ TS error: '"typo"' not in '"minion" | "floor"'
+ * ```
+ */
+import { BasePrefabBucket, type StringOr } from './index';
+import type { Prefab2D, Prefab2DSpec, Prefab3D, Prefab3DSpec, PrefabFor } from './specs';
+type SpecForMode<M> = M extends '3d' ? Prefab3DSpec : Prefab2DSpec;
+type PrefabUnionForMode<M> = M extends '3d' ? Prefab3D : Prefab2D;
+/**
+ * Registry of prefab specs and their parsed variants. The bucket tracks the mapping of
+ * spec `id` strings to their parsed prefab types, so `get` narrows to the correct
+ * prefab type based on the provided id. The bucket is mutable; call `add`/`addAll`
+ * to register new specs and their prefab types. Call `load` to parse all registered
+ * specs and populate the bucket's internal prefab registry.
+ */
+export declare class PrefabBucket<M extends '2d' | '3d' = '3d', Specs extends Record<string, SpecForMode<M>> = {}> extends BasePrefabBucket<M, SpecForMode<M>, PrefabUnionForMode<M>, Specs> {
+    constructor(mode: M);
+    /**
+     * Add a spec. Chains return the subclass type so the bucket variable's
+     * static type accumulates id→spec mappings, enabling `get` to narrow.
+     */
+    add<const S extends SpecForMode<M>>(spec: S): PrefabBucket<M, Specs & {
+        [K in S['id']]: S;
+    }>;
+    addAll<const Ss extends readonly SpecForMode<M>[]>(specs: Ss): PrefabBucket<M, Specs & {
+        [K in Ss[number]['id']]: Extract<Ss[number], {
+            id: K;
+        }>;
+    }>;
+    /**
+     * Return the parsed prefab variant for this id. Narrow type — `get('minion')`
+     * returns `GltfPrefab` (with `.animations`, `.jointCount`), not the union.
+     *
+     * Accepts any string at runtime but autocompletes known ids.
+     */
+    get<K extends keyof Specs & string, R = PrefabFor<Specs[K]>>(id: StringOr<K>): R;
+}
+/** Convenience aliases for explicit mode typing (e.g. function params). */
+export type PrefabBucket2D<Specs extends Record<string, Prefab2DSpec> = {}> = PrefabBucket<'2d', Specs>;
+export type PrefabBucket3D<Specs extends Record<string, Prefab3DSpec> = {}> = PrefabBucket<'3d', Specs>;
+export type { GltfPrefab, GltfSpec, GridPrefab, GridSpec, Prefab2D, Prefab2DSpec, Prefab3D, Prefab3DSpec, PrefabFor, SpritesheetPrefab, SpritesheetSpec, } from './specs';