aigpu 0.3.1

package/dist/timer.js

@@ -0,0 +1,261 @@
+import { timerCapacityError, timerInvalidError } from "./errors.js";
+import { FRAME_PASS_ATTACHMENT } from "./frame-protocols.js";
+import { liveKernel, ownQueryFeature } from "./live-kernel.js";
+import { createQueryRing } from "./query-ring.js";
+/** Initial capacity in spans; each span writes a begin/end timestamp pair (2 queries). */
+const INITIAL_SPAN_CAPACITY = 32;
+/** WebGPU createQuerySet: "descriptor.count must be ≤ 4096" — a fixed constant, so at most 2048 begin/end pairs. */
+const MAX_QUERIES = 4096;
+const MAX_SPANS_PER_FRAME = MAX_QUERIES / 2;
+const MS_PER_NS = 1 / 1_000_000;
+class InternalTimerSpan {
+    name;
+    owner;
+    constructor(name, owner) {
+        this.name = name;
+        this.owner = owner;
+    }
+    /**
+     * Frame pass attachment: registering the span is what returns the descriptor's `timestampWrites`
+     * (undefined when the span is dropped this frame because the query set is full). The owner is the
+     * timer, not the span, so a frame that attaches two spans of the same timer bookkeeps one owner.
+     */
+    [FRAME_PASS_ATTACHMENT](ctx) {
+        return { owner: this.owner, timestampWrites: this.owner.attachSpan(this, ctx.frame, ctx.device) };
+    }
+}
+/** @internal */
+export function createTimer(device, host = {}) {
+    return new InternalTimer(device, host);
+}
+/**
+ * GPU pass timing for this gpu. Needs the "timestamp-query" device feature — request it at init:
+ * `init({ requiredFeatures: ["timestamp-query"] })`.
+ *
+ * The timer owns a query ring: its readbacks join `gpu.settled()`, a dropped readback is reported
+ * on `gpu.onError`, and `gpu.dispose()` releases the query set (deferring destruction while a frame
+ * in flight still references it). `timer.dispose()` releases it earlier and drops the registration.
+ */
+export function timer(gpu) {
+    const kernel = liveKernel(gpu, "timer");
+    return ownQueryFeature(kernel, (host) => new InternalTimer(kernel.device, host));
+}
+/**
+ * Ring-1 GPU pass timer. Owns name→span bookkeeping per frame, contiguous
+ * begin/end index pair allocation, ns→ms conversion, and onResults dispatch;
+ * the query set + resolve/readback plumbing lives in the shared query ring.
+ *
+ * @internal
+ */
+export class InternalTimer {
+    #device;
+    #host;
+    #spans = new Map();
+    #listeners = new Set();
+    #ring;
+    #capacity = INITIAL_SPAN_CAPACITY * 2;
+    /** High-water query demand; capacity grows to cover it at the next frame boundary. */
+    #demand = INITIAL_SPAN_CAPACITY * 2;
+    #frame;
+    #frameSpans = [];
+    #frameNames = new Set();
+    #usedQueries = 0;
+    #encodedSpans;
+    #resultSeq = 0;
+    #appliedSeq = -1;
+    /**
+     * One retain per open frame whose pass descriptors reference a ring's query set, keyed by frame
+     * identity and remembering *which* ring it pinned (capacity growth swaps the ring mid-life).
+     * Released only when that frame reports back — submitted, failed or abandoned — because nothing
+     * else proves the frame's encoder is done with the query set: age does not (a Frame held for many
+     * frames can still be submitted), so a Frame the caller drops without submit() keeps its retain
+     * until gpu.dispose() or device loss, exactly like a native GPUCommandEncoder that never finishes.
+     */
+    #frameRetains = new Map();
+    #disposed = false;
+    constructor(device, host = {}) {
+        // Mirrors WebGPU "Validate timestampWrites": '"timestamp-query" must be enabled for device' — and
+        // createQuerySet would throw a TypeError for a timestamp set without it. Fail at creation instead.
+        if (!device.features.has("timestamp-query")) {
+            throw timerInvalidError(`timer(gpu) needs the "timestamp-query" device feature — request it at init: init({ requiredFeatures: ["timestamp-query"] }).`, `Pass init({ requiredFeatures: ["timestamp-query"] }) on an adapter that supports it; gate optional timing on gpu.device.features.has("timestamp-query").`);
+        }
+        this.#device = device;
+        this.#host = host;
+        this.#ring = this.#createRing();
+    }
+    span(name) {
+        this.#assertUsable("Timer.span");
+        if (typeof name !== "string" || name.length === 0) {
+            throw timerInvalidError(`span name received ${previewName(name)}; expected a non-empty string.`, `Name each timed pass, e.g. timer.span("shadows").`, "Timer.span");
+        }
+        let span = this.#spans.get(name);
+        if (!span) {
+            span = new InternalTimerSpan(name, this);
+            this.#spans.set(name, span);
+        }
+        return span;
+    }
+    onResults(cb) {
+        this.#assertUsable("Timer.onResults");
+        this.#listeners.add(cb);
+        return () => { this.#listeners.delete(cb); };
+    }
+    dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        this.#listeners.clear();
+        this.#spans.clear();
+        this.#frameNames.clear();
+        this.#frameSpans = [];
+        this.#encodedSpans = undefined;
+        // The ring defers its destruction while the current frame still references the query set from a
+        // pass descriptor (released at frameSubmitted or at the next frame boundary).
+        this.#ring.dispose();
+        this.#host.onDispose?.();
+    }
+    /**
+     * @internal Frame.pass hook: registers the span for the current frame and returns the pass
+     * descriptor's timestampWrites, or undefined when the span is dropped for this frame because
+     * the query set is full (capacity grows at the next frame boundary — never mid-frame, since
+     * earlier passes already reference the current set).
+     */
+    attachSpan(span, frame, frameDevice) {
+        this.#assertUsable("Frame.pass");
+        if (frameDevice !== this.#device) {
+            throw timerInvalidError(`span '${span.name}' belongs to a timer created on a different gpu; timestamp queries cannot cross devices.`, "Create one timer(gpu) per gpu and use its spans only with that gpu's frames.", "Frame.pass");
+        }
+        if (frame !== this.#frame)
+            this.#beginFrame(frame);
+        if (this.#frameNames.has(span.name)) {
+            throw timerInvalidError(`duplicate span '${span.name}' in one frame; each result key holds a single begin/end pair per frame.`, `Use one timer.span(name) per pass per frame, e.g. timer.span("${span.name}-2") for the second pass.`, "Frame.pass");
+        }
+        if (this.#frameNames.size >= MAX_SPANS_PER_FRAME) {
+            throw timerCapacityError(MAX_SPANS_PER_FRAME, MAX_QUERIES);
+        }
+        this.#frameNames.add(span.name);
+        const begin = this.#frameNames.size * 2 - 2;
+        if (this.#demand < begin + 2)
+            this.#demand = begin + 2;
+        // Mirrors WebGPU "Validate timestampWrites": each provided index must be < querySet.count.
+        if (begin + 2 > this.#ring.capacity)
+            return undefined;
+        this.#usedQueries = begin + 2;
+        this.#frameSpans.push({ name: span.name, begin });
+        // The descriptor now references the ring's query set for the rest of the frame: keep the ring alive
+        // even if dispose() lands mid-frame (destroying a referenced set would invalidate the pass).
+        // The retain is per frame, so a second frame opened while this one is still unsubmitted cannot
+        // release it — both keep the set alive until each of them is submitted or abandoned.
+        this.#retainRing(frame);
+        // "Of the write index members ... at least one must be provided ... no two may be equal": begin/end pairs are distinct by construction.
+        return { querySet: this.#ring.querySet, beginningOfPassWriteIndex: begin, endOfPassWriteIndex: begin + 1 };
+    }
+    /** @internal Frame.submit hook, before encoder.finish(): appends this frame's single resolve to the frame encoder. */
+    finalizeFrame(frame, encoder) {
+        this.#encodedSpans = undefined;
+        if (this.#disposed || frame !== this.#frame || this.#usedQueries === 0)
+            return;
+        if (this.#ring.encodeResolve(encoder, this.#usedQueries))
+            this.#encodedSpans = [...this.#frameSpans];
+    }
+    /** @internal Frame.submit hook, after queue.submit succeeds: starts the non-blocking readback. */
+    frameSubmitted(frame) {
+        // Release *this* frame's retain first, whichever ring it pinned: the command buffer is submitted
+        // (or the frame was abandoned), so nothing it encoded references that query set anymore, and a
+        // dispose() that landed mid-frame can now destroy the ring. Runs before the identity check so a
+        // frame that is no longer the current one — another frame was opened meanwhile — still releases.
+        this.#releaseRing(frame);
+        // Results stay identity-scoped: only the current frame's encoded resolve is read back.
+        if (frame !== this.#frame)
+            return;
+        if (this.#disposed)
+            return;
+        const spans = this.#encodedSpans;
+        this.#encodedSpans = undefined;
+        if (!spans || spans.length === 0)
+            return;
+        const seq = this.#resultSeq;
+        this.#resultSeq += 1;
+        this.#ring.onSubmitted((values) => {
+            // The ring orders its own readbacks; this guard extends the ordering across ring recreations (capacity growth).
+            if (seq <= this.#appliedSeq)
+                return;
+            this.#appliedSeq = seq;
+            this.#dispatch(spans, values);
+        });
+    }
+    /**
+     * @internal Frame abandon hook (a failed pass, a failed finish/submit, or Frame.cancel()): the
+     * frame ends without ever reaching the queue. Drops the pending encoded state so no readback can
+     * decode stale staging bytes as a phantom duration, and releases the retain this frame took when
+     * it attached a span — the counterpart of frameSubmitted() for frames that never submit.
+     */
+    frameAbandoned(frame) {
+        if (frame === this.#frame)
+            this.#encodedSpans = undefined;
+        this.#releaseRing(frame);
+    }
+    #beginFrame(frame) {
+        if (this.#demand > this.#ring.capacity) {
+            // Grow only at frame boundaries. The retired ring keeps applying its in-flight readbacks
+            // before releasing its resources, so growth never drops results already submitted.
+            this.#ring.dispose();
+            this.#capacity = Math.min(MAX_QUERIES, nextPowerOfTwo(this.#demand));
+            this.#ring = this.#createRing();
+        }
+        this.#demand = this.#capacity;
+        this.#frame = frame;
+        this.#frameSpans = [];
+        this.#frameNames.clear();
+        this.#usedQueries = 0;
+    }
+    #dispatch(spans, values) {
+        const results = {};
+        for (const { name, begin } of spans) {
+            const start = values[begin] ?? 0n;
+            const end = values[begin + 1] ?? 0n;
+            // Timestamps are implementation-defined ns ticks and the counter may reset between writes
+            // ("unexpected values such as negative deltas ... can safely be discarded"): clamp negatives to 0.
+            results[name] = end > start ? Number(end - start) * MS_PER_NS : 0;
+        }
+        const frozen = Object.freeze(results);
+        for (const listener of [...this.#listeners]) {
+            try {
+                listener(frozen);
+            }
+            catch (error) {
+                console.error(error);
+            }
+        }
+    }
+    #retainRing(frame) {
+        if (this.#frameRetains.has(frame))
+            return;
+        this.#frameRetains.set(frame, this.#ring);
+        this.#ring.retain();
+    }
+    #releaseRing(frame) {
+        const ring = this.#frameRetains.get(frame);
+        if (!ring)
+            return;
+        this.#frameRetains.delete(frame);
+        ring.release();
+    }
+    #createRing() {
+        return createQueryRing(this.#device, { type: "timestamp", capacity: this.#capacity, label: "aigpu.timer", trackSettled: this.#host.trackSettled, errorSink: this.#host.errorSink });
+    }
+    #assertUsable(where) {
+        if (this.#disposed)
+            throw timerInvalidError("the timer is disposed.", "Create a new timer with timer(gpu).", where);
+    }
+}
+function nextPowerOfTwo(value) {
+    let result = 1;
+    while (result < value)
+        result *= 2;
+    return result;
+}
+function previewName(value) {
+    return typeof value === "string" ? `'${value}'` : String(value);
+}
+//# sourceMappingURL=timer.js.map

package/dist/timer.js.map

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

package/dist/uniforms-layout.d.ts

@@ -0,0 +1,8 @@
+import type { HostShareableLayout } from "@aigpu/wgsl/reflect-source";
+/** Builds the binary compatibility signature used by shared uniforms after first-bind adoption. */
+export declare function sharedUniformLayoutSignature(layout: HostShareableLayout): string;
+/** Formats a reflected layout for Lane-E shared-uniform diagnostics. */
+export declare function formatSharedUniformLayout(layout: HostShareableLayout, opts?: {
+    readonly abbreviated?: boolean;
+}): string;
+//# sourceMappingURL=uniforms-layout.d.ts.map

package/dist/uniforms-layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uniforms-layout.d.ts","sourceRoot":"","sources":["../src/uniforms-layout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAA0B,MAAM,4BAA4B,CAAC;AAE9F,mGAAmG;AACnG,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAEhF;AAED,wEAAwE;AACxE,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,mBAAmB,EAAE,IAAI,GAAE;IAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,MAAM,CAI5H"}

package/dist/uniforms-layout.js

@@ -0,0 +1,84 @@
+/** Builds the binary compatibility signature used by shared uniforms after first-bind adoption. */
+export function sharedUniformLayoutSignature(layout) {
+    return JSON.stringify(signatureNode(layout));
+}
+/** Formats a reflected layout for Lane-E shared-uniform diagnostics. */
+export function formatSharedUniformLayout(layout, opts = {}) {
+    if (layout.members?.length)
+        return formatStructLayout(layout.members, opts.abbreviated === true);
+    if (layout.element)
+        return formatArrayLayout(layout);
+    return formatType(layout.type);
+}
+function signatureNode(layout) {
+    return {
+        type: typeSignature(layout.type),
+        align: layout.align,
+        size: layout.size,
+        stride: layout.stride,
+        members: layout.members?.map(memberSignature),
+        element: layout.element ? signatureNode(layout.element) : undefined,
+    };
+}
+function memberSignature(member) {
+    return {
+        name: member.name,
+        offset: member.offset,
+        align: member.align,
+        size: member.size,
+        explicitAlign: member.explicitAlign,
+        explicitSize: member.explicitSize,
+        type: typeSignature(member.type),
+        layout: signatureNode(member.layout),
+    };
+}
+function typeSignature(type) {
+    switch (type.kind) {
+        case "scalar": return { scalar: type.name };
+        case "vector": return { vector: type.width, element: typeSignature(type.element) };
+        case "matrix": return { matrix: [type.columns, type.rows], element: typeSignature(type.element) };
+        case "array": return { array: typeSignature(type.element), count: type.count ?? type.countExpression };
+        case "atomic": return { atomic: typeSignature(type.element) };
+        default: return type.kind;
+    }
+}
+function formatStructLayout(members, abbreviated) {
+    const shown = abbreviated ? members.slice(0, 1) : members;
+    const suffix = abbreviated && members.length > 1 ? ", ..." : "";
+    return `{ ${shown.map(formatMember).join(", ")}${suffix} }`;
+}
+function formatArrayLayout(layout) {
+    const count = arrayCount(layout.type);
+    const suffix = count === undefined ? "" : `, ${count}`;
+    return `array<${formatSharedUniformLayout(layout.element)}${suffix}>`;
+}
+function formatMember(member) {
+    return `${member.name}: ${formatSharedUniformLayout(member.layout)}`;
+}
+function formatType(type) {
+    switch (type.kind) {
+        case "scalar": return type.name;
+        case "vector": return `vec${type.width}${scalarSuffix(type.element)}`;
+        case "matrix": return `mat${type.columns}x${type.rows}${scalarSuffix(type.element)}`;
+        case "array": return formatArrayType(type);
+        case "identifier": return type.name;
+        case "atomic": return `atomic<${formatType(type.element)}>`;
+        default: return type.kind;
+    }
+}
+function formatArrayType(type) {
+    const count = type.count ?? type.countExpression;
+    const suffix = count === undefined ? "" : `, ${count}`;
+    return `array<${formatType(type.element)}${suffix}>`;
+}
+function scalarSuffix(type) {
+    if (type.kind !== "scalar")
+        return "";
+    if (type.name === "bool")
+        return "b";
+    return type.name.slice(0, 1);
+}
+function arrayCount(type) {
+    return type.kind === "array" ? type.count ?? type.countExpression : undefined;
+}
+//# sourceMappingURL=uniforms-layout.js.map

package/dist/uniforms-layout.js.map

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

package/dist/uniforms.d.ts

@@ -0,0 +1,43 @@
+import type { Buffer, Device } from "@aigpu/core";
+import type { BindingInfo } from "@aigpu/wgsl/reflect-source";
+import type { SharedUniforms } from "./api-types.ts";
+import type { Gpu } from "./kernel.ts";
+import { BINDING_RESOURCE, type BindingResourceProvider } from "./draw-protocols.ts";
+import type { NormalizedBindingResource } from "./set-resources.ts";
+/**
+ * Values-first shared uniform/storage buffer. The WGSL layout is adopted lazily from
+ * the first shader that binds this object, keeping the backing buffer identity stable.
+ */
+export declare class SharedUniformsImpl<T extends Record<string, unknown>> implements SharedUniforms<T>, BindingResourceProvider {
+    #private;
+    private readonly device;
+    constructor(device: Device, initialValues: T);
+    get buffer(): Buffer | undefined;
+    get gpu(): GPUBuffer | undefined;
+    get size(): number | undefined;
+    set(values: Partial<T>): void;
+    /**
+     * Adopts or validates the reflected binding layout, then returns a user-owned resource.
+     *
+     * Keyed by the nominal protocol symbol so `set-resources.ts` recognizes a shared uniforms block
+     * without importing this module: binding a plain buffer must not link the layout machinery.
+     */
+    [BINDING_RESOURCE](binding: BindingInfo, sourceHint: string): NormalizedBindingResource;
+    /**
+     * Frees the backing buffer, if the layout was already adopted. Idempotent, and a no-op for an
+     * object that no shader ever bound — the buffer only exists after adoption.
+     *
+     * @internal Lifetime is the gpu's: `gpu.dispose()` runs this in the resource phase.
+     */
+    destroy(): void;
+}
+export declare function createSharedUniforms<T extends Record<string, unknown>>(device: Device, values: T): SharedUniformsImpl<T>;
+/**
+ * Values-first shared uniform/storage block for this gpu. Bind the same object in several shaders:
+ * the WGSL layout is adopted from the first binding that uses it and validated against the rest, so
+ * one `set()` updates every consumer through a single buffer.
+ *
+ * The buffer (created on adoption) is freed by `gpu.dispose()`.
+ */
+export declare function uniforms<T extends Record<string, unknown>>(gpu: Gpu, values: T): SharedUniforms<T>;
+//# sourceMappingURL=uniforms.d.ts.map

package/dist/uniforms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uniforms.d.ts","sourceRoot":"","sources":["../src/uniforms.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAuB,MAAM,4BAA4B,CAAC;AACnF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAEvC,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AACrF,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAepE;;;GAGG;AACH,qBAAa,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,YAAW,cAAc,CAAC,CAAC,CAAC,EAAE,uBAAuB;;IAK1G,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;IAI7D,IAAI,MAAM,IAAI,MAAM,GAAG,SAAS,CAA4B;IAC5D,IAAI,GAAG,IAAI,SAAS,GAAG,SAAS,CAAiC;IACjE,IAAI,IAAI,IAAI,MAAM,GAAG,SAAS,CAAqC;IAEnE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI;IAK7B;;;;;OAKG;IACH,CAAC,gBAAgB,CAAC,CAAC,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,GAAG,yBAAyB;IA+DvF;;;;;OAKG;IACH,OAAO,IAAI,IAAI;CAGhB;AAED,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAExH;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAGlG"}

package/dist/uniforms.js

@@ -0,0 +1,176 @@
+import { liveKernel, ownResource } from "./live-kernel.js";
+import { BINDING_RESOURCE } from "./draw-protocols.js";
+import { sharedUniformLayoutMismatchError, unsupportedError } from "./errors.js";
+import { writeLayoutValue } from "./set-packing.js";
+import { formatSharedUniformLayout, sharedUniformLayoutSignature } from "./uniforms-layout.js";
+import { assertBufferUsable } from "./lifecycle.js";
+/**
+ * Values-first shared uniform/storage buffer. The WGSL layout is adopted lazily from
+ * the first shader that binds this object, keeping the backing buffer identity stable.
+ */
+export class SharedUniformsImpl {
+    device;
+    #values;
+    #state;
+    #bufferRef;
+    constructor(device, initialValues) {
+        this.device = device;
+        this.#values = cloneRecord(initialValues);
+    }
+    get buffer() { return this.#bufferRef; }
+    get gpu() { return this.#bufferRef?.gpu; }
+    get size() { return this.#state?.layout.size; }
+    set(values) {
+        mergeInto(this.#values, values);
+        this.#writeCurrentValues();
+    }
+    /**
+     * Adopts or validates the reflected binding layout, then returns a user-owned resource.
+     *
+     * Keyed by the nominal protocol symbol so `set-resources.ts` recognizes a shared uniforms block
+     * without importing this module: binding a plain buffer must not link the layout machinery.
+     */
+    [BINDING_RESOURCE](binding, sourceHint) {
+        ensureBufferBinding(binding);
+        const adopted = this.#ensureLayout(binding, sourceHint);
+        const buffer = this.#requiredBuffer();
+        assertBufferUsable(buffer, `${sourceHint}.set`);
+        return {
+            resource: { buffer: buffer.gpu, offset: 0, size: adopted.layout.size },
+            identity: buffer.resourceIdentity,
+            unsubscribe: (cb) => buffer.onDestroy(cb),
+        };
+    }
+    #ensureLayout(binding, sourceHint) {
+        const layout = staticBindingLayout(binding);
+        const addressSpace = normalizeAddressSpace(binding.addressSpace);
+        if (!this.#state)
+            return this.#adoptLayout(binding, layout, addressSpace, sourceHint);
+        this.#assertCompatibleLayout(binding, layout, addressSpace, sourceHint);
+        return this.#state;
+    }
+    #adoptLayout(binding, layout, addressSpace, sourceHint) {
+        this.#state = {
+            layout,
+            layoutSignature: sharedUniformLayoutSignature(layout),
+            layoutText: formatSharedUniformLayout(layout),
+            sourceHint,
+            bindingName: binding.name,
+            addressSpace,
+        };
+        this.#bufferRef = this.device.createBuffer({
+            size: layout.size,
+            usage: addressSpace === "storage" ? ["storage", "copy_dst"] : ["uniform", "copy_dst"],
+            label: `${binding.name}.sharedUniform`,
+        });
+        this.#writeCurrentValues();
+        return this.#state;
+    }
+    #assertCompatibleLayout(binding, layout, addressSpace, sourceHint) {
+        const state = this.#state;
+        if (state.addressSpace !== addressSpace) {
+            throw unsupportedError("uniforms", `shared uniforms '${state.bindingName}' already adopted address space ${state.addressSpace}; '${binding.name}' uses ${addressSpace}.`);
+        }
+        if (sharedUniformLayoutSignature(layout) === state.layoutSignature)
+            return;
+        throw sharedUniformLayoutMismatchError({
+            bindingName: state.bindingName,
+            adoptedLayout: state.layoutText,
+            adoptedSource: state.sourceHint,
+            incomingLayout: formatSharedUniformLayout(layout, { abbreviated: true }),
+            incomingSource: sourceHint,
+        });
+    }
+    #writeCurrentValues() {
+        if (!this.#state || !this.#bufferRef)
+            return;
+        this.#bufferRef.write(writeLayoutValue(this.#state.layout, this.#values), 0);
+    }
+    #requiredBuffer() {
+        if (!this.#bufferRef)
+            throw unsupportedError("uniforms", "shared uniforms have not adopted a layout yet.");
+        return this.#bufferRef;
+    }
+    /**
+     * Frees the backing buffer, if the layout was already adopted. Idempotent, and a no-op for an
+     * object that no shader ever bound — the buffer only exists after adoption.
+     *
+     * @internal Lifetime is the gpu's: `gpu.dispose()` runs this in the resource phase.
+     */
+    destroy() {
+        this.#bufferRef?.destroy();
+    }
+}
+export function createSharedUniforms(device, values) {
+    return new SharedUniformsImpl(device, values);
+}
+/**
+ * Values-first shared uniform/storage block for this gpu. Bind the same object in several shaders:
+ * the WGSL layout is adopted from the first binding that uses it and validated against the rest, so
+ * one `set()` updates every consumer through a single buffer.
+ *
+ * The buffer (created on adoption) is freed by `gpu.dispose()`.
+ */
+export function uniforms(gpu, values) {
+    const kernel = liveKernel(gpu, "uniforms");
+    return ownResource(kernel, new SharedUniformsImpl(kernel.device, values), (shared) => shared.destroy());
+}
+function ensureBufferBinding(binding) {
+    if (binding.bindingLayout?.kind === "buffer")
+        return;
+    throw unsupportedError("uniforms", `Binding '${binding.name}' does not accept shared uniforms; the shader reflected ${binding.bindingLayout?.kind ?? "none"}.`);
+}
+function staticBindingLayout(binding) {
+    if (!binding.layout)
+        throw unsupportedError("uniforms", `Binding '${binding.name}' does not expose a host-shareable layout.`);
+    if (binding.layout.size === undefined)
+        throw unsupportedError("uniforms", `Binding '${binding.name}' has a runtime-sized layout; it cannot be shared.`);
+    return binding.layout;
+}
+function mergeInto(target, patch) {
+    for (const [key, value] of Object.entries(patch)) {
+        if (isUnsafeKey(key))
+            continue;
+        if (isPlainObject(value) && isPlainObject(target[key]))
+            mergeInto(target[key], value);
+        else
+            target[key] = cloneValue(value);
+    }
+}
+function cloneRecord(value) {
+    const next = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (isUnsafeKey(key))
+            continue;
+        next[key] = cloneValue(entry);
+    }
+    return next;
+}
+function isUnsafeKey(key) {
+    return key === "__proto__" || key === "constructor" || key === "prototype";
+}
+function cloneValue(value) {
+    if (Array.isArray(value))
+        return value.map(cloneValue);
+    if (ArrayBuffer.isView(value))
+        return cloneTypedArray(value);
+    if (isPlainObject(value))
+        return cloneRecord(value);
+    return value;
+}
+function cloneTypedArray(value) {
+    if (value instanceof Float32Array)
+        return value.slice();
+    if (value instanceof Uint32Array)
+        return value.slice();
+    if (value instanceof Int32Array)
+        return value.slice();
+    return value;
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) && !ArrayBuffer.isView(value);
+}
+function normalizeAddressSpace(addressSpace) {
+    return addressSpace === "storage" ? "storage" : "uniform";
+}
+//# sourceMappingURL=uniforms.js.map

package/dist/uniforms.js.map

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