murow 0.1.1 → 0.1.3

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

@@ -0,0 +1,45 @@
+import type { InputSnapshot } from 'murow/core/input';
+import { HitBuffer } from 'murow/core/raycast';
+import { Raycast, RaycastMemo, type RaycastHit, type RaycastOptions } from 'murow/renderer';
+import type { SpriteHandle } from 'murow/renderer';
+import type { WebGPU2DRenderer } from './renderer';
+type Point = [number, number];
+type Hit = RaycastHit<SpriteHandle, Point>;
+type Opts = RaycastOptions<SpriteHandle>;
+export type RaycastState2D = HitBuffer<SpriteHandle, Point>;
+export declare class WebGPURaycast2D extends Raycast<SpriteHandle, Point> {
+    private renderer;
+    readonly state: RaycastState2D;
+    private resultBuffer;
+    private memos;
+    constructor(renderer: WebGPU2DRenderer);
+    update(input: InputSnapshot): void;
+    /**
+     * Topmost sprite under the cursor, or null. The returned object is
+     * pool-backed and valid only until the next `update()` -- copy what
+     * you need, or use `memo` for results that persist across frames.
+     */
+    hit(opts?: Opts): Hit | null;
+    /**
+     * Every sprite under the cursor, topmost first. The array and its
+     * entries are reused and overwritten by the next `update()`.
+     */
+    hitAll(opts?: Opts): readonly Hit[];
+    memo(opts: Opts): WebGPURaycastMemo2D;
+    clearMemos(): void;
+}
+export declare class WebGPURaycastMemo2D extends RaycastMemo<SpriteHandle, Point> {
+    private state;
+    private opts;
+    private onDispose;
+    private dirty;
+    private detached;
+    private cached;
+    constructor(state: RaycastState2D, opts: Opts, onDispose: () => void);
+    get hits(): readonly Hit[];
+    get first(): Hit | null;
+    dispose(): void;
+    _invalidate(): void;
+    _detach(): void;
+}
+export {};

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

@@ -1,5 +1,6 @@
 import { Base2DRenderer } from 'murow/renderer';
 import type { Renderer2DOptions, SpriteHandle, SpriteOptions, SpritesheetHandle, SpritesheetSource } from 'murow/renderer';
+import { WebGPURaycast2D, type RaycastState2D } from './raycast';
 import { Camera2D } from '../camera/camera-2d';
 import { type ParsedSpritesheet } from 'murow/renderer';
 import { GeometryBuilder, type GeometryOptions } from '../geometry/geometry-builder';
@@ -49,7 +50,11 @@ export declare class WebGPU2DRenderer extends Base2DRenderer {
     private sheets;
     private nextSheetId;
     readonly camera: Camera2D;
+    readonly raycast: WebGPURaycast2D;
     private uniformData;
+    private spriteHandles;
+    private spriteHitboxes;
+    private nextSpriteId;
     private resizeObserver;
     private resizeCallbacks;
     private readonly _prefabs;
@@ -78,6 +83,12 @@ export declare class WebGPU2DRenderer extends Base2DRenderer {
         sheet: SpritesheetHandle | Prefab2D;
     }): SpriteHandle;
     removeSprite(sprite: SpriteHandle): void;
+    /**
+     * Point-test every sprite against the unprojected cursor and push the
+     * hits into the buffer. Sort key is `-layer` so the topmost sprite is
+     * "nearest". A declared hitbox overrides the default rendered quad.
+     */
+    _collectRaycastHitsInto(screenX: number, screenY: number, rc: RaycastState2D): void;
     storePreviousState(): void;
     createGeometry(name: string, options: GeometryOptions): GeometryBuilder;
     createCompute(name: string, options: ComputeOptions): ComputeBuilder;

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

@@ -4,10 +4,12 @@ export declare class SpriteAccessor implements SpriteHandle {
     private staticData;
     private dynamicBase;
     private staticBase;
+    private _id;
     private _slot;
     private _sheetId;
     private _onStaticDirty;
-    constructor(dynamicData: Float32Array, staticData: Float32Array, slot: number, sheetId: number, onStaticDirty: () => void);
+    constructor(dynamicData: Float32Array, staticData: Float32Array, id: number, slot: number, sheetId: number, onStaticDirty: () => void);
+    get id(): number;
     get slot(): number;
     get sheetId(): number;
     get x(): number;

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

@@ -0,0 +1,32 @@
+import { type HitboxPart } from 'murow/core/hitbox';
+/**
+ * Line-list wireframe renderer for instance hitboxes. Owns its pipeline,
+ * the three unit-shape vertex buffers, and a dynamic-offset uniform buffer
+ * (one MVP + color per entry). The caller walks instances and feeds each
+ * hitbox into `emit`; `flush` issues the per-entry draws.
+ */
+export declare class HitboxDebugRenderer {
+    private device;
+    private pipeline;
+    private bindGroup;
+    private uniformBuffer;
+    private sphereBuffer;
+    private sphereVertexCount;
+    private boxBuffer;
+    private boxVertexCount;
+    private cylinderBuffer;
+    private cylinderVertexCount;
+    private stage;
+    private entries;
+    private vp;
+    init(device: GPUDevice, format: GPUTextureFormat): void;
+    begin(vp: Float32Array): void;
+    emit(hb: HitboxPart<'3d'>, hovered: boolean, px: number, py: number, pz: number, sx: number, sy: number, sz: number): void;
+    flush(pass: GPURenderPassEncoder): void;
+    /**
+     * The model matrix is pure scale-then-translate, so `MVP = VP * M`
+     * collapses to scaling VP's first three columns by the extents and
+     * replacing the fourth with `VP * (center, 1)` -- no matrix multiply.
+     */
+    private collect;
+}

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

@@ -0,0 +1,113 @@
+/**
+ * A dynamic point or spot light. Directional/ambient terms are global and set
+ * via `setDirectionalLight` / `setAmbient`, not added here.
+ */
+export type LightSpec = {
+    type: 'point';
+    position: readonly [x: number, y: number, z: number];
+    /** Light color RGB. Defaults to `[1, 1, 1]`. */
+    color?: readonly [r: number, g: number, b: number];
+    /** Brightness multiplier. Defaults to `1`. */
+    intensity?: number;
+    /** World-unit radius past which the light contributes nothing. Defaults to `10`. */
+    range?: number;
+} | {
+    type: 'spot';
+    position: readonly [x: number, y: number, z: number];
+    /** Direction the cone points along. */
+    direction: readonly [x: number, y: number, z: number];
+    color?: readonly [r: number, g: number, b: number];
+    intensity?: number;
+    range?: number;
+    /** Cone half-angle in radians (the outer edge). Defaults to `0.5`. */
+    angle?: number;
+    /**
+     * Edge softness, 0..1. `0` = hard edge at `angle`; `1` = the cone fades
+     * all the way from its center. The feathered band is `angle * smoothness`
+     * wide, measured inward from the edge. Defaults to `0.5`.
+     */
+    smoothness?: number;
+};
+/**
+ * Live handle to a dynamic light. All properties are readable and mutable every
+ * frame — unlike a mesh instance's spawn-frozen color. `destroy()` frees the slot.
+ *
+ * The `position` / `direction` / `color` getters return a per-handle reused
+ * tuple (mutated on each read), matching `MeshInstanceHandle`. Copy the values
+ * out if you need to retain them past the next read on the same handle.
+ */
+export interface LightHandle {
+    readonly slot: number;
+    setPosition(x: number, y: number, z: number): void;
+    setDirection(x: number, y: number, z: number): void;
+    /** Snap to a position without interpolating from the previous one (use after a discontinuous move). */
+    teleport(x: number, y: number, z: number): void;
+    setColor(r: number, g: number, b: number): void;
+    readonly position: readonly [number, number, number];
+    readonly direction: readonly [number, number, number];
+    readonly color: readonly [number, number, number];
+    intensity: number;
+    range: number;
+    /** Cone half-angle in radians (spot only; `0` for point lights). Readable + settable. */
+    angle: number;
+    /** Edge softness 0..1 (spot only). `0` = hard edge, `1` = fades from center. Readable + settable. */
+    smoothness: number;
+    /** Whether the light contributes this frame. Toggling does not free the slot. */
+    enabled: boolean;
+    destroy(): void;
+}
+export declare class LightSystem {
+    private readonly maxLights;
+    private readonly data;
+    private readonly slots;
+    private readonly enabled;
+    private readonly handles;
+    /** Dense scratch buffer of enabled lights, packed each frame for upload. */
+    private readonly uploadData;
+    /** CPU-side spot cone params per slot (the GPU only needs the derived cosines). */
+    private readonly angle;
+    private readonly smoothness;
+    private dirDir;
+    private dirColor;
+    private dirIntensity;
+    private ambient;
+    constructor(maxLights: number);
+    /** Add a dynamic point or spot light. Throws past `maxLights`. */
+    add(spec: LightSpec): LightHandle;
+    /**
+     * Set the global directional light (the "sun"). `direction` points from the
+     * surface toward the light. Defaults to `(0.3, 0.8, 0.5)`, white, intensity 1.
+     */
+    setDirectional(direction: readonly [number, number, number], color?: readonly [number, number, number], intensity?: number): void;
+    /** Set the global ambient term. Defaults to `(0.3, 0.3, 0.3)`. */
+    setAmbient(color: readonly [number, number, number]): void;
+    /** Number of live dynamic lights. */
+    get count(): number;
+    /**
+     * Pack enabled lights into a dense run for upload. Disabled lights are
+     * skipped so the shader loop only walks contributing lights. Returns the
+     * shared scratch buffer, the light count, and the byte length to upload
+     * (so the caller never needs the record layout).
+     */
+    pack(): {
+        data: Float32Array;
+        count: number;
+        byteLength: number;
+    };
+    /**
+     * Stamp the directional + ambient terms and the light count into the
+     * renderer's uniform array, starting at `offset` (the float index after the
+     * VP matrix + alpha). Layout: lightDir(3), dirColor(3), dirIntensity(1),
+     * ambient(3), then lightCount as a u32 reinterpret at `offset + 10`.
+     */
+    writeUniforms(uniformData: Float32Array, offset: number, count: number): void;
+    /**
+     * Snapshot every live light's current position/direction into its prev
+     * slot. Called from the renderer's `storePreviousState()` in `pre-tick`, so
+     * the shader can `mix(prev, curr, alpha)` and moving lights interpolate at
+     * render rate instead of snapping at the tick boundary.
+     */
+    storePrevious(): void;
+    /** Write a light spec into its CPU slot. Prev is seeded to curr (no spawn lerp). */
+    private writeSlot;
+}

package/dist/webgpu/types/3d/lights.test.d.ts

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

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

@@ -0,0 +1,44 @@
+import type { InputSnapshot } from 'murow/core/input';
+import { HitBuffer } from 'murow/core/raycast';
+import { Raycast, RaycastMemo, type RaycastHit, type RaycastOptions } from 'murow/renderer';
+import type { MeshInstanceHandle, WebGPU3DRenderer } from './renderer';
+type Point = [number, number, number];
+type Hit = RaycastHit<MeshInstanceHandle, Point>;
+type Opts = RaycastOptions<MeshInstanceHandle>;
+export type RaycastState = HitBuffer<MeshInstanceHandle, Point>;
+export declare class WebGPURaycast3D extends Raycast<MeshInstanceHandle, Point> {
+    private renderer;
+    readonly state: RaycastState;
+    private resultBuffer;
+    private memos;
+    constructor(renderer: WebGPU3DRenderer);
+    update(input: InputSnapshot): void;
+    /**
+     * Nearest hit, or null. The returned object is pool-backed and valid
+     * only until the next `update()` -- copy what you need, or use `memo`
+     * for results that persist across frames.
+     */
+    hit(opts?: Opts): Hit | null;
+    /**
+     * All hits, nearest first. The array and its entries are reused across
+     * calls and overwritten by the next `update()`; do not retain them.
+     */
+    hitAll(opts?: Opts): readonly Hit[];
+    memo(opts: Opts): WebGPURaycastMemo3D;
+    clearMemos(): void;
+}
+export declare class WebGPURaycastMemo3D extends RaycastMemo<MeshInstanceHandle, Point> {
+    private state;
+    private opts;
+    private onDispose;
+    private dirty;
+    private detached;
+    private cached;
+    constructor(state: RaycastState, opts: Opts, onDispose: () => void);
+    get hits(): readonly Hit[];
+    get first(): Hit | null;
+    dispose(): void;
+    _invalidate(): void;
+    _detach(): void;
+}
+export {};

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

@@ -1,8 +1,10 @@
 import { Base3DRenderer } from 'murow/renderer';
 import type { Renderer3DOptions } from 'murow/renderer';
 import { ComputeBuilder, type ComputeOptions } from '../compute/compute-builder';
+import { type LightSpec, type LightHandle } from './lights';
 import { Camera3D } from '../camera/camera-3d';
-import { type ParsedGltf, type PrefabBucket3D, type Prefab3D, type PlayOptions } from 'murow/renderer';
+import { type ParsedGltf, type PrefabBucket3D, type Prefab3D, type PlayOptions, Raycast as RaycastBase, RaycastMemo as RaycastMemoBase, type RaycastHit as RaycastHitBase, type RaycastOptions as RaycastOptionsBase } from 'murow/renderer';
+import { WebGPURaycast3D, type RaycastState } from './raycast';
 export interface ModelData {
     positions: Float32Array;
     normals?: Float32Array;
@@ -17,6 +19,7 @@ export interface ModelHandle {
     readonly skinned: boolean;
 }
 export interface MeshInstanceHandle {
+    readonly id: number;
     readonly slot: number;
     readonly modelId: number;
     readonly skinned: boolean;
@@ -59,6 +62,7 @@ export interface GltfModel {
 }
 /** Handle to a spawned instance (single primitive or multi-part glTF). */
 export interface InstanceHandle {
+    readonly id: number;
     setPosition(x: number, y: number, z: number): void;
     setRotation(x: number, y: number, z: number): void;
     setScale(x: number, y: number, z: number): void;
@@ -103,6 +107,10 @@ export interface MeshInstanceOptions {
     /** Tint color RGB. Defaults to `[1, 1, 1]`. */
     color?: readonly [r: number, g: number, b: number];
 }
+export type RaycastHit = RaycastHitBase<MeshInstanceHandle, [number, number, number]>;
+export type RaycastOptions = RaycastOptionsBase<MeshInstanceHandle>;
+export type Raycast = RaycastBase<MeshInstanceHandle, [number, number, number]>;
+export type RaycastMemo = RaycastMemoBase<MeshInstanceHandle, [number, number, number]>;
 export interface WebGPU3DRendererOptions extends Renderer3DOptions {
     maxSkinnedInstances?: number;
     maxBonesPerSkin?: number;
@@ -140,6 +148,8 @@ export declare class WebGPU3DRenderer extends Base3DRenderer {
     private batcher;
     private staticDirty;
     private instanceModelIds;
+    private instanceHandles;
+    private nextInstanceId;
     private dynamicBuffer;
     private staticBuffer;
     private uniformBuffer;
@@ -184,6 +194,7 @@ export declare class WebGPU3DRenderer extends Base3DRenderer {
     private skinnedInstanceModelIds;
     private skinnedInstanceBoneOffsets;
     private skinnedAnimStates;
+    private skinnedInstanceHandles;
     private nextBoneOffset;
     /** Reusable bone-offset blocks per skinIndex. Pushed on remove, popped on add. Indexed by skinIndex (low cardinality), so a Map of lists is fine. */
     private freedBoneOffsets;
@@ -199,10 +210,18 @@ export declare class WebGPU3DRenderer extends Base3DRenderer {
     private rawSkinnedUniformBuffer;
     private rawSkinnedSlotIndexBuffer;
     private frustumPlanes;
+    private lights;
+    private lightBuffer;
+    private rawLightBuffer;
     readonly camera: Camera3D;
+    readonly raycast: WebGPURaycast3D;
     private uniformData;
     private lastRenderTime;
     private readonly _prefabs;
+    debug: {
+        hitboxes: boolean;
+    };
+    private hitboxDebug;
     constructor(canvas: HTMLCanvasElement, options: WebGPU3DRendererOptions);
     init(): Promise<void>;
     /**
@@ -243,6 +262,25 @@ export declare class WebGPU3DRenderer extends Base3DRenderer {
      * separate set of GPU buffers. Read-only.
      */
     get maxSkinned(): number;
+    /**
+     * Add a dynamic point or spot light. Returns a live handle whose position,
+     * color, intensity, range, and enabled state can all be changed every frame.
+     * Up to `MAX_LIGHTS` (64) lights may be live at once; throws past that.
+     *
+     * The global directional + ambient terms are separate — see
+     * `setDirectionalLight` / `setAmbient`.
+     */
+    addLight(spec: LightSpec): LightHandle;
+    /**
+     * Set the global directional light (the "sun"). `direction` points from the
+     * surface toward the light. Defaults to `(0.3, 0.8, 0.5)`, white, intensity 1
+     * — the engine's classic fixed look.
+     */
+    setDirectionalLight(direction: readonly [number, number, number], color?: readonly [number, number, number], intensity?: number): void;
+    /** Set the global ambient term. Defaults to `(0.3, 0.3, 0.3)`. */
+    setAmbient(color: readonly [number, number, number]): void;
+    /** Number of live dynamic lights. */
+    get lightCount(): number;
     /**
      * Create a flat grid mesh on the XZ plane at Y=0.
      *
@@ -357,7 +395,18 @@ export declare class WebGPU3DRenderer extends Base3DRenderer {
      */
     removeInstance(handle: InstanceHandle): void;
     storePreviousState(): void;
+    /** Resolve an instance's declared hitbox name to its Hitbox via the bucket's library. */
+    private resolveHitbox;
+    /**
+     * Pick test for a single instance. Returns the ray-`t` and the struck
+     * part name, or `null`. Uses the prefab's declared hitbox when
+     * available; falls back to the model's axis-aligned bounding box.
+     */
+    private testInstanceRay;
+    /** Push every instance the screen ray hits within [near, far] into the hit buffer. Unsorted. */
+    _collectRaycastHitsInto(screenX: number, screenY: number, rc: RaycastState): void;
     render(alpha: number): void;
+    private drawDebugHitboxes;
     /**
      * 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.

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

@@ -1,4 +1,6 @@
 import * as d from 'typegpu/data';
+/** Max point/spot lights the mesh shaders' storage buffer holds. */
+export declare const MAX_LIGHTS = 64;
 export declare function createMeshLayout(maxInstances: number): import("typegpu").TgpuBindGroupLayout<{
     uniforms: {
         uniform: d.WgslStruct<{
@@ -7,6 +9,14 @@ export declare function createMeshLayout(maxInstances: number): import("typegpu"
             lightDirX: d.F32;
             lightDirY: d.F32;
             lightDirZ: d.F32;
+            lightDirR: d.F32;
+            lightDirG: d.F32;
+            lightDirB: d.F32;
+            lightDirIntensity: d.F32;
+            ambientR: d.F32;
+            ambientG: d.F32;
+            ambientB: d.F32;
+            lightCount: d.U32;
         }>;
     };
     dynamicInstances: {
@@ -38,6 +48,32 @@ export declare function createMeshLayout(maxInstances: number): import("typegpu"
     slotIndices: {
         storage: d.WgslArray<d.U32>;
     };
+    lights: {
+        storage: d.WgslArray<d.WgslStruct<{
+            kind: d.F32;
+            currPosX: d.F32;
+            currPosY: d.F32;
+            currPosZ: d.F32;
+            prevPosX: d.F32;
+            prevPosY: d.F32;
+            prevPosZ: d.F32;
+            currDirX: d.F32;
+            currDirY: d.F32;
+            currDirZ: d.F32;
+            prevDirX: d.F32;
+            prevDirY: d.F32;
+            prevDirZ: d.F32;
+            colorR: d.F32;
+            colorG: d.F32;
+            colorB: d.F32;
+            intensity: d.F32;
+            range: d.F32;
+            innerCos: d.F32;
+            outerCos: d.F32;
+            castsShadow: d.F32;
+            shadowMapIndex: d.F32;
+        }>>;
+    };
 }>;
 export type MeshDataLayout = ReturnType<typeof createMeshLayout>;
 export declare function createMeshVertex(meshLayout: MeshDataLayout): import("typegpu").TgpuVertexFn<{
@@ -46,10 +82,12 @@ export declare function createMeshVertex(meshLayout: MeshDataLayout): import("ty
 }, {
     vNormal: d.Vec3f;
     vColor: d.Vec3f;
+    vWorldPos: d.Vec3f;
 }>;
-export declare function createMeshFragment(meshLayout: MeshDataLayout): import("typegpu").TgpuFragmentFn<{
+export declare function createMeshFragment(meshLayout: MeshDataLayout | SkinnedMeshDataLayout): import("typegpu").TgpuFragmentFn<{
     vNormal: d.Vec3f;
     vColor: d.Vec3f;
+    vWorldPos: d.Vec3f;
 }, d.Vec4f>;
 export declare function createTextureBindGroupLayout(): import("typegpu").TgpuBindGroupLayout<{
     modelTexture: import("typegpu").TgpuLayoutTexture<d.WgslTexture2d<d.F32>>;
@@ -66,11 +104,13 @@ export declare function createTexturedMeshVertex(meshLayout: MeshDataLayout): im
     vNormal: d.Vec3f;
     vColor: d.Vec3f;
     vUV: d.Vec2f;
+    vWorldPos: d.Vec3f;
 }>;
-export declare function createTexturedMeshFragment(meshLayout: MeshDataLayout, texLayout: TextureBindGroupLayout): import("typegpu").TgpuFragmentFn<{
+export declare function createTexturedMeshFragment(meshLayout: MeshDataLayout | SkinnedMeshDataLayout, texLayout: TextureBindGroupLayout): import("typegpu").TgpuFragmentFn<{
     vNormal: d.Vec3f;
     vColor: d.Vec3f;
     vUV: d.Vec2f;
+    vWorldPos: d.Vec3f;
 }, d.Vec4f>;
 export declare function createSkinnedMeshLayout(maxInstances: number, maxBones: number): import("typegpu").TgpuBindGroupLayout<{
     uniforms: {
@@ -80,6 +120,14 @@ export declare function createSkinnedMeshLayout(maxInstances: number, maxBones:
             lightDirX: d.F32;
             lightDirY: d.F32;
             lightDirZ: d.F32;
+            lightDirR: d.F32;
+            lightDirG: d.F32;
+            lightDirB: d.F32;
+            lightDirIntensity: d.F32;
+            ambientR: d.F32;
+            ambientG: d.F32;
+            ambientB: d.F32;
+            lightCount: d.U32;
         }>;
     };
     dynamicInstances: {
@@ -115,6 +163,32 @@ export declare function createSkinnedMeshLayout(maxInstances: number, maxBones:
     boneMatrices: {
         storage: d.WgslArray<d.Mat4x4f>;
     };
+    lights: {
+        storage: d.WgslArray<d.WgslStruct<{
+            kind: d.F32;
+            currPosX: d.F32;
+            currPosY: d.F32;
+            currPosZ: d.F32;
+            prevPosX: d.F32;
+            prevPosY: d.F32;
+            prevPosZ: d.F32;
+            currDirX: d.F32;
+            currDirY: d.F32;
+            currDirZ: d.F32;
+            prevDirX: d.F32;
+            prevDirY: d.F32;
+            prevDirZ: d.F32;
+            colorR: d.F32;
+            colorG: d.F32;
+            colorB: d.F32;
+            intensity: d.F32;
+            range: d.F32;
+            innerCos: d.F32;
+            outerCos: d.F32;
+            castsShadow: d.F32;
+            shadowMapIndex: d.F32;
+        }>>;
+    };
 }>;
 export type SkinnedMeshDataLayout = ReturnType<typeof createSkinnedMeshLayout>;
 export declare function createSkinnedMeshVertex(layout: SkinnedMeshDataLayout): import("typegpu").TgpuVertexFn<{
@@ -127,10 +201,19 @@ export declare function createSkinnedMeshVertex(layout: SkinnedMeshDataLayout):
     vNormal: d.Vec3f;
     vColor: d.Vec3f;
     vUV: d.Vec2f;
+    vWorldPos: d.Vec3f;
 }>;
 /**
- * Fragment shader for skinned meshes — reuses the textured fragment shader.
- * For untextured skinned meshes, reuse createMeshFragment.
+ * Fragment shader for untextured skinned meshes. The skinned vertex shader
+ * always emits `vUV` (location 2) because it is shared with the textured path,
+ * so this fragment must declare `vUV` in its `in` too, otherwise `vWorldPos`
+ * lands on location 2 and collides with the vertex's `vUV` (vec2 vs vec3). The
+ * UV is simply unused here. Lighting matches createMeshFragment.
  */
-export { createMeshFragment as createSkinnedMeshFragment };
+export declare function createSkinnedMeshFragment(meshLayout: SkinnedMeshDataLayout): import("typegpu").TgpuFragmentFn<{
+    vNormal: d.Vec3f;
+    vColor: d.Vec3f;
+    vUV: d.Vec2f;
+    vWorldPos: d.Vec3f;
+}, d.Vec4f>;
 export { createTexturedMeshFragment as createSkinnedTexturedMeshFragment };

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

@@ -104,7 +104,62 @@ export declare const MeshUniforms: d.WgslStruct<{
     lightDirX: d.F32;
     lightDirY: d.F32;
     lightDirZ: d.F32;
+    lightDirR: d.F32;
+    lightDirG: d.F32;
+    lightDirB: d.F32;
+    lightDirIntensity: d.F32;
+    ambientR: d.F32;
+    ambientG: d.F32;
+    ambientB: d.F32;
+    lightCount: d.U32;
 }>;
+/** viewProjection occupies floats [0, 16). */
+export declare const MESH_UNIFORM_ALPHA_OFFSET = 16;
+/** The directional/ambient/count block starts right after `alpha`. */
+export declare const MESH_UNIFORM_LIGHT_OFFSET = 17;
+/** Total f32 slots in MeshUniforms (mat4x4 16 + alpha 1 + 10 light terms + count 1). */
+export declare const MESH_UNIFORM_FLOATS = 28;
+/**
+ * Point/spot light record. One entry per slot in the renderer's light storage
+ * buffer; the fragment shader loops `[0, lightCount)`. Kept f32-contiguous (no
+ * vec types) to match the flat Float32Array the renderer uploads.
+ *
+ * Position and direction carry `prev` + `curr` snapshots so the fragment shader
+ * can `mix(prev, curr, alpha)`, moving lights interpolate at render rate, the
+ * same as mesh instances, instead of snapping at the tick boundary.
+ *
+ * `kind`: 1 = point, 2 = spot (0/directional is the global term in MeshUniforms).
+ * `castsShadow` / `shadowMapIndex` are reserved for shadow-map support: the
+ * fragment loop already multiplies each light by a shadow factor (currently
+ * 1.0), so a shadow pass can populate these without reshaping the buffer.
+ */
+export declare const Light: d.WgslStruct<{
+    kind: d.F32;
+    currPosX: d.F32;
+    currPosY: d.F32;
+    currPosZ: d.F32;
+    prevPosX: d.F32;
+    prevPosY: d.F32;
+    prevPosZ: d.F32;
+    currDirX: d.F32;
+    currDirY: d.F32;
+    currDirZ: d.F32;
+    prevDirX: d.F32;
+    prevDirY: d.F32;
+    prevDirZ: d.F32;
+    colorR: d.F32;
+    colorG: d.F32;
+    colorB: d.F32;
+    intensity: d.F32;
+    range: d.F32;
+    innerCos: d.F32;
+    outerCos: d.F32;
+    castsShadow: d.F32;
+    shadowMapIndex: d.F32;
+}>;
+export declare const LIGHT_FLOATS = 22;
+export declare const LIGHT_KIND_POINT = 1;
+export declare const LIGHT_KIND_SPOT = 2;
 /** Per-instance animation state, uploaded from CPU each frame. */
 export declare const InstanceAnimStateGPU: d.WgslStruct<{
     clipId: d.I32;

package/dist/webgpu/types/geometry/geometry-builder.d.ts

@@ -40,7 +40,7 @@ export declare class CustomGeometry<TDynamic extends Record<string, AnyWgslData>
     readonly maxInstances: number;
     readonly geometryData: GeometryData;
     private root;
-    private freeList;
+    private slots;
     private layoutConfig;
     private dynamicFieldNames;
     private staticFieldNames;
@@ -54,9 +54,6 @@ export declare class CustomGeometry<TDynamic extends Record<string, AnyWgslData>
     private _uniformDirty;
     private _isComputeSourced;
     private _drawCount;
-    private activeSlots;
-    private activeCount;
-    private slotToActive;
     private _ctx;
     private dynamicBuffer;
     private staticBuffer;

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

@@ -17,6 +17,7 @@ export { AnimationController } from './2d/animation';
 export type { AnimationClip, AnimationState, AnimationClipConfig } from './2d/animation';
 export { WebGPU3DRenderer } from './3d/renderer';
 export type { ModelData, ModelHandle, GltfModel, InstanceHandle, MeshInstanceHandle, MeshInstanceOptions, } from './3d/renderer';
+export type { LightSpec, LightHandle } from './3d/lights';
 export { MorphAnimation } from './3d/morph-animation';
 export type { MorphClip, MorphState, MorphClipConfig } from './3d/morph-animation';
 export { Camera2D } from './camera/camera-2d';

package/dist/webgpu/types/shaders/utils.d.ts

@@ -26,3 +26,27 @@ export declare const scaleRotate2d: import("typegpu").TgpuFn<(scale: d.Vec2f, an
  * Inverse lerp — given a value in [min, max], returns its t in [0, 1].
  */
 export declare const inverseLerp: import("typegpu").TgpuFn<(min: d.F32, max: d.F32, value: d.F32) => d.F32>;
+/**
+ * Diffuse contribution of one point/spot light at a surface point. Returns the
+ * light's color scaled by Lambert term, distance attenuation, spot cone, and a
+ * shadow factor. The shadow factor is currently fixed at 1.0; a shadow-map pass
+ * replaces it by sampling the light's shadow map without changing this loop.
+ *
+ * Takes the light's fields as vectors (rather than the `Light` struct) so the
+ * signature is portable across the mesh and skinned fragment shaders, which
+ * each read the struct from their own bind-group storage buffer:
+ *   `pos`      light position (point/spot)
+ *   `axis`     spot direction (unused for point lights)
+ *   `color`    light rgb
+ *   `params`   (intensity, range, innerCos, outerCos); a point light passes
+ *              innerCos = 1, outerCos = -1 so the cone term is always 1.
+ *   `normal`   surface normal (world space, normalized)
+ *   `worldPos` surface position (world space)
+ */
+export declare const lightContribution: import("typegpu").TgpuFn<(pos: d.Vec3f, axis: d.Vec3f, color: d.Vec3f, params: d.Vec4f, normal: d.Vec3f, worldPos: d.Vec3f) => d.Vec3f>;
+/**
+ * Reinhard tone map: rolls accumulated light smoothly toward white instead of
+ * hard-clipping at 1.0. Without it, summed lights flat-top to white and any
+ * gradient (e.g. a feathered spot edge) collapses into a thin visible ring.
+ */
+export declare const tonemap: import("typegpu").TgpuFn<(c: d.Vec3f) => d.Vec3f>;