ranger-compiler 3.5.1 → 3.5.2

package/dist/lib/evg/gl/README.md

@@ -0,0 +1,198 @@
+# EVG on the GPU
+
+Running the CSS palette — flex, grid, the stylesheet layer, real TTF metrics
+and kerning — on a GPU, without a browser doing the layout.
+
+```
+npm run evg:displaylist -- page.tsx out.json -css sheet.css -theme editorial
+```
+
+## The seam
+
+`EVGDisplayList` walks a laid-out tree once and emits flat draw commands:
+filled rect, border, image quad, text run, push/pop clip. Absolute pixels,
+colours resolved to 0–255 + alpha, no tree and no units left.
+
+```
+JSX + CSS ──► EVG layout ──► display list ──┬─► WebGL 2      (evg-webgl.js)
+                                            ├─► SVG / DOM    (../html/evg-html.js)
+                                            ├─► SDL2 + GL    (C++ target)
+                                            ├─► PDF, PNG, HTML (existing)
+                                            └─► framebuffer  (v2 game UI)
+```
+
+The SVG backend is the second consumer of this seam and the evidence that the
+seam is one: it is 500 lines, it shares no code with this file, and the two are
+differenced pixel for pixel over the same frames — 0.022% on a sheet built to
+exercise every command kind, 0.000% on every slide of the .pptx deck. See
+[`gallery/pptx/web/html/`](../../../gallery/pptx/web/html/README.md), which is the slide
+editor with this painter swapped out for that one and nothing else changed.
+
+Everything above the seam is the code the PDF is made with. Everything below
+knows only about quads, glyph runs and scissor rectangles.
+
+This matters for more than tidiness: five painters already walk the tree
+themselves, and each decides again what a box means. That is how border-radius
+came to work in PDF and silently not in PNG — one painter read
+`box.borderRadius`, another a stale `el.borderRadius` that nothing wrote. A
+GPU backend should not become a sixth copy of that walk.
+
+## WebGL 2 — working
+
+```
+python3 -m http.server 8000 --directory <repo root>
+# open /lib/evg/gl/demo.html?list=boxmodel.json
+```
+
+One quad per command, drawn instanced. Rounded corners and borders come from a
+signed distance function in the fragment shader, so a rounded rect costs the
+same two triangles as a square one and needs no tessellation:
+
+```glsl
+sdRoundedBox(p, b, r) = length(max(|p| - b + r, 0)) + min(max(qx, qy), 0) - r
+```
+
+Antialiasing is one `fwidth()` smoothstep. It is **clamped** — on a very large
+quad the derivative jumps across the triangle strip's diagonal and drew a
+visible hairline across the page.
+
+Text: the list carries the run, the face and the size, and the position is
+EVG's — measured from the same TTF the PDF is set in, kerning included. Only
+the glyph *images* come from the platform. Here a 2D canvas rasterizes each run
+into an atlas, one slot per run rather than per glyph, which keeps the run
+intact and therefore keeps EVG's kerning exactly.
+
+## Images
+
+`object-fit: cover` is the only fit the raster and PDF targets implement, and
+it is done here the same way they do it — by cropping, not by squashing. The
+crop is a UV rectangle computed from the source and box aspect ratios, so the
+GPU samples only the covered region and the quad stays two triangles. A radius
+on the element clips the photo through the same distance field the rectangles
+use.
+
+A photo needs its own texture bound, which a single instanced draw cannot do,
+so the list is split into **runs**: consecutive quads that share the atlas are
+one draw, and an image breaks the run and is drawn on its own. Runs read the
+same instance buffers offset to their first instance, because WebGL 2 has no
+base-instance parameter. That keeps paint order exactly as the list has it —
+`boxmodel` is one run, `album` is six.
+
+The published gallery copies the referenced photos next to the viewer and
+rewrites the list to point at the copies. Without that the `src` was the path
+the author wrote — relative to the page source — which resolves in the
+repository and nowhere else, so the deployed viewer fetched four 404s and drew
+a page with holes in it. The PDF and PNG targets never hit this: they read the
+file at render time and embed the pixels.
+
+Verified against `showcase/pages/boxmodel.tsx`: 20 commands, 15 rects with
+their radii, one border, 4 text runs, rendering to the same geometry as the
+PDF — and against `album`, whose four photos now draw.
+
+Not done yet: a real clip stack. A single scissor rect is straightforward;
+nested clips need a stack. It is marked in the source.
+
+## SDL2 + OpenGL — the portable half is ready
+
+The display list module compiles to **C++, Rust and Go** as well as ES6, which
+is the whole reason this shape was chosen — the same list can drive WebGL in a
+browser and SDL2 on a Raspberry Pi or a Mac.
+
+What is already in the repo:
+
+- `EVGDisplayList` compiles cleanly to the C++ target (checked).
+- `ranger_games/sprite_char_sdl.rgr` is an existing Ranger → C++ → SDL2
+  front-end with a real window and gamepad, so the platform pattern is
+  established rather than hypothetical.
+- `imaging/raster/RasterText` already rasterizes glyph outlines — including
+  composite glyphs, so `ä`/`ö` work — which is the atlas source on a platform
+  with no canvas.
+
+What is missing is the platform shim: create an SDL2 window with a GL context,
+upload the same vertex data, and use the same shader source. The shaders are
+plain GLSL ES 3.00 and need no change for desktop GL 3.3 beyond the `#version`
+line.
+
+The honest gap: none of that is compiled or run here, because this container
+has neither SDL2 nor a GPU. Treat the C++ compile as evidence that the
+portable half holds, not that the app runs.
+
+## The engine in a Worker
+
+Everything above the seam is pure Ranger, so it can run in a Worker; only the
+painter needs the page. [`evg-engine.js`](evg-engine.js) is the harness —
+`serveEngine` in the worker, `connectEngine` on the page — and what crosses
+back per frame is one of three replies: a new build as `toBinary()`'s typed
+arrays, transferred, and read by [`evg-binary.js`](evg-binary.js) into the
+same commands `evg-list.js` reads off the object; a kept list that only moved,
+as the layers' shifts; or nothing. Input crosses the other way as the calls
+the host already made, batched into the frame request, and the hit test runs
+where the tree is. `gallery/realtrainer/web/main-worker.js` is a host written
+that way; `?engine=worker` on the RealTrainer page runs it, and `rt:frame`
+drives both hosts through one check. `npm run evg:binary:check` holds the two
+readers against each other on real frames. PLAN_NATIVE_HOSTS.md S1.
+
+## Moving the view — [`evg-gestures.js`](evg-gestures.js)
+
+> The gestures move a view; the *view* itself is still baked into the
+> coordinates of every command, so a canvas rebuilds its whole list for every
+> frame of a pan. It does not have to:
+> [`../PLAN_VIEW_TRANSFORM.md`](../PLAN_VIEW_TRANSFORM.md) designs the camera
+> as a uniform beside `uShift`, measured on the canvases in this repository.
+
+
+Every page that draws a scene bigger than its canvas needs the same four
+gestures, and every standalone had written its own: drag to pan, wheel to
+zoom, a press that does not travel is a click — and, missing from all of
+them, two fingers to pinch.
+
+```js
+attachViewGestures(canvas, {
+  view: () => ({ x, y, sc }),      // the pan and scale in force
+  setView: (x, y, sc) => { … },    // schedule this one — it does not paint
+  onTap: (clientX, clientY) => { … },
+});
+```
+
+It never touches the scene: it reads the view the host keeps and hands back
+another, so the host goes on deciding what a view is and when to paint one.
+
+The anchor is what makes a zoom feel like a zoom — the point under the
+cursor, or under the midpoint of two fingers, stays where it is. Keeping the
+scene point `(screen - pan) / scale` where it was gives
+`pan' = screen - (screen - pan) * (scale' / scale)`, which is also what moves
+the picture when the fingers travel: a pinch pans and zooms in one expression
+rather than two that fight.
+
+A trackpad pinch is not a touch — browsers report it as a wheel with `ctrl`
+held, a fraction of a notch at a time, so it gets its own rate or it crawls
+where a wheel flies; Safari's own `gesture*` events are read too. A finger
+lifted out of a pinch leaves the other one panning rather than stopping the
+picture until both are lifted. `npm run evg:gestures:check` drives all of it
+against a canvas that is not one — 19 checks, including the pinch no headless
+driver will send.
+
+## Nobody can read it — so there is a second list
+
+A GPU frame is invisible to a screen reader: NVDA asks the platform for a tree
+of roles and names, and this file produces quads. So the app emits a second list
+beside the display list — `EVGA11yTree`, meaning where this one carries geometry
+— and `evg-a11y.js` mirrors it as real DOM over the canvas, positioned at the
+rectangles that were painted.
+
+```
+GridApp ─┬─ sceneJson()  ─► evg-webgl.js  ─► pixels
+         └─ a11yJson()   ─► evg-a11y.js   ─► DOM ─► VoiceOver / NVDA / Orca
+```
+
+The canvas becomes `aria-hidden`. The sheet is a `role="grid"` that claims all
+ten thousand rows and emits the forty on screen; the caret cell is the one tab
+stop in the application; a dialog is modal and hides the sheet behind it. The
+mirror never tells the app where focus is — the app tells the mirror, or the two
+chase each other.
+
+Checked in a real browser by `npm run datagrid:web:test`, which asks the DOM
+what a reader would be handed. Turn it off with `?a11y=0`.
+
+Design, state and how to try it with VoiceOver:
+[../PLAN_ACCESSIBILITY.md](../PLAN_ACCESSIBILITY.md).

package/dist/lib/evg/gl/a11y-paint-check.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+//
+// The accessibility mirror may not paint.
+//
+//   node lib/evg/gl/a11y-paint-check.mjs
+//
+// The mirror is real DOM over the canvas — that is the whole point of it, and
+// it is why a reader can find a button EVG drew. The canvas underneath has
+// already drawn every one of those nodes, so a mirror node that puts one
+// pixel on the screen is a SECOND COPY OF THE PAGE. And because the mirror is
+// rebuilt on its own schedule rather than once a frame, that copy is at an
+// older scroll offset: two pages superimposed, sliding over each other.
+//
+// `color: transparent` reads as enough and is not. The mirror makes NATIVE
+// controls on purpose — a real <button> and a real <input>, because that is
+// what readers understand and what the text bridge edits in — and a native
+// control on iOS paints through `-webkit-text-fill-color` and
+// `-webkit-appearance`, neither of which `color` reaches.
+//
+// So this is a list, and the list is the point: every way a user agent can
+// decide to draw something has to be turned off by name. It runs without a
+// DOM — `styleBase` only ever writes to `el.style`, so a plain object is a
+// good enough element for the question being asked.
+
+import { styleBase } from "./evg-a11y.js";
+
+const MUST_BE = {
+  background: "transparent",
+  color: "transparent",
+  webkitTextFillColor: "transparent",
+  webkitAppearance: "none",
+  appearance: "none",
+  caretColor: "transparent",
+  textShadow: "none",
+  boxShadow: "none",
+  border: "0",
+  outline: "none",
+  overflow: "hidden",
+  pointerEvents: "none",
+  userSelect: "none",
+  // NOT A PAINTING RULE, and here anyway because it lives in the same style
+  // block and is the same kind of invisible-until-a-phone mistake: iOS Safari
+  // zooms the whole page in when it focuses a text field computing to under
+  // 16px, and the mirror's `<input>` is what a tap on a drawn field focuses.
+  // It was 10px, which is small enough to trigger it and invisible enough
+  // that nothing on a desktop ever said so.
+  fontSize: "16px",
+};
+
+const el = { style: {} };
+styleBase(el);
+
+let failed = 0;
+for (const [prop, want] of Object.entries(MUST_BE)) {
+  const got = el.style[prop];
+  if (got === want) console.log("  PASS " + prop + ": " + want);
+  else {
+    failed += 1;
+    console.log("  FAIL " + prop + " is " + JSON.stringify(got) + ", want " + JSON.stringify(want));
+  }
+}
+
+console.log("");
+if (failed > 0) {
+  console.log(`  ${failed} way(s) the mirror could still paint, or zoom a phone`);
+  process.exit(1);
+}
+console.log(`  ${Object.keys(MUST_BE).length} ways it cannot paint, or make a phone zoom`);
+// The marker `scripts/run-gallery-editor-tests.sh` greps for. The compiler
+// prints `[FAIL]` and still exits 0, so that runner refuses to take a zero
+// exit as a pass — a suite has to SAY it passed.
+console.log("ALL PASS");

package/dist/lib/evg/gl/blur-check.mjs

@@ -0,0 +1,399 @@
+/**
+ * The painter's backdrop blur, checked in a real GPU context against the
+ * browser's own numbers.
+ *
+ *   node lib/evg/gl/blur-check.mjs [--write-png out.png]
+ *
+ * `oracle/css_blur_oracle.mjs` measured what Chrome does with
+ * `backdrop-filter: blur()`. This draws the same picture through the WebGL
+ * painter and reads the same pixels back, so the two can be compared where it
+ * counts — in the framebuffer, not in a comment.
+ *
+ * Three claims, and each one fails differently:
+ *
+ *   THE PROFILE. A hard black/white edge behind a blurred pane. The ramp
+ *   across it is the kernel's step response, and it is compared sample by
+ *   sample against what the browser produced. A true Gaussian instead of the
+ *   three-box approximation is out by up to 14 luminance levels here — small
+ *   enough to look fine and large enough to be the wrong filter.
+ *
+ *   THE EDGE. A flat grey behind the pane must come out flat: same value at
+ *   the pane's border as at its centre. An implementation that blurs only the
+ *   pixels inside the box gets a pale rim, because its samples fall off the
+ *   edge of what it copied. This is the case that catches the mistake nobody
+ *   notices until they put a scrim over a photograph.
+ *
+ *   THE CLIP. Outside a rounded corner, the backdrop is untouched.
+ *
+ * Exit code 0 when every probe is within tolerance.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { requireDom, findChromium, assertDomInstalled } from "../../../gallery/ui/conformance/dom-adapter.mjs";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const ORACLE = JSON.parse(fs.readFileSync(path.join(HERE, "..", "oracle", "css-blur.json"), "utf8"));
+
+const W = 400;
+const H = 200;
+// The same geometry the oracle used: a 400x200 backdrop, a 200x120 pane at
+// (100,40). Same numbers on both sides or the comparison is not one.
+const PANE = { x: 100, y: 40, w: 200, h: 120 };
+
+/** The three scenes, matching the oracle's cases. */
+const SCENES = {
+  // Black left of x=200, white right of it, under a pane that blurs and
+  // paints nothing of its own.
+  edge: (blur) => ({
+    width: W, height: H,
+    cmds: [
+      { k: 0, x: 0, y: 0, w: 200, h: H, c: [0, 0, 0, 1] },
+      { k: 0, x: 200, y: 0, w: 200, h: H, c: [255, 255, 255, 1] },
+      { k: 0, ...PANE, c: [0, 0, 0, 0], bb: blur },
+    ],
+  }),
+  // Flat mid grey everywhere behind.
+  uniform: (blur) => ({
+    width: W, height: H,
+    cmds: [
+      { k: 0, x: 0, y: 0, w: W, h: H, c: [128, 128, 128, 1] },
+      { k: 0, ...PANE, c: [0, 0, 0, 0], bb: blur },
+    ],
+  }),
+  // White page, a black stripe starting EXACTLY at the pane's left edge. This
+  // is the case that decides whether the backdrop is the element's own region
+  // or the page around it, and cases that do not straddle the border cannot
+  // tell — which is how this implementation shipped the wrong rule for an
+  // afternoon and passed every check it had.
+  acrossTheEdge: (blur) => ({
+    width: W, height: H,
+    cmds: [
+      { k: 0, x: 0, y: 0, w: W, h: H, c: [255, 255, 255, 1] },
+      // From x=99, one pixel left of the pane, so this rectangle's own
+      // antialiased edge falls OUTSIDE the region the blur samples. EVG
+      // softens a rectangle's border by about a third of a pixel and a
+      // browser's div does not; with the two edges on top of each other that
+      // seam blurs inward and reads as a bleed this is meant to be measuring.
+      { k: 0, x: 99, y: 0, w: 101, h: H, c: [0, 0, 0, 1] },
+      { k: 0, ...PANE, r: 40, c: [0, 0, 0, 0], bb: blur },
+    ],
+  }),
+  // A hard band across the top of a rounded pane, over white. This is the only
+  // scene where the blur ITSELF can be caught being drawn square: everywhere
+  // else the backdrop near the corner is uniform, and blurred uniform is
+  // uniform, so a square clip and a rounded one are the same picture.
+  banded: (blur) => ({
+    width: W, height: H,
+    cmds: [
+      { k: 0, x: 0, y: 0, w: W, h: H, c: [255, 255, 255, 1] },
+      { k: 0, x: 0, y: 39, w: W, h: 31, c: [0, 0, 0, 1] },
+      { k: 0, ...PANE, r: 40, c: [0, 0, 0, 0], bb: blur },
+    ],
+  }),
+  // A narrow black column down the pane's left side. The banded scene cannot
+  // see a blur drawn square, because near the top-left corner everything in it
+  // is black either way; turning the feature ninety degrees means the raw
+  // backdrop outside the corner is black while the blurred one is nearly
+  // white, and the two cannot be confused.
+  verticalColumn: (blur) => ({
+    width: W, height: H,
+    cmds: [
+      { k: 0, x: 0, y: 0, w: W, h: H, c: [255, 255, 255, 1] },
+      { k: 0, x: 95, y: 0, w: 14, h: H, c: [0, 0, 0, 1] },
+      { k: 0, ...PANE, r: 40, c: [0, 0, 0, 0], bb: blur },
+    ],
+  }),
+  // The same column, moved fifty pixels clear of the nearest border. Two edges
+  // close together is the case a kernel is easiest to get wrong on, and with
+  // no border within reach it is the kernel alone being compared.
+  innerColumn: (blur) => ({
+    width: W, height: H,
+    cmds: [
+      { k: 0, x: 0, y: 0, w: W, h: H, c: [255, 255, 255, 1] },
+      { k: 0, x: 150, y: 0, w: 14, h: H, c: [0, 0, 0, 1] },
+      { k: 0, ...PANE, c: [0, 0, 0, 0], bb: blur },
+    ],
+  }),
+  // The same small pane, alone and after a bigger one — the pair for case 6.
+  //
+  // The painter keeps its blur targets between draws and grows them without
+  // shrinking, so a second, smaller pane reads out of a texture larger than
+  // its own region, with whatever the first pane left in the rest of it right
+  // there to be sampled. Every other scene here renders one pane into a fresh
+  // context and cannot see that.
+  //
+  // The two panes must NOT overlap. The first version put a big pane over the
+  // same band and compared the result with the small pane alone, and the
+  // difference it found — 12 against 189 — was not a bug at all: the big pane
+  // had already softened that backdrop, so the small one was blurring an
+  // already-blurred band. Correct behaviour, wrong reference.
+  smallAlone: (blur) => ({
+    width: W, height: H,
+    cmds: [
+      { k: 0, x: 0, y: 0, w: W, h: H, c: [255, 255, 255, 1] },
+      { k: 0, x: 0, y: 39, w: W, h: 31, c: [0, 0, 0, 1] },
+      { k: 0, x: 200, y: 30, w: 150, h: 120, c: [0, 0, 0, 0], bb: blur },
+    ],
+  }),
+  smallAfterBig: (blur) => ({
+    width: W, height: H,
+    cmds: [
+      { k: 0, x: 0, y: 0, w: W, h: H, c: [255, 255, 255, 1] },
+      { k: 0, x: 0, y: 39, w: W, h: 31, c: [0, 0, 0, 1] },
+      // Its own dark patch, well clear of the small pane, so anything left
+      // behind in the reused texture is distinctive rather than the same white
+      // the small pane would see anyway.
+      { k: 0, x: 10, y: 100, w: 170, h: 80, c: [20, 20, 20, 1] },
+      // 180 wide by 90 tall: wider than the small pane and shorter, so the
+      // shared texture ends up bigger than the small pane's region on one axis
+      // and the leftovers are inside it.
+      { k: 0, x: 5, y: 95, w: 180, h: 90, c: [0, 0, 0, 0], bb: blur },
+      { k: 0, x: 200, y: 30, w: 150, h: 120, c: [0, 0, 0, 0], bb: blur },
+    ],
+  }),
+  // A rounded pane with a translucent white fill over black.
+  rounded: (blur) => ({
+    width: W, height: H,
+    cmds: [
+      { k: 0, x: 0, y: 0, w: W, h: H, c: [0, 0, 0, 1] },
+      { k: 0, ...PANE, r: 40, c: [255, 255, 255, 0.85], bb: blur },
+    ],
+  }),
+};
+
+const painter = fs.readFileSync(path.join(HERE, "evg-webgl.js"), "utf8").replace(/^export /gm, "");
+
+const pageFor = (scene) => `<!doctype html><meta charset="utf-8"><body style="margin:0;background:#fff">
+<canvas id="c" width="${W}" height="${H}" style="width:${W}px;height:${H}px"></canvas>
+<script>
+${painter}
+(async () => {
+  try {
+    const c = document.getElementById("c");
+    const gl = c.getContext("webgl2", { antialias: true, preserveDrawingBuffer: true });
+    const doc = ${JSON.stringify(scene)};
+    window.__stats = renderDisplayList(gl, { list: { cmds: doc.cmds }, width: doc.width, height: doc.height }, { dpr: 1 });
+  } catch (e) { window.__ERR__ = String(e && e.stack || e); }
+  window.__DONE__ = true;
+})();
+</script></body>`;
+
+assertDomInstalled();
+const { chromium } = requireDom("playwright-core");
+// SwiftShader, for the same reason the rotation check uses it: a check that
+// only runs on a machine with a GPU is not a check.
+const browser = await chromium.launch({
+  executablePath: findChromium(),
+  args: ["--use-gl=swiftshader", "--enable-unsafe-swiftshader"],
+});
+const page = await browser.newPage({ viewport: { width: W + 40, height: H + 40 } });
+const pageErrors = [];
+page.on("pageerror", (e) => pageErrors.push(String(e.message)));
+
+const tmp = path.join(HERE, ".blur-check.html");
+
+/** Render one scene and hand back a row of RGBA readings. */
+async function rowOf(scene, y, xs) {
+  fs.writeFileSync(tmp, pageFor(scene));
+  await page.goto(pathToFileURL(tmp).href);
+  await page.waitForFunction("window.__DONE__ === true", { timeout: 30000 });
+  const err = await page.evaluate(() => window.__ERR__ || null);
+  if (err) throw new Error("painter threw: " + err);
+  const write = process.argv.indexOf("--write-png");
+  if (write > -1 && process.argv[write + 1]) {
+    await page.locator("#c").screenshot({ path: process.argv[write + 1] });
+  }
+  return page.evaluate(([yy, xxs, hh]) => {
+    const gl = document.getElementById("c").getContext("webgl2");
+    const px = new Uint8Array(4);
+    return xxs.map((x) => {
+      // GL reads from the bottom; the display list counts from the top.
+      gl.readPixels(x, hh - 1 - yy, 1, 1, gl.RGBA, gl.UNSIGNED_BYTE, px);
+      return [px[0], px[1], px[2], px[3]];
+    });
+  }, [y, xs, H]);
+}
+
+const lum = (p) => Math.round(0.2126 * p[0] + 0.7152 * p[1] + 0.0722 * p[2]);
+let bad = 0, checked = 0;
+const say = (ok, name, detail) => {
+  checked++;
+  if (ok) { console.log("  PASS " + name); return; }
+  bad++;
+  console.log("  FAIL " + name + "\n        " + detail);
+};
+
+console.log("=== the painter's backdrop blur, against the browser's own numbers ===");
+
+// --- 1. the profile, at each radius the oracle measured ---------------------
+// Tolerance of 6 luminance levels out of 255. Wide enough for SwiftShader's
+// rounding and a slightly different sample grid; far tighter than the 14 that
+// separates the three-box kernel from a true Gaussian, which is the mistake
+// this is here to catch.
+const TOL = 6;
+console.log("");
+console.log("-- the ramp across a hard edge");
+for (const [label, v] of Object.entries(ORACLE.stepResponse)) {
+  const r = parseInt(label.match(/\d+/)[0], 10);
+  // Sample inside the pane only: the pane spans x 100..300 and the edge is at
+  // x=200, so +-40 is comfortably inside it.
+  const xs = [];
+  for (let x = v.xFrom; x < v.xTo; x++) xs.push(200 + x);
+  const row = await rowOf(SCENES.edge(r), 100, xs);
+  let worst = 0, worstAt = 0;
+  for (let i = 0; i < xs.length; i++) {
+    const d = Math.abs(lum(row[i]) - v.luma[i]);
+    if (d > worst) { worst = d; worstAt = v.xFrom + i; }
+  }
+  say(worst <= TOL, `${label}: the ramp matches the browser's (worst ${worst})`,
+    `worst error ${worst} luminance levels at x=${worstAt}, tolerance ${TOL}`);
+}
+
+// --- 2. the element's own edge over a flat backdrop --------------------------
+console.log("");
+console.log("-- a flat backdrop stays flat to the pane's edge");
+{
+  const want = ORACLE.uniformBackdrop.centre;
+  const xs = ORACLE.uniformBackdrop.insideLeft.map((s) => 100 + s.dx);
+  const row = await rowOf(SCENES.uniform(12), 100, xs);
+  const got = row.map(lum);
+  const worst = Math.max(...got.map((g) => Math.abs(g - want)));
+  say(worst <= TOL, `no rim at the edge (worst ${worst})`,
+    `wanted ${want} everywhere, got ${got.join(" ")} — a ramp here means the ` +
+    `blur sampled only inside the box`);
+}
+
+// --- 3. the rounded corner ---------------------------------------------------
+console.log("");
+console.log("-- the blur is clipped to the rounded box");
+{
+  const row = await rowOf(SCENES.rounded(12), 44, [104, 140]);
+  const outside = lum(row[0]);
+  const inside = lum(row[1]);
+  const wantOutside = lum(ORACLE.rounded.outsideTheCorner);
+  say(Math.abs(outside - wantOutside) <= TOL,
+    `outside the corner the backdrop is untouched (${outside})`,
+    `wanted ${wantOutside}, got ${outside}`);
+  const rowIn = await rowOf(SCENES.rounded(12), 80, [140]);
+  const wantInside = lum(ORACLE.rounded.insideTheCorner);
+  say(Math.abs(lum(rowIn[0]) - wantInside) <= TOL,
+    `and inside it the fill is over the blur (${lum(rowIn[0])})`,
+    `wanted ${wantInside}, got ${lum(rowIn[0])}`);
+}
+
+// --- 4. the case the others are blind to -------------------------------------
+console.log("");
+console.log("-- a feature that straddles the pane's own border");
+{
+  const want = ORACLE.acrossTheEdge;
+  const xs = [102, 105, 110, 120];
+  const row = await rowOf(SCENES.acrossTheEdge(12), 100, xs);
+  const got = row.map(lum);
+  const wantL = want.insideEdge.map(lum);
+  const worst = Math.max(...got.map((g, i) => Math.abs(g - wantL[i])));
+  say(worst <= TOL,
+    `the white outside the pane does not bleed in (${got.join(" ")})`,
+    `wanted ${wantL.join(" ")}, got ${got.join(" ")} — anything much above ` +
+    `zero here means the copied region reached past the element, and the page ` +
+    `behind it is showing through its own border`);
+
+  // Outside the rounded corner the backdrop is untouched black. A blur drawn
+  // as a square rather than a rounded box lightens this pixel, because it
+  // carries the white from x < 100 across the corner.
+  const corner = await rowOf(SCENES.acrossTheEdge(12), 43, [103]);
+  const wantCorner = lum(want.outsideCorner);
+  say(Math.abs(lum(corner[0]) - wantCorner) <= TOL,
+    `and the corner outside the radius is untouched (${lum(corner[0])})`,
+    `wanted ${wantCorner}, got ${lum(corner[0])} — a square clip shows here`);
+}
+
+// --- 5. the blur itself, clipped to the radius -------------------------------
+console.log("");
+console.log("-- the BLUR, not just the fill, respects the radius");
+{
+  const want = ORACLE.bandedCorner;
+  const row = await rowOf(SCENES.banded(12), 43, [103]);
+  const got = lum(row[0]);
+  say(Math.abs(got - lum(want.outsideCorner)) <= TOL,
+    `outside the corner the band is still hard (${got})`,
+    `wanted ${lum(want.outsideCorner)}, got ${got} — grey here means the ` +
+    `blurred backdrop was drawn as a rectangle and spilled past the radius`);
+  const inBand = await rowOf(SCENES.banded(12), 50, [200]);
+  say(Math.abs(lum(inBand[0]) - lum(want.insideBand)) <= TOL,
+    `and inside the shape the band is softened (${lum(inBand[0])})`,
+    `wanted ${lum(want.insideBand)}, got ${lum(inBand[0])}`);
+}
+
+// --- 5b. and the radius, where the two answers are far apart -----------------
+console.log("");
+console.log("-- outside the corner, the raw backdrop and the blurred one differ");
+{
+  const want = ORACLE.verticalCorner;
+  const outside = lum((await rowOf(SCENES.verticalColumn(12), 43, [104]))[0]);
+  const inside = lum((await rowOf(SCENES.verticalColumn(12), 100, [104]))[0]);
+  say(Math.abs(outside - lum(want.outsideCorner)) <= TOL,
+    `outside the radius the column is still hard (${outside})`,
+    `wanted ${lum(want.outsideCorner)}, got ${outside} — the blurred value at ` +
+    `this x is ${lum(want.wellInside)}, so anything near that means the blur ` +
+    `was drawn as a rectangle`);
+  // Deliberately NOT compared with the browser: this x is four pixels from the
+  // pane's border, and inside a kernel's reach of it Chrome stops producing a
+  // blur profile at all — see `borderBand` in the oracle. What is checked here
+  // is only that the blur HAPPENED, which is what makes the probe above mean
+  // something: raw black outside the corner, softened inside it.
+  say(inside > 40,
+    `and at the same x inside the shape it is softened (${inside})`,
+    `expected the column to have blurred away from black here, got ${inside}`);
+}
+
+// --- 5c. the kernel again, on a narrow feature clear of every border ---------
+// The step response is one edge. This is two, close together, which is where a
+// kernel that is nearly right stops being right — and it is 50px from the
+// nearest border, so nothing about the element's edge is mixed in.
+console.log("");
+console.log("-- a narrow column, well clear of the borders");
+{
+  const want = ORACLE.innerColumn;
+  const row = (await rowOf(SCENES.innerColumn(12), 100, want.xs)).map(lum);
+  let worst = 0, at = 0;
+  for (let i = 0; i < row.length; i++) {
+    const d = Math.abs(row[i] - want.luma[i]);
+    if (d > worst) { worst = d; at = want.xs[i]; }
+  }
+  say(worst <= TOL, `the profile matches the browser's (worst ${worst})`,
+    `worst ${worst} levels at x=${at}\n        browser ${want.luma.join(" ")}` +
+    `\n        painter ${row.join(" ")}`);
+}
+
+// --- 6. a second pane must not read the first one's leftovers ----------------
+// Not against the browser: against the SAME pane drawn alone. The claim is
+// that a pane looks the same whether or not a bigger one was blurred before it
+// in the frame, and the reference for that is the pane on its own.
+console.log("");
+console.log("-- a pane looks the same after a bigger one has been blurred");
+{
+  const xs = [205, 240, 275, 310, 345];
+  const alone = (await rowOf(SCENES.smallAlone(12), 55, xs)).map(lum);
+  const after = (await rowOf(SCENES.smallAfterBig(12), 55, xs)).map(lum);
+  const worst = Math.max(...alone.map((a, i) => Math.abs(a - after[i])));
+  say(worst <= TOL,
+    `the second pane is unchanged by the first (worst ${worst})`,
+    `alone ${alone.join(" ")} vs after ${after.join(" ")} — a difference here ` +
+    `means the blur passes sampled outside their own region and found what the ` +
+    `bigger pane left in the reused texture`);
+}
+
+await browser.close();
+fs.rmSync(tmp, { force: true });
+if (pageErrors.length) {
+  console.log("");
+  console.log("page errors:");
+  for (const e of pageErrors) console.log("  " + e);
+  bad += pageErrors.length;
+}
+console.log("");
+console.log(`passed=${checked - bad} failed=${bad}`);
+if (bad > 0) { console.log("FAILURES"); process.exit(1); }
+console.log("ALL PASS");

package/dist/lib/evg/gl/boxmodel.json

@@ -0,0 +1 @@
+{"width":595.00,"height":842.00,"list":{"cmds":[{"k":0,"x":0.00,"y":0.00,"w":595.00,"h":842.00,"c":[251,247,240,1.00]},{"k":3,"x":44.00,"y":44.00,"w":258.74,"h":40.80,"c":[59,47,42,1.00],"text":"Laatikkomalli","font":"Cinzel","size":34.00},{"k":0,"x":44.00,"y":98.80,"w":88.00,"h":3.00,"c":[176,141,87,1.00]},{"k":3,"x":44.00,"y":127.80,"w":76.17,"h":15.60,"c":[138,115,96,1.00],"text":"Täyte ja reunus","font":"Josefin Sans","size":13.00},{"k":0,"x":44.00,"y":151.40,"w":159.67,"h":90.00,"r":6.00,"c":[232,220,200,1.00]},{"k":0,"x":58.00,"y":165.40,"w":131.67,"h":22.00,"r":3.00,"c":[176,141,87,1.00]},{"k":0,"x":217.67,"y":151.40,"w":159.67,"h":90.00,"r":6.00,"c":[232,220,200,1.00]},{"k":0,"x":225.67,"y":155.40,"w":131.67,"h":22.00,"r":3.00,"c":[176,141,87,1.00]},{"k":0,"x":391.33,"y":151.40,"w":159.67,"h":90.00,"r":6.00,"c":[232,220,200,1.00]},{"k":0,"x":404.33,"y":164.40,"w":133.67,"h":22.00,"r":3.00,"c":[176,141,87,1.00]},{"k":3,"x":44.00,"y":267.40,"w":95.23,"h":15.60,"c":[138,115,96,1.00],"text":"Sisäkkäiset laatikot","font":"Josefin Sans","size":13.00},{"k":0,"x":44.00,"y":299.00,"w":507.00,"h":120.00,"r":6.00,"c":[239,230,214,1.00]},{"k":0,"x":56.00,"y":319.00,"w":483.00,"h":88.00,"r":6.00,"c":[229,216,194,1.00]},{"k":0,"x":68.00,"y":339.00,"w":459.00,"h":56.00,"r":6.00,"c":[216,199,171,1.00]},{"k":0,"x":80.00,"y":359.00,"w":435.00,"h":24.00,"r":6.00,"c":[176,141,87,1.00]},{"k":3,"x":44.00,"y":445.00,"w":103.09,"h":15.60,"c":[138,115,96,1.00],"text":"Marginaalit erikseen","font":"Josefin Sans","size":13.00},{"k":0,"x":44.00,"y":468.60,"w":507.00,"h":90.00,"r":6.00,"c":[232,220,200,1.00]},{"k":0,"x":58.00,"y":482.60,"w":479.00,"h":21.00,"r":3.00,"c":[176,141,87,1.00]},{"k":0,"x":82.00,"y":523.60,"w":383.20,"h":21.00,"r":3.00,"c":[176,141,87,1.00]}]}}