fix(shadow): kill cast/self-shadow holes on imported meshes + shadow-parity bench tooling (#70)

* fix(shadow): fill floor cast-shadow gaps on imported meshes via silhouette-reliability gate + double-sided fallback

* feat(bench): real-capture all-mesh shadow oracle with headless JSON verdict

* feat(bench): shadow-mask parity oracle — binary shadow-shape diff, IoU, rotation-correct occluder attribution

* fix(shadow): cast from all polygons, not just camera-rendered ones, to kill camera-dependent floor-shadow holes

* fix(shadow): gate self-shadow seam cull to near-coplanar casters so faceted meshes keep real self-shadows

* feat(bench): light-animation panel — per-axis math expressions of t with play/pause, speed, and scrub

* fix(shadow): cast self-shadow double-sided so non-watertight meshes keep self-shadows from light-back-facing occluders

Author: apresmoi

AGENTS.md

@@ -41,7 +41,9 @@ Strategies are ordered cheapest → most expensive. The mesher's job is to maxim
 
 Callers can opt out of specific strategies via `strategies: { disable: ["b" | "i" | "u"] }` on `RenderTextureAtlasOptions`. Disabled or unsupported strategies fall through the chain (`b → i → s`, `u → i → s`, `i → s`). Disabling `"i"` also disables the exact corner-shape solid branch even though that branch emits a bare `<u>`, because it belongs to the non-triangle clipped-solid family. `<s>` is the universal fallback and cannot be disabled. Solid seam bleed is internal: detected shared solid edges get up to `1.5` CSS px of per-edge overscan, fitted to the polygon plan, rather than inflating every side of each participating polygon. It is not exposed as a scene, mesh, custom-element, or atlas renderer option.
 
-Cast shadows are not a render-strategy leaf tag. Meshes with `castShadow: true` project casting polygons on the CPU into SVG shadow surfaces: one aggregate path for the ground plane in vanilla, per-mesh SVG paths in React/Vue, plus scene-level receiver surfaces where `receiveShadow` is enabled. Overlapping projections are merged into compound paths so shadows do not alpha-stack polygon-by-polygon, and back-facing / duplicate projections are dropped before emission. Moving a light or changing caster/receiver geometry re-emits the shadow SVGs; this is DOM/SVG work only and does not redraw texture atlases.
+Cast shadows are not a render-strategy leaf tag. Meshes with `castShadow: true` project casting polygons on the CPU into SVG shadow surfaces: one aggregate path for the ground plane in vanilla, per-mesh SVG paths in React/Vue, plus scene-level receiver surfaces where `receiveShadow` is enabled. EVERY polygon casts — shadow casters are NOT filtered to the camera-rendered set (atlas plan) or de-duplicated, because a polygon casts a shadow regardless of whether it's painted for the camera; filtering left camera-dependent holes in imported-mesh shadows. Coincident/overlapping projections are merged into one compound path per caster under `fill-rule: nonzero`, so they don't alpha-stack rather than being pre-dropped. Moving a light or changing caster/receiver geometry re-emits the shadow SVGs; this is DOM/SVG work only and does not redraw texture atlases.
+
+Receiver-shadow geometry has two caster paths. The default per-mesh **silhouette fast path** (caster ≠ receiver, ≥40 polys) projects one outline per caster instead of every front-facing triangle — but only when the caster's silhouette under the current light is a clean union of simple closed loops (every silhouette vertex shared by exactly two silhouette edges). Meshes whose silhouette has non-manifold / T-junction / open-boundary vertices (imported architecture like the castle) fall back to the **per-polygon union**, which is gap-free for any topology. Light-back-facing caster polygons are normally culled (single-sided casting, correct for clean closed meshes); the per-poly path casts **double-sided** (skips that cull) for two cases — cross-mesh casters whose silhouette is unreliable, and ALL self-shadow casters (caster = receiver) — so badly-wound / single-sided interior walls don't leave holes. Closed meshes are unaffected by double-siding: their far back-faces sit below each lit receiver plane and get above-plane-culled, adding no spurious shadow.
 
 The `.vox` fast path emits plain `<b>` elements inside `.polycss-voxel-face` wrappers. They intentionally reuse the cheap quad tag; each visible quad has one `matrix3d(...)`, with same-color shared-edge overscan folded into the local left/top/width/height before matrix generation. The face wrappers are grouping nodes for cheap add/remove and are not render-strategy leaves. Desktop-class documents use a canonical 1px primitive for the cheapest transform shape; mobile-class documents (`pointer: coarse` or `hover: none`) use an 8px primitive and divide the in-plane matrix scale by 8 to preserve identical CSS-space geometry while avoiding large GPU filtering gaps.
 

bench/scripts/shadow-mask-verdict.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/**
+ * Shadow-MASK parity verdict — the better oracle.
+ *
+ * Instead of a luma diff with a tolerance knob, this drives both engines
+ * into "shadows only" mode (PolyCSS hides meshes → shadow SVGs only;
+ * three.js → ShadowMaterial), reduces each REAL render to a binary
+ * "in shadow?" mask, and compares shadow SHAPE: missing (three shadowed,
+ * PolyCSS lit = a hole), extra (PolyCSS shadowed, three lit). three.js
+ * stays the reference; only the comparison method changes.
+ *
+ * Writes illustration PNGs (diff classification + the on-render green
+ * occluder outlines) next to the JSON verdict.
+ *
+ * Usage:
+ *   node bench/scripts/shadow-mask-verdict.mjs "<shadow-oracle URL>" [outPrefix]
+ *
+ * Server must be running on :4400.
+ */
+import { chromium } from 'playwright';
+import { writeFileSync } from 'node:fs';
+
+const url = process.argv[2];
+if (!url) { console.error('usage: shadow-mask-verdict.mjs <url> [outPrefix]'); process.exit(2); }
+const prefix = process.argv[3] ?? '/tmp/shadow-mask';
+
+const browser = await chromium.launch({ args: ['--use-angle=metal', '--enable-gpu-rasterization'] });
+const ctx = await browser.newContext({ viewport: { width: 1500, height: 950 }, deviceScaleFactor: 2 });
+const page = await ctx.newPage();
+page.on('pageerror', e => console.error('[pageerror]', e.message));
+await page.goto(url, { waitUntil: 'networkidle', timeout: 30000 });
+await page.waitForTimeout(6500);
+
+await page.evaluate(() => window.oracleSetHelpersHidden(true));
+// Shadows-only mode for clean binary masks on both engines.
+await page.evaluate(() => window.oracleSetShadowsOnly(true));
+await page.waitForTimeout(800); // SVG recolor + three ShadowMaterial render
+
+const shot = await (await page.$('#poly-host')).screenshot();
+const json = await page.evaluate(
+  d => window.oracleMaskCompare(d),
+  'data:image/png;base64,' + shot.toString('base64'),
+);
+
+// Illustration 1: the diff classification (red=missing, blue=extra).
+await (await page.$('.stage.diff')).screenshot({ path: `${prefix}-diff.png` });
+// Illustration 2: back to normal render so the green occluder outlines show.
+await page.evaluate(() => window.oracleSetShadowsOnly(false));
+await page.evaluate(() => window.oracleSetHelpersHidden(true));
+await page.waitForTimeout(400);
+await (await page.$('.stage.polycss')).screenshot({ path: `${prefix}-render.png` });
+await (await page.$('.stage.three')).screenshot({ path: `${prefix}-three.png` });
+
+writeFileSync(`${prefix}.json`, JSON.stringify(json, null, 2));
+console.log(JSON.stringify(json, null, 2));
+console.error(`wrote ${prefix}-diff.png ${prefix}-render.png ${prefix}-three.png ${prefix}.json`);
+await browser.close();

bench/scripts/shadow-oracle-verdict.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * Headless shadow-oracle verdict.
+ *
+ * Drives bench/shadow-oracle.html with a deterministic URL, screenshots
+ * #poly-host with the REAL compositor (Playwright — captures the
+ * 3D-`matrix3d`-transformed receiver-shadow SVGs that html-to-image drops),
+ * hands it to the in-page oracle, and prints the JSON verdict: every polygon
+ * (across ALL meshes — caster model + floor receiver) whose rendered
+ * shading/shadow disagrees with three.js beyond the luma tolerance.
+ *
+ * Usage:
+ *   node bench/scripts/shadow-oracle-verdict.mjs "<shadow-oracle URL>" [outFile.json]
+ *
+ * Server must be running on :4400 (node bench/perf-serve.mjs).
+ */
+import { chromium } from 'playwright';
+import { writeFileSync } from 'node:fs';
+
+const url = process.argv[2];
+if (!url) { console.error('usage: shadow-oracle-verdict.mjs <url> [out.json]'); process.exit(2); }
+const outFile = process.argv[3];
+
+const browser = await chromium.launch({ args: ['--use-angle=metal', '--enable-gpu-rasterization'] });
+const ctx = await browser.newContext({ viewport: { width: 1500, height: 950 }, deviceScaleFactor: 1 });
+const page = await ctx.newPage();
+page.on('pageerror', e => console.error('[pageerror]', e.message));
+await page.goto(url, { waitUntil: 'networkidle', timeout: 30000 });
+// Settle: atlas blobs + shadow SVGs + three draw.
+await page.waitForTimeout(6500);
+
+// Hide the light helper, let it present, screenshot the real PolyCSS render.
+await page.evaluate(() => window.oracleSetHelpersHidden(true));
+await page.waitForTimeout(200);
+const host = await page.$('#poly-host');
+const shot = await host.screenshot();
+const dataUrl = 'data:image/png;base64,' + shot.toString('base64');
+
+const json = await page.evaluate(d => window.oracleCompareWithImage(d), dataUrl);
+await page.evaluate(() => window.oracleSetHelpersHidden(false));
+
+if (!json) { console.error('oracle returned null'); process.exit(1); }
+const out = JSON.stringify(json, null, 2);
+if (outFile) { writeFileSync(outFile, out); console.error('wrote', outFile); }
+console.log(out);
+await browser.close();