@nodetool-ai/gpu 0.8.1

package/README.md

@@ -0,0 +1,52 @@
+# @nodetool-ai/gpu
+
+Canonical blend-mode catalog and shared WGSL blend functions for NodeTool compositors (sketch, timeline, Compositor node) for [NodeTool](https://nodetool.ai).
+
+The single source of truth for the `BlendMode` union, its stable numeric GPU ids, the Canvas2D and Sharp/libvips mappings, and the shared WGSL `applyBlendMode` shader math. The package root is pure — no WebGPU runtime — so Node consumers can pull in the catalog without the GPU stack. The TypeGPU shader pool lives behind `./pool` and the browser layer-compositing engine behind `./webgpu`.
+
+## Install
+
+```bash
+npm install @nodetool-ai/gpu
+```
+
+## Exported symbols
+
+| Symbol | Kind | Description |
+| --- | --- | --- |
+| `BlendMode` | type | Union of the 13 canonical blend modes (`normal`, `multiply`, `add`, …) |
+| `BLEND_MODE_TUPLE` | const | Ordered `const` tuple of mode names — drives the union and Zod enums |
+| `BLEND_MODE_INFOS` | const | Full table: value, label, `gpuId`, Canvas2D op, Sharp blend |
+| `BLEND_MODES` | const | `{ value, label }[]` for UI dropdowns |
+| `BLEND_MODE_VALUES` | const | Alias of `BLEND_MODE_TUPLE` |
+| `BlendModeInfo` | interface | One catalog row |
+| `CanvasCompositeOp` | type | Literal union of the Canvas2D `globalCompositeOperation` values used |
+| `coerceBlendMode` | function | Coerce unknown input to a valid `BlendMode` (falls back to `normal`) |
+| `blendModeGpuId` | function | Map a mode to its stable numeric shader id |
+| `blendModeToCanvasOp` | function | Map a mode to its Canvas2D composite op |
+| `blendModeToSharpBlend` | function | Map a mode to its Sharp/libvips `blend` string |
+| `WGSL_BLEND_FUNCTIONS` | const | WGSL source for `applyBlendMode(src, dst, mode)`, injected into fragment shaders |
+
+## Usage
+
+```ts
+import {
+  BLEND_MODES,
+  blendModeToCanvasOp,
+  WGSL_BLEND_FUNCTIONS
+} from "@nodetool-ai/gpu";
+
+// Populate a UI dropdown
+BLEND_MODES.forEach(({ value, label }) => addOption(value, label));
+
+// Canvas2D compositing
+ctx.globalCompositeOperation = blendModeToCanvasOp("multiply") as GlobalCompositeOperation;
+
+// Inject the shared blend math into a WGSL fragment shader
+const fragment = `${WGSL_BLEND_FUNCTIONS}\n@fragment fn fs(...) { ... }`;
+```
+
+## Links
+
+- [NodeTool](https://nodetool.ai)
+- [GitHub](https://github.com/nodetool-ai/nodetool)

package/dist/.nodetool-build-stamp

@@ -0,0 +1 @@
+2026-09-28T09:19:03.821Z

package/dist/blend/blendModes.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Canonical blend-mode catalog shared by every NodeTool compositor:
+ *
+ *   - the sketch editor (WebGPU + Canvas2D layer compositing)
+ *   - the timeline preview compositor (WebGPU clip compositing)
+ *   - the Compositor image node (server-side Sharp/libvips compositing)
+ *
+ * The mode names come from `@nodetool-ai/protocol/blend-modes`, where the
+ * document schemas validate against them, and are re-exported here so callers
+ * see one catalog. This module owns what a compositor needs on top of a name:
+ * the stable numeric ids baked into WGSL shader uniforms, the Canvas2D
+ * `globalCompositeOperation` mapping, the Sharp/libvips `blend` mapping, and
+ * the ordered list that populates UI dropdowns. Keeping those in one table
+ * guarantees the implementations agree on ordering and on the numeric ids the
+ * shaders switch on.
+ */
+import { BLEND_MODE_TUPLE, type BlendMode } from "@nodetool-ai/protocol/blend-modes";
+export { BLEND_MODE_TUPLE, type BlendMode };
+/**
+ * Canvas2D `globalCompositeOperation` values we map onto. Declared as a
+ * literal union (not the DOM `GlobalCompositeOperation`) so this package
+ * builds without the DOM lib; every member is a valid DOM value, so callers
+ * can cast the result to `GlobalCompositeOperation` safely.
+ */
+export type CanvasCompositeOp = "source-over" | "multiply" | "screen" | "overlay" | "darken" | "lighten" | "color-dodge" | "color-burn" | "hard-light" | "soft-light" | "difference" | "exclusion" | "lighter";
+export interface BlendModeInfo {
+    value: BlendMode;
+    /** Human-readable label for UI dropdowns. */
+    label: string;
+    /**
+     * Stable numeric id consumed by the WGSL `applyBlendMode` switch (see
+     * {@link WGSL_BLEND_FUNCTIONS}). Never renumber — shaders depend on it.
+     */
+    gpuId: number;
+    /** Canvas2D `globalCompositeOperation` equivalent. */
+    canvasOp: CanvasCompositeOp;
+    /** Sharp/libvips `blend` string for server-side compositing. */
+    sharpBlend: string;
+}
+/**
+ * The canonical table. Order is the UI display order. `gpuId` values 0–11
+ * match the historical sketch-editor shader switch; `add` is 12.
+ */
+export declare const BLEND_MODE_INFOS: readonly BlendModeInfo[];
+/** Ordered list of `{ value, label }` for populating UI dropdowns. */
+export declare const BLEND_MODES: readonly {
+    value: BlendMode;
+    label: string;
+}[];
+/** All canonical blend-mode values in display order (literal tuple). */
+export declare const BLEND_MODE_VALUES: readonly ["normal", "multiply", "screen", "overlay", "darken", "lighten", "color-dodge", "color-burn", "hard-light", "soft-light", "difference", "exclusion", "add"];
+/**
+ * Coerce an arbitrary input to a canonical {@link BlendMode}. Unknown values
+ * (including stray data URLs that can leak into persisted UI state) fall back
+ * to `"normal"`. Accepts the legacy `"over"` alias.
+ */
+export declare function coerceBlendMode(value: unknown): BlendMode;
+/**
+ * Numeric id for the WGSL `applyBlendMode` switch. Takes a persisted value
+ * (canonical, legacy alias, or junk); anything unrecognized blends as normal.
+ */
+export declare function blendModeGpuId(value: unknown): number;
+/** Canvas2D `globalCompositeOperation` for a persisted blend mode. */
+export declare function blendModeToCanvasOp(value: unknown): CanvasCompositeOp;
+/** Sharp/libvips `blend` string for a persisted blend mode. */
+export declare function blendModeToSharpBlend(value: unknown): string;
+//# sourceMappingURL=blendModes.d.ts.map

package/dist/blend/blendModes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blendModes.d.ts","sourceRoot":"","sources":["../../src/blend/blendModes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EACL,gBAAgB,EAChB,KAAK,SAAS,EACf,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EAAE,gBAAgB,EAAE,KAAK,SAAS,EAAE,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GACzB,aAAa,GACb,UAAU,GACV,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,SAAS,GACT,aAAa,GACb,YAAY,GACZ,YAAY,GACZ,YAAY,GACZ,YAAY,GACZ,WAAW,GACX,SAAS,CAAC;AAEd,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,SAAS,CAAC;IACjB,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,aAAa,EAc3C,CAAC;AAEX,sEAAsE;AACtE,eAAO,MAAM,WAAW,EAAE,SAAS;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EACN,CAAC;AAEjE,wEAAwE;AACxE,eAAO,MAAM,iBAAiB,sKAAmB,CAAC;AAqBlD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CAEzD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAErD;AAED,sEAAsE;AACtE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,CAErE;AAED,+DAA+D;AAC/D,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE5D"}

package/dist/blend/blendModes.js

@@ -0,0 +1,80 @@
+/**
+ * Canonical blend-mode catalog shared by every NodeTool compositor:
+ *
+ *   - the sketch editor (WebGPU + Canvas2D layer compositing)
+ *   - the timeline preview compositor (WebGPU clip compositing)
+ *   - the Compositor image node (server-side Sharp/libvips compositing)
+ *
+ * The mode names come from `@nodetool-ai/protocol/blend-modes`, where the
+ * document schemas validate against them, and are re-exported here so callers
+ * see one catalog. This module owns what a compositor needs on top of a name:
+ * the stable numeric ids baked into WGSL shader uniforms, the Canvas2D
+ * `globalCompositeOperation` mapping, the Sharp/libvips `blend` mapping, and
+ * the ordered list that populates UI dropdowns. Keeping those in one table
+ * guarantees the implementations agree on ordering and on the numeric ids the
+ * shaders switch on.
+ */
+import { BLEND_MODE_TUPLE } from "@nodetool-ai/protocol/blend-modes";
+export { BLEND_MODE_TUPLE };
+/**
+ * The canonical table. Order is the UI display order. `gpuId` values 0–11
+ * match the historical sketch-editor shader switch; `add` is 12.
+ */
+export const BLEND_MODE_INFOS = [
+    { value: "normal", label: "Normal", gpuId: 0, canvasOp: "source-over", sharpBlend: "over" },
+    { value: "multiply", label: "Multiply", gpuId: 1, canvasOp: "multiply", sharpBlend: "multiply" },
+    { value: "screen", label: "Screen", gpuId: 2, canvasOp: "screen", sharpBlend: "screen" },
+    { value: "overlay", label: "Overlay", gpuId: 3, canvasOp: "overlay", sharpBlend: "overlay" },
+    { value: "darken", label: "Darken", gpuId: 4, canvasOp: "darken", sharpBlend: "darken" },
+    { value: "lighten", label: "Lighten", gpuId: 5, canvasOp: "lighten", sharpBlend: "lighten" },
+    { value: "color-dodge", label: "Color Dodge", gpuId: 6, canvasOp: "color-dodge", sharpBlend: "color-dodge" },
+    { value: "color-burn", label: "Color Burn", gpuId: 7, canvasOp: "color-burn", sharpBlend: "color-burn" },
+    { value: "hard-light", label: "Hard Light", gpuId: 8, canvasOp: "hard-light", sharpBlend: "hard-light" },
+    { value: "soft-light", label: "Soft Light", gpuId: 9, canvasOp: "soft-light", sharpBlend: "soft-light" },
+    { value: "difference", label: "Difference", gpuId: 10, canvasOp: "difference", sharpBlend: "difference" },
+    { value: "exclusion", label: "Exclusion", gpuId: 11, canvasOp: "exclusion", sharpBlend: "exclusion" },
+    { value: "add", label: "Add", gpuId: 12, canvasOp: "lighter", sharpBlend: "add" }
+];
+/** Ordered list of `{ value, label }` for populating UI dropdowns. */
+export const BLEND_MODES = BLEND_MODE_INFOS.map(({ value, label }) => ({ value, label }));
+/** All canonical blend-mode values in display order (literal tuple). */
+export const BLEND_MODE_VALUES = BLEND_MODE_TUPLE;
+const INFO_BY_VALUE = new Map(BLEND_MODE_INFOS.map((info) => [info.value, info]));
+/**
+ * Every persisted spelling of a blend mode, mapped to its canonical value:
+ * each canonical value itself, plus the legacy aliases — the Compositor image
+ * node historically stored `"over"` (the libvips name) for normal blending.
+ *
+ * Keyed by `unknown` so a persisted value that is not a blend-mode string at
+ * all (a number, an object, a stray data URL that leaked into UI state) simply
+ * misses the lookup instead of needing a representation check first.
+ */
+const CANONICAL_BY_PERSISTED_VALUE = new Map();
+for (const info of BLEND_MODE_INFOS) {
+    CANONICAL_BY_PERSISTED_VALUE.set(info.value, info.value);
+}
+CANONICAL_BY_PERSISTED_VALUE.set("over", "normal");
+/**
+ * Coerce an arbitrary input to a canonical {@link BlendMode}. Unknown values
+ * (including stray data URLs that can leak into persisted UI state) fall back
+ * to `"normal"`. Accepts the legacy `"over"` alias.
+ */
+export function coerceBlendMode(value) {
+    return CANONICAL_BY_PERSISTED_VALUE.get(value) ?? "normal";
+}
+/**
+ * Numeric id for the WGSL `applyBlendMode` switch. Takes a persisted value
+ * (canonical, legacy alias, or junk); anything unrecognized blends as normal.
+ */
+export function blendModeGpuId(value) {
+    return INFO_BY_VALUE.get(coerceBlendMode(value))?.gpuId ?? 0;
+}
+/** Canvas2D `globalCompositeOperation` for a persisted blend mode. */
+export function blendModeToCanvasOp(value) {
+    return INFO_BY_VALUE.get(coerceBlendMode(value))?.canvasOp ?? "source-over";
+}
+/** Sharp/libvips `blend` string for a persisted blend mode. */
+export function blendModeToSharpBlend(value) {
+    return INFO_BY_VALUE.get(coerceBlendMode(value))?.sharpBlend ?? "over";
+}
+//# sourceMappingURL=blendModes.js.map

package/dist/blend/blendModes.js.map

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

package/dist/blend/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Blend catalog — pure, Node-safe.
+ *
+ * The canonical `BlendMode` union, the ordered UI list, stable `gpuId`s, the
+ * Canvas2D / Sharp-libvips mappings, and the shared WGSL `applyBlendMode`
+ * switch. No WebGPU runtime — importable from Node consumers.
+ */
+export * from "./blendModes.js";
+export * from "./wgsl.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/blend/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC"}

package/dist/blend/index.js

@@ -0,0 +1,10 @@
+/**
+ * Blend catalog — pure, Node-safe.
+ *
+ * The canonical `BlendMode` union, the ordered UI list, stable `gpuId`s, the
+ * Canvas2D / Sharp-libvips mappings, and the shared WGSL `applyBlendMode`
+ * switch. No WebGPU runtime — importable from Node consumers.
+ */
+export * from "./blendModes.js";
+export * from "./wgsl.js";
+//# sourceMappingURL=index.js.map

package/dist/blend/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/blend/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC"}

package/dist/blend/wgsl.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared WGSL blend-mode functions.
+ *
+ * Both the sketch editor and the timeline preview compositor inject this
+ * string into their fragment shaders (via template interpolation) so the
+ * blend math is defined once. It exposes:
+ *
+ *   fn applyBlendMode(src: vec3f, dst: vec3f, mode: u32) -> vec3f
+ *
+ * `mode` is the `gpuId` from the canonical blend-mode table in
+ * `blendModes.ts` — keep the switch cases in lock-step with that table.
+ * The per-channel functions implement the W3C compositing spec; `add` (12)
+ * is additive (saturating sum).
+ */
+export declare const WGSL_BLEND_FUNCTIONS = "\n// Blend mode ids (must match BLEND_MODE_INFOS[*].gpuId in blendModes.ts):\n// 0 = normal, 1 = multiply, 2 = screen, 3 = overlay, 4 = darken,\n// 5 = lighten, 6 = color-dodge, 7 = color-burn, 8 = hard-light,\n// 9 = soft-light, 10 = difference, 11 = exclusion, 12 = add\n\nfn softLightD(x: f32) -> f32 {\n  if (x <= 0.25) {\n    return ((16.0 * x - 12.0) * x + 4.0) * x;\n  }\n  return sqrt(x);\n}\n\nfn blendChannel(s: f32, d: f32, mode: u32) -> f32 {\n  switch (mode) {\n    case 0u: { return s; }\n    case 1u: { return s * d; }\n    case 2u: { return s + d - s * d; }\n    case 3u: {\n      return select(\n        1.0 - 2.0 * (1.0 - s) * (1.0 - d),\n        2.0 * s * d,\n        d <= 0.5\n      );\n    }\n    case 4u: { return min(s, d); }\n    case 5u: { return max(s, d); }\n    case 6u: {\n      return select(\n        min(1.0, d / max(1.0 - s, 0.001)),\n        1.0,\n        s >= 1.0\n      );\n    }\n    case 7u: {\n      return select(\n        max(0.0, 1.0 - (1.0 - d) / max(s, 0.001)),\n        0.0,\n        s <= 0.0\n      );\n    }\n    case 8u: {\n      return select(\n        1.0 - 2.0 * (1.0 - s) * (1.0 - d),\n        2.0 * s * d,\n        s <= 0.5\n      );\n    }\n    case 9u: {\n      return select(\n        d + (2.0 * s - 1.0) * (softLightD(d) - d),\n        d - (1.0 - 2.0 * s) * d * (1.0 - d),\n        s <= 0.5\n      );\n    }\n    case 10u: { return abs(s - d); }\n    case 11u: { return s + d - 2.0 * s * d; }\n    case 12u: { return min(1.0, s + d); }\n    default: { return s; }\n  }\n}\n\nfn applyBlendMode(src: vec3f, dst: vec3f, mode: u32) -> vec3f {\n  return vec3f(\n    blendChannel(src.x, dst.x, mode),\n    blendChannel(src.y, dst.y, mode),\n    blendChannel(src.z, dst.z, mode)\n  );\n}\n";
+//# sourceMappingURL=wgsl.d.ts.map

package/dist/blend/wgsl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wgsl.d.ts","sourceRoot":"","sources":["../../src/blend/wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB,gtDAqEhC,CAAC"}

package/dist/blend/wgsl.js

@@ -0,0 +1,85 @@
+/**
+ * Shared WGSL blend-mode functions.
+ *
+ * Both the sketch editor and the timeline preview compositor inject this
+ * string into their fragment shaders (via template interpolation) so the
+ * blend math is defined once. It exposes:
+ *
+ *   fn applyBlendMode(src: vec3f, dst: vec3f, mode: u32) -> vec3f
+ *
+ * `mode` is the `gpuId` from the canonical blend-mode table in
+ * `blendModes.ts` — keep the switch cases in lock-step with that table.
+ * The per-channel functions implement the W3C compositing spec; `add` (12)
+ * is additive (saturating sum).
+ */
+export const WGSL_BLEND_FUNCTIONS = /* wgsl */ `
+// Blend mode ids (must match BLEND_MODE_INFOS[*].gpuId in blendModes.ts):
+// 0 = normal, 1 = multiply, 2 = screen, 3 = overlay, 4 = darken,
+// 5 = lighten, 6 = color-dodge, 7 = color-burn, 8 = hard-light,
+// 9 = soft-light, 10 = difference, 11 = exclusion, 12 = add
+
+fn softLightD(x: f32) -> f32 {
+  if (x <= 0.25) {
+    return ((16.0 * x - 12.0) * x + 4.0) * x;
+  }
+  return sqrt(x);
+}
+
+fn blendChannel(s: f32, d: f32, mode: u32) -> f32 {
+  switch (mode) {
+    case 0u: { return s; }
+    case 1u: { return s * d; }
+    case 2u: { return s + d - s * d; }
+    case 3u: {
+      return select(
+        1.0 - 2.0 * (1.0 - s) * (1.0 - d),
+        2.0 * s * d,
+        d <= 0.5
+      );
+    }
+    case 4u: { return min(s, d); }
+    case 5u: { return max(s, d); }
+    case 6u: {
+      return select(
+        min(1.0, d / max(1.0 - s, 0.001)),
+        1.0,
+        s >= 1.0
+      );
+    }
+    case 7u: {
+      return select(
+        max(0.0, 1.0 - (1.0 - d) / max(s, 0.001)),
+        0.0,
+        s <= 0.0
+      );
+    }
+    case 8u: {
+      return select(
+        1.0 - 2.0 * (1.0 - s) * (1.0 - d),
+        2.0 * s * d,
+        s <= 0.5
+      );
+    }
+    case 9u: {
+      return select(
+        d + (2.0 * s - 1.0) * (softLightD(d) - d),
+        d - (1.0 - 2.0 * s) * d * (1.0 - d),
+        s <= 0.5
+      );
+    }
+    case 10u: { return abs(s - d); }
+    case 11u: { return s + d - 2.0 * s * d; }
+    case 12u: { return min(1.0, s + d); }
+    default: { return s; }
+  }
+}
+
+fn applyBlendMode(src: vec3f, dst: vec3f, mode: u32) -> vec3f {
+  return vec3f(
+    blendChannel(src.x, dst.x, mode),
+    blendChannel(src.y, dst.y, mode),
+    blendChannel(src.z, dst.z, mode)
+  );
+}
+`;
+//# sourceMappingURL=wgsl.js.map

package/dist/blend/wgsl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wgsl.js","sourceRoot":"","sources":["../../src/blend/wgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqE9C,CAAC"}

package/dist/compositor/compositor.d.ts

@@ -0,0 +1,112 @@
+/**
+ * WebGPULayerCompositor — the shared layer-compositing engine.
+ *
+ * Owns the blend + blit render pipelines, the ping-pong accumulation
+ * textures, and the sampler. Both the sketch editor and the timeline
+ * preview drive it: they upload their own source textures (canvas layers /
+ * video frames), seed the background into the read texture, then call
+ * {@link renderBlendPass} once per layer and {@link blit} to present.
+ *
+ * The engine is source-agnostic — it composites `GPUTexture`s addressed by a
+ * 2×3 inverse-affine matrix (screen px → layer texel). Sketch supplies
+ * `nearest` filtering (pixel-exact paint); the timeline supplies `linear`
+ * (smooth scaled video) plus an optional rounded-rect mask.
+ */
+/** 2×3 affine matrix mapping screen pixels → layer texels. */
+export interface InverseAffine {
+    a: number;
+    b: number;
+    tx: number;
+    c: number;
+    d: number;
+    ty: number;
+    p?: number;
+    q?: number;
+    r?: number;
+}
+export type CompositorFilter = "nearest" | "linear";
+export interface BlendPassParams {
+    /** Layer source texture. */
+    source: GPUTexture;
+    opacity: number;
+    /** Canonical blend-mode gpuId (see blendModes.ts). */
+    blendModeId: number;
+    canvasW: number;
+    canvasH: number;
+    invAffine: InverseAffine;
+    /** Normalized rounded-corner radius 0..0.5. 0 = sharp (default). */
+    borderRadius?: number;
+    /**
+     * Directional wipe mask in the layer's own normalized quad space (the mask
+     * edge rotates with the layer). Omit for no mask.
+     */
+    wipe?: {
+        /** Edge the reveal starts from: 1 = left, 2 = right, 3 = top, 4 = bottom. */
+        edge: 1 | 2 | 3 | 4;
+        /** 0 = fully hidden, 1 = fully revealed. */
+        progress: number;
+        /** Feathered edge width as a fraction of the wipe axis. 0 = hard edge. */
+        softness: number;
+    };
+    iris?: {
+        progress: number;
+        softness: number;
+    };
+}
+/**
+ * Convert a column-major 4×4 clip-space placement matrix (mapping a quad
+ * with local coords in [-1,1]² to clip space, as produced by the timeline's
+ * `buildTransformMatrix`) into the inverse-affine matrix (screen px → layer
+ * texel) the compositor shader expects.
+ *
+ * The composed screen→texel map is affine, so it is reconstructed exactly by
+ * evaluating three points and differencing — no hand-derived trigonometry,
+ * which keeps placement faithful to the matrix the caller already trusts.
+ */
+export declare function forwardClipMatrixToInverseAffine(m: Float32Array | number[], sourceWidth: number, sourceHeight: number, canvasWidth: number, canvasHeight: number): InverseAffine;
+/**
+ * {@link forwardClipMatrixToInverseAffine} without the identity fallback: null
+ * when the placement covers no area, such as a layer scaled to zero on either
+ * axis. A caller that draws layers must skip a null placement. The identity
+ * would draw the source 1:1 from the frame's top-left corner.
+ */
+export declare function invertClipPlacement(m: Float32Array | number[], sourceWidth: number, sourceHeight: number, canvasWidth: number, canvasHeight: number): InverseAffine | null;
+export declare class WebGPULayerCompositor {
+    private readonly device;
+    private readonly format;
+    private readonly root;
+    private readonly blendBindGroupLayout;
+    private readonly blendPipeline;
+    private readonly blitBindGroupLayout;
+    private readonly blitPipeline;
+    private readonly sampler;
+    private readonly filterMode;
+    private pingPongA;
+    private pingPongB;
+    private widthPx;
+    private heightPx;
+    private uniformBuffers;
+    private passIndex;
+    constructor(device: GPUDevice, format: GPUTextureFormat, filter?: CompositorFilter, label?: string);
+    get width(): number;
+    get height(): number;
+    /** The ping-pong accumulation textures. Seed the background into A. */
+    get textureA(): GPUTexture | null;
+    get textureB(): GPUTexture | null;
+    /** (Re)allocate the ping-pong textures when the canvas size changes. */
+    ensureSize(width: number, height: number): void;
+    /**
+     * Reset the per-frame uniform-buffer ring. Call once before the frame's
+     * sequence of {@link renderBlendPass} calls.
+     */
+    beginFrame(): void;
+    /**
+     * Composite one layer: reads `readTex` (current accumulation) and the
+     * layer source, writes the blended result to `writeTex` (full-screen).
+     */
+    renderBlendPass(encoder: GPUCommandEncoder, readTex: GPUTexture, writeTex: GPUTexture, params: BlendPassParams): void;
+    /** Present `srcTex` to a target view (swap chain or other attachment). */
+    blit(encoder: GPUCommandEncoder, srcTex: GPUTexture, targetView: GPUTextureView): void;
+    dispose(): void;
+}
+//# sourceMappingURL=compositor.d.ts.map

package/dist/compositor/compositor.d.ts.map

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