@nodetool-ai/gpu 0.8.1

package/dist/shaders/transform/spherize/v1/module.js

@@ -0,0 +1,94 @@
+/**
+ * `transform.spherize@1` — spherical/fisheye lens distortion centered on the
+ * source.
+ *
+ * `amount > 0` bulges the centre outward (fisheye, magnifying-glass);
+ * `amount < 0` pinches it inward. The implementation is the classic
+ * Photoshop-style normalized-radius warp: convert UV to centered polar,
+ * remap the radius by `r' = r * (1 + amount * (1 - r²))`, convert back.
+ *
+ * Output dimensions stay `same-as:source`. Pixels outside the unit circle
+ * pass through unchanged so the corners of a rectangular source aren't
+ * snipped; pixels inside the circle get the spherical remap.
+ */
+import tgpu from "typegpu";
+import * as d from "typegpu/data";
+import { defineModule } from "../../../../module.js";
+export const SpherizeParams = d.struct({
+    amount: d.f32
+});
+const layout = tgpu.bindGroupLayout({
+    params: { uniform: SpherizeParams },
+    source: { texture: "float" },
+    samp: { sampler: "filtering" }
+});
+const samplerDescriptor = {
+    magFilter: "linear",
+    minFilter: "linear",
+    addressModeU: "clamp-to-edge",
+    addressModeV: "clamp-to-edge"
+};
+export const transformSpherizeV1 = defineModule({
+    id: "transform.spherize",
+    version: 1,
+    surface: "internal",
+    category: "transform",
+    linearity: "linear-in-rgb",
+    kind: "fragment",
+    params: SpherizeParams,
+    paramDefaults: { amount: 0.5 },
+    paramUi: {
+        amount: {
+            min: -1,
+            max: 1,
+            step: 0.01,
+            label: "Amount",
+            notes: "negative pinches, positive bulges"
+        }
+    },
+    layout,
+    samplers: { samp: samplerDescriptor },
+    wgsl: /* wgsl */ `
+@fragment
+fn fs_main(@location(0) uv: vec2f) -> @location(0) vec4f {
+  let amount = layout.$.params.amount;
+  let centered = (uv - vec2f(0.5)) * 2.0;
+  let r2 = dot(centered, centered);
+  // Inverse map: an output pixel at radius r samples the source at r*factor.
+  // To bulge (magnify) the centre, the source radius must be pulled inward
+  // (factor < 1 near the centre), so positive amount subtracts. Using
+  // 1.0 + amount * (...) inverted this and pinched on positive amount, the
+  // opposite of the documented behaviour.
+  let factor = 1.0 - amount * (1.0 - r2);
+  let warpedUv = centered * factor * 0.5 + vec2f(0.5);
+  // Outside the unit circle: passthrough (sample the original uv). Inside:
+  // sample the warped uv. textureSample must run in uniform control flow, so
+  // pick the source uv up front and sample once.
+  let inside = r2 < 1.0;
+  let s = select(uv, warpedUv, inside);
+  let col = textureSample(layout.$.source, layout.$.samp, s);
+  // A strong pinch (amount < 0) can push the warped uv outside [0,1]; those
+  // taps become transparent black rather than smearing the edge, matching the
+  // out-of-bounds convention in transform.affine / transform.cornerPin.
+  let oob = inside && (warpedUv.x < 0.0 || warpedUv.x > 1.0 || warpedUv.y < 0.0 || warpedUv.y > 1.0);
+  return select(col, vec4f(0.0), oob);
+}
+`,
+    io: {
+        inputs: {
+            source: {
+                colorSpace: "linear",
+                alpha: "premultiplied",
+                bindingKinds: ["texture_2d"]
+            }
+        },
+        output: {
+            colorSpace: "linear",
+            alpha: "premultiplied",
+            format: "rgba8unorm",
+            dimensions: "same-as:source"
+        },
+        rod: "same-as:source"
+    }
+});
+//# sourceMappingURL=module.js.map

package/dist/shaders/transform/spherize/v1/module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.js","sourceRoot":"","sources":["../../../../../src/shaders/transform/spherize/v1/module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,IAAI,MAAM,SAAS,CAAC;AAC3B,OAAO,KAAK,CAAC,MAAM,cAAc,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAErD,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,MAAM,EAAE,CAAC,CAAC,GAAG;CACd,CAAC,CAAC;AAEH,MAAM,MAAM,GAAG,IAAI,CAAC,eAAe,CAAC;IAClC,MAAM,EAAE,EAAE,OAAO,EAAE,cAAc,EAAE;IACnC,MAAM,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE;IAC5B,IAAI,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE;CAC/B,CAAC,CAAC;AAEH,MAAM,iBAAiB,GAAyB;IAC9C,SAAS,EAAE,QAAQ;IACnB,SAAS,EAAE,QAAQ;IACnB,YAAY,EAAE,eAAe;IAC7B,YAAY,EAAE,eAAe;CAC9B,CAAC;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAG,YAAY,CAAC;IAC9C,EAAE,EAAE,oBAAoB;IACxB,OAAO,EAAE,CAAC;IACV,OAAO,EAAE,UAAU;IACnB,QAAQ,EAAE,WAAW;IACrB,SAAS,EAAE,eAAe;IAC1B,IAAI,EAAE,UAAU;IAChB,MAAM,EAAE,cAAc;IACtB,aAAa,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE;IAC9B,OAAO,EAAE;QACP,MAAM,EAAE;YACN,GAAG,EAAE,CAAC,CAAC;YACP,GAAG,EAAE,CAAC;YACN,IAAI,EAAE,IAAI;YACV,KAAK,EAAE,QAAQ;YACf,KAAK,EAAE,mCAAmC;SAC3C;KACF;IACD,MAAM;IACN,QAAQ,EAAE,EAAE,IAAI,EAAE,iBAAiB,EAAE;IACrC,IAAI,EAAE,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;CAyBlB;IACC,EAAE,EAAE;QACF,MAAM,EAAE;YACN,MAAM,EAAE;gBACN,UAAU,EAAE,QAAQ;gBACpB,KAAK,EAAE,eAAe;gBACtB,YAAY,EAAE,CAAC,YAAY,CAAC;aAC7B;SACF;QACD,MAAM,EAAE;YACN,UAAU,EAAE,QAAQ;YACpB,KAAK,EAAE,eAAe;YACtB,MAAM,EAAE,YAAY;YACpB,UAAU,EAAE,gBAAgB;SAC7B;QACD,GAAG,EAAE,gBAAgB;KACtB;CACF,CAAC,CAAC"}

package/dist/shaders/transform/tile/v1/module.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `transform.tile@1` — tile the source `tilesX` × `tilesY` times across the
+ * output canvas.
+ *
+ * Output dimensions stay `same-as:source` — tiling reduces the per-tile size
+ * inside the same canvas rather than enlarging the target. `wrap` controls
+ * how UVs at tile borders are sampled: `0` clamp-to-edge (every tile is a
+ * crisp copy of the source), `1` repeat, `2` mirror-repeat (tiles alternate
+ * orientation, producing the classic seamless pattern).
+ */
+import * as d from "typegpu/data";
+export declare const TileParams: d.WgslStruct<{
+    tilesX: d.F32;
+    tilesY: d.F32;
+    wrap: d.F32;
+}>;
+export declare const transformTileV1: import("../../../../module.js").ShaderModule<d.WgslStruct<{
+    tilesX: d.F32;
+    tilesY: d.F32;
+    wrap: d.F32;
+}>>;
+//# sourceMappingURL=module.d.ts.map

package/dist/shaders/transform/tile/v1/module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../../../../../src/shaders/transform/tile/v1/module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,CAAC,MAAM,cAAc,CAAC;AAGlC,eAAO,MAAM,UAAU;;;;EAIrB,CAAC;AAeH,eAAO,MAAM,eAAe;;;;GA0D1B,CAAC"}

package/dist/shaders/transform/tile/v1/module.js

@@ -0,0 +1,89 @@
+/**
+ * `transform.tile@1` — tile the source `tilesX` × `tilesY` times across the
+ * output canvas.
+ *
+ * Output dimensions stay `same-as:source` — tiling reduces the per-tile size
+ * inside the same canvas rather than enlarging the target. `wrap` controls
+ * how UVs at tile borders are sampled: `0` clamp-to-edge (every tile is a
+ * crisp copy of the source), `1` repeat, `2` mirror-repeat (tiles alternate
+ * orientation, producing the classic seamless pattern).
+ */
+import tgpu from "typegpu";
+import * as d from "typegpu/data";
+import { defineModule } from "../../../../module.js";
+export const TileParams = d.struct({
+    tilesX: d.f32,
+    tilesY: d.f32,
+    wrap: d.f32
+});
+const layout = tgpu.bindGroupLayout({
+    params: { uniform: TileParams },
+    source: { texture: "float" },
+    samp: { sampler: "filtering" }
+});
+const samplerDescriptor = {
+    magFilter: "linear",
+    minFilter: "linear",
+    addressModeU: "clamp-to-edge",
+    addressModeV: "clamp-to-edge"
+};
+export const transformTileV1 = defineModule({
+    id: "transform.tile",
+    version: 1,
+    surface: "internal",
+    category: "transform",
+    linearity: "linear-in-rgb",
+    kind: "fragment",
+    params: TileParams,
+    paramDefaults: { tilesX: 2, tilesY: 2, wrap: 1 },
+    paramUi: {
+        tilesX: { min: 1, max: 32, step: 1, label: "Tiles X" },
+        tilesY: { min: 1, max: 32, step: 1, label: "Tiles Y" },
+        wrap: { min: 0, max: 2, step: 1, label: "Wrap", notes: "0 clamp / 1 repeat / 2 mirror" }
+    },
+    layout,
+    samplers: { samp: samplerDescriptor },
+    wgsl: /* wgsl */ `
+fn applyWrap(u: vec2f, mode: i32) -> vec2f {
+  if (mode == 2) {
+    let q = fract(u * 0.5) * 2.0;
+    return vec2f(
+      select(q.x, 2.0 - q.x, q.x > 1.0),
+      select(q.y, 2.0 - q.y, q.y > 1.0)
+    );
+  }
+  if (mode == 0) {
+    return clamp(u, vec2f(0.0), vec2f(1.0));
+  }
+  return fract(u);
+}
+
+@fragment
+fn fs_main(@location(0) uv: vec2f) -> @location(0) vec4f {
+  let p = layout.$.params;
+  let tx = max(1.0, p.tilesX);
+  let ty = max(1.0, p.tilesY);
+  let mode = i32(round(p.wrap));
+  let scaled = vec2f(uv.x * tx, uv.y * ty);
+  let u = applyWrap(scaled, mode);
+  return textureSample(layout.$.source, layout.$.samp, u);
+}
+`,
+    io: {
+        inputs: {
+            source: {
+                colorSpace: "linear",
+                alpha: "premultiplied",
+                bindingKinds: ["texture_2d"]
+            }
+        },
+        output: {
+            colorSpace: "linear",
+            alpha: "premultiplied",
+            format: "rgba8unorm",
+            dimensions: "same-as:source"
+        },
+        rod: "same-as:source"
+    }
+});
+//# sourceMappingURL=module.js.map

package/dist/shaders/transform/tile/v1/module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.js","sourceRoot":"","sources":["../../../../../src/shaders/transform/tile/v1/module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,IAAI,MAAM,SAAS,CAAC;AAC3B,OAAO,KAAK,CAAC,MAAM,cAAc,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAErD,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC;IACjC,MAAM,EAAE,CAAC,CAAC,GAAG;IACb,MAAM,EAAE,CAAC,CAAC,GAAG;IACb,IAAI,EAAE,CAAC,CAAC,GAAG;CACZ,CAAC,CAAC;AAEH,MAAM,MAAM,GAAG,IAAI,CAAC,eAAe,CAAC;IAClC,MAAM,EAAE,EAAE,OAAO,EAAE,UAAU,EAAE;IAC/B,MAAM,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE;IAC5B,IAAI,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE;CAC/B,CAAC,CAAC;AAEH,MAAM,iBAAiB,GAAyB;IAC9C,SAAS,EAAE,QAAQ;IACnB,SAAS,EAAE,QAAQ;IACnB,YAAY,EAAE,eAAe;IAC7B,YAAY,EAAE,eAAe;CAC9B,CAAC;AAEF,MAAM,CAAC,MAAM,eAAe,GAAG,YAAY,CAAC;IAC1C,EAAE,EAAE,gBAAgB;IACpB,OAAO,EAAE,CAAC;IACV,OAAO,EAAE,UAAU;IACnB,QAAQ,EAAE,WAAW;IACrB,SAAS,EAAE,eAAe;IAC1B,IAAI,EAAE,UAAU;IAChB,MAAM,EAAE,UAAU;IAClB,aAAa,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE;IAChD,OAAO,EAAE;QACP,MAAM,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE;QACtD,MAAM,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE;QACtD,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,+BAA+B,EAAE;KACzF;IACD,MAAM;IACN,QAAQ,EAAE,EAAE,IAAI,EAAE,iBAAiB,EAAE;IACrC,IAAI,EAAE,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;CAyBlB;IACC,EAAE,EAAE;QACF,MAAM,EAAE;YACN,MAAM,EAAE;gBACN,UAAU,EAAE,QAAQ;gBACpB,KAAK,EAAE,eAAe;gBACtB,YAAY,EAAE,CAAC,YAAY,CAAC;aAC7B;SACF;QACD,MAAM,EAAE;YACN,UAAU,EAAE,QAAQ;YACpB,KAAK,EAAE,eAAe;YACtB,MAAM,EAAE,YAAY;YACpB,UAAU,EAAE,gBAAgB;SAC7B;QACD,GAAG,EAAE,gBAAgB;KACtB;CACF,CAAC,CAAC"}

package/dist/shared/lumaWgsl.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Rec. 709 luminance — interpolate into a WGSL template, then call `luma709`.
+ *
+ * The weights are the linear-space set. Rec. 601 (`0.299, 0.587, 0.114`) is
+ * for gamma-encoded video and is wrong for the color spaces the pool declares;
+ * `shaderCorrectness.test.ts` asserts it never appears.
+ *
+ * What to pass is the caller's call. A nonlinear module un-premultiplies first
+ * (see `shared/premulWgsl.ts`) so the result doesn't drift with alpha; a
+ * `linear-in-rgb` one can hand over premultiplied RGB, because `dot` commutes
+ * with the alpha multiply.
+ */
+export declare const WGSL_LUMA709 = "\nfn luma709(c: vec3f) -> f32 {\n  return dot(c, vec3f(0.2126, 0.7152, 0.0722));\n}\n";
+//# sourceMappingURL=lumaWgsl.d.ts.map

package/dist/shared/lumaWgsl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lumaWgsl.d.ts","sourceRoot":"","sources":["../../src/shared/lumaWgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,0FAIxB,CAAC"}

package/dist/shared/lumaWgsl.js

@@ -0,0 +1,18 @@
+/**
+ * Rec. 709 luminance — interpolate into a WGSL template, then call `luma709`.
+ *
+ * The weights are the linear-space set. Rec. 601 (`0.299, 0.587, 0.114`) is
+ * for gamma-encoded video and is wrong for the color spaces the pool declares;
+ * `shaderCorrectness.test.ts` asserts it never appears.
+ *
+ * What to pass is the caller's call. A nonlinear module un-premultiplies first
+ * (see `shared/premulWgsl.ts`) so the result doesn't drift with alpha; a
+ * `linear-in-rgb` one can hand over premultiplied RGB, because `dot` commutes
+ * with the alpha multiply.
+ */
+export const WGSL_LUMA709 = /* wgsl */ `
+fn luma709(c: vec3f) -> f32 {
+  return dot(c, vec3f(0.2126, 0.7152, 0.0722));
+}
+`;
+//# sourceMappingURL=lumaWgsl.js.map

package/dist/shared/lumaWgsl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lumaWgsl.js","sourceRoot":"","sources":["../../src/shared/lumaWgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,UAAU,CAAC;;;;CAItC,CAAC"}

package/dist/shared/premulWgsl.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Premul-typed color helpers — WGSL snippet bundle for shader authors.
+ *
+ * **When to use.** Any module whose input is `alpha: "premultiplied"` AND
+ * whose RGB math is *nonlinear* (gamma, contrast, HSV, saturate, etc.) MUST
+ * un-premultiply before touching channels and re-premultiply before writing.
+ * Doing that math directly on `texture.rgb` silently produces wrong output
+ * on partially transparent pixels, and the bug is invisible in the common
+ * fully-opaque case. This bundle makes the mistake impossible to express:
+ *
+ *   - `Premul { v: vec4f }` and `Straight { v: vec4f }` are distinct structs.
+ *     WGSL has no newtype, but distinct structs are nominally typed — you
+ *     can't pass a `Premul` where a `Straight` is expected, and neither has
+ *     a `.rgb` field, so `samp.rgb` simply won't compile.
+ *   - The only way to extract channels is `unpremul(p).v.rgb` (for nonlinear
+ *     ops) or `p.v` (for linear ops that stay in premul space).
+ *
+ * **How to use.** Interpolate the bundle into the WGSL template:
+ *
+ *   import { WGSL_PREMUL_HELPERS } from "../../../../shared/premulWgsl.js";
+ *
+ *   wgsl: \/\* wgsl \*\/ \`
+ *   ${WGSL_PREMUL_HELPERS}
+ *
+ *   @fragment fn fs_main(@location(0) uv: vec2f) -> @location(0) vec4f {
+ *     let p = samplePremul(layout.$.source, layout.$.samp, uv);
+ *     let s = unpremul(p);
+ *     let newRgb = vec3f(1.0) - s.v.rgb;            // nonlinear op
+ *     let out = premul(Straight(vec4f(newRgb, s.v.a)));
+ *     return out.v;
+ *   }
+ *   \`
+ *
+ * For linear-in-rgb modules (tint multiply, brightness add, lerp between
+ * two premul values, Porter-Duff over), prefer the `premul*` helpers
+ * (`premulScale`, `premulAdd`, `premulOver`) so the *intent* is local —
+ * a reader doesn't have to verify the math is linearity-safe by eye.
+ *
+ * **Migration status.** Two modules use this bundle today as proof of
+ * concept: `_canary.passthrough@1` (linear) and `color.invert@1` (nonlinear,
+ * previously hand-rolled the unpremul dance). Migrating the remaining 47
+ * shader modules is tracked separately and is deliberate follow-up work —
+ * the bundle is ship-ready; the rest of the pool isn't blocked on it.
+ */
+export declare const WGSL_PREMUL_HELPERS = "\n// ---- Typed-color helpers (premul-invariant) -------------------------------\n// Distinct structs; WGSL nominal typing prevents Premul/Straight from being\n// swapped, and neither has a .rgb field so channel access is forced through\n// unpremul()/premul().\nstruct Premul { v: vec4f }\nstruct Straight { v: vec4f }\n\nfn samplePremul(t: texture_2d<f32>, s: sampler, uv: vec2f) -> Premul {\n  return Premul(textureSample(t, s, uv));\n}\n\nfn sampleStraight(t: texture_2d<f32>, s: sampler, uv: vec2f) -> Straight {\n  return Straight(textureSample(t, s, uv));\n}\n\n// 1/255 floor avoids dividing by zero on transparent pixels; the resulting\n// \"straight\" color of a fully-transparent pixel is undefined anyway because\n// rgb*0 = 0 erases all information, but the floor keeps math finite and\n// matches the convention used elsewhere in the pool.\nfn unpremul(p: Premul) -> Straight {\n  let a = max(p.v.a, 1.0 / 255.0);\n  return Straight(vec4f(p.v.rgb / a, p.v.a));\n}\n\nfn premul(s: Straight) -> Premul {\n  return Premul(vec4f(s.v.rgb * s.v.a, s.v.a));\n}\n\n// Linear-op helpers \u2014 safe to apply directly to premul values without an\n// unpremul round-trip. Use these when you want the intent (\"this is a\n// premul-safe linear op\") to be visible at the call site.\nfn premulScale(p: Premul, k: f32) -> Premul {\n  return Premul(p.v * k);\n}\n\nfn premulAdd(a: Premul, b: Premul) -> Premul {\n  return Premul(a.v + b.v);\n}\n\n// Premultiplied Porter-Duff \"over\": src over dst, correct on premul inputs.\nfn premulOver(src: Premul, dst: Premul) -> Premul {\n  return Premul(src.v + dst.v * (1.0 - src.v.a));\n}\n";
+//# sourceMappingURL=premulWgsl.d.ts.map

package/dist/shared/premulWgsl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"premulWgsl.d.ts","sourceRoot":"","sources":["../../src/shared/premulWgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,eAAO,MAAM,mBAAmB,smDA4C/B,CAAC"}

package/dist/shared/premulWgsl.js

@@ -0,0 +1,90 @@
+/**
+ * Premul-typed color helpers — WGSL snippet bundle for shader authors.
+ *
+ * **When to use.** Any module whose input is `alpha: "premultiplied"` AND
+ * whose RGB math is *nonlinear* (gamma, contrast, HSV, saturate, etc.) MUST
+ * un-premultiply before touching channels and re-premultiply before writing.
+ * Doing that math directly on `texture.rgb` silently produces wrong output
+ * on partially transparent pixels, and the bug is invisible in the common
+ * fully-opaque case. This bundle makes the mistake impossible to express:
+ *
+ *   - `Premul { v: vec4f }` and `Straight { v: vec4f }` are distinct structs.
+ *     WGSL has no newtype, but distinct structs are nominally typed — you
+ *     can't pass a `Premul` where a `Straight` is expected, and neither has
+ *     a `.rgb` field, so `samp.rgb` simply won't compile.
+ *   - The only way to extract channels is `unpremul(p).v.rgb` (for nonlinear
+ *     ops) or `p.v` (for linear ops that stay in premul space).
+ *
+ * **How to use.** Interpolate the bundle into the WGSL template:
+ *
+ *   import { WGSL_PREMUL_HELPERS } from "../../../../shared/premulWgsl.js";
+ *
+ *   wgsl: \/\* wgsl \*\/ \`
+ *   ${WGSL_PREMUL_HELPERS}
+ *
+ *   @fragment fn fs_main(@location(0) uv: vec2f) -> @location(0) vec4f {
+ *     let p = samplePremul(layout.$.source, layout.$.samp, uv);
+ *     let s = unpremul(p);
+ *     let newRgb = vec3f(1.0) - s.v.rgb;            // nonlinear op
+ *     let out = premul(Straight(vec4f(newRgb, s.v.a)));
+ *     return out.v;
+ *   }
+ *   \`
+ *
+ * For linear-in-rgb modules (tint multiply, brightness add, lerp between
+ * two premul values, Porter-Duff over), prefer the `premul*` helpers
+ * (`premulScale`, `premulAdd`, `premulOver`) so the *intent* is local —
+ * a reader doesn't have to verify the math is linearity-safe by eye.
+ *
+ * **Migration status.** Two modules use this bundle today as proof of
+ * concept: `_canary.passthrough@1` (linear) and `color.invert@1` (nonlinear,
+ * previously hand-rolled the unpremul dance). Migrating the remaining 47
+ * shader modules is tracked separately and is deliberate follow-up work —
+ * the bundle is ship-ready; the rest of the pool isn't blocked on it.
+ */
+export const WGSL_PREMUL_HELPERS = /* wgsl */ `
+// ---- Typed-color helpers (premul-invariant) -------------------------------
+// Distinct structs; WGSL nominal typing prevents Premul/Straight from being
+// swapped, and neither has a .rgb field so channel access is forced through
+// unpremul()/premul().
+struct Premul { v: vec4f }
+struct Straight { v: vec4f }
+
+fn samplePremul(t: texture_2d<f32>, s: sampler, uv: vec2f) -> Premul {
+  return Premul(textureSample(t, s, uv));
+}
+
+fn sampleStraight(t: texture_2d<f32>, s: sampler, uv: vec2f) -> Straight {
+  return Straight(textureSample(t, s, uv));
+}
+
+// 1/255 floor avoids dividing by zero on transparent pixels; the resulting
+// "straight" color of a fully-transparent pixel is undefined anyway because
+// rgb*0 = 0 erases all information, but the floor keeps math finite and
+// matches the convention used elsewhere in the pool.
+fn unpremul(p: Premul) -> Straight {
+  let a = max(p.v.a, 1.0 / 255.0);
+  return Straight(vec4f(p.v.rgb / a, p.v.a));
+}
+
+fn premul(s: Straight) -> Premul {
+  return Premul(vec4f(s.v.rgb * s.v.a, s.v.a));
+}
+
+// Linear-op helpers — safe to apply directly to premul values without an
+// unpremul round-trip. Use these when you want the intent ("this is a
+// premul-safe linear op") to be visible at the call site.
+fn premulScale(p: Premul, k: f32) -> Premul {
+  return Premul(p.v * k);
+}
+
+fn premulAdd(a: Premul, b: Premul) -> Premul {
+  return Premul(a.v + b.v);
+}
+
+// Premultiplied Porter-Duff "over": src over dst, correct on premul inputs.
+fn premulOver(src: Premul, dst: Premul) -> Premul {
+  return Premul(src.v + dst.v * (1.0 - src.v.a));
+}
+`;
+//# sourceMappingURL=premulWgsl.js.map

package/dist/shared/premulWgsl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"premulWgsl.js","sourceRoot":"","sources":["../../src/shared/premulWgsl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4C7C,CAAC"}

package/dist/texture.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `LabeledTexture` — a `GPUTexture` plus the metadata the Executor validates
+ * against a module's I/O contract.
+ *
+ * Every texture in flight through the pool is labeled: it carries its color
+ * space, alpha association, format, dimensions, and binding kind. The
+ * Executor checks bound inputs against the module's declared contract at
+ * bind time; mismatches fail loud or (later phases) route through a
+ * registered conversion.
+ *
+ * It also exposes a `contentVersion` counter, bumped on every write. That is
+ * the `inputs_content_hash` source for the future cache key (Phase 3) — full
+ * pixel hashing is not required.
+ */
+import type { AlphaMode, BindingKind, ColorSpaceTag } from "./types.js";
+/** Storage encoding + association recorded per texture. */
+export interface LabeledTextureMeta {
+    colorSpace: ColorSpaceTag;
+    alpha: AlphaMode;
+    bindingKind: BindingKind;
+}
+export interface CreateLabeledTextureOptions {
+    width: number;
+    height: number;
+    format: GPUTextureFormat;
+    usage: GPUTextureUsageFlags;
+    label?: string;
+    meta?: Partial<LabeledTextureMeta>;
+}
+export declare class LabeledTexture {
+    readonly texture: GPUTexture;
+    readonly label: string;
+    readonly format: GPUTextureFormat;
+    readonly width: number;
+    readonly height: number;
+    readonly meta: LabeledTextureMeta;
+    private version;
+    constructor(texture: GPUTexture, info: {
+        label: string;
+        format: GPUTextureFormat;
+        width: number;
+        height: number;
+        meta: LabeledTextureMeta;
+    });
+    /** Monotonic counter, bumped by {@link markWritten}. */
+    get contentVersion(): number;
+    /** Record that this texture's pixels changed (cache-key source). */
+    markWritten(): void;
+    createView(descriptor?: GPUTextureViewDescriptor): GPUTextureView;
+    destroy(): void;
+}
+/** Allocate a fresh {@link LabeledTexture} on the given device. */
+export declare function createLabeledTexture(device: GPUDevice, options: CreateLabeledTextureOptions): LabeledTexture;
+//# sourceMappingURL=texture.d.ts.map

package/dist/texture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"texture.d.ts","sourceRoot":"","sources":["../src/texture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAExE,2DAA2D;AAC3D,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,aAAa,CAAC;IAC1B,KAAK,EAAE,SAAS,CAAC;IACjB,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,gBAAgB,CAAC;IACzB,KAAK,EAAE,oBAAoB,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACpC;AAQD,qBAAa,cAAc;IACzB,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAElC,OAAO,CAAC,OAAO,CAAK;IAEpB,YACE,OAAO,EAAE,UAAU,EACnB,IAAI,EAAE;QACJ,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,gBAAgB,CAAC;QACzB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,kBAAkB,CAAC;KAC1B,EAQF;IAED,wDAAwD;IACxD,IAAI,cAAc,IAAI,MAAM,CAE3B;IAED,oEAAoE;IACpE,WAAW,IAAI,IAAI,CAElB;IAED,UAAU,CAAC,UAAU,CAAC,EAAE,wBAAwB,GAAG,cAAc,CAEhE;IAED,OAAO,IAAI,IAAI,CAEd;CACF;AAED,mEAAmE;AACnE,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,2BAA2B,GACnC,cAAc,CAiBhB"}

package/dist/texture.js

@@ -0,0 +1,70 @@
+/**
+ * `LabeledTexture` — a `GPUTexture` plus the metadata the Executor validates
+ * against a module's I/O contract.
+ *
+ * Every texture in flight through the pool is labeled: it carries its color
+ * space, alpha association, format, dimensions, and binding kind. The
+ * Executor checks bound inputs against the module's declared contract at
+ * bind time; mismatches fail loud or (later phases) route through a
+ * registered conversion.
+ *
+ * It also exposes a `contentVersion` counter, bumped on every write. That is
+ * the `inputs_content_hash` source for the future cache key (Phase 3) — full
+ * pixel hashing is not required.
+ */
+const DEFAULT_META = {
+    colorSpace: "linear",
+    alpha: "premultiplied",
+    bindingKind: "texture_2d"
+};
+export class LabeledTexture {
+    texture;
+    label;
+    format;
+    width;
+    height;
+    meta;
+    version = 0;
+    constructor(texture, info) {
+        this.texture = texture;
+        this.label = info.label;
+        this.format = info.format;
+        this.width = info.width;
+        this.height = info.height;
+        this.meta = info.meta;
+    }
+    /** Monotonic counter, bumped by {@link markWritten}. */
+    get contentVersion() {
+        return this.version;
+    }
+    /** Record that this texture's pixels changed (cache-key source). */
+    markWritten() {
+        this.version += 1;
+    }
+    createView(descriptor) {
+        return this.texture.createView(descriptor);
+    }
+    destroy() {
+        this.texture.destroy();
+    }
+}
+/** Allocate a fresh {@link LabeledTexture} on the given device. */
+export function createLabeledTexture(device, options) {
+    const width = Math.max(1, Math.floor(options.width));
+    const height = Math.max(1, Math.floor(options.height));
+    const label = options.label ?? "labeled-texture";
+    const texture = device.createTexture({
+        label,
+        size: { width, height },
+        format: options.format,
+        usage: options.usage
+    });
+    return new LabeledTexture(texture, {
+        label,
+        format: options.format,
+        width,
+        height,
+        meta: { ...DEFAULT_META, ...options.meta }
+    });
+}
+//# sourceMappingURL=texture.js.map

package/dist/texture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"texture.js","sourceRoot":"","sources":["../src/texture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAoBH,MAAM,YAAY,GAAuB;IACvC,UAAU,EAAE,QAAQ;IACpB,KAAK,EAAE,eAAe;IACtB,WAAW,EAAE,YAAY;CAC1B,CAAC;AAEF,MAAM,OAAO,cAAc;IAChB,OAAO,CAAa;IACpB,KAAK,CAAS;IACd,MAAM,CAAmB;IACzB,KAAK,CAAS;IACd,MAAM,CAAS;IACf,IAAI,CAAqB;IAE1B,OAAO,GAAG,CAAC,CAAC;IAEpB,YACE,OAAmB,EACnB,IAMC;QAED,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IACxB,CAAC;IAED,wDAAwD;IACxD,IAAI,cAAc;QAChB,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,oEAAoE;IACpE,WAAW;QACT,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC;IACpB,CAAC;IAED,UAAU,CAAC,UAAqC;QAC9C,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;IAC7C,CAAC;IAED,OAAO;QACL,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;IACzB,CAAC;CACF;AAED,mEAAmE;AACnE,MAAM,UAAU,oBAAoB,CAClC,MAAiB,EACjB,OAAoC;IAEpC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IACrD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IACvD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,iBAAiB,CAAC;IACjD,MAAM,OAAO,GAAG,MAAM,CAAC,aAAa,CAAC;QACnC,KAAK;QACL,IAAI,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE;QACvB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,KAAK,EAAE,OAAO,CAAC,KAAK;KACrB,CAAC,CAAC;IACH,OAAO,IAAI,cAAc,CAAC,OAAO,EAAE;QACjC,KAAK;QACL,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,KAAK;QACL,MAAM;QACN,IAAI,EAAE,EAAE,GAAG,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,EAAE;KAC3C,CAAC,CAAC;AACL,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Shared shader-pool contracts. Pure types + small const tuples — no WebGPU
+ * runtime, Node-safe. The pool's atomic unit of reuse is a {@link
+ * ShaderModule} (see `module.ts`); these are the vocabulary its fields are
+ * built from.
+ */
+/**
+ * Operation category. Drives registry grouping and (later) workflow-node
+ * palette organization. Open-ended on purpose — the catalog grows across
+ * phases — but the Phase 1–3 set is enumerated so typos fail typecheck.
+ */
+export type ShaderCategory = "filters" | "color" | "keyer" | "mask" | "sources" | "transform" | "mixer" | "compositor" | "alpha" | "_canary";
+/**
+ * Stability surface. `internal` modules are free to churn; `published`
+ * modules are frozen (additive-only) and are the only ones workflow nodes
+ * may reference (Phase 4). Promotion is a deliberate review, never a side
+ * effect of authoring a shader.
+ */
+export type ShaderSurface = "internal" | "published";
+/**
+ * Dispatch kind. `fragment` (full-screen triangle render pass) is the
+ * default for image-in/image-out ops. `compute` is reserved for ops that
+ * genuinely need shared memory or reductions. `snippet` is a reusable WGSL
+ * fragment with no entry point of its own (resolved into other modules).
+ */
+export type ShaderKind = "fragment" | "compute" | "snippet";
+/** Working color space a module input expects / an output is encoded in. */
+export type ColorSpaceTag = "linear" | "srgb";
+/**
+ * Alpha association. The pool keeps alpha **premultiplied between modules**;
+ * `straight` appears only at host boundaries (decode/encode).
+ */
+export type AlphaMode = "premultiplied" | "straight";
+/**
+ * Premul-invariant classification for a module's RGB math.
+ *
+ * - `linear-in-rgb` — the shader's RGB output is a linear function of its RGB
+ *   input (scale, add, lerp, convolution with normalized weights). Safe to
+ *   apply directly to premultiplied input; preserves the rgb ≤ a invariant.
+ * - `nonlinear-in-rgb` — the shader applies a nonlinear function to RGB (pow,
+ *   log, hue rotate, threshold, posterize). MUST unpremultiply before the op
+ *   and re-premultiply after, otherwise output violates rgb ≤ a.
+ * - `alpha-only` — the shader does not read or write RGB (only alpha math,
+ *   RGB output is zero or pass-through).
+ * - `source` — no RGB input (generator); responsibility for premul-valid
+ *   output rests on the source itself.
+ *
+ * This tag is read by the static WGSL validator (load-time) and the runtime
+ * debug pass (per-dispatch).
+ */
+export type LinearityMode = "linear-in-rgb" | "nonlinear-in-rgb" | "alpha-only" | "source";
+/**
+ * How a binding is presented to WGSL. Phase 1 ships `texture_2d`; `texture_external`
+ * (camera/video fast path) arrives with variants in Phase 3. Kept a string
+ * enum until a module needs format/dimension discrimination (deferred).
+ */
+export type BindingKind = "texture_2d" | "texture_external";
+/**
+ * Region-of-definition propagation. Declared by every module from Phase 1;
+ * the Executor does nothing with it until a real consumer (blur, crop,
+ * composite) demands propagation. Declaring it now avoids retrofitting a
+ * 50-module catalog later.
+ */
+export type RodSpec = "same-as:source" | `expand:${string}` | "union-of-inputs" | "explicit";
+/** How an output's dimensions are derived. */
+export type OutputDimensions = `same-as:${string}` | "host-specified" | "derived";
+/** A declared texture input. `"source"` and `"mask"` are reserved names. */
+export interface InputContract {
+    colorSpace: ColorSpaceTag;
+    alpha: AlphaMode;
+    bindingKinds: readonly BindingKind[];
+    /** Optional inputs sample as fully-covered (mask → 1.0) when unbound. */
+    optional?: boolean;
+}
+/** The declared output of a module. */
+export interface OutputContract {
+    colorSpace: ColorSpaceTag;
+    alpha: AlphaMode;
+    format: GPUTextureFormat;
+    dimensions: OutputDimensions;
+}
+/**
+ * I/O contract. The Executor validates bound {@link LabeledTexture}s against
+ * this at encode time; mismatches fail loud or route through a registered
+ * conversion (later phases). Source modules declare `inputs: {}`.
+ */
+export interface IOContract {
+    inputs: Record<string, InputContract>;
+    output: OutputContract;
+    rod: RodSpec;
+}
+/**
+ * Non-semantic UI hint for a param (min/max/step/notes). Carries no runtime
+ * meaning — the TypeGPU schema is the source of truth for layout and type.
+ */
+export interface UiHint {
+    min?: number;
+    max?: number;
+    step?: number;
+    label?: string;
+    notes?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;GAIG;AACH,MAAM,MAAM,cAAc,GACtB,SAAS,GACT,OAAO,GACP,OAAO,GACP,MAAM,GACN,SAAS,GACT,WAAW,GACX,OAAO,GACP,YAAY,GACZ,OAAO,GACP,SAAS,CAAC;AAEd;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,WAAW,CAAC;AAErD;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;AAE5D,4EAA4E;AAC5E,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE9C;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,eAAe,GAAG,UAAU,CAAC;AAErD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,aAAa,GACrB,eAAe,GACf,kBAAkB,GAClB,YAAY,GACZ,QAAQ,CAAC;AAEb;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,kBAAkB,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,MAAM,OAAO,GACf,gBAAgB,GAChB,UAAU,MAAM,EAAE,GAClB,iBAAiB,GACjB,UAAU,CAAC;AAEf,8CAA8C;AAC9C,MAAM,MAAM,gBAAgB,GACxB,WAAW,MAAM,EAAE,GACnB,gBAAgB,GAChB,SAAS,CAAC;AAEd,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,aAAa,CAAC;IAC1B,KAAK,EAAE,SAAS,CAAC;IACjB,YAAY,EAAE,SAAS,WAAW,EAAE,CAAC;IACrC,yEAAyE;IACzE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,uCAAuC;AACvC,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,aAAa,CAAC;IAC1B,KAAK,EAAE,SAAS,CAAC;IACjB,MAAM,EAAE,gBAAgB,CAAC;IACzB,UAAU,EAAE,gBAAgB,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACtC,MAAM,EAAE,cAAc,CAAC;IACvB,GAAG,EAAE,OAAO,CAAC;CACd;AAED;;;GAGG;AACH,MAAM,WAAW,MAAM;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}