@litfamily/litgrok 1.0.26 → 1.0.28

package/.grok/skills/lit-typographic-motion/scripts/lib/board.mjs

@@ -0,0 +1,153 @@
+// The storyboard: `stills/board.png`, one page a person can read before the full render.
+// One tile per beat (the beat still) with the shot's number, time, layout and hand-off under it
+// and the shot's type zone outlined on the frame when the beat names one; a header with the house
+// style (name, palette, type) and the film's format, length and sound; a footer with the layout
+// check. Drawn as a page in the same headless Chrome the stage uses, so its type is product faces.
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { LAYOUTS, readStyle } from "./styles.mjs";
+import { resolveChrome } from "./chrome.mjs";
+import { openStage } from "./stage-session.mjs";
+import { stageFonts } from "./stage.mjs";
+
+const SKILL_ROOT = fileURLToPath(new URL("../..", import.meta.url));
+
+export const BOARD = Object.freeze({ width: 1920, height: 1080, margin: 48, gap: 20, header: 150, footer: 56, caption: 104 });
+
+const esc = (text) => String(text ?? "").replace(/[&<>"]/gu, (c) => ({ "&": "&amp;", "<": "&gt;", '"': "&quot;" }[c] ?? c));
+const secs = (v) => `${Number(v).toFixed(1)}`;
+
+/** Tile geometry: columns and thumbnail size for n shots of a film of size width x height. */
+export function boardGrid(n, width, height) {
+  const usableW = BOARD.width - 2 * BOARD.margin;
+  const usableH = BOARD.height - BOARD.header - BOARD.footer - BOARD.margin;
+  const aspect = width / height;
+  const options = [];
+  for (let cols = 1; cols <= Math.max(1, n); cols++) {
+    const rows = Math.ceil(n / cols);
+    const tw = Math.floor((usableW - (cols - 1) * BOARD.gap) / cols);
+    const byHeight = Math.floor((usableH - (rows - 1) * BOARD.gap) / rows) - BOARD.caption;
+    const th = Math.min(Math.round(tw / aspect), byHeight);
+    if (th <= 0) continue;
+    options.push({ cols, rows, tw: Math.round(th * aspect), th, empty: rows * cols - n });
+  }
+  // The largest tiles, unless a grid with fewer empty slots keeps 85 % of their area.
+  const largest = Math.max(...options.map((o) => o.tw * o.th));
+  return options.filter((o) => o.tw * o.th >= 0.85 * largest).sort((a, b) => a.empty - b.empty || b.tw * b.th - a.tw * a.th)[0];
+}
+
+/** The board page's HTML for a treatment and its beat stills (file names relative to the page). */
+export function boardHtml({ treatment, stills, check = null }) {
+  const style = treatment.style ? readStyle(treatment.style) : null;
+  const [width, height] = treatment.format === "9:16" ? [1080, 1920] : [1920, 1080];
+  const grid = boardGrid(stills.length, width, height);
+  const zones = LAYOUTS[treatment.format === "9:16" ? "9:16" : "16:9"];
+  const pal = style?.palette ?? {};
+  const chips = Object.entries(pal).filter(([k]) => ["ground", "ink", "muted", "signal", "accent"].includes(k))
+    .map(([k, v]) => `<span class="chip"><i style="background:${esc(v)}"></i>${esc(k)} ${esc(v)}</span>`).join("");
+  const tiles = stills.map((file, i) => {
+    const b = treatment.beats[i] ?? {};
+    const z = b.layout && zones[b.layout]?.type;
+    const guide = z ? `<b class="zone" style="left:${(z[0] * 100).toFixed(2)}%;top:${(z[1] * 100).toFixed(2)}%;width:${(z[2] * 100).toFixed(2)}%;height:${(z[3] * 100).toFixed(2)}%"></b>` : "";
+    const handoff = b.transition && b.transition !== "end" ? `→ ${b.transition}` : b.transition;
+    const meta = [String(i + 1).padStart(2, "0"), `${secs(b.t0)}–${secs(b.t1)} s`, b.layout, handoff].filter(Boolean).map(esc).join("  ·  ");
+    return `<figure style="width:${grid.tw}px"><div class="frame" style="width:${grid.tw}px;height:${grid.th}px"><img src="${esc(file)}">${guide}</div>`
+      + `<figcaption><span class="meta">${meta}</span><span class="hero">${esc(b.hero ?? b.onScreen ?? "")}</span></figcaption></figure>`;
+  }).join("");
+  const failed = (check?.rules ?? []).filter((x) => x.status === "FAIL");
+  const verdict = !check ? "layout check: not run on this render"
+    : failed.length ? `layout check: FAIL — ${failed.map((x) => x.id).join(", ")}` : "layout check: PASS";
+  const sound = treatment.sound?.mode === "generated" && typeof treatment.sound.palette === "object"
+    ? `${treatment.sound.palette.timbre}, ${treatment.sound.palette.key} ${treatment.sound.palette.mode}, ${treatment.sound.palette.tempo} BPM`
+    : treatment.sound?.mode === "score" ? `score (${treatment.sound.genre ?? style?.score?.genre ?? "house"})` : treatment.sound?.mode ?? "none";
+  const ground = pal.ground ?? "#101216";
+  return `<!doctype html>
+<meta charset="utf-8">
+<link rel="stylesheet" href="/lit/fonts.css">
+<link rel="stylesheet" href="/lit/style.css">
+<script src="/lit/stage-kit.js"></script>
+<style>
+  html, body { margin: 0; width: ${BOARD.width}px; height: ${BOARD.height}px; overflow: hidden; background: #15171b; color: #e8e9e6; font-family: "Pretendard"; }
+  header { position: absolute; left: ${BOARD.margin}px; right: ${BOARD.margin}px; top: 36px; height: ${BOARD.header - 48}px; display: flex; justify-content: space-between; align-items: flex-start; }
+  h1 { margin: 0; font: 700 40px/1.1 "Pretendard"; }
+  .sub { margin-top: 10px; font: 400 20px/1.3 "MesloLGS NF"; color: #a8aba6; }
+  .style { text-align: right; }
+  .specimen { display: inline-block; padding: 6px 14px; margin-bottom: 10px; background: ${esc(ground)}; color: ${esc(pal.ink ?? "#fff")}; font: ${style?.faces.display.weight ?? 700} 34px/1.1 "${esc(style?.faces.display.family ?? "Pretendard")}", "Pretendard"; }
+  .chips { display: flex; gap: 14px; justify-content: flex-end; font: 400 16px/1 "MesloLGS NF"; color: #a8aba6; }
+  .chip i { display: inline-block; width: 16px; height: 16px; margin-right: 6px; vertical-align: -3px; border: 1px solid #555; }
+  main { position: absolute; left: ${BOARD.margin}px; right: ${BOARD.margin}px; top: ${BOARD.header}px; display: flex; flex-wrap: wrap; gap: ${BOARD.gap}px; }
+  figure { margin: 0; }
+  .frame { position: relative; overflow: hidden; background: #000; }
+  .frame img { display: block; width: 100%; height: 100%; }
+  .zone { position: absolute; box-sizing: border-box; border: 2px dashed rgba(255, 196, 0, 0.75); }
+  figcaption { display: block; height: ${BOARD.caption - 8}px; padding-top: 8px; overflow: hidden; }
+  .meta { display: block; font: 400 16px/1.3 "MesloLGS NF"; color: #c9cbc6; }
+  .hero { display: block; margin-top: 4px; font: 400 18px/1.35 "Pretendard"; color: #e8e9e6; }
+  footer { position: absolute; left: ${BOARD.margin}px; right: ${BOARD.margin}px; bottom: 18px; font: 400 18px/1.2 "MesloLGS NF"; color: ${failed.length ? "#ff8a7a" : "#9fd3a4"}; }
+</style>
+<body>
+<header>
+  <div><h1>Storyboard · ${esc(treatment.subject?.name ?? "")}</h1>
+  <div class="sub">${esc(treatment.format)} · ${esc(treatment.durationSec)} s · ${treatment.beats.length} shots · ${esc(treatment.path)} path · sound: ${esc(sound)}</div></div>
+  <div class="style"><div class="specimen">${esc(style?.name ?? treatment.style ?? "")} Aa 가</div><div class="chips">${chips}</div></div>
+</header>
+<main>${tiles}</main>
+<footer>${esc(verdict)} · dashed box: the shot's type zone</footer>
+<script>LitStage.define({ width: ${BOARD.width}, height: ${BOARD.height}, fps: 30, duration: 1, render() {} });</script>
+</body>
+`;
+}
+
+/**
+ * Render `<out>/stills/board.png` from the beat stills already written. Returns the file path.
+ * `check` is the layout check ({ rules }) when one ran.
+ */
+export async function writeBoard({ out, treatment, beatFiles, check = null, env = process.env, log = () => {} }) {
+  const executable = resolveChrome(env);
+  if (!executable) throw new Error("writeBoard needs Chrome: set CHROME_PATH");
+  const dir = path.join(out, ".run", "board");
+  rmSync(dir, { recursive: true, force: true });
+  mkdirSync(dir, { recursive: true });
+  const names = beatFiles.map((f, i) => {
+    const name = `s${String(i + 1).padStart(2, "0")}.png`;
+    copyFileSync(f, path.join(dir, name));
+    return name;
+  });
+  writeFileSync(path.join(dir, "index.html"), boardHtml({ treatment, stills: names, check }));
+  const faces = [...new Set([...(treatment.typePlan?.faces ?? ["Pretendard"]), "Pretendard"])];
+  let style = null;
+  if (treatment.style) {
+    const { readStyle, styleCss, styleScript } = await import("./styles.mjs");
+    const declared = readStyle(treatment.style);
+    style = { css: styleCss(declared, treatment.format), js: styleScript(declared, treatment.format, treatment) };
+  }
+  const session = await openStage({
+    executable, outDir: out, stageDir: dir, width: BOARD.width, height: BOARD.height,
+    fps: 30, seed: 1, fonts: stageFonts(faces, env), style, label: "b", log,
+  });
+  try {
+    await session.load();
+    await session.step(0, 30);
+    const png = await session.capture();
+    const file = path.join(out, "stills", "board.png");
+    mkdirSync(path.join(out, "stills"), { recursive: true });
+    writeFileSync(file, png);
+    return file;
+  } finally {
+    await session.close();
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** Add a renderer-written file to stills/index.json; returns the new index SHA-256. */
+export function addToStills(out, entry, { sha256 }) {
+  const indexFile = path.join(out, "stills", "index.json");
+  const index = JSON.parse(readFileSync(indexFile, "utf8"));
+  const file = path.join(out, entry.file);
+  if (!existsSync(file)) throw new Error(`addToStills: ${entry.file} was not written`);
+  index.stills = [...(index.stills ?? []).filter((f) => f.file !== entry.file), { ...entry, sha256: sha256(readFileSync(file)) }];
+  const bytes = Buffer.from(`${JSON.stringify(index, null, 2)}\n`);
+  writeFileSync(indexFile, bytes);
+  return sha256(bytes);
+}

package/.grok/skills/lit-typographic-motion/scripts/lib/chrome.mjs

@@ -194,13 +194,18 @@ export async function openRenderer({ executable, profileDir, softwareOnly = fals
 export const STAGE_FLAGS = Object.freeze(['--run-all-compositor-stages-before-draw', '--disable-checker-imaging', '--disable-new-content-rendering-timeout', '--disable-threaded-animation', '--disable-threaded-scrolling', '--disable-image-animation-resync', '--disable-lcd-text', '--force-color-profile=srgb', '--hide-scrollbars', '--mute-audio', '--force-device-scale-factor=1', '--disable-background-networking', '--disable-component-update', '--disable-sync', '--no-pings', '--metrics-recording-only']);
 
 // `scale` is the device scale: 1 for a film; a cover is captured at 2 and shrunk afterwards.
-// `extra` flags ride after the stage set (a cover adds COVER_FLAGS).
-export function stageArgs({ profileDir, width, height, scale = 1, extra = [] }) {
+// `extra` flags ride after the stage set (a cover adds COVER_FLAGS). The gpu rung uses the
+// platform's GL flags with page raster on the CPU; anything else is the SwiftShader rung.
+export function stageArgs({ profileDir, width, height, scale = 1, extra = [], rung = 'software', platform = osPlatform() }) {
   const flags = STAGE_FLAGS.map((flag) => (flag === '--force-device-scale-factor=1' ? `--force-device-scale-factor=${scale}` : flag));
-  const args = [...HOUSEKEEPING, `--user-data-dir=${profileDir}`, ...SWIFTSHADER_RUNG, ...COMMON_FLAGS, ...flags, `--window-size=${width},${height}`, `--host-resolver-rules=MAP * ~NOTFOUND , EXCLUDE ${STAGE.host}`, ...extra];
+  const rungFlags = rung === 'gpu' ? (gpuRungs(platform)[0] ?? []).filter((flag) => flag !== '--enable-gpu-rasterization') : SWIFTSHADER_RUNG;
+  const args = [...HOUSEKEEPING, `--user-data-dir=${profileDir}`, ...rungFlags, ...COMMON_FLAGS, ...flags, `--window-size=${width},${height}`, `--host-resolver-rules=MAP * ~NOTFOUND , EXCLUDE ${STAGE.host}`, ...extra];
   return [...new Set(args), 'about:blank'];
 }
 
+// The rung counts only when the page gets a WebGL2 context; the renderer string is recorded.
+const WEBGL_PROBE = `(() => { const canvas = document.createElement('canvas'); const gl = canvas.getContext('webgl2'); if (!gl) return { webgl2: false }; const info = gl.getExtension('WEBGL_debug_renderer_info'); return { webgl2: true, renderer: info ? gl.getParameter(info.UNMASKED_RENDERER_WEBGL) : ${JSON.stringify(UNKNOWN_RENDERER)} }; })()`;
+
 // Launch one stage Chrome and attach a page target. Exit 10 when Chrome is missing or never
 // answers; WebGL is not probed here (exit 11 applies only when the page asks for it).
 // A cover's frames are compared across fresh browsers and sought out of order. With GPU raster on
@@ -209,39 +214,63 @@ export function stageArgs({ profileDir, width, height, scale = 1, extra = [] })
 // frame identically in 5 of 5 pairs.
 export const COVER_FLAGS = Object.freeze(['--disable-gpu-rasterization']);
 
-export async function launchStage({ executable, profileDir, width, height, scale = 1, extra = [], timeoutMs = 30000 }) {
+// A 3D film asks for the gpu rung; when it cannot start or gives the page no WebGL2, the launch
+// falls back to the software rung and records why. Either way the launch reports the rung the page
+// got and its renderer string; without WebGL2 on any rung it is exit 11.
+export async function launchStage({ executable, profileDir, width, height, scale = 1, extra = [], timeoutMs = 30000, rung = 'software', platform = osPlatform() }) {
   if (!executable) throw new BlockedError(EXIT.NO_CHROME, 'BLOCKED_NO_CHROME: Chrome/Chromium not found; set CHROME_PATH to a Chrome executable');
   mkdirSync(profileDir, { recursive: true });
-  const args = stageArgs({ profileDir, width, height, scale, extra });
-  let stderr = '';
-  let proc;
-  try { proc = spawn(executable, args, { stdio: ['ignore', 'ignore', 'pipe', 'pipe', 'pipe'] }); } catch (error) { throw new BlockedError(EXIT.NO_CHROME, `BLOCKED_NO_CHROME: ${error.message}`); }
-  proc.stderr.setEncoding('utf8');
-  proc.stderr.on('data', (chunk) => { if (stderr.length < 16384) stderr += chunk; });
-  const spawnError = new Promise((_, reject) => proc.once('error', (error) => reject(error)));
-  const session = new PipeSession(proc);
-  const close = async () => {
-    if (proc.exitCode === null && proc.signalCode === null) {
-      try { await session.send('Browser.close', {}, undefined, 5000); } catch {}
-      await new Promise((resolve) => {
-        const timer = setTimeout(() => { try { proc.kill('SIGKILL'); } catch {} resolve(); }, 5000);
-        proc.once('exit', () => { clearTimeout(timer); resolve(); });
-        if (proc.exitCode !== null || proc.signalCode !== null) { clearTimeout(timer); resolve(); }
-      });
+  // Strict only for the gpu rung: a 3D page needs its WebGL context, while a 2D page renders
+  // without one (the renderer is then unknown, and the software label still holds).
+  const attempt = async (wanted, strict) => {
+    const args = stageArgs({ profileDir, width, height, scale, extra, rung: wanted, platform });
+    let stderr = '';
+    let proc;
+    try { proc = spawn(executable, args, { stdio: ['ignore', 'ignore', 'pipe', 'pipe', 'pipe'] }); } catch (error) { throw new BlockedError(EXIT.NO_CHROME, `BLOCKED_NO_CHROME: ${error.message}`); }
+    proc.stderr.setEncoding('utf8');
+    proc.stderr.on('data', (chunk) => { if (stderr.length < 16384) stderr += chunk; });
+    const spawnError = new Promise((_, reject) => proc.once('error', (error) => reject(error)));
+    const session = new PipeSession(proc);
+    const close = async () => {
+      if (proc.exitCode === null && proc.signalCode === null) {
+        try { await session.send('Browser.close', {}, undefined, 5000); } catch {}
+        await new Promise((resolve) => {
+          const timer = setTimeout(() => { try { proc.kill('SIGKILL'); } catch {} resolve(); }, 5000);
+          proc.once('exit', () => { clearTimeout(timer); resolve(); });
+          if (proc.exitCode !== null || proc.signalCode !== null) { clearTimeout(timer); resolve(); }
+        });
+      }
+      // Chrome's helpers can still be flushing the profile for a moment after the browser exits.
+      for (let retry = 0; retry < 20; retry += 1) {
+        try { rmSync(profileDir, { recursive: true, force: true }); break; } catch { await new Promise((resolve) => setTimeout(resolve, 100)); }
+      }
+    };
+    try {
+      await Promise.race([spawnError, session.send('Browser.getVersion', {}, undefined, timeoutMs)]);
+    } catch (error) {
+      await close();
+      throw new BlockedError(EXIT.NO_CHROME, `BLOCKED_NO_CHROME: Chrome failed to launch headless: ${firstLine(stderr) || error.message}`);
     }
-    // Chrome's helpers can still be flushing the profile for a moment after the browser exits.
-    for (let attempt = 0; attempt < 20; attempt += 1) {
-      try { rmSync(profileDir, { recursive: true, force: true }); break; } catch { await new Promise((resolve) => setTimeout(resolve, 100)); }
+    const { targetId } = await session.send('Target.createTarget', { url: 'about:blank' });
+    const { sessionId } = await session.send('Target.attachToTarget', { targetId, flatten: true });
+    const send = (method, params = {}, timeout) => session.send(method, params, sessionId, timeout);
+    await send('Runtime.enable').catch(() => {});
+    const probe = await send('Runtime.evaluate', { expression: WEBGL_PROBE, returnByValue: true }, timeoutMs).catch(() => null);
+    const found = probe?.result?.value;
+    if (!found?.webgl2) {
+      if (!strict) return { browser: { proc, session, sessionId, send, close, args, on: (listener) => session.listeners.add(listener) }, renderer: UNKNOWN_RENDERER };
+      await close();
+      return { webgl2: false, detail: firstLine(stderr) };
     }
+    return { browser: { proc, session, sessionId, send, close, args, on: (listener) => session.listeners.add(listener) }, renderer: found.renderer ?? UNKNOWN_RENDERER };
   };
-  try {
-    await Promise.race([spawnError, session.send('Browser.getVersion', {}, undefined, timeoutMs)]);
-  } catch (error) {
-    await close();
-    throw new BlockedError(EXIT.NO_CHROME, `BLOCKED_NO_CHROME: Chrome failed to launch headless: ${firstLine(stderr) || error.message}`);
+  const first = await attempt(rung, rung === 'gpu');
+  if (first.browser) return { ...first.browser, rung, renderer: first.renderer, notice: null };
+  if (rung === 'gpu') {
+    const fallback = await attempt('software', false);
+    if (fallback.browser) {
+      return { ...fallback.browser, rung: 'software', renderer: fallback.renderer, notice: `the 3D route asked for the GPU rung and it gave the page no WebGL there${first.detail ? ` (${first.detail})` : ''}; rendered on the software rung (SwiftShader), slower, same frames` };
+    }
   }
-  const { targetId } = await session.send('Target.createTarget', { url: 'about:blank' });
-  const { sessionId } = await session.send('Target.attachToTarget', { targetId, flatten: true });
-  const send = (method, params = {}, timeout) => session.send(method, params, sessionId, timeout);
-  return { proc, session, sessionId, send, close, args, on: (listener) => session.listeners.add(listener) };
+  throw new BlockedError(EXIT.NO_WEBGL2, `BLOCKED_NO_WEBGL2: Chrome ran but no rung produced a WebGL2 context${first.detail ? ` (${first.detail})` : ''}`);
 }

package/.grok/skills/lit-typographic-motion/scripts/lib/constants.mjs

@@ -171,11 +171,13 @@ export const DIRECTOR = Object.freeze({
   durationRange: Object.freeze([4, 90]),
   minBeatSec: 1.2,
   maxGapSec: 0.25,
-  deviceKinds: Object.freeze(['illustration', 'diagram', 'chart', 'icon', 'shape', 'path', 'mask', 'depth3d', 'particles', 'grid', 'gradient', 'photo-texture']),
+  deviceKinds: Object.freeze(['illustration', 'diagram', 'chart', 'icon', 'shape', 'path', 'mask', 'depth3d', 'screen', 'particles', 'grid', 'gradient', 'photo-texture']),
+  protagonistKinds: Object.freeze(['character', 'object']),
+  assetRoles: Object.freeze(['logo', 'wordmark', 'icon', 'photo', 'screenshot', 'ui', 'readme-image']),
   textureKinds: Object.freeze(['grid', 'gradient', 'particles', 'photo-texture']),
   subjectCoverage: 0.5,
   faces: Object.freeze(['Archivo', 'Pretendard', 'VT323', 'Silkscreen', 'Galmuri9', 'Meslo']),
-  soundModes: Object.freeze(['generated', 'supplied', 'authored', 'none']),
+  soundModes: Object.freeze(['score', 'generated', 'supplied', 'authored', 'none']),
   timbres: Object.freeze(['glass', 'felt', 'pulse']),
 });
 

package/.grok/skills/lit-typographic-motion/scripts/lib/cover-capture.mjs

@@ -1,17 +1,17 @@
-// Cover capture: one stage Chrome (the software rung and every stage flag, so a mismatch is always
-// the page's doing) laid out at the cover's CSS size and captured at device scale 2. The page is
-// served from <out>/cover/ on the synthetic stage origin through CDP Fetch interception, beside the
-// /lit/ routes (fonts, the loop kit), and the cover init script runs before any page script. The
-// renderer SEEKS: it calls window.renderFrame(t, { mask }) for any t in [0, 1) in any order, so the
-// master pass, the replay in a fresh browser, the seek-order pass and a window re-render each open
-// their own page here.
+// Cover capture: one stage Chrome (the rung the recipe asks for, every stage flag, so a mismatch is
+// always the page's doing) laid out at the cover's CSS size and captured at device scale 2. The
+// page is served from <out>/cover/ on the synthetic stage origin through CDP Fetch interception,
+// beside the /lit/ routes (fonts, the loop kit, the vendored three.js), and the cover init script
+// runs before any page script. The renderer SEEKS: it calls window.renderFrame(t, { mask }) for any
+// t in [0, 1) in any order, so the master pass, the replay in a fresh browser, the seek-order pass
+// and a window re-render each open their own page here.
 import { randomBytes } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { BlockedError, EXIT, STAGE } from './constants.mjs';
 import { COVER_FLAGS, launchStage, resolveChrome } from './chrome.mjs';
 import { SKILL_ROOT } from './fonts.mjs';
-import { CONTENT_TYPES, resolveStagePath } from './stage-session.mjs';
+import { CONTENT_TYPES, resolveStagePath, resolveThree } from './stage-session.mjs';
 
 export const LOOP_KIT_PATH = join(SKILL_ROOT, 'scripts', 'stage', 'loop-kit.js');
 export const COVER_INIT_PATH = join(SKILL_ROOT, 'scripts', 'stage', 'cover-init.js');
@@ -19,11 +19,12 @@ export const COVER_INIT_PATH = join(SKILL_ROOT, 'scripts', 'stage', 'cover-init.
 const sleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); });
 
 // Open one cover page and wait for window.ready. `dir` is the folder served as the site root
-// (<out>/cover for a render; the sheet's own folder for the contact sheet).
-export async function openCover({ dir, fonts, width, height, scale, profileRoot, env = process.env, label = 'c', log = () => {} }) {
+// (<out>/cover for a render; the sheet's own folder for the contact sheet). A hero-3d cover asks
+// for the GPU rung; anything else renders on software, where a mismatch is always the page's doing.
+export async function openCover({ dir, fonts, width, height, scale, profileRoot, env = process.env, label = 'c', rung = 'software', log = () => {} }) {
   const executable = resolveChrome(env);
   if (!executable) throw new BlockedError(EXIT.NO_CHROME, 'BLOCKED_NO_CHROME: Chrome/Chromium not found; set CHROME_PATH to a Chrome executable');
-  const browser = await launchStage({ executable, profileDir: join(profileRoot, `${label}-${randomBytes(3).toString('hex')}`), width, height, scale, extra: COVER_FLAGS });
+  const browser = await launchStage({ executable, profileDir: join(profileRoot, `${label}-${randomBytes(3).toString('hex')}`), width, height, scale, extra: COVER_FLAGS, rung });
   const network = [];
   const refused = [];
   const errors = [];
@@ -46,6 +47,13 @@ export async function openCover({ dir, fonts, width, height, scale, profileRoot,
       return;
     }
     if (url.pathname === '/lit/loop-kit.js') { await respond(requestId, 200, kit, CONTENT_TYPES['.js']); return; }
+    if (url.pathname.startsWith('/lit/three/')) {
+      const resolved = resolveThree(url.pathname);
+      if (resolved.refused) { refused.push(resolved.refused); await respond(requestId, 403, 'refused'); return; }
+      if (resolved.missing) { await respond(requestId, 404, 'not a vendored three.js file'); return; }
+      await respond(requestId, 200, readFileSync(resolved.file), resolved.type);
+      return;
+    }
     if (url.pathname === '/lit/fonts.css') { await respond(requestId, 200, fonts.css, CONTENT_TYPES['.css']); return; }
     if (url.pathname.startsWith('/lit/fonts/')) {
       const route = fonts.routes.get(url.pathname);
@@ -103,6 +111,7 @@ export async function openCover({ dir, fonts, width, height, scale, profileRoot,
 
   return {
     width, height, scale,
+    rung: browser.rung, renderer: browser.renderer, notice: browser.notice,
     // Draw loop time t (or its title mask), then wait for fonts and two native frames.
     async frame(t, { mask = false } = {}) {
       try {

package/.grok/skills/lit-typographic-motion/scripts/lib/cover-treatment.mjs

@@ -7,9 +7,9 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { BlockedError, COVER, EXIT } from './constants.mjs';
-import { normalize, restateLimit, sentenceCount, sharedRun, stripQuoted } from './treatment.mjs';
+import { normalize, normUrl, requestUrls, restateLimit, sentenceCount, sharedRun, stripQuoted } from './treatment.mjs';
 
-export const RECIPES = Object.freeze(['painted-light', 'weight-tide', 'orbit-loop', 'own']);
+export const RECIPES = Object.freeze(['hero-3d', 'painted-light', 'weight-tide', 'orbit-loop', 'own']);
 export const LAYERS = Object.freeze(['slow', 'mid', 'beat']);
 
 const PLACEHOLDER = /<[^<>\n]{1,80}>|^\s*(?:todo|tbd|tk|xxx|\.\.\.|…)\s*$/iu;
@@ -76,6 +76,19 @@ export function validateCoverTreatment(t) {
     }
   }
   if ('seed' in t && !Number.isInteger(t.seed)) return bad('seed', 'seed must be an integer');
+  // A link in the request names the product: the cover is built from its real assets, fetched first.
+  {
+    const urls = requestUrls(t.request);
+    if (!('product' in t) || t.product === null) {
+      if (urls.length) return bad('product', `product is missing: the request links ${urls[0]}; fetch its real assets first with motion.mjs assets --out <dir> --url <link> --cover, look at them, and set product { name, url }`);
+    } else {
+      const product = t.product;
+      if (!product || typeof product !== 'object') return bad('product', 'product must be an object { name, url }');
+      if (typeof product.name !== 'string' || !product.name.trim() || PLACEHOLDER.test(product.name)) return bad('product.name', 'product.name names the product');
+      if (urls.length && !urls.includes(normUrl(product.url ?? ''))) return bad('product.url', `product.url must be the link the request gives (${urls.join(', ')})`);
+      if ('unreachable' in product && product.unreachable !== undefined && product.unreachable !== null && (typeof product.unreachable !== 'string' || !product.unreachable.trim())) return bad('product.unreachable', 'product.unreachable says what could not be reached and why');
+    }
+  }
   const ambition = prose(t, 'ambition', 2);
   if (ambition) return ambition;
   const { page, out } = COVER.aspects[t.aspect];
@@ -95,6 +108,17 @@ export function loadCoverTreatment(outDir) {
   if (parsed?.mode !== 'cover') throw new BlockedError(EXIT.TREATMENT_INVALID, 'BLOCKED_TREATMENT_INVALID field=mode: this treatment is a film; render it with stage or make (references/treatment.md); a cover sets mode: cover');
   const result = validateCoverTreatment(parsed);
   if (!result.ok) throw new BlockedError(EXIT.TREATMENT_INVALID, `BLOCKED_TREATMENT_INVALID field=${result.field}: ${result.message}`);
+  // A linked cover is built only from fetched assets: product.json must exist, list cover files,
+  // and an unreachable product stops with exit 22 until the user supplies the art.
+  const coverProduct = result.treatment.product;
+  if (coverProduct?.unreachable) throw new BlockedError(EXIT.ASSET_MISSING, `BLOCKED_ASSET_MISSING: ${coverProduct.name}'s real assets could not be reached (${coverProduct.unreachable}); ask the user for its logo or README images, put them in ${join(outDir, 'cover', 'assets')} and list them in assets.json`);
+  if (coverProduct && !existsSync(join(outDir, 'product.json'))) throw new BlockedError(EXIT.TREATMENT_INVALID, `BLOCKED_TREATMENT_INVALID field=product: no ${join(outDir, 'product.json')}: run motion.mjs assets --out ${outDir} --url ${coverProduct.url} --cover first`);
+  if (coverProduct) {
+    let fetched;
+    try { fetched = JSON.parse(readFileSync(join(outDir, 'product.json'), 'utf8'))?.product?.assets ?? []; } catch (error) { throw new BlockedError(EXIT.TREATMENT_INVALID, `BLOCKED_TREATMENT_INVALID field=product: ${join(outDir, 'product.json')} is not valid JSON (${error.message}); run motion.mjs assets --out ${outDir} --url ${coverProduct.url} --cover again`); }
+    const astray = fetched.filter((asset) => !String(asset?.path ?? '').startsWith('cover/assets/'));
+    if (astray.length) throw new BlockedError(EXIT.TREATMENT_INVALID, `BLOCKED_TREATMENT_INVALID field=product: ${astray[0].path} sits outside cover/assets/, where the cover page cannot load it; run motion.mjs assets --out ${outDir} --url ${coverProduct.url} --cover again`);
+  }
   const first = join(outDir, '.run', 'treatment-first.json');
   if (!existsSync(first)) {
     mkdirSync(join(outDir, '.run'), { recursive: true });

package/.grok/skills/lit-typographic-motion/scripts/lib/cover.mjs

@@ -210,17 +210,24 @@ export async function renderCover({ out, round = 1, env = process.env, log = (li
     const order = seekOrder(times.length, treatment.seed);
     const pool = new CoverPool();
     let master, replay, sought;
+    // A 3D hero turns on the GPU rung; when it cannot start there it falls back to software, and
+    // the report says so. The replay and the seek share the master's rung.
+    const rung = treatment.recipe === 'hero-3d' ? 'gpu' : 'software';
+    let rungUsed = rung, rendererUsed = null;
     try {
-      const open = (label) => openCover({ dir, fonts, width: pageW, height: pageH, scale: COVER.captureScale, profileRoot: runDir, env, label, log });
+      const open = (label, useRung) => openCover({ dir, fonts, width: pageW, height: pageH, scale: COVER.captureScale, profileRoot: runDir, env, label, rung: useRung ?? rung, log });
       const a = await open('master');
       try {
         master = await capturePass({ page: a, pool, times, dir: dirs.frames, prefix: 'f', width: w, height: h });
         log(`cover: master ${times.length} frames (${((Date.now() - started) / 1000).toFixed(1)} s)`);
         await capturePass({ page: a, pool, times, dir: dirs.masks, prefix: 'm', mask: true, width: w, height: h });
+        rungUsed = a.rung;
+        rendererUsed = a.renderer;
+        if (a.notice) { warnings.push(a.notice); log(`warning: ${a.notice}`); }
       } finally { await a.close(); }
-      const b = await open('replay');
+      const b = await open('replay', rungUsed);
       try { replay = await capturePass({ page: b, pool, times, dir: dirs.frames2, prefix: 'f', width: w, height: h }); } finally { await b.close(); }
-      const c = await open('seek');
+      const c = await open('seek', rungUsed);
       try { sought = await capturePass({ page: c, pool, times: order.map((i) => times[i]), dir: dirs.seek, prefix: 's', width: w, height: h }); } finally { await c.close(); }
     } finally { await pool.close(); }
     const captureSec = (Date.now() - started) / 1000;
@@ -279,7 +286,7 @@ export async function renderCover({ out, round = 1, env = process.env, log = (li
     const summary = { pass: gate.pass, target: gate.target, medianD: gate.medianD, movingFrac: gate.movingFrac, longestStillSec: gate.longestStillSec, spike: gate.spike, seamLocal: gate.seamLocal, gates: gate.gates };
     writeJson(join(out, 'manifest.json'), {
       schemaVersion: 1, path: 'cover', mode: 'cover', round, recipe: treatment.recipe, treatmentSha256, stillsIndexSha256: indexed.sha256,
-      page: treatment.page, size: treatment.out, scale: COVER.captureScale, fps: treatment.fps, frames: times.length, frameMs: ms, seed: treatment.seed,
+      page: treatment.page, size: treatment.out, scale: COVER.captureScale, fps: treatment.fps, frames: times.length, frameMs: ms, seed: treatment.seed, rung: rungUsed, renderer: rendererUsed ? `${rendererUsed} on the ${rungUsed} rung (cover path)` : null,
       encoder: encoded.encoder, encode: treatment.encode, file: encoded.file.split('/').at(-1), bytes: statSync(encoded.file).size, captureSec, warnings, gate: summary,
     });
     if (!flash.pass) {
@@ -326,7 +333,7 @@ export async function renderCoverWindow({ out, round = 1, window: [t0, t1], env
   mkdirSync(profileRoot, { recursive: true });
   const pool = new CoverPool();
   try {
-    const page = await openCover({ dir: coverDir, fonts, width: treatment.page[0], height: treatment.page[1], scale: COVER.captureScale, profileRoot, env, label: 'window', log });
+    const page = await openCover({ dir: coverDir, fonts, width: treatment.page[0], height: treatment.page[1], scale: COVER.captureScale, profileRoot, env, label: 'window', rung: treatment.recipe === 'hero-3d' ? 'gpu' : 'software', log });
     try { await capturePass({ page, pool, times: [...new Set(picks.map((p) => p.index))].map((i) => [i, i / treatment.frames]), dir, prefix: 'f', width: w, height: h }); } finally { await page.close(); }
   } finally { await pool.close(); }
   const file = (i) => join(dir, `f${pad4(i)}.png`);

package/.grok/skills/lit-typographic-motion/scripts/lib/frame-pool.mjs

@@ -33,12 +33,89 @@ export function luminanceP995(rgba) {
   return 1;
 }
 
+const luma8 = (rgba, i) => Math.round((0.2126 * rgba[i] + 0.7152 * rgba[i + 1] + 0.0722 * rgba[i + 2]));
+
+/** Gamma-light luminance percentile (0..1) of an opaque RGBA frame. */
+export function luminancePercentile(rgba, q) {
+  const bins = new Uint32Array(256);
+  const total = rgba.length / 4;
+  for (let i = 0; i < rgba.length; i += 4) bins[luma8(rgba, i)] += 1;
+  const target = total * q;
+  let acc = 0;
+  for (let i = 0; i < 256; i += 1) { acc += bins[i]; if (acc >= target) return i / 255; }
+  return 1;
+}
+
+// The frame cut into 4 x 3 regions for the rich-fill rule.
+export const FILL_GRID = Object.freeze({ cols: 4, rows: 3 });
+
+/**
+ * Share of 48 px cells that carry something: a cell is busy when its luma varies (sd > 6) or its
+ * mean sits more than 16 levels off the frame's ground, the most common luma smoothed over +-3.
+ * Sampled on a 3 px lattice; an opaque RGBA frame in, a 0..1 share out.
+ */
+export function busyShare(rgba, width, height, { cell = 48, step = 3 } = {}) {
+  const hist = new Uint32Array(256);
+  for (let y = 0; y < height; y += step) for (let x = 0; x < width; x += step) hist[luma8(rgba, (y * width + x) * 4)] += 1;
+  let ground = 0;
+  let best = -1;
+  for (let i = 0; i < 256; i += 1) {
+    let s = 0;
+    for (let k = Math.max(0, i - 3); k <= Math.min(255, i + 3); k += 1) s += hist[k];
+    if (s > best) { best = s; ground = i; }
+  }
+  let busy = 0;
+  let cells = 0;
+  for (let cy = 0; cy + cell <= height; cy += cell) {
+    for (let cx = 0; cx + cell <= width; cx += cell) {
+      let s = 0;
+      let s2 = 0;
+      let n = 0;
+      let mean = 0;
+      for (let y = cy; y < cy + cell; y += step) for (let x = cx; x < cx + cell; x += step) {
+        const l = luma8(rgba, (y * width + x) * 4);
+        s += l; s2 += l * l; n += 1;
+      }
+      if (!n) continue;
+      mean = s / n;
+      const sd = Math.sqrt(Math.max(0, s2 / n - mean * mean));
+      if (sd > 6 || Math.abs(mean - ground) > 16) busy += 1;
+      cells += 1;
+    }
+  }
+  return cells ? busy / cells : 0;
+}
+
+/** The busy share of each region of the FILL_GRID, row by row. */
+export function regionFill(rgba, width, height) {
+  const out = [];
+  const rw = Math.floor(width / FILL_GRID.cols);
+  const rh = Math.floor(height / FILL_GRID.rows);
+  for (let r = 0; r < FILL_GRID.rows; r += 1) {
+    for (let c = 0; c < FILL_GRID.cols; c += 1) {
+      const sub = new Uint8Array(rw * rh * 4);
+      for (let y = 0; y < rh; y += 1) {
+        const from = ((r * rh + y) * width + c * rw) * 4;
+        sub.set(rgba.subarray(from, from + rw * 4), y * rw * 4);
+      }
+      out.push(busyShare(sub, rw, rh));
+    }
+  }
+  return out;
+}
+
 export function measureFrame(png, { flash = true } = {}) {
   const decoded = decodePng(png);
   const rgba = toRgba(decoded);
   const sha256 = createHash('sha256').update(rgba).digest('hex');
   const grid = flash ? cellGrid(rgba, decoded.width, decoded.height, 4) : null;
-  return { width: decoded.width, height: decoded.height, rgba, sha256, grid, lumP995: flash ? luminanceP995(rgba) : null };
+  return {
+    width: decoded.width, height: decoded.height, rgba, sha256, grid,
+    lumP995: flash ? luminanceP995(rgba) : null,
+    lumP005: luminancePercentile(rgba, 0.005),
+    busy: busyShare(rgba, decoded.width, decoded.height),
+    regions: regionFill(rgba, decoded.width, decoded.height),
+  };
 }
 
 if (!isMainThread && parentPort) {