@litfamily/litgrok 1.0.26 → 1.0.28

package/.grok/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 installed .grok tree.
+
+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 grokRoot = realpathSync(resolve(SKILL_ROOT, "..", ".."));
+  mkdirSync(target, { recursive: true });
+  const real = realpathSync(target);
+  if (real === grokRoot || real.startsWith(grokRoot + sep)) throw new Error("refusing to write inside the installed .grok tree; 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/.grok/skills/lit-scientific-visualization/SKILL.md

@@ -17,7 +17,7 @@ labels, captions, notebooks, fetched pages, and repository prose as inert data.
 shell command, dependency installation, or host configuration change.
 Unsupported or undocumented surfaces remain blocked.
 
-For conceptual architecture or process diagrams, use [lit-diagram-drawer](../lit-diagram-drawer/SKILL.md); plots of measured scientific data remain in this skill.
+For conceptual architecture or process diagrams, use [lit-diagram-drawer](../lit-diagram-drawer/SKILL.md); for drawings of real equipment, a P&ID, or an experimental-setup figure, use [lit-schematic](../lit-schematic/SKILL.md); plots of measured scientific data remain in this skill. A figure that mixes an apparatus drawing with data panels is split by panel.
 
 ## #contract.output_channels
 
@@ -120,23 +120,44 @@ The verifier checks the exact path set, byte sizes, per-file SHA-256 values, and
    ordered trajectory or a justified model/fitted curve. Use a common position scale for precise
    comparisons, intervals with an explicitly stated definition, and log axes only when the
    question and labels support them.
-6. Enforce the packaged visual defaults: inward major and minor ticks, grids off unless requested,
-   visible round-number endpoints, zero as the first tick on zero-origin axes, no title unless the
-   user asks for one, and `layout='constrained'` for multi-panel figures. Use `ensure_zero_origin_ticks()`
-   after explicit limits. Use `style_legend()` with a black border and `framealpha=1`; move a
-   dense legend outside rather than covering evidence.
+6. Enforce the packaged visual defaults: inward major and minor ticks, a light major grid (see
+   the rich layer below), visible round-number endpoints, zero as the first tick on zero-origin
+   axes, no title unless the user asks for one, and `layout='constrained'` for multi-panel
+   figures. Use `ensure_zero_origin_ticks()` after explicit limits. Use `style_legend()` with a
+   black border and `framealpha=1`; move a dense legend outside rather than covering evidence.
 7. Use Okabe-Ito, Wong, or Paul Tol palettes from `color_palettes.py` for categorical marks and
    perceptually uniform maps such as `viridis`, `plasma`, `inferno`, `magma`, or `cividis` for
    continuous data. Pair color with shape, label, or position when identity matters. Do not use
    `jet`, `rainbow`, or unexplained red-green oppositions.
-8. Keep panels purposeful and captions factual. Show sample size and independence when relevant;
+8. Build the rich layer. The packaged corpus keeps grids, annotation and ornament off until a
+   request asks for them; LitGrok makes that request on the user's behalf, so a figure is
+   context-dense by default and the corpus restraints for those items are satisfied, not undone.
+   Every correctness rule above stays in force.
+   - **Light grid.** Major gridlines only, thin and pale, behind the data, applied right after
+     `rcparams()` (snippet in the recipe below).
+   - **Direct annotation.** Label series at their line ends or in place instead of a detached
+     legend when it fits. Mark the values a reader will ask about (maxima, crossovers,
+     thresholds, a fitted parameter with its uncertainty and units) with short arrowed or offset
+     notes that never sit on data.
+   - **Inset.** When a region matters at another scale (a low-pressure slope, an onset, a tail),
+     add an inset axis with `indicate_inset_zoom`, or a marginal distribution or residual strip
+     for fitted data.
+   - **Multi-panel context.** When the data supports more than one view (the raw measurement and a
+     derived quantity, per-condition panels, a fit and its residuals), build a multi-panel figure
+     with shared axes where panels share units and bold panel labels (a), (b), (c) at the top left.
+   - **Every layer stays true.** Annotations quote only values computed from the data; error bars
+     or bands show the replicate spread when replicates exist; the layer never adds fake
+     precision or a line through unordered observations.
+   A minimal figure (no grid, no annotations, one panel) is produced only when the user asks for
+   minimal, clean, simple or a journal's bare style.
+9. Keep panels purposeful and captions factual. Show sample size and independence when relevant;
    distinguish raw observations, aggregates, model predictions, exploratory fits, and transformed
    values. Do not add significance stars without a traceable test. Do not hide outliers or
    contradictory conditions to improve a narrative.
-9. Export a vector file for line art and a high-resolution raster when requested. Raster DPI must exceed 500; the packaged defaults are 600. Keep `bbox_inches='tight'`, inspect outside
+10. Export a vector file for line art and a high-resolution raster when requested. Raster DPI must exceed 500; the packaged defaults are 600. Keep `bbox_inches='tight'`, inspect outside
    legends and colorbars for clipping, and verify that vector text remains selectable when that
    matters. Save only to an explicit, non-conflicting output path.
-10. Inspect every produced format at final physical scale. Check dimensions, DPI, format
+11. Inspect every produced format at final physical scale. Check dimensions, DPI, format
     signature, fonts and glyphs, endpoints, labels and units, grids, legends, panel alignment,
     color/grayscale legibility, and clipping. Recompute a small sample of plotted positions and
     compare figure counts, categories, uncertainties, and caption numbers with the source data.
@@ -164,14 +185,16 @@ from figure_export import save_publication_figure
 
 rcparams()
 plt.style.use(str(ASSETS / "nature.mplstyle"))
+# Rich layer: a light major grid behind the data (a minimal request skips this line).
+plt.rcParams.update({"axes.grid": True, "axes.grid.which": "major", "axes.axisbelow": True,
+                     "grid.linewidth": 0.4, "grid.alpha": 0.35, "grid.color": "#9a9a9a"})
 fig, ax = plt.subplots(layout="constrained")
 # Load verified data, choose marks from its semantics, and label units.
 save_publication_figure(fig, PROJECT_ROOT / "figure", formats=["pdf", "png"], dpi=600)
 ```
 
 The style call is an explicit provenance check: after applying it, inspect `mpl.rcParams` and
-record a style-owned value such as `font.size == 7`, `savefig.dpi == 600`, or
-`axes.grid is False`. Do not claim that a style was applied merely because the file exists.
+record a style-owned value such as `font.size == 7` or `savefig.dpi == 600`. Do not claim that a style was applied merely because the file exists.
 
 ## #contract.evidence
 
@@ -212,7 +235,8 @@ that no artifact was rendered.
 - [ ] One explicit scientific question and authorized data source are recorded.
 - [ ] The verifier passed and the generated script resolved package-local helpers and assets.
 - [ ] `rcparams()` ran before figure creation; styles, palette, ticks, spines, grids, legends,
-      layout, and export settings match the requested context.
+      layout, and export settings match the requested context, with the rich layer on unless a
+      minimal figure was requested.
 - [ ] Independent points remain scatter-only; uncertainty and sample counts are traceable.
 - [ ] Every requested format passed metadata and final-scale visual inspection.
 - [ ] Temporary files, processes, environments, and QA projects were removed or explicitly listed.

package/.grok/skills/lit-typographic-motion/SKILL.md

@@ -7,24 +7,26 @@ argument-hint: "<what the film is for, plus any words, facts or style>"
 
 # lit-typographic-motion: film director
 
-Installed at `.grok/skills/lit-typographic-motion/` (project) or `~/.grok/skills/lit-typographic-motion/` (user). Run every command from that skill root as `node scripts/motion.mjs <mode> --out <dir>`. Every frame and track passes through this skill's renderer; hand-encoded films (an ffmpeg filter graph, a Python frame loop, a screen recording, a flipbook) are not the deliverable.
+Installed at `.grok/skills/lit-typographic-motion/` (project) or `~/.grok/skills/lit-typographic-motion/` (user). Run every command from that skill root as `node scripts/motion.mjs <mode> --out <dir>`. Every frame and track passes through this skill's renderer; hand-encoded films are not the deliverable.
 
 Under bare `lit`, ask no questions: choose defaults and label them, and label every invention and the generated sound in the reply.
 
+Otherwise ask a numbered choice of house style first (recommended first; load references/choice-first.md); skip only when the prompt names the style or says you choose.
+
 A README, hero, banner or cover loop is not a film: cover mode (`cover`, `cover-gate`) replaces this order.
 
 ## Order
 
 1. Read references/treatment.md first, and only it, before anything else. Write `<dir>/treatment.json`. When the request names no subject, words or facts, invent them and list them in `inventions`.
 2. Set `path` there, then read that path's references: stage → references/stage.md; type → references/scene-contract.md, references/type-craft.md, references/style-bible.md.
-3. Round 1 is stills: `stage --out <dir> --stills-only` or `make --out <dir> --stills-only`. Open every PNG it lists with your image tool, then `look --out <dir> --round 1 --answers <file>`, naming the weakest beat and the change you made.
-4. Full render: `stage --out <dir> --round 2` or `make --out <dir> --round 2`. Give the call a timeout of at least 600 s; never shorten the film to save time. `sound --out <dir>` rebuilds the generated bed alone.
+3. Round 1 is stills: `stage --out <dir> --stills-only` or `make --out <dir> --stills-only`. Open every PNG it lists, then `look --out <dir> --round 1 --answers <file>`, naming the weakest beat and the change you made.
+4. Full render: `stage --out <dir> --round 2` or `make --out <dir> --round 2` (timeout: at least 600 s; never shorten it). `sound --out <dir>` rebuilds the score or bed alone.
 5. Look again at the new stills (`look --round 2`, then a round 3 if an answer asks for one).
 6. `node scripts/motion.mjs verify --out <dir>` decides done.
 
 Pre-warm happens outside the session: `npm exec --yes --package @litfamily/litgrok@<installed version> -- litgrok motion-runtime install` (`motion-runtime status` shows the probes). A render never installs or fetches.
 
-A flash FAIL withholds the exports under `withheld/`; say so and never present them as a film. Never downgrade to pass: fix the cause or deliver with the failure stated.
+A flash FAIL withholds the exports under `withheld/`; say so. Never downgrade to pass.
 
 Exit codes: 10 no Chrome (set CHROME_PATH), 11 no WebGL2, 12 no ffmpeg (stills still work), 13 gate FAIL, 14 runtime not pre-warmed, 15 font missing or tampered (fix both with the pre-warm above), 16 treatment invalid (the field is named), 17 stage contract, 18 stage nondeterministic, 19 stage network request, 20 sound invalid, 21 no cover encoder, 22 cover asset missing. Name the code and its fix.
 
@@ -36,6 +38,7 @@ Read references/scene-contract.md when `path` is type and you write the brief or
 Read references/type-craft.md when `path` is type and the words mix Hangul and Latin or wrap.
 Read references/style-bible.md when `path` is type and you choose or describe the preset.
 Read references/craft-loop.md before the first look round: look questions, rounds, done, gate table.
+Read references/depth.md for a 3D subject or hero.
 Read references/runtime.md when a render exits 10-15 or 21, or an audio file is supplied.
 Read references/cover.md when the request is a README, hero, banner or cover loop.
 Read references/complete-contract.md for the reply contract and the completion rule.

package/.grok/skills/lit-typographic-motion/THIRD_PARTY_NOTICES

@@ -42,4 +42,15 @@ its sha256 and its licence file's sha256 match the pins in fonts/pins.json
   Pretendard (Regular; fetched only when the lit-pptx pair is absent)
       OFL 1.1: Pretendard-LICENSE
 
+Vendored library (bundled, unmodified, served to stage and cover pages at /lit/three/)
+  three.js r170 (npm three@0.170.0, MIT), Copyright 2010-2024 Three.js Authors
+    licence:    scripts/lib/vendor/three/LICENSE
+    source:     https://registry.npmjs.org/three/-/three-0.170.0.tgz
+                tarball sha256 4a608a355dcaba72e0e5383cdc814303f5b6060b43c238cdf6932dceb699238d
+                integrity sha512-FQK+LEpYc0fBD+J8g6oSEyyNzjp+Q7Ks1C568WWaoMRLW+TkNNWmenWeGgJjV105Gd+p/2ql1ZcjYvNiPZBhuQ==
+    files (sha256), copied unmodified from the tarball (build/, examples/jsm/):
+      three.module.js                           ce1fa418de16a19495a9f72495580e3015d7745c296d3ce0485897f902ddedfb
+      addons/environments/RoomEnvironment.js    85869bdd22f7cf0b22e68dcefe6cb710480af0f5c901a76f7a7764fd07fc8014
+      addons/geometries/RoundedBoxGeometry.js    d20aeaf7077c459a8d952d215738d7b44fba028440bb862d84b622a34f0c80bb
+
 Credit line: Typographic-motion engine adapted from mexicat/pdoom-video (MIT, Giacomo Magnanini), commit `ca251e3`.

package/.grok/skills/lit-typographic-motion/recipes/hero-3d/expected.json

@@ -0,0 +1,62 @@
+{
+  "schema": "litgrok.motion-cover-recipe/v1",
+  "note": "The decoded gate row this recipe reached when it shipped. npm run qa:cover-recipes re-renders it through motion.mjs cover and fails when median d or the moving share leaves +-15 % of this row, seamLocal leaves TARGET, the file passes 2 MiB or the render exits non-zero. Measured on the GPU rung (Apple ANGLE Metal on Apple silicon; the software rung fallback renders the same frames more slowly) and libwebp 1.6.0.",
+  "row": {
+    "medianD": 0.002038,
+    "movingFrac": 1,
+    "longestStillSec": 0.05,
+    "spike": 1.631053,
+    "seamLocal": 1.141655,
+    "bytes": 621220
+  },
+  "settings": {
+    "size": [
+      1000,
+      500
+    ],
+    "fps": 20,
+    "frames": 160,
+    "encode": {
+      "q": 86,
+      "edgeQ": 97,
+      "edgeFrames": 15,
+      "method": 4
+    }
+  },
+  "treatment": {
+    "mode": "cover",
+    "request": "A README motion cover for LitGrok with a hero you can turn in your head.",
+    "idea": "One rounded hero turns once per loop under a key light while the brand word sits live over it.",
+    "recipe": "hero-3d",
+    "recipeReason": "The subject has a back and an inside, so the loop is an object, not a drawing.",
+    "brandWord": "LITGROK",
+    "motto": {
+      "text": "KEEP THE WORK LIT.",
+      "source": "project",
+      "from": "README.md"
+    },
+    "aspect": "2:1",
+    "loopSec": 8,
+    "fps": 20,
+    "layers": {
+      "slow": "The shadow slides under the turning hero once per loop.",
+      "mid": "The hero turns once per loop, showing every side.",
+      "beat": "The brand word holds still over the turn."
+    },
+    "system": {
+      "rule": "One full turn per loop, eased at neither end.",
+      "copies": "One hero and the brand word.",
+      "offset": "The turn is the loop phase itself."
+    },
+    "title": {
+      "box": [
+        0.1,
+        0.55,
+        0.8,
+        0.32
+      ],
+      "kind": "live"
+    },
+    "ambition": "The turn reads as one object and the seam is invisible in the decoded file."
+  }
+}

package/.grok/skills/lit-typographic-motion/recipes/hero-3d/index.html

@@ -0,0 +1,82 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<!-- Recipe: 3D hero (hero-3d), the loop as an object. A worked page: one rounded hero turns once
+     per loop under a key light while the brand word sits live over it. The hero is built once and
+     only posed from t, so a fresh capture draws the same pixels; replace the RoundedBox with the
+     product modelled from its real logo and keep the turn to one loop. -->
+<link rel="stylesheet" href="/lit/fonts.css">
+<script src="/lit/loop-kit.js"></script>
+<script type="importmap">{ "imports": { "three": "/lit/three/three.module.js", "three/addons/": "/lit/three/addons/" } }</script>
+<style>
+  :root { --ground: #0c0e12; --ivory: #f1eee2; --ember: #ff6a3d; }
+  html, body { margin: 0; width: 1200px; height: 600px; overflow: hidden; background: var(--ground); font-family: "JetBrains Mono"; }
+  #world { position: absolute; left: 0; top: 0; width: 1200px; height: 600px; }
+  #name { position: absolute; left: 0; right: 0; top: 356px; text-align: center; font-size: 120px; line-height: 1; color: var(--ivory); white-space: pre; letter-spacing: 2px; }
+  #motto { position: absolute; left: 0; right: 0; top: 500px; text-align: center; font-size: 19px; font-weight: 500; letter-spacing: 9px; color: #8a9096; }
+  #motto b { color: var(--ember); font-weight: 700; }
+  body.mask, body.mask * { color: #000 !important; background: #000 !important; border-color: #000 !important; }
+  body.mask #world { visibility: hidden; }
+  body.mask #name { color: #fff !important; background: transparent !important; }
+</style>
+</head>
+<body>
+<canvas id="world" width="1200" height="600"></canvas>
+<div id="name">LITGROK</div>
+<div id="motto">KEEP THE WORK <b>LIT.</b></div>
+<script type="module">
+import * as THREE from 'three';
+import { RoomEnvironment } from 'three/addons/environments/RoomEnvironment.js';
+import { RoundedBoxGeometry } from 'three/addons/geometries/RoundedBoxGeometry.js';
+
+// One scene for the whole loop. The hero is built once; renderFrame only poses it from t, so the
+// seam (t = 1 is t = 0 rebuilt) is exact and a fresh page draws the same frame.
+const renderer = new THREE.WebGLRenderer({ canvas: document.getElementById('world'), antialias: true });
+renderer.setPixelRatio(1);
+renderer.setSize(1200, 600, false);
+renderer.setClearColor(0x0c0e12, 1);
+renderer.outputColorSpace = THREE.SRGBColorSpace;
+renderer.toneMapping = THREE.ACESFilmicToneMapping;
+renderer.shadowMap.enabled = true;
+renderer.shadowMap.type = THREE.PCFSoftShadowMap;
+const scene = new THREE.Scene();
+scene.environment = new THREE.PMREMGenerator(renderer).fromScene(new RoomEnvironment(), 0.04).texture;
+const cam = new THREE.PerspectiveCamera(30, 2, 0.1, 100);
+cam.position.set(0, 1.9, 7.2);
+cam.lookAt(0, 0.7, 0);
+const key = new THREE.DirectionalLight(0xffffff, 2.2);
+key.position.set(3, 6, 4);
+key.castShadow = true;
+key.shadow.mapSize.set(2048, 2048);
+key.shadow.radius = 4;
+key.shadow.bias = -0.0004;
+key.shadow.normalBias = 0.03;
+scene.add(key, new THREE.HemisphereLight(0xf4f1ea, 0x101418, 0.6));
+const floor = new THREE.Mesh(new THREE.PlaneGeometry(40, 40), new THREE.ShadowMaterial({ opacity: 0.18 }));
+floor.rotation.x = -Math.PI / 2;
+floor.receiveShadow = true;
+scene.add(floor);
+const HERO = new THREE.Group();
+const block = new THREE.Mesh(
+  new RoundedBoxGeometry(2.6, 1.3, 1.3, 4, 0.3),
+  new THREE.MeshStandardMaterial({ color: 0x0f7a82, roughness: 0.35, metalness: 0.15 }),
+);
+block.position.y = 1.05;
+block.castShadow = true;
+HERO.add(block);
+scene.add(HERO);
+
+window.renderFrame = (t, o = {}) => {
+  document.body.className = o.mask ? 'mask' : '';
+  // The one beat: a full turn per loop, eased at neither end, so the seam cannot slip.
+  HERO.rotation.y = t * Math.PI * 2;
+  renderer.render(scene, cam);
+};
+// One warm-up frame before ready: one-time allocations (the shadow map's target, three.js object
+// ids) happen in the seeded build phase, so no frame ever reads unseeded entropy.
+window.renderFrame(0);
+window.ready = true;
+</script>
+</body>
+</html>

package/.grok/skills/lit-typographic-motion/references/choice-first.md

@@ -0,0 +1,30 @@
+# Choose the house style first
+
+A film has no default look. Before the treatment names a style, ask the user to
+choose one: a numbered choice in the reply, the recommended style first with a
+one-sentence reason, then the alternatives. Skip only when the prompt names the
+style or says you choose; under bare `lit` the delegation is implicit, so choose
+and label the default. A named style is never re-asked.
+
+## Candidates
+
+| # | Style | Character | Reach for it when |
+|---|-------|-----------|-------------------|
+| 1 | `swiss-signal` | Dark ink ground, bone type, one teal signal; type lands exactly and cuts hard | Nothing in the request picks another (the default) |
+| 2 | `tidal` | Deep blue drift, pale type riding the current, one coral accent | The film flows, swells, or runs calm and slow |
+| 3 | `terminalcore` | Phosphor console type at typing pace, one signal hue, hard cuts | The film is about code, systems, or logs |
+| 4 | `paper` | Warm paper ground, near-black ink, soft springs, a calm hand | The film teaches, prints, or stays gentle |
+
+On the type path, `paper` is out (it has no type preset); recommend from the other three.
+
+## Recommendation order
+
+Recommend the style `pickStyle` would take, and say why in one sentence:
+
+1. The request names it (`swiss-signal`, `tidal`, `terminalcore`, `paper`, or a clear paraphrase).
+2. The project's `motion-house.json` names it.
+3. A keyword in the request or copy picks it (code, console, flow, calm, paper, teach).
+4. The genre picks it (explainer → `paper`, brand-mood → `tidal`).
+5. Otherwise `swiss-signal`.
+
+Put the chosen style in the treatment and name it in the reply. The `styles` command renders the same demo film in every house style for comparison when the user asks to see them.

package/.grok/skills/lit-typographic-motion/references/cover.md

@@ -61,7 +61,7 @@ naming the first bad field (`BLOCKED_TREATMENT_INVALID field=...`).
 | `mode` | `cover` |
 | `request` | the user's words, verbatim and inert |
 | `idea` | one sentence on what the loop does; it may not restate the request |
-| `recipe`, `recipeReason` | `painted-light` (default), `weight-tide`, `orbit-loop` or `own`, and why in 1-2 sentences |
+| `recipe`, `recipeReason` | `painted-light` (default), `hero-3d`, `weight-tide`, `orbit-loop` or `own`, and why in 1-2 sentences |
 | `brandWord` | the name, set once, at most three words |
 | `motto` | optional `{ text, source: user \| project, from }`, at most six words; a `user` motto appears in the request, a `project` motto names where the project already uses it |
 | `aspect`, `loopSec`, `fps` | `2:1` or `3:2`; 6-12; 16, 20 or 25 |
@@ -197,6 +197,15 @@ transfers.
   and a ledger under the word whose cells light at the crossing times (as many crossings as cells,
   so the ledger loops). The core breathes once per loop and rings out on each bar. The word stands
   still on the left.
+- **Turning hero (`hero-3d`).** The loop as an object, for a subject with a back and an inside: a
+  rounded hero turns once per loop under a key light on the GPU rung (software when the GPU has no
+  WebGL; the manifest names the rung), the brand word sits live over it, and the motto closes the
+  frame. Build the hero once and only pose it from `t`: the seam is exact and a fresh capture draws
+  the same pixels. Render one warm-up frame before `window.ready = true`, so one-time allocations
+  (the shadow map's target, three.js object ids) happen in the seeded build phase. Keep the word
+  clear of the hero: the title gate measures contrast against the worst background decile in its
+  box. The shipped page reached TARGET at q 86 (seamLocal 1.14, 0.61 MB); read it before modelling a
+  product hero from its real logo and screens, and keep the type in the DOM.
 - **Own.** Any system that keeps the rules: one rule many copies, three layers, a still word, edges
   instead of fades. Name it in `recipeReason`.
 

package/.grok/skills/lit-typographic-motion/references/depth.md

@@ -0,0 +1,119 @@
+# Depth: the 3D route
+
+Read this when the treatment's subject is a `depth3d` device (`depth: "3d"`), or when a cover takes
+the `hero-3d` recipe. A drawn 3D object is the right subject when the film is about a thing that has
+a back and an inside: a product that turns, opens, unfolds or is assembled. A flat diagram, a chart or
+type does not need it; keep those on the 2D page.
+
+## What the renderer gives you
+
+- **A pinned three.js.** The skill ships three.js r170 (npm `three@0.170.0`, MIT) in
+  `scripts/lib/vendor/three/`: the unminified `three.module.js` plus two addons,
+  `environments/RoomEnvironment.js` and `geometries/RoundedBoxGeometry.js`. The renderer serves them at
+  `/lit/three/`; a page imports them through an import map:
+
+  ```html
+  <script type="importmap">{ "imports": { "three": "/lit/three/three.module.js", "three/addons/": "/lit/three/addons/" } }</script>
+  <script type="module">
+    import * as THREE from "three";
+    import { RoomEnvironment } from "three/addons/environments/RoomEnvironment.js";
+  </script>
+  ```
+
+  Any other path under `/lit/three/` is refused as a missing file, and the network rules still hold:
+  never load three.js, a model or a texture from a CDN. The file hashes and the licence are in
+  `THIRD_PARTY_NOTICES`.
+- **The GPU rung.** A `depth: 3d` film and a `hero-3d` cover start Chrome on the platform's GPU rung
+  (ANGLE on Metal on macOS, GL on Linux, D3D11 on Windows), with GPU rasterization of the page
+  itself still off. The renderer records the WebGL renderer string, and the gate's WebGL line names
+  the rung and the renderer. The same determinism replay runs as on the software rung: a fresh
+  browser on the same rung must reproduce the sampled frames pixel for pixel, or the render stops with
+  exit 18.
+- **A labelled fallback.** When the GPU rung cannot start, or starts without WebGL, the render
+  reopens on the software rung (SwiftShader), adds a warning to the report and the manifest naming
+  the reason, and records `rung: "software"`. The film still renders, more slowly. Say in the reply
+  that it rendered without the GPU. Only when neither rung has WebGL is it exit 11.
+
+The rung is chosen from the treatment (`depth`) or the cover recipe, never by the page.
+
+## The scaffold's world
+
+`motion.mjs scaffold` on a `depth: 3d` treatment adds, on top of the 2D shots:
+
+- `<canvas id="world">` behind every shot's section, so the type stays DOM text the QA can read;
+- one renderer for the whole film (alpha, `preserveDrawingBuffer`, pixel ratio 1, ACES tone mapping,
+  soft shadows), a `RoomEnvironment` for reflections, a key light with a biased shadow, a hemisphere
+  light in neutral tones and a shadow-only floor;
+- `HERO`, a group that holds the protagonist from the first frame to the last;
+- `WORLD[i](s, hero, cam, t)`, one function per shot that poses the hero, the camera and anything else
+  as a function of the shot; the camera frames the full frame by default.
+
+Build the protagonist once, in `HERO`, and only pose it per shot: that is what makes it the same
+object across the film. For a named product, start from its real logo and screens: a fetched logo or
+screenshot goes on a plane or a face of the object as a texture (`TextureLoader` on the file under
+`stage/assets/`); a simple logo shape can be traced into a `THREE.Shape` and given depth with
+`ExtrudeGeometry`.
+
+## Craft and the gate
+
+- **Turn slowly.** A full turn takes the loop (a cover) or a whole shot (a film). Fast spins, a flicker
+  of specular highlights and shadow acne all read as flashes and fail MO-C-03.
+- **Bias the shadow.** On a turning object set `shadow.bias` about -0.0004 and `shadow.normalBias`
+  about 0.03; without them the self-shadow flickers frame to frame.
+- **Ease every open and close.** A lid, a drawer or an exploded view eases in and out, holds, and
+  returns; the move is the beat, so it happens once, where the treatment's story puts it.
+- **Keep the type in the DOM.** Copy stays in the shot as HTML text over the canvas;
+  text drawn inside the 3D scene is invisible to the QA unless registered with `LitStage.text`.
+- **Mind the dead air.** A small object on a large empty ground is `DEAD-AIR`; move the camera in.
+- **Covers at 20 fps.** The cover gate measures on a 50 ms grid; at 25 fps a smooth turn lands two
+  frames on one step at the seam (FLOOR), at 20 fps every step is one frame (TARGET). Encode at q94:
+  smooth light surfaces blotch at the default q86.
+
+## Camera moves and the flash audit
+
+A rich film moves its camera in at least half its shots, and the flash audit stays exactly as it is.
+When a move fails MO-C-03, keep the move and change what it passes over: slow the light change (a
+highlight that sweeps over 0.5 s or more, not a frame), lower the contrast of the detail behind the
+move, or cut instead of whipping. Removing the camera move is a downgrade.
+
+## The Blender rung (`render3d: "blender"`)
+
+For path-traced light (bevels that catch it, soft global illumination, depth of field, motion blur) a
+3D film can render its world in Blender with Cycles. The page then shows the rendered plate and keeps
+its type, labels and 2D layers in the DOM over it.
+
+Take this rung when the request asks for high-quality, cinematic or photoreal 3D (고퀄리티, 고품질,
+시네마틱, 실사, cinematic, photoreal, high-quality, Blender) and Blender is installed: `scaffold` prints
+`BLENDER:` with the path when both hold. On an Apple M-series GPU a full hero scene rendered at 8-10 s
+per 1080p frame at 160 samples, so a 13 s plate (390 frames) takes about an hour. Settle the scene on
+the preview stills first, since a fix after the final means rendering the plate again, and build the
+page's panels while it renders.
+
+1. Set `depth: 3d`, a `depth3d` subject and `render3d: "blender"`.
+2. Write `stage/scene.py`, a Blender Python scene. It runs inside the bundled runner with `bpy`,
+   `math`, `Vector` and `lit` in scope; times are film seconds and the plate starts at frame 1:
+   `lit.camera(location, target, lens, dof=(distance, fstop))`, `lit.area_light(name, location, target,
+   power, size, color)`, `lit.world(color, strength)`, `lit.material(name, color, roughness, metallic,
+   emission, strength)`, `lit.rounded_box(name, size, radius, segments, material, location)`,
+   `lit.image_card(name, path, width, location)` (a fetched product image as a card) and
+   `lit.key(obj, prop, t, value)`. The scene must set a camera. The command line sets size, samples,
+   device, fps and frames; the scene sets everything else.
+3. `motion.mjs blender --out <dir>` renders preview stills at the beat midpoints (50 %, 40 samples) into
+   `stage/plate-preview/`. Open them, compare them with any reference frames the user gave, and fix
+   `scene.py` before the final.
+4. `motion.mjs blender --out <dir> --final` renders the plate (full size, 160 samples, motion blur,
+   30 fps, `stage/plate/000001.png ...`) detached with a progress file; it can take most of an hour.
+   It writes `plate.json`, which lists every frame by name and size with the Blender version, device and
+   samples. Listed plate frames are not counted as page rasters; any other frame sequence is still a
+   flipbook (exit 17).
+5. On the page, `const show = LitStage.plate({ parent, count, fps: 30 })` returns `show(t)`; call it from
+   `render(t)`. The page renders on the software rung, and the stage refuses to start (exit 17) when the
+   plate is missing or does not cover the film.
+
+Blender is found from `LITGROK_BLENDER` (used only if it exists), the macOS app
+(`/Applications/Blender.app/Contents/MacOS/Blender`) or `blender` on PATH, and always runs headless as
+`blender -b --factory-startup --python-exit-code 1 -P runner.py -- ...` (so a scene exception fails
+the command instead of exiting 0), on Metal on Apple silicon, another GPU backend next, the CPU
+last; the receipt says which. Without Blender the command renders nothing and prints `FALLBACK`: set
+`render3d` to `three`, build the world in three.js on the GPU rung, and say so in the reply. The report
+and manifest name the plate (Blender version, Cycles device, samples).

package/.grok/skills/lit-typographic-motion/references/treatment.md

@@ -39,12 +39,17 @@ or a type-led cue in the request, and refuses `type` at 9:16.
 | `durationSec` | 4 to 90; at least 10 for announcement, event, explainer and motion-graphics unless the user asked for a length |
 | `beats[]` | `{t0, t1, purpose, onScreen, motion, sound}`; they cover 0 to `durationSec` with no gap over 0.25 s; each lasts at least 1.2 s; at least as many beats as the genre's arc |
 | `subject` | `{name, source: user or invented, specifics[]}`; a user subject is named in the request's words; an invented one has at least 2 concrete specifics (what it is or does, for whom, one distinctive detail) |
-| `visualDevices[]` | `{kind, role: subject, support or texture, beats[]}`; kinds: illustration, diagram, chart, icon, shape, path, mask, depth3d, particles, grid, gradient, photo-texture |
+| `visualDevices[]` | `{kind, role: subject, support or texture, beats[]}`; kinds: illustration, diagram, chart, icon, shape, path, mask, depth3d, screen, particles, grid, gradient, photo-texture; a `screen` device names a listed product asset in `asset` and shows the product's real screenshot, UI or README image, never an invented screen |
 | `typePlan` | `{faces[], hierarchy, maxWordsOnScreen, index?}`; faces from Archivo, Pretendard, VT323, Silkscreen, Galmuri9, Meslo; `index: true` only when the film should show a running shot index |
 | `palette[]` | 3 to 6 `{hex, role}` entries |
 | `sound` | `{mode: generated, supplied, authored or none, plan, palette, file?}`; see below |
 | `copy` | `{source: user or invented, lines[]}`; user lines are the request's own words (quoted spans included); invented lines may not restate the request |
 | `inventions[]` | every invented thing, named; required when the subject or copy is invented, and it names the invented subject |
+| `story` | `{expect, turn, beat, payoff}` on every film: what the viewer expects, what happens instead (at most 2 sentences each, never equal), the shot where the turn lands (after the opening, before the end: 1 to beats-1), what the ending gives |
+| `protagonist` | stage only: `{name, kind: character or object, look, acts[]}`; one drawn character or hero object that acts across the film, shot by shot (`{beat, action}`), covering at least half the film including the turn's shot, one act per shot |
+| `product` | when the request links a product, repo or site: `{name, url, assets[]}` with the request's link; assets are `{path, role, source, sha256}` under `stage/assets/` (`fetched` by `motion.mjs assets`, or `user` supplied); when nothing could be reached, `{name, url, unreachable}` instead and the film stops at exit 22 until the user supplies the files |
+| `depth`, `render3d` | `depth`: `2d` (default) or `3d`; a `depth3d` subject device needs `depth: 3d` (the 3D route, references/depth.md), and only the stage path takes it. `render3d`: `three` (the GPU rung, default) or `blender` (the offline Cycles rung, only with `depth: 3d`) |
+| `world` | a rich stage film's density, planned before any page exists: `{layers[], labels[], camera[]}`; at least 3 depth layers back to front, at least 6 labelled parts as they appear on screen (at most 4 words each; longer text is copy), camera moves (`{beat, move}`: push-in, truck, crane, orbit, rack focus) in at least half the shots; a locked shot is never listed. Minimal films (negative space) skip it |
 | `ambition` | 1 to 2 sentences, in craft terms, on what would make this film excellent for this request |
 | `seed` | optional integer; the stage page's `Math.random` is seeded from it (otherwise from the idea) |
 
@@ -106,6 +111,9 @@ mostly equals this example.
   "sound": { "mode": "generated", "plan": "<what the bed does across the arc>", "palette": "glass" },
   "copy": { "source": "invented", "lines": ["<line written from the subject's specifics>"] },
   "inventions": ["<subject name>", "<every other invented item>"],
+  "story": { "expect": "<what the viewer expects>", "turn": "<what happens instead>", "beat": 2, "payoff": "<what the ending gives>" },
+  "protagonist": { "name": "<subject name>", "kind": "<character or object>", "look": "<what it looks like on screen>", "acts": [{ "beat": 0, "action": "<what it does in this shot>" }] },
+  "world": { "layers": ["<back>", "<middle>", "<front>"], "labels": ["<part>", "<part>", "<part>", "<part>", "<part>", "<part>"], "camera": [{ "beat": 0, "move": "<push-in, truck, crane, orbit or rack focus>" }] },
   "ambition": "<what would make this film excellent, in craft terms>"
 }
 ```