aigpu 0.3.1

package/dist/clock.js

@@ -0,0 +1,50 @@
+/**
+ * The frame clock of a gpu, as a free function over the lazy frame-state service.
+ *
+ * `clock(gpu)` is the only public clock: `Frame` does not duplicate it. Reading it never creates
+ * anything a frame would not have created anyway, and a program that never opens a frame and never
+ * calls `clock()` never allocates the service.
+ */
+import { frameState } from "./frame-state.js";
+import { assertDeviceUsable } from "./lifecycle.js";
+import { gpuDisposedError, liveKernel } from "./live-kernel.js";
+import { clockDeltaInvalidError } from "./errors.js";
+import { serviceToken } from "./kernel.js";
+/** One clock facade per gpu, so `clock(gpu) === clock(gpu)`. */
+const clockToken = serviceToken("clock");
+/**
+ * The frame clock of `gpu`.
+ *
+ * Without `advance()`, every `frame()` moves `time` forward by the wall-clock delta since the last
+ * frame — the default 0.1.x behavior. With `advance(dt)`, you own the clock for that frame.
+ *
+ * Throws `AIGPU-GPU-DISPOSED` after `gpu.dispose()`.
+ */
+export function clock(gpu) {
+    return createClock(liveKernel(gpu, "clock"));
+}
+function createClock(kernel) {
+    return kernel.service(clockToken, (self) => {
+        const state = frameState(self);
+        const assertLive = (where) => {
+            if (self.disposed)
+                throw gpuDisposedError(where);
+            // The clock is the frame-state entry point, and a retained external device can be lost or
+            // destroyed by its owner while this gpu still looks alive. Reading or advancing then reports
+            // state that can no longer reach a device, so re-check the device itself.
+            assertDeviceUsable(self.device, where);
+        };
+        return {
+            get time() { assertLive("clock.time"); return state.time; },
+            get deltaTime() { assertLive("clock.deltaTime"); return state.deltaTime; },
+            get frameCount() { assertLive("clock.frameCount"); return state.frameCount; },
+            advance(dtSeconds) {
+                assertLive("clock.advance");
+                if (typeof dtSeconds !== "number" || !Number.isFinite(dtSeconds) || dtSeconds < 0)
+                    throw clockDeltaInvalidError(dtSeconds);
+                state.advanceBy(dtSeconds);
+            },
+        };
+    });
+}
+//# sourceMappingURL=clock.js.map

package/dist/clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.js","sourceRoot":"","sources":["../src/clock.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,YAAY,EAAyB,MAAM,aAAa,CAAC;AAkBlE,gEAAgE;AAChE,MAAM,UAAU,GAAG,YAAY,CAAQ,OAAO,CAAC,CAAC;AAEhD;;;;;;;GAOG;AACH,MAAM,UAAU,KAAK,CAAC,GAAQ;IAC5B,OAAO,WAAW,CAAC,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED,SAAS,WAAW,CAAC,MAAc;IACjC,OAAO,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,EAAE;QACzC,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;QAC/B,MAAM,UAAU,GAAG,CAAC,KAAa,EAAE,EAAE;YACnC,IAAI,IAAI,CAAC,QAAQ;gBAAE,MAAM,gBAAgB,CAAC,KAAK,CAAC,CAAC;YACjD,0FAA0F;YAC1F,6FAA6F;YAC7F,0EAA0E;YAC1E,kBAAkB,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QACzC,CAAC,CAAC;QACF,OAAO;YACL,IAAI,IAAI,KAAa,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;YACnE,IAAI,SAAS,KAAa,UAAU,CAAC,iBAAiB,CAAC,CAAC,CAAC,OAAO,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;YAClF,IAAI,UAAU,KAAa,UAAU,CAAC,kBAAkB,CAAC,CAAC,CAAC,OAAO,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC;YACrF,OAAO,CAAC,SAAiB;gBACvB,UAAU,CAAC,eAAe,CAAC,CAAC;gBAC5B,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,GAAG,CAAC;oBAAE,MAAM,sBAAsB,CAAC,SAAS,CAAC,CAAC;gBAC3H,KAAK,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;YAC7B,CAAC;SACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/compute.d.ts

@@ -0,0 +1,41 @@
+import type { Device } from "@aigpu/core";
+import type { ShaderSource } from "@aigpu/wgsl";
+import { type Reflection } from "@aigpu/wgsl/reflect-source";
+import { type BindGroupCache } from "./bind-cache.ts";
+import { type SetBag, type SetCore } from "./set-core.ts";
+import type { Compute, ComputeOptions, DispatchOptions } from "./api-types.ts";
+import type { Gpu } from "./kernel.ts";
+/**
+ * Compute pipeline for this gpu, ready to `set()` bindings and `dispatch()`.
+ *
+ * Each compute owns its own pipeline (no shared pipeline store), but it resolves the gpu's single
+ * lazy bind group cache through the kernel, so a bind group built for a draw and one built here are
+ * the same object when the resources match — and the cache is torn down once, in the service phase.
+ */
+export declare function compute(gpu: Gpu, source: string | ShaderSource, opts?: ComputeOptions): Compute;
+/**
+ * Internal Ring-1 compute implementation behind `compute(gpu, source, opts)`.
+ *
+ * @internal
+ */
+export declare class ComputePipeline implements Compute {
+    #private;
+    private readonly device;
+    readonly source: string;
+    readonly opts: ComputeOptions;
+    private readonly cache;
+    readonly id: number;
+    readonly label: string;
+    readonly reflection: Reflection;
+    readonly entryPoint: string;
+    readonly setCore: SetCore;
+    readonly bindGroupLayouts: ReadonlyMap<number, GPUBindGroupLayout>;
+    readonly pipelineLayout: GPUPipelineLayout;
+    readonly shaderModule: GPUShaderModule;
+    readonly pipeline: GPUComputePipeline;
+    constructor(device: Device, source: string, opts?: ComputeOptions, cache?: BindGroupCache);
+    set(values: SetBag): this;
+    dispatch(x: number, y?: number, z?: number): void;
+    dispatch(opts: DispatchOptions): void;
+}
+//# sourceMappingURL=compute.d.ts.map

package/dist/compute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compute.d.ts","sourceRoot":"","sources":["../src/compute.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAwD,KAAK,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAEnH,OAAO,EAAqC,KAAK,cAAc,EAA8B,MAAM,iBAAiB,CAAC;AACrH,OAAO,EAAmE,KAAK,MAAM,EAAE,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AAE3H,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAI/E,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAMvC;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAG,YAAY,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAGnG;AAID;;;;GAIG;AACH,qBAAa,eAAgB,YAAW,OAAO;;IAa3C,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,EAAE,cAAc;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK;IAfxB,QAAQ,CAAC,EAAE,SAAmB;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,gBAAgB,EAAE,WAAW,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IACnE,QAAQ,CAAC,cAAc,EAAE,iBAAiB,CAAC;IAC3C,QAAQ,CAAC,YAAY,EAAE,eAAe,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;gBAInB,MAAM,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,cAAmB,EACjB,KAAK,GAAE,cAAuC;IA0BjE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAMzB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IACjD,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI;CAsCtC"}

package/dist/compute.js

@@ -0,0 +1,132 @@
+import { reflectSource } from "@aigpu/wgsl/reflect-source";
+import { entryMetadata } from "./entry-metadata.js";
+import { createBindGroupCache, identityKey } from "./bind-cache.js";
+import { createSetCore, bindGroupLayoutsForReflection, pipelineLayoutFor } from "./set-core.js";
+import { visibilityForEntries } from "./set-layouts.js";
+import { normalizeConstantsOptions, selectEntryPoint } from "./pipeline-store.js";
+import { indirectInvalidError, unsupportedError, writableStorageAliasingError } from "./errors.js";
+import { assertDeviceUsable } from "./lifecycle.js";
+import { liveKernel } from "./live-kernel.js";
+import { renderService } from "./render-service.js";
+import { toWgsl } from "./shader-source.js";
+import { resolveIndirect } from "./indirect.js";
+/**
+ * Compute pipeline for this gpu, ready to `set()` bindings and `dispatch()`.
+ *
+ * Each compute owns its own pipeline (no shared pipeline store), but it resolves the gpu's single
+ * lazy bind group cache through the kernel, so a bind group built for a draw and one built here are
+ * the same object when the resources match — and the cache is torn down once, in the service phase.
+ */
+export function compute(gpu, source, opts = {}) {
+    const kernel = liveKernel(gpu, "compute");
+    return new ComputePipeline(kernel.device, toWgsl(source), opts, renderService(kernel).binds);
+}
+let nextComputeId = 1;
+/**
+ * Internal Ring-1 compute implementation behind `compute(gpu, source, opts)`.
+ *
+ * @internal
+ */
+export class ComputePipeline {
+    device;
+    source;
+    opts;
+    cache;
+    id = nextComputeId++;
+    label;
+    reflection;
+    entryPoint;
+    setCore;
+    bindGroupLayouts;
+    pipelineLayout;
+    shaderModule;
+    pipeline;
+    #storageBindings;
+    constructor(device, source, opts = {}, cache = createBindGroupCache()) {
+        this.device = device;
+        this.source = source;
+        this.opts = opts;
+        this.cache = cache;
+        assertDeviceUsable(device, "Compute.constructor");
+        this.label = opts.label ?? "compute";
+        this.reflection = reflectSource(source, `${this.label}.wgsl`);
+        // Entry selection runs before everything derived from the selected entry — binding visibility, bind group
+        // layouts, and the active-binding set for storage aliasing all reflect the chosen variant.
+        const entry = computeEntryPoint(this.reflection, this.label, opts.entry);
+        this.entryPoint = entry.name;
+        const { constants } = normalizeConstantsOptions(this.label, opts.constants, this.reflection.overrides, "compute");
+        this.bindGroupLayouts = bindGroupLayoutsForReflection(device, this.label, this.reflection, visibilityForEntries(this.reflection.bindings, [entry]));
+        this.pipelineLayout = pipelineLayoutFor(device, this.bindGroupLayouts);
+        this.shaderModule = device.gpu.createShaderModule({ label: `${this.label}.shader`, code: source });
+        // Each Compute owns its pipeline (no shared store), so constants join the descriptor directly; the record is
+        // omitted when the option is absent to keep the descriptor byte-identical to before.
+        this.pipeline = device.gpu.createComputePipeline({
+            label: `${this.label}.pipeline`,
+            layout: this.pipelineLayout,
+            compute: { module: this.shaderModule, entryPoint: this.entryPoint, ...(constants ? { constants } : {}) },
+        });
+        this.setCore = createSetCore({ device, label: this.label, drawId: this.id, reflection: this.reflection, bindGroupLayouts: this.bindGroupLayouts, cache: this.cache });
+        const active = new Set(entryMetadata(entry, "bindings", this.label).map((binding) => `${binding.group}:${binding.binding}`));
+        this.#storageBindings = this.reflection.bindings.filter((binding) => binding.kind === "buffer" && binding.addressSpace === "storage" && active.has(`${binding.group}:${binding.binding}`));
+        if (opts.set)
+            this.set(opts.set);
+    }
+    set(values) {
+        assertDeviceUsable(this.device, `${this.label}.set`);
+        this.setCore.set(values);
+        return this;
+    }
+    dispatch(x, y, z) {
+        assertDeviceUsable(this.device, `${this.label}.dispatch`);
+        const indirect = typeof x === "object" && x !== null ? this.#resolveIndirectDispatch(x, y, z) : undefined;
+        this.#preflightAliasing();
+        const encoder = this.device.gpu.createCommandEncoder({ label: `${this.label}.encoder` });
+        const pass = encoder.beginComputePass({ label: `${this.label}.pass` });
+        pass.setPipeline(this.pipeline);
+        for (const binding of this.setCore.bindGroups())
+            pass.setBindGroup(binding.group, binding.bindGroup, binding.offsets);
+        if (indirect)
+            pass.dispatchWorkgroupsIndirect(indirect.buffer, indirect.offset);
+        else
+            pass.dispatchWorkgroups(x, y ?? 1, z ?? 1);
+        pass.end();
+        this.device.gpu.queue.submit([encoder.finish()]);
+    }
+    /** The GPU reads the workgroup counts from the buffer, so explicit counts alongside indirect are dead options and throw. */
+    #resolveIndirectDispatch(opts, y, z) {
+        const where = `${this.label}.dispatch`;
+        if (y !== undefined || z !== undefined)
+            throw indirectInvalidError(this.label, `indirect cannot be combined with explicit workgroup counts in the same call; the GPU reads the counts from the buffer, so the CPU-side values would be ignored.`, where);
+        return resolveIndirect(this.label, where, opts.indirect, "dispatchWorkgroupsIndirect");
+    }
+    #preflightAliasing() {
+        if (!this.#storageBindings.length)
+            return;
+        const buckets = new Map();
+        for (const binding of this.#storageBindings) {
+            const state = this.setCore.bindingState(binding.name);
+            if (!state)
+                continue;
+            const key = identityKey(state.identity);
+            if (!buckets.has(key))
+                buckets.set(key, []);
+            buckets.get(key).push({ identity: state.identity, writable: binding.access !== "read" });
+        }
+        for (const bucket of buckets.values()) {
+            if (bucket.length < 2)
+                continue;
+            if (!bucket.some((entry) => entry.writable))
+                continue;
+            throw writableStorageAliasingError(`${this.label}.dispatch`);
+        }
+    }
+}
+function computeEntryPoint(reflection, label, name) {
+    // A named entry validates existence and stage inside selectEntryPoint (AIGPU-ENTRY-INVALID); only the
+    // no-name case can come back undefined, keeping today's error for a shader without any @compute entry.
+    const entry = selectEntryPoint(label, reflection.entryPoints, "compute", name, "compute");
+    if (!entry)
+        throw unsupportedError(`${label}.compute`, "The compute shader requires a @compute entry point.");
+    return entry;
+}
+//# sourceMappingURL=compute.js.map

package/dist/compute.js.map

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

package/dist/core/render-bundle.d.ts

@@ -0,0 +1,30 @@
+import { Buffer } from "@aigpu/core";
+export interface RenderPassDrawOptions {
+    readonly vertexCount: number;
+    readonly instanceCount?: number;
+    readonly firstVertex?: number;
+    readonly firstInstance?: number;
+}
+export type RenderPassDynamicOffsets = readonly GPUBufferDynamicOffset[] | Uint32Array;
+export interface RenderBundleOptions {
+    readonly label?: string;
+    readonly colorFormats: readonly (GPUTextureFormat | null)[];
+    readonly depthStencilFormat?: GPUTextureFormat;
+    readonly sampleCount?: number;
+    readonly depthReadOnly?: boolean;
+    readonly stencilReadOnly?: boolean;
+    readonly record: (bundle: RenderBundleRecorder) => void;
+}
+export declare class RenderBundleRecorder {
+    readonly gpu: GPURenderBundleEncoder;
+    constructor(gpu: GPURenderBundleEncoder);
+    setPipeline(pipeline: GPURenderPipeline): void;
+    setBindGroup(index: number, group: GPUBindGroup | null, dynamicOffsets?: RenderPassDynamicOffsets): void;
+    setVertexBuffer(slot: number, buffer: Buffer | GPUBuffer | null, offset?: number, size?: GPUSize64): void;
+    draw(options: RenderPassDrawOptions): void;
+    draw(vertexCount: number, instanceCount?: number, firstVertex?: number, firstInstance?: number): void;
+}
+export declare function createRenderBundle(device: {
+    readonly gpu: GPUDevice;
+}, opts: RenderBundleOptions): GPURenderBundle;
+//# sourceMappingURL=render-bundle.d.ts.map

package/dist/core/render-bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-bundle.d.ts","sourceRoot":"","sources":["../../src/core/render-bundle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,MAAM,wBAAwB,GAAG,SAAS,sBAAsB,EAAE,GAAG,WAAW,CAAC;AAEvF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC,gBAAgB,GAAG,IAAI,CAAC,EAAE,CAAC;IAC5D,QAAQ,CAAC,kBAAkB,CAAC,EAAE,gBAAgB,CAAC;IAC/C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,oBAAoB,KAAK,IAAI,CAAC;CACzD;AAED,qBAAa,oBAAoB;IACnB,QAAQ,CAAC,GAAG,EAAE,sBAAsB;gBAA3B,GAAG,EAAE,sBAAsB;IAEhD,WAAW,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI;IAI9C,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI,EAAE,cAAc,CAAC,EAAE,wBAAwB,GAAG,IAAI;IAIxG,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAAE,MAAM,SAAI,EAAE,IAAI,CAAC,EAAE,SAAS,GAAG,IAAI;IAIpG,IAAI,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI;IAC1C,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI;CAatG;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAA;CAAE,EAAE,IAAI,EAAE,mBAAmB,GAAG,eAAe,CAWlH"}

package/dist/core/render-bundle.js

@@ -0,0 +1,39 @@
+import { Buffer } from "@aigpu/core";
+export class RenderBundleRecorder {
+    gpu;
+    constructor(gpu) {
+        this.gpu = gpu;
+    }
+    setPipeline(pipeline) {
+        this.gpu.setPipeline(pipeline);
+    }
+    setBindGroup(index, group, dynamicOffsets) {
+        this.gpu.setBindGroup(index, group, dynamicOffsets);
+    }
+    setVertexBuffer(slot, buffer, offset = 0, size) {
+        this.gpu.setVertexBuffer(slot, gpuBuffer(buffer), offset, size);
+    }
+    draw(optionsOrVertexCount, instanceCount = 1, firstVertex = 0, firstInstance = 0) {
+        if (typeof optionsOrVertexCount === "number") {
+            this.gpu.draw(optionsOrVertexCount, instanceCount, firstVertex, firstInstance);
+            return;
+        }
+        this.gpu.draw(optionsOrVertexCount.vertexCount, optionsOrVertexCount.instanceCount ?? 1, optionsOrVertexCount.firstVertex ?? 0, optionsOrVertexCount.firstInstance ?? 0);
+    }
+}
+export function createRenderBundle(device, opts) {
+    const encoder = device.gpu.createRenderBundleEncoder({
+        label: opts.label,
+        colorFormats: opts.colorFormats,
+        depthStencilFormat: opts.depthStencilFormat,
+        sampleCount: opts.sampleCount,
+        depthReadOnly: opts.depthReadOnly,
+        stencilReadOnly: opts.stencilReadOnly,
+    });
+    opts.record(new RenderBundleRecorder(encoder));
+    return encoder.finish({ label: opts.label });
+}
+function gpuBuffer(buffer) {
+    return buffer instanceof Buffer ? buffer.gpu : buffer;
+}
+//# sourceMappingURL=render-bundle.js.map

package/dist/core/render-bundle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-bundle.js","sourceRoot":"","sources":["../../src/core/render-bundle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAqBrC,MAAM,OAAO,oBAAoB;IACV;IAArB,YAAqB,GAA2B;QAA3B,QAAG,GAAH,GAAG,CAAwB;IAAG,CAAC;IAEpD,WAAW,CAAC,QAA2B;QACrC,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;IACjC,CAAC;IAED,YAAY,CAAC,KAAa,EAAE,KAA0B,EAAE,cAAyC;QAC/F,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,cAAc,CAAC,CAAC;IACtD,CAAC;IAED,eAAe,CAAC,IAAY,EAAE,MAAiC,EAAE,MAAM,GAAG,CAAC,EAAE,IAAgB;QAC3F,IAAI,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;IAClE,CAAC;IAID,IAAI,CAAC,oBAAoD,EAAE,aAAa,GAAG,CAAC,EAAE,WAAW,GAAG,CAAC,EAAE,aAAa,GAAG,CAAC;QAC9G,IAAI,OAAO,oBAAoB,KAAK,QAAQ,EAAE,CAAC;YAC7C,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,oBAAoB,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,CAAC,CAAC;YAC/E,OAAO;QACT,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,IAAI,CACX,oBAAoB,CAAC,WAAW,EAChC,oBAAoB,CAAC,aAAa,IAAI,CAAC,EACvC,oBAAoB,CAAC,WAAW,IAAI,CAAC,EACrC,oBAAoB,CAAC,aAAa,IAAI,CAAC,CACxC,CAAC;IACJ,CAAC;CACF;AAED,MAAM,UAAU,kBAAkB,CAAC,MAAmC,EAAE,IAAyB;IAC/F,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,yBAAyB,CAAC;QACnD,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,kBAAkB,EAAE,IAAI,CAAC,kBAAkB;QAC3C,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,eAAe,EAAE,IAAI,CAAC,eAAe;KACtC,CAAC,CAAC;IACH,IAAI,CAAC,MAAM,CAAC,IAAI,oBAAoB,CAAC,OAAO,CAAC,CAAC,CAAC;IAC/C,OAAO,OAAO,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;AAC/C,CAAC;AAED,SAAS,SAAS,CAAC,MAAiC;IAClD,OAAO,MAAM,YAAY,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC;AACxD,CAAC"}

package/dist/core/storage-buffer.d.ts

@@ -0,0 +1,81 @@
+import { Buffer, type Device } from "@aigpu/core";
+export interface StorageBufferOptions {
+    /** Byte size of the storage buffer. Must be a positive number. Storage buffers may be far larger than uniforms (up to the adapter's `maxStorageBufferBindingSize`, typically 128 MiB). */
+    readonly size: number;
+    /** Optional debug label forwarded to the buffer, bind group layout, and bind group. */
+    readonly label?: string;
+    /**
+     * Whether the shader only reads the buffer (`"read"`, the default → `var<storage, read>`)
+     * or also writes it (`"read-write"` → `var<storage, read_write>`). This selects the
+     * bind group layout entry type (`"read-only-storage"` vs `"storage"`) and changes the
+     * default {@link StorageBufferOptions.visibility}.
+     */
+    readonly access?: "read" | "read-write";
+    /**
+     * Shader stages that access binding 0. Defaults to `FRAGMENT | COMPUTE` for both access modes —
+     * no `VERTEX`. Read-write storage is forbidden in the vertex stage; read-only storage is allowed
+     * there but `maxStorageBuffersInVertexStage` is 0 on many adapters (software/CI Vulkan, some
+     * mobile GPUs), so vertex-stage storage is opt-in: pass `visibility` explicitly and raise that
+     * limit via `requiredLimits`. Ignored when {@link StorageBufferOptions.bindGroupLayout} is provided.
+     */
+    readonly visibility?: GPUShaderStageFlags;
+    /**
+     * Reuse a pipeline-owned bind group layout instead of creating one.
+     * The layout's binding 0 must be a storage buffer compatible with `size` and `access`.
+     */
+    readonly bindGroupLayout?: GPUBindGroupLayout;
+}
+/**
+ * A single stable storage buffer for one render (or compute) pass, rewritten as needed.
+ *
+ * @remarks
+ * `StorageBuffer` is the storage-buffer counterpart to {@link Uniform}. Reach for it when
+ * the data is too large or too dynamic for a uniform: arrays, runtime-sized data, particle
+ * state, lookup tables. Storage buffers can be much bigger than uniforms (up to the adapter's
+ * `maxStorageBufferBindingSize`, typically 128 MiB, versus a uniform's 64 KiB) and can be
+ * written by the shader when `access: "read-write"`.
+ *
+ * Like `Uniform`, it owns exactly one buffer at binding 0 with a fixed (non-dynamic) offset,
+ * and the caller decides when to {@link StorageBuffer.write}. Unlike {@link UniformPool} — a
+ * dynamic-offset ring allocator for many small per-draw uniforms — there is no dynamic offset
+ * and the bind group never moves.
+ *
+ * `access` controls the layout entry type; both modes default to `FRAGMENT | COMPUTE` visibility:
+ * - `"read"` (default) → `var<storage, read>`, layout type `"read-only-storage"`.
+ * - `"read-write"` → `var<storage, read_write>`, layout type `"storage"`.
+ * Neither default includes `VERTEX`: read-write storage is forbidden in the vertex stage, and
+ * read-only storage — though legal there — needs `maxStorageBuffersInVertexStage > 0`, which is 0
+ * on many adapters (software/CI Vulkan, some mobile GPUs). For vertex-stage read-only storage, pass
+ * `visibility: VERTEX | …` explicitly and raise the limit via `requiredLimits`; do not rely on the default.
+ *
+ * @example
+ * ```ts
+ * // A read-only array the fragment shader samples (var<storage, read> values: array<f32>):
+ * const storage = new StorageBuffer(device, { size: 4 * count, label: "values" });
+ * storage.write(new Float32Array(values));
+ * pass.setBindGroup(0, storage.bindGroup);
+ *
+ * // A compute-written scratch buffer (var<storage, read_write> out: array<u32>):
+ * const scratch = new StorageBuffer(device, { size: 4 * count, access: "read-write" });
+ * ```
+ */
+export declare class StorageBuffer {
+    #private;
+    readonly device: Device;
+    readonly size: number;
+    readonly access: "read" | "read-write";
+    readonly buffer: Buffer;
+    readonly bindGroupLayout: GPUBindGroupLayout;
+    readonly bindGroup: GPUBindGroup;
+    constructor(device: Device, opts: StorageBufferOptions);
+    /** The underlying storage `GPUBuffer`. */
+    get gpu(): GPUBuffer;
+    /**
+     * Upload `data` to the buffer via `queue.writeBuffer`. No dynamic offset; the
+     * bind group is unchanged. Call only when the contents actually change.
+     */
+    write(data: BufferSource, offset?: number): void;
+    destroy(): void;
+    dispose(): void;
+}
+//# sourceMappingURL=storage-buffer.d.ts.map

package/dist/core/storage-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-buffer.d.ts","sourceRoot":"","sources":["../../src/core/storage-buffer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,MAAM,EAA0C,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AAEhG,MAAM,WAAW,oBAAoB;IACnC,0LAA0L;IAC1L,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uFAAuF;IACvF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;IACxC;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,mBAAmB,CAAC;IAC1C;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,kBAAkB,CAAC;CAC/C;AAUD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBAAa,aAAa;;IAQZ,QAAQ,CAAC,MAAM,EAAE,MAAM;IAPnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,eAAe,EAAE,kBAAkB,CAAC;IAC7C,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;gBAGZ,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB;IAmB/D,0CAA0C;IAC1C,IAAI,GAAG,IAAI,SAAS,CAEnB;IAED;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,SAAI,GAAG,IAAI;IAI3C,OAAO,IAAI,IAAI;IAMf,OAAO,IAAI,IAAI;CAGhB"}

package/dist/core/storage-buffer.js

@@ -0,0 +1,91 @@
+import { bind, createBindGroup, createBindGroupLayout } from "@aigpu/core";
+// Both access modes default to FRAGMENT | COMPUTE (no VERTEX):
+// - read-write storage is ILLEGAL in the vertex stage (WebGPU forbids it).
+// - read-only storage IS legal in vertex, but maxStorageBuffersInVertexStage is 0 on many adapters
+//   (software/CI Vulkan, some mobile GPUs), so a VERTEX-visible default would silently invalidate
+//   the layout there (the draw no-ops). Vertex-stage read-only storage is opt-in: pass `visibility`
+//   explicitly AND raise the limit via requiredLimits when requesting the device.
+const defaultVisibility = ((globalThis.GPUShaderStage?.FRAGMENT ?? 2) | (globalThis.GPUShaderStage?.COMPUTE ?? 4));
+/**
+ * A single stable storage buffer for one render (or compute) pass, rewritten as needed.
+ *
+ * @remarks
+ * `StorageBuffer` is the storage-buffer counterpart to {@link Uniform}. Reach for it when
+ * the data is too large or too dynamic for a uniform: arrays, runtime-sized data, particle
+ * state, lookup tables. Storage buffers can be much bigger than uniforms (up to the adapter's
+ * `maxStorageBufferBindingSize`, typically 128 MiB, versus a uniform's 64 KiB) and can be
+ * written by the shader when `access: "read-write"`.
+ *
+ * Like `Uniform`, it owns exactly one buffer at binding 0 with a fixed (non-dynamic) offset,
+ * and the caller decides when to {@link StorageBuffer.write}. Unlike {@link UniformPool} — a
+ * dynamic-offset ring allocator for many small per-draw uniforms — there is no dynamic offset
+ * and the bind group never moves.
+ *
+ * `access` controls the layout entry type; both modes default to `FRAGMENT | COMPUTE` visibility:
+ * - `"read"` (default) → `var<storage, read>`, layout type `"read-only-storage"`.
+ * - `"read-write"` → `var<storage, read_write>`, layout type `"storage"`.
+ * Neither default includes `VERTEX`: read-write storage is forbidden in the vertex stage, and
+ * read-only storage — though legal there — needs `maxStorageBuffersInVertexStage > 0`, which is 0
+ * on many adapters (software/CI Vulkan, some mobile GPUs). For vertex-stage read-only storage, pass
+ * `visibility: VERTEX | …` explicitly and raise the limit via `requiredLimits`; do not rely on the default.
+ *
+ * @example
+ * ```ts
+ * // A read-only array the fragment shader samples (var<storage, read> values: array<f32>):
+ * const storage = new StorageBuffer(device, { size: 4 * count, label: "values" });
+ * storage.write(new Float32Array(values));
+ * pass.setBindGroup(0, storage.bindGroup);
+ *
+ * // A compute-written scratch buffer (var<storage, read_write> out: array<u32>):
+ * const scratch = new StorageBuffer(device, { size: 4 * count, access: "read-write" });
+ * ```
+ */
+export class StorageBuffer {
+    device;
+    size;
+    access;
+    buffer;
+    bindGroupLayout;
+    bindGroup;
+    #destroyed = false;
+    constructor(device, opts) {
+        this.device = device;
+        this.size = opts.size;
+        this.access = opts.access ?? "read";
+        this.buffer = device.createBuffer({ size: opts.size, usage: ["storage", "copy_dst"], label: opts.label });
+        const visibility = opts.visibility ?? defaultVisibility;
+        const entry = this.access === "read-write"
+            ? bind.storage(0, visibility, { minBindingSize: opts.size })
+            : bind.readonlyStorage(0, visibility, { minBindingSize: opts.size });
+        this.bindGroupLayout = opts.bindGroupLayout ?? createBindGroupLayout(device, {
+            label: opts.label ? `${opts.label}.bgl` : undefined,
+            entries: [entry],
+        });
+        this.bindGroup = createBindGroup(device, {
+            label: opts.label ? `${opts.label}.bg` : undefined,
+            layout: this.bindGroupLayout,
+            entries: [bind.resource(0, this.buffer)],
+        });
+    }
+    /** The underlying storage `GPUBuffer`. */
+    get gpu() {
+        return this.buffer.gpu;
+    }
+    /**
+     * Upload `data` to the buffer via `queue.writeBuffer`. No dynamic offset; the
+     * bind group is unchanged. Call only when the contents actually change.
+     */
+    write(data, offset = 0) {
+        this.buffer.write(data, offset);
+    }
+    destroy() {
+        if (this.#destroyed)
+            return;
+        this.#destroyed = true;
+        this.buffer.destroy();
+    }
+    dispose() {
+        this.destroy();
+    }
+}
+//# sourceMappingURL=storage-buffer.js.map

package/dist/core/storage-buffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-buffer.js","sourceRoot":"","sources":["../../src/core/storage-buffer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAU,eAAe,EAAE,qBAAqB,EAAe,MAAM,aAAa,CAAC;AA6BhG,+DAA+D;AAC/D,2EAA2E;AAC3E,mGAAmG;AACnG,kGAAkG;AAClG,oGAAoG;AACpG,kFAAkF;AAClF,MAAM,iBAAiB,GAAG,CAAC,CAAC,UAAU,CAAC,cAAc,EAAE,QAAQ,IAAI,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,cAAc,EAAE,OAAO,IAAI,CAAC,CAAC,CAAwB,CAAC;AAE1I;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,OAAO,aAAa;IAQH;IAPZ,IAAI,CAAS;IACb,MAAM,CAAwB;IAC9B,MAAM,CAAS;IACf,eAAe,CAAqB;IACpC,SAAS,CAAe;IACjC,UAAU,GAAG,KAAK,CAAC;IAEnB,YAAqB,MAAc,EAAE,IAA0B;QAA1C,WAAM,GAAN,MAAM,CAAQ;QACjC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC;QACpC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,SAAS,EAAE,UAAU,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QAC1G,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,iBAAiB,CAAC;QACxD,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,KAAK,YAAY;YACxC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,EAAE,UAAU,EAAE,EAAE,cAAc,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;YAC5D,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,EAAE,UAAU,EAAE,EAAE,cAAc,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QACvE,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,eAAe,IAAI,qBAAqB,CAAC,MAAM,EAAE;YAC3E,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS;YACnD,OAAO,EAAE,CAAC,KAAK,CAAC;SACjB,CAAC,CAAC;QACH,IAAI,CAAC,SAAS,GAAG,eAAe,CAAC,MAAM,EAAE;YACvC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,SAAS;YAClD,MAAM,EAAE,IAAI,CAAC,eAAe;YAC5B,OAAO,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;SACzC,CAAC,CAAC;IACL,CAAC;IAED,0CAA0C;IAC1C,IAAI,GAAG;QACL,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC;IACzB,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,IAAkB,EAAE,MAAM,GAAG,CAAC;QAClC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAClC,CAAC;IAED,OAAO;QACL,IAAI,IAAI,CAAC,UAAU;YAAE,OAAO;QAC5B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACvB,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;IACxB,CAAC;IAED,OAAO;QACL,IAAI,CAAC,OAAO,EAAE,CAAC;IACjB,CAAC;CACF"}

package/dist/core/structured-uniform.d.ts

@@ -0,0 +1,33 @@
+import { Buffer, type BindVisibility, type Device } from "@aigpu/core";
+import { type UniformLayoutInfo, type WgslUniformType } from "./wgsl-alignment.ts";
+export type ScalarUniformType = "f32" | "u32" | "i32";
+export type VectorUniformInput = readonly number[] | Float32Array | Uint32Array | Int32Array;
+export type UniformValues<S extends Record<string, WgslUniformType>> = {
+    [K in keyof S]: S[K] extends ScalarUniformType ? number : VectorUniformInput;
+};
+export interface StructuredUniformOptions<S extends Record<string, WgslUniformType>> {
+    /** Field insertion order = WGSL member order. Offsets come from alignUniforms. */
+    readonly schema: S;
+    readonly label?: string;
+    /** Used only by the lazy bindGroupLayout getter. Default VERTEX | FRAGMENT. */
+    readonly visibility?: BindVisibility;
+}
+export declare class StructuredUniform<S extends Record<string, WgslUniformType>> {
+    #private;
+    readonly device: Device;
+    readonly schema: S;
+    readonly layout: UniformLayoutInfo;
+    readonly byteSize: number;
+    readonly offsets: Readonly<Record<keyof S, number>>;
+    readonly buffer: Buffer;
+    constructor(device: Device, opts: StructuredUniformOptions<S>);
+    get gpu(): GPUBuffer;
+    get bindGroupLayout(): GPUBindGroupLayout;
+    get bindGroup(): GPUBindGroup;
+    write(values: Partial<UniformValues<S>>): void;
+    wgsl(structName?: string): string;
+    destroy(): void;
+    dispose(): void;
+    [Symbol.dispose](): void;
+}
+//# sourceMappingURL=structured-uniform.d.ts.map

package/dist/core/structured-uniform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-uniform.d.ts","sourceRoot":"","sources":["../../src/core/structured-uniform.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,MAAM,EAA2D,KAAK,cAAc,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AACtI,OAAO,EAOL,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACrB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,MAAM,iBAAiB,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;AACtD,MAAM,MAAM,kBAAkB,GAAG,SAAS,MAAM,EAAE,GAAG,YAAY,GAAG,WAAW,GAAG,UAAU,CAAC;AAC7F,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,IAAI;KACpE,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,iBAAiB,GAAG,MAAM,GAAG,kBAAkB;CAC7E,CAAC;AAEF,MAAM,WAAW,wBAAwB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC;IACjF,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACnB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,CAAC,EAAE,cAAc,CAAC;CACtC;AAED,qBAAa,iBAAiB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC;;IAe1D,QAAQ,CAAC,MAAM,EAAE,MAAM;IAdnC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAUH,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,wBAAwB,CAAC,CAAC,CAAC;IActE,IAAI,GAAG,IAAI,SAAS,CAEnB;IAED,IAAI,eAAe,IAAI,kBAAkB,CAOxC;IAED,IAAI,SAAS,IAAI,YAAY,CAQ5B;IAED,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI;IAgB9C,IAAI,CAAC,UAAU,SAAa,GAAG,MAAM;IAKrC,OAAO,IAAI,IAAI;IAMf,OAAO,IAAI,IAAI;IAIf,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;CAQzB"}