murow 0.0.70 → 0.0.72

package/dist/webgpu/types/2d/animation.d.ts

@@ -0,0 +1,97 @@
+/**
+ * AnimationController — frame-by-frame spritesheet animation.
+ *
+ * Manages animation clips (sequences of sprite frames with per-frame durations)
+ * and updates sprite handles to show the current frame. Zero allocations in the
+ * update loop — all clip data is pre-allocated typed arrays.
+ *
+ * ECS-independent: works with any system that can call update() per entity.
+ *
+ * Usage:
+ * ```ts
+ * const anim = new AnimationController();
+ *
+ * const runClip = anim.loadClip({
+ *     name: 'run',
+ *     frames: [0, 1, 2, 3],
+ *     durations: [100, 100, 100, 100],
+ *     loop: true,
+ * });
+ *
+ * const state = anim.createState(runClip);
+ * // Each tick:
+ * anim.update(state, deltaTime, spriteHandle);
+ * ```
+ */
+export interface AnimationClip {
+    readonly id: number;
+    readonly name: string;
+    readonly frames: Uint16Array;
+    readonly durations: Float32Array;
+    readonly frameCount: number;
+    readonly totalDuration: number;
+    readonly loop: boolean;
+}
+export interface AnimationState {
+    clipId: number;
+    frame: number;
+    time: number;
+    speed: number;
+    playing: boolean;
+}
+export interface AnimationClipConfig {
+    name: string;
+    frames: number[];
+    durations: number[];
+    loop: boolean;
+}
+/**
+ * Minimal interface for what update() needs to set on a sprite.
+ * Matches SpriteAccessor but doesn't import it — stays decoupled.
+ */
+export interface Animatable {
+    setSpriteId?(id: number): void;
+}
+export declare class AnimationController {
+    private clips;
+    private clipsByName;
+    /**
+     * Register an animation clip. Returns the clip ID.
+     */
+    loadClip(config: AnimationClipConfig): number;
+    /**
+     * Get a clip by name.
+     */
+    getClipId(name: string): number;
+    /**
+     * Get a clip by ID.
+     */
+    getClip(id: number): AnimationClip;
+    /**
+     * Create a new animation state for an entity. This is the per-entity data
+     * that tracks playback progress. Store it however you like (flat array, component, etc).
+     */
+    createState(clipId: number, speed?: number, playing?: boolean): AnimationState;
+    /**
+     * Advance an animation state by deltaTime (in seconds).
+     * Returns the current sprite frame ID, or -1 if not playing.
+     * Zero allocations.
+     */
+    update(state: AnimationState, deltaTime: number): number;
+    /**
+     * Play a different clip on an existing state. Resets frame and time.
+     */
+    play(state: AnimationState, clipId: number, speed?: number): void;
+    /**
+     * Stop playback.
+     */
+    stop(state: AnimationState): void;
+    /**
+     * Resume playback.
+     */
+    resume(state: AnimationState): void;
+    /**
+     * Number of loaded clips.
+     */
+    get clipCount(): number;
+}

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

@@ -0,0 +1,86 @@
+import { Base2DRenderer } from 'murow/renderer';
+import type { Renderer2DOptions, SpriteHandle, SpriteOptions, SpritesheetHandle, SpritesheetSource } from 'murow/renderer';
+import { Camera2D } from '../camera/camera-2d';
+import { type ParsedSpritesheet } from 'murow/renderer';
+import { GeometryBuilder, type GeometryOptions } from '../geometry/geometry-builder';
+import { ComputeBuilder, type ComputeOptions } from '../compute/compute-builder';
+import type { PrefabBucket2D, Prefab2D } from 'murow/renderer';
+export interface WebGPU2DRendererOptions extends Renderer2DOptions {
+    /**
+     * Pre-loaded prefab bucket. When provided, the renderer uploads each prefab
+     * to the GPU during `init()`, and `addSprite({ prefab: bucket.get('id') })`
+     * resolves to the right spritesheet handle. The bucket must have `load()`
+     * resolved before being passed in.
+     */
+    prefabs?: PrefabBucket2D;
+    /**
+     * How many sprite instances you intend to spawn. Used to size buffers when
+     * `maxSprites` is not given explicitly. Defaults to 1024.
+     */
+    maxInstances?: number;
+}
+export declare class WebGPU2DRenderer extends Base2DRenderer {
+    private root;
+    private _device;
+    private context;
+    private _format;
+    get device(): GPUDevice;
+    get format(): GPUTextureFormat;
+    private spriteLayout;
+    private textureLayout;
+    private dynamicData;
+    private staticData;
+    private freeList;
+    private batcher;
+    private staticDirty;
+    private dynamicBuffer;
+    private staticBuffer;
+    private uniformBuffer;
+    private slotIndexBuffer;
+    private slotIndexData;
+    private rawPipeline;
+    private rawSpriteBindGroup;
+    private rawTextureLayout;
+    private rawDynamicBuffer;
+    private rawStaticBuffer;
+    private rawUniformBuffer;
+    private rawSlotIndexBuffer;
+    private sheetBindGroups;
+    private sheets;
+    private nextSheetId;
+    readonly camera: Camera2D;
+    private uniformData;
+    private resizeObserver;
+    private resizeCallbacks;
+    private readonly _prefabs;
+    constructor(canvas: HTMLCanvasElement, options: WebGPU2DRendererOptions);
+    init(): Promise<void>;
+    /**
+     * Upload every prefab in the bucket to the GPU and stash the resulting
+     * SpritesheetHandle on each prefab so `bucket.get(id)` returns something
+     * usable as a sprite source.
+     */
+    private uploadPrefabBucket;
+    private setupResizeObserver;
+    /**
+     * Register a callback that fires when the canvas resizes.
+     * Receives the new width and height in physical pixels.
+     */
+    onResize(callback: (width: number, height: number) => void): void;
+    loadSpritesheet(source: SpritesheetSource): Promise<SpritesheetHandle>;
+    /**
+     * Upload a previously-parsed spritesheet to the GPU. Returns a SpritesheetHandle.
+     * Splitting parse (CPU) from upload (GPU) lets callers parse spritesheets in parallel
+     * before a renderer exists.
+     */
+    uploadParsedSpritesheet(parsed: ParsedSpritesheet): SpritesheetHandle;
+    addSprite(opts: Omit<SpriteOptions, 'sheet'> & {
+        sheet: SpritesheetHandle | Prefab2D;
+    }): SpriteHandle;
+    removeSprite(sprite: SpriteHandle): void;
+    storePreviousState(): void;
+    createGeometry(name: string, options: GeometryOptions): GeometryBuilder;
+    createCompute(name: string, options: ComputeOptions): ComputeBuilder;
+    render(alpha: number): void;
+    destroy(): void;
+}

package/dist/webgpu/types/2d/shader.d.ts

@@ -0,0 +1,61 @@
+import * as d from 'typegpu/data';
+export declare function createSpriteLayout(maxSprites: number): import("typegpu").TgpuBindGroupLayout<{
+    uniforms: {
+        uniform: d.WgslStruct<{
+            viewProjection: d.Mat3x3f;
+            alpha: d.F32;
+            resolution: d.Vec2f;
+        }>;
+    };
+    dynamicInstances: {
+        storage: d.WgslArray<d.WgslStruct<{
+            prevX: d.F32;
+            prevY: d.F32;
+            currX: d.F32;
+            currY: d.F32;
+            prevRotation: d.F32;
+            currRotation: d.F32;
+        }>>;
+    };
+    staticInstances: {
+        storage: d.WgslArray<d.WgslStruct<{
+            scaleX: d.F32;
+            scaleY: d.F32;
+            uvMinX: d.F32;
+            uvMinY: d.F32;
+            uvMaxX: d.F32;
+            uvMaxY: d.F32;
+            layer: d.F32;
+            flipX: d.F32;
+            flipY: d.F32;
+            opacity: d.F32;
+            tintR: d.F32;
+            tintG: d.F32;
+            tintB: d.F32;
+            tintA: d.F32;
+        }>>;
+    };
+    slotIndices: {
+        storage: d.WgslArray<d.U32>;
+    };
+}>;
+export declare function createTextureLayout(): import("typegpu").TgpuBindGroupLayout<{
+    spriteTex: {
+        texture: d.WgslTexture2d<d.F32>;
+    };
+    spriteSampler: {
+        sampler: "filtering";
+    };
+}>;
+export type SpriteDataLayout = ReturnType<typeof createSpriteLayout>;
+export type SpriteTextureLayout = ReturnType<typeof createTextureLayout>;
+export declare function createSpriteVertex(spriteLayout: SpriteDataLayout, _textureLayout: SpriteTextureLayout): import("typegpu").TgpuVertexFn<{}, {
+    vUv: d.Vec2f;
+    vTint: d.Vec4f;
+    vOpacity: d.F32;
+}>;
+export declare function createSpriteFragment(_spriteLayout: SpriteDataLayout, textureLayout: SpriteTextureLayout): import("typegpu").TgpuFragmentFn<{
+    vUv: d.Vec2f;
+    vTint: d.Vec4f;
+    vOpacity: d.F32;
+}, d.Vec4f>;

package/dist/webgpu/types/2d/sprite-accessor.d.ts

@@ -0,0 +1,47 @@
+import type { SpriteHandle } from "murow/renderer";
+export declare class SpriteAccessor implements SpriteHandle {
+    private dynamicData;
+    private staticData;
+    private dynamicBase;
+    private staticBase;
+    private _slot;
+    private _sheetId;
+    private _onStaticDirty;
+    constructor(dynamicData: Float32Array, staticData: Float32Array, slot: number, sheetId: number, onStaticDirty: () => void);
+    get slot(): number;
+    get sheetId(): number;
+    get x(): number;
+    set x(v: number);
+    get y(): number;
+    set y(v: number);
+    get prevX(): number;
+    get prevY(): number;
+    get rotation(): number;
+    set rotation(v: number);
+    get prevRotation(): number;
+    /**
+     * Store current position/rotation as previous (called before tick).
+     */
+    storePrevious(): void;
+    get scaleX(): number;
+    set scaleX(v: number);
+    get scaleY(): number;
+    set scaleY(v: number);
+    get layer(): number;
+    set layer(v: number);
+    get flipX(): boolean;
+    set flipX(v: boolean);
+    get flipY(): boolean;
+    set flipY(v: boolean);
+    get opacity(): number;
+    set opacity(v: number);
+    get tintR(): number;
+    get tintG(): number;
+    get tintB(): number;
+    get tintA(): number;
+    setTint(r: number, g: number, b: number, a?: number): void;
+    get uvMinX(): number;
+    get uvMinY(): number;
+    get uvMaxX(): number;
+    get uvMaxY(): number;
+}

package/dist/webgpu/types/3d/clip-resync-coordinator.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Bridges the bucket's `clips-changed` events to per-skin resync work in the
+ * renderer. The renderer registers `prefabId → skinIndex` at upload time;
+ * subsequent events flag affected skins in a pending set the renderer drains
+ * each frame.
+ */
+import type { PrefabBucket } from 'murow';
+export declare class GltfClipResyncCoordinator {
+    private bucket;
+    private readonly skinIndexByPrefabId;
+    private readonly _pending;
+    constructor(bucket: PrefabBucket);
+    /** Map a prefab id to its index in the renderer's `skinnedModels` list. */
+    registerSkin(prefabId: string, skinIndex: number): void;
+    /** Skin indices whose clip set has changed since the last `clear()`. */
+    get pending(): ReadonlySet<number>;
+    clear(): void;
+    /** Unsubscribe from the bucket and reset its animation clip sets. */
+    dispose(): void;
+}

package/dist/webgpu/types/3d/morph-animation.d.ts

@@ -0,0 +1,69 @@
+/**
+ * MorphAnimation — keyframe-based vertex animation for 3D meshes.
+ *
+ * Stores multiple vertex position snapshots (morph targets) per model.
+ * Each instance has a float `morphTime` that determines which two keyframes
+ * to blend and by how much. The blending happens CPU-side by writing
+ * interpolated positions into the model's vertex buffer.
+ *
+ * This is simpler than GPU-side blending (no shader changes needed) and
+ * works well for small-to-medium meshes with few keyframes.
+ *
+ * Usage:
+ * ```ts
+ * const morph = new MorphAnimation();
+ *
+ * // Load keyframes (each is a flat Float32Array of positions)
+ * const clipId = morph.loadClip({
+ *     name: 'walk',
+ *     keyframes: [frame0Positions, frame1Positions, frame2Positions],
+ *     durations: [100, 100, 100],
+ *     loop: true,
+ * });
+ *
+ * const state = morph.createState(clipId);
+ *
+ * // Each tick: advance time, get interpolated positions
+ * morph.update(state, deltaTime, outputPositions);
+ * ```
+ */
+export interface MorphClip {
+    readonly id: number;
+    readonly name: string;
+    readonly keyframes: Float32Array[];
+    readonly durations: Float32Array;
+    readonly frameCount: number;
+    readonly totalDuration: number;
+    readonly loop: boolean;
+    readonly vertexCount: number;
+}
+export interface MorphState {
+    clipId: number;
+    time: number;
+    speed: number;
+    playing: boolean;
+}
+export interface MorphClipConfig {
+    name: string;
+    keyframes: Float32Array[];
+    durations: number[];
+    loop: boolean;
+}
+export declare class MorphAnimation {
+    private clips;
+    private clipsByName;
+    loadClip(config: MorphClipConfig): number;
+    getClipId(name: string): number;
+    getClip(id: number): MorphClip;
+    createState(clipId: number, speed?: number, playing?: boolean): MorphState;
+    /**
+     * Advance time and write interpolated vertex positions into `output`.
+     * Output must be a Float32Array of vertexCount * 3 floats.
+     * Zero allocations.
+     */
+    update(state: MorphState, deltaTime: number, output: Float32Array): void;
+    play(state: MorphState, clipId: number, speed?: number): void;
+    stop(state: MorphState): void;
+    resume(state: MorphState): void;
+    get clipCount(): number;
+}

package/dist/webgpu/types/3d/morph-animation.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,266 @@
+import { Base3DRenderer } from 'murow/renderer';
+import type { Renderer3DOptions } from 'murow/renderer';
+import { ComputeBuilder, type ComputeOptions } from '../compute/compute-builder';
+import { Camera3D } from '../camera/camera-3d';
+import { type ParsedGltf, type PrefabBucket3D, type Prefab3D, type PlayOptions } from 'murow/renderer';
+export interface ModelData {
+    positions: Float32Array;
+    normals?: Float32Array;
+    uvs?: Float32Array;
+    indices?: Uint16Array | Uint32Array;
+    texture?: ImageBitmap;
+}
+export interface ModelHandle {
+    readonly id: number;
+    readonly vertexCount: number;
+    readonly indexCount: number;
+    readonly skinned: boolean;
+}
+export interface MeshInstanceHandle {
+    readonly slot: number;
+    readonly modelId: number;
+    readonly skinned: boolean;
+    setPosition(x: number, y: number, z: number): void;
+    setRotation(x: number, y: number, z: number): void;
+    setScale(x: number, y: number, z: number): void;
+    play?(name: string, opts?: PlayOptions): void;
+    stop?(): void;
+}
+/** A loaded glTF model — may contain multiple mesh parts that share a skeleton. */
+export interface GltfModel {
+    readonly parts: ModelHandle[];
+    readonly totalVertexCount: number;
+    readonly skinned: boolean;
+    /** Animation clip names available on this model (empty if not skinned). */
+    readonly animations: string[];
+    /** Source URL this model was loaded from. */
+    readonly src: string;
+}
+/** Handle to a spawned instance (single primitive or multi-part glTF). */
+export interface InstanceHandle {
+    setPosition(x: number, y: number, z: number): void;
+    setRotation(x: number, y: number, z: number): void;
+    setScale(x: number, y: number, z: number): void;
+    play?(name: string, opts?: PlayOptions): void;
+    stop?(): void;
+    readonly skinned: boolean;
+}
+export interface MeshInstanceOptions {
+    /**
+     * The model to instance. Either a renderer-internal handle (from `loadGltf`,
+     * `loadModel`, `createGrid`) or a prefab fetched from a `PrefabBucket3D` —
+     * `bucket.get('my-id')`.
+     */
+    model: ModelHandle | GltfModel | Prefab3D;
+    /** World position. Defaults to `[0, 0, 0]`. */
+    position?: readonly [x: number, y: number, z: number];
+    /** Euler rotation in radians. Defaults to `[0, 0, 0]`. */
+    rotation?: readonly [x: number, y: number, z: number];
+    /** Per-axis scale. Pass a single number to scale uniformly. Defaults to `[1, 1, 1]`. */
+    scale?: number | readonly [x: number, y: number, z: number];
+    /** Tint color RGB. Defaults to `[1, 1, 1]`. */
+    color?: readonly [r: number, g: number, b: number];
+}
+export interface WebGPU3DRendererOptions extends Renderer3DOptions {
+    maxSkinnedInstances?: number;
+    maxBonesPerSkin?: number;
+    /**
+     * Pre-loaded prefab bucket. When provided, the renderer self-sizes its
+     * skinned-instance + bone buffers from the bucket's prefab stats, and
+     * uploads each prefab to the GPU during `init()`. The bucket must have
+     * `load()` resolved before being passed in.
+     *
+     * `maxSkinnedInstances` defaults to `maxInstances * maxSkinnedPartsPerPrefab`.
+     * `maxBonesPerSkin` defaults to the maximum joint count across all prefabs.
+     */
+    prefabs?: PrefabBucket3D;
+    /**
+     * How many instances you intend to spawn. Used together with `prefabs` to
+     * size the skinned-instance budget. Ignored if `maxSkinnedInstances` is set
+     * explicitly. Defaults to `maxModels` when only `prefabs` is provided.
+     */
+    maxInstances?: number;
+}
+export declare class WebGPU3DRenderer extends Base3DRenderer {
+    private root;
+    private device;
+    private context;
+    private resizeObserver;
+    private resizeCallbacks;
+    private format;
+    private meshLayout;
+    private dynamicData;
+    private staticData;
+    private slotIndexData;
+    private freeList;
+    private batcher;
+    private staticDirty;
+    private instanceModelIds;
+    private dynamicBuffer;
+    private staticBuffer;
+    private uniformBuffer;
+    private slotIndexBuffer;
+    private rawPipeline;
+    private rawBindGroup;
+    private rawDynamicBuffer;
+    private rawStaticBuffer;
+    private rawUniformBuffer;
+    private rawSlotIndexBuffer;
+    private depthTexture;
+    private rawTexturedPipeline;
+    private models;
+    private nextModelId;
+    private skinnedModels;
+    private clipResync;
+    private skinnedMeshLayout;
+    private rawSkinnedPipeline;
+    private rawSkinnedTexturedPipeline;
+    private rawSkinnedBindGroup;
+    private boneMatrixData;
+    private rawBoneMatrixBuffer;
+    private boneMatrixDirty;
+    private readonly maxTotalBones;
+    private packedAnimData;
+    private animComputeKernel;
+    private animComputeNeedsRebuild;
+    private animKernelBudgets;
+    private animClipTableOffset;
+    private animChannelTableOffset;
+    private animJointLookupOffset;
+    private gpuAnimInstanceStates;
+    private gpuInstData;
+    private gpuInstDV;
+    private skinnedDynamicData;
+    private skinnedStaticData;
+    private skinnedSlotIndexData;
+    private skinnedFreeList;
+    private skinnedBatcher;
+    private skinnedStaticDirty;
+    private skinnedInstanceModelIds;
+    private skinnedInstanceBoneOffsets;
+    private skinnedAnimStates;
+    private nextBoneOffset;
+    private readonly maxSkinnedInstances;
+    private readonly maxBonesPerSkin;
+    private rawSkinnedDynamicBuffer;
+    private rawSkinnedStaticBuffer;
+    private rawSkinnedUniformBuffer;
+    private rawSkinnedSlotIndexBuffer;
+    private frustumPlanes;
+    readonly camera: Camera3D;
+    private uniformData;
+    private lastRenderTime;
+    private readonly _prefabs;
+    constructor(canvas: HTMLCanvasElement, options: WebGPU3DRendererOptions);
+    init(): Promise<void>;
+    /**
+     * Upload every prefab in the bucket to the GPU and stash the handle on
+     * each prefab so `bucket.get(id)` resolves to a usable model. Also
+     * subscribes the resync coordinator to the bucket's `clips-changed`
+     * channel for lazy load/unload.
+     */
+    private uploadPrefabBucket;
+    private setupResizeObserver;
+    /**
+     * Register a callback that fires when the canvas resizes.
+     * Receives the new width and height in physical pixels.
+     */
+    onResize(callback: (width: number, height: number) => void): void;
+    createCompute(name: string, options: ComputeOptions): ComputeBuilder;
+    /**
+     * Create a flat grid mesh on the XZ plane at Y=0.
+     *
+     * ```ts
+     * const grid = renderer.createGrid({ size: 20, step: 1, lineWidth: 0.005 });
+     * renderer.addInstance({ model: grid, color: [0.3, 0.3, 0.3] });
+     * ```
+     */
+    createGrid(opts?: {
+        size?: number;
+        step?: number;
+        lineWidth?: number;
+    }): ModelHandle;
+    /**
+     * Register a model. Returns a handle for addInstance().
+     *
+     * ```ts
+     * const hero = renderer.loadModel({
+     *     positions: new Float32Array([...]),
+     *     normals: new Float32Array([...]),  // optional — auto-computed from faces
+     *     uvs: new Float32Array([...]),       // optional
+     *     indices: new Uint16Array([...]),    // optional
+     *     texture: myImageBitmap,             // optional
+     * });
+     * ```
+     */
+    loadModel(data: ModelData): ModelHandle;
+    /**
+     * Register a skinned model with joint/weight vertex data.
+     * Called internally by loadGltf when a skin is detected.
+     */
+    private loadSkinnedModel;
+    /**
+     * Auto-compute flat normals from triangle faces.
+     */
+    private computeNormals;
+    /**
+     * Load a glTF/GLB model from a URL. Returns one ModelHandle per primitive.
+     * Most models have multiple primitives (body parts, material groups, etc.).
+     *
+     * ```ts
+     * const model = await renderer.loadGltf('assets/hero.glb');
+     * const instance = renderer.addInstance({ model, x: 0, y: 0, z: 0 });
+     * instance.playAnimation?.('walk');
+     * ```
+     */
+    loadGltf(url: string, opts?: {
+        animations?: string[];
+    }): Promise<GltfModel>;
+    /**
+     * Upload a previously-parsed glTF to the GPU. Returns a GltfModel handle.
+     * Splitting parse (CPU) from upload (GPU) lets callers parse models in parallel
+     * before a renderer exists and inspect joint counts / vertex totals to size the
+     * renderer appropriately.
+     */
+    uploadParsedGltf(parsed: ParsedGltf): GltfModel;
+    /**
+     * Add an instance. For skinned models, pass `linkedTo` to share bone matrices
+     * with another instance (e.g., when spawning all parts of a character).
+     */
+    addInstance(opts: MeshInstanceOptions): InstanceHandle;
+    private addGltfInstance;
+    private addSkinnedInstance;
+    /**
+     * Drain pending resyncs from the coordinator. Per affected skin: rebuild
+     * its `SkeletalAnimation` clip list densely, remap in-flight animStates,
+     * then full-repack `packedAnimData`. Falls back to a kernel rebuild only
+     * when the new data exceeds the kernel's allocated budgets.
+     *
+     * The dense renumbering is load-bearing: the kernel reads each clip by
+     * its per-skin index, which must equal `SkeletalAnimation`'s clip id.
+     */
+    private syncLazyAnimationChanges;
+    /** Doubling-growth budgets for kernel storage buffers, with sensible floors. */
+    private growBudgetsForPacked;
+    /** Upload `packedAnimData` to the existing kernel iff it fits the current budgets. Returns false to force a rebuild. */
+    private tryUploadInPlace;
+    /**
+     * Update skeletal animations for all skinned instances. Call once per tick.
+     */
+    private updatedBoneOffsets;
+    private updateAnimations;
+    removeInstance(handle: MeshInstanceHandle): void;
+    storePreviousState(): void;
+    render(alpha: number): void;
+    /**
+     * Extract 6 frustum planes from a column-major VP matrix.
+     * Each plane is [a, b, c, d] where ax + by + cz + d >= 0 means inside.
+     */
+    private extractFrustumPlanes;
+    /**
+     * Test if a bounding sphere is inside or intersects the frustum.
+     * Returns true if visible (should be drawn).
+     */
+    private isInFrustum;
+    destroy(): void;
+}