@nodetool-ai/gpu 0.8.1

package/dist/context.js

@@ -0,0 +1,205 @@
+/**
+ * `GPUContext` — the host-portability adapter.
+ *
+ * Holds a TypeGPU `root` (from `tgpu.initFromDevice({ device })`) plus the
+ * per-host services the Executor leans on: a pipeline cache, a scratch
+ * texture pool, and a capability record. The same `ShaderModule` code runs
+ * against a browser `navigator.gpu` device, an Electron device, or a
+ * Node.js Dawn device — only the adapter that builds this object differs.
+ */
+import tgpu from "typegpu";
+import { createLabeledTexture } from "./texture.js";
+/** Round a dimension up to the allocation bucket (multiple of 64, pow2 ≥ 256). */
+export function ceilToBucket(value) {
+    const v = Math.max(1, Math.floor(value));
+    if (v <= 256) {
+        return Math.ceil(v / 64) * 64;
+    }
+    let pow = 256;
+    while (pow < v) {
+        pow *= 2;
+    }
+    return pow;
+}
+function makePipelineCache() {
+    const cache = new Map();
+    return {
+        get: (key) => cache.get(key),
+        set: (key, pipeline) => {
+            cache.set(key, pipeline);
+        }
+    };
+}
+/** Bucket key per scratch texture, for routing `release` back to its pool. */
+const poolKeys = new WeakMap();
+/**
+ * Bucketed, refcounted scratch pool. Buckets on
+ * `(format, usage, bucketW, bucketH)`; the caller sees only the requested
+ * viewport, the underlying texture may be larger.
+ */
+export function makeScratchPool(device) {
+    const free = new Map();
+    const live = new Set();
+    const dimsFor = (spec) => spec.exact
+        ? {
+            width: Math.max(1, Math.floor(spec.width)),
+            height: Math.max(1, Math.floor(spec.height))
+        }
+        : { width: ceilToBucket(spec.width), height: ceilToBucket(spec.height) };
+    // Reuse keys on the *resolved* dimensions, so an exact 64×64 and a
+    // bucketed-to-64 request share a pool entry — a 64×64 texture is a 64×64
+    // texture regardless of how it was requested.
+    const bucketKey = (spec) => {
+        const { width, height } = dimsFor(spec);
+        return `${spec.format}:${spec.usage}:${width}x${height}`;
+    };
+    return {
+        acquire(spec) {
+            const key = bucketKey(spec);
+            const pooled = free.get(key);
+            const reused = pooled?.pop();
+            if (reused) {
+                live.add(reused);
+                return reused;
+            }
+            const dims = dimsFor(spec);
+            const texture = createLabeledTexture(device, {
+                width: dims.width,
+                height: dims.height,
+                format: spec.format,
+                usage: spec.usage,
+                label: spec.label ?? `scratch-${key}`,
+                meta: spec.meta
+            });
+            poolKeys.set(texture, key);
+            live.add(texture);
+            return texture;
+        },
+        release(texture) {
+            if (!live.delete(texture)) {
+                return;
+            }
+            const key = poolKeys.get(texture);
+            if (!key) {
+                texture.destroy();
+                return;
+            }
+            const pooled = free.get(key);
+            if (pooled) {
+                pooled.push(texture);
+            }
+            else {
+                free.set(key, [texture]);
+            }
+        },
+        dispose() {
+            for (const texture of live) {
+                texture.destroy();
+            }
+            live.clear();
+            for (const pooled of free.values()) {
+                for (const texture of pooled) {
+                    texture.destroy();
+                }
+            }
+            free.clear();
+        }
+    };
+}
+/** Pool of uniform buffers, sized to the largest submission seen. */
+export function makeUniformRing(device) {
+    const buffers = [];
+    let index = 0;
+    return {
+        beginSubmission() {
+            index = 0;
+        },
+        acquire(size) {
+            const slot = index++;
+            const wanted = Math.max(16, size);
+            let buffer = buffers[slot];
+            if (!buffer || buffer.size < wanted) {
+                buffer?.destroy();
+                buffer = device.createBuffer({
+                    label: `uniform-ring-${slot}`,
+                    size: wanted,
+                    usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+                });
+                buffers[slot] = buffer;
+            }
+            return buffer;
+        },
+        dispose() {
+            for (const buffer of buffers) {
+                buffer?.destroy();
+            }
+            buffers.fill(undefined);
+        }
+    };
+}
+function detectCapabilities(device) {
+    const features = device.features;
+    return {
+        textureExternal: true,
+        f16Storage: features.has("shader-f16")
+    };
+}
+/**
+ * Build a {@link GPUContext} from the browser `navigator.gpu`. Browser/WebGPU
+ * only — kept out of the package's pure root so Node consumers can import the
+ * catalog without touching `navigator`.
+ */
+export async function createBrowserGPUContext(options = {}) {
+    // SAFETY: this package compiles without the DOM lib, so `navigator` is not a
+    // declared global here. The asserted shape only claims the two optional
+    // members read below, and both are guarded before use — a host without
+    // `navigator` or without `navigator.gpu` takes the throw.
+    const nav = globalThis.navigator;
+    const gpu = nav?.gpu;
+    if (!gpu) {
+        throw new Error("WebGPU is not available (navigator.gpu is undefined)");
+    }
+    const adapter = await gpu.requestAdapter(options.adapterOptions);
+    if (!adapter) {
+        throw new Error("No WebGPU adapter available");
+    }
+    const device = await adapter.requestDevice();
+    return createGPUContextFromDevice(device);
+}
+/** Lazy-allocated 1×1 white texture (default for unbound optional inputs). */
+function makeWhiteTextureProvider(device) {
+    let cached = null;
+    return () => {
+        if (cached) {
+            return cached;
+        }
+        const tex = createLabeledTexture(device, {
+            label: "default-white-1x1",
+            width: 1,
+            height: 1,
+            format: "rgba8unorm",
+            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+            meta: { colorSpace: "linear", alpha: "premultiplied" }
+        });
+        device.queue.writeTexture({ texture: tex.texture }, new Uint8Array([255, 255, 255, 255]), { bytesPerRow: 4, rowsPerImage: 1 }, { width: 1, height: 1 });
+        cached = tex;
+        return cached;
+    };
+}
+/**
+ * Build a {@link GPUContext} from an already-acquired `GPUDevice` (browser,
+ * Electron, or Node.js Dawn). The shared path every adapter funnels into.
+ */
+export function createGPUContextFromDevice(device) {
+    const root = tgpu.initFromDevice({ device });
+    return {
+        root,
+        device,
+        capabilities: detectCapabilities(device),
+        pipelineCache: makePipelineCache(),
+        scratch: makeScratchPool(device),
+        uniformRing: makeUniformRing(device),
+        getDefaultWhiteTexture: makeWhiteTextureProvider(device)
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

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

package/dist/debug/premulValidator.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Premultiplied-alpha invariant validator (Item 5 of the shader-pool
+ * invariant enforcement plan).
+ *
+ * When enabled (env flag `NODETOOL_GPU_DEBUG` contains `"premul"`), the
+ * Executor calls {@link encodePremulValidationPass} after every dispatch that
+ * writes a premultiplied output. The pass runs a small compute shader that
+ * scans the output texture and atomically increments counters in a tiny
+ * storage buffer whenever a texel violates the premul invariant
+ * (`rgb ≤ a`, `rgb ≥ 0`, no NaN).
+ *
+ * The buffer is then copied into a readback buffer registered on the
+ * context's debug sink; the host calls {@link consumePremulDebugWarnings}
+ * after submit to map, read, and log violations.
+ *
+ * Zero overhead when the flag is off: the gate function short-circuits before
+ * any allocation. The validator only reads the output texture — it never
+ * mutates it — so it cannot perturb pipeline behaviour even when enabled.
+ */
+import type { GPUContext } from "../context.js";
+import { type ShaderModule } from "../module.js";
+import type { LabeledTexture } from "../texture.js";
+/** One violation report, materialized after readback. */
+export interface DebugViolation {
+    /** `id@version` of the module whose output was scanned. */
+    readonly moduleKey: string;
+    /** Total texels scanned. */
+    readonly totalChecked: number;
+    /** Texels where any RGB channel exceeds alpha by more than epsilon. */
+    readonly rgbExceedsA: number;
+    /** Texels with any channel < -epsilon. */
+    readonly negative: number;
+    /** Texels with NaN in any channel. */
+    readonly nan: number;
+}
+/** A queued readback; the executor pushes these onto {@link DebugSink}. */
+export interface DebugReadback {
+    readonly moduleKey: string;
+    readonly buffer: GPUBuffer;
+    /**
+     * The counters buffer the validation pass wrote, copied into `buffer`. Only
+     * needed while the encoder runs; the consumer destroys it once the readback
+     * completes.
+     */
+    readonly countersBuffer?: GPUBuffer;
+}
+/** Mutable list of pending readbacks; one per {@link GPUContext}. */
+export type DebugSink = DebugReadback[];
+/**
+ * Whether the premul debug pass should run. Cached on first read for zero
+ * overhead in the hot path; {@link setPremulDebugEnabled} exists for tests
+ * that need to flip it without re-importing the module.
+ */
+export declare function isPremulDebugEnabled(): boolean;
+/** Test hook: forcibly toggle the cached gate (bypassing env). */
+export declare function setPremulDebugEnabled(enabled: boolean): void;
+/** Test hook: clear the cache so the next call re-reads the env. */
+export declare function resetPremulDebugCache(): void;
+export interface EncodeValidationArgs {
+    ctx: GPUContext;
+    module: ShaderModule;
+    encoder: GPUCommandEncoder;
+    output: LabeledTexture;
+}
+/**
+ * Encode a debug validation pass into the given encoder, then schedule a
+ * buffer-to-buffer copy into a fresh readback buffer queued for this context.
+ * Caller is responsible for `consumePremulDebugWarnings` after submit to
+ * actually map the readback.
+ *
+ * Silently skips if the output texture lacks `TEXTURE_BINDING` usage: the
+ * pass needs to sample the output and we will not silently re-allocate
+ * with extra usage flags. The host should add `TEXTURE_BINDING` to outputs
+ * it wants validated.
+ */
+export declare function encodePremulValidationPass(args: EncodeValidationArgs): void;
+/**
+ * Map every queued debug readback, decode the four-counter struct, log a
+ * warning per non-zero entry, and return the violations. Buffers are
+ * destroyed after read so a long-running host doesn't leak.
+ *
+ * Safe to call when no validation passes were encoded — returns `[]`.
+ */
+export declare function consumePremulDebugWarnings(ctx: GPUContext): Promise<DebugViolation[]>;
+//# sourceMappingURL=premulValidator.d.ts.map

package/dist/debug/premulValidator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"premulValidator.d.ts","sourceRoot":"","sources":["../../src/debug/premulValidator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAa,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,yDAAyD;AACzD,MAAM,WAAW,cAAc;IAC7B,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4BAA4B;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,uEAAuE;IACvE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,sCAAsC;IACtC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,2EAA2E;AAC3E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,CAAC;CACrC;AAED,qEAAqE;AACrE,MAAM,MAAM,SAAS,GAAG,aAAa,EAAE,CAAC;AA6DxC;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAK9C;AAED,kEAAkE;AAClE,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAE5D;AAED,oEAAoE;AACpE,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AA0CD,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,UAAU,CAAC;IAChB,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,EAAE,iBAAiB,CAAC;IAC3B,MAAM,EAAE,cAAc,CAAC;CACxB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,oBAAoB,GAAG,IAAI,CAsD3E;AAID;;;;;;GAMG;AACH,wBAAsB,0BAA0B,CAC9C,GAAG,EAAE,UAAU,GACd,OAAO,CAAC,cAAc,EAAE,CAAC,CA6C3B"}

package/dist/debug/premulValidator.js

@@ -0,0 +1,239 @@
+/**
+ * Premultiplied-alpha invariant validator (Item 5 of the shader-pool
+ * invariant enforcement plan).
+ *
+ * When enabled (env flag `NODETOOL_GPU_DEBUG` contains `"premul"`), the
+ * Executor calls {@link encodePremulValidationPass} after every dispatch that
+ * writes a premultiplied output. The pass runs a small compute shader that
+ * scans the output texture and atomically increments counters in a tiny
+ * storage buffer whenever a texel violates the premul invariant
+ * (`rgb ≤ a`, `rgb ≥ 0`, no NaN).
+ *
+ * The buffer is then copied into a readback buffer registered on the
+ * context's debug sink; the host calls {@link consumePremulDebugWarnings}
+ * after submit to map, read, and log violations.
+ *
+ * Zero overhead when the flag is off: the gate function short-circuits before
+ * any allocation. The validator only reads the output texture — it never
+ * mutates it — so it cannot perturb pipeline behaviour even when enabled.
+ */
+import { moduleKey } from "../module.js";
+/**
+ * Pending readbacks per context. Kept beside the context rather than on it:
+ * the sink is this module's own bookkeeping, not part of the {@link GPUContext}
+ * contract, and a weak key lets a discarded context take its queue with it.
+ */
+const debugSinks = new WeakMap();
+const COUNTERS_SIZE_BYTES = 16; // 4 × u32: rgbExceedsA, negative, nan, totalChecked
+const VALIDATOR_WGSL = /* wgsl */ `
+struct Counters {
+  rgbExceedsA: atomic<u32>,
+  negative: atomic<u32>,
+  nan: atomic<u32>,
+  totalChecked: atomic<u32>,
+};
+@group(0) @binding(0) var src: texture_2d<f32>;
+@group(0) @binding(1) var<storage, read_write> counters: Counters;
+
+@compute @workgroup_size(8, 8, 1)
+fn main(@builtin(global_invocation_id) gid: vec3u) {
+  let dims = textureDimensions(src);
+  if (gid.x >= dims.x || gid.y >= dims.y) { return; }
+  let c = textureLoad(src, vec2i(i32(gid.x), i32(gid.y)), 0);
+  atomicAdd(&counters.totalChecked, 1u);
+  let eps = 1.0 / 255.0;
+  if (c.r != c.r || c.g != c.g || c.b != c.b || c.a != c.a) {
+    atomicAdd(&counters.nan, 1u);
+    return;
+  }
+  if (c.r < -eps || c.g < -eps || c.b < -eps || c.a < -eps) {
+    atomicAdd(&counters.negative, 1u);
+  }
+  if (c.r > c.a + eps || c.g > c.a + eps || c.b > c.a + eps) {
+    atomicAdd(&counters.rgbExceedsA, 1u);
+  }
+}
+`;
+// --- Gating ------------------------------------------------------------------
+let cachedFlag = null;
+function readEnvFlag() {
+    // SAFETY: this package compiles without @types/node, so `process` is not a
+    // declared global here. The asserted shape only claims optional members, and
+    // the optional chain reads the flag as unset in a host that has no
+    // `process` (browser, worker) — which leaves the validator off.
+    const raw = globalThis
+        .process?.env?.NODETOOL_GPU_DEBUG;
+    if (!raw) {
+        return false;
+    }
+    return raw
+        .split(",")
+        .map((tag) => tag.trim().toLowerCase())
+        .includes("premul");
+}
+/**
+ * Whether the premul debug pass should run. Cached on first read for zero
+ * overhead in the hot path; {@link setPremulDebugEnabled} exists for tests
+ * that need to flip it without re-importing the module.
+ */
+export function isPremulDebugEnabled() {
+    if (cachedFlag === null) {
+        cachedFlag = readEnvFlag();
+    }
+    return cachedFlag;
+}
+/** Test hook: forcibly toggle the cached gate (bypassing env). */
+export function setPremulDebugEnabled(enabled) {
+    cachedFlag = enabled;
+}
+/** Test hook: clear the cache so the next call re-reads the env. */
+export function resetPremulDebugCache() {
+    cachedFlag = null;
+}
+// --- Pipeline + encoding -----------------------------------------------------
+const pipelineByDevice = new WeakMap();
+const bindGroupLayoutByDevice = new WeakMap();
+function getValidatorPipeline(device) {
+    let pipeline = pipelineByDevice.get(device);
+    let bindGroupLayout = bindGroupLayoutByDevice.get(device);
+    if (pipeline && bindGroupLayout) {
+        return { pipeline, bindGroupLayout };
+    }
+    bindGroupLayout = device.createBindGroupLayout({
+        label: "premul-validator-bgl",
+        entries: [
+            {
+                binding: 0,
+                visibility: GPUShaderStage.COMPUTE,
+                texture: { sampleType: "float", viewDimension: "2d" }
+            },
+            {
+                binding: 1,
+                visibility: GPUShaderStage.COMPUTE,
+                buffer: { type: "storage" }
+            }
+        ]
+    });
+    const shaderModule = device.createShaderModule({
+        label: "premul-validator-shader",
+        code: VALIDATOR_WGSL
+    });
+    pipeline = device.createComputePipeline({
+        label: "premul-validator-pipeline",
+        layout: device.createPipelineLayout({ bindGroupLayouts: [bindGroupLayout] }),
+        compute: { module: shaderModule, entryPoint: "main" }
+    });
+    pipelineByDevice.set(device, pipeline);
+    bindGroupLayoutByDevice.set(device, bindGroupLayout);
+    return { pipeline, bindGroupLayout };
+}
+/**
+ * Encode a debug validation pass into the given encoder, then schedule a
+ * buffer-to-buffer copy into a fresh readback buffer queued for this context.
+ * Caller is responsible for `consumePremulDebugWarnings` after submit to
+ * actually map the readback.
+ *
+ * Silently skips if the output texture lacks `TEXTURE_BINDING` usage: the
+ * pass needs to sample the output and we will not silently re-allocate
+ * with extra usage flags. The host should add `TEXTURE_BINDING` to outputs
+ * it wants validated.
+ */
+export function encodePremulValidationPass(args) {
+    const { ctx, module, encoder, output } = args;
+    if ((output.texture.usage & GPUTextureUsage.TEXTURE_BINDING) === 0) {
+        return;
+    }
+    const { device } = ctx;
+    const { pipeline, bindGroupLayout } = getValidatorPipeline(device);
+    const counters = device.createBuffer({
+        label: "premul-validator-counters",
+        size: COUNTERS_SIZE_BYTES,
+        usage: GPUBufferUsage.STORAGE |
+            GPUBufferUsage.COPY_SRC |
+            GPUBufferUsage.COPY_DST
+    });
+    // Zero the counters before the pass.
+    device.queue.writeBuffer(counters, 0, new Uint32Array([0, 0, 0, 0]));
+    const readback = device.createBuffer({
+        label: "premul-validator-readback",
+        size: COUNTERS_SIZE_BYTES,
+        usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ
+    });
+    const bindGroup = device.createBindGroup({
+        label: "premul-validator-bindgroup",
+        layout: bindGroupLayout,
+        entries: [
+            { binding: 0, resource: output.createView() },
+            { binding: 1, resource: { buffer: counters } }
+        ]
+    });
+    const pass = encoder.beginComputePass({ label: "premul-validator-pass" });
+    pass.setPipeline(pipeline);
+    pass.setBindGroup(0, bindGroup);
+    const wgX = Math.ceil(output.width / 8);
+    const wgY = Math.ceil(output.height / 8);
+    pass.dispatchWorkgroups(Math.max(1, wgX), Math.max(1, wgY), 1);
+    pass.end();
+    encoder.copyBufferToBuffer(counters, 0, readback, 0, COUNTERS_SIZE_BYTES);
+    let sink = debugSinks.get(ctx);
+    if (!sink) {
+        sink = [];
+        debugSinks.set(ctx, sink);
+    }
+    sink.push({
+        moduleKey: moduleKey(module.id, module.version),
+        buffer: readback,
+        countersBuffer: counters
+    });
+}
+// --- Readback / reporting ----------------------------------------------------
+/**
+ * Map every queued debug readback, decode the four-counter struct, log a
+ * warning per non-zero entry, and return the violations. Buffers are
+ * destroyed after read so a long-running host doesn't leak.
+ *
+ * Safe to call when no validation passes were encoded — returns `[]`.
+ */
+export async function consumePremulDebugWarnings(ctx) {
+    const sink = debugSinks.get(ctx);
+    if (!sink || sink.length === 0) {
+        return [];
+    }
+    // Detach so concurrent encoders can begin a fresh batch.
+    debugSinks.delete(ctx);
+    const violations = [];
+    for (const entry of sink) {
+        await entry.buffer.mapAsync(GPUMapMode.READ);
+        const view = new Uint32Array(entry.buffer.getMappedRange().slice(0));
+        entry.buffer.unmap();
+        entry.buffer.destroy();
+        entry.countersBuffer?.destroy();
+        const violation = {
+            moduleKey: entry.moduleKey,
+            rgbExceedsA: view[0] ?? 0,
+            negative: view[1] ?? 0,
+            nan: view[2] ?? 0,
+            totalChecked: view[3] ?? 0
+        };
+        if (violation.rgbExceedsA > 0 ||
+            violation.negative > 0 ||
+            violation.nan > 0) {
+            // `console` is not in this package's tsconfig `lib`, but every host
+            // (browser, Electron, Node) has it on globalThis. Routed through a
+            // typed alias so DOM lib isn't required.
+            // SAFETY: the asserted shape claims one optional member, read through
+            // `?.` below, so a host without `console` logs nothing instead of
+            // throwing.
+            const con = globalThis
+                .console;
+            con?.warn(`[gpu/premul-debug] ${violation.moduleKey}: ` +
+                `rgbExceedsA=${violation.rgbExceedsA} ` +
+                `negative=${violation.negative} ` +
+                `nan=${violation.nan} ` +
+                `(of ${violation.totalChecked} texels)`);
+        }
+        violations.push(violation);
+    }
+    return violations;
+}
+//# sourceMappingURL=premulValidator.js.map

package/dist/debug/premulValidator.js.map

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

package/dist/executor.d.ts

@@ -0,0 +1,74 @@
+/**
+ * `Executor` — the tiny shared runtime that turns a {@link ShaderModule} plus
+ * bound textures and params into encoded GPU work.
+ *
+ * Steps per call: validate input labels against the module's I/O contract,
+ * get-or-compile the pipeline via `ctx.pipelineCache`, pack `params` through
+ * the module's TypeGPU schema, build the bind group from the module's typed
+ * layout (`root.unwrap(layout)`), and encode the pass. The host owns *when*
+ * to submit and *where* the output texture lives.
+ *
+ * **No executor-inserted readback.** `encode` records GPU commands only — it
+ * never calls `copyTextureToBuffer`, `mapAsync`, or any path that pulls
+ * pixels to the CPU. Materialization is a deliberate host-side step at
+ * boundaries (Phase 4).
+ *
+ * The `fragment` arm (full-screen pass) drives image-in/image-out modules;
+ * the `compute` arm (a workgroup dispatch writing a storage-texture output)
+ * drives the migrated timeline effects. Both share input validation, the
+ * params packer, and bind-group construction — only the pipeline kind and the
+ * encoded pass differ.
+ */
+import type { TgpuBindGroupLayout } from "typegpu";
+import type { AnyWgslStruct, Infer } from "typegpu/data";
+import type { GPUCapabilities, GPUContext } from "./context.js";
+import { type ShaderModule } from "./module.js";
+import type { LabeledTexture } from "./texture.js";
+export type ExecutorDispatch = {
+    kind: "fragment";
+} | {
+    kind: "compute";
+    x: number;
+    y: number;
+    z?: number;
+};
+/**
+ * The slice of a module the Executor actually binds against. Either the
+ * module's primary (`layout`, `wgsl`, `entryPoint`, `samplers`,
+ * `workgroupSize`) or one of its `variants` selected by
+ * {@link resolveVariant}.
+ */
+export interface ResolvedShader {
+    layout: TgpuBindGroupLayout;
+    wgsl: string;
+    entryPoint: string;
+    samplers: Readonly<Record<string, GPUSamplerDescriptor>>;
+    workgroupSize: readonly [number, number, number];
+    /** `undefined` ⇒ module's primary; otherwise the chosen variant's name. */
+    variant: string | undefined;
+}
+/**
+ * Resolve which `(layout, wgsl, ...)` to use for this dispatch.
+ *
+ * Phase 3 policy: try variants in declaration order; the first one whose
+ * `bindingKinds` match the bound inputs AND whose `requires` are satisfied by
+ * `ctx.capabilities` wins. If no variant matches, the module's primary is
+ * used; if it can't match either (e.g. a `texture_external` input on a host
+ * without that capability), the Executor lets the original validation /
+ * pipeline-creation fail loud rather than substituting silently.
+ */
+export declare function resolveVariant(module: ShaderModule, inputs: Record<string, LabeledTexture>, capabilities: GPUCapabilities): ResolvedShader;
+export interface EncodeArgs<Schema extends AnyWgslStruct> {
+    ctx: GPUContext;
+    module: ShaderModule<Schema>;
+    encoder: GPUCommandEncoder;
+    inputs: Record<string, LabeledTexture>;
+    output: LabeledTexture;
+    params: Infer<Schema>;
+    dispatch: ExecutorDispatch;
+}
+export interface Executor {
+    encode<Schema extends AnyWgslStruct>(args: EncodeArgs<Schema>): void;
+}
+export declare function createExecutor(): Executor;
+//# sourceMappingURL=executor.d.ts.map

package/dist/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../src/executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAShE,OAAO,EAAa,KAAK,YAAY,EAAsB,MAAM,aAAa,CAAC;AAG/E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAGnD,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GACpB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,mBAAmB,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC;IACzD,aAAa,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACjD,2EAA2E;IAC3E,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAuCD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,EACtC,YAAY,EAAE,eAAe,GAC5B,cAAc,CA4BhB;AAED,MAAM,WAAW,UAAU,CAAC,MAAM,SAAS,aAAa;IACtD,GAAG,EAAE,UAAU,CAAC;IAChB,MAAM,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IAC7B,OAAO,EAAE,iBAAiB,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACvC,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACtB,QAAQ,EAAE,gBAAgB,CAAC;CAC5B;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,CAAC,MAAM,SAAS,aAAa,EAAE,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;CACtE;AAED,wBAAgB,cAAc,IAAI,QAAQ,CAwZzC"}