@litfamily/lithermes 1.0.28 → 1.0.30

package/assets/lithermes-plugin/skills/lit-schematic/scripts/scaffold.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+// Starts a drawing from the closest worked example.
+//
+//   node scaffold.mjs pid <dir>        P&ID on an A3 sheet (examples/pid-dosing-skid)
+//   node scaffold.mjs journal <dir>    two-panel journal figure (examples/journal-adsorption-rig)
+//   node scaffold.mjs iso <dir>        isometric cutaway (examples/iso-heat-exchanger)
+//
+// It writes <dir>/build.mjs (and every other module of the example, such as the iso scene.mjs)
+// with the kit imports pointing at this installed skill, never overwrites an existing file, and
+// never writes inside the plugin.
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const SKILL_ROOT = resolve(fileURLToPath(new URL("..", import.meta.url)));
+export const TEMPLATES = Object.freeze({
+  pid: "pid-dosing-skid",
+  journal: "journal-adsorption-rig",
+  iso: "iso-heat-exchanger",
+});
+
+export function scaffold(kind, dir) {
+  const example = TEMPLATES[kind];
+  if (!example) throw new Error(`kind must be one of ${Object.keys(TEMPLATES).join(", ")}`);
+  const target = resolve(dir);
+  const pluginRoot = realpathSync(resolve(SKILL_ROOT, "..", ".."));
+  mkdirSync(target, { recursive: true });
+  const real = realpathSync(target);
+  if (real === pluginRoot || real.startsWith(pluginRoot + sep)) throw new Error("refusing to write inside the installed plugin; pick a directory in your project");
+  const modules = readdirSync(join(SKILL_ROOT, "examples", example)).filter((f) => f.endsWith(".mjs"));
+  for (const name of modules) {
+    if (existsSync(join(target, name))) throw new Error(`${join(target, name)} already exists; move it or pick another directory`);
+  }
+  const lib = pathToFileURL(join(SKILL_ROOT, "scripts", "lib")).href;
+  for (const name of modules) {
+    const source = readFileSync(join(SKILL_ROOT, "examples", example, name), "utf8")
+      .replaceAll('"../../scripts/lib/', `"${lib}/`)
+      .replaceAll('"../../scripts/', `"${pathToFileURL(join(SKILL_ROOT, "scripts")).href}/`);
+    writeFileSync(join(target, name), source);
+  }
+  return join(target, "build.mjs");
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  const [kind, dir] = process.argv.slice(2);
+  if (!kind || !dir) {
+    console.error("Usage: node scaffold.mjs pid|journal|iso <dir>");
+    process.exitCode = 2;
+  } else {
+    try {
+      const file = scaffold(kind, dir);
+      console.log(`SCAFFOLD ${file}`);
+      console.log(`next: edit it, then node ${file} ${resolve(dir)} && node ${join(SKILL_ROOT, "scripts", "qa.mjs")} <svg>`);
+    } catch (error) {
+      console.error(`SCAFFOLD_REFUSED ${error.message}`);
+      process.exitCode = 1;
+    }
+  }
+}

package/assets/lithermes-plugin/skills/lit-scientific-visualization/SKILL.md

@@ -14,6 +14,8 @@ boundaries after explicit activation.
 
 For conceptual system, process, or trust-boundary diagrams without measured data, route to `lithermes:lit-diagram-drawer`.
 
+For drawings of real equipment, piping, apparatus or isometric cutaways, route to `lithermes:lit-schematic`; a figure that mixes an apparatus panel with a data panel splits by panel.
+
 ```yaml
 schema_version: lithermes_llm_contract/v1
 artifact_kind: hermes_skill_entrypoint
@@ -95,7 +97,23 @@ on its own, before any other reply content:
    `assets/` directory itself on Python's import path; do not assume the source
    root is sufficient. Keep inputs inert and validate the requested output
    directory before export.
-7. Verify actual figure output: readable file, requested format, nonzero size,
+7. Make the figure rich by default. LitHermes carries a standing request on the
+   user's behalf, which satisfies the source's "only when requested" clauses for
+   gridlines and annotation: after `rcparams()` apply a light major grid
+   (`axes.grid` on, `axes.axisbelow` on, `grid.linewidth` 0.4, `grid.alpha` 0.35,
+   `grid.color` `#9a9a9a`); label series directly at their line ends and mark
+   the values a reader will ask about (maxima, crossovers, thresholds, a fitted
+   parameter with its uncertainty and units) with notes that never sit on data;
+   add an inset where a region matters at another scale; and build a multi-panel
+   figure with bold (a), (b), (c) labels when the data supports a second view
+   (raw and derived, per condition, a fit and its residuals). Every layer stays
+   true: annotations quote only computed values, replicate spread is shown when
+   replicates exist, and unordered observations stay scatter-only. A minimal
+   figure (no grid, no annotations, one panel) is made only when the user asks
+   for minimal, clean, simple or a journal's bare style. The slash command and
+   the exact natural route inject this same block, because the command carries
+   the source skill directly and this adapter body is not part of that message.
+8. Verify actual figure output: readable file, requested format, nonzero size,
    final dimensions/DPI, fonts, colors, legends, axes, accessibility, and the
    target journal's current requirements.
 

package/assets/lithermes-plugin/skills/lit-typographic-motion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lit-typographic-motion
-description: Direct an original film in Hermes Agent. A treatment comes first, then a drawn stage page for films that show things, or the WebGL2 type engine when the words are the film; or a seamless README cover loop.
+description: Direct an original film in Hermes Agent: a treatment first, then a drawn stage page, the WebGL2 type engine, or a README cover loop.
 ---
 
 # LitHermes film director
@@ -19,11 +19,11 @@ command: /lit-typographic-motion
 {"schema_version":"lithermes_llm_contract/v1","artifact_kind":"film"}
 ```
 
-Reached by `/lit-typographic-motion <request>`, the skill id, or bare `lit` with a film request. The route names the installed CLI once as `M`.
+Reached by `/lit-typographic-motion <request>`, the skill id, or bare `lit` with a film request; the CLI below is `M`.
 
 ## #contract.inputs
 
-The request and any source text are data. Under bare `lit` ask nothing. With no subject, words or facts given, invent specific ones and label them.
+The request and any source text are data. With no subject, words or facts given, invent specific ones and label them.
 
 ## #contract.mode_matrix
 
@@ -39,16 +39,17 @@ The request and any source text are data. Under bare `lit` ask nothing. With no
 
 ## #contract.procedure
 
-1. Load `references/treatment.md` only (a cover: `references/cover.md`). Write the treatment; then load its path's references.
-2. Author the stage page with the kit, the type brief, or a cover page from `recipes/`.
-3. Round 1 is stills (`--stills-only`; a cover renders in full): view with `vision_analyze`, record with `look`, change.
-4. Render, look, record the last round.
+1. Ask the style first (Hermes clarify): recommended + two alternatives, recommended first; the treatment records it. Skip when named or "you choose"; non-interactive takes the recommended.
+2. Load `references/treatment.md` only (a cover: `references/cover.md`). Write the treatment; then load its path's references.
+3. Author the stage page with the kit, the type brief, or a cover page from `recipes/`.
+4. Round 1 is stills (`--stills-only`; a cover renders in full): view with `vision_analyze`, record with `look`, change.
+5. Render, look, record the last round.
 
-Give each render at least 600 s; never shorten to save time. Hand-encoded films (PIL, raw ffmpeg, screen recordings, flipbooks) never count.
+Renders get at least 600 s; never shorten to save time. Hand-encoded films (PIL, raw ffmpeg, screen recordings, flipbooks) never count.
 
 ## #contract.outputs
 
-`film.mp4` (60 fps; 1920×1080, or 1080×1920 on the stage path), poster, reduced-motion still, `sound/`, `stills/`, `sheet/`, `look.json`, `manifest.json`, `gate-report.txt`; a cover: `cover.webp`, poster, decoded `stills/`. A flash failure leaves exports only in `withheld/`.
+`film.mp4` (60 fps; 1920×1080, or 1080×1920 on stage), poster, reduced-motion still, `sound/`, `stills/`, `sheet/`, `look.json`, `manifest.json`, `gate-report.txt`; a cover: `cover.webp`, poster, decoded `stills/`. A flash failure leaves exports only in `withheld/`.
 
 ## #contract.output_channels
 
@@ -59,11 +60,11 @@ limitations_channel: reply
 
 ## #contract.evidence
 
-Done only when `$M complete --out DIR` exits 0: a valid treatment, a passing gate (a cover: TARGET) and two look rounds, the last on the final render. Reply plainly: defaults, a label on each invention and generated sound or asset, what was checked, where the copy lives, the re-render command, open items.
+Done only when `$M complete --out DIR` exits 0: valid treatment, passing gate (a cover: TARGET), two look rounds, the last on the final render. Reply: defaults, labels on inventions and generated sound/assets, checks, copy location, re-render command, open items.
 
 ## #contract.hard_stops
 
-Exits 10, 11, 12, 14, 15: name the state and its fix (`references/runtime.md`). 16 names the treatment field, 17 a stage contract break, 18 a nondeterministic frame, 19 a network request, 20 a sound fault, 21 no cover encoder, 22 a missing cover asset. Never install during a render, deliver a flash-failing film, or downgrade to pass.
+Exits 10, 11, 12, 14, 15: name the state and its fix (`references/runtime.md`). 16 the treatment field, 17 a stage break, 18 a nondeterministic frame, 19 a network request, 20 a sound fault, 21 no cover encoder, 22 a missing cover asset. Never install during a render, deliver a flash-failing film, or downgrade to pass.
 
 ## #contract.anti_patterns
 

package/assets/lithermes-plugin/skills/lit-typographic-motion/bin/motion.mjs

@@ -21,6 +21,8 @@ import { areaResize, contactSheet, encodePreview, ffprobe, hasFfmpeg, pngDecode,
 import { openRenderer } from '../engine/browser.mjs';
 import { WARM, audioState, findCache, fontFile, fontState, hangulPath, runtimeRequire, skillRoot, wordTimingReady } from './runtime.mjs';
 import { loadTreatment } from '../engine/treatment.mjs';
+import { readStyle, STYLE_IDS } from '../engine/styles.mjs';
+import { writeScaffold } from '../engine/scaffold.mjs';
 import { recordFirstTreatment } from '../engine/director.mjs';
 import { stageCommand, stageRegate } from '../engine/stage.mjs';
 import { coverCommand, coverGateCommand } from '../engine/cover.mjs';
@@ -38,9 +40,12 @@ usage: node motion.mjs <subcommand> --out DIR [options]   (write DIR/treatment.j
   cover-gate FILE [--frames D --frames2 D --masks D --title x,y,w,h] [--strict] [--json]
                                                                   the cover gate on any cover file or PNG frame folder
   run      --out DIR [--brief FILE] [--round 1-3] [--stills-only] type path: the WebGL2 type engine; stills, cut sheet, film, preview, poster, gate
-  sound    --out DIR                                              build the generated sound bed and sound-cues.json from the treatment
+  sound    --out DIR                                              build the score (or generated bed) and sound-cues.json from the treatment
+  blender  --out DIR [--final]                                   offline Blender rung: stills at the beat midpoints (stage/plate-preview) or the plate (stage/plate)
   look     --out DIR --round 1-3 --answers FILE                   record one look round against the latest stills set
   gate     --out DIR                                              rerun the gate on an existing output dir
+  styles   [--out DIR] [--format 16:9|9:16]                       print the house-style table; with --out, write the style catalog styles.json
+  scaffold --out DIR                                              write DIR/stage/index.html from the treatment (never overwrites a page)
   complete --out DIR                                              exit 0 only when this film is done (treatment, gate, look rounds)
 type-path tools: stills, sheet, video, perf (--brief FILE --out DIR)
 options: --scale 1-4  --word-timing  --force-software
@@ -60,7 +65,7 @@ function parseArgs(argv) {
     const arg = argv[i];
     if (!arg.startsWith('--')) { flags._.push(arg); continue; }
     const key = arg.slice(2);
-    if (['stills-only', 'cuts', 'word-timing', 'force-software', 'help', 'no-rerender', 'aids', 'detach', 'strict', 'json'].includes(key)) flags[key] = true;
+    if (['stills-only', 'cuts', 'word-timing', 'force-software', 'help', 'no-rerender', 'aids', 'detach', 'strict', 'json', 'final'].includes(key)) flags[key] = true;
     else if (key === 'viewed') flags.viewed = String(argv[++i] || '').split(',').map((v) => Number(v.replace(/^f/, ''))).filter(Number.isInteger);
     else flags[key] = argv[++i];
   }
@@ -548,10 +553,59 @@ async function main(argv) {
   const mode = flags._[0];
   if (!mode || flags.help || mode === 'help') { console.log(USAGE); return 0; }
   if (mode === 'complete') return completeCommand(resolve(flags.out || 'motion-output'));
+  if (mode === 'styles') {
+    const format = flags.format === '9:16' ? '9:16' : '16:9';
+    const rows = STYLE_IDS.map((id) => {
+      const style = readStyle(id);
+      return { id, name: style.name, format, palette: style.palette, typePreset: style.typePreset, beds: style.beds.map((bed) => `${bed.timbre} ${bed.key} ${bed.tempo}bpm`), motions: style.motion, transitions: style.transitions };
+    });
+    for (const row of rows) console.log(`${row.id}: ${row.name} (type preset ${row.typePreset ?? 'none, stage only'}; beds ${row.beds.join(' / ')})`);
+    if (flags.out) {
+      mkdirSync(resolve(flags.out), { recursive: true });
+      writeJson(join(resolve(flags.out), 'styles.json'), { schema: 'litfamily.motion-styles/v1', format, styles: rows });
+      console.log(`styles: ${join(resolve(flags.out), 'styles.json')}`);
+    }
+    return 0;
+  }
+  if (mode === 'scaffold') {
+    const out = resolve(flags.out || 'motion-output');
+    try {
+      const { treatment } = loadTreatment(out, EXIT.BLOCKED_TREATMENT_INVALID);
+      if (treatment.path !== 'stage') throw fail(EXIT.BLOCKED_TREATMENT_INVALID, `BLOCKED_TREATMENT_INVALID: field path: this treatment takes the type path; scaffold writes the stage page`);
+      const { file, note } = writeScaffold(out, treatment);
+      console.log(`scaffold: ${file}`);
+      if (note) console.log(note);
+    } catch (error) {
+      if (error && typeof error.message === 'string' && error.message.startsWith('scaffold: ')) {
+        console.error(error.message);
+        return 2;
+      }
+      if (error && Number.isInteger(error.exitCode)) {
+        console.error(error.message);
+        return error.exitCode;
+      }
+      throw error;
+    }
+    return 0;
+  }
   if (mode === 'stage') return stageCommand(flags);
   if (mode === 'cover') return coverCommand(flags);
   if (mode === 'cover-gate') return coverGateCommand(flags);
   if (mode === 'sound') return soundCommand(flags);
+  if (mode === 'blender') {
+    const { blenderCommand } = await import('../engine/blender.mjs');
+    try {
+      const result = await blenderCommand({ out: resolve(flags.out || 'motion-output'), final: Boolean(flags.final) });
+      console.log(result.message);
+      return result.code;
+    } catch (error) {
+      if (error && Number.isInteger(error.exitCode)) {
+        console.error(error.message);
+        return error.exitCode;
+      }
+      throw error;
+    }
+  }
   if (mode === 'look') return lookCommand(flags);
   if (!['run', 'stills', 'sheet', 'video', 'perf', 'gate', 'hash-frame'].includes(mode)) { console.error(USAGE); return 2; }
   if (mode === 'gate') return regate(flags);

package/assets/lithermes-plugin/skills/lit-typographic-motion/bin/runtime.mjs

@@ -7,6 +7,11 @@
 // and the product installer are the only callers of install() (MO-A-42/43).
 import { createHash } from 'node:crypto';
 import { spawnSync } from 'node:child_process';
+import { lookup } from 'node:dns/promises';
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { isIP } from 'node:net';
+import { Readable } from 'node:stream';
 import { createRequire } from 'node:module';
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
@@ -97,14 +102,134 @@ function run(cmd, args, options = {}) {
 
 // Pinned URL + sha256, verified before it lands; a mirror (file:// or http://127.0.0.1)
 // replaces the host part for offline tests.
-export async function fetchPinned(entry, targetFile, { mirror = process.env.LITHERMES_MOTION_FONT_MIRROR } = {}) {
+const FONT_FETCH_LIMIT = 32 * 1024 * 1024;
+
+/** True only for a public unicast address (mirrors the hijack capture guard). */
+const isPublicUnicastIp = (ip) => {
+  if (isIP(ip) === 4) {
+    const parts = ip.split('.').map(Number);
+    if (parts[0] === 127 || parts[0] === 10) return false;
+    if (parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31) return false;
+    if (parts[0] === 192 && parts[1] === 168) return false;
+    if (parts[0] === 169 && parts[1] === 254) return false;
+    if (parts.every((part) => part === 0)) return false;
+    if (parts[0] >= 224 && parts[0] <= 239) return false;
+    return true;
+  }
+  if (isIP(ip) === 6) {
+    const lower = ip.toLowerCase();
+    if (lower === '::1' || lower === '::' || lower.startsWith('ff')) return false;
+    const first = Number.parseInt(lower.split(':', 1)[0] || '0', 16);
+    if (first >= 0xfe80 && first <= 0xfebf) return false;
+    const mapped = lower.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/u);
+    if (mapped) return isPublicUnicastIp(mapped[1]);
+    return true;
+  }
+  return false;
+};
+
+const resolvePublicHost = async (hostname, lookupImpl) => {
+  let records;
+  try {
+    records = await lookupImpl(hostname, { all: true });
+  } catch (error) {
+    throw new Error(`cannot resolve ${hostname}: ${error.message}`);
+  }
+  if (!records.length) throw new Error(`${hostname} resolves to nothing`);
+  for (const record of records) {
+    if (!isPublicUnicastIp(record.address)) {
+      throw new Error(`${hostname} resolves to ${record.address}, which is not a public unicast address`);
+    }
+  }
+  return { address: records[0].address, family: records[0].family };
+};
+
+const pinnedSend = (requestImpl) => (href, init, pin) => new Promise((resolveResponse, rejectResponse) => {
+  const pinLookup = (_host, options, callback) => (
+    options?.all
+      ? callback(null, [{ address: pin.address, family: pin.family }])
+      : callback(null, pin.address, pin.family)
+  );
+  const req = requestImpl(href, { signal: init.signal, lookup: pinLookup }, (res) => {
+    const answer = new Headers();
+    for (const [name, value] of Object.entries(res.headers)) {
+      for (const item of [value].flat()) if (item !== undefined) answer.append(name, String(item));
+    }
+    const empty = [204, 205, 304].includes(res.statusCode);
+    if (empty) res.resume();
+    try {
+      resolveResponse(new Response(empty ? null : Readable.toWeb(res), { status: res.statusCode, headers: answer }));
+    } catch (error) {
+      res.destroy();
+      rejectResponse(error);
+    }
+  });
+  req.on('error', rejectResponse);
+  req.end();
+});
+
+const PINNED_REQUESTS = { 'http:': httpRequest, 'https:': httpsRequest };
+
+export async function fetchPinned(entry, targetFile, { mirror = process.env.LITHERMES_MOTION_FONT_MIRROR, fetchImpl = null, requestImpls = PINNED_REQUESTS, lookupImpl = lookup } = {}) {
   const url = mirror ? `${mirror.replace(/\/$/, '')}/${entry.path}` : entry.url;
   let bytes;
   if (url.startsWith('file://')) bytes = readFileSync(fileURLToPath(url));
   else {
-    const response = await fetch(url, { redirect: 'follow' });
-    if (!response.ok) throw new Error(`${entry.path}: HTTP ${response.status} from ${url}`);
-    bytes = Buffer.from(await response.arrayBuffer());
+    // Every hop is resolved and checked before connecting, with a timeout, and
+    // no hop may leave the entry host: a rebinding mirror must not smuggle the
+    // fetch onto loopback, and a compromised CDN must not redirect it away. The
+    // socket connects to the address the check approved, even if the name
+    // rebinds afterwards; TLS still verifies the certificate for the name.
+    const send = fetchImpl
+      ? (href, init) => fetchImpl(href, init)
+      : (href, init, pin) => pinnedSend({ ...PINNED_REQUESTS, ...requestImpls }[new URL(href).protocol])(href, init, pin);
+    const pinned = new URL(url).host;
+    const limit = FONT_FETCH_LIMIT;
+    let current = url;
+    let chunks = null;
+    for (let hop = 0; hop <= 5; hop += 1) {
+      const checked = new URL(current);
+      if (checked.host !== pinned) {
+        throw new Error(`${entry.path}: refusing font redirect off ${pinned} to ${checked.host}`);
+      }
+      let pin;
+      if (isIP(checked.hostname)) {
+        if (!isPublicUnicastIp(checked.hostname)) {
+          throw new Error(`${checked.hostname} is not a public unicast address`);
+        }
+        pin = { address: checked.hostname, family: isIP(checked.hostname) };
+      } else {
+        pin = await resolvePublicHost(checked.hostname, lookupImpl);
+      }
+      const response = await send(current, { redirect: 'manual', signal: AbortSignal.timeout(30_000) }, pin);
+      if ([301, 302, 303, 307, 308].includes(response.status)) {
+        const location = response.headers.get('location');
+        if (!location) throw new Error(`${entry.path}: font redirect without a location`);
+        current = new URL(location, current).toString();
+        continue;
+      }
+      if (!response.ok) throw new Error(`${entry.path}: HTTP ${response.status} from ${current}`);
+      const declared = Number(response.headers.get('content-length'));
+      if (Number.isFinite(declared) && declared > limit) {
+        throw new Error(`${entry.path}: declares ${declared} bytes, over the ${limit} byte cap`);
+      }
+      const reader = response.body.getReader();
+      chunks = [];
+      let size = 0;
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        size += value.byteLength;
+        if (size > limit) {
+          try { await reader.cancel(); } catch { /* the server side already went away */ }
+          throw new Error(`${entry.path}: larger than ${limit} bytes`);
+        }
+        chunks.push(value);
+      }
+      break;
+    }
+    if (!chunks) throw new Error(`${entry.path}: redirected more than 5 times`);
+    bytes = Buffer.concat(chunks);
   }
   const got = sha(bytes);
   if (got !== entry.sha256) throw new Error(`${entry.path}: sha256 mismatch (got ${got}, pinned ${entry.sha256})`);

package/assets/lithermes-plugin/skills/lit-typographic-motion/engine/THIRD_PARTY_NOTICES

@@ -4,6 +4,15 @@ Engine: portions adapted from mexicat/pdoom-video, commit
 ca251e3dddda422b364385eb484b5a3593a0990d (MIT, Giacomo Magnanini). The full
 MIT permission text is in engine/NOTICE next to this file.
 
+Vendored library (bundled, unmodified, served to stage pages at /lit/three/)
+  three.js r170 (npm three@0.170.0, MIT), Copyright 2010-2024 Three.js Authors
+    licence:    engine/vendor/three/LICENSE
+    source:     https://registry.npmjs.org/three/-/three-0.170.0.tgz
+    files (sha256), copied unmodified from the tarball (build/, examples/jsm/):
+      three.module.js                           ce1fa418de16a19495a9f72495580e3015d7745c296d3ce0485897f902ddedfb
+      addons/environments/RoomEnvironment.js    85869bdd22f7cf0b22e68dcefe6cb710480af0f5c901a76f7a7764fd07fc8014
+      addons/geometries/RoundedBoxGeometry.js   d20aeaf7077c459a8d952d215738d7b44fba028440bb862d84b622a34f0c80bb
+
 Fonts. Nothing below is bundled in this package. `lithermes motion-runtime
 install` fetches each file from its pinned URL, verifies its sha256 against
 runtime/fonts.json, and stores it with its licence file in the product cache.

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

@@ -0,0 +1,218 @@
+# 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)
+# It sets up Cycles on the GPU (Metal on Apple silicon, else whatever GPU backend Blender finds, else
+# the CPU, and the receipt says which), runs the film's scene.py with the `lit` helpers in scope, then
+# renders either 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
+
+
+def parse():
+    argv = sys.argv[sys.argv.index("--") + 1:] if "--" in sys.argv else []
+    p = argparse.ArgumentParser(prog="runner.py")
+    p.add_argument("--scene", required=True)
+    p.add_argument("--out", required=True)
+    p.add_argument("--width", type=int, required=True)
+    p.add_argument("--height", type=int, required=True)
+    p.add_argument("--percent", type=int, default=100)
+    p.add_argument("--samples", type=int, default=128)
+    p.add_argument("--device", default="METAL")
+    p.add_argument("--fps", type=int, default=30)
+    p.add_argument("--seed", type=int, default=0)
+    p.add_argument("--stills")
+    p.add_argument("--frames")
+    return p.parse_args(argv)
+
+
+def use_gpu(scene, wanted):
+    """Cycles on the wanted GPU backend when it has a device; another GPU backend next; the CPU last."""
+    prefs = bpy.context.preferences.addons["cycles"].preferences
+    for backend in [wanted, "METAL", "OPTIX", "CUDA", "HIP", "ONEAPI"]:
+        try:
+            prefs.compute_device_type = backend
+        except TypeError:
+            continue
+        prefs.get_devices()
+        gpus = [d for d in prefs.devices if d.type == backend]
+        if gpus:
+            for d in prefs.devices:
+                d.use = d.type == backend
+            scene.cycles.device = "GPU"
+            return backend
+    scene.cycles.device = "CPU"
+    return "CPU"
+
+
+class Lit:
+    """Helpers the scene script may use. Times are in film seconds; the plate starts at 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) and 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 look_at(self, obj, target):
+        direction = Vector(target) - obj.location
+        obj.rotation_euler = direction.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
+        bsdf = mat.node_tree.nodes["Principled BSDF"]
+        bsdf.inputs["Base Color"].default_value = (*self.rgb(color), 1.0)
+        bsdf.inputs["Roughness"].default_value = roughness
+        bsdf.inputs["Metallic"].default_value = metallic
+        if emission is not None:
+            bsdf.inputs["Emission Color"].default_value = (*self.rgb(emission), 1.0)
+            bsdf.inputs["Emission Strength"].default_value = strength
+        return mat
+
+    def rgb(self, color):
+        """A #RRGGBB colour in Blender's linear space."""
+        if not isinstance(color, str):
+            return tuple(color)[:3]
+        h = color.lstrip("#")
+        srgb = [int(h[i:i + 2], 16) / 255 for i in (0, 2, 4)]
+        return tuple(c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4 for c in srgb)
+
+    def rounded_box(self, name, size, radius=0.08, segments=6, material=None, location=(0, 0, 0)):
+        """A box with bevelled edges that 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 an image file (a fetched product asset) at its own aspect ratio."""
+        img = bpy.data.images.load(os.path.abspath(image_path))
+        w, h = img.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 = mat.node_tree.nodes
+        tex = nodes.new("ShaderNodeTexImage")
+        tex.image = img
+        bsdf = nodes["Principled BSDF"]
+        mat.node_tree.links.new(tex.outputs["Color"], bsdf.inputs["Base Color"])
+        mat.node_tree.links.new(tex.outputs["Color"], bsdf.inputs["Emission Color"])
+        mat.node_tree.links.new(tex.outputs["Alpha"], bsdf.inputs["Alpha"])
+        bsdf.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 on depth of field."""
+        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):
+        world = bpy.context.scene.world or bpy.data.worlds.new("world")
+        bpy.context.scene.world = world
+        world.use_nodes = True
+        bg = world.node_tree.nodes["Background"]
+        bg.inputs["Color"].default_value = (*self.rgb(color), 1.0)
+        bg.inputs["Strength"].default_value = strength
+        return world
+
+
+def main():
+    a = parse()
+    os.makedirs(a.out, exist_ok=True)
+    bpy.ops.wm.read_factory_settings(use_empty=True)
+    scene = bpy.context.scene
+    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
+    scene.render.image_settings.file_format = "PNG"
+    scene.render.image_settings.color_mode = "RGB"
+    scene.render.image_settings.color_depth = "8"
+
+    lit = Lit(a.fps)
+    with open(a.scene, encoding="utf-8") as fh:
+        code = compile(fh.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")
+    # The scene may raise its own settings; the command line has the last word on size and samples.
+    scene.cycles.samples = a.samples
+    scene.render.resolution_percentage = a.percent
+
+    files = []
+    if a.stills:
+        for i, t in enumerate(float(x) for x in a.stills.split(",")):
+            scene.frame_set(lit.frame(t))
+            name = f"still-{i + 1:02d}.png"
+            scene.render.filepath = os.path.join(a.out, name)
+            bpy.ops.render.render(write_still=True)
+            files.append(name)
+    else:
+        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)
+        files = [f"{f:06d}.png" for f in range(first, last + 1)]
+
+    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": [f for f in files if os.path.exists(os.path.join(a.out, f))],
+    }
+    with open(os.path.join(a.out, "receipt.json"), "w", encoding="utf-8") as fh:
+        json.dump(receipt, fh)
+
+
+main()