@litfamily/litgrok 1.0.24 → 1.0.26

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (120) hide show
  1. package/.grok/hooks/auto-handoff.mjs +1 -1
  2. package/.grok/hooks/lit-status-line.mjs +414 -269
  3. package/.grok/hooks/plan-progress.mjs +11 -2
  4. package/.grok/hooks/record-passive-event.mjs +20 -9
  5. package/.grok/hooks/workflow-stage.mjs +48 -13
  6. package/.grok/rules/00-litgrok.md +21 -12
  7. package/.grok/skills/autoconference/SKILL.md +3 -1
  8. package/.grok/skills/autoresearch/SKILL.md +3 -1
  9. package/.grok/skills/browser-drive/SKILL.md +3 -1
  10. package/.grok/skills/browser-drive/scripts/capability-probe.mjs +2 -2
  11. package/.grok/skills/comment-checker/SKILL.md +3 -1
  12. package/.grok/skills/debugging/SKILL.md +3 -1
  13. package/.grok/skills/deep-interview/SKILL.md +4 -1
  14. package/.grok/skills/frontend-ui-ux/scripts/probe.mjs +3 -2
  15. package/.grok/skills/lit-brainstorm/SKILL.md +162 -0
  16. package/.grok/skills/lit-brainstorm/references/converge-and-score.md +85 -0
  17. package/.grok/skills/lit-brainstorm/references/handoff-and-notes.md +66 -0
  18. package/.grok/skills/lit-brainstorm/references/idea-lane-packet.md +58 -0
  19. package/.grok/skills/lit-brainstorm/references/idea-lenses.md +60 -0
  20. package/.grok/skills/lit-diagram-drawer/scripts/diagram-metrics.mjs +1 -1
  21. package/.grok/skills/lit-diagram-drawer/scripts/export.mjs +6 -6
  22. package/.grok/skills/lit-diagram-drawer/scripts/renderer-status.mjs +3 -3
  23. package/.grok/skills/lit-docx/SKILL.md +3 -1
  24. package/.grok/skills/lit-docx/scripts/convert_md_to_pdf.py +7 -4
  25. package/.grok/skills/lit-docx/scripts/docx_gate.py +5 -2
  26. package/.grok/skills/lit-docx/scripts/pdf_fonts.py +63 -0
  27. package/.grok/skills/lit-docx/scripts/run.mjs +3 -5
  28. package/.grok/skills/lit-docx/templates/latex/acs/template.tex +5 -0
  29. package/.grok/skills/lit-docx/templates/latex/elsevier/template.tex +5 -0
  30. package/.grok/skills/lit-docx/templates/latex/ieee/template.tex +5 -0
  31. package/.grok/skills/lit-docx/templates/latex/korean-generic/template.tex +5 -0
  32. package/.grok/skills/lit-docx/templates/latex/nature/template.tex +5 -0
  33. package/.grok/skills/lit-handoff/SKILL.md +3 -1
  34. package/.grok/skills/lit-humanizer/scripts/extract.mjs +6 -3
  35. package/.grok/skills/lit-humanizer/scripts/test-fixtures.mjs +3 -1
  36. package/.grok/skills/lit-plan/SKILL.md +2 -0
  37. package/.grok/skills/lit-pptx/SKILL.md +3 -1
  38. package/.grok/skills/lit-pptx/scripts/deps.cjs +18 -8
  39. package/.grok/skills/lit-pptx/scripts/proc.cjs +192 -0
  40. package/.grok/skills/lit-pptx/scripts/run.mjs +3 -5
  41. package/.grok/skills/lit-recap/SKILL.md +3 -1
  42. package/.grok/skills/lit-typographic-motion/SKILL.md +9 -6
  43. package/.grok/skills/lit-typographic-motion/THIRD_PARTY_NOTICES +3 -0
  44. package/.grok/skills/lit-typographic-motion/fonts/JetBrainsMono-OFL.txt +93 -0
  45. package/.grok/skills/lit-typographic-motion/fonts/JetBrainsMono-wght-latin.woff2 +0 -0
  46. package/.grok/skills/lit-typographic-motion/fonts/pins.json +15 -0
  47. package/.grok/skills/lit-typographic-motion/recipes/negatives/card-scenes/expected.json +16 -0
  48. package/.grok/skills/lit-typographic-motion/recipes/negatives/card-scenes/index.html +36 -0
  49. package/.grok/skills/lit-typographic-motion/recipes/negatives/reset-sweep/expected.json +16 -0
  50. package/.grok/skills/lit-typographic-motion/recipes/negatives/reset-sweep/index.html +24 -0
  51. package/.grok/skills/lit-typographic-motion/recipes/negatives/still-glow/expected.json +17 -0
  52. package/.grok/skills/lit-typographic-motion/recipes/negatives/still-glow/index.html +25 -0
  53. package/.grok/skills/lit-typographic-motion/recipes/negatives/title-slam/expected.json +17 -0
  54. package/.grok/skills/lit-typographic-motion/recipes/negatives/title-slam/index.html +37 -0
  55. package/.grok/skills/lit-typographic-motion/recipes/orbit-loop/expected.json +67 -0
  56. package/.grok/skills/lit-typographic-motion/recipes/orbit-loop/index.html +119 -0
  57. package/.grok/skills/lit-typographic-motion/recipes/painted-light/expected.json +95 -0
  58. package/.grok/skills/lit-typographic-motion/recipes/painted-light/index.html +192 -0
  59. package/.grok/skills/lit-typographic-motion/recipes/weight-tide/expected.json +67 -0
  60. package/.grok/skills/lit-typographic-motion/recipes/weight-tide/index.html +85 -0
  61. package/.grok/skills/lit-typographic-motion/references/cover.md +380 -0
  62. package/.grok/skills/lit-typographic-motion/references/craft-loop.md +4 -0
  63. package/.grok/skills/lit-typographic-motion/references/runtime.md +14 -3
  64. package/.grok/skills/lit-typographic-motion/references/stage.md +2 -1
  65. package/.grok/skills/lit-typographic-motion/references/treatment.md +5 -0
  66. package/.grok/skills/lit-typographic-motion/requirements-audio.txt +3 -3
  67. package/.grok/skills/lit-typographic-motion/scripts/lib/cache.mjs +1 -1
  68. package/.grok/skills/lit-typographic-motion/scripts/lib/chrome.mjs +14 -4
  69. package/.grok/skills/lit-typographic-motion/scripts/lib/constants.mjs +39 -0
  70. package/.grok/skills/lit-typographic-motion/scripts/lib/cover-assets.mjs +88 -0
  71. package/.grok/skills/lit-typographic-motion/scripts/lib/cover-capture.mjs +144 -0
  72. package/.grok/skills/lit-typographic-motion/scripts/lib/cover-gate.mjs +312 -0
  73. package/.grok/skills/lit-typographic-motion/scripts/lib/cover-image.mjs +111 -0
  74. package/.grok/skills/lit-typographic-motion/scripts/lib/cover-pool.mjs +62 -0
  75. package/.grok/skills/lit-typographic-motion/scripts/lib/cover-sheet.mjs +73 -0
  76. package/.grok/skills/lit-typographic-motion/scripts/lib/cover-treatment.mjs +104 -0
  77. package/.grok/skills/lit-typographic-motion/scripts/lib/cover-webp.mjs +134 -0
  78. package/.grok/skills/lit-typographic-motion/scripts/lib/cover.mjs +347 -0
  79. package/.grok/skills/lit-typographic-motion/scripts/lib/encode.mjs +1 -1
  80. package/.grok/skills/lit-typographic-motion/scripts/lib/gate.mjs +2 -2
  81. package/.grok/skills/lit-typographic-motion/scripts/lib/look.mjs +99 -7
  82. package/.grok/skills/lit-typographic-motion/scripts/lib/render.mjs +8 -11
  83. package/.grok/skills/lit-typographic-motion/scripts/lib/sound.mjs +1 -1
  84. package/.grok/skills/lit-typographic-motion/scripts/lib/stage.mjs +3 -1
  85. package/.grok/skills/lit-typographic-motion/scripts/lib/treatment.mjs +1 -0
  86. package/.grok/skills/lit-typographic-motion/scripts/motion.mjs +45 -3
  87. package/.grok/skills/lit-typographic-motion/scripts/prewarm.mjs +35 -22
  88. package/.grok/skills/lit-typographic-motion/scripts/stage/cover-init.js +44 -0
  89. package/.grok/skills/lit-typographic-motion/scripts/stage/loop-kit.js +96 -0
  90. package/.grok/skills/litgoal/SKILL.md +14 -2
  91. package/.grok/skills/litgrok/SKILL.md +30 -7
  92. package/.grok/skills/litresearch/SKILL.md +3 -1
  93. package/.grok/skills/litwork/SKILL.md +12 -1
  94. package/.grok/skills/lsp/SKILL.md +3 -1
  95. package/.grok/skills/lsp-setup/SKILL.md +3 -1
  96. package/.grok/skills/lsp-setup/scripts/lsp-server-table.mjs +3 -3
  97. package/.grok/skills/readme-studio/templates/hyperframes/package-lock.json +3 -3
  98. package/.grok/skills/readme-studio/templates/remotion/package-lock.json +3 -3
  99. package/.grok/skills/refactor/SKILL.md +3 -1
  100. package/.grok/skills/review-work/SKILL.md +20 -26
  101. package/.grok/skills/rules/SKILL.md +3 -1
  102. package/.grok/skills/start-work/SKILL.md +1 -1
  103. package/.grok/skills/structural-search/SKILL.md +3 -1
  104. package/.grok/skills/wikify/SKILL.md +2 -0
  105. package/.grok-plugin/plugin.json +2 -1
  106. package/CHANGELOG.md +18 -0
  107. package/README.md +12 -11
  108. package/README_ko-KR.md +12 -11
  109. package/bin/litgrok.mjs +7 -2
  110. package/bin/status-line-config.mjs +26 -14
  111. package/docs/assets/cover-motion-still.webp +0 -0
  112. package/docs/assets/cover-motion.webp +0 -0
  113. package/docs/assets/cover.webp +0 -0
  114. package/docs/assets/readme/README.md +5 -5
  115. package/docs/assets/readme/badge-version.svg +1 -1
  116. package/docs/assets/skills/lit-brainstorm.webp +0 -0
  117. package/docs/reference.md +18 -8
  118. package/docs/reference_ko-KR.md +19 -8
  119. package/package.json +3 -2
  120. package/plugin.json +1 -1
@@ -0,0 +1,85 @@
1
+ <!doctype html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <!-- Recipe: weight tide (weight-tide), type as material. A worked page: the brand word stays where
6
+ it is while one weight wave rolls through it and through faint rows of it that drift exactly
7
+ one word length per loop. JetBrains Mono has a real wght axis (100-800) and a fixed advance,
8
+ so nothing reflows while the weight moves. Replace NAME and the motto with the project's own. -->
9
+ <link rel="stylesheet" href="/lit/fonts.css">
10
+ <script src="/lit/loop-kit.js"></script>
11
+ <style>
12
+ :root { --ground: #080c12; --ivory: #f1eee2; --ember: #ff6a3d; }
13
+ html, body { margin: 0; width: 1200px; height: 600px; overflow: hidden; background: var(--ground); font-family: "JetBrains Mono"; }
14
+ #rows { position: absolute; inset: 0; }
15
+ .row { position: absolute; left: 0; white-space: pre; font-size: 56px; line-height: 1; }
16
+ .row span, #name span { display: inline-block; }
17
+ #band { position: absolute; left: 0; right: 0; top: 178px; height: 256px; background: var(--ground); border-top: 2px solid #1d2733; border-bottom: 2px solid #1d2733; }
18
+ #name { position: absolute; left: 0; right: 0; top: 196px; text-align: center; font-size: 176px; line-height: 1; color: var(--ivory); white-space: pre; }
19
+ #cursor { position: absolute; top: 372px; height: 9px; background: var(--ember); }
20
+ #motto { position: absolute; left: 0; right: 0; top: 400px; text-align: center; font-size: 19px; font-weight: 500; letter-spacing: 9px; color: #8a9096; }
21
+ #motto b { color: var(--ember); font-weight: 700; }
22
+ body.mask, body.mask * { color: #000 !important; background: #000 !important; border-color: #000 !important; }
23
+ body.mask #name, body.mask #name span { color: #fff !important; background: transparent !important; }
24
+ </style>
25
+ </head>
26
+ <body>
27
+ <div id="rows"></div>
28
+ <div id="band"></div>
29
+ <div id="name"></div>
30
+ <div id="cursor"></div>
31
+ <div id="motto">KEEP THE WORK <b>LIT.</b></div>
32
+ <script>
33
+ // One rule: a letter's weight is a swell of the loop phase, shifted by where the letter is on the
34
+ // screen, so the wave appears by itself across hundreds of copies. Slow: the rows drift one word
35
+ // per loop, alternate rows opposite ways (perpetual and linear, so the encoder always sees motion).
36
+ // Mid: the tide. Beat: a terminal cursor dwells under each letter, steps on with an overshoot and
37
+ // returns home on the last stop.
38
+ const { fract, mix, ease, swell, makeNoise, loopNoise, cubicPulse, clamp } = LitLoop;
39
+ const NAME = 'LITGROK', SEP = '·', SIZE = 56, ADV = SIZE * 0.6, ROW = 64;
40
+ const noise = makeNoise(11);
41
+ const offsetAt = (x, y, row) => 0.85 * (x / 1200) + 0.35 * (y / 600) + 0.06 * row;
42
+ const tide = (t, offset) => ease.gain(swell(fract(t - offset)), 2.4); // rests light and bold, turns fast
43
+
44
+ const rows = [];
45
+ for (let r = 0; r < 10; r += 1) {
46
+ const node = document.createElement('div');
47
+ node.className = 'row';
48
+ node.style.top = `${r * ROW - 18}px`;
49
+ const spans = [...(NAME + SEP).repeat(7)].map((ch) => { const s = document.createElement('span'); s.textContent = ch; node.appendChild(s); return s; });
50
+ document.getElementById('rows').appendChild(node);
51
+ rows.push({ node, spans, y: r * ROW + 10, dir: r % 2 ? 1 : -1, r });
52
+ }
53
+ const name = document.getElementById('name');
54
+ const letters = [...NAME].map((ch) => { const s = document.createElement('span'); s.textContent = ch; name.appendChild(s); return s; });
55
+ const cursor = document.getElementById('cursor');
56
+ const HSIZE = 176, HADV = HSIZE * 0.6, HX0 = (1200 - HADV * NAME.length) / 2;
57
+ const WORD = (NAME.length + 1) * ADV;
58
+
59
+ window.renderFrame = (t, o = {}) => {
60
+ document.body.className = o.mask ? 'mask' : '';
61
+ for (const row of rows) {
62
+ // Exactly one word of travel per loop keeps the drift seamless; loop noise breathes its phase.
63
+ const shift = row.dir * WORD * t - WORD * 1.5 + 6 * loopNoise(noise, t, row.r * 3.1, 0.9);
64
+ row.node.style.transform = `translateX(${shift}px)`;
65
+ const wobble = 0.05 * loopNoise(noise, t, 40 + row.r, 1.1);
66
+ row.spans.forEach((s, i) => {
67
+ const k = tide(t, offsetAt(shift + (i + 0.5) * ADV, row.y, row.r) + wobble);
68
+ s.style.fontVariationSettings = `"wght" ${Math.round(mix(100, 800, k))}`;
69
+ s.style.color = `rgb(${Math.round(mix(21, 46, k))},${Math.round(mix(30, 58, k))},${Math.round(mix(41, 74, k))})`;
70
+ });
71
+ }
72
+ // The name takes the same field over a narrower range, so it never thins below a readable weight.
73
+ letters.forEach((s, i) => {
74
+ s.style.fontVariationSettings = `"wght" ${Math.round(mix(340, 800, tide(t, offsetAt(HX0 + (i + 0.5) * HADV, 300, 4.5))))}`;
75
+ });
76
+ const stops = NAME.length + 1, x = t * stops, slot = Math.floor(x), f = x - slot;
77
+ const pos = slot < stops - 1 ? slot + ease.outBack(clamp((f - 0.62) / 0.38), 1.4) : NAME.length * (1 - ease.inCubic(clamp(f / 0.45)));
78
+ cursor.style.left = `${HX0 + Math.min(pos, NAME.length) * HADV + 6}px`;
79
+ cursor.style.width = `${HADV - 12}px`;
80
+ cursor.style.opacity = String(1 - 0.75 * (slot === stops - 1 ? 0 : cubicPulse(0.3, 0.12, f)));
81
+ };
82
+ document.fonts.load('400 56px "JetBrains Mono"').then(() => document.fonts.ready).then(() => { window.renderFrame(0); window.ready = true; });
83
+ </script>
84
+ </body>
85
+ </html>
@@ -0,0 +1,380 @@
1
+ # Cover mode: the README cover loop
2
+
3
+ Read this when the request is a README cover, a hero or banner loop, an animated project cover, or
4
+ any short picture that plays forever at the top of a page. Such a loop is not a film. It has no
5
+ beats, no arc, no ending, no sound and no copy lines: it is one picture that never stops moving and
6
+ never shows where it starts. Every other request stays on the film paths (`stage`, `make`), which
7
+ this mode does not change.
8
+
9
+ The film pipeline rewards the wrong things for a cover. Beats of at least 1.2 s, a new composition
10
+ per beat, stills at beat midpoints, a settled end card and a reading floor all pull a loop toward a
11
+ slide deck, and that is what earlier covers looked like. Cover mode replaces them with a loop
12
+ contract, a review that watches motion instead of stills, and a gate that reads the encoded file a
13
+ reader's browser will actually decode.
14
+
15
+ ## What changes from a film
16
+
17
+ | Film rule | Cover mode |
18
+ | --- | --- |
19
+ | Beats of at least 1.2 s, each showing something new | No beats: three speed layers and one system, each running the whole loop |
20
+ | A settled end card; holds are a reward | No ending: any hold over 0.5 s is a defect (G3) |
21
+ | 10 s minimum, "never shorten" | 6 to 12 s; 8 s suited every recipe |
22
+ | 16:9 or 9:16 | 2:1 (page 1200 x 600, cover 1000 x 500) or 3:2 (page 1200 x 800, cover 960 x 640) |
23
+ | A generated sound bed and the sound gates | Silent; `sound` is absent or `none` |
24
+ | An invented subject and invented copy lines | The brand word, plus at most one motto the user wrote or the project already uses |
25
+ | Title fade-in, a stage that fades up from black | Frame 0 is the poster and already the whole picture |
26
+ | Look questions about purpose and beats | Look questions about motion, the seam and damage (Review, below) |
27
+
28
+ ## Page contract
29
+
30
+ - Write `<dir>/cover/index.html`, with local files beside it (`cover/assets/`). The renderer serves
31
+ only that folder, the loop kit at `/lit/loop-kit.js` and the faces at `/lit/fonts.css`. The stage
32
+ path's static scan applies: no network, no `<video>`, `<audio>` or `<iframe>`, at most 24 rasters
33
+ and 8 MB, no animated raster, no flipbook.
34
+ - Lay the page out at the aspect's page size in CSS pixels. The renderer captures it at device scale
35
+ 2 and shrinks every capture to the cover size with Lanczos, so hairlines and small type are drawn
36
+ at twice the size they are shown.
37
+ - Define `window.renderFrame(t, { mask })` and set `window.ready = true` once fonts and images are
38
+ decoded. `t` is the loop time in [0, 1): frame `i` of `N` is `t = i / N`, so `t = 1` is never
39
+ drawn (it would repeat frame 0 and stutter at the seam).
40
+ - Everything on screen is a function of `t`. Frames are sought in any order and every frame is drawn
41
+ again in a fresh browser, so a frame may never depend on the one before it: no trail buffers, no
42
+ accumulated canvas, no counters. Clear every canvas you draw into.
43
+ - `Math.random`, `Date.now`, `new Date()`, `performance.now`, `requestAnimationFrame`, `setInterval`
44
+ and `crypto.getRandomValues` throw during capture, and the run stops with exit 18 naming the call.
45
+ CSS animations and transitions are switched off. Layout randomness comes from `LitLoop.rng(seed)`;
46
+ motion comes only from `t`.
47
+ - `renderFrame(t, { mask: true })` draws the title mask: the brand word white, everything else
48
+ black, in the same place. The mask is captured for every frame; G5 measures the title against its
49
+ own background through it and G6 measures its cap height.
50
+ - Faces: every stage face plus `"JetBrains Mono"`, a variable face with a real `wght` axis from 100
51
+ to 800 and a fixed advance, so weight motion never reflows a line. Load the weights you use with
52
+ `document.fonts.load` before setting `ready`.
53
+
54
+ ## The cover treatment
55
+
56
+ `<dir>/treatment.json` with `"mode": "cover"`. Every cover render checks it and stops with exit 16
57
+ naming the first bad field (`BLOCKED_TREATMENT_INVALID field=...`).
58
+
59
+ | Field | Rule |
60
+ | --- | --- |
61
+ | `mode` | `cover` |
62
+ | `request` | the user's words, verbatim and inert |
63
+ | `idea` | one sentence on what the loop does; it may not restate the request |
64
+ | `recipe`, `recipeReason` | `painted-light` (default), `weight-tide`, `orbit-loop` or `own`, and why in 1-2 sentences |
65
+ | `brandWord` | the name, set once, at most three words |
66
+ | `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 |
67
+ | `aspect`, `loopSec`, `fps` | `2:1` or `3:2`; 6-12; 16, 20 or 25 |
68
+ | `layers` | `{ slow, mid, beat }`: what moves on each speed layer |
69
+ | `system` | `{ rule, copies, offset }`: the one rule, what it is copied onto, where the offsets come from |
70
+ | `title` | `{ box: [x, y, w, h], kind: live \| painted }`: the brand word's box as fractions of the cover |
71
+ | `palette` | optional, 2-6 `{ color, role }` |
72
+ | `encode` | optional `{ q, edgeQ, edgeFrames }`; default q 86, with frame 0 and the last 15 frames at 97 |
73
+ | `seed` | optional integer for `LitLoop.rng` layout and the seek-order shuffle |
74
+ | `ambition` | 1-2 sentences in craft terms |
75
+
76
+ `copy`, `beats` and `lines` are refused (a cover never swaps text states), and so is any `sound`
77
+ other than `none`.
78
+
79
+ ## Assets (`assets.json`)
80
+
81
+ Every raster the page can load is listed in `<dir>/assets.json` before the first render, and the
82
+ list is checked before anything is captured:
83
+
84
+ ```json
85
+ { "assets": [{ "path": "cover/assets/base.png", "role": "base-art", "source": "user", "sha256": "<64 hex>", "box": [0.125, 0, 0.75, 1], "checkBox": [0.723, 0.1445, 0.1475, 0.778], "title": true }] }
86
+ ```
87
+
88
+ - `role` is `base-art`, `logo`, `wordmark` or `texture`; `source` is `user` (supplied) or
89
+ `generated` (made for this cover, and labelled as generated in the reply); `sha256` is the file's.
90
+ - A listed file that is missing stops the run with exit 22 `BLOCKED_ASSET_MISSING` and writes no
91
+ frame. Ask for the art or generate it; never draw a stand-in in its place. The `painted-light`
92
+ recipe needs a `base-art` entry. A raster under `cover/` that the list does not name, or a listed
93
+ file whose bytes changed, is exit 17.
94
+ - `box` is where the base art sits on the cover. After the render, frame 0 has to show the art: the
95
+ SSIM of `checkBox` (default: the whole box) in decoded frame 0 against the same region of the
96
+ source scaled into the box reaches 0.90 (the ART line). A page that relights a painting dims most of
97
+ it at frame 0 on purpose, so point `checkBox` at the part it leaves lit (the hero bay); it covers
98
+ at least 10 % of the box. The LitGrok line-up painting with the hero bay lit measured 0.946 there.
99
+ - `title: true` on the base art declares the brand word painted into it; only then is the title
100
+ exempt from the glyph-height floor, and G6 still measures and reports it as INFO.
101
+ - The art is scaled into its box, never cropped.
102
+
103
+ ## Craft rules, ranked
104
+
105
+ 1. **The encoder is part of the design.** Lossy animated WebP treats a pixel as unchanged when it
106
+ moves less than about `31(1 - sqrt(q/100)) + sqrt(q/100)` levels from the previous frame: about 6
107
+ levels at q72 and 3 at q90. Slow fades and slow breathing below that are dropped, go stale, and
108
+ snap back at the next keyframe, which by default is the loop point. This failure is invisible in
109
+ the PNG frames and plain in the decoded file, which is why the gate decodes.
110
+ 2. **Light is a moving edge, not an in-place fade.** A travelling window with a 24-40 px edge
111
+ survives the encoder; a 150 px soft edge does not at q72 (the moving share fell from 0.92 to 0.83
112
+ and the seam jumped to 24 times its neighbours on the same frames). At a high edge quality the soft
113
+ edge survives and reads as a wash instead: no motion gate sees that, so the look review has to.
114
+ 3. **Something translates.** A weight tide alone lost most of its motion in the encoder (median step
115
+ 0.0007, seam 14x); one word of row drift per loop kept all of it (0.0098, seam 1.1x).
116
+ 4. **One rule, many copies, offsets from position.** One swell over hundreds of letters, one orbit
117
+ rule on three rings, one light window over the bays. Offsets come from x, y, angle or loop noise
118
+ and the wave appears by itself. No timeline, no scenes.
119
+ 5. **Three speed layers.** A slow, perpetual, linear layer (drift, laps, rising motes), a mid swell
120
+ (the tide, the light window) and beat events (a cursor step with `outBack`, a gate flash, a lens
121
+ pulse, a flare). Every cover that reached TARGET had all three.
122
+ 6. **The brand word is set once and never leaves.** It is the material (its weight moves, its place
123
+ does not), or it stands still beside the system, or it is painted into the base art. Motion
124
+ happens in, around or behind it.
125
+ 7. **Frame 0 is the poster.** Reduced-motion readers, thumbnails and slow networks show it alone, so
126
+ it is the whole picture: no fade from black, no empty opening.
127
+ 8. **Bands are flat steps, and every step clears the threshold.** A 3 px leading line with a two-step
128
+ afterglow (0.10, 0.05) passed; a third 0.03 step drifted and pushed the seam from 1.71 to 2.48. A
129
+ single flat slab encodes well but reads as a box.
130
+ 9. **Exponential tails are slow fades.** `expImpulse` sits under the threshold for half the loop. Use
131
+ the symmetric `cubicPulse` for beat events and put one across `t = 0`, so the keyframe reset lands
132
+ under motion.
133
+ 10. **Small movers over texture are expensive.** Each mote over a painting makes the encoder re-send
134
+ the textured blocks around it; keep motes few and mostly on the plain wings.
135
+ 11. **Use the painted title instead of laying live text over it.** Live text set at a painting's
136
+ scale came out about 11 px tall in a README. The painted word is the title, and its mask is the
137
+ letters above the plate's level. When G5 finds the painted letters under 4.5:1, lift them in
138
+ place with a luminance-keyed gain (only pixels above the plate's level brighten, so the plate
139
+ stays black): that took one painted word from 1.8:1 to 4.9:1.
140
+ 12. **Spend quality at the seam, not on keyframes.** Once every edge is sharp, what is left at the
141
+ loop point is requantisation: keyframe 0 and the frames before it carry different error. Raise
142
+ the quality of frame 0 and the last second (`edgeQ`, `edgeFrames`) and keep the default
143
+ keyframes. Periodic keyframes spread the snap into visible pops; a small `-kmax` made a 2.5-5 Hz
144
+ shimmer.
145
+ 13. **16 fps for slow painted covers, 25 for a system with fast dots.** 20 fps cost 18 % more and
146
+ dropped the median step under 0.0015 on the painted cover. At 16 fps img2webp writes 63 ms
147
+ frames, so an 8 s loop is 8.064 s; that is fine.
148
+
149
+ ## Recipes
150
+
151
+ Each recipe ships as a worked page in `recipes/<name>/index.html` with the gate row it reached in
152
+ `recipes/<name>/expected.json`. Copy the page into `<dir>/cover/`, then replace the name, the motto
153
+ and, for the painted recipe, the `PAINTING` block. The pages are examples; the rules above are what
154
+ transfers.
155
+
156
+ - **Painted base + travelling light (`painted-light`, the default).** A finished painting (supplied,
157
+ or generated and labelled) is the whole picture and the page relights it. The painting keeps its
158
+ own coordinates and is scaled, never cropped; at 2:1 a 3:2 painting is pillarboxed and the wings
159
+ stay quiet (a static spill, a few motes). Mid: a light window with a 24 px feather walks the dim
160
+ bays once per loop, and each bay gets a scan band twice per loop, offset by its position. Slow: a
161
+ comet laps the hero frame; motes rise one screen per loop. Beat: the hero's lenses light in turn,
162
+ one fast skewed glint crosses the title in **overlay** blend (screen lights a visible box;
163
+ colour-dodge turned a coloured letter into a red block), and the accent word pulses at `t = 0` and
164
+ `t = 0.5`. The LitGrok line-up reached TARGET at q 79 with frame 0 and the last 44 frames at 95 (seamLocal
165
+ 1.83, 1.98 MB). At q 80 with the last 30 frames at 97 the seam sat at 1.92, and an earlier rerun
166
+ reached 2.03-2.04, past the target; at q 83 with the last 18 frames at 97 it missed too.
167
+ More frames at a high edge quality lower the seam and cost bytes, so a seam margin is bought with
168
+ the size budget, never with a looser threshold.
169
+
170
+ **Choosing the hero.** Any bay can be the hero, so a cover can feature one machine of a shared
171
+ line-up. Three things move together:
172
+ 1. `PAINTING.hero` is the bay index (0 is the leftmost bay). The dim pool still spans the first to
173
+ the last dim bay, so the light window walks every bay as one continuous light, but it is
174
+ clipped around the hero bay: a hero in the middle stays at source brightness. The comet laps
175
+ the hero's border and its scan band stays at full strength.
176
+ 2. `PAINTING.lenses` maps a bay index to the lenses measured on that machine (`[x, y, radius]` in
177
+ painting pixels). Only the hero's entry lights. A hero with no entry stops the page with
178
+ `PAINTING.lenses has no entry for the hero bay N` (the render ends as `STAGE_CONTRACT_ERROR`
179
+ after the 60 s ready wait), because borrowing another machine's coordinates draws its lenses
180
+ on the wrong body. Measure them, or write `[]` for that bay to run with no lenses and say so
181
+ in the treatment's beat layer. A hero index that is not a bay stops the page the same way.
182
+ 3. The base art's `checkBox` in `assets.json` points at the hero bay. With the shipped layout
183
+ (painting scaled by `S = 600 / 1024` and pillarboxed 150 px from the left of a 1200 x 600
184
+ page) a bay `[x0, x1]` with panel `top` and `bottom` is
185
+ `[(150 + x0·S) / 1200, top·S / 600, (x1 - x0)·S / 1200, (bottom - top)·S / 600]`. A box left
186
+ on another bay measures a dimmed bay and the ART line fails.
187
+
188
+ The accent flare and the title glint belong to the painted motto and title, not to the hero, and
189
+ stay where they are.
190
+ - **Weight tide (`weight-tide`).** Rows of the brand word in JetBrains Mono at about 1.3:1 to the
191
+ ground drift one word length per loop, alternate rows opposite ways. Weight is
192
+ `gain(swell(fract(t - offset)), 2.4)` with `offset = 0.85 x / W + 0.35 y / H`. The name, on a
193
+ knockout band, takes the same field over 340-800 so it never thins. One accent: a cursor that
194
+ dwells under each letter, steps on with `outBack` and returns home.
195
+ - **Orbit loop (`orbit-loop`).** Three rings with whole laps per loop (3, 2, 1) in alternating
196
+ directions, dots with fading arc trails, a gate at twelve o'clock that flashes on each crossing,
197
+ and a ledger under the word whose cells light at the crossing times (as many crossings as cells,
198
+ so the ledger loops). The core breathes once per loop and rings out on each bar. The word stands
199
+ still on the left.
200
+ - **Own.** Any system that keeps the rules: one rule many copies, three layers, a still word, edges
201
+ instead of fades. Name it in `recipeReason`.
202
+
203
+ ## Loop kit (`/lit/loop-kit.js`)
204
+
205
+ `LitLoop` holds `rng(seed)` (mulberry32, layout only); `makeNoise(seed)` and
206
+ `loopNoise(noise, t, offset, radius)` (value noise read on a circle, so it closes at `t = 1`);
207
+ `ease.smooth`, `ease.outCubic`, `ease.inCubic`, `ease.outExpo`, `ease.outBack(p, s)`,
208
+ `ease.gain(p, k)`; `cubicPulse(c, w, x)` and `expImpulse(x, k)`; `phase(t, offset, cycles)`;
209
+ `cdist(p, c)` (distance around the loop, for an event that straddles `t = 0`); `window(p, start,
210
+ dur)` (a one-shot event inside the loop, -1 outside); `steps(p, stops, travel, ease)` (hold and
211
+ move); `swell(p)`; `TAU`, `clamp`, `fract`, `mix`. Every helper is pure or periodic in `t`.
212
+
213
+ ## Encode
214
+
215
+ `img2webp`, lossy, loop forever, `-m 4`, every frame `-d round(1000 / fps)` ms, frame 0 and the last
216
+ `edgeFrames` frames at `edgeQ`, default keyframes. `-m 6` took minutes and gained little; `-mixed`
217
+ changes nothing while every frame is lossy. When `img2webp` or `dwebp` (the gate decodes with it) is
218
+ missing, `gifski` is the fallback at quality 90. Neither is exit 21 `BLOCKED_NO_COVER_ENCODER`. A
219
+ cover is never an MP4: README renderers do not autoplay video.
220
+
221
+ ## Gate (decoded file)
222
+
223
+ The gate decodes the cover (each frame through `dwebp`, composited as a browser shows it) and
224
+ measures on a fixed grid of `max(50 ms, shortest frame)`, because the encoder merges identical
225
+ frames into long ones and frame counts would flatter a slide film. `d` is the mean |change in luma|
226
+ (0..1, at about 300 px wide) per grid step, and the loop is a ring, so the seam is one more step.
227
+
228
+ | Gate | Metric | FLOOR (fails) | TARGET (cover mode) |
229
+ | --- | --- | --- | --- |
230
+ | G0 determinism | SHA-256 per frame, two captures in fresh browsers | 100 % identical | same |
231
+ | G1 budget | bytes, duration, loop | ≤ 3 MiB, 6-12 s, loop 0 | ≤ 2 MiB |
232
+ | G2 motion energy | median d; share of moving steps | ≥ 0.0004; ≥ 0.45 | ≥ 0.0015; ≥ 0.95 |
233
+ | G3 anti-slide | longest still run; max d / median d | ≤ 2.0 s | ≤ 0.5 s, spike ≤ 6 |
234
+ | G4 seam | seam / mean of the two steps on each side | ≤ 8 | 0.25-2.0 |
235
+ | G5 title contrast | median title pixel vs the worst background decile in the box, every frame, through the mask | ≥ 4.5:1 | same |
236
+ | G6 title size | cap height of the title glyphs in the mask at the README width (830 px) | ≥ 24 px | same; a title painted into declared base art is INFO |
237
+ | SEEK order | 16 frames in a seeded shuffled order in a fresh page, against the master | identical, or within one level per channel (else exit 18 naming the frame and its time) | same |
238
+ | ART | SSIM of the base art's check box in decoded frame 0 against the source | ≥ 0.90 | same |
239
+ | FLASH | WCAG 2.3.1 flashes in any 1 s window, the loop wrapped | ≤ 3 general, ≤ 3 red | same; a FAIL withholds the cover under `withheld/` |
240
+
241
+ FLOOR was set so eight earlier painted covers pass and four slide-like negatives fail; TARGET is
242
+ what cover mode delivers, and those earlier covers miss it on purpose (a 1.9 s hold, a flash at the
243
+ seam). A cover render exits 13 until every gate reaches TARGET, 2 MiB included. G2 and G3 are
244
+ area-weighted: a small comet on a still picture counts as still at thumbnail scale, which is
245
+ intended. Never raise a number, shorten the loop or drop a layer to pass; fix the cause.
246
+
247
+ G6 splits the mask's title pixels into connected glyphs, leaves out dots and accents (under 1 % of
248
+ the largest glyph's area or 30 % of the tallest), takes the median glyph height of the smallest of
249
+ twelve samples and scales it from the cover width to 830 px. The seek-order check catches a page
250
+ that keeps state between frames (a trail drawn by never clearing a canvas): the sequential captures
251
+ agree with each other, and a frame sought out of order does not. The software rasterizer can round
252
+ a few text or opacity pixels one level apart depending on what it painted before, so a sought frame
253
+ within one level per channel passes and is counted as `oneLevel`; kept state differs by far more.
254
+
255
+ `node scripts/motion.mjs cover-gate <file> [--frames d --frames2 d --masks d --title x,y,w,h]
256
+ [--strict] [--json]` runs the same gate on any cover file.
257
+
258
+ ## Review
259
+
260
+ Every cover render writes, from the DECODED file:
261
+
262
+ - `stills/sheet.png`: twelve frames at `t = k / 12` above a plot of every grid step's `d`, the still
263
+ threshold (red dashes) and the median (green dots). A hold is a flat run on the dashes; encoder
264
+ pops are regular spikes; a reset is a spike at the right end.
265
+ - `stills/poster.png` (frame 0) and `stills/seam.png` (the last frame beside frame 0);
266
+ - `stills/frame-00.png` to `frame-11.png`, the sheet's frames at full size.
267
+
268
+ Open the sheet, the poster and the seam pair with Grok Build's image viewing (the same tool the
269
+ film loop uses; `craft-loop.md`) and look at them; a file listing is not a look. The gate cannot see
270
+ damage: the two worst defects of the first painted cover, a colour-dodge glint that turned a letter
271
+ into a red block and a wing glow that read as a dark disc, were found only by eye on the sheet.
272
+
273
+ Answer all eight every round, each naming a stills file and what you saw in it:
274
+
275
+ 1. Is something moving in every half-second window (the plot never lies flat on the dashes)?
276
+ 2. Does the seam disappear in the decoded file (`seam.png`, the right end of the plot)?
277
+ 3. Does it still move after encoding: no region that freezes and then pops?
278
+ 4. Is the brand word present, legible and in place in every frame, never faded or swapped?
279
+ 5. Are all three speed layers visible: a slow perpetual layer, a mid swell, beat events?
280
+ 6. Does anything read as a slide, a card swap, a title fade or an end card, or does light wash in
281
+ place instead of travelling as an edge?
282
+ 7. Is any glyph, glint or glow damaged: a colour block, a dark disc, a visible box?
283
+ 8. Name one thing a skilled motion designer would add or remove, or `none`.
284
+
285
+ A `no` on 1-5, a `yes` on 6 or 7, or anything but `none` on 8 asks for another round. Record the
286
+ round with `look --out <dir> --round <N> --answers <file>`. The answers file has the film's shape
287
+ (`viewed`, `answers` with `q`, `verdict`, `frame`, `observed`) with eight answers and no
288
+ `weakestBeat`; round 1 names the `change` you make before round 2. With no image tool reachable,
289
+ `--blocked no-vision-tool` ends the cover `DONE_UNVIEWED`, said plainly in the reply.
290
+
291
+ ## Defects and window re-renders
292
+
293
+ What the eye finds goes into the round as `defects`, at most three, worst first:
294
+
295
+ ```json
296
+ "defects": [{ "t": 1.2, "region": [340, 10, 330, 50], "frame": "stills/frame-02.png", "observed": "<what is visible there>", "cause": "<why>", "fix": "<the change>" }]
297
+ ```
298
+
299
+ `t` is the loop time in seconds where the defect shows, `region` the `[x, y, w, h]` it covers in cover
300
+ pixels, `frame` a file of the current stills set that shows it. `look` refuses a defect with no time,
301
+ a time outside the loop, a region off the cover, or a frame outside the current stills set.
302
+
303
+ Check each fix before the next full render with
304
+ `node scripts/motion.mjs cover --out <dir> --round <N> --window <t0>,<t1>`: it captures only the
305
+ frames from `t0 - 0.5 s` to `t1 + 0.5 s` (wrapping at the seam) in a fresh page and writes
306
+ `windows/round-<N>/<t0>-<t1>/sheet.png` (the span shaded on its plot) and `window.json`. It shows the
307
+ frames before encoding, touches no stills, report or manifest, and never counts as done: the full
308
+ render and its gate decide.
309
+
310
+ ## Rounds and done
311
+
312
+ Rounds share one counter with the renders, 1 to 3, and every round is a full cover render followed
313
+ by a look. `node scripts/motion.mjs verify --out <dir>` says DONE when all of these hold: a valid
314
+ cover treatment unchanged since the last render; that render's report reading
315
+ `COVER gate --strict: PASS+TARGET`; at least two look rounds, the first naming its change; the last
316
+ round stamped with the final render's stills and viewing `stills/sheet.png`, `stills/poster.png` and
317
+ `stills/seam.png`. After round 3 deliver with the open items said plainly. A window render never
318
+ counts. When the cover is done, `verify` prints one line per asset `assets.json` marks as generated,
319
+ and the reply carries that label.
320
+
321
+ ## Recipe rows and negatives
322
+
323
+ Each recipe keeps its gate row in `recipes/<name>/expected.json` (median d, moving share, longest
324
+ still, spike, seamLocal, bytes, the settings and the treatment it shipped with). In a LitGrok
325
+ checkout `npm run qa:cover-recipes` re-renders every recipe through `cover --out` and fails when it
326
+ has no row, median d or the moving share leaves ±15 % of its row, seamLocal leaves TARGET, the file
327
+ passes 2 MiB or the render exits non-zero.
328
+
329
+ Every negative and regression declares the gates it must fail (`mustFail`, as `G2.floor` or
330
+ `G1.target`). `--negatives` renders the four negatives and every regression a recipe declares, and
331
+ one counts as caught only when its render completed and gated the decoded file (exit 0 or 13 with a
332
+ manifest), every declared gate failed at its tier, and no undeclared FLOOR gate among G1-G4 failed.
333
+ A crash, a missing declaration, a missing expected file, a patch whose search text left the page or a
334
+ failure on another gate fails the QA with the reason; a declared gate that was not measured is not
335
+ caught either.
336
+
337
+ The painted recipe declares one regression, `feather-150` (`--feather 150` runs it alone): the
338
+ light edge widened from 24 to 150 px. The defect it stands for is light drawn as a soft wash instead
339
+ of a moving edge, but at this recipe's encode (q 79, edge q 95 for 44 frames) the encoder keeps the
340
+ soft edge and the motion numbers stay where the recipe's are. What it reliably trips is the size
341
+ TARGET (G1: 2.58 MB against 1.98 MB), so `G1.target` is all it declares; seamLocal sits inside
342
+ run-to-run noise around its own TARGET, so no G4 is declared. A decoded-file edge measure was
343
+ considered and not added: it would score every soft change in the frame, not the travelling edge, and
344
+ any threshold would be fitted to one painting. The soft wash is caught by look review on the sheet
345
+ (question 6 under Review).
346
+
347
+ `recipes/negatives/` ships four slide-like pages that must keep failing on their named gates: a title
348
+ slam with lines that appear and hold before an end card (G2, G3), card scenes that fade in, hold and
349
+ fade out (G2), a still with a faint breathing glow (G2, G3), and a progress sweep that resets at the
350
+ seam (G4). They are never recipes: read them to see what cover mode exists to prevent, and never tune
351
+ a threshold so one of them passes.
352
+
353
+ ## Commands and exits
354
+
355
+ Run from the skill root:
356
+
357
+ ```bash
358
+ node scripts/motion.mjs cover --out <dir> --round <N>
359
+ node scripts/motion.mjs cover --out <dir> --round <N> --window <t0>,<t1>
360
+ node scripts/motion.mjs look --out <dir> --round <N> --answers <file>
361
+ node scripts/motion.mjs cover-gate <dir>/cover.webp --strict
362
+ node scripts/motion.mjs verify --out <dir>
363
+ ```
364
+
365
+ A cover render runs in the foreground; give the call a timeout of at least 600 s (the painted recipe
366
+ took about 3 minutes on the software rung). It writes `cover.webp` (or `cover.gif`), `poster.png`,
367
+ `stills/`, `manifest.json` and `gate-report.txt`. Exit 13 names the gates that miss TARGET; 16 the
368
+ treatment field; 17 the page contract or the asset list; 18 a call that is not a function of `t`, or
369
+ a frame that differs in a fresh browser or when sought out of order; 19 a network request; 21 no cover
370
+ encoder; 22 a listed asset is missing. `gate --out <dir>` on a cover points at `cover-gate`.
371
+
372
+ ## Unconfirmed
373
+
374
+ - Whether the single keyframe reset at the loop point is visible to a person on a real README; the
375
+ numbers say smooth, nobody has watched it there yet.
376
+ - How a cover reads inside GitHub's README column at full width; review so far used local frames.
377
+ - The encoder threshold formula comes from libwebp's animation encoder as remembered; measured
378
+ behaviour matches it (q72 drops slow fades, q86-90 drops fewer).
379
+ - The thresholds come from 8 positives and 4 negatives in one family's style; re-check them on covers
380
+ made for other projects.
@@ -4,6 +4,10 @@ This is the working order for one film on either path. The renderer draws, captu
4
4
  the agent directs, looks and fixes. A gate PASS proves hygiene (flash safety, legibility, size,
5
5
  determinism), not quality, so a PASS never ends the loop by itself.
6
6
 
7
+ A README cover loop runs its own loop (`cover.md`): no stills-only round, eight cover questions read
8
+ from the decoded contact sheet, the poster and the seam pair, and done only at TARGET on the decoded
9
+ file. Everything below is the film loop.
10
+
7
11
  ## Phase 0: treatment
8
12
 
9
13
  Write `treatment.json` in the output directory (`treatment.md`). Under bare `lit` ask no questions:
@@ -11,6 +11,8 @@ touches the network either; it only prints where to pre-warm.
11
11
  must use the same pinned lockfile. The install receipt, `status` and every BLOCKED message print the
12
12
  command with that version filled in; copy it from there.
13
13
 
14
+ Outside Grok Build (Grok Bot, Cursor): the skill root is wherever the host placed this folder; render there only when the host has Node.js and this pre-warmed cache, write films to a workspace path, and otherwise report the render as BLOCKED with the missing piece. The `litgrok` skill holds the full host mapping.
15
+
14
16
  ## The cache
15
17
 
16
18
  `${XDG_CACHE_HOME:-~/.cache}/litgrok/motion-runtime/<lock digest>/` for both install scopes,
@@ -26,26 +28,33 @@ never under `.grok/vendor/`. `LITGROK_MOTION_CACHE` (an absolute path) replaces
26
28
  `pip install --require-hashes --only-binary=:all:`;
27
29
  - `install.lock` — held while an install runs; a second install started meanwhile stops and says so.
28
30
 
29
- Archivo instances, VT323, Silkscreen and the five EMS stroke fonts ship inside the skill; the
31
+ Archivo instances, VT323, Silkscreen, JetBrains Mono (the variable face cover mode moves by weight)
32
+ and the five EMS stroke fonts ship inside the skill; the
30
33
  Hangul body pair is the lit-pptx skill's own Pretendard Regular and Bold, checked against
31
34
  LitGrok's recorded hashes.
32
35
 
33
36
  ## Commands
34
37
 
35
38
  - `npm exec --yes --package @litfamily/litgrok@<installed version> -- litgrok motion-runtime install` — deps and fonts; prints one line per item and the cache path.
36
- - `npm exec --yes --package @litfamily/litgrok@<installed version> -- litgrok motion-runtime install --audio` — also the Tier 2 venv (needs `uv` or Python 3.11-3.13).
39
+ - `npm exec --yes --package @litfamily/litgrok@<installed version> -- litgrok motion-runtime install --audio` — also the Tier 2 venv (needs `uv`, or Python 3.12 or 3.13 on PATH; a newer `python3` such as 3.15 is passed over because the pinned wheels do not cover it).
37
40
  - `npm exec --yes --package @litfamily/litgrok@<installed version> -- litgrok motion-runtime install --word-timing` — prints the model table (id, revision,
38
41
  licence, size) before any download. While any pin is unverified it fails closed and downloads
39
42
  nothing; Tier 3 then stays unavailable.
40
- - `npm exec --yes --package @litfamily/litgrok@<installed version> -- litgrok motion-runtime status` — the five probes, every time:
43
+ - `npm exec --yes --package @litfamily/litgrok@<installed version> -- litgrok motion-runtime status` — the six probes, every time:
41
44
  1. Chrome path and version;
42
45
  2. ffmpeg path, version line and the preview encoder rung (`libwebp_anim`, `img2webp` or GIF);
43
46
  3. the WebGL2 renderer string from a real headless probe;
44
47
  4. the software-GL warning (SwiftShader, llvmpipe and the rest of the one canonical list), or the
45
48
  unknown-renderer warning when the debug extension is unavailable;
46
49
  5. pre-warm state: which deps or fonts are missing or hash-mismatched, and the fix command;
50
+ 6. the cover encoder: `img2webp` and `dwebp` from libwebp (cover mode encodes the README loop and
51
+ the gate decodes it again), else `gifski` as the GIF fallback, else `BLOCKED_NO_COVER_ENCODER`;
47
52
  plus the audio venv and word-timing model state.
48
53
 
54
+ Cover mode (`cover.md`) needs no pre-warm at all: it uses Chrome, the bundled faces and the host's
55
+ libwebp tools, which are never bundled and never installed by LitGrok. Install libwebp with the
56
+ system package manager (`brew install webp`, `apt install webp`).
57
+
49
58
  ## Exit codes
50
59
 
51
60
  | Exit | Name | Meaning and fix |
@@ -62,6 +71,8 @@ LitGrok's recorded hashes.
62
71
  | 18 | STAGE_NONDETERMINISTIC | a replayed sample frame differs from the master; the message names the frame and the region. Seed the randomness and drop wall-clock reads. |
63
72
  | 19 | STAGE_NETWORK_REQUEST | the page reached outside `http://lit.stage/` (a URL, a WebSocket, a peer connection). |
64
73
  | 20 | SOUND_INVALID | a planned track is missing from the film, cannot be decoded, or a generated bed opens silent. |
74
+ | 21 | BLOCKED_NO_COVER_ENCODER | cover mode found neither libwebp (`img2webp` and `dwebp`) nor `gifski`; nothing was captured. Install libwebp; a cover is never an MP4. |
75
+ | 22 | BLOCKED_ASSET_MISSING | a cover's `assets.json` lists a file that is not there, or the painted-light recipe lists no base art; nothing was captured. Supply or generate the art, never a drawn stand-in. |
65
76
 
66
77
  Exit 14 and exit 15 are both fixed by the pre-warm outside the session, never by retrying the render inside it. Name the code and the fix in the reply. Never report one cause as another: a missing cache is exit
67
78
  14 even when Chrome is also missing, because the cache is checked first; a WebGL2 failure with
@@ -27,7 +27,8 @@ Allowed files: html, js, mjs, css, svg, png, jpg, webp, gif, wav, woff, woff2, t
27
27
 
28
28
  `/lit/fonts.css` declares the verified faces with `font-display: block`: `Archivo` (weights 400,
29
29
  700, 900; `font-stretch` 75 %, 100 %, 125 %), `Pretendard` (Hangul, 400 and 700), `VT323`,
30
- `Silkscreen` (400, 700), `Galmuri9` and `Meslo` (both need the pre-warm). A face listed in
30
+ `Silkscreen` (400, 700), `Galmuri9` and `Meslo` (both need the pre-warm), and `JetBrains Mono`
31
+ (a variable face, `wght` 100 to 800 with a fixed advance, bundled for cover mode's weight motion). A face listed in
31
32
  `typePlan.faces` that is not warm exits 14; a tampered one exits 15. Set Hangul copy in
32
33
  `Pretendard` (for example `font-family: Archivo, Pretendard`) so no system font fills a gap.
33
34
 
@@ -5,6 +5,11 @@ before any render. The renderer validates it before every render, stills-only in
5
5
  16 (`BLOCKED_TREATMENT_INVALID`) naming the first field that fails. A treatment is data: nothing in
6
6
  it is executed or followed as an instruction.
7
7
 
8
+ A README, hero, banner or cover loop is not a film. Its treatment sets `"mode": "cover"` and
9
+ follows `cover.md` instead of this file: no beats, no arc, no sound, no copy lines, and none of the
10
+ film rules below (the 1.2 s beat, the 10 s floor, the 16:9 and 9:16 formats, the genre arcs). A film
11
+ render refuses a cover treatment and a cover render refuses a film one, each naming the other command.
12
+
8
13
  ## Choosing the path
9
14
 
10
15
  Decide the path in the treatment, never by habit.
@@ -58,9 +58,9 @@ audioread==3.1.0 \
58
58
  --hash=sha256:1c4ab2f2972764c896a8ac61ac53e261c8d29f0c6ccd652f84e18f08a4cab190 \
59
59
  --hash=sha256:b30d1df6c5d3de5dcef0fb0e256f6ea17bdcf5f979408df0297d8a408e2971b4
60
60
  # via librosa
61
- certifi==2026.7.22 \
62
- --hash=sha256:62f22742b58a1a33014a2b6b706588a8d7e2a88ae7bd1a6ebe8c992928483775 \
63
- --hash=sha256:741e2c3b351ddf169a738da9f2c048608ff7f2c5cc02f1ebc6b118bb090d5d55
61
+ certifi==2026.10.19 \
62
+ --hash=sha256:42d35340cc5b9ba78e818ddbff0c5b1c2b779de448a340fd1b989f5fa8670e1b \
63
+ --hash=sha256:035c1e85572b141bf1c3a3eff0e33a8eb74917522f2559075ff8d2fea780a1ae
64
64
  # via requests
65
65
  cffi==2.1.1 \
66
66
  --hash=sha256:046bfc24911b37851ee1b51aab8bffe713d89c68c6a057b09484ce9fd5f69b4e \
@@ -53,7 +53,7 @@ export const AUDIO_REQUIREMENTS = join(SKILL_ROOT, 'requirements-audio.txt');
53
53
  export function audioPins(pythonVersion = '3.12.0') {
54
54
  const pins = new Map();
55
55
  const [major, minor] = pythonVersion.split('.').map(Number);
56
- for (const line of readFileSync(AUDIO_REQUIREMENTS, 'utf8').split('\n')) {
56
+ for (const line of readFileSync(AUDIO_REQUIREMENTS, 'utf8').split(/\r?\n/)) {
57
57
  const match = line.match(/^([A-Za-z0-9_.-]+)==([^\s;\\]+)\s*(?:;\s*(.*?))?\s*\\?$/);
58
58
  if (!match) continue;
59
59
  const marker = match[3] ?? '';
@@ -38,6 +38,7 @@ export function resolveChrome(env = process.env) {
38
38
  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
39
39
  '/Applications/Chromium.app/Contents/MacOS/Chromium',
40
40
  '/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/usr/bin/chromium', '/usr/bin/chromium-browser',
41
+ ...['ProgramFiles', 'ProgramFiles(x86)', 'LOCALAPPDATA'].filter((name) => env[name]).map((name) => `${env[name]}\\Google\\Chrome\\Application\\chrome.exe`),
41
42
  'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
42
43
  ];
43
44
  return candidates.find((candidate) => existsSync(candidate)) ?? null;
@@ -192,17 +193,26 @@ export async function openRenderer({ executable, profileDir, softwareOnly = fals
192
193
  // display rate stays capped: an uncapped compositor starves Page.captureScreenshot.
193
194
  export const STAGE_FLAGS = Object.freeze(['--run-all-compositor-stages-before-draw', '--disable-checker-imaging', '--disable-new-content-rendering-timeout', '--disable-threaded-animation', '--disable-threaded-scrolling', '--disable-image-animation-resync', '--disable-lcd-text', '--force-color-profile=srgb', '--hide-scrollbars', '--mute-audio', '--force-device-scale-factor=1', '--disable-background-networking', '--disable-component-update', '--disable-sync', '--no-pings', '--metrics-recording-only']);
194
195
 
195
- export function stageArgs({ profileDir, width, height }) {
196
- const args = [...HOUSEKEEPING, `--user-data-dir=${profileDir}`, ...SWIFTSHADER_RUNG, ...COMMON_FLAGS, ...STAGE_FLAGS, `--window-size=${width},${height}`, `--host-resolver-rules=MAP * ~NOTFOUND , EXCLUDE ${STAGE.host}`];
196
+ // `scale` is the device scale: 1 for a film; a cover is captured at 2 and shrunk afterwards.
197
+ // `extra` flags ride after the stage set (a cover adds COVER_FLAGS).
198
+ export function stageArgs({ profileDir, width, height, scale = 1, extra = [] }) {
199
+ const flags = STAGE_FLAGS.map((flag) => (flag === '--force-device-scale-factor=1' ? `--force-device-scale-factor=${scale}` : flag));
200
+ const args = [...HOUSEKEEPING, `--user-data-dir=${profileDir}`, ...SWIFTSHADER_RUNG, ...COMMON_FLAGS, ...flags, `--window-size=${width},${height}`, `--host-resolver-rules=MAP * ~NOTFOUND , EXCLUDE ${STAGE.host}`, ...extra];
197
201
  return [...new Set(args), 'about:blank'];
198
202
  }
199
203
 
200
204
  // Launch one stage Chrome and attach a page target. Exit 10 when Chrome is missing or never
201
205
  // answers; WebGL is not probed here (exit 11 applies only when the page asks for it).
202
- export async function launchStage({ executable, profileDir, width, height, timeoutMs = 30000 }) {
206
+ // A cover's frames are compared across fresh browsers and sought out of order. With GPU raster on
207
+ // the software rung, large DOM text came out one level apart on a few pixels between fresh
208
+ // browsers (the still-glow negative: 3 of 3 pairs, 13-115 of 160 frames); CPU raster drew every
209
+ // frame identically in 5 of 5 pairs.
210
+ export const COVER_FLAGS = Object.freeze(['--disable-gpu-rasterization']);
211
+
212
+ export async function launchStage({ executable, profileDir, width, height, scale = 1, extra = [], timeoutMs = 30000 }) {
203
213
  if (!executable) throw new BlockedError(EXIT.NO_CHROME, 'BLOCKED_NO_CHROME: Chrome/Chromium not found; set CHROME_PATH to a Chrome executable');
204
214
  mkdirSync(profileDir, { recursive: true });
205
- const args = stageArgs({ profileDir, width, height });
215
+ const args = stageArgs({ profileDir, width, height, scale, extra });
206
216
  let stderr = '';
207
217
  let proc;
208
218
  try { proc = spawn(executable, args, { stdio: ['ignore', 'ignore', 'pipe', 'pipe', 'pipe'] }); } catch (error) { throw new BlockedError(EXIT.NO_CHROME, `BLOCKED_NO_CHROME: ${error.message}`); }