@litfamily/litopencode 1.0.30 → 1.0.32

package/skills/lit-typographic-motion/engine/blender/runner.py

@@ -0,0 +1,228 @@
+# lit-typographic-motion: the offline Blender rung. Blender runs this headless:
+#   blender -b --factory-startup -P runner.py -- --scene scene.py --out DIR --width W --height H
+#           --percent P --samples S --device METAL --fps F --seed N (--stills t,t,... | --frames 1-N)
+# Cycles goes on the GPU (the wanted backend first, then any other that has a device, else the CPU,
+# and the receipt names which). The film's scene.py then runs with the `lit` helpers in scope, and the
+# runner renders one still per listed time (still-01.png ...) or the frame sequence (000001.png ...)
+# and writes receipt.json: the Blender version, engine, device, samples, size and the files written.
+import argparse
+import json
+import math
+import os
+import sys
+
+import bpy
+from mathutils import Vector
+
+GPU_BACKENDS = ("METAL", "OPTIX", "CUDA", "HIP", "ONEAPI")
+
+
+def arguments():
+    rest = sys.argv[sys.argv.index("--") + 1:] if "--" in sys.argv else []
+    parser = argparse.ArgumentParser(prog="runner.py")
+    parser.add_argument("--scene", required=True)
+    parser.add_argument("--out", required=True)
+    parser.add_argument("--width", type=int, required=True)
+    parser.add_argument("--height", type=int, required=True)
+    parser.add_argument("--percent", type=int, default=100)
+    parser.add_argument("--samples", type=int, default=128)
+    parser.add_argument("--device", default="METAL")
+    parser.add_argument("--fps", type=int, default=30)
+    parser.add_argument("--seed", type=int, default=0)
+    parser.add_argument("--stills")
+    parser.add_argument("--frames")
+    return parser.parse_args(rest)
+
+
+def use_gpu(scene, wanted):
+    """Put Cycles on a GPU backend that has a device, the wanted one first; the CPU when none does."""
+    prefs = bpy.context.preferences.addons["cycles"].preferences
+    for backend in dict.fromkeys((wanted, *GPU_BACKENDS)):
+        try:
+            prefs.compute_device_type = backend
+        except TypeError:
+            continue
+        prefs.get_devices()
+        chosen = [d for d in prefs.devices if d.type == backend]
+        if chosen:
+            for d in prefs.devices:
+                d.use = d.type == backend
+            scene.cycles.device = "GPU"
+            return backend
+    scene.cycles.device = "CPU"
+    return "CPU"
+
+
+def srgb_to_linear(value):
+    return value / 12.92 if value <= 0.04045 else ((value + 0.055) / 1.055) ** 2.4
+
+
+class Lit:
+    """What scene.py may call. Times are film seconds; the plate's first frame is frame 1."""
+
+    def __init__(self, fps):
+        self.fps = fps
+
+    def frame(self, t):
+        return int(round(t * self.fps)) + 1
+
+    def key(self, obj, prop, t, value=None, index=-1):
+        """Set obj.<prop> when a value is given, then keyframe it at film time t."""
+        if value is not None:
+            setattr(obj, prop, value)
+        obj.keyframe_insert(data_path=prop, frame=self.frame(t), index=index)
+
+    def rgb(self, color):
+        """A #RRGGBB string, or a tuple already in linear space, as Blender's linear colour."""
+        if not isinstance(color, str):
+            return tuple(color)[:3]
+        digits = color.lstrip("#")
+        return tuple(srgb_to_linear(int(digits[i:i + 2], 16) / 255) for i in (0, 2, 4))
+
+    def look_at(self, obj, target):
+        aim = Vector(target) - obj.location
+        obj.rotation_euler = aim.to_track_quat("-Z", "Y").to_euler()
+
+    def material(self, name, color, roughness=0.4, metallic=0.0, emission=None, strength=0.0):
+        mat = bpy.data.materials.new(name)
+        mat.use_nodes = True
+        shader = mat.node_tree.nodes["Principled BSDF"]
+        shader.inputs["Base Color"].default_value = (*self.rgb(color), 1.0)
+        shader.inputs["Roughness"].default_value = roughness
+        shader.inputs["Metallic"].default_value = metallic
+        if emission is not None:
+            shader.inputs["Emission Color"].default_value = (*self.rgb(emission), 1.0)
+            shader.inputs["Emission Strength"].default_value = strength
+        return mat
+
+    def rounded_box(self, name, size, radius=0.08, segments=6, material=None, location=(0, 0, 0)):
+        """A box whose bevelled edges catch the light."""
+        bpy.ops.mesh.primitive_cube_add(size=1, location=location)
+        obj = bpy.context.active_object
+        obj.name = name
+        obj.scale = size
+        bpy.ops.object.transform_apply(scale=True)
+        bevel = obj.modifiers.new("bevel", "BEVEL")
+        bevel.width = radius
+        bevel.segments = segments
+        bevel.limit_method = "ANGLE"
+        bpy.ops.object.shade_smooth()
+        if material is not None:
+            obj.data.materials.append(material)
+        return obj
+
+    def image_card(self, name, image_path, width=1.0, location=(0, 0, 0), emission=1.0):
+        """A flat card showing a product image file at its own aspect ratio, lit from within."""
+        image = bpy.data.images.load(os.path.abspath(image_path))
+        w, h = image.size
+        bpy.ops.mesh.primitive_plane_add(size=1, location=location)
+        obj = bpy.context.active_object
+        obj.name = name
+        obj.scale = (width, width * h / max(w, 1), 1)
+        mat = bpy.data.materials.new(name)
+        mat.use_nodes = True
+        nodes, links = mat.node_tree.nodes, mat.node_tree.links
+        texture = nodes.new("ShaderNodeTexImage")
+        texture.image = image
+        shader = nodes["Principled BSDF"]
+        links.new(texture.outputs["Color"], shader.inputs["Base Color"])
+        links.new(texture.outputs["Color"], shader.inputs["Emission Color"])
+        links.new(texture.outputs["Alpha"], shader.inputs["Alpha"])
+        shader.inputs["Emission Strength"].default_value = emission
+        obj.data.materials.append(mat)
+        return obj
+
+    def area_light(self, name, location, target=(0, 0, 0), power=400.0, size=2.0, color="#FFFFFF"):
+        data = bpy.data.lights.new(name, "AREA")
+        data.energy = power
+        data.size = size
+        data.color = self.rgb(color)
+        obj = bpy.data.objects.new(name, data)
+        bpy.context.scene.collection.objects.link(obj)
+        obj.location = location
+        self.look_at(obj, target)
+        return obj
+
+    def camera(self, location, target=(0, 0, 0), lens=50.0, dof=None):
+        """The scene camera aimed at target; dof=(focus_distance, f_stop) turns depth of field on."""
+        data = bpy.data.cameras.new("camera")
+        data.lens = lens
+        if dof is not None:
+            data.dof.use_dof = True
+            data.dof.focus_distance, data.dof.aperture_fstop = dof
+        obj = bpy.data.objects.new("camera", data)
+        bpy.context.scene.collection.objects.link(obj)
+        obj.location = location
+        self.look_at(obj, target)
+        bpy.context.scene.camera = obj
+        return obj
+
+    def world(self, color, strength=1.0):
+        scene = bpy.context.scene
+        scene.world = scene.world or bpy.data.worlds.new("world")
+        scene.world.use_nodes = True
+        background = scene.world.node_tree.nodes["Background"]
+        background.inputs["Color"].default_value = (*self.rgb(color), 1.0)
+        background.inputs["Strength"].default_value = strength
+        return scene.world
+
+
+def configure(scene, a):
+    scene.render.engine = "CYCLES"
+    device = use_gpu(scene, a.device)
+    scene.cycles.samples = a.samples
+    scene.cycles.seed = a.seed
+    scene.cycles.use_denoising = True
+    scene.render.resolution_x = a.width
+    scene.render.resolution_y = a.height
+    scene.render.resolution_percentage = a.percent
+    scene.render.fps = a.fps
+    scene.render.use_motion_blur = True
+    image = scene.render.image_settings
+    image.file_format, image.color_mode, image.color_depth = "PNG", "RGB", "8"
+    return device
+
+
+def render_stills(scene, lit, a):
+    names = []
+    for index, t in enumerate(float(x) for x in a.stills.split(",")):
+        scene.frame_set(lit.frame(t))
+        names.append(f"still-{index + 1:02d}.png")
+        scene.render.filepath = os.path.join(a.out, names[-1])
+        bpy.ops.render.render(write_still=True)
+    return names
+
+
+def render_frames(scene, a):
+    first, last = (int(x) for x in a.frames.split("-"))
+    scene.frame_start, scene.frame_end = first, last
+    scene.render.filepath = os.path.join(a.out, "######")
+    bpy.ops.render.render(animation=True)
+    return [f"{n:06d}.png" for n in range(first, last + 1)]
+
+
+def main():
+    a = arguments()
+    os.makedirs(a.out, exist_ok=True)
+    bpy.ops.wm.read_factory_settings(use_empty=True)
+    scene = bpy.context.scene
+    device = configure(scene, a)
+    lit = Lit(a.fps)
+    with open(a.scene, encoding="utf-8") as handle:
+        code = compile(handle.read(), a.scene, "exec")
+    exec(code, {"bpy": bpy, "lit": lit, "math": math, "Vector": Vector, "__name__": "__main__", "__file__": a.scene})
+    if scene.camera is None:
+        raise SystemExit("scene.py made no camera: call lit.camera(...) or set bpy.context.scene.camera")
+    scene.cycles.samples = a.samples  # the command line has the last word on quality
+    scene.render.resolution_percentage = a.percent
+    names = render_stills(scene, lit, a) if a.stills else render_frames(scene, a)
+    receipt = {
+        "blender": bpy.app.version_string, "engine": "CYCLES", "device": device, "samples": a.samples,
+        "percent": a.percent, "width": a.width * a.percent // 100, "height": a.height * a.percent // 100,
+        "fps": a.fps, "files": [n for n in names if os.path.exists(os.path.join(a.out, n))],
+    }
+    with open(os.path.join(a.out, "receipt.json"), "w", encoding="utf-8") as handle:
+        json.dump(receipt, handle)
+
+
+main()

package/skills/lit-typographic-motion/engine/blender.mjs

@@ -0,0 +1,126 @@
+// The offline Blender rung. A 3D film with `render3d: "blender"` writes its world as a Blender Python
+// scene (<out>/stage/scene.py); `render.mjs blender` renders it headless with Cycles on the GPU through
+// the bundled runner: first preview stills at the shot midpoints (half size, few samples) to look at,
+// then with --final the full plate sequence in <out>/stage/plate/ with plate.json, the receipt the
+// stage trusts. The stage page shows the plate through LitStage.plate() and draws its type and labels
+// over it, so the page itself stays on the software rung. Without Blender the command renders nothing
+// and names the fallback: the three.js world on the GPU rung.
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { EXIT } from "./constants.mjs";
+import { StageError, readPlate } from "./stage/scan.mjs";
+import { frameSize, loadTreatment } from "./treatment.mjs";
+
+export { readPlate };
+
+export const BLENDER = Object.freeze({
+  macApp: "/Applications/Blender.app/Contents/MacOS/Blender",
+  runner: fileURLToPath(new URL("./blender/runner.py", import.meta.url)),
+  plateFps: 30,
+  device: "METAL",
+  preview: Object.freeze({ percent: 50, samples: 40 }),
+  final: Object.freeze({ percent: 100, samples: 160 })
+});
+
+// Where Blender is: an explicit LITOPENCODE_BLENDER path (used only if it exists, never second-guessed),
+// then the macOS app, then `blender` on PATH. Returns { path, source } or null.
+export function findBlender({ env = process.env, exists = existsSync, platform = process.platform } = {}) {
+  if (env.LITOPENCODE_BLENDER) return exists(env.LITOPENCODE_BLENDER) ? { path: env.LITOPENCODE_BLENDER, source: "LITOPENCODE_BLENDER" } : null;
+  if (platform === "darwin" && exists(BLENDER.macApp)) return { path: BLENDER.macApp, source: "app" };
+  for (const dir of String(env.PATH ?? "").split(path.delimiter).filter(Boolean)) {
+    const file = path.join(dir, "blender");
+    if (exists(file)) return { path: file, source: "PATH" };
+  }
+  return null;
+}
+
+export const plateFrames = (treatment) => Math.round(treatment.durationSec * BLENDER.plateFps);
+
+// The seed the stage page and the plate share, below 2^31 because Cycles takes a signed int.
+export const plateSeed = (seed) => (seed >>> 0) % 2147483648;
+
+// The headless command line: factory settings, the runner, and the runner's own arguments after `--`.
+export function blenderArgs({ treatment, scene, out, quality }) {
+  const q = BLENDER[quality];
+  if (quality !== "preview" && quality !== "final") throw new Error(`blenderArgs: quality is preview or final (got ${quality})`);
+  const { width, height } = frameSize(treatment);
+  const args = ["-b", "--factory-startup", "-P", BLENDER.runner, "--",
+    "--scene", scene, "--out", out, "--width", String(width), "--height", String(height),
+    "--percent", String(q.percent), "--samples", String(q.samples), "--device", BLENDER.device,
+    "--fps", String(BLENDER.plateFps), "--seed", String(plateSeed(Number.isSafeInteger(treatment.seed) ? treatment.seed : 0))];
+  if (quality === "preview") args.push("--stills", treatment.beats.map((b) => +((b.t0 + b.t1) / 2).toFixed(3)).join(","));
+  else args.push("--frames", `1-${plateFrames(treatment)}`);
+  return args;
+}
+
+const FALLBACK = (out) => [
+  "FALLBACK: no Blender found (LITOPENCODE_BLENDER, /Applications/Blender.app, blender on PATH), so nothing was rendered.",
+  `Set render3d to "three" in ${path.join(out, "treatment.json")} and build the world in three.js on the GPU rung (references/depth.md),`,
+  "and say in the reply that the film used the GPU rung because Blender is not installed."
+].join("\n");
+
+const usage = (detail) => Object.assign(new Error(detail), { exitCode: 2 });
+const listPngs = (dir) => (existsSync(dir) ? readdirSync(dir).filter((name) => name.endsWith(".png")).sort() : []);
+
+function runBlender({ bin, args, dir, expected, progress }) {
+  return new Promise((resolve) => {
+    const child = spawn(bin, args, { stdio: ["ignore", "pipe", "pipe"] });
+    let tail = "";
+    const keep = (chunk) => { tail = (tail + chunk).slice(-4000); };
+    child.stdout.on("data", keep);
+    child.stderr.on("data", keep);
+    const timer = progress ? setInterval(() => progress(listPngs(dir).length, expected), 2000) : null;
+    const done = (value) => { if (timer) clearInterval(timer); resolve(value); };
+    child.on("close", (code) => done({ code, tail }));
+    child.on("error", (error) => done({ code: -1, tail: error.message }));
+  });
+}
+
+// `render.mjs blender --out <dir> [--final]`. Preview: stills in stage/plate-preview/. Final: the plate
+// sequence in stage/plate/ and plate.json listing every frame by name and size, with the device,
+// samples and Blender version from the runner's receipt. Returns { code, message }.
+export async function blenderCommand({ out, final = false, env = process.env, log = () => {}, progress = null }) {
+  const { treatment } = loadTreatment(out);
+  if (treatment.path !== "stage" || treatment.render3d !== "blender") throw usage(`blender renders a stage treatment with render3d "blender" (this one is ${treatment.path === "stage" ? (treatment.render3d ?? "three") : "a type-path film"})`);
+  const stageDir = path.join(out, "stage");
+  const scene = path.join(stageDir, "scene.py");
+  if (!existsSync(scene)) throw new StageError(EXIT.STAGE_CONTRACT_ERROR, "STAGE_CONTRACT_ERROR", `${scene} is missing; write the Blender scene first (references/depth.md, the Blender rung)`);
+  const found = findBlender({ env });
+  if (!found) return { code: EXIT.OK, message: FALLBACK(out) };
+  const quality = final ? "final" : "preview";
+  const dir = path.join(stageDir, final ? "plate" : "plate-preview");
+  rmSync(dir, { recursive: true, force: true });
+  mkdirSync(dir, { recursive: true });
+  const args = blenderArgs({ treatment, scene, out: dir, quality });
+  const expected = final ? plateFrames(treatment) : treatment.beats.length;
+  log(`blender ${quality}: ${found.path} (${found.source}), ${expected} ${final ? "frames" : "stills"}`);
+  const run = await runBlender({ bin: found.path, args, dir, expected, progress });
+  const receiptFile = path.join(dir, "receipt.json");
+  if (run.code !== 0 || !existsSync(receiptFile)) {
+    throw new StageError(EXIT.STAGE_CONTRACT_ERROR, "STAGE_CONTRACT_ERROR", `Blender ${quality} failed (exit ${run.code}); fix stage/scene.py and run it again. Last output: ${run.tail.trim().split("\n").slice(-8).join(" | ")}`);
+  }
+  const receipt = JSON.parse(readFileSync(receiptFile, "utf8"));
+  const frames = receipt.files.map((name) => ({ name, bytes: statSync(path.join(dir, name)).size }));
+  if (frames.length !== expected) throw new StageError(EXIT.STAGE_CONTRACT_ERROR, "STAGE_CONTRACT_ERROR", `Blender wrote ${frames.length} of ${expected} ${final ? "frames" : "stills"}`);
+  const plate = { kind: quality, blender: receipt.blender, engine: receipt.engine, device: receipt.device, samples: receipt.samples, percent: receipt.percent, fps: BLENDER.plateFps, frames };
+  writeFileSync(path.join(dir, "plate.json"), `${JSON.stringify(plate, null, 1)}\n`);
+  const label = `Blender ${receipt.blender}, ${receipt.engine} ${receipt.device}, ${receipt.samples} spp at ${receipt.percent} %`;
+  if (!final) {
+    return { code: EXIT.OK, message: `BLENDER preview: ${frames.length} stills at the shot midpoints in ${dir} (${label}). Open them with the read tool, compare them with any reference frames the user gave, fix scene.py, then render the plate: blender --out ${out} --final` };
+  }
+  return { code: EXIT.OK, message: `BLENDER plate: ${frames.length} frames at ${BLENDER.plateFps} fps in ${dir} (${label}). Show it with LitStage.plate() under the type, then render the stage: stage --out ${out} --round N` };
+}
+
+// A Blender film needs its whole plate before the stage starts: returns the plate, throws exit 17 when
+// plate.json is missing, does not match its frames, or counts a different number of frames than the
+// film's length needs. Any other film returns null.
+export function requirePlate(treatment, stageDir) {
+  if (treatment.render3d !== "blender") return null;
+  const plate = readPlate(stageDir, "plate");
+  if (!plate) throw new StageError(EXIT.STAGE_CONTRACT_ERROR, "STAGE_CONTRACT_ERROR", `render3d is blender but stage/plate/plate.json is missing or does not match its frames; render the plate first: blender --out <dir> --final (no Blender: set render3d to "three" and use the GPU rung)`);
+  const want = plateFrames(treatment);
+  if (plate.frames.length !== want) throw new StageError(EXIT.STAGE_CONTRACT_ERROR, "STAGE_CONTRACT_ERROR", `the plate has ${plate.frames.length} frames; a ${treatment.durationSec} s film needs ${want} at ${BLENDER.plateFps} fps (render it again: blender --out <dir> --final)`);
+  return plate;
+}

package/skills/lit-typographic-motion/engine/board.mjs

@@ -0,0 +1,138 @@
+// The storyboard: `stills/board.png`, one page a person can read before the full render. One keyframe
+// per shot (the beat still) with the shot's number, time, layout, hand-off and hero move under it and
+// the shot's type zone outlined on the frame; a header with the house style (name, palette, type) and
+// the film's format, length and sound; a footer with the layout check. It is drawn as a page in the same
+// headless Chrome the stage uses, so its type is the product's own faces.
+import { createHash } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { LAYOUTS, readStyle } from "./styles.mjs";
+import { openStage } from "./stage/capture.mjs";
+
+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;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
+const secs = (v) => `${Number(v).toFixed(1)}`;
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+
+// Tile geometry (columns, 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 layout check as board rules: every gate row of the text QA that is not N/A.
+export function boardRules(checks) {
+  return Object.entries(checks).filter(([, row]) => !row.na).map(([id, row]) => ({ id, status: row.pass ? "PASS" : row.warn ? "WARN" : "FAIL", detail: row.detail }));
+}
+
+// The board page's HTML for a treatment and its beat stills (file names relative to the page).
+export function boardHtml({ treatment, stills, rules = null }) {
+  const style = treatment.style ? readStyle(treatment.style) : null;
+  const format = treatment.format === "9:16" ? "9:16" : "16:9";
+  const [width, height] = format === "9:16" ? [1080, 1920] : [1920, 1080];
+  const grid = boardGrid(stills.length, width, height);
+  const zones = LAYOUTS[format];
+  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 meta = [String(i + 1).padStart(2, "0"), `${secs(b.t0)}–${secs(b.t1)} s`, b.layout, b.transition && b.transition !== "end" ? `→ ${b.transition}` : b.transition].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 = (rules ?? []).filter((x) => x.status === "FAIL");
+  const verdict = !rules ? "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" && treatment.sound.palette
+    ? `${treatment.sound.palette}, ${treatment.sound.key}, ${treatment.sound.tempo} BPM`
+    : treatment.sound?.mode ?? "none";
+  const ground = pal.ground ?? "#101216";
+  return `<!doctype html>
+<meta charset="utf-8">
+<link rel="stylesheet" href="/lit/fonts.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>
+`;
+}
+
+// Draws `<out>/stills/board.png` from the beat stills already written. `context` is the stage context
+// (Chrome path, faces); `rules` is the layout check when one ran. Returns the file path.
+export async function writeBoard({ out, context, chromium, treatment, beatFiles, rules = null }) {
+  const dir = path.join(out, ".run", "board");
+  rmSync(dir, { recursive: true, force: true });
+  mkdirSync(dir, { recursive: true });
+  const names = beatFiles.map((file, i) => {
+    const name = `s${String(i + 1).padStart(2, "0")}.png`;
+    copyFileSync(file, path.join(dir, name));
+    return name;
+  });
+  writeFileSync(path.join(dir, "index.html"), boardHtml({ treatment, stills: names, rules }));
+  const stage = await openStage(chromium, { chromePath: context.chromePath, profile: path.join(out, ".run", "bd"), stageDir: dir, width: BOARD.width, height: BOARD.height, fps: 30, seed: 1, fonts: context.fonts });
+  try {
+    await stage.load(names.map((name) => `/${name}`));
+    await stage.step(0, true);
+    const file = path.join(out, "stills", "board.png");
+    writeFileSync(file, await stage.capture());
+    return file;
+  } finally {
+    await stage.close();
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+// Adds a file the renderer wrote after the stills set to `stills/stills.json`; returns the new index SHA-256.
+export function addToStills(out, entry) {
+  const indexFile = path.join(out, "stills", "stills.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.files = [...index.files.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/skills/lit-typographic-motion/engine/cover/assets.mjs

@@ -1,9 +1,10 @@
 // The cover's asset list, `<out>/assets.json`. Every raster the cover page can load (base art, logo,
-// wordmark, texture) is listed with its path, role, source (user: supplied; generated: made for this
-// cover and labelled so in the reply) and SHA-256, and the renderer checks the list before the first
-// capture. The art is supplied or generated, never replaced by a drawn stand-in: a listed file that
-// is missing stops the run as BLOCKED_ASSET_MISSING (exit 22), and so does the painted-light recipe
-// with no base art listed. After the render, decoded frame 0 must show the base art (artCheck).
+// wordmark, texture) is listed with its path, role, source (user: supplied; fetched: taken from the
+// product's own pages by `render.mjs assets --cover`; generated: made for this cover and labelled so
+// in the reply) and SHA-256, and the renderer checks the list before the first capture. The art is
+// supplied, fetched or generated, never replaced by a drawn stand-in: a listed file that is missing
+// stops the run as BLOCKED_ASSET_MISSING (exit 22), and so does the painted-light recipe with no
+// user-supplied base art listed. After the render, decoded frame 0 must show the base art (artCheck).
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
@@ -35,7 +36,7 @@ export function checkAssets({ out, treatment, rasters, coverDir = "cover" }) {
       if (!entry || typeof entry !== "object") throw badEntry(at, "must be an object");
       if (typeof entry.path !== "string" || !entry.path.startsWith(`${coverDir}/`) || entry.path.split("/").includes("..")) throw badEntry(`${at}.path`, `must be a path inside ${coverDir}/, relative to the output directory`);
       if (!ASSET_ROLES.includes(entry.role)) throw badEntry(`${at}.role`, `must be one of ${ASSET_ROLES.join(", ")}`);
-      if (!["user", "generated"].includes(entry.source)) throw badEntry(`${at}.source`, "must be user (supplied) or generated");
+      if (!["user", "fetched", "generated"].includes(entry.source)) throw badEntry(`${at}.source`, "must be user (supplied), fetched (by render.mjs assets --cover) or generated");
       if (!/^[0-9a-f]{64}$/u.test(entry.sha256 ?? "")) throw badEntry(`${at}.sha256`, "must be the file's SHA-256 (64 hex digits)");
       if ("box" in entry && !isBox(entry.box)) throw badEntry(`${at}.box`, "must be [x, y, w, h] as fractions of the cover, inside it");
       if (entry.role === "base-art" && !entry.box) throw badEntry(`${at}.box`, "base art needs the box it fills on the cover");
@@ -52,8 +53,10 @@ export function checkAssets({ out, treatment, rasters, coverDir = "cover" }) {
       if (sha256(readFileSync(real)) !== asset.sha256) throw stop(EXIT.STAGE_CONTRACT_ERROR, "STAGE_CONTRACT_ERROR", `${asset.path} no longer matches its sha256 in assets.json; list it again after changing it`);
     }
   }
-  if (treatment.recipe === "painted-light" && !assets.some((asset) => asset.role === "base-art")) {
-    throw stop(EXIT.BLOCKED_ASSET_MISSING, "BLOCKED_ASSET_MISSING", "the painted-light recipe relights a painting, and assets.json lists no base-art; supply the painting or generate it and list it, never draw a stand-in");
+  // The painted recipe relights a painting the user supplied. Without one the cover takes hero-3d
+  // (or weight-tide, orbit-loop) instead of a stand-in painting drawn for the occasion.
+  if (treatment.recipe === "painted-light" && !assets.some((asset) => asset.role === "base-art" && asset.source === "user")) {
+    throw stop(EXIT.BLOCKED_ASSET_MISSING, "BLOCKED_ASSET_MISSING", "the painted-light recipe relights a painting, and assets.json lists no base-art with source user: a painting the user supplied; without one, take hero-3d (or weight-tide, orbit-loop), never draw or generate a stand-in");
   }
   const listed = new Set(assets.map((asset) => asset.path));
   for (const raster of rasters) {

package/skills/lit-typographic-motion/engine/cover/capture.mjs

@@ -1,4 +1,4 @@
-// One cover browser: the stage path's software rung and stage flags at device scale 2, the cover
+// One cover browser: the stage path's software rung (the GPU rung for a 3D hero) and stage flags at device scale 2, the cover
 // page served from disk on the stage origin (engine/stage/capture.mjs serveStage, so no socket
 // listens), the loop kit at /lit/loop-kit.js, the product faces plus JetBrains Mono at
 // /lit/fonts.css, and the cover init script before any page script. The renderer SEEKS: it calls
@@ -23,9 +23,9 @@ const stageDir = path.join(here, "..", "stage");
  * software GL (canvas fillText, and DOM text at changing weights) came out one level apart on a
  * handful of pixels between them; CPU raster gives the same pixels every time.
  */
-export function coverChromeFlags(width, height, scale) {
-  const flags = stageChromeFlags(width, height).map((flag) => (flag === "--force-device-scale-factor=1" ? `--force-device-scale-factor=${scale}` : flag));
-  return [...flags, "--disable-gpu-rasterization", "--disable-partial-raster"];
+export function coverChromeFlags(width, height, scale, rung = "swiftshader") {
+  const flags = stageChromeFlags(width, height, rung).map((flag) => (flag === "--force-device-scale-factor=1" ? `--force-device-scale-factor=${scale}` : flag));
+  return [...new Set([...flags, "--disable-gpu-rasterization", "--disable-partial-raster"])];
 }
 
 /** The stage faces plus JetBrains Mono, a variable face with a real wght axis (100-800). */
@@ -60,8 +60,8 @@ export async function waitForCoverReady(tab, pageFailed, timeout = 60000) {
  * Launch a cover browser on `coverDir` and load its index.html. `page` is the CSS size; screenshots
  * are `scale` times that. Returns { frame(t, { mask }), capture(), close(), flags }.
  */
-export async function openCover(chromium, { chromePath, profile, coverDir, page: [width, height], scale, fonts }) {
-  const flags = coverChromeFlags(width, height, scale);
+export async function openCover(chromium, { chromePath, profile, coverDir, page: [width, height], scale, fonts, rung = "swiftshader" }) {
+  const flags = coverChromeFlags(width, height, scale, rung);
   let context;
   try {
     context = await chromium.launchPersistentContext(profile, {

package/skills/lit-typographic-motion/engine/cover/render.mjs

@@ -114,14 +114,27 @@ function prepare(out) {
   if (state.blocked) throw stop(state.blocked.exit, state.blocked.name, `${state.blocked.detail}; fix: ${state.fix}`);
   const chrome = findChrome();
   if (!chrome.path) throw stop(EXIT.BLOCKED_NO_CHROME, "BLOCKED_NO_CHROME", `${chrome.missing}; fix: install Chrome or set CHROME_PATH`);
-  return { cover, coverDir, assets, state, chromePath: chrome.path, fonts: coverFonts(skillRoot, state, pins) };
+  return { cover, coverDir, assets, state, chromePath: chrome.path, fonts: coverFonts(skillRoot, state, pins), rung: cover.recipe === "hero-3d" ? "gpu" : "swiftshader", notices: [] };
 }
 
-// One browser for one pass; the profile lives under .run/cover/ and goes with the pass.
+// One browser for one pass; the profile lives under .run/cover/ and goes with the pass. The 3D hero asks
+// for the GPU rung. When a browser cannot start or draw there, every pass of the round takes the
+// software rung (the passes must share one) and the report says so; a page that breaks the
+// determinism or network rules is not retried, it would break the same way.
 async function withBrowser(chromium, context, profile, body) {
-  rmSync(profile, { recursive: true, force: true });
-  mkdirSync(profile, { recursive: true });
-  const browser = await openCover(chromium, { chromePath: context.chromePath, profile, coverDir: context.coverDir, page: context.cover.page, scale: COVER.captureScale, fonts: context.fonts });
+  const open = async () => {
+    rmSync(profile, { recursive: true, force: true });
+    mkdirSync(profile, { recursive: true });
+    return openCover(chromium, { chromePath: context.chromePath, profile, coverDir: context.coverDir, page: context.cover.page, scale: COVER.captureScale, fonts: context.fonts, rung: context.rung });
+  };
+  let browser;
+  try { browser = await open(); }
+  catch (error) {
+    if (context.rung !== "gpu" || [EXIT.STAGE_NETWORK_REQUEST, EXIT.STAGE_NONDETERMINISTIC].includes(error.exitCode)) throw error;
+    context.notices.push(`the 3D hero asked for the GPU rung and it failed there (${String(error.message).slice(0, 120)}); rendered on the software rung (SwiftShader), slower, same frames`);
+    context.rung = "swiftshader";
+    browser = await open();
+  }
   try { return await body(browser); } finally { await browser.close(); rmSync(profile, { recursive: true, force: true }); }
 }
 
@@ -255,11 +268,11 @@ export async function renderCover(out, { round = 1, log = () => {} } = {}) {
   renameSync(encoded.file, delivered);
   const stills = writeCoverStills(out, { round, gate, cover });
   writeFileSync(path.join(out, "poster.png"), readFileSync(path.join(out, "stills", "poster.png")));
-  const report = formatCoverReport(gate, { strict: true });
+  const report = `${formatCoverReport(gate, { strict: true })}${context.notices.map((note) => `warning: ${note}\n`).join("")}`;
   writeFileSync(path.join(out, "gate-report.txt"), report);
   const manifest = {
     schemaVersion: 1, mode: "cover", path: "cover", craftRound: round, recipe: cover.recipe,
-    page: cover.page, size, scale: COVER.captureScale, fps: cover.fps, frames: times.length, frameMs: ms, seed: cover.seed,
+    page: cover.page, size, scale: COVER.captureScale, rung: context.rung, warnings: context.notices, fps: cover.fps, frames: times.length, frameMs: ms, seed: cover.seed,
     encoder: encoded.encoder, encode: cover.encode, file: path.basename(delivered), bytes: statSync(delivered).size, captureSec: Number(captureSec.toFixed(1)),
     treatmentSha256: sha256(readFileSync(path.join(out, "treatment.json"))), coverSha256: stageSha(context.coverDir), stillsSha256: stills.sha256,
     gate: { pass: gate.pass, target: gate.target, medianD: gate.medianD, movingFrac: gate.movingFrac, longestStillSec: gate.longestStillSec, spike: gate.spike, seamLocal: gate.seamLocal, gates: gate.gates },