@vgpu/render 0.0.1

package/dist/uniform-pool-types.d.ts

@@ -0,0 +1,22 @@
+import type { UniformPool } from "./uniform-pool.ts";
+export interface UniformPoolOptions {
+    readonly capacityBytes?: number;
+}
+export interface UniformLayout<T> {
+    readonly size: number;
+    readonly bindings?: readonly GPUBindGroupLayoutEntry[];
+    /** Optional layout to share with the pipeline that will consume this slot. */
+    readonly bindGroupLayout?: GPUBindGroupLayout;
+    encode(value: T, dst: ArrayBuffer, byteOffset: number): void;
+}
+export interface UniformSlot<T> {
+    readonly pool: UniformPool;
+    readonly layout: UniformLayout<T>;
+    readonly bindGroup: GPUBindGroup;
+    readonly bindGroupLayout: GPUBindGroupLayout;
+    readonly gpu: GPUBuffer;
+    readonly stride: number;
+    push(value: T): number;
+    pushBytes(bytes: ArrayBufferView<ArrayBuffer>): number;
+}
+//# sourceMappingURL=uniform-pool-types.d.ts.map

package/dist/uniform-pool-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uniform-pool-types.d.ts","sourceRoot":"","sources":["../src/uniform-pool-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,uBAAuB,EAAE,CAAC;IACvD,8EAA8E;IAC9E,QAAQ,CAAC,eAAe,CAAC,EAAE,kBAAkB,CAAC;IAC9C,MAAM,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9D;AAED,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IACjC,QAAQ,CAAC,eAAe,EAAE,kBAAkB,CAAC;IAC7C,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC;IACvB,SAAS,CAAC,KAAK,EAAE,eAAe,CAAC,WAAW,CAAC,GAAG,MAAM,CAAC;CACxD"}

package/dist/uniform-pool-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=uniform-pool-types.js.map

package/dist/uniform-pool-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uniform-pool-types.js","sourceRoot":"","sources":["../src/uniform-pool-types.ts"],"names":[],"mappings":""}

package/dist/uniform-pool.d.ts

@@ -0,0 +1,30 @@
+import { type Device } from "@vgpu/core";
+import type { UniformLayout, UniformPoolOptions, UniformSlot } from "./uniform-pool-types.ts";
+export declare class UniformPool {
+    readonly device: Device;
+    readonly minOffsetAlignment: number;
+    readonly capacityBytes: number;
+    readonly maxUniformBindingSize: number;
+    readonly cpuMirror: ArrayBuffer;
+    readonly gpu: GPUBuffer;
+    private readonly bytes;
+    private head;
+    private hasUnflushedPushes;
+    private isDisposed;
+    constructor(device: Device, opts?: UniformPoolOptions);
+    get usedBytes(): number;
+    get disposed(): boolean;
+    alloc<T>(layout: UniformLayout<T>): UniformSlot<T>;
+    push<T>(slot: UniformSlot<T>, value: T): number;
+    pushBytes(slot: UniformSlot<unknown>, bytes: ArrayBufferView<ArrayBuffer>): number;
+    beginFrame(_frameIndex: number): void;
+    endFrame(): void;
+    assertReadyForSubmit(where: string): void;
+    dispose(): void;
+    private assertOwnsSlot;
+    private write;
+    private assertCanPush;
+    private assertLayoutFits;
+    private assertUsable;
+}
+//# sourceMappingURL=uniform-pool.d.ts.map

package/dist/uniform-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uniform-pool.d.ts","sourceRoot":"","sources":["../src/uniform-pool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,MAAM,EAAE,MAAM,YAAY,CAAC;AAapD,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE9F,qBAAa,WAAW;IAWV,QAAQ,CAAC,MAAM,EAAE,MAAM;IAVnC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC;IAChC,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IACnC,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,UAAU,CAAS;gBAEN,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,kBAAuB;IASlE,IAAI,SAAS,IAAI,MAAM,CAAsB;IAC7C,IAAI,QAAQ,IAAI,OAAO,CAA4B;IAEnD,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC;IAMlD,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,MAAM;IAK/C,SAAS,CAAC,IAAI,EAAE,WAAW,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,eAAe,CAAC,WAAW,CAAC,GAAG,MAAM;IAQlF,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAMrC,QAAQ,IAAI,IAAI;IAMhB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAMzC,OAAO,IAAI,IAAI;IAMf,OAAO,CAAC,cAAc;IAKtB,OAAO,CAAC,KAAK;IAUb,OAAO,CAAC,aAAa;IASrB,OAAO,CAAC,gBAAgB;IASxB,OAAO,CAAC,YAAY;CAIrB"}

package/dist/uniform-pool.js

@@ -0,0 +1,127 @@
+import { VGPUError } from "@vgpu/core";
+import { copyDstUsage, defaultCapacityBytes, defaultMaxUniformBindingSize, defaultMinOffsetAlignment, deviceLimit, invalidUsage, roundUp, shaderVisibility, uniformUsage, viewBytes, } from "./uniform-pool-internals.js";
+export class UniformPool {
+    device;
+    minOffsetAlignment;
+    capacityBytes;
+    maxUniformBindingSize;
+    cpuMirror;
+    gpu;
+    bytes;
+    head = 0;
+    hasUnflushedPushes = false;
+    isDisposed = false;
+    constructor(device, opts = {}) {
+        this.device = device;
+        this.capacityBytes = opts.capacityBytes ?? defaultCapacityBytes;
+        this.minOffsetAlignment = deviceLimit(device, "minUniformBufferOffsetAlignment", defaultMinOffsetAlignment);
+        this.maxUniformBindingSize = deviceLimit(device, "maxUniformBufferBindingSize", defaultMaxUniformBindingSize);
+        this.cpuMirror = new ArrayBuffer(this.capacityBytes);
+        this.bytes = new Uint8Array(this.cpuMirror);
+        this.gpu = device.gpu.createBuffer({ label: "vgpu UniformPool", size: this.capacityBytes, usage: uniformUsage | copyDstUsage });
+    }
+    get usedBytes() { return this.head; }
+    get disposed() { return this.isDisposed; }
+    alloc(layout) {
+        this.assertUsable("UniformPool.alloc");
+        this.assertLayoutFits(layout);
+        return new PoolSlot(this, layout, roundUp(layout.size, this.minOffsetAlignment));
+    }
+    push(slot, value) {
+        this.assertOwnsSlot(slot, "UniformPool.push");
+        return this.write(slot.layout.size, slot.stride, (offset) => slot.layout.encode(value, this.cpuMirror, offset));
+    }
+    pushBytes(slot, bytes) {
+        this.assertOwnsSlot(slot, "UniformPool.pushBytes");
+        if (bytes.byteLength !== slot.layout.size) {
+            throw invalidUsage("UniformSlot.pushBytes", `Uniform bytes must match layout size ${slot.layout.size}.`);
+        }
+        return this.write(slot.layout.size, slot.stride, (offset) => this.bytes.set(viewBytes(bytes), offset));
+    }
+    beginFrame(_frameIndex) {
+        this.assertUsable("UniformPool.beginFrame");
+        this.head = 0;
+        this.hasUnflushedPushes = false;
+    }
+    endFrame() {
+        this.assertUsable("UniformPool.endFrame");
+        if (this.hasUnflushedPushes)
+            this.device.gpu.queue.writeBuffer(this.gpu, 0, this.cpuMirror, 0, this.head);
+        this.hasUnflushedPushes = false;
+    }
+    assertReadyForSubmit(where) {
+        this.assertUsable(where);
+        if (!this.hasUnflushedPushes)
+            return;
+        throw invalidUsage(where, "UniformPool has unflushed pushes; call endFrame() before submitting.");
+    }
+    dispose() {
+        if (this.isDisposed)
+            return;
+        this.isDisposed = true;
+        this.gpu.destroy();
+    }
+    assertOwnsSlot(slot, where) {
+        if (slot.pool === this)
+            return;
+        throw invalidUsage(where, "UniformSlot was allocated by a different UniformPool.");
+    }
+    write(layoutSize, stride, encode) {
+        this.assertUsable("UniformSlot.push");
+        this.assertCanPush(layoutSize, stride);
+        const offset = this.head;
+        encode(offset);
+        this.head += stride;
+        this.hasUnflushedPushes = true;
+        return offset;
+    }
+    assertCanPush(layoutSize, stride) {
+        if (this.head + stride <= this.capacityBytes)
+            return;
+        throw new VGPUError({
+            code: "VGPU-UNIFORM-POOL-OVERFLOW",
+            message: `UniformPool capacity ${this.capacityBytes} bytes is exceeded by a ${layoutSize}-byte layout.`,
+            where: "UniformSlot.push",
+        });
+    }
+    assertLayoutFits(layout) {
+        if (layout.size <= this.capacityBytes && layout.size <= this.maxUniformBindingSize)
+            return;
+        throw new VGPUError({
+            code: "VGPU-UNIFORM-LAYOUT-OVERSIZED",
+            message: `Uniform layout size ${layout.size} bytes is too large for this pool.`,
+            where: "UniformPool.alloc",
+        });
+    }
+    assertUsable(where) {
+        if (!this.isDisposed)
+            return;
+        throw invalidUsage(where, "UniformPool has been disposed.");
+    }
+}
+class PoolSlot {
+    pool;
+    layout;
+    stride;
+    bindGroup;
+    bindGroupLayout;
+    gpu;
+    constructor(pool, layout, stride) {
+        this.pool = pool;
+        this.layout = layout;
+        this.stride = stride;
+        this.gpu = pool.gpu;
+        this.bindGroupLayout = layout.bindGroupLayout ?? pool.device.gpu.createBindGroupLayout({
+            label: "UniformPool.slot.bgl",
+            entries: layout.bindings ?? [{ binding: 0, visibility: shaderVisibility(), buffer: { type: "uniform", hasDynamicOffset: true, minBindingSize: layout.size } }],
+        });
+        this.bindGroup = pool.device.gpu.createBindGroup({
+            label: "UniformPool.slot.bg",
+            layout: this.bindGroupLayout,
+            entries: [{ binding: 0, resource: { buffer: this.gpu, offset: 0, size: stride } }],
+        });
+    }
+    push(value) { return this.pool.push(this, value); }
+    pushBytes(bytes) { return this.pool.pushBytes(this, bytes); }
+}
+//# sourceMappingURL=uniform-pool.js.map

package/dist/uniform-pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uniform-pool.js","sourceRoot":"","sources":["../src/uniform-pool.ts"],"names":[],"mappings":"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"}

package/dist/utils/canvas-mouse-tracker.d.ts

@@ -0,0 +1,11 @@
+export interface CanvasMouseTrackerSpec {
+    readonly canvas: HTMLCanvasElement;
+    readonly normalize?: boolean;
+    readonly flipY?: boolean;
+}
+export interface CanvasMouseTracker {
+    readonly position: readonly [number, number];
+    dispose(): void;
+}
+export declare function canvasMouseTracker(spec: CanvasMouseTrackerSpec): CanvasMouseTracker;
+//# sourceMappingURL=canvas-mouse-tracker.d.ts.map

package/dist/utils/canvas-mouse-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-mouse-tracker.d.ts","sourceRoot":"","sources":["../../src/utils/canvas-mouse-tracker.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7C,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,sBAAsB,GAAG,kBAAkB,CAiBnF"}

package/dist/utils/canvas-mouse-tracker.js

@@ -0,0 +1,19 @@
+export function canvasMouseTracker(spec) {
+    let position = Object.freeze([0, 0]);
+    const handler = (event) => {
+        const rect = spec.canvas.getBoundingClientRect();
+        const rawX = Number.isFinite(event.offsetX) ? event.offsetX : event.clientX - rect.left;
+        const rawY = Number.isFinite(event.offsetY) ? event.offsetY : event.clientY - rect.top;
+        const width = spec.canvas.width || rect.width || 1;
+        const height = spec.canvas.height || rect.height || 1;
+        const x = spec.normalize === true ? rawX / width : rawX;
+        const y = spec.normalize === true ? rawY / height : rawY;
+        position = Object.freeze([x, spec.flipY === true ? (spec.normalize === true ? 1 - y : height - y) : y]);
+    };
+    spec.canvas.addEventListener("pointermove", handler);
+    return Object.freeze({
+        get position() { return position; },
+        dispose: () => spec.canvas.removeEventListener("pointermove", handler),
+    });
+}
+//# sourceMappingURL=canvas-mouse-tracker.js.map

package/dist/utils/canvas-mouse-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-mouse-tracker.js","sourceRoot":"","sources":["../../src/utils/canvas-mouse-tracker.ts"],"names":[],"mappings":"AAWA,MAAM,UAAU,kBAAkB,CAAC,IAA4B;IAC7D,IAAI,QAAQ,GAA8B,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAU,CAAC,CAAC;IACzE,MAAM,OAAO,GAAG,CAAC,KAAmB,EAAQ,EAAE;QAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,qBAAqB,EAAE,CAAC;QACjD,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC;QACxF,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC;QACvF,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC;QACnD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;QACtD,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;QACxD,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;QACzD,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAU,CAAC,CAAC;IACnH,CAAC,CAAC;IACF,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;IACrD,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,IAAI,QAAQ,KAAK,OAAO,QAAQ,CAAC,CAAC,CAAC;QACnC,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,mBAAmB,CAAC,aAAa,EAAE,OAAO,CAAC;KACvE,CAAC,CAAC;AACL,CAAC"}

package/dist/utils/canvas-resolution.d.ts

@@ -0,0 +1,9 @@
+export interface CanvasResolution {
+    readonly width: number;
+    readonly height: number;
+    dispose(): void;
+}
+export declare function canvasResolution(canvas: HTMLCanvasElement, opts?: {
+    readonly observe?: boolean;
+}): CanvasResolution;
+//# sourceMappingURL=canvas-resolution.d.ts.map

package/dist/utils/canvas-resolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-resolution.d.ts","sourceRoot":"","sources":["../../src/utils/canvas-resolution.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,iBAAiB,EAAE,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,gBAAgB,CAcnH"}

package/dist/utils/canvas-resolution.js

@@ -0,0 +1,16 @@
+export function canvasResolution(canvas, opts) {
+    let width = canvas.width;
+    let height = canvas.height;
+    const update = () => {
+        width = canvas.width;
+        height = canvas.height;
+    };
+    const observer = opts?.observe === true ? new ResizeObserver(update) : undefined;
+    observer?.observe(canvas);
+    return Object.freeze({
+        get width() { return width; },
+        get height() { return height; },
+        dispose: () => observer?.disconnect(),
+    });
+}
+//# sourceMappingURL=canvas-resolution.js.map

package/dist/utils/canvas-resolution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-resolution.js","sourceRoot":"","sources":["../../src/utils/canvas-resolution.ts"],"names":[],"mappings":"AAMA,MAAM,UAAU,gBAAgB,CAAC,MAAyB,EAAE,IAAqC;IAC/F,IAAI,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;IACzB,IAAI,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAC3B,MAAM,MAAM,GAAG,GAAS,EAAE;QACxB,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;QACrB,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IACzB,CAAC,CAAC;IACF,MAAM,QAAQ,GAAG,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACjF,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1B,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,IAAI,KAAK,KAAK,OAAO,KAAK,CAAC,CAAC,CAAC;QAC7B,IAAI,MAAM,KAAK,OAAO,MAAM,CAAC,CAAC,CAAC;QAC/B,OAAO,EAAE,GAAG,EAAE,CAAC,QAAQ,EAAE,UAAU,EAAE;KACtC,CAAC,CAAC;AACL,CAAC"}

package/dist/utils/frame-clock.d.ts

@@ -0,0 +1,10 @@
+export interface FrameClock {
+    now(): number;
+    delta(): number;
+    reset(): void;
+    pause(): void;
+    resume(): void;
+    readonly isPaused: boolean;
+}
+export declare function frameClock(): FrameClock;
+//# sourceMappingURL=frame-clock.d.ts.map

package/dist/utils/frame-clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-clock.d.ts","sourceRoot":"","sources":["../../src/utils/frame-clock.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,GAAG,IAAI,MAAM,CAAC;IACd,KAAK,IAAI,MAAM,CAAC;IAChB,KAAK,IAAI,IAAI,CAAC;IACd,KAAK,IAAI,IAAI,CAAC;IACd,MAAM,IAAI,IAAI,CAAC;IACf,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,wBAAgB,UAAU,IAAI,UAAU,CA4CvC"}

package/dist/utils/frame-clock.js

@@ -0,0 +1,47 @@
+export function frameClock() {
+    let startTime = performance.now();
+    let lastDeltaTime = startTime;
+    let pausedAt = 0;
+    let accumulatedPause = 0;
+    let paused = false;
+    const activeNow = () => {
+        const current = performance.now();
+        const pendingPause = paused ? current - pausedAt : 0;
+        return current - startTime - accumulatedPause - pendingPause;
+    };
+    return Object.freeze({
+        now: () => activeNow() / 1000,
+        delta: () => {
+            if (paused)
+                return 0;
+            const current = performance.now();
+            const value = (current - lastDeltaTime) / 1000;
+            lastDeltaTime = current;
+            return value;
+        },
+        reset: () => {
+            startTime = performance.now();
+            lastDeltaTime = startTime;
+            pausedAt = 0;
+            accumulatedPause = 0;
+            paused = false;
+        },
+        pause: () => {
+            if (paused)
+                return;
+            pausedAt = performance.now();
+            paused = true;
+        },
+        resume: () => {
+            if (!paused)
+                return;
+            const current = performance.now();
+            accumulatedPause += current - pausedAt;
+            lastDeltaTime += current - pausedAt;
+            pausedAt = 0;
+            paused = false;
+        },
+        get isPaused() { return paused; },
+    });
+}
+//# sourceMappingURL=frame-clock.js.map

package/dist/utils/frame-clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-clock.js","sourceRoot":"","sources":["../../src/utils/frame-clock.ts"],"names":[],"mappings":"AASA,MAAM,UAAU,UAAU;IACxB,IAAI,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAClC,IAAI,aAAa,GAAG,SAAS,CAAC;IAC9B,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,gBAAgB,GAAG,CAAC,CAAC;IACzB,IAAI,MAAM,GAAG,KAAK,CAAC;IAEnB,MAAM,SAAS,GAAG,GAAW,EAAE;QAC7B,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QAClC,MAAM,YAAY,GAAG,MAAM,CAAC,CAAC,CAAC,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QACrD,OAAO,OAAO,GAAG,SAAS,GAAG,gBAAgB,GAAG,YAAY,CAAC;IAC/D,CAAC,CAAC;IAEF,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,GAAG,EAAE,GAAG,EAAE,CAAC,SAAS,EAAE,GAAG,IAAI;QAC7B,KAAK,EAAE,GAAG,EAAE;YACV,IAAI,MAAM;gBAAE,OAAO,CAAC,CAAC;YACrB,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;YAClC,MAAM,KAAK,GAAG,CAAC,OAAO,GAAG,aAAa,CAAC,GAAG,IAAI,CAAC;YAC/C,aAAa,GAAG,OAAO,CAAC;YACxB,OAAO,KAAK,CAAC;QACf,CAAC;QACD,KAAK,EAAE,GAAG,EAAE;YACV,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;YAC9B,aAAa,GAAG,SAAS,CAAC;YAC1B,QAAQ,GAAG,CAAC,CAAC;YACb,gBAAgB,GAAG,CAAC,CAAC;YACrB,MAAM,GAAG,KAAK,CAAC;QACjB,CAAC;QACD,KAAK,EAAE,GAAG,EAAE;YACV,IAAI,MAAM;gBAAE,OAAO;YACnB,QAAQ,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;YAC7B,MAAM,GAAG,IAAI,CAAC;QAChB,CAAC;QACD,MAAM,EAAE,GAAG,EAAE;YACX,IAAI,CAAC,MAAM;gBAAE,OAAO;YACpB,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;YAClC,gBAAgB,IAAI,OAAO,GAAG,QAAQ,CAAC;YACvC,aAAa,IAAI,OAAO,GAAG,QAAQ,CAAC;YACpC,QAAQ,GAAG,CAAC,CAAC;YACb,MAAM,GAAG,KAAK,CAAC;QACjB,CAAC;QACD,IAAI,QAAQ,KAAK,OAAO,MAAM,CAAC,CAAC,CAAC;KAClC,CAAC,CAAC;AACL,CAAC"}

package/dist/utils/index.d.ts

@@ -0,0 +1,7 @@
+export { canvasMouseTracker } from "./canvas-mouse-tracker.ts";
+export type { CanvasMouseTrackerSpec, CanvasMouseTracker } from "./canvas-mouse-tracker.ts";
+export { frameClock } from "./frame-clock.ts";
+export type { FrameClock } from "./frame-clock.ts";
+export { canvasResolution } from "./canvas-resolution.ts";
+export type { CanvasResolution } from "./canvas-resolution.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,YAAY,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC5F,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/utils/index.js

@@ -0,0 +1,4 @@
+export { canvasMouseTracker } from "./canvas-mouse-tracker.js";
+export { frameClock } from "./frame-clock.js";
+export { canvasResolution } from "./canvas-resolution.js";
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC"}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@vgpu/render",
+  "version": "0.0.1",
+  "description": "Render pipeline + render pass abstractions for vgpu.",
+  "keywords": [
+    "webgpu",
+    "graphics",
+    "rendering",
+    "render",
+    "pipeline",
+    "render-pass"
+  ],
+  "homepage": "https://github.com/vercel-labs/vgpu#readme",
+  "bugs": {
+    "url": "https://github.com/vercel-labs/vgpu/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vercel-labs/vgpu.git",
+    "directory": "packages/render"
+  },
+  "license": "MIT",
+  "author": "Matias Gonzalez <matiasngf@hotmail.com>",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./inspect": {
+      "types": "./dist/inspect/index.d.ts",
+      "import": "./dist/inspect/index.js"
+    },
+    "./utils": {
+      "types": "./dist/utils/index.d.ts",
+      "import": "./dist/utils/index.js"
+    },
+    "./edit": {
+      "types": "./dist/edit/index.d.ts",
+      "import": "./dist/edit/index.js"
+    },
+    "./passes": {
+      "types": "./dist/passes/index.d.ts",
+      "import": "./dist/passes/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/tsconfig.tsbuildinfo",
+    "src/**/*.docs.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "wgpu-matrix": "^3.4.2",
+    "@vgpu/core": "0.0.1"
+  },
+  "vgpuExportBundleBudgetsGzipBytes": {
+    ".": 49152,
+    "./inspect": 4096,
+    "./utils": 2048,
+    "./edit": 25600,
+    "./passes": 3584
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc -b",
+    "lint": "tsc -b --pretty false",
+    "test": "cd ../.. && vitest run packages/render"
+  }
+}

package/src/RenderPass.docs.md

@@ -0,0 +1,41 @@
+# RenderPass
+
+`RenderPass` is a command-encoding wrapper for drawing into color
+attachments. Construct it with a core `Device` and `RenderPassOptions`, encode
+render commands, then call `end()` to finish the pass and submit the command
+buffer through `Device.queue`.
+
+`RenderPassOptions` contains `colorAttachments` and an optional `label`.
+`ColorAttachment.view` accepts either a core `Texture` or a raw
+`GPUTextureView`; `loadOp`, `storeOp`, and `clearValue` are forwarded to WebGPU.
+
+Commands mirror the WebGPU render pass encoder:
+
+- `setPipeline(pipeline)` binds a raw `GPURenderPipeline`.
+- `setBindGroup(index, group, dynamicOffsets?)` binds a raw `GPUBindGroup`.
+- `setVertexBuffer(slot, buffer, offset?, size?)` binds a core `Buffer` or raw
+  `GPUBuffer` for vertex input.
+- `draw({ vertexCount, instanceCount?, firstVertex?, firstInstance? })` issues a
+  non-indexed draw. The numeric WebGPU-style `draw(vertexCount, ...)` call is
+  also accepted.
+
+Use `gpu` when you need direct `GPURenderPassEncoder` access for commands that
+are not wrapped yet.
+
+Invariants: a pass is single-use. After `end()`, the underlying
+`GPURenderPassEncoder` is invalid, so `RenderPass.gpu` throws `VGPUError` with
+code `VGPU-RENDER-PASS-ENDED`. Calling `end()` more than once is safe and is a
+no-op after the first submission.
+
+Example:
+
+```ts
+const pass = new RenderPass(device, {
+  colorAttachments: [{ view: target, loadOp: "clear", storeOp: "store", clearValue: [0, 0, 0, 1] }],
+});
+pass.setPipeline(pipeline);
+pass.setBindGroup(0, uniforms);
+pass.setVertexBuffer(0, vertices);
+pass.draw({ vertexCount: 3 });
+pass.end();
+```

package/src/createRenderPipeline.docs.md

@@ -0,0 +1,34 @@
+# createRenderPipeline
+
+Creates a GPU render pipeline from a vgpu `Shader` plus vertex and fragment
+entry points. Returns a raw `GPURenderPipeline` with no wrapper.
+
+## Signature
+
+`createRenderPipeline(device: Device, opts: RenderPipelineOptions): GPURenderPipeline`
+
+## Options
+
+- `shader`: the `Shader` whose compiled GPU module will back both stages.
+- `vertex.entry`: the vertex shader entry-point name.
+- `fragment.entry`: the fragment shader entry-point name.
+- `fragment.targets`: the color target formats and blend/write settings.
+- `primitive`: optional WebGPU primitive state such as topology or culling.
+- `layout`: optional pipeline layout, or `"auto"` to let WebGPU derive one.
+- `label`: optional debug label forwarded to WebGPU.
+
+## Example
+
+```ts
+const pipeline = createRenderPipeline(device, {
+  shader,
+  vertex: { entry: "vs_main" },
+  fragment: { entry: "fs_main", targets: [{ format: "rgba8unorm" }] },
+  primitive: { topology: "triangle-list" },
+});
+```
+
+## Notes
+
+The returned `GPURenderPipeline` can be used directly with WebGPU APIs or
+passed to `RenderPass.setPipeline`.

package/src/domain/camera.docs.md

@@ -0,0 +1,21 @@
+# Camera
+
+A `Camera` is a plain value that contains the data shaders need to draw from a viewpoint.
+
+It has a `viewProjectionMatrix`, a 16-element column-major `Float32Array`, and a `position`, a 3-element vector in world space. Camera factories compute the matrix once when you create the camera.
+
+The returned camera object is frozen, so its fields cannot be replaced. The typed-array buffers are not frozen; mutating them after creation is undefined behavior. Copy a matrix or position first if you need your own editable snapshot.
+
+```ts
+import { perspectiveCamera, degToRad } from "@vgpu/render";
+
+const camera = perspectiveCamera({
+  fovYRadians: degToRad(45),
+  aspect: 1,
+  near: 0.1,
+  far: 100,
+  position: [2, 2, 3],
+  target: [0, 0, 0],
+});
+// camera.viewProjectionMatrix is a 16-element column-major Float32Array.
+```

package/src/domain/deg-to-rad.docs.md

@@ -0,0 +1,9 @@
+# degToRad
+
+Converts degrees to radians for numeric inputs such as camera field-of-view values.
+
+Use it when a design, note, or UI control gives an angle in degrees but the render API expects radians:
+
+```ts
+const fovYRadians = degToRad(50);
+```

package/src/domain/material-factory.docs.md

@@ -0,0 +1,59 @@
+# `material()` factory
+
+`material()` builds a render `Material` from WGSL vertex and fragment source. It injects a uniform struct when the schema has fields, creates the shader module, creates a render pipeline, allocates one uniform buffer, and returns a material with `writeUniforms()` plus raw GPU objects under `.gpu` for advanced use.
+
+## Uniform schema
+
+Pass `uniforms` as an object where each key is the field name used by the shader and each value is a supported WGSL type. The supported types are `f32`, `u32`, `i32`, `vec2f`, `vec3f`, `vec4f`, `vec2u`, `vec3u`, `vec4u`, `vec2i`, `vec3i`, `vec4i`, `mat3x3f`, and `mat4x4f`.
+
+The name `uniforms` is reserved because the factory creates a variable with that name. An empty schema is allowed. With an empty schema the factory does not inject the `Uniforms` struct or binding, and `uniformByteSize` is `0`.
+
+Uniform byte layout follows WGSL alignment rules. Scalars align to 4 bytes, `vec2` values align to 8 bytes, `vec3` and `vec4` values align to 16 bytes, `mat3x3f` occupies 48 bytes, and `mat4x4f` occupies 64 bytes. The final struct size is rounded up to at least 16-byte alignment so `{ time: 'f32' }` has `uniformByteSize === 16`.
+
+## Vertex layouts
+
+Choose one `vertexLayout` value:
+
+- `position-only`: location 0 is `vec3<f32>`, stride 12 bytes.
+- `position-normal`: location 0 is position and location 1 is normal, stride 24 bytes.
+- `position-normal-uv`: location 0 is position, location 1 is normal, and location 2 is uv, stride 32 bytes.
+- `position-uv`: location 0 is position and location 1 is uv, stride 20 bytes.
+
+## WGSL conventions
+
+When the schema is not empty, the factory injects this binding before your shader source:
+
+```wgsl
+struct Uniforms {
+  fieldName: f32,
+};
+@group(0) @binding(0) var<uniform> uniforms: Uniforms;
+```
+
+Your shader reads fields as `uniforms.fieldName`. Provide `vs_main` and `fs_main` entry points.
+
+## Example
+
+```ts
+const mat = material({
+  device,
+  vertexLayout: 'position-only',
+  uniforms: { time: 'f32' },
+  vertex: `
+struct VertexIn { @location(0) position: vec3<f32> };
+@vertex fn vs_main(in: VertexIn) -> @builtin(position) vec4<f32> {
+  return vec4<f32>(in.position, 1.0);
+}`,
+  fragment: `
+@fragment fn fs_main() -> @location(0) vec4<f32> {
+  let pulse = 0.5 + 0.5 * sin(uniforms.time);
+  return vec4<f32>(pulse, 0.2, 1.0 - pulse, 1.0);
+}`,
+});
+
+mat.writeUniforms?.({ time: performance.now() / 1000 });
+```
+
+## `writeUniforms()`
+
+`writeUniforms()` is strict. Pass every uniform on every call, and make the keys match the schema exactly. A missing key or an extra key throws `VGPU-CORE-INVALID-USAGE`. Values can be numbers, arrays, or typed arrays. Matrix values are passed in column-major order.

package/src/domain/material.docs.md

@@ -0,0 +1,12 @@
+# Material
+
+A `Material` is the GPU state needed to draw a mesh with a shader. It contains:
+
+- `pipeline`: the ready-to-bind `GPURenderPipeline`.
+- `bindGroupLayout`: the layout for per-draw uniforms at group 0.
+- `shader`: the compiled vgpu shader object.
+- `uniformByteSize`: the number of bytes each uniform record must provide.
+
+Use the `material()` factory to build custom materials from WGSL vertex and fragment entry points.
+
+`MaterialUniformValue` is the value shape accepted by generic material uniform writers: a number, readonly number array, or typed numeric array.