@buoy-gg/shared-ui 7.0.35 → 7.0.38

package/scripts/generate-wormhole-textures.cjs

@@ -0,0 +1,261 @@
+// Generates src/ui/backgrounds/variants/wormhole/textures.ts.
+// Usage (from packages/shared): node scripts/generate-wormhole-textures.cjs [--still scene.jpg] [--keep dir]
+//
+// The moving scene is a zoom, and a zoom only loops invisibly when the picture
+// is self-similar under the handoff transform. So the cloud sheet is built by
+// tiling ONE annulus of the real shader frame in log-polar space with the
+// spiral symmetry  sheet(K·ρ, φ+θ) = sheet(ρ, φ)  (K, θ come from motion.ts).
+// Two copies of the sheet, one K× larger and θ further round, are then the same
+// picture, so the crossfade between them cannot be seen. The destination is
+// cut from the same frame and drawn as a static layer above the sheets.
+//
+// Pipeline (all in memory, no image dependencies):
+//   1. CPU port of apps/website vortexShader.ts renders the dark scene at u_t=4,
+//      framed so the destination sits at the centre, without the site vignette.
+//   2. That frame is tiled into the sheet (opaque → JPEG via macOS `sips`).
+//   3. The eye is cut with a feathered alpha (→ PNG, zlib only).
+//   4. The reduced-motion still is kept from the existing module unless --still
+//      supplies a fresh WebGL capture (a centered 640px JPEG of the website).
+const fs = require('node:fs'), path = require('node:path'), zlib = require('node:zlib'), os = require('node:os');
+const { execFileSync } = require('node:child_process');
+const ts = require('typescript');
+const vm = require('node:vm');
+
+const ROOT = path.join(__dirname, '..');
+const MOTION = path.join(ROOT, 'src/ui/backgrounds/variants/wormhole/motion.ts');
+const MODULE = path.join(ROOT, 'src/ui/backgrounds/variants/wormhole/textures.ts');
+const args = process.argv.slice(2);
+const flag = (name) => { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : null; };
+
+// The same numbers the animation uses — the sheet's symmetry MUST match them.
+const motion = {};
+vm.runInNewContext(ts.transpileModule(fs.readFileSync(MOTION, 'utf8'), { compilerOptions: { module: ts.ModuleKind.CommonJS } }).outputText, { exports: motion });
+const K = motion.WORMHOLE_PERIOD, THETA = motion.WORMHOLE_TWIST * Math.PI / 180;
+
+// Radii below are in STILL units: 1 = the edge of the shipped 640px still, which
+// the plane stretches to its own radius. The source frame is rendered with a
+// wider field (WIDE) so the whole tile annulus fits inside it.
+const SOURCE_PX = 2560;  // render size; every visible sheet period samples it at ≥ 1:1
+const WIDE = 1.25;       // still units per source-frame radius
+const SHEET_PX = 1440;   // opaque JPEG, stretched over the plane (≈ the old texel size at the shells' mean scale)
+const CORE_PX = 384;     // RGBA PNG, covers the centre half of the plane
+const CORE_SPAN = 0.5;   // still radii covered by the core image
+const CORE_FEATHER = [0.12, 0.34]; // alpha 1→0 across these still radii
+const BAND_INNER = 0.45; // the annulus [BAND_INNER, K·BAND_INNER] of the frame is the tile
+const SEAM = 0.3;        // fraction of a period crossfaded into the next tile
+const JPEG_QUALITY = 88;
+
+// ---------------------------------------------------------------------------
+// 1. Shader port (dark palette, u_t = 4, no pointer / ripple / copy scrim)
+// ---------------------------------------------------------------------------
+const fract = (x) => x - Math.floor(x);
+const pmod = (x, m) => ((x % m) + m) % m;
+const hash = (x, y) => fract(Math.sin(x * 127.1 + y * 311.7) * 43758.5453123);
+const smooth = (a, b, x) => { const t = Math.max(0, Math.min(1, (x - a) / (b - a))); return t * t * (3 - 2 * t); };
+const mix = (a, b, t) => a + (b - a) * t;
+const TAU = Math.PI * 2;
+function noise(x, y) {
+  const ix = Math.floor(x), iy = Math.floor(y); let fx = x - ix, fy = y - iy;
+  fx = fx * fx * (3 - 2 * fx); fy = fy * fy * (3 - 2 * fy);
+  return mix(mix(hash(ix, iy), hash(ix + 1, iy), fx), mix(hash(ix, iy + 1), hash(ix + 1, iy + 1), fx), fy);
+}
+function volumeNoise(x, y, z) {
+  const zi = Math.floor(z); let f = z - zi; f = f * f * (3 - 2 * f);
+  const a = pmod(zi, 256), b = pmod(zi + 1, 256);
+  return mix(noise(x + a * 17.1, y + a * 31.7), noise(x + b * 17.1, y + b * 31.7), f);
+}
+function vapor(x, y, z) {
+  let r = 0, w = 0.53;
+  for (let i = 0; i < 3; i++) { r += volumeNoise(x, y, z) * w; x = x * 2.03 + 2.1; y = y * 2.03 + 5.7; z = z * 2.03 + 9.3; w *= 0.48; }
+  return r;
+}
+const WALL = [0.06, 0.16, 0.48], LIGHT = [0.2, 0.62, 1.0], DEST = [1.0, 0.33, 0.1], DUST = [0.8, 0.95, 1.0], LIFT = [0.004, 0.008, 0.017];
+const SPEED = 0.68, TWIST = 0.48, BEND = 0.32, T = 4, FOV = 1.55 * WIDE;
+const flightCourse = (z) => [(Math.sin(z * 0.24) * 2.2 + Math.sin(z * 0.08) * 1.4) * BEND, Math.cos(z * 0.19) * 1.7 * BEND];
+const camera = T * SPEED * 2.1;
+const origin = flightCourse(camera);
+const ahead = flightCourse(camera + 2.2);
+const look = [(ahead[0] - origin[0]) / 2.2, (ahead[1] - origin[1]) / 2.2];
+const passage = (z) => { const f = flightCourse(camera + z); return [f[0] - origin[0] - look[0] * z, f[1] - origin[1] - look[1] * z]; };
+const roll = Math.sin(T * 0.13) * 0.055, cr = Math.cos(roll), sr = Math.sin(roll);
+// Frame the destination at the centre: undo the roll on its p-space position.
+const far = passage(14).map((v) => v / 14);
+const FRAME = [0.5 - (Math.cos(-roll) * far[0] - Math.sin(-roll) * far[1]) / FOV, 0.5 - (Math.sin(-roll) * far[0] + Math.cos(-roll) * far[1]) / FOV];
+
+function shade(uvx, uvy) {
+  let px = (uvx - FRAME[0]) * FOV, py = (uvy - FRAME[1]) * FOV;
+  [px, py] = [cr * px - sr * py, sr * px + cr * py];
+  let z = 0;
+  for (let i = 0; i < 48; i++) {
+    const pz = passage(z), qx = px * z - pz[0], qy = py * z - pz[1];
+    const a = Math.atan2(qy, qx + 1e-6);
+    const gap = 0.78 + 0.055 * Math.sin(a * 4 + (camera + z) * 0.7) - Math.hypot(qx, qy);
+    if (gap < 0.004 || z > 18) break;
+    z += Math.max(0.003, gap * 0.65 / Math.hypot(px, py, 1));
+  }
+  const pz = passage(z), wx = px * z - pz[0], wy = py * z - pz[1];
+  const angle = Math.atan2(wy, wx), textureZ = camera + z, twist = angle + textureZ * TWIST;
+  const sx = Math.cos(twist) * 2.6, sy = Math.sin(twist) * 2.6, sz = textureZ * 0.78;
+  const n = vapor(sx, sy, sz);
+  const detail = volumeNoise(sx * 3.2 + n * 1.7, sy * 3.2 + n * 1.7, sz * 3.2 + n * 1.7);
+  const depth = 1 - Math.exp(-z * 0.13), wallFade = 1 - smooth(10, 18, z);
+  const billow = smooth(0.18, 0.75, n);
+  const ridges = Math.pow(1 - Math.abs(detail * 2 - 1), 7);
+  const ribbons = Math.pow(0.5 + 0.5 * Math.sin(twist * 5 + n * 6 + textureZ * 2.6), 7);
+  const copper = smooth(2.5, 9, z), side = 0.55 + 0.45 * Math.sin(angle - 0.8 + n * 1.2);
+  const dx = px - far[0], dy = py - far[1], core = Math.hypot(dx, dy);
+  const glow = Math.exp(-core * 13) * (0.23 + 0.04 * Math.sin(T * 0.7)), haze = Math.exp(-core * 5) * 0.025;
+  const c = [0, 0, 0];
+  for (let i = 0; i < 3; i++) {
+    let v = WALL[i] * (0.2 + billow * 1.15) + LIGHT[i] * (ridges * 0.17 + ribbons * 0.4) * (0.3 + billow);
+    v = mix(v, DEST[i] * (billow * 0.55 + ribbons * 0.3), copper);
+    c[i] = v * side * (0.75 + depth * 0.55) * wallFade + DEST[i] * glow + LIGHT[i] * haze;
+  }
+  for (let layer = 0; layer < 3; layer++) {
+    const r = Math.max(core, 0.012), angular = (Math.atan2(dy, dx) / TAU + 0.5) * (85 + layer * 27);
+    const seed = hash(Math.floor(angular), layer + 5);
+    const along = fract(Math.log(r) * (2.3 + layer * 0.5) - camera * (0.75 + seed * 0.5) + seed * 13);
+    const across = (fract(angular) - 0.5) / ((0.045 + layer * 0.012) / (0.5 + r));
+    const streak = Math.exp(-across * across) * Math.exp(-along * 36) * (seed > 0.69 ? 1 : 0) * smooth(0.06, 0.25, r);
+    for (let i = 0; i < 3; i++) c[i] += mix(LIGHT[i], DUST[i], 0.6) * streak * 0.4;
+  }
+  for (let i = 0; i < 3; i++) c[i] = 1 - Math.exp(-(c[i] + LIFT[i]) * 1.3);
+  return c;
+}
+
+// ---------------------------------------------------------------------------
+// 2–3. Tiling and the eye cut
+// ---------------------------------------------------------------------------
+function png(w, h, rgba) {
+  const crcTable = []; for (let n = 0; n < 256; n++) { let c = n; for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1; crcTable[n] = c >>> 0; }
+  const crc = (buf) => { let c = 0xffffffff; for (const b of buf) c = crcTable[(c ^ b) & 0xff] ^ (c >>> 8); return (c ^ 0xffffffff) >>> 0; };
+  const chunk = (type, data) => { const t = Buffer.from(type), len = Buffer.alloc(4), sum = Buffer.alloc(4); len.writeUInt32BE(data.length); sum.writeUInt32BE(crc(Buffer.concat([t, data]))); return Buffer.concat([len, t, data, sum]); };
+  const header = Buffer.alloc(13); header.writeUInt32BE(w); header.writeUInt32BE(h, 4); header[8] = 8; header[9] = 6;
+  const rows = [];
+  for (let y = 0; y < h; y++) {
+    const row = Buffer.alloc(w * 4);
+    for (let x = 0; x < w * 4; x++) row[x] = (rgba[y * w * 4 + x] - (x >= 4 ? rgba[y * w * 4 + x - 4] : 0) + 256) % 256;
+    rows.push(Buffer.from([1]), row);
+  }
+  return Buffer.concat([Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]), chunk('IHDR', header), chunk('IDAT', zlib.deflateSync(Buffer.concat(rows), { level: 9 })), chunk('IEND', Buffer.alloc(0))]);
+}
+
+console.log(`rendering ${SOURCE_PX}px source frame…`);
+let t0 = Date.now();
+const source = new Float32Array(SOURCE_PX * SOURCE_PX * 3);
+for (let y = 0; y < SOURCE_PX; y++) for (let x = 0; x < SOURCE_PX; x++) {
+  const c = shade((x + 0.5) / SOURCE_PX, (y + 0.5) / SOURCE_PX);
+  source.set(c, (y * SOURCE_PX + x) * 3);
+}
+console.log(`  ${((Date.now() - t0) / 1000).toFixed(1)}s`);
+
+// Bilinear sample at still radii (u, v).
+function sample(u, v) {
+  u /= WIDE; v /= WIDE;
+  if (Math.max(Math.abs(u), Math.abs(v)) > 1) throw new Error(`sample outside the source frame (${u.toFixed(2)}, ${v.toFixed(2)}): raise WIDE`);
+  const x = Math.max(0, Math.min(SOURCE_PX - 1.001, (u + 1) / 2 * SOURCE_PX - 0.5)), y = Math.max(0, Math.min(SOURCE_PX - 1.001, (v + 1) / 2 * SOURCE_PX - 0.5));
+  const x0 = Math.floor(x), y0 = Math.floor(y), fx = x - x0, fy = y - y0;
+  const out = [0, 0, 0];
+  for (const [xx, yy, w] of [[x0, y0, (1 - fx) * (1 - fy)], [x0 + 1, y0, fx * (1 - fy)], [x0, y0 + 1, (1 - fx) * fy], [x0 + 1, y0 + 1, fx * fy]]) {
+    const i = (yy * SOURCE_PX + xx) * 3; out[0] += source[i] * w; out[1] += source[i + 1] * w; out[2] += source[i + 2] * w;
+  }
+  return out;
+}
+const polar = (rho, phi) => sample(rho * Math.cos(phi), rho * Math.sin(phi));
+// One sheet sample: which period is this radius in, and where in the tile.
+// A sheet radius is K still radii, so at the shells' mean scale (K) the sheet
+// shows the still's features at their own size.
+function tile(px, py) {
+  const rho = Math.max(Math.hypot(px, py) * K, 1e-9), phi = Math.atan2(py, px);
+  const u = Math.log(rho / BAND_INNER) / Math.log(K), m = Math.floor(u), f = u - m;
+  // Period m is the tile rotated m·θ further round (screen convention: positive = clockwise).
+  const c = polar(BAND_INNER * Math.pow(K, f), phi - m * THETA);
+  if (f > 1 - SEAM) {
+    const t = smooth(1 - SEAM, 1, f), d = polar(BAND_INNER * Math.pow(K, f - 1), phi - (m + 1) * THETA);
+    for (let i = 0; i < 3; i++) c[i] += (d[i] - c[i]) * t;
+  }
+  return c;
+}
+
+console.log(`tiling ${SHEET_PX}px sheet (K=${K.toFixed(4)}, θ=${motion.WORMHOLE_TWIST}°)…`);
+t0 = Date.now();
+const sheet = Buffer.alloc(SHEET_PX * SHEET_PX * 4);
+for (let y = 0; y < SHEET_PX; y++) for (let x = 0; x < SHEET_PX; x++) {
+  const px = ((x + 0.5) / SHEET_PX) * 2 - 1, py = ((y + 0.5) / SHEET_PX) * 2 - 1;
+  // Periods shrink toward the centre, so supersample harder there.
+  const ss = Math.max(2, Math.min(12, Math.ceil(2 / Math.max(Math.hypot(px, py) * K, 0.02))));
+  const acc = [0, 0, 0];
+  for (let j = 0; j < ss; j++) for (let i = 0; i < ss; i++) {
+    const c = tile(px + ((i + 0.5) / ss - 0.5) * 2 / SHEET_PX, py + ((j + 0.5) / ss - 0.5) * 2 / SHEET_PX);
+    acc[0] += c[0]; acc[1] += c[1]; acc[2] += c[2];
+  }
+  const o = (y * SHEET_PX + x) * 4;
+  for (let i = 0; i < 3; i++) sheet[o + i] = Math.max(0, Math.min(255, Math.round(acc[i] / (ss * ss) * 255)));
+  sheet[o + 3] = 255;
+}
+console.log(`  ${((Date.now() - t0) / 1000).toFixed(1)}s`);
+
+// Self-check: the sheet drawn K× larger and θ further round must be the same
+// picture. Compare against the 4px-neighbour difference so "similar" is
+// relative to the sheet's own detail, not an absolute threshold.
+{
+  const N = SHEET_PX, c = N / 2, at = (x, y) => { x = Math.round(x); y = Math.round(y); if (x < 0 || y < 0 || x >= N || y >= N) return null; const i = (y * N + x) * 4; return [sheet[i], sheet[i + 1], sheet[i + 2]]; };
+  let err = 0, base = 0, n = 0;
+  for (let y = 0; y < N; y += 5) for (let x = 0; x < N; x += 5) {
+    const dx = x - c, dy = y - c, r = Math.hypot(dx, dy); if (r > c * 0.45 || r < c * 0.08) continue;
+    const cs = Math.cos(-THETA), sn = Math.sin(-THETA);
+    const a = at(x, y), b = at((dx * cs - dy * sn) / K + c, (dx * sn + dy * cs) / K + c), d = at(x + 4, y); if (!a || !b || !d) continue;
+    for (let i = 0; i < 3; i++) { err += Math.abs(a[i] - b[i]); base += Math.abs(a[i] - d[i]); }
+    n++;
+  }
+  console.log(`  symmetry residual ${(err / n / 3).toFixed(2)} vs neighbour difference ${(base / n / 3).toFixed(2)}`);
+  if (err > base) throw new Error('sheet is not self-similar under (K, θ) — the handoff would be visible');
+}
+
+console.log(`cutting ${CORE_PX}px eye…`);
+const core = Buffer.alloc(CORE_PX * CORE_PX * 4);
+for (let y = 0; y < CORE_PX; y++) for (let x = 0; x < CORE_PX; x++) {
+  const u = (((x + 0.5) / CORE_PX) * 2 - 1) * CORE_SPAN, v = (((y + 0.5) / CORE_PX) * 2 - 1) * CORE_SPAN;
+  const ss = 3, acc = [0, 0, 0];
+  for (let j = 0; j < ss; j++) for (let i = 0; i < ss; i++) {
+    const c = sample(u + ((i + 0.5) / ss - 0.5) * 2 * CORE_SPAN / CORE_PX, v + ((j + 0.5) / ss - 0.5) * 2 * CORE_SPAN / CORE_PX);
+    acc[0] += c[0]; acc[1] += c[1]; acc[2] += c[2];
+  }
+  const o = (y * CORE_PX + x) * 4;
+  for (let i = 0; i < 3; i++) core[o + i] = Math.max(0, Math.min(255, Math.round(acc[i] / (ss * ss) * 255)));
+  core[o + 3] = Math.round(255 * (1 - smooth(CORE_FEATHER[0], CORE_FEATHER[1], Math.hypot(u, v))));
+}
+
+// ---------------------------------------------------------------------------
+// 4. Encode and emit
+// ---------------------------------------------------------------------------
+const keep = flag('--keep');
+const work = keep ? path.resolve(keep) : fs.mkdtempSync(path.join(os.tmpdir(), 'wormhole-'));
+fs.mkdirSync(work, { recursive: true });
+const sheetPng = path.join(work, 'sheet.png'), sheetJpg = path.join(work, 'sheet.jpg'), corePng = path.join(work, 'core.png');
+fs.writeFileSync(sheetPng, png(SHEET_PX, SHEET_PX, sheet));
+fs.writeFileSync(corePng, png(CORE_PX, CORE_PX, core));
+try {
+  execFileSync('sips', ['-s', 'format', 'jpeg', '-s', 'formatOptions', String(JPEG_QUALITY), sheetPng, '--out', sheetJpg], { stdio: 'ignore' });
+} catch (error) {
+  throw new Error(`JPEG encoding needs macOS \`sips\` (${error.message}); the PNG is at ${sheetPng}`);
+}
+const stillArg = flag('--still');
+const still = stillArg
+  ? fs.readFileSync(stillArg).toString('base64')
+  : /WORMHOLE_STILL = \{ uri: "data:image\/jpeg;base64,([^"]+)"/.exec(fs.readFileSync(MODULE, 'utf8'))?.[1];
+if (!still) throw new Error('No still: pass --still scene.jpg (a centered 640px WebGL capture of the website wormhole)');
+const sheetB64 = fs.readFileSync(sheetJpg).toString('base64'), coreB64 = fs.readFileSync(corePng).toString('base64');
+const module_ = '// Generated by scripts/generate-wormhole-textures.cjs — do not edit.\n'
+  + '// Shared source objects reuse the decoded images across instances.\n'
+  + '/** The website frame as captured (reduced motion / animation off). */\n'
+  + `export const WORMHOLE_STILL = { uri: "data:image/jpeg;base64,${still}" };\n`
+  + `/** Opaque cloud sheet, self-similar under scale ×${K.toFixed(4)} + rotate ${motion.WORMHOLE_TWIST}°; stretched over the plane. */\n`
+  + `export const WORMHOLE_SHEET = { uri: "data:image/jpeg;base64,${sheetB64}" };\n`
+  + `/** The destination, feathered; drawn static over the sheets at half the plane's size. */\n`
+  + `export const WORMHOLE_CORE = { uri: "data:image/png;base64,${coreB64}" };\n`;
+fs.writeFileSync(MODULE, module_);
+const kib = (s) => Math.round(s / 1024);
+console.log(`wrote ${path.relative(ROOT, MODULE)}: still ${kib(still.length * 0.75)} KiB, sheet ${kib(sheetB64.length * 0.75)} KiB, core ${kib(coreB64.length * 0.75)} KiB (module ${kib(module_.length)} KiB)`);
+console.log(`decoded: sheet ${(SHEET_PX * SHEET_PX * 4 / 1048576).toFixed(1)} MiB + core ${(CORE_PX * CORE_PX * 4 / 1048576).toFixed(1)} MiB while moving; still ${(640 * 640 * 4 / 1048576).toFixed(1)} MiB otherwise`);
+if (!keep) fs.rmSync(work, { recursive: true, force: true }); else console.log(`intermediates kept in ${work}`);

package/scripts/test-wormhole-motion.cjs

@@ -0,0 +1,59 @@
+// Run from packages/shared: node scripts/test-wormhole-motion.cjs
+// Checks the keyframe math only. Whether the handoff is VISIBLE depends on the
+// sheet texture being self-similar under (WORMHOLE_PERIOD, WORMHOLE_TWIST);
+// generate-wormhole-textures.cjs checks that against the rendered pixels.
+const fs = require('node:fs');
+const vm = require('node:vm');
+const assert = require('node:assert/strict');
+const ts = require('typescript');
+const e = {};
+const source = fs.readFileSync('src/ui/backgrounds/variants/wormhole/motion.ts', 'utf8');
+vm.runInNewContext(ts.transpileModule(source, { compilerOptions: { module: ts.ModuleKind.CommonJS } }).outputText, { exports: e });
+const { WORMHOLE_INPUT: input, WORMHOLE_SHELLS: shells, WORMHOLE_PERIOD: K, WORMHOLE_TWIST: THETA } = e;
+const passMs = e.WORMHOLE_CYCLE_MS / e.WORMHOLE_PASSES;
+assert.equal(passMs, 6000);
+assert.equal(shells.length, 2, 'reuse the existing two image layers');
+const close = (a, b, tolerance = 1e-9) => Math.abs(a - b) < tolerance;
+for (const shell of shells) {
+  for (const values of [shell.scale, shell.opacity, shell.rotate]) {
+    assert.equal(values.length, input.length);
+    assert.equal(values[0], values.at(-1), 'camera loop must be seamless');
+  }
+  for (let i = 1; i < input.length; i++) {
+    assert(input[i] > input[i - 1]);
+    assert(shell.scale[i] >= 1 - 1e-9 && shell.scale[i] <= K * K + 1e-9, 'the sheet covers the plane from scale 1 and a pass spans one K² zoom');
+    assert(shell.opacity[i] >= 0 && shell.opacity[i] <= 0.9200000001);
+    if (shell.scale[i] < shell.scale[i - 1]) {
+      assert.equal(shell.opacity[i - 1], 0, 'hide before reset');
+      assert.equal(shell.opacity[i], 0, 'hide during reset');
+      // The reset is itself a symmetry of the sheet: K² in scale and 2θ in
+      // rotation (the keyframe before the wrap sits one step short of both).
+      const step = shell.scale[1] / shell.scale[0], turn = parseFloat(shell.rotate[1]) - parseFloat(shell.rotate[0]);
+      assert(close(shell.scale[i - 1] / shell.scale[i] * step, K * K, 1e-6), 'reset jumps exactly two periods');
+      assert(close(parseFloat(shell.rotate[i - 1]) - parseFloat(shell.rotate[i]) + turn, 2 * THETA, 1e-6), 'reset unwinds exactly two twists');
+    }
+  }
+}
+for (let i = 0; i < input.length; i++) {
+  const transmission = shells.reduce((total, shell) => total * (1 - shell.opacity[i]), 1);
+  assert(close(transmission, 0.08, 1e-10), 'handoff must not pulse its composited opacity');
+  // THE invariant that hides the handoff: whichever shell is larger is exactly
+  // the other one scaled by K and turned by θ, i.e. the same picture.
+  const [a, b] = shells[0].scale[i] < shells[1].scale[i] ? [shells[0], shells[1]] : [shells[1], shells[0]];
+  assert(close(b.scale[i] / a.scale[i], K, 1e-6), `shells must sit one period apart (index ${i})`);
+  assert(close(parseFloat(b.rotate[i]) - parseFloat(a.rotate[i]), THETA, 1e-6), `shells must sit one twist apart (index ${i})`);
+}
+for (const shell of shells) {
+  const ratios = [];
+  for (let i = 1; i < input.length; i++) {
+    if (shell.scale[i] > shell.scale[i - 1]) ratios.push(shell.scale[i] / shell.scale[i - 1]);
+    assert(Math.abs(shell.opacity[i] - shell.opacity[i - 1]) < 0.09, 'no abrupt opacity steps');
+  }
+  assert(Math.max(...ratios) - Math.min(...ratios) < 1e-10, 'consistent proportional forward speed');
+}
+const rotation = e.WORMHOLE_CAMERA_ROTATION.map(parseFloat);
+const turnaround = (input.length - 1) / 2;
+assert.equal(rotation[0], rotation.at(-1));
+assert(Math.abs(rotation[1] - rotation[0]) < 0.002, 'camera eases through loop seam');
+assert(Math.abs(rotation[turnaround + 1] - rotation[turnaround]) < 0.002, 'camera eases through turnaround');
+console.log(`PASS: shells always one (×${K}, ${THETA}°) symmetry apart, resets are symmetries too, continuous optical density, steady forward expansion, sheet never shows an edge, smooth camera turns, same two layers.`);