nodality 1.0.221 → 1.1.0

package/lib/raster-ops.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.0.221
+ * nodality v1.1.0
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */
@@ -23,11 +23,21 @@
 //     so fidelity is high. Static: recaptured on resize (or via
 //     handle.refresh()). External images / webfonts do not load inside
 //     the SVG image context — system fonts and data: URIs only.
-//   live (opt-in: any raster node carries `live: true`) — the emerging
-//     HTML-in-Canvas API (WICG, Chrome origin trial): the mount subtree
-//     moves inside the effect <canvas layoutsubtree> and is uploaded per
-//     frame with gl.texElementImage2D(), staying interactive and live.
-//     Falls back to snapshot when the API is absent.
+//   live (the DEFAULT where it applies; opt OUT with `live: false` on any
+//     node) — the emerging HTML-in-Canvas API (WICG, Chrome origin trial):
+//     the mount subtree moves inside the effect <canvas layoutsubtree> and
+//     is uploaded per frame with gl.texElementImage2D(), staying
+//     interactive and live. Falls back to snapshot when the API is absent,
+//     and again if no paint event arrives within 1500ms.
+//
+//     "Where it applies" = any chain that is not PURE overlay. A
+//     pure-overlay chain (blobs alone) restructures nothing, so there is
+//     no live subtree to sample and it stays on snapshot. See `wantLive`
+//     in applyRasterPipeline, which is the authority:
+//         !pureOverlay && !nodes.some(n => n.live === false)
+//     (This said "opt-in: any raster node carries `live: true`" until
+//     2026-08-12. It had been the opposite of the code for some time —
+//     `live: true` is not read anywhere.)
 //
 // Safety: this module touches nothing at import time, so it is inert
 // under jsdom prerender (nodality/ssg). applyRasterPipeline() returns
@@ -44,8 +54,30 @@
 // Ops execute in nodes-array order within their stage. Uniforms are
 // namespaced per node index so the same op can appear twice.
 
+// Same "did you mean" matching the element mapper and morph use, so a
+// mistyped stage reads like a mistyped element type. Pure module, no DOM
+// — importing it keeps this file inert at import (phase P1).
+import { didYouMean } from "./suggest.js";
+
 const MAX_BLOBS = 12;
 
+// The unit vocabulary doc.params draws on. Not enforcement — nothing
+// converts by unit — but it is what lets the inspector label a control
+// and pick a sane step, and a closed list means "pixels" vs "px" vs "PX"
+// cannot drift across 15 ops.
+const RASTER_UNITS = [
+    "px",       // a length in CSS pixels; the op scales it by dpr itself
+    "ratio",    // 0..1, or a multiplier — never scaled by dpr
+    "deg",      // degrees, converted to radians at upload
+    "count",    // an integer quantity of things
+    "color",    // "#rrggbb"
+    "name",     // an identifier: a field name, a driver, a blend mode
+    "point",    // [x, y], fractions of the element box
+    "range",    // [lo, hi], a remap
+    "bool",     // present/absent toggle
+    "seconds",  // a duration or a rate per second
+];
+
 // ── Drivers ──────────────────────────────────────────────────────────
 // What steers a reactive op. Previously "react to the pointer" was
 // hardcoded into offset and duotone; a driver makes the input a value in
@@ -78,6 +110,24 @@ const DRIVER_NAMES = Object.keys(DRIVERS);
 
 const REGISTRY = {
     hexalize: {
+        doc: {
+            summary: "Hexagonal cell grid. Snaps sampling to a hex lattice and "
+                + "draws cell borders; with `lift`, cells near the driver swell "
+                + "toward the viewer and their content magnifies to match.",
+            params: {
+                size: { default: 24, unit: "px", summary: "lattice pitch — the width of one cell" },
+                lift: {
+                    default: 0, unit: "ratio", structural: true,
+                    summary: "how much bigger a cell gets at the focus: 0.3 renders the "
+                        + "nearest hexagons at 1.3x. 0 compiles the cheap path entirely away, "
+                        + "so crossing zero rebuilds.",
+                },
+                radius: { default: 200, unit: "px", summary: "falloff distance around the driver focus" },
+            },
+        },
+        // `lift` at 0 compiles the cheap path; non-zero compiles the
+        // seven-neighbour probe. Only crossing zero needs a new shader.
+        structuralOnToggle: ["lift"],
         stage: "cell",
         decl: (p) => `
             uniform float ${p}size;
@@ -181,9 +231,25 @@ ${NB.map(([x, y]) => probe(x, y)).join("")}
             lift: ["1f", node.lift != null ? node.lift : 0],
             radius: ["1f", (node.radius || 200) * dpr],
         }),
+        // Without `lift` the cheap path never writes `warped` — it only
+        // sets center/edge — so the coordinate is unchanged. WITH lift it
+        // probes seven neighbours to find which grown hexagon covers the
+        // fragment, and mirroring that on the CPU would be a second
+        // implementation of the subtlest code here. Returns null instead,
+        // which routes the query to the GPU readback.
+        map: (pt, node) => (node.lift ? null : pt),
     },
 
     offset: {
+        doc: {
+            summary: "Pushes the coordinate space away from the driver focus. Warp "
+                + "stage, so cell grids and borders move WITH the content instead of "
+                + "staying a fixed screen-space lattice.",
+            params: {
+                strength: { default: 20, unit: "px", summary: "how far the space is pushed at full amount" },
+                radius: { default: 260, unit: "px", summary: "falloff distance around the focus" },
+            },
+        },
         // Warp-stage: displaces the coordinate space before the cell
         // grid is computed, so tiles — content AND borders — move
         // together away from the pointer. (The old displace-stage
@@ -206,9 +272,136 @@ ${NB.map(([x, y]) => probe(x, y)).join("")}
             strength: ["1f", (node.strength || 20) * dpr],
             radius: ["1f", (node.radius || 260) * dpr],
         }),
+        // Phase I2. The CPU twin of code() above, so a hit-test costs no
+        // GPU sync. Checked against the readback rather than trusted —
+        // see the property test in raster-probe.spec.js.
+        map: (pt, node, ctx) => {
+            const strength = (node.strength || 20) * ctx.dpr;
+            const radius = (node.radius || 260) * ctx.dpr;
+            const vx = pt[0] - ctx.dpos[0], vy = pt[1] - ctx.dpos[1];
+            const d = Math.hypot(vx, vy);
+            const fall = 1 - smoothstep(0, radius, d);
+            if (!(d > 0.5)) return pt;
+            const k = (strength * fall * ctx.damt) / d;
+            return [pt[0] - vx * k, pt[1] - vy * k];
+        },
+    },
+
+    // Curl-noise flow: the coordinate space drifts along a divergence-free
+    // vector field, so content slides as if carried by a current. Warp
+    // stage, which buys two things for free — it is maskable (STAGE_VARS
+    // snapshots `warped`) and it composes with every cell and colour op,
+    // because those run downstream of it.
+    //
+    //   { op: "flow", strength: 18, scale: 120 }        // whole element
+    //   { op: "flow", by: "mouse", radius: 320 }        // a current at the pointer
+    //   { op: "flow", by: "time", speed: 0.4 }          // hands-free drift
+    //
+    // Divergence-free BY CONSTRUCTION: the field is the curl of a scalar
+    // potential ψ, and curl of a gradient-free scalar has zero divergence.
+    // That is what makes it read as a fluid without a pressure solve —
+    // `stir` pays for a full Stable-Fluids projection to get a field that
+    // also responds to input; this one is free and static-by-seed.
+    //
+    // Without `by:` the current fills the element. With a driver, strength
+    // falls off around the focus (the `duotone`/`halftone` convention), so
+    // the effect resolves away from the pointer instead of being global.
+    flow: {
+        doc: {
+            summary: "Curl-noise current. The coordinate space drifts along a "
+                + "divergence-free field, so content slides as if carried by water. "
+                + "Divergence-free means the flow never piles up or tears.",
+            params: {
+                strength: { default: 18, unit: "px", summary: "how far the current carries the space" },
+                scale: { default: 120, unit: "px", summary: "size of one eddy — small is turbulent, large is a slow drift" },
+                speed: { default: 0.25, unit: "seconds", summary: "how fast the field evolves; 0 freezes it" },
+                seed: { default: 0, unit: "count", summary: "picks a different field of the same character" },
+                radius: {
+                    default: 320, unit: "px",
+                    summary: "falloff around the focus. Only used when `by` names a driver; "
+                        + "without one the current covers the whole element.",
+                },
+            },
+        },
+        structural: ["by"],
+        stage: "warp",
+        decl: (p) => `
+            uniform float ${p}scale;
+            uniform float ${p}strength;
+            uniform float ${p}speed;
+            uniform float ${p}seed;
+            uniform float ${p}radius;
+            uniform vec2 ${p}dpos;
+            uniform float ${p}damt;
+            // Polynomial bit-mixing hash, deliberately NOT the usual
+            // fract(sin(dot(...))). Trig-based hashes disagree across GPU
+            // vendors — sin's precision at large arguments is not
+            // specified — so the same seed would render a different field
+            // on different hardware. This one is multiply/fract only, so
+            // the field is at least stable per-device. (Determinism rule,
+            // MORPH-IMPL-SPEC §2.9.5a.)
+            float ${p}h(vec2 v) {
+                vec3 q = fract(vec3(v.xyx) * 0.1031 + ${p}seed);
+                q += dot(q, q.yzx + 33.33);
+                return fract((q.x + q.y) * q.z);
+            }
+            float ${p}n(vec2 v) {
+                vec2 i = floor(v), f = v - i;
+                f = f * f * (3.0 - 2.0 * f);
+                return mix(mix(${p}h(i), ${p}h(i + vec2(1.0, 0.0)), f.x),
+                           mix(${p}h(i + vec2(0.0, 1.0)), ${p}h(i + vec2(1.0, 1.0)), f.x), f.y);
+            }
+            // The potential. Two octaves: enough structure to read as a
+            // current without the cost of a full fBm.
+            float ${p}psi(vec2 v) {
+                return ${p}n(v) * 0.65 + ${p}n(v * 2.3 + 11.0) * 0.35;
+            }`,
+        code: (p, node) => `
+        {
+            float sc = max(${p}scale, 1.0);
+            vec2 drift = vec2(0.0, u_time * ${p}speed);${node.by ? `
+            float fall = 1.0 - smoothstep(0.0, ${p}radius, length(warped - ${p}dpos));
+            float amt = ${p}strength * fall * ${p}damt;` : `
+            float amt = ${p}strength;`}
+            // Three fixed Euler steps along curl(psi). Fixed count, not
+            // adaptive: the step budget is a compile-time property so the
+            // shader cost cannot vary with the content.
+            for (int i = 0; i < 3; i++) {
+                vec2 q = warped / sc + drift;
+                float e = 0.35;
+                float dy = ${p}psi(q + vec2(0.0, e)) - ${p}psi(q - vec2(0.0, e));
+                float dx = ${p}psi(q + vec2(e, 0.0)) - ${p}psi(q - vec2(e, 0.0));
+                // curl of a 2D scalar potential = (dpsi/dy, -dpsi/dx)
+                warped += vec2(dy, -dx) / (2.0 * e) * amt * 0.3333;
+            }
+        }`,
+        uniforms: (node, dpr) => ({
+            // Feature size of the current, in px. Larger = broader, slower
+            // -turning eddies.
+            scale: ["1f", (node.scale != null ? node.scale : 120) * dpr],
+            // Displacement in px. Scaled by dpr: it is a length.
+            strength: ["1f", (node.strength != null ? node.strength : 18) * dpr],
+            speed: ["1f", node.speed != null ? node.speed : 0.25],
+            // NOT dpr-scaled — it selects a field, it is not a length.
+            seed: ["1f", node.seed != null ? node.seed : 0],
+            radius: ["1f", (node.radius != null ? node.radius : 320) * dpr],
+        }),
     },
 
     duotone: {
+        doc: {
+            summary: "Maps luminance onto a two-colour ramp. With `by`, the mapping "
+                + "is confined to a spot around the driver focus and the rest of the "
+                + "element keeps its own colour.",
+            params: {
+                colors: {
+                    default: ["#104B87", "#E8FF00"], unit: "color",
+                    summary: "[shadow, highlight] — the two ends of the ramp",
+                },
+                radius: { default: 220, unit: "px", summary: "spot size when `by` names a driver" },
+            },
+        },
+        structural: ["by"],
         stage: "color",
         decl: (p) => `uniform vec3 ${p}a; uniform vec3 ${p}b; uniform float ${p}radius;
             uniform vec2 ${p}dpos; uniform float ${p}damt;`,
@@ -239,6 +432,15 @@ ${NB.map(([x, y]) => probe(x, y)).join("")}
     // e.g. { op: "edges", color: "#FFFFFF" } gives white borders under
     // the text. When present it also replaces the default seam darkening.
     edges: {
+        doc: {
+            summary: "Draws the cell borders a cell-stage op produced. On its own it "
+                + "shows nothing — it colours `edge`, which only hexalize (or another "
+                + "cell op) writes.",
+            params: {
+                color: { default: "#FFFFFF", unit: "color", summary: "border colour" },
+                strength: { default: 1.0, unit: "ratio", summary: "border opacity" },
+            },
+        },
         stage: "color",
         decl: (p) => `uniform vec3 ${p}color; uniform float ${p}strength;`,
         code: (p) => `
@@ -285,9 +487,24 @@ ${NB.map(([x, y]) => probe(x, y)).join("")}
     // With a driver the screen coarsens toward the focus, like holding a
     // loupe over the sheet.
     halftone: {
+        doc: {
+            summary: "Print halftone: the image is redrawn as a grid of ink dots on "
+                + "paper, dot size following local luminance.",
+            params: {
+                size: { default: 6, unit: "px", summary: "dot pitch" },
+                angle: { default: 15, unit: "deg", summary: "screen angle of the dot grid" },
+                ink: { default: "#0B1B2B", unit: "color", summary: "dot colour" },
+                paper: { default: "#FFFFFF", unit: "color", summary: "background colour" },
+                softness: { default: 0.08, unit: "ratio", summary: "dot edge softness — 0 is a hard stencil" },
+                amount: { default: 1, unit: "ratio", summary: "blend back toward the un-screened image; 0 is identity. Keyframe it to 0 at both ends of a transition so the shader hands over to the real element without a pop." },
+                radius: { default: 220, unit: "px", summary: "spot size when `by` names a driver" },
+            },
+        },
+        structural: ["by"],
         stage: "color",
         decl: (p) => `
             uniform float ${p}size;
+            uniform float ${p}amount;
             uniform float ${p}angle;
             uniform vec3 ${p}ink;
             uniform vec3 ${p}paper;
@@ -311,10 +528,11 @@ ${NB.map(([x, y]) => probe(x, y)).join("")}
             // sqrt because ink coverage goes as area, not radius.
             float rr = sqrt(clamp(1.0 - lum, 0.0, 1.0)) * 0.55;
             float dm = smoothstep(rr, rr - ${p}soft, length(cell));
-            col = mix(${p}paper, ${p}ink, dm);
+            col = mix(col, mix(${p}paper, ${p}ink, dm), clamp(${p}amount, 0.0, 1.0));
         }`,
         uniforms: (node, dpr) => ({
             size: ["1f", (node.size || 6) * dpr],
+            amount: ["1f", node.amount != null ? node.amount : 1],
             angle: ["1f", ((node.angle != null ? node.angle : 15) * Math.PI) / 180],
             ink: ["3fv", hexToRgb(node.ink || "#0B1B2B")],
             paper: ["3fv", hexToRgb(node.paper || "#FFFFFF")],
@@ -341,6 +559,25 @@ ${NB.map(([x, y]) => probe(x, y)).join("")}
     //
     // `by` coarsens the pattern toward the driver focus, as halftone does.
     dither: {
+        doc: {
+            summary: "Ordered (Bayer) dithering to a small palette — the look of an "
+                + "8-bit display, and the one op that gets sharper as the element gets "
+                + "smaller.",
+            params: {
+                size: { default: 1, unit: "px", summary: "size of one dither cell; 1 is per-pixel" },
+                levels: { default: 6, unit: "count", summary: "quantisation steps per channel" },
+                amount: { default: 1, unit: "ratio", summary: "blend back toward the undithered image" },
+                mono: {
+                    default: false, unit: "bool", structural: true,
+                    summary: "quantise luminance to ink/paper instead of per-channel colour. "
+                        + "A different shader, so toggling rebuilds.",
+                },
+                ink: { default: "#0B1B2B", unit: "color", summary: "dark end, mono only" },
+                paper: { default: "#FFFFFF", unit: "color", summary: "light end, mono only" },
+                radius: { default: 220, unit: "px", summary: "spot size when `by` names a driver" },
+            },
+        },
+        structural: ["by", "mono"],
         stage: "color",
         decl: (p) => `
             uniform float ${p}levels;
@@ -400,6 +637,20 @@ ${NB.map(([x, y]) => probe(x, y)).join("")}
     //   { op: "aberration", amount: 6 }            // radial, lens-like
     //   { op: "aberration", amount: 14, by: "mouse" }  // focused at the pointer
     aberration: {
+        // Displace stage, but it only spreads the per-channel taps
+        // (`chroma`) — the primary sample position is untouched. Declared
+        // so a hit-test can skip it rather than give up on the CPU path;
+        // a unit test checks this against the op's own source.
+        movesCoords: false,
+        doc: {
+            summary: "Chromatic aberration: the three colour channels are sampled "
+                + "at slightly different offsets, like a cheap lens.",
+            params: {
+                amount: { default: 6, unit: "px", summary: "channel separation" },
+                radius: { default: 240, unit: "px", summary: "falloff around the focus when `by` names a driver" },
+            },
+        },
+        structural: ["by"],
         stage: "displace",
         chroma: true,
         decl: (p) => `
@@ -439,6 +690,30 @@ ${NB.map(([x, y]) => probe(x, y)).join("")}
 
     // Geometric / content masks.
     mask: {
+        doc: {
+            summary: "Writes a scalar FIELD for later ops to read — draws nothing "
+                + "itself. Give a downstream op `masked: \"name\"` and it applies only "
+                + "where this field is high. This is how any op becomes local without "
+                + "knowing anything about masking.",
+            params: {
+                as: {
+                    default: "mask", unit: "name", structural: true,
+                    summary: "name of the field written. Consumers name it in `masked:`.",
+                },
+                from: {
+                    default: "radial", unit: "name", structural: true,
+                    summary: "field shape — compiled in, so changing it rebuilds",
+                },
+                at: {
+                    default: [0.5, 0.5], unit: "point", structural: true,
+                    summary: "centre as a fraction of the element box; survives resizes",
+                },
+                radius: { default: 260, unit: "px", summary: "field radius" },
+                invert: { default: false, unit: "bool", summary: "swap inside and outside" },
+                remap: { default: [0, 1], unit: "range", summary: "rescale the field's output range" },
+            },
+        },
+        structural: ["as", "from", "at"],
         stage: "field",
         producesField: true,
         defaultDriver: "static",
@@ -483,6 +758,22 @@ ${NB.map(([x, y]) => probe(x, y)).join("")}
     //   { op: "noise", as: "turbulence", scale: 3, speed: 0.4 },
     //   { op: "offset", masked: "turbulence", strength: 30 },
     noise: {
+        doc: {
+            summary: "Writes an animated noise FIELD. Same contract as `mask` — it "
+                + "draws nothing; downstream ops read it via `masked:`. Use it to make "
+                + "any other op flicker, breathe or crawl.",
+            params: {
+                as: {
+                    default: "mask", unit: "name", structural: true,
+                    summary: "name of the field written",
+                },
+                scale: { default: 3, unit: "ratio", summary: "noise frequency across the element" },
+                speed: { default: 0.3, unit: "seconds", summary: "how fast it evolves; 0 freezes it" },
+                amount: { default: 1, unit: "ratio", summary: "blend between flat 1.0 and full noise" },
+                remap: { default: [0, 1], unit: "range", summary: "rescale the field's output range" },
+            },
+        },
+        structural: ["as"],
         stage: "field",
         producesField: true,
         decl: (p) => `
@@ -535,6 +826,35 @@ ${NB.map(([x, y]) => probe(x, y)).join("")}
     // earlier colour ops, so a copy of a halftoned element is a copy of
     // the unhalftoned source with the screen applied over it.
     copy: {
+        // Phase I4. Draws N stamps of the ORIGINAL texture over the
+        // result, so one screen point genuinely shows several sources and
+        // `sourceAt` can only report the primary sample. There is no
+        // correct single answer here, only a documented one.
+        multiSample: true,
+        doc: {
+            summary: "Stamps extra copies of the element over itself. Copies sample "
+                + "the ORIGINAL texture, not the result of earlier colour ops, so a copy "
+                + "of a halftoned element is a copy of the unhalftoned source.",
+            params: {
+                count: {
+                    default: 5, unit: "count", structural: true,
+                    summary: "stamps arranged in a ring around the focus. The loop is "
+                        + "unrolled at compile time, so this rebuilds — not something to animate.",
+                },
+                points: {
+                    default: null, unit: "point", structural: true,
+                    summary: "explicit [[x,y], ...] in fractions of the element box, instead "
+                        + "of a ring. Survives resizes. Overrides `count`.",
+                },
+                radius: { default: 110, unit: "px", summary: "ring radius when using `count`" },
+                scale: { default: 0.5, unit: "ratio", summary: "size of each copy" },
+                rotate: { default: 0, unit: "deg", summary: "rotation applied per copy" },
+                fade: { default: 1, unit: "ratio", summary: "opacity falloff across the set" },
+                amount: { default: 1, unit: "ratio", summary: "overall blend of the copies over the original" },
+            },
+        },
+        // `count`/`points` unroll the stamp loop at compile time.
+        structural: ["count", "points"],
         stage: "color",
         defaultDriver: "static",
         decl: (p) => `
@@ -605,6 +925,22 @@ ${NB.map(([x, y]) => probe(x, y)).join("")}
     // no extra framebuffer and no second capture of the DOM. It cannot,
     // for the same reason, give the branches different source content.
     merge: {
+        doc: {
+            summary: "Runs two sub-chains over the same source and blends the "
+                + "results. The only op that takes other ops as arguments — everything "
+                + "else composes by sequence, this composes in parallel.",
+            params: {
+                a: { default: null, summary: "first branch: an array of nodes", structural: true },
+                b: { default: null, summary: "second branch: an array of nodes", structural: true },
+                mode: {
+                    default: "over", unit: "name", structural: true,
+                    summary: "how the branches combine: over, add, screen, multiply, "
+                        + "difference, lighten. Compiled in, so it rebuilds.",
+                },
+                mix: { default: 1, unit: "ratio", summary: "how far to blend b into a" },
+            },
+        },
+        structural: ["mode", "a", "b"],
         // Never routed through the normal stage path — emitMerge()
         // handles it — but it still needs decl/uniforms so its `mix`
         // gets declared and uploaded like any other op's.
@@ -632,6 +968,17 @@ ${NB.map(([x, y]) => probe(x, y)).join("")}
     // skeleton composites underneath the content, so the ghosts sit
     // behind the live text rather than veiling it.
     echo: {
+        doc: {
+            summary: "Temporal accumulation — a fading trail of what CHANGED. Typing "
+                + "smears, a ticking counter leaves a comet. The one op that does nothing "
+                + "on the snapshot backend, because a frozen image has no motion to record.",
+            params: {
+                strength: { default: 0.85, unit: "ratio", summary: "opacity of the trail" },
+                decay: { default: 0.92, unit: "ratio", summary: "per-second persistence — higher is a longer tail" },
+                tint: { default: "#7FD4FF", unit: "color", summary: "colour pushed into the trail" },
+                tintAmount: { default: 0.5, unit: "ratio", summary: "how far the trail is tinted" },
+            },
+        },
         stage: "color",
         decl: (p) => `
             uniform sampler2D ${p}hist;
@@ -747,6 +1094,29 @@ void main() {
     // Needs WebGL2 with float render targets; without them the op
     // disables itself and the rest of the chain still renders.
     stir: {
+        doc: {
+            summary: "Stirred liquid: a real fluid simulation the content is dragged "
+                + "through. STATEFUL — it owns a ping-pong pair of render targets that "
+                + "evolve frame to frame, so it is the most expensive op here.",
+            params: {
+                strength: { default: 26, unit: "px", summary: "how far the fluid carries the content" },
+                force: { default: 1.0, unit: "ratio", summary: "how hard the pointer pushes the fluid" },
+                radius: { default: 0.1, unit: "ratio", summary: "splat size, as a fraction of the sim grid" },
+                curl: { default: 2.2, unit: "ratio", summary: "vorticity — how much the fluid curls into eddies" },
+                decay: { default: 0.985, unit: "ratio", summary: "per-second velocity persistence" },
+                pressure: { default: 0.8, unit: "ratio", summary: "pressure retained between frames" },
+                pressureIterations: { default: 6, unit: "count", summary: "solver iterations; higher is stiffer and slower" },
+                intensity: { default: 1.6, unit: "ratio", summary: "brightness of the dye layer" },
+                sheen: { default: 0.15, unit: "ratio", summary: "specular highlight on the surface" },
+                tint: { default: "#7FD4FF", unit: "color", summary: "dye colour, unless `rainbow`" },
+                rainbow: { default: false, unit: "bool", summary: "cycle dye hue instead of using `tint`" },
+                dye: { default: 0.85, unit: "ratio", summary: "how much dye colour reaches the final image" },
+                dyeAmount: { default: 0.6, unit: "ratio", summary: "how much dye each splat injects" },
+                dyeFade: { default: 0.97, unit: "ratio", summary: "per-second dye persistence" },
+                resolution: { default: 128, unit: "count", summary: "velocity grid size, clamped 32..512" },
+                dyeResolution: { default: 512, unit: "count", summary: "dye grid size, clamped 64..1024" },
+            },
+        },
         stage: ["warp", "color"],
         decl: (p) => `
             uniform sampler2D ${p}vel;
@@ -1079,6 +1449,32 @@ void main() {
     // gradient. init()/tick() run the particle sim on the CPU and feed
     // the positions in as a per-frame uniform array.
     blobs: {
+        doc: {
+            summary: "Liquid-glass blobs that follow the pointer: a chain of "
+                + "metaballs refracting the content behind them, stretching apart on a "
+                + "fast flick and relaxing back to a single circle at rest.",
+            params: {
+                count: {
+                    default: 1, unit: "count", structural: true,
+                    summary: "independent drifting blobs, on top of the trail chain",
+                },
+                trail: {
+                    default: 7, unit: "count", structural: true,
+                    summary: "blobs in the follow-the-leader chain. Unrolled at compile "
+                        + "time, so it rebuilds.",
+                },
+                radius: { default: 46, unit: "px", summary: "blob radius at rest" },
+                color: { default: "#EAF4EE", unit: "color", summary: "glass tint" },
+                refract: { default: 70, unit: "px", summary: "how far the glass bends what is behind it" },
+                rim: { default: 0.6, unit: "ratio", summary: "brightness of the rim light" },
+                alpha: { default: 1.0, unit: "ratio", summary: "overall opacity" },
+                iridescence: { default: 0.8, unit: "ratio", summary: "colour shift across the rim" },
+                dispersion: { default: 1.0, unit: "ratio", summary: "per-channel refraction spread" },
+                frost: { default: 0.25, unit: "ratio", summary: "blur of what shows through" },
+            },
+        },
+        // Read by init(), which allocates the particle chain.
+        structural: ["count", "trail"],
         stage: "color",
         overlay: true,
         mips: true,
@@ -1266,15 +1662,18 @@ void main() {
             chain[0].y = state.head.y;
             const follow = 1 - Math.exp(-dt * 16);
             for (let i = 1; i < chain.length; i++) {
-                const lead = chain[i - 1], node = chain[i];
-                let dx = lead.x - node.x, dy = lead.y - node.y;
+                // `b` is a blob in the chain, NOT the raster node — it was
+                // called `node` and shadowed the op's own parameter, which
+                // reads as this op having x/y params it does not have.
+                const lead = chain[i - 1], b = chain[i];
+                let dx = lead.x - b.x, dy = lead.y - b.y;
                 const d = Math.hypot(dx, dy) || 1e-4;
                 // Cap the lag so a fast flick can't tear the tube apart,
                 // then ease the remainder — gives an elastic pull.
                 const maxLag = state.seg;
-                if (d > maxLag) { node.x += dx * (1 - maxLag / d); node.y += dy * (1 - maxLag / d); }
-                node.x += (lead.x - node.x) * follow;
-                node.y += (lead.y - node.y) * follow;
+                if (d > maxLag) { b.x += dx * (1 - maxLag / d); b.y += dy * (1 - maxLag / d); }
+                b.x += (lead.x - b.x) * follow;
+                b.y += (lead.y - b.y) * follow;
             }
 
             // Stretch = how far the tail trails the head, normalised by the
@@ -1320,6 +1719,12 @@ void main() {
     },
 };
 
+// GLSL smoothstep, for the CPU coordinate twins (phase I2).
+function smoothstep(e0, e1, x) {
+    const t = Math.min(1, Math.max(0, (x - e0) / (e1 - e0 || 1e-6)));
+    return t * t * (3 - 2 * t);
+}
+
 function hexToRgb(c) {
     return [1, 3, 5].map((i) => parseInt(c.slice(i, i + 2), 16) / 255);
 }
@@ -1333,11 +1738,258 @@ function hexToRgb(c) {
 // node carries `target:`; the sub-chains inherit whatever it matched.
 const RASTER_OP_NAMES = Object.keys(REGISTRY).concat("switch");
 
+/**
+ * How an op behaves under hit-testing (phase I4).
+ *
+ * DERIVED from what the op already declares rather than hand-listed, so
+ * the taxonomy cannot drift from the contract the way a maintained table
+ * would. The classes, and what each means for `pipeline.sourceAt`:
+ *
+ *   "neutral"     does not move the sampling coordinate, so the browser's
+ *                 own hit-testing was already right (halftone, duotone,
+ *                 and aberration, which spreads only the per-channel taps)
+ *   "analytic"    declares a CPU twin that always answers, so a hit-test
+ *                 costs no GPU sync (offset, and the pixelate example)
+ *   "conditional" declares a twin that answers only for some parameters —
+ *                 hexalize is identity without `lift` and declines with it
+ *   "readback"    moves coordinates with no twin, so every query is an
+ *                 exact GPU round trip (flow, stir)
+ *   "many-to-one" one screen point maps to several sources; sourceAt
+ *                 reports the primary sample (copy)
+ *
+ * @param {string} op
+ * @returns {"neutral"|"analytic"|"conditional"|"readback"|"many-to-one"|"unknown"}
+ */
+function interactionClass(op) {
+    const def = REGISTRY[op];
+    if (!def) return "unknown";
+    if (def.multiSample) return "many-to-one";
+    const stages = Array.isArray(def.stage) ? def.stage : [def.stage];
+    const movesStage = stages.some((s) => s === "warp" || s === "cell" || s === "displace");
+    if (!movesStage || def.movesCoords === false) return "neutral";
+    if (typeof def.map !== "function") return "readback";
+    // A twin that can decline for some parameter values is not the same
+    // promise as one that always answers, and the difference is exactly
+    // what a caller budgeting for GPU syncs needs to know.
+    return /return\s+null|\?\s*null|null\s*:/.test(String(def.map)) ? "conditional" : "analytic";
+}
+
+// ── Phase T1: keyframed params ───────────────────────────────────────
+//
+// A param may be given as an array of numbers, sampled over transition
+// progress `t`:
+//
+//     { op: "flow", strength: [0, 40, 0] }   // in, peak, out
+//
+// The problem this has to solve: plenty of params are LEGITIMATELY
+// arrays. `mask.at` is [x, y], `remap` is [lo, hi], `duotone.colors` is
+// a pair, `copy.points` is a list, `merge.a` is a sub-chain. Guessing
+// from the value alone would break all of them.
+//
+// H4's `doc.params` already carries the answer: a param whose declared
+// unit is a SCALAR quantity, given as two or more numbers, is keyframes.
+// Anything else is data. So this is another property bought by the
+// declaration an op already makes, and an op with no doc never
+// keyframes — which is the safe direction to be wrong in.
+const KEYFRAMABLE_UNITS = ["px", "ratio", "deg", "count", "seconds"];
+
+function isKeyframed(op, key, value) {
+    if (!Array.isArray(value) || value.length < 2) return false;
+    for (const v of value) if (typeof v !== "number" || !Number.isFinite(v)) return false;
+    const def = REGISTRY[op];
+    const meta = def && def.doc && def.doc.params && def.doc.params[key];
+    return !!meta && KEYFRAMABLE_UNITS.includes(meta.unit);
+}
+
+/** Piecewise-linear sample of a keyframe array at t in [0, 1]. */
+function sampleKeyframes(kf, t) {
+    const n = kf.length - 1;
+    const x = Math.min(1, Math.max(0, t)) * n;
+    const i = Math.min(n - 1, Math.floor(x));
+    return kf[i] + (kf[i + 1] - kf[i]) * (x - i);
+}
+
+// ── Phase T3: choreography ───────────────────────────────────────────
+//
+// Two node-level controls, both acting on the LOCAL progress an op's
+// keyframes are sampled against. Neither is a new authoring language —
+// they reshape t, and everything downstream is unchanged.
+//
+//   window: [0.2, 0.8]   this op's keyframes span that slice of t, so
+//                        several ops in one chain can stagger
+//   ease:   "in-out"     easing applied to the local progress
+//
+// Easing lives here rather than in the timeline because a chain wants
+// ops on different curves; the timeline that drives `t` stays linear and
+// therefore still scrubbable and reversible (P-1).
+const EASINGS = {
+    linear: (x) => x,
+    in: (x) => x * x * x,
+    out: (x) => 1 - Math.pow(1 - x, 3),
+    "in-out": (x) => (x < 0.5 ? 4 * x * x * x : 1 - Math.pow(-2 * x + 2, 3) / 2),
+    // Overshoots past 1 and settles — the classic UI "pop". Keyframes are
+    // sampled with clamping, so an overshoot reads as a hold at the end
+    // unless the author gives it somewhere to go.
+    back: (x) => 1 + 2.70158 * Math.pow(x - 1, 3) + 1.70158 * Math.pow(x - 1, 2),
+};
+const EASING_NAMES = Object.keys(EASINGS);
+
+/** An op's own progress: its window, then its easing. */
+function localProgress(node, t) {
+    let x = Math.min(1, Math.max(0, t));
+    const w = node.window;
+    if (Array.isArray(w) && w.length === 2 && w[1] !== w[0]) {
+        x = Math.min(1, Math.max(0, (x - w[0]) / (w[1] - w[0])));
+    }
+    const ease = node.ease && EASINGS[node.ease];
+    return ease ? ease(x) : x;
+}
+
+/**
+ * The node as the op should see it at progress `t` — keyframe arrays
+ * collapsed to scalars, everything else untouched.
+ *
+ * Returns the ORIGINAL object when nothing is keyframed, so the common
+ * case allocates nothing per frame.
+ */
+function resolveNode(node, t) {
+    let out = null;
+    const local = (node.window || node.ease) ? localProgress(node, t) : t;
+    for (const key in node) {
+        if (!isKeyframed(node.op, key, node[key])) continue;
+        out = out || Object.assign({}, node);
+        out[key] = sampleKeyframes(node[key], local);
+    }
+    return out || node;
+}
+
+/** Does this node carry any keyframed param? */
+function hasKeyframes(node) {
+    for (const key in node) if (isKeyframed(node.op, key, node[key])) return true;
+    return false;
+}
+
 // Extension surface — mirrors the CSS-level operation registry:
 // registerRasterOp("pixelate", { stage, decl, code, uniforms }).
+//
+// This used to be two lines that assigned and returned. Every way of
+// getting it wrong therefore succeeded, and surfaced later as a shader
+// that failed to compile with no indication of which op wrote the bad
+// line — or, worse, as an op that compiled and did nothing, because a
+// misspelt `stage` matched no stage and its code was never emitted.
+// That is the silently-ignored-key class again, one level up: not a bad
+// option on a node, but a bad op in the registry.
+//
+// Registration is a one-time cost paid at startup, so it validates
+// eagerly and throws with the vocabulary listed. Everything here is
+// checkable without a GL context, which is why it runs at registration
+// rather than at first compile.
+function validateRasterOp(name, def) {
+    const where = `registerRasterOp("${name}")`;
+    if (typeof name !== "string" || !name.trim()) {
+        throw new TypeError("[nodality] registerRasterOp needs a non-empty name");
+    }
+    if (!def || typeof def !== "object") {
+        throw new TypeError(`[nodality] ${where}: definition must be an object`);
+    }
+
+    // stage — the one field whose typo is invisible at runtime.
+    const stages = Array.isArray(def.stage) ? def.stage : [def.stage];
+    if (def.stage == null || !stages.length) {
+        throw new TypeError(`[nodality] ${where}: missing "stage". ` +
+            `Valid stages: ${RASTER_STAGES.join(", ")}.`);
+    }
+    for (const s of stages) {
+        if (typeof s !== "string" || !RASTER_STAGES.includes(s)) {
+            throw new TypeError(`[nodality] ${where}: ` +
+                didYouMean(s, RASTER_STAGES, "stage"));
+        }
+    }
+
+    // The two functions that produce GLSL, and the optional one that
+    // feeds it. `uniforms` is optional because an op may be entirely
+    // compile-time (see `copy`, which unrolls its loop in code()).
+    for (const k of ["decl", "code"]) {
+        if (typeof def[k] !== "function") {
+            throw new TypeError(`[nodality] ${where}: "${k}" must be a function ` +
+                `(got ${def[k] === undefined ? "nothing" : typeof def[k]}).`);
+        }
+    }
+    if (def.uniforms != null && typeof def.uniforms !== "function") {
+        throw new TypeError(`[nodality] ${where}: "uniforms" must be a function if present.`);
+    }
+    // Phase I2. `map` is the CPU twin of the op's coordinate arithmetic;
+    // `movesCoords: false` says a coordinate-stage op leaves the sampling
+    // position alone (aberration only spreads the per-channel taps). Both
+    // let a hit-test skip the GPU readback, so a wrong shape here would
+    // silently route every query the slow way.
+    if (def.map != null && typeof def.map !== "function") {
+        throw new TypeError(`[nodality] ${where}: "map" must be a function if present.`);
+    }
+    if (def.movesCoords != null && typeof def.movesCoords !== "boolean") {
+        throw new TypeError(`[nodality] ${where}: "movesCoords" must be a boolean if present.`);
+    }
+
+    // Rebuild hints. A name here that is not a real param is not fatal,
+    // but the shape being wrong means isStructuralChange() would throw
+    // mid-drag, so the array-of-strings part is enforced.
+    for (const k of ["structural", "structuralOnToggle"]) {
+        if (def[k] == null) continue;
+        if (!Array.isArray(def[k]) || def[k].some((s) => typeof s !== "string")) {
+            throw new TypeError(`[nodality] ${where}: "${k}" must be an array of param names.`);
+        }
+    }
+
+    if (def.defaultDriver != null && !DRIVER_NAMES.includes(def.defaultDriver)) {
+        throw new TypeError(`[nodality] ${where}: ` +
+            didYouMean(def.defaultDriver, DRIVER_NAMES, "driver"));
+    }
+
+    // `doc` is optional — a third-party op stays registerable without it,
+    // and the inspector falls back to introspection. But a doc that IS
+    // supplied has to be the shape every reader assumes, or the panel
+    // throws while rendering someone else's op.
+    if (def.doc != null) {
+        if (typeof def.doc !== "object") {
+            throw new TypeError(`[nodality] ${where}: "doc" must be an object.`);
+        }
+        if (typeof def.doc.summary !== "string" || !def.doc.summary.trim()) {
+            throw new TypeError(`[nodality] ${where}: "doc.summary" must be a non-empty string.`);
+        }
+        const params = def.doc.params;
+        if (params != null) {
+            if (typeof params !== "object" || Array.isArray(params)) {
+                throw new TypeError(`[nodality] ${where}: "doc.params" must be an object ` +
+                    `keyed by param name.`);
+            }
+            for (const [k, v] of Object.entries(params)) {
+                if (!v || typeof v !== "object" || Array.isArray(v)) {
+                    throw new TypeError(`[nodality] ${where}: doc.params.${k} must be an ` +
+                        `object like { default, unit }.`);
+                }
+                if (v.unit != null && !RASTER_UNITS.includes(v.unit)) {
+                    throw new TypeError(`[nodality] ${where}: doc.params.${k}: ` +
+                        didYouMean(v.unit, RASTER_UNITS, "unit"));
+                }
+            }
+        }
+    }
+    return def;
+}
+
 function registerRasterOp(name, def) {
+    validateRasterOp(name, def);
+    // Replacing a built-in is legitimate — overriding `halftone` with your
+    // own is a reason this surface exists — but doing it by accident,
+    // because two libraries picked the same word, is not. Warn rather than
+    // throw: the caller may well mean it, and there is no way to tell.
+    if (Object.prototype.hasOwnProperty.call(REGISTRY, name) &&
+        typeof console !== "undefined" && console.warn) {
+        console.warn(`[nodality] registerRasterOp("${name}") replaces an existing op.`);
+    }
     REGISTRY[name] = def;
     if (!RASTER_OP_NAMES.includes(name)) RASTER_OP_NAMES.push(name);
+    return def;
 }
 
 function isHTMLInCanvasAvailable() {
@@ -1359,6 +2011,71 @@ const STAGE_VARS = {
     color: ["col", "edgeCol", "edgeCov", "ovCol", "ovA"],
 };
 
+// What `stage:` may say. Derived from STAGE_VARS rather than written out
+// again, so adding a stage cannot leave the validator rejecting it.
+// `field` is the exception that has no stage vars of its own: a field op
+// writes a scalar for later ops to read, it does not modify the frame.
+//
+// Read by validateRasterOp, which is defined above this line but only
+// ever RUNS from registerRasterOp — i.e. after this module has finished
+// evaluating. Nothing registers an op during our own module eval.
+const RASTER_STAGES = ["field", ...Object.keys(STAGE_VARS)];
+
+// Params the PIPELINE reads off every node, whatever the op. An op does
+// not declare these and must not document them — they would be fifteen
+// identical paragraphs that drift apart on the first edit. Defined once
+// here; the inspector merges them in, and API.md documents them once.
+const FRAMEWORK_DOC = {
+    op: { default: null, unit: "name", summary: "which op this node is" },
+    target: {
+        default: null, unit: "name",
+        summary: "element ids this node applies to, e.g. [\"#hero\"]",
+    },
+    side: {
+        default: null, unit: "name", structural: true,
+        summary: "\"old\" or \"new\" — scope this op to ONE half of a morph " +
+            "instead of the blended result, so the outgoing and incoming " +
+            "states can be art-directed differently. Colour-stage ops only: " +
+            "both sides share one sampling coordinate, so a sided warp has " +
+            "no meaning. Ignored outside a transition.",
+    },
+    by: {
+        default: "static", unit: "name", structural: true,
+        summary: `what steers the effect: ${DRIVER_NAMES.join(", ")}. ` +
+            "Compiled in, so changing it rebuilds.",
+    },
+    masked: {
+        default: false, unit: "name",
+        summary: "read a field written upstream — true for the default " +
+            "\"mask\", or a name. Works for ANY op; the op needs no knowledge of it.",
+    },
+    live: {
+        default: true, unit: "bool",
+        summary: "false forces the snapshot backend for this element " +
+            "instead of HTML-in-Canvas capture",
+    },
+    // Phase T3. Both reshape the progress this node's keyframes are
+    // sampled against; neither is read by any op.
+    window: {
+        default: null, unit: "range",
+        summary: "[from, to] slice of transition progress this node's " +
+            "keyframes span — how ops in one chain stagger",
+    },
+    ease: {
+        default: "linear", unit: "name",
+        summary: `easing for this node's local progress: ${EASING_NAMES.join(", ")}`,
+    },
+    interactive: {
+        default: true, unit: "bool",
+        summary: "false opts this pipeline out of pointer retargeting",
+    },
+    hoverAttr: {
+        default: false, unit: "bool",
+        summary: "mirror hover onto [data-nodality-hover] at the DRAWN " +
+            "position; costs the zero-DOM-mutation property, so opt-in",
+    },
+};
+
 // A node opts into a field with `masked: true` (the default field) or
 // `masked: "name"`. Field producers declare `as:` to name what they
 // write. This is the whole of the node-to-node data flow: one op writes
@@ -1484,7 +2201,16 @@ function emitMerge(rec, buckets) {
     }
 }
 
-function buildFragmentShader(recs, flat) {
+/**
+ * @param {boolean} [probe] emit the coordinate-readback variant (phase I1)
+ *        instead of the visible one. Identical up to and including the
+ *        displace stage; then writes the packed source coordinate rather
+ *        than a colour.
+ */
+function buildFragmentShader(recs, flat, probe, transition) {
+    // "opaque" (default) keeps the union solid; "dissolve" is a true
+    // cross-dissolve. See nodBlend.
+    const fade = (transition && transition.fade) || "opaque";
     let decls = "";
 
     // Every field any node writes or reads, declared up front at 1.0 so
@@ -1504,8 +2230,71 @@ function buildFragmentShader(recs, flat) {
         if (def) decls += def.decl(`u${i}_`, node) + "\n";
     });
 
+    // PER-SIDE effects. A node may carry `side: "old" | "new"`, which
+    // scopes it to one half of a morph instead of the blended result.
+    //
+    // Everything else in a transition chain decorates the CROSSFADE — it
+    // runs after old and new have already been mixed, so both ends get
+    // the same treatment. That cannot express "the outgoing state burns
+    // out while the incoming one develops", which is the thing a designer
+    // actually reaches for. A sided op runs on its own side's colour
+    // BEFORE nodBlend sees it.
+    //
+    // Colour stage only, and deliberately: warp/displace ops rewrite the
+    // sampling coordinate, and there is one coordinate shared by both
+    // sides — honouring `side` there would mean two independent
+    // coordinate pipelines. A sided warp is rejected loudly rather than
+    // silently ignored.
+    const sideOf = (rec) => {
+        const v = rec && rec.node && rec.node.side;
+        if (v !== "old" && v !== "new") return null;
+        const def = REGISTRY[rec.node.op];
+        const stages = def ? (Array.isArray(def.stage) ? def.stage : [def.stage]) : [];
+        if (!stages.every((st) => st === "color")) {
+            console.warn(`[nodality] "${rec.node.op}" is a ${stages.join("+")} op, ` +
+                `so side:"${v}" cannot apply to it — a sided op must be colour-only, ` +
+                `because both sides share one sampling coordinate. Running it on ` +
+                `the blended result instead.`);
+            return null;
+        }
+        if (!transition) {
+            console.warn(`[nodality] side:"${v}" has no meaning without a ` +
+                `transition — there is only one image. Ignoring it.`);
+            return null;
+        }
+        return v;
+    };
+    const mainRecs = recs.filter((r) => !sideOf(r));
+    const oldRecs = recs.filter((r) => sideOf(r) === "old");
+    const newRecs = recs.filter((r) => sideOf(r) === "new");
+
     const buckets = emptyBuckets();
-    emitStages(recs, buckets);
+    emitStages(mainRecs, buckets);
+
+    // One scope per side, with the colour stage variables declared local
+    // so an op that touches edgeCol/ovA compiles here exactly as it does
+    // in main(). `frag` is the sample position, which is what a sided op
+    // means by "where am I".
+    const sideBlock = (list, src) => {
+        if (!list.length) return "";
+        const b = emptyBuckets();
+        emitStages(list, b);
+        if (!b.color) return "";
+        const decls = STAGE_VARS.color
+            .filter((v) => v !== "col")
+            .map((v) => `        ${glslType(v)} ${v} = ${glslType(v) === "vec3"
+                ? "vec3(0.0)" : "0.0"};`).join("\n");
+        return `    {
+        vec2 frag = p;
+        vec3 col = ${src}.rgb;
+${decls}
+${b.color}
+        ${src}.rgb = col;
+    }
+`;
+    };
+    const oldSideCode = sideBlock(oldRecs, "o");
+    const newSideCode = sideBlock(newRecs, "n");
     const { field, warp, cell, displace, color } = buckets;
     const nodes = flat;
     // Compositing, in three layers (all straight-alpha):
@@ -1520,19 +2309,161 @@ function buildFragmentShader(recs, flat) {
     // Per-channel resampling costs two extra fetches, so it is only
     // emitted when a displace-stage op actually asks for dispersion.
     const hasChroma = nodes.some((n) => (REGISTRY[n.op] || {}).chroma);
-    const chromaFetch = hasChroma ? `
+    // In transition mode the per-channel taps must see BOTH captures —
+    // sampling u_tex alone would drop the old element out of the red and
+    // blue channels for the whole morph.
+    const chromaFetch = !hasChroma ? "" : (transition ? `
+    vec2 cdev = vec2(chroma.x, chroma.y);
+    col.r = nodSampleAt(sampleP + cdev).r;
+    col.b = nodSampleAt(sampleP - cdev).b;` : `
     vec2 cpx = vec2(chroma.x, -chroma.y) / u_res;
     col.r = texture2D(u_tex, clamp(uv + cpx, 0.001, 0.999)).r;
-    col.b = texture2D(u_tex, clamp(uv - cpx, 0.001, 0.999)).b;` : "";
+    col.b = texture2D(u_tex, clamp(uv - cpx, 0.001, 0.999)).b;`);
+    // Phase I1. The PROBE variant is the same shader with a different last
+    // line: instead of compositing a colour it writes the source
+    // coordinate the fragment sampled from. Everything between `main()`
+    // and the tail is byte-identical to the visible pass, which is the
+    // whole point — a hit-test that recomputed the coordinate its own way
+    // could disagree with what is actually drawn, and that disagreement
+    // would be invisible.
+    //
+    // In probe mode the fragment coordinate is SUPPLIED rather than
+    // derived: `u_probe` names the pixel being asked about, so a 1x1
+    // framebuffer with a plain viewport can stand in for any pixel of the
+    // full-size render. No full-resolution attachment is allocated, and
+    // no negative-origin viewport is needed — an earlier attempt offset
+    // the viewport instead and rasterised nothing, which readback
+    // reported as a confident (0, 0).
+    const probeDecl = probe ? "uniform vec2 u_probe;\n" : "";
+    const fragCoord = probe ? "u_probe + vec2(0.5)" : "gl_FragCoord.xy";
+    // Two bytes per axis: hi in one channel, lo in the next, so a 4000px
+    // element resolves to about 0.06px. Decoded in sourceAt().
+    const probeTail = `
+    vec2 q = clamp(sampleP / u_res, 0.0, 1.0) * 255.0;
+    vec2 hi = floor(q);
+    vec2 lo = floor(fract(q) * 255.0);
+    gl_FragColor = vec4(hi.x, lo.x, hi.y, lo.y) / 255.0;
+}`;
+
     return `
 precision highp float;
 uniform sampler2D u_tex;
 uniform vec2 u_res;
 uniform vec2 u_mouse;
 uniform float u_time;
-${decls}
+uniform float u_t;          // phase T1: transition progress, 0..1
+
+// Op uniforms are declared HERE, above the transition helpers, because a
+// per-side op's code is emitted inside nodSampleAt. GLSL requires
+// declaration before use, and with the declarations further down every
+// sided op failed to compile with "'u0_amount' : undeclared identifier".
+${probeDecl}${decls}
+${transition ? `
+// ── phase T2: transition mode ──────────────────────────────────────
+// Two captures instead of one. u_tex is the NEW element, u_old the
+// frozen OLD one, and u_box is the content box they are both drawn
+// into — lerped from the old rect to the new rect by u_t. So geometry
+// (the box) and pixels (the effect chain) stay separate problems, which
+// is the split View Transitions also makes and the one that keeps this
+// maintainable.
+uniform sampler2D u_old;
+${transition && transition.newImage ? "uniform sampler2D u_newimg;" : ""}
+// Phase T2, gap 2. TWO boxes, not one. With a single shared box the
+// only expressible motion is "both sides march together", so the classic
+// "old slides out while new slides in" was impossible. Each capture now
+// interpolates in its own rect, which keeps per-side motion in the
+// GEOMETRY tier (P-3) instead of needing per-side op scoping.
+uniform vec4 u_boxOld;      // x, y, w, h — device px, top-down
+uniform vec4 u_boxNew;
+
+// sRGB <-> linear. A naive crossfade in gamma space dips visibly in
+// brightness at mid-fade on photographic content; this is the classic
+// artifact and it is why the mix below is not just mix().
+vec3 nodToLinear(vec3 c) { return pow(c, vec3(2.2)); }
+vec3 nodToSRGB(vec3 c)   { return pow(c, vec3(1.0 / 2.2)); }
+
+// Premultiplied, so anti-aliased edges over transparency do not pick up
+// a dark halo as the two sides cross.
+vec4 nodBlend(vec4 a, vec4 b, float t, float d) {
+    vec3 pa = nodToLinear(a.rgb) * a.a;
+    vec3 pb = nodToLinear(b.rgb) * b.a;
+${fade === "morph" ? `
+    // MORPH — a per-pixel CHOICE, not a mix. d is a stable hash of the
+    // output pixel, so each pixel flips from old to new at its own point
+    // in t. At any instant almost every pixel is showing exactly ONE
+    // side, and the two contents are never both legible at once.
+    //
+    // A uniform crossfade cannot do this: at t=0.5 it is by definition
+    // 50% of each, which reads as a double exposure the moment the two
+    // states differ much — a wide nav bar and a small card, say.
+    float k = smoothstep(d - 0.12, d + 0.12, t);
+    vec3 pm = pa * (1.0 - k) + pb * k;
+    float al = a.a * (1.0 - k) + b.a * k;` : fade === "dissolve" ? `
+    // DISSOLVE — a true cross-dissolve: alpha lerps between the two.
+    // Correct, and the right choice when one side really should fade to
+    // nothing. Wrong for a shape morph, because any region covered by
+    // only ONE side is translucent for the whole transition and the
+    // morph reads as "everything is disappearing".
+    vec3 pm = mix(pa, pb, t);
+    float al = mix(a.a, b.a, t);` : `
+    // OPAQUE (default) — the colour crosses over without the shape
+    // thinning out. The coverage-weighted lerp already gives that for
+    // free, and it is worth seeing why:
+    //
+    //   both sides cover   a.a = b.a = 1  ->  w = 1 at every t. Solid
+    //                                         throughout. No mid-fade.
+    //   only the old       b.a = 0        ->  w = 1-t. Releases.
+    //   only the new       a.a = 0        ->  w = t.   Arrives.
+    //
+    // So one expression covers the union case AND each side's release,
+    // linearly, with no curve to pop against.
+    vec3 pm = pa * (1.0 - t) + pb * t;
+    float al = a.a * (1.0 - t) + b.a * t;` }
+    return vec4(nodToSRGB(pm / max(al, 1e-4)), al);
+}
+
+// EVERY fetch in transition mode goes through here. A displace-stage op
+// that sampled u_tex directly — aberration does exactly that for its
+// per-channel taps — would show fringes from the new capture only, with
+// the old one silently absent from those channels.
+// Takes a position in DEVICE PX (sampleP space), not uv, because the two
+// captures no longer share a uv. Each is mapped through its own box and
+// masked to it, then blended.
+vec2 nodBoxUV(vec4 box, vec2 p) {
+    return vec2((p.x - box.x) / max(box.z, 1.0),
+                1.0 - (p.y - box.y) / max(box.w, 1.0));
+}
+float nodInBox(vec2 uv) {
+    return step(0.0, uv.x) * step(uv.x, 1.0) * step(0.0, uv.y) * step(uv.y, 1.0);
+}
+vec4 nodSampleAt(vec2 p) {
+    vec2 uo = nodBoxUV(u_boxOld, p);
+    vec2 un = nodBoxUV(u_boxNew, p);
+    vec4 o = texture2D(u_old, clamp(uo, 0.001, 0.999));
+    // With newImage the new side is a capture of the ELEMENT, so both
+    // sides can travel between their own rects and converge into one
+    // shape. Without it the new side is the HOST capture, which can only
+    // be mapped 1:1 — the destination then sits at its final place from
+    // t=0 while the old shrinks toward it, and the result reads as two
+    // things on screen at once rather than one thing morphing.
+    vec4 n = texture2D(${transition && transition.newImage ? "u_newimg" : "u_tex"},
+                       clamp(un, 0.001, 0.999));
+    o.a *= nodInBox(uo);
+    n.a *= nodInBox(un);
+${oldSideCode}${newSideCode}
+    // The threshold each pixel flips at. Mostly a COHERENT ramp down the
+    // box with a little grain on top — pure white noise chooses correctly
+    // (never two legible images at once) but reads as television static
+    // rather than as one thing becoming another. The ramp makes it a
+    // wipe; the grain keeps the edge from looking like a ruler.
+    float grain = fract(sin(dot(floor(p / 3.0), vec2(12.9898, 78.233))) * 43758.5453);
+    float ramp = clamp(un.y, 0.0, 1.0);
+    float d = ramp * 0.82 + grain * 0.18;
+    return nodBlend(o, n, u_t, d);
+}` : ""}
 void main() {
-    vec2 frag = vec2(gl_FragCoord.x, u_res.y - gl_FragCoord.y);
+    vec2 fc = ${fragCoord};
+    vec2 frag = vec2(fc.x, u_res.y - fc.y);
 ${fieldDecls}
 ${field}
     vec2 warped = frag;
@@ -1542,9 +2473,13 @@ ${warp}
 ${cell}
     vec2 sampleP = warped;
     vec2 chroma = vec2(0.0);
-${displace}
+${displace}${probe ? probeTail : `
+${transition ? `
+    // uv stays defined, as the NEW box's, for ops that reference it.
+    vec2 uv = nodBoxUV(u_boxNew, sampleP);
+    vec4 tex = nodSampleAt(sampleP);` : `
     vec2 uv = vec2(sampleP.x / u_res.x, 1.0 - sampleP.y / u_res.y);
-    vec4 tex = texture2D(u_tex, clamp(uv, 0.001, 0.999));
+    vec4 tex = texture2D(u_tex, clamp(uv, 0.001, 0.999));`}
     vec3 col = tex.rgb;${chromaFetch}
     vec3 edgeCol = vec3(1.0);
     float edgeCov = 0.0;
@@ -1559,7 +2494,7 @@ ${defaultSeam}
     float outA = ovA + baseA * (1.0 - ovA);
     vec3 outRGB = (ovCol * ovA + baseRGB * baseA * (1.0 - ovA)) / max(outA, 1e-4);
     gl_FragColor = vec4(outRGB, outA);
-}`;
+}`}`;
 }
 
 // ── Snapshot backend: DOM subtree -> SVG foreignObject -> texture ────
@@ -1574,19 +2509,97 @@ ${defaultSeam}
 // computes, on a clone, so the snapshot matches the live layout.
 const VIEWPORT_UNIT = /\d(?:vw|vh|vmin|vmax|dvw|dvh|svw|svh|lvw|lvh)\b/i;
 
-function freezeViewportUnits(original, clone) {
+// Inheritable text properties. A foreignObject rendered from a data: URI
+// carries NO page stylesheet, and a clone carries only inline styles — so
+// anything a rule or an ancestor supplied is gone. Nodality's own
+// components style inline and survive; hand-written markup styled by CSS
+// captures as default black serif on transparent, which is what made the
+// demo panels render dark text on a dark panel.
+//
+// Frozen onto the clone only where an element's computed value DIFFERS
+// from its parent's, so inheritance still does the work and the
+// serialized string does not balloon on a large subtree.
+const INHERITED = [
+    "color", "font-family", "font-size", "font-weight", "font-style",
+    "line-height", "letter-spacing", "text-align", "text-transform",
+    "text-decoration-color", "white-space", "word-break",
+];
+
+// Painted, NON-inherited properties — see part 3 of freezeStyles. Layout
+// properties are deliberately absent: freezing width or padding would
+// relayout the clone and move the glyphs off the real text.
+const PAINTED = [
+    "background-color", "background-image", "background-size",
+    "background-position", "background-repeat", "background-clip",
+    "border-radius", "box-shadow", "opacity", "outline-color",
+];
+
+// Initial values, skipped so a page of plain elements does not gain ten
+// no-op declarations per node.
+const PAINT_INITIAL = new Set([
+    "none", "rgba(0, 0, 0, 0)", "transparent", "0px", "auto", "1",
+    "repeat", "0% 0%", "border-box", "0% 0% / auto repeat scroll padding-box border-box",
+]);
+
+function freezeStyles(original, clone) {
     const origs = [original, ...original.querySelectorAll("*")];
     const clones = [clone, ...clone.querySelectorAll("*")];
     for (let i = 0; i < origs.length && i < clones.length; i++) {
         const inline = clones[i].style;
-        if (!inline || inline.length === 0) continue;
-        let computed = null;
-        // Iterate a snapshot of the names: writing to style mutates the list.
-        for (const prop of Array.from(inline)) {
-            if (!VIEWPORT_UNIT.test(inline.getPropertyValue(prop))) continue;
-            computed = computed || window.getComputedStyle(origs[i]);
-            const px = computed.getPropertyValue(prop);
-            if (px) inline.setProperty(prop, px, inline.getPropertyPriority(prop));
+        if (!inline) continue;
+
+        // 1. Viewport units resolve against the SVG's own size inside a
+        //    foreignObject, not the browser viewport, so `calc(1.6rem +
+        //    5vw)` renders at a different size than it does on the page.
+        //    The glyphs then sit somewhere the DOM text does not, which
+        //    is what makes a selection highlight look offset.
+        if (inline.length > 0) {
+            let computed = null;
+            // Iterate a snapshot of the names: writing to style mutates the list.
+            for (const prop of Array.from(inline)) {
+                if (!VIEWPORT_UNIT.test(inline.getPropertyValue(prop))) continue;
+                computed = computed || window.getComputedStyle(origs[i]);
+                const px = computed.getPropertyValue(prop);
+                if (px) inline.setProperty(prop, px, inline.getPropertyPriority(prop));
+            }
+        }
+
+        // 2. Inherited text styling, which the clone would otherwise lose.
+        const cs = window.getComputedStyle(origs[i]);
+        const parent = origs[i].parentElement;
+        const ps = i === 0 || !parent ? null : window.getComputedStyle(parent);
+        for (const prop of INHERITED) {
+            const v = cs.getPropertyValue(prop);
+            if (!v) continue;
+            // The root always states its value — there is no ancestor
+            // inside the foreignObject to inherit from.
+            if (ps && ps.getPropertyValue(prop) === v) continue;
+            if (inline.getPropertyValue(prop)) continue;   // caller was explicit
+            inline.setProperty(prop, v);
+        }
+
+        // 3. Painted, NON-inherited properties. Inheritance cannot rescue
+        //    these: `.card { background: #e8eef5 }` is simply absent from
+        //    the clone, so the element captures fully transparent.
+        //
+        //    The symptom is easy to misread. In a transition the two
+        //    captures crossfade against each other, and with backgrounds
+        //    missing both sides are transparent everywhere except their
+        //    glyphs — so the morph looks like it fades away toward the
+        //    middle and "disappears", when every pixel is exactly where
+        //    it belongs and merely has nothing opaque behind it.
+        //
+        //    Restricted to properties that do not affect LAYOUT. Freezing
+        //    width, padding or border-width would relayout the clone and
+        //    move the glyphs away from where the real text sits — the
+        //    very bug this function was written to prevent.
+        for (const prop of PAINTED) {
+            if (inline.getPropertyValue(prop)) continue;   // caller was explicit
+            const v = cs.getPropertyValue(prop);
+            // Skip initial values, or every node gains a handful of
+            // no-op declarations and the serialized string balloons.
+            if (!v || PAINT_INITIAL.has(v)) continue;
+            inline.setProperty(prop, v);
         }
     }
     return clone;
@@ -1697,7 +2710,7 @@ function snapshotToImage(el, w, h, dpr) {
 
     return new Promise((resolve, reject) => {
         const serialized = new XMLSerializer()
-            .serializeToString(freezeViewportUnits(el, el.cloneNode(true)));
+            .serializeToString(freezeStyles(el, el.cloneNode(true)));
         const svg =
             `<svg xmlns="http://www.w3.org/2000/svg" width="${w * dpr}" height="${h * dpr}" viewBox="0 0 ${w} ${h}">` +
             `<foreignObject width="100%" height="100%">` +
@@ -1826,17 +2839,101 @@ function wrapReplacedHost(el) {
 
 // ── Pipeline runner ──────────────────────────────────────────────────
 
-function applyRasterPipeline(el, rasterNodes) {
+// Fired on `document` whenever a pipeline param changes through setParam,
+// so any UI showing that data — the inspector, a code preview, an editor —
+// stays in step without polling or knowing about the others.
+//   detail: { pipeline, el, index, key, value, prev, how }
+// `how` is "uniform" or "rebuild", the same value setParam returns.
+const RASTER_PARAM_EVENT = "nodality:raster-param";
+
+// ── Live pipelines (phase H3) ────────────────────────────────────────
+// Every attached pipeline, so a dev tool can find what is running without
+// the page having to hand it over. A Set, not a WeakSet: enumerating is
+// the entire point, and destroy() removes deterministically.
+const ACTIVE = new Set();
+
+/** Every raster pipeline currently attached, in attach order. */
+function activeRasterPipelines() {
+    return [...ACTIVE];
+}
+
+// Params that are compiled into the shader rather than uploaded as a
+// uniform, per op. Measured from which of code()/uniforms() reads them —
+// see the table in HOUDINI-DECISIONS. `masked`, `op` and `live` are
+// structural for every op: they change the emitted code or the backend.
+const ALWAYS_STRUCTURAL = ["op", "masked", "live"];
+
+/**
+ * Does changing `key` on an op of this type require a new shader?
+ *
+ * Unknown keys rebuild. That is deliberately the pessimistic default: a
+ * missed structural param renders the wrong thing with no error, while an
+ * unnecessary rebuild only costs a frame.
+ */
+function isStructuralChange(op, key, next, prev) {
+    if (ALWAYS_STRUCTURAL.includes(key)) return true;
+    const def = REGISTRY[op];
+    if (!def) return true;
+    if ((def.structural || []).includes(key)) return true;
+    // A param that only branches the shader when it crosses zero —
+    // hexalize's `lift` picks the cheap path at 0 and the seven-neighbour
+    // probe otherwise, so 0 -> 0.3 needs a rebuild but 0.3 -> 0.5 does not.
+    if ((def.structuralOnToggle || []).includes(key)) return !next !== !prev;
+    // Known uniform? Then it is live.
+    if (def.uniforms) {
+        try { if (key in def.uniforms(Object.assign({ op }, { [key]: next }), 1)) return false; }
+        catch (e) { /* fall through to the pessimistic default */ }
+    }
+    return true;
+}
+
+/**
+ * @param {HTMLElement} el
+ * @param {Array} rasterNodes
+ * @param {object} [opts]
+ * @param {object} [opts.transition] phase T2 — run in transition mode.
+ *   `{ oldImage, oldRect, newRect }` where oldImage is an already
+ *   captured Image/canvas of the OLD element (it has to be captured
+ *   before the DOM swap, because by the time the morph runs that subtree
+ *   is gone), and the rects are CSS px relative to `el`.
+ */
+// One stylesheet for the whole library: while a host's ink is hidden, a
+// selection inside it paints its glyphs in the colour they had before the
+// canvas took over. Unselected text stays transparent (the canvas is
+// drawing it), so what the user sees is exactly the selected run appearing
+// in place — rather than a blank rectangle over an invisible one.
+let selectionStyleAdded = false;
+function ensureSelectionStyle() {
+    if (selectionStyleAdded || typeof document === "undefined") return;
+    selectionStyleAdded = true;
+    const s = document.createElement("style");
+    s.setAttribute("data-nodality", "selection");
+    s.textContent =
+        "[data-nodality-ink]::selection,[data-nodality-ink] *::selection{" +
+        "color:var(--nod-ink);-webkit-text-fill-color:var(--nod-ink)}" +
+        "[data-nodality-ink]::-moz-selection,[data-nodality-ink] *::-moz-selection{" +
+        "color:var(--nod-ink);-webkit-text-fill-color:var(--nod-ink)}";
+    (document.head || document.documentElement).appendChild(s);
+}
+
+function applyRasterPipeline(el, rasterNodes, opts) {
+    // Kept before flattening: rebuild() needs the tree, not the flat list.
+    const sourceNodes = rasterNodes;
+    const transition = (opts && opts.transition) || null;
     // Hard guards — every early-out is silent by design so that jsdom
     // prerender, old browsers and reduced-motion users get the plain
     // page untouched.
     if (!el || typeof document === "undefined" || typeof window === "undefined") return null;
-    if (!rasterNodes || rasterNodes.length === 0) return null;
+    // An empty chain is nothing to do — EXCEPT in transition mode, where
+    // the crossfade between the two captures IS the effect and ops are
+    // only decoration on top of it.
+    if ((!rasterNodes || rasterNodes.length === 0) && !transition) return null;
+    if (!rasterNodes) rasterNodes = [];
     // Flatten any switch nodes down to the chain this device actually
     // gets, before anything reads the list.
     if (rasterNodes.some((n) => n && n.op === "switch")) {
         rasterNodes = resolveSwitches(rasterNodes, 0);
-        if (rasterNodes.length === 0) return null;
+        if (rasterNodes.length === 0 && !transition) return null;
     }
     // Flatten merge sub-chains into the linear list that owns the
     // uniform slots. `tree` keeps the branch structure for the shader
@@ -1888,7 +2985,14 @@ function applyRasterPipeline(el, rasterNodes) {
     const rect = measure();
     if (rect.width < 2 || rect.height < 2) return null;
 
-    const dpr = Math.min(window.devicePixelRatio || 1, 2);
+    // Render resolution. The cap exists because every op runs per output
+    // pixel, so cost is quadratic in it — but capping at 2 also means a 3x
+    // phone or a scaled 4K desktop renders the effect at LOWER density than
+    // the text beside it, and the canvas reads as soft next to real DOM.
+    // Default to the display's own density up to 3, and let a caller that
+    // knows its budget say otherwise.
+    const dpr = Math.max(1, Math.min(
+        opts && opts.resolution ? opts.resolution : (window.devicePixelRatio || 1), 3));
     const isOverlay = rasterNodes.some((n) => (REGISTRY[n.op] || {}).overlay);
     // Stacking: a pipeline may mix in-place ops (hexalize/offset/duotone/
     // edges) with an overlay op (blobs). The single shader composites them
@@ -1896,7 +3000,14 @@ function applyRasterPipeline(el, rasterNodes) {
     // chain leaves the host visible (the lens refracts untouched content).
     // The moment an in-place op joins, the canvas fully carries the look,
     // so the host must be hidden or the original content ghosts through.
-    const pureOverlay = rasterNodes.every((n) => (REGISTRY[n.op] || {}).overlay);
+    // `.every()` on an EMPTY array is vacuously true, which used to be
+    // unreachable — a chain with no ops returned null long before here.
+    // Transition mode made it reachable, and an empty transition chain
+    // was classified a pure overlay: the canvas composited over untouched
+    // DOM instead of replacing it, so the same chain rendered differently
+    // with and without a zero-strength op in it.
+    const pureOverlay = rasterNodes.length > 0 && !transition &&
+        rasterNodes.every((n) => (REGISTRY[n.op] || {}).overlay);
     // Live-first (HTML-in-Canvas). The live backend captures content that
     // lives INSIDE the canvas (texElementImage2D over the restructured
     // subtree) — the same model canvasUI's bubble uses: content in the
@@ -1907,7 +3018,29 @@ function applyRasterPipeline(el, rasterNodes) {
     // subtree to sample; that case stays snapshot). A combined chain
     // (blobs + hexalize/offset/…) hides the host and therefore runs live,
     // lens included. Opt out per pipeline with `live: false` on any node.
-    const wantLive = !pureOverlay && !rasterNodes.some((n) => n.live === false);
+    // A TRANSITION never wants the live backend, and the reason is not a
+    // preference — it is that live costs interactivity and buys nothing
+    // here.
+    //
+    // Buys nothing: a morph samples u_old and u_newimg, two frozen
+    // captures. The live upload of the host is never read (see
+    // nodSampleAt), so restructuring the DOM into the canvas produces a
+    // texture nobody looks at.
+    //
+    // Costs interactivity: the live path MOVES the host's children into
+    // the canvas, where they become canvas fallback content — present in
+    // the accessibility tree but not hit-testable the way ordinary DOM
+    // is. Every control inside the morphed element then stops responding
+    // to the pointer, which is what "the back button is not clickable"
+    // is. It only reproduces on a browser with the HTML-in-Canvas API,
+    // so a snapshot-only run says everything is fine.
+    //
+    // `transition.live: true` overrides this deliberately, for comparing
+    // the two backends side by side. Expect the morph to LOOK the same and
+    // stop responding to the pointer — that is the trade being shown.
+    const forceLive = !!(transition && transition.live === true);
+    const wantLive = !pureOverlay && (!transition || forceLive) &&
+        !rasterNodes.some((n) => n.live === false);
     const apiAvailable =
         (typeof WebGL2RenderingContext !== "undefined" &&
             "texElementImage2D" in WebGL2RenderingContext.prototype) ||
@@ -1948,6 +3081,9 @@ function applyRasterPipeline(el, rasterNodes) {
     canvas.setAttribute("data-nodality-raster", live ? "live" : "snapshot");
     console.info("[nodality] raster backend:", live ? "html-in-canvas (live)" : "snapshot");
 
+    // In live mode the canvas fills the host's CONTENT box, not its border
+    // box (it is a child of the host). Filled in below when live attaches.
+    const liveBox = { width: rect.width, height: rect.height };
     let sourceEl = el; // element uploaded as the texture in live mode
     if (live) {
         // HTML-in-Canvas: the subtree becomes canvas children (wrapped in
@@ -1976,9 +3112,42 @@ function applyRasterPipeline(el, rasterNodes) {
         // mode the children never leave the host.
         const hostCS = getComputedStyle(el);
         const hostIsFlex = hostCS.display === "flex" || hostCS.display === "inline-flex";
+        // GRID too, and for a sharper reason than flex.
+        //
+        // Dropping a flex host's layout misplaced its children; dropping a
+        // GRID host's layout changes the box SIZE. Columns collapse, the
+        // children stack vertically, and they overflow the fixed-height
+        // wrapper — at which point measure()'s scrollHeight fallback (the
+        // host's own rect is collapsed in live mode) starts counting the
+        // overflowing canvas, which is a child of the thing being measured.
+        // Canvas grows -> host grows -> ResizeObserver -> repeat. A
+        // 98px-tall two-column panel reached 4014px before this line.
+        const hostIsGrid = hostCS.display === "grid" || hostCS.display === "inline-grid";
+
+        // The canvas is a CHILD of the host, so it lives in the host's
+        // CONTENT box — but `rect` is the border box. Sizing the canvas to
+        // `rect` therefore overflows by the padding on both axes and makes
+        // the host padding taller than it started, every time. Measure the
+        // content box once, here, and use it for both the canvas and the
+        // subtree; the host keeps its own padding and nothing is applied
+        // twice.
+        const px = (v) => parseFloat(v) || 0;
+        const padX = px(hostCS.paddingLeft) + px(hostCS.paddingRight);
+        const padY = px(hostCS.paddingTop) + px(hostCS.paddingBottom);
+        liveBox.width = Math.max(2, rect.width - padX);
+        liveBox.height = Math.max(2, rect.height - padY);
+
         wrap.style.cssText =
-            `display:${hostIsFlex ? "flex" : "block"};` +
-            `width:${rect.width}px;height:${rect.height}px;`;
+            `display:${hostIsFlex || hostIsGrid ? hostCS.display : "block"};` +
+            `width:${liveBox.width}px;height:${liveBox.height}px;`;
+        if (hostIsGrid) {
+            wrap.style.gridTemplateColumns = hostCS.gridTemplateColumns;
+            wrap.style.gridTemplateRows = hostCS.gridTemplateRows;
+            wrap.style.gridTemplateAreas = hostCS.gridTemplateAreas;
+            wrap.style.gap = hostCS.gap;
+            wrap.style.alignItems = hostCS.alignItems;
+            wrap.style.justifyItems = hostCS.justifyItems;
+        }
         if (hostIsFlex) {
             wrap.style.flexDirection  = hostCS.flexDirection;
             wrap.style.alignItems     = hostCS.alignItems;
@@ -1991,7 +3160,7 @@ function applyRasterPipeline(el, rasterNodes) {
         // The host collapses once its children move into the canvas, so
         // the canvas itself carries the box in normal flow (not overlay).
         canvas.style.cssText =
-            `display:block;width:${rect.width}px;height:${rect.height}px;`;
+            `display:block;width:${liveBox.width}px;height:${liveBox.height}px;`;
     } else {
         // Snapshot mode: purely visual overlay.
         canvas.style.cssText =
@@ -2026,7 +3195,8 @@ function applyRasterPipeline(el, rasterNodes) {
     };
     const prog = gl.createProgram();
     gl.attachShader(prog, compile(gl.VERTEX_SHADER, VS));
-    gl.attachShader(prog, compile(gl.FRAGMENT_SHADER, buildFragmentShader(rasterTree, rasterNodes)));
+    gl.attachShader(prog, compile(gl.FRAGMENT_SHADER,
+        buildFragmentShader(rasterTree, rasterNodes, false, transition)));
     // Pin "a" to location 0 so a field-simulation program (which shares
     // this vertex buffer and attribute array) can be swapped in without
     // respecifying the pointer.
@@ -2046,15 +3216,46 @@ function applyRasterPipeline(el, rasterNodes) {
         else if (kind === "3fv") gl.uniform3fv(loc, value);
     };
 
-    // Static uniforms from the node data.
-    rasterNodes.forEach((node, i) => {
-        const def = REGISTRY[node.op];
-        if (!def || !def.uniforms) return;
-        const us = def.uniforms(node, dpr);
-        for (const key in us) {
-            setUniform(U(`u${i}_${key}`), us[key][0], us[key][1]);
+    // Static uniforms from the node data. Uploaded once per PROGRAM
+    // rather than once per pipeline: phase I1's probe is a second program
+    // running the same chain, and without these its op uniforms would all
+    // read 0 — a `size` of 0 divides to infinity and the whole coordinate
+    // computation becomes NaN, which readback reports as a confident 0.
+    // Phase T1. Transition progress. Static uniforms are resolved AT this
+    // value, so a keyframed param is correct from the first frame rather
+    // than jumping once something scrubs.
+    let progress = 0;
+    const keyframed = rasterNodes
+        .map((node, i) => ({ node, i }))
+        .filter(({ node }) => hasKeyframes(node));
+
+    const applyStaticUniforms = (Uq, only) => {
+        rasterNodes.forEach((node, i) => {
+            if (only && !only.has(i)) return;
+            const def = REGISTRY[node.op];
+            if (!def || !def.uniforms) return;
+            const us = def.uniforms(resolveNode(node, progress), dpr);
+            for (const key in us) {
+                setUniform(Uq(`u${i}_${key}`), us[key][0], us[key][1]);
+            }
+        });
+    };
+    applyStaticUniforms(U);
+
+    // Re-upload only the keyframed nodes. Cheap enough to run per frame
+    // while a transition is scrubbing, and a no-op for every chain that
+    // has no keyframes — which is all of them until someone opts in.
+    const kfIndices = new Set(keyframed.map((k) => k.i));
+    const uploadKeyframes = () => {
+        if (!keyframed.length) return;
+        gl.useProgram(prog);
+        applyStaticUniforms(U, kfIndices);
+        if (probe && !probe.broken) {
+            gl.useProgram(probe.prog);
+            applyStaticUniforms(probe.U, kfIndices);
+            gl.useProgram(prog);
         }
-    });
+    };
 
     // Ops with a CPU simulation (e.g. blobs) get per-frame state and
     // feed dynamic uniforms each draw (see the render loop below).
@@ -2262,6 +3463,52 @@ function applyRasterPipeline(el, rasterNodes) {
     const finishUpload = () => { if (needMips) gl.generateMipmap(gl.TEXTURE_2D); };
 
     let textureReady = false;
+
+    // Phase T2. The frozen capture of the element being transitioned
+    // FROM. Uploaded once — it is a still by definition, which is also
+    // why transitions need no live-capture support and therefore work in
+    // every browser that has WebGL, not just those in the origin trial.
+    let oldTex = null;
+    let newTex = null;
+    // NOTE: the new element's ink is NOT hidden here. An earlier attempt
+    // did it on the next animation frame and raced the capture — the
+    // texture was taken from an already-transparent subtree, so the new
+    // side of every morph was blank. The existing post-capture path
+    // (`if (!pureOverlay) hideHostInk()`) runs at the right moment, and
+    // transition mode is never pureOverlay; setProgress governs it from
+    // then on.
+    if (transition && transition.oldImage) {
+        oldTex = gl.createTexture();
+        gl.bindTexture(gl.TEXTURE_2D, oldTex);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+        try {
+            gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA,
+                gl.UNSIGNED_BYTE, transition.oldImage);
+        } catch (e) {
+            console.warn("[nodality] transition: old capture upload failed:", e);
+            gl.deleteTexture(oldTex);
+            oldTex = null;
+        }
+    }
+    if (transition && transition.newImage) {
+        newTex = gl.createTexture();
+        gl.bindTexture(gl.TEXTURE_2D, newTex);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+        try {
+            gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA,
+                gl.UNSIGNED_BYTE, transition.newImage);
+        } catch (e) {
+            console.warn("[nodality] transition: new capture upload failed:", e);
+            gl.deleteTexture(newTex);
+            newTex = null;
+        }
+    }
     let destroyed = false;
     let mode = live ? "live" : "snapshot";
 
@@ -2305,12 +3552,31 @@ function applyRasterPipeline(el, rasterNodes) {
 
     const hideHostInk = () => {
         if (inkSaved) return;
+        ensureSelectionStyle();
         inkSaved = [];
-        for (const node of [el, ...el.querySelectorAll("*")]) {
-            if (node === canvas || node.tagName === "CANVAS") continue;
-            const saved = { op: node.style.getPropertyValue("opacity") };
+        el.setAttribute("data-nodality-ink", "");
+        const nodes = [el, ...el.querySelectorAll("*")]
+            .filter((n) => n !== canvas && n.tagName !== "CANVAS");
+        // Selection has to stay LEGIBLE while the ink is transparent. The
+        // host is deliberately still selectable (see above), but with
+        // color:transparent a drag paints the selection rectangle over
+        // invisible glyphs — a blank block that hides the effect instead
+        // of highlighting anything. Stash each node's real colour so the
+        // ::selection rule can repaint just the selected run.
+        //
+        // Read EVERY colour before writing ANY, in two passes. Colour is
+        // inherited, so transparentising a parent inside a single loop
+        // makes each later child read back the already-hidden value —
+        // which stores transparent as the "real" colour and restores
+        // nothing.
+        const realInk = nodes.map((n) => getComputedStyle(n).color);
+        for (let i = 0; i < nodes.length; i++) {
+            const node = nodes[i];
+            const saved = { op: node.style.getPropertyValue("opacity"),
+                ink: node.style.getPropertyValue("--nod-ink") };
             for (const p in INK) saved[p] = node.style.getPropertyValue(p);
             inkSaved.push([node, saved]);
+            node.style.setProperty("--nod-ink", realInk[i]);
             for (const p in INK) node.style.setProperty(p, INK[p], "important");
             // Replaced content has no "ink" property to neutralise.
             if (node !== el && node.matches && node.matches(REPLACED)) {
@@ -2325,6 +3591,7 @@ function applyRasterPipeline(el, rasterNodes) {
 
     const showHostInk = () => {
         el.style.visibility = "";
+        el.removeAttribute("data-nodality-ink");
         if (!inkSaved) return;
         for (const [node, saved] of inkSaved) {
             for (const p in INK) {
@@ -2333,12 +3600,76 @@ function applyRasterPipeline(el, rasterNodes) {
             }
             if (saved.op) node.style.setProperty("opacity", saved.op);
             else node.style.removeProperty("opacity");
+            if (saved.ink) node.style.setProperty("--nod-ink", saved.ink);
+            else node.style.removeProperty("--nod-ink");
         }
         inkSaved = null;
         el.style.isolation = "";
         canvas.style.zIndex = "";
     };
 
+    // Phase T2. WHO presents: the canvas while a transition is running,
+    // the real DOM once it completes. They are alternatives, never both.
+    //
+    // This has to be one function called from everywhere, because the
+    // snapshot path hides ink on EVERY capture completion — and a capture
+    // can land long after the transition has finished (a resize, a late
+    // image load, a refresh()). When that happened after t reached 1 the
+    // ink was hidden again while the canvas was already down, and the
+    // element vanished. It only reproduced on a real browser: headless
+    // finishes its single capture before anything can scrub.
+    //
+    // Returns true when it took ownership, so callers know to stand down.
+    // Re-asserted EVERY FRAME rather than only on the events that change
+    // it, because at least three other subsystems write the same state
+    // for their own reasons and the last writer wins:
+    //
+    //   - snapshotCapture() calls showHostInk() before serialising, so
+    //     the capture sees real ink rather than the transparent version;
+    //   - its completion hides the ink again;
+    //   - the live -> snapshot fallback rewrites canvas.style.cssText
+    //     wholesale, discarding `visibility: hidden` along with it.
+    //
+    // Any of those can land after a transition completes and leave the
+    // element hidden behind an already-hidden canvas, which is exactly
+    // the "it disappears at t=1" report. Ordering fixes kept missing a
+    // path; a cheap idempotent re-assert cannot. Two property reads per
+    // frame, and only in transition mode.
+    const syncTransitionView = () => {
+        if (!transition) return false;
+        const done = progress >= 1;
+        // Standing the canvas down at t=1 assumes it OVERLAYS the content,
+        // so hiding it reveals the real element underneath. That is true
+        // of the snapshot backend, but the live backend MOVES the
+        // element's children into the canvas (canvas.appendChild(wrap)) —
+        // there the canvas is where the content lives, and hiding it hides
+        // the very thing being handed over to.
+        //
+        // The test is `sourceEl !== el`, not `mode === "live"`. A live
+        // pipeline only restructures when it actually needs the live
+        // upload; a transition draws from the two frozen captures instead,
+        // so it stays an overlay even on a live-capable browser. Keying
+        // off the mode suppressed ink suppression on every such browser.
+        const hostsContent = sourceEl !== el;
+        // A morph owns the screen strictly BETWEEN its endpoints. At t=1
+        // the new element takes over; opting in with `standDownAtStart`
+        // makes t=0 symmetric, so the OLD element presents there — real,
+        // clickable, selectable — instead of a picture of itself. Opt-in
+        // because the library cannot supply the old element: it belongs to
+        // the caller, who must put it back. Without it, t=0 keeps showing
+        // the old capture, which is the right default for a morph that is
+        // about to run.
+        const atStart = transition.standDownAtStart && progress <= 0;
+        const wantVis = (done || atStart) && !hostsContent ? "hidden" : "visible";
+        if (canvas.style.visibility !== wantVis) canvas.style.visibility = wantVis;
+        if (done) {
+            if (inkSaved) showHostInk();
+        } else if (!inkSaved) {
+            hideHostInk();
+        }
+        return true;
+    };
+
     const snapshotCapture = () => {
         // Overlay + image content: use the image directly as the texture.
         if (isOverlay) {
@@ -2374,8 +3705,12 @@ function applyRasterPipeline(el, rasterNodes) {
                 // A pure-overlay chain leaves the host alone; the lens
                 // floats over untouched content. Otherwise the canvas
                 // carries the look and the host's own ink is suppressed.
-                if (!pureOverlay) hideHostInk();
-                canvas.style.visibility = "visible";
+                // In transition mode progress decides this, not the
+                // capture — see syncTransitionView.
+                if (!syncTransitionView()) {
+                    if (!pureOverlay) hideHostInk();
+                    canvas.style.visibility = "visible";
+                }
             })
             .catch((e) => {
                 showHostInk();
@@ -2519,9 +3854,420 @@ function applyRasterPipeline(el, rasterNodes) {
 
     // Render loop — paused while off-screen.
     let raf = 0;
+    // The last frame's uniform values, so the phase-I1 probe pass can
+    // reproduce that exact frame on the probe program. Null until the
+    // first draw — sourceAt() reports "not ready" rather than guessing.
+    let lastSnap = null;
+
+    /** Write a frame snapshot to whichever program `Uq` resolves against. */
+    const applyUniforms = (Uq, s) => {
+        gl.uniform2f(Uq("u_res"), s.res[0], s.res[1]);
+        gl.uniform2f(Uq("u_mouse"), s.mouse[0], s.mouse[1]);
+        gl.uniform1f(Uq("u_time"), s.time);
+        gl.uniform1f(Uq("u_t"), s.t);
+        for (const d of s.drivers) {
+            gl.uniform2f(Uq(`u${d.i}_dpos`), d.x, d.y);
+            gl.uniform1f(Uq(`u${d.i}_damt`), d.amt);
+        }
+        for (const d of s.dyn) {
+            for (const u of d.ups) setUniform(Uq(`u${d.i}_${u.name}`), u.kind, u.value);
+        }
+        // Content on unit 0, then each solver's named result textures
+        // (velocity, dye, ...) on units above it.
+        gl.activeTexture(gl.TEXTURE0);
+        gl.bindTexture(gl.TEXTURE_2D, tex);
+        gl.uniform1i(Uq("u_tex"), 0);
+        let unit = 1;
+        if (transition && oldTex) {
+            // Phase T2. The frozen old capture, and the box both sides
+            // are drawn into — lerped by progress, in device px.
+            gl.activeTexture(gl.TEXTURE0 + unit);
+            gl.bindTexture(gl.TEXTURE_2D, oldTex);
+            gl.uniform1i(Uq("u_old"), unit);
+            unit++;
+            // Each side interpolates in its own rect. `oldTo` is where
+            // the outgoing element travels to (default: the new rect, so
+            // they converge), `newFrom` where the incoming one starts
+            // from (default: the old rect). Supplying both is how you get
+            // "old exits left while new enters from the right".
+            const t = s.t;
+            const lerpBox = (from, to) => [
+                (from.x + (to.x - from.x) * t) * dpr,
+                (from.y + (to.y - from.y) * t) * dpr,
+                (from.w + (to.w - from.w) * t) * dpr,
+                (from.h + (to.h - from.h) * t) * dpr,
+            ];
+            const oldBox = lerpBox(transition.oldRect,
+                transition.oldTo || transition.newRect);
+            const newBox = lerpBox(transition.newFrom || transition.oldRect,
+                transition.newRect);
+            gl.uniform4f(Uq("u_boxOld"), oldBox[0], oldBox[1], oldBox[2], oldBox[3]);
+            gl.uniform4f(Uq("u_boxNew"), newBox[0], newBox[1], newBox[2], newBox[3]);
+            if (newTex) {
+                gl.activeTexture(gl.TEXTURE0 + unit);
+                gl.bindTexture(gl.TEXTURE_2D, newTex);
+                gl.uniform1i(Uq("u_newimg"), unit);
+                unit++;
+            }
+        }
+        for (const so of solverOps) {
+            const smps = so.def.solver.samplers;
+            for (const key in smps) {
+                gl.activeTexture(gl.TEXTURE0 + unit);
+                gl.bindTexture(gl.TEXTURE_2D, so.targets[smps[key]].a.tex);
+                gl.uniform1i(Uq(`u${so.i}_${key}`), unit);
+                unit++;
+            }
+        }
+        gl.activeTexture(gl.TEXTURE0); // texture uploads assume unit 0
+    };
+
+    // ── Phase I1: coordinate readback ────────────────────────────────
+    //
+    // The overlay canvas is pointer-events:none and the DOM underneath
+    // stays where layout put it, so once a warp displaces content, a link
+    // is clickable where it is NOT drawn. Fixing that needs one fact:
+    // given a screen point, which source pixel is shown there?
+    //
+    // The shader already computes it — output pixel -> sampleP -> fetch.
+    // So rather than reimplement each op's arithmetic on the CPU (which
+    // could silently disagree with what is drawn, and is impossible for
+    // `stir`, a fluid sim with no closed form), run the SAME chain and
+    // read the answer back.
+    //
+    // Cost is one draw of a single fragment plus a 1-pixel readPixels.
+    // Built on first use, so a page that never hit-tests pays nothing.
+    let probe = null;
+    const buildProbe = () => {
+        if (probe) return probe;
+        const p = gl.createProgram();
+        gl.attachShader(p, compile(gl.VERTEX_SHADER, VS));
+        gl.attachShader(p, compile(gl.FRAGMENT_SHADER,
+            buildFragmentShader(rasterTree, rasterNodes, true, transition)));
+        gl.bindAttribLocation(p, 0, "a");
+        gl.linkProgram(p);
+        if (!gl.getProgramParameter(p, gl.LINK_STATUS)) {
+            console.warn("[nodality] probe program failed:", gl.getProgramInfoLog(p));
+            gl.deleteProgram(p);
+            probe = { broken: true };
+            return probe;
+        }
+        // One pixel is the entire render target: the viewport is offset so
+        // that the queried pixel is the only one rasterised.
+        const t = gl.createTexture();
+        gl.bindTexture(gl.TEXTURE_2D, t);
+        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, 1, 1, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+        const fbo = gl.createFramebuffer();
+        gl.bindFramebuffer(gl.FRAMEBUFFER, fbo);
+        gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, t, 0);
+        const st = gl.checkFramebufferStatus(gl.FRAMEBUFFER);
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        if (st !== gl.FRAMEBUFFER_COMPLETE) {
+            console.warn("[nodality] probe framebuffer incomplete:", st);
+            gl.deleteProgram(p); gl.deleteFramebuffer(fbo); gl.deleteTexture(t);
+            probe = { broken: true };
+            return probe;
+        }
+        const cache = {};
+        const Up = (n) => (n in cache ? cache[n] : (cache[n] = gl.getUniformLocation(p, n)));
+        // The chain's static op uniforms, on this program too.
+        gl.useProgram(p);
+        applyStaticUniforms(Up);
+        gl.useProgram(prog);
+        probe = { prog: p, fbo, tex: t, px: new Uint8Array(4), U: Up };
+        return probe;
+    };
+
+    /**
+     * Which source pixel is drawn at this point on screen?
+     *
+     * @param {number} clientX viewport coordinate, as on a PointerEvent
+     * @param {number} clientY
+     * @returns {{x: number, y: number} | null} the point in CLIENT
+     *   coordinates that the content visible at (clientX, clientY) came
+     *   from — feed it straight to document.elementFromPoint(). Null if
+     *   nothing has been drawn yet, the point is outside the canvas, or
+     *   the probe could not be built.
+     *
+     * Caveat, documented rather than hidden: `copy` draws several stamps,
+     * so one screen point genuinely maps to several sources. This returns
+     * the primary sample. Phase I4 classifies that case.
+     */
+    // ── Phase I2: the CPU path ───────────────────────────────────────
+    //
+    // A GPU readback is a pipeline sync, which is fine per click and too
+    // expensive per pointermove. An op may declare `map` — the same
+    // coordinate arithmetic its GLSL does, in JS — and a chain whose
+    // coordinate-moving ops all declare one is answered without touching
+    // the GPU.
+    //
+    // The duplication is safe only because I1 exists to check it: the
+    // property test asserts twin and readback agree across the parameter
+    // space. A twin that drifts from its shader is caught, not trusted.
+    //
+    // Bails to null — meaning "ask the GPU" — for anything it cannot do
+    // faithfully:
+    //   - an op in a coordinate stage with no `map` and no explicit
+    //     `movesCoords: false` (flow, stir)
+    //   - a `map` that declines (hexalize with lift)
+    //   - any MASKED op, because its effect is lerped by a field this
+    //     path does not evaluate
+    const COORD_STAGES = ["warp", "cell", "displace"];
+    const cpuSourceAt = (px, py) => {
+        if (!lastSnap) return null;
+        const byIndex = {};
+        for (const d of lastSnap.drivers) byIndex[d.i] = d;
+        let pt = [px, py];
+        for (const stage of COORD_STAGES) {
+            for (let i = 0; i < rasterNodes.length; i++) {
+                const node = rasterNodes[i];
+                const def = REGISTRY[node.op];
+                if (!def) continue;
+                const stages = Array.isArray(def.stage) ? def.stage : [def.stage];
+                if (!stages.includes(stage)) continue;
+                if (maskedField(node)) return null;
+                if (typeof def.map !== "function") {
+                    if (def.movesCoords === false) continue;
+                    return null;
+                }
+                const d = byIndex[i];
+                const out = def.map(pt, node, {
+                    res: lastSnap.res,
+                    dpr,
+                    dpos: d ? [d.x, d.y] : [lastSnap.res[0] / 2, lastSnap.res[1] / 2],
+                    damt: d ? d.amt : 1,
+                    time: lastSnap.time,
+                    mouse: lastSnap.mouse,
+                });
+                if (!out) return null;
+                pt = out;
+            }
+        }
+        return pt;
+    };
+
+    /**
+     * @param {object} [opts]
+     * @param {boolean} [opts.gpu] force the readback path, skipping any
+     *        declared CPU twin. This is the oracle the twins are checked
+     *        against — a `map` that drifted from its shader would
+     *        otherwise be undetectable, since both paths would be asked
+     *        the same question and only one of them consulted.
+     */
+    const sourceAt = (clientX, clientY, opts) => {
+        if (destroyed || !lastSnap || !textureReady) return null;
+
+        const rect = canvas.getBoundingClientRect();
+        if (rect.width && rect.height && !(opts && opts.gpu)) {
+            // Try the CPU path first — same answer, no pipeline sync.
+            const sxc = canvas.width / rect.width, syc = canvas.height / rect.height;
+            const dx = (clientX - rect.left) * sxc, dy = (clientY - rect.top) * syc;
+            if (dx >= 0 && dy >= 0 && dx < canvas.width && dy < canvas.height) {
+                // The SAME pixel-centre convention the readback uses: floor
+                // to a pixel, then take its centre. Without this the two
+                // paths ask about points up to half a pixel apart, which is
+                // invisible for most ops and enormous for `offset` near its
+                // focus, where dir = (warped - dpos)/d is a singularity.
+                const fx = Math.floor(dx);
+                const fy = Math.floor(canvas.height - dy);
+                const cpu = cpuSourceAt(fx + 0.5, canvas.height - fy - 0.5);
+                if (cpu) {
+                    return {
+                        x: rect.left + Math.min(Math.max(cpu[0], 0), canvas.width) / sxc,
+                        y: rect.top + Math.min(Math.max(cpu[1], 0), canvas.height) / syc,
+                    };
+                }
+            }
+        }
+
+        const pr = buildProbe();
+        if (pr.broken) return null;
+
+        const r = canvas.getBoundingClientRect();
+        if (!r.width || !r.height) return null;
+        // Client -> canvas device pixels. The canvas may be scaled by CSS,
+        // so go through the rect rather than assuming dpr.
+        const sx = canvas.width / r.width, sy = canvas.height / r.height;
+        const px = (clientX - r.left) * sx;
+        const py = (clientY - r.top) * sy;
+        if (px < 0 || py < 0 || px >= canvas.width || py >= canvas.height) return null;
+
+        // gl_FragCoord is bottom-up; `py` is top-down.
+        const fx = Math.floor(px);
+        const fy = Math.floor(canvas.height - py);
+
+        gl.bindFramebuffer(gl.FRAMEBUFFER, pr.fbo);
+        gl.useProgram(pr.prog);
+        // The whole target is one pixel; the shader reads the coordinate
+        // it is standing in for from u_probe rather than gl_FragCoord.
+        gl.viewport(0, 0, 1, 1);
+        gl.uniform2f(pr.U("u_probe"), fx, fy);
+        applyUniforms(pr.U, lastSnap);
+        gl.drawArrays(gl.TRIANGLES, 0, 3);
+        gl.readPixels(0, 0, 1, 1, gl.RGBA, gl.UNSIGNED_BYTE, pr.px);
+
+        // Restore what draw() expects to find.
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        gl.useProgram(prog);
+        gl.viewport(0, 0, canvas.width, canvas.height);
+
+        // Two bytes per axis, as packed in the probe tail.
+        const b = pr.px;
+        const qx = (b[0] + b[1] / 255) / 255;
+        const qy = (b[2] + b[3] / 255) / 255;
+        // Device px (top-down) -> client coordinates.
+        return {
+            x: r.left + (qx * canvas.width) / sx,
+            y: r.top + (qy * canvas.height) / sy,
+        };
+    };
+
+    // ── Phase I3: event retargeting ──────────────────────────────────
+    //
+    // With I1 able to say where a pixel came from, the fix is mechanical:
+    // catch pointer events on the host in the CAPTURE phase (before they
+    // reach the element the browser picked), ask where the content under
+    // the cursor actually lives, and re-dispatch there.
+    //
+    // Honest boundary, stated because it cannot be fixed from here: CSS
+    // `:hover` and `:active` are computed by the browser from the real
+    // pointer position over the real box. A synthetic MouseEvent does not
+    // move them. So JS handlers retarget correctly and CSS pseudo-classes
+    // still follow the undisplaced layout. Retargeting those would mean
+    // moving the DOM, which is the one thing this library promises not to
+    // do. Focus and keyboard were never wrong — they never went through
+    // coordinates.
+    const RETARGET = "__nodalityRetargeted";
+    // Opt out per pipeline, like `live: false`. An effect used as pure
+    // decoration should not pay for a GPU readback per click.
+    const interactive = !rasterNodes.some((n) => n.interactive === false);
+
+    // Phase I3c. CSS :hover is computed by the browser from the real
+    // pointer over the real box, and a synthetic MouseEvent does not move
+    // it — so on a displaced element the wrong thing lights up. It CAN be
+    // mirrored: track the hovered ancestor chain at the SOURCE position
+    // and mark it with an attribute the page can style.
+    //
+    //   { op: "flow", hoverAttr: true }   →  [data-nodality-hover]
+    //
+    // OPT-IN, and this is the reason: writing that attribute is a DOM
+    // mutation, and this library's headline property is that an effect
+    // never touches the host subtree — asserted with a MutationObserver
+    // in the e2e suite. Turning it on trades that property for hover
+    // fidelity, so it must be the page's decision, not a default. Page
+    // authors also have to write `[data-nodality-hover]` rather than
+    // `:hover`, which is a real cost.
+    const HOVER_ATTR = "data-nodality-hover";
+    const hoverMirror = rasterNodes.some((n) => n.hoverAttr === true);
+    let hoverChain = [];
+    const setHoverChain = (target) => {
+        const next = [];
+        for (let n = target; n && n !== el.parentNode; n = n.parentElement) next.push(n);
+        const keep = new Set(next);
+        for (const n of hoverChain) if (!keep.has(n)) n.removeAttribute(HOVER_ATTR);
+        for (const n of next) if (!n.hasAttribute(HOVER_ATTR)) n.setAttribute(HOVER_ATTR, "");
+        hoverChain = next;
+    };
+
+    /** Build an event of the same kind, at corrected coordinates. */
+    const cloneAt = (e, x, y) => {
+        const Ctor = (typeof PointerEvent !== "undefined" && e instanceof PointerEvent)
+            ? PointerEvent
+            : MouseEvent;
+        const ev = new Ctor(e.type, {
+            bubbles: true, cancelable: e.cancelable, composed: true,
+            view: e.view || (typeof window !== "undefined" ? window : null),
+            detail: e.detail,
+            clientX: x, clientY: y,
+            // Keep screen coords consistent with the shift we applied.
+            screenX: e.screenX + (x - e.clientX),
+            screenY: e.screenY + (y - e.clientY),
+            ctrlKey: e.ctrlKey, altKey: e.altKey,
+            shiftKey: e.shiftKey, metaKey: e.metaKey,
+            button: e.button, buttons: e.buttons,
+            relatedTarget: e.relatedTarget,
+            // Ignored by MouseEvent, meaningful for PointerEvent.
+            pointerId: e.pointerId, pointerType: e.pointerType,
+            isPrimary: e.isPrimary, pressure: e.pressure,
+        });
+        ev[RETARGET] = true;
+        return ev;
+    };
+
+    // A GPU readback per pointermove would be one sync per frame. Moves
+    // are throttled to one probe per animation frame; clicks are rare and
+    // always probed. Phase I2 removes the sync for ops that can declare
+    // their coordinate math on the CPU.
+    let lastMoveProbe = 0;
+
+    const onRetarget = (e) => {
+        if (!interactive || destroyed || e[RETARGET]) return;
+        if (e.type === "pointermove" || e.type === "mousemove") {
+            const t = (typeof performance !== "undefined") ? performance.now() : 0;
+            if (t - lastMoveProbe < 12) return;
+            lastMoveProbe = t;
+        }
+        const s = sourceAt(e.clientX, e.clientY);
+        if (!s) return;
+        // Nothing moved here: let the browser's own hit-testing stand.
+        if (Math.abs(s.x - e.clientX) < 0.5 && Math.abs(s.y - e.clientY) < 0.5) return;
+
+        // Returns null when the source lands outside the VIEWPORT — an
+        // element scrolled half off-screen whose displacement pushes the
+        // source past the edge. Declining is the right answer there: the
+        // native hit stands, rather than dispatching somewhere wrong.
+        const target = typeof document.elementFromPoint === "function"
+            ? document.elementFromPoint(s.x, s.y)
+            : null;
+        // Only ever redirect INTO our own subtree. A displacement that
+        // resolves outside the host is a bug or an edge case, and
+        // dispatching into unrelated page content would be worse than
+        // doing nothing.
+        if (!target || target === e.target || !el.contains(target)) return;
+
+        // Hover, if the page opted in. Done for moves as well as clicks,
+        // since that is when hover state changes.
+        if (hoverMirror) setHoverChain(target);
+
+        // Phase I3b. Focus follows the pointer to the element that was
+        // actually clicked. Without this, clicking a displaced link moves
+        // focus to whatever sits under the cursor in the undisplaced
+        // layout — so the picture, the click and the focus ring disagree.
+        // Only on activating events: a pointermove must not steal focus.
+        if (e.type === "pointerdown" || e.type === "mousedown" || e.type === "click") {
+            const focusable = target.closest &&
+                target.closest("a, button, input, select, textarea, [tabindex]");
+            if (focusable && typeof focusable.focus === "function") {
+                focusable.focus({ preventScroll: true });
+            }
+        }
+
+        // Stop the original in the capture phase so the element the
+        // browser picked never sees it, then deliver the corrected one.
+        e.stopPropagation();
+        if (e.cancelable) e.preventDefault();
+        target.dispatchEvent(cloneAt(e, s.x, s.y));
+    };
+
+    const RETARGET_EVENTS = ["pointerdown", "pointerup", "pointermove", "click",
+        "dblclick", "contextmenu", "mousedown", "mouseup"];
+    // Leaving the element must clear the mirrored hover, or it sticks.
+    const onRetargetLeave = () => { if (hoverMirror) setHoverChain(null); };
+    if (interactive) {
+        for (const t of RETARGET_EVENTS) el.addEventListener(t, onRetarget, true);
+        el.addEventListener("pointerleave", onRetargetLeave, true);
+    }
+
     let visible = true;
     const draw = () => {
         if (destroyed) return;
+        // Self-healing: whatever else touched the ink or the canvas since
+        // the last frame, progress is the authority.
+        syncTransitionView();
         if (visible && textureReady) {
             const now = (typeof performance !== "undefined") ? performance.now() : lastFrame + 16;
             const dt = Math.max(0, (now - lastFrame) / 1000);
@@ -2540,10 +4286,20 @@ function applyRasterPipeline(el, rasterNodes) {
             gl.viewport(0, 0, canvas.width, canvas.height);
             gl.clearColor(0, 0, 0, 0);
             gl.clear(gl.COLOR_BUFFER_BIT);
-            gl.uniform2f(U("u_res"), canvas.width, canvas.height);
-            gl.uniform2f(U("u_mouse"), mouse[0], mouse[1]);
-            gl.uniform1f(U("u_time"), now / 1000);
-            // Evaluate each reactive op's driver and upload its focus.
+            // Everything the frame needs, computed ONCE, then written to
+            // a program. Split this way for phase I1: the probe pass has
+            // to reproduce this frame on a different program, and both
+            // the hover easing above and `tick()` below MUTATE — running
+            // them again for a hit-test would advance every animation by
+            // an extra step per pointer event.
+            const snap = {
+                res: [canvas.width, canvas.height],
+                mouse: [mouse[0], mouse[1]],
+                time: now / 1000,
+                t: progress,
+                drivers: [],
+                dyn: [],
+            };
             if (driverNodes.length > 0) {
                 hover += (hoverTarget - hover) * (1 - Math.exp(-dt * 8));
                 const dctx = {
@@ -2553,34 +4309,17 @@ function applyRasterPipeline(el, rasterNodes) {
                 };
                 for (const d of driverNodes) {
                     const v = d.fn(dctx);
-                    gl.uniform2f(U(`u${d.i}_dpos`), v.x, v.y);
-                    gl.uniform1f(U(`u${d.i}_damt`), v.amt);
+                    snap.drivers.push({ i: d.i, x: v.x, y: v.y, amt: v.amt });
                 }
             }
-            // Advance and upload per-frame CPU simulations.
             if (dynamicOps.length > 0) {
                 const ctx = { w: canvas.width, h: canvas.height, mouseX: mouse[0], mouseY: mouse[1], dt: dt, t: now / 1000 };
                 for (const d of dynamicOps) {
-                    const ups = d.def.tick(d.state, ctx);
-                    for (const u of ups) setUniform(U(`u${d.i}_${u.name}`), u.kind, u.value);
-                }
-            }
-            // Content on unit 0, then each solver's named result
-            // textures (velocity, dye, ...) on units above it.
-            gl.activeTexture(gl.TEXTURE0);
-            gl.bindTexture(gl.TEXTURE_2D, tex);
-            gl.uniform1i(U("u_tex"), 0);
-            let unit = 1;
-            for (const s of solverOps) {
-                const smps = s.def.solver.samplers;
-                for (const key in smps) {
-                    gl.activeTexture(gl.TEXTURE0 + unit);
-                    gl.bindTexture(gl.TEXTURE_2D, s.targets[smps[key]].a.tex);
-                    gl.uniform1i(U(`u${s.i}_${key}`), unit);
-                    unit++;
+                    snap.dyn.push({ i: d.i, ups: d.def.tick(d.state, ctx) });
                 }
             }
-            gl.activeTexture(gl.TEXTURE0); // texture uploads assume unit 0
+            lastSnap = snap;
+            applyUniforms(U, snap);
             lastFrame = now;
             gl.drawArrays(gl.TRIANGLES, 0, 3);
         }
@@ -2650,6 +4389,22 @@ function applyRasterPipeline(el, rasterNodes) {
 
     if (typeof ResizeObserver !== "undefined") {
         ro = new ResizeObserver(() => {
+            // SNAPSHOT ONLY. In live mode the host's children have moved
+            // inside the canvas, so the canvas is the host's only in-flow
+            // child and the host's height is padding + canvas + padding.
+            // Measuring the host to size the canvas is therefore circular:
+            // every observation adds the padding back, resizes the canvas,
+            // and re-triggers this observer. A 98px two-column panel walked
+            // to ~4000px on load, growing by its own padding each pass.
+            //
+            // The live path is handled by onWinResize, which measures the
+            // SUBTREE inside the canvas rather than the host — the one
+            // measurement that is not downstream of the value being set.
+            //
+            // Guarded on the current mode rather than by not observing at
+            // all, so a mid-session fallbackToSnapshot re-enables it with
+            // no re-observation.
+            if (mode === "live") return;
             syncCanvasBox();
             clearTimeout(resizeTimer);
             resizeTimer = setTimeout(remeasureAndCapture, 150);
@@ -2709,10 +4464,122 @@ function applyRasterPipeline(el, rasterNodes) {
         }
     }
 
-    return {
+    // A param change is DATA changing, and more than one thing may be
+    // showing that data: the inspector panel, a code preview, a future node
+    // editor. Whoever writes a value cannot know who else is displaying it,
+    // so setParam announces rather than expecting callers to coordinate.
+    //
+    // A DOM CustomEvent rather than a subscriber list: consumers come and
+    // go with the page, listeners unregister themselves, and nothing has to
+    // hold a reference to a pipeline that may be rebuilt out from under it.
+    const announce = (index, key, value, prev, how) => {
+        if (typeof CustomEvent !== "function" || typeof document === "undefined") return;
+        document.dispatchEvent(new CustomEvent(RASTER_PARAM_EVENT, {
+            detail: { pipeline: handle, el, index, key, value, prev, how },
+        }));
+    };
+
+    // ── Live introspection (phase H3) ─────────────────────────────────
+    // A param is LIVE if the op reads it in uniforms() — changing it is a
+    // uniform upload. It is STRUCTURAL if the op reads it in code(),
+    // because that value is compiled into the GLSL and the only way to
+    // change it is to build a new shader. See `structural` on each
+    // registry entry; anything unrecognised rebuilds, which is the safe
+    // direction to be wrong in.
+    const handle = {
         canvas,
+        // The FLATTENED node list — the one that owns the uniform slots,
+        // so index i here is the `u<i>_` prefix in the shader and what an
+        // inspector must show. Nodes nested in a `merge` appear inline.
+        nodes: rasterNodes,
+        get backend() { return mode; },
+
+        // Phase I1. Where the content visible at a screen point came
+        // from, in client coordinates — the input to hit-testing through
+        // a displacement. Defined below, next to the probe program.
+        sourceAt: (clientX, clientY, opts) => sourceAt(clientX, clientY, opts),
+
+        // Phase T1. Transition progress. `t` is an INPUT, not a timer —
+        // a timeline is one driver of it, scroll scrub and a test are
+        // others. Everything downstream is a pure function of it, which
+        // is what makes transitions deterministic to test and
+        // interruptible for free.
+        get progress() { return progress; },
+        setProgress(t) {
+            const next = Math.min(1, Math.max(0, Number(t) || 0));
+            if (next === progress) return progress;
+            progress = next;
+            uploadKeyframes();
+            // Phase T2, gap 1. The real NEW element is still in the tree
+            // under the canvas, so without this it is visible at t=0 —
+            // the morph would show the destination behind its own start
+            // frame. Suppress its ink for the duration and release at
+            // completion, which is also the moment the DOM becomes the
+            // truth again: selection, hover and video resume on the real
+            // element rather than on a picture of it.
+            //
+            // Driven off `progress` rather than a lifecycle callback, so
+            // it stays a pure function of t (P-1) and a scrub backwards
+            // out of 1 re-hides correctly.
+            syncTransitionView();
+            return progress;
+        },
+
+        /**
+         * Change one param of one node, live where possible.
+         * Returns "uniform" | "rebuild" | false (unknown node).
+         */
+        setParam(i, key, value) {
+            const node = rasterNodes[i];
+            if (!node || destroyed) return false;
+            const prev = node[key];
+            node[key] = value;
+
+            if (isStructuralChange(node.op, key, value, prev)) {
+                handle.rebuild();
+                announce(i, key, value, prev, "rebuild");
+                return "rebuild";
+            }
+            const def = REGISTRY[node.op];
+            if (def && def.uniforms) {
+                const us = def.uniforms(node, dpr);
+                gl.useProgram(prog);
+                for (const k in us) setUniform(U(`u${i}_${k}`), us[k][0], us[k][1]);
+                // The phase-I1 probe is a SECOND program running the same
+                // chain, so it needs the new value too. Without this it
+                // keeps answering with the parameters it was built with —
+                // and since the inspector drives setParam on every drag,
+                // hit-testing would silently drift away from the picture
+                // the moment anyone tuned anything.
+                if (probe && !probe.broken) {
+                    gl.useProgram(probe.prog);
+                    for (const k in us) setUniform(probe.U(`u${i}_${k}`), us[k][0], us[k][1]);
+                    gl.useProgram(prog);
+                }
+            }
+            announce(i, key, value, prev, "uniform");
+            return "uniform";
+        },
+
+        /**
+         * Tear down and re-apply from the (mutated) node tree. Needed for
+         * anything baked into the shader. `sourceNodes` is the ORIGINAL
+         * tree, merge sub-chains and all — flattening loses that nesting,
+         * and rebuilding from the flat list would silently promote a
+         * merge branch to a top-level op.
+         */
+        rebuild() {
+            if (destroyed) return null;
+            const host = el;
+            handle.destroy();
+            return applyRasterPipeline(host, sourceNodes);
+        },
+    };
+    ACTIVE.add(handle);
+    return Object.assign(handle, {
         refresh: () => (mode === "live" ? onPaint() : snapshotCapture()),
         destroy() {
+            ACTIVE.delete(handle);
             destroyed = true;
             cancelAnimationFrame(raf);
             clearTimeout(resizeTimer);
@@ -2722,6 +4589,11 @@ function applyRasterPipeline(el, rasterNodes) {
             if (typeof window !== "undefined") window.removeEventListener("resize", onWinResize);
             el.removeEventListener("mousemove", onMove);
             el.removeEventListener("touchmove", onMove);
+            // Phase I3 listeners are registered in the capture phase, so
+            // they must be removed with the same flag or they leak.
+            for (const t of RETARGET_EVENTS) el.removeEventListener(t, onRetarget, true);
+            el.removeEventListener("pointerleave", onRetargetLeave, true);
+            setHoverChain(null);   // never leave the attribute behind
             el.removeEventListener("mouseenter", onEnter);
             el.removeEventListener("mouseleave", onLeave);
             canvas.removeEventListener("paint", onPaint);
@@ -2730,17 +4602,44 @@ function applyRasterPipeline(el, rasterNodes) {
                 for (const n in s.progs) gl.deleteProgram(s.progs[n].prog);
             }
             solverOps.length = 0;
+            // The probe pass owns a program, a 1x1 texture and an FBO —
+            // only allocated if something hit-tested.
+            if (probe && !probe.broken) {
+                gl.deleteProgram(probe.prog);
+                gl.deleteFramebuffer(probe.fbo);
+                gl.deleteTexture(probe.tex);
+            }
+            probe = null;
+            if (oldTex) { gl.deleteTexture(oldTex); oldTex = null; }
+            if (newTex) { gl.deleteTexture(newTex); newTex = null; }
             while (sourceEl !== el && sourceEl.firstChild) el.appendChild(sourceEl.firstChild);
             showHostInk();
             el.style.visibility = "";
             canvas.remove();
         },
-    };
+    });
 }
 
 export {
     applyRasterPipeline, registerRasterOp, RASTER_OP_NAMES,
     isHTMLInCanvasAvailable, DRIVER_NAMES,
+    // Phase H3. The registry is already effectively public — registerRasterOp
+    // mutates it — and a dev tool needs to read an op's stage and params to
+    // show them. `isStructuralChange` is exported so the inspector can label
+    // a control "rebuilds" before the user drags it, rather than after.
+    activeRasterPipelines, isStructuralChange, REGISTRY, RASTER_PARAM_EVENT,
+    // Phase H4. The op contract, as data: the vocabularies a third-party
+    // op is checked against, and the shared params every op inherits from
+    // the pipeline rather than declaring itself.
+    RASTER_STAGES, RASTER_UNITS, FRAMEWORK_DOC, validateRasterOp,
+    // Phase T1. Keyframed params, resolved against the units an op
+    // already declares.
+    isKeyframed, sampleKeyframes, resolveNode,
+    // Phase T3. Choreography: per-node windows and easing over progress.
+    EASINGS, EASING_NAMES, localProgress,
+    // Phase I4. How each op behaves under hit-testing, derived from its
+    // own declarations.
+    interactionClass,
     // Exported so which branch a `switch` takes can be asserted directly
     // rather than inferred from pixels.
     resolveSwitches,