@litfamily/litcodex 1.0.27 → 1.0.29

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 (204) hide show
  1. package/README-Ko-KR.md +10 -10
  2. package/README.md +10 -10
  3. package/dist/cli.d.ts +3 -2
  4. package/dist/cli.js +73 -4
  5. package/dist/config-migration/cli.js +11 -3
  6. package/dist/install/generated-skill-payload-hashes.d.ts +58 -30
  7. package/dist/install/generated-skill-payload-hashes.js +58 -30
  8. package/dist/install/index.js +1 -1
  9. package/dist/install/motion-runtime.d.ts +4 -1
  10. package/dist/install/motion-runtime.js +15 -4
  11. package/dist/install/office-runtime.d.ts +10 -11
  12. package/dist/install/office-runtime.js +8 -3
  13. package/dist/install/skill-catalog.d.ts +1 -1
  14. package/dist/install/skill-catalog.js +1 -0
  15. package/dist/postinstall.js +16 -3
  16. package/dist/pty-helper.d.ts +7 -0
  17. package/dist/pty-helper.js +45 -0
  18. package/dist/run.d.ts +57 -0
  19. package/dist/run.js +354 -0
  20. package/marketplace/plugins/litcodex/.codex-plugin/plugin.json +1 -1
  21. package/marketplace/plugins/litcodex/components/auto-update/dist/auto-update.d.ts +12 -0
  22. package/marketplace/plugins/litcodex/components/auto-update/dist/auto-update.js +31 -2
  23. package/marketplace/plugins/litcodex/components/auto-update/package.json +1 -1
  24. package/marketplace/plugins/litcodex/components/comment-checker/package.json +1 -1
  25. package/marketplace/plugins/litcodex/components/git-bash/package.json +1 -1
  26. package/marketplace/plugins/litcodex/components/lit-loop/directive.md +2 -1
  27. package/marketplace/plugins/litcodex/components/lit-loop/directives/deep-interview.md +2 -0
  28. package/marketplace/plugins/litcodex/components/lit-loop/directives/lit-brainstorm.md +216 -0
  29. package/marketplace/plugins/litcodex/components/lit-loop/directives/litgoal.md +8 -1
  30. package/marketplace/plugins/litcodex/components/lit-loop/directives/review-work.md +12 -4
  31. package/marketplace/plugins/litcodex/components/lit-loop/dist/card-status.d.ts +8 -3
  32. package/marketplace/plugins/litcodex/components/lit-loop/dist/card-status.js +11 -6
  33. package/marketplace/plugins/litcodex/components/lit-loop/dist/codex-hook.d.ts +6 -1
  34. package/marketplace/plugins/litcodex/components/lit-loop/dist/codex-hook.js +16 -5
  35. package/marketplace/plugins/litcodex/components/lit-loop/dist/guards.d.ts +3 -1
  36. package/marketplace/plugins/litcodex/components/lit-loop/dist/guards.js +5 -2
  37. package/marketplace/plugins/litcodex/components/lit-loop/dist/hook-cli.d.ts +2 -0
  38. package/marketplace/plugins/litcodex/components/lit-loop/dist/hook-cli.js +53 -17
  39. package/marketplace/plugins/litcodex/components/lit-loop/dist/hud-cli.d.ts +38 -0
  40. package/marketplace/plugins/litcodex/components/lit-loop/dist/hud-cli.js +155 -0
  41. package/marketplace/plugins/litcodex/components/lit-loop/dist/hud.d.ts +42 -0
  42. package/marketplace/plugins/litcodex/components/lit-loop/dist/hud.js +297 -0
  43. package/marketplace/plugins/litcodex/components/lit-loop/dist/markers.d.ts +2 -0
  44. package/marketplace/plugins/litcodex/components/lit-loop/dist/markers.js +2 -0
  45. package/marketplace/plugins/litcodex/components/lit-loop/dist/modes.d.ts +1 -1
  46. package/marketplace/plugins/litcodex/components/lit-loop/dist/modes.js +9 -1
  47. package/marketplace/plugins/litcodex/components/lit-loop/dist/motion-route.js +2 -0
  48. package/marketplace/plugins/litcodex/components/lit-loop/dist/plan-persistence.d.ts +2 -0
  49. package/marketplace/plugins/litcodex/components/lit-loop/dist/plan-persistence.js +8 -0
  50. package/marketplace/plugins/litcodex/components/lit-loop/dist/reentry.d.ts +56 -0
  51. package/marketplace/plugins/litcodex/components/lit-loop/dist/reentry.js +171 -0
  52. package/marketplace/plugins/litcodex/components/lit-loop/dist/route-context.js +5 -2
  53. package/marketplace/plugins/litcodex/components/lit-loop/dist/route-heads.js +35 -15
  54. package/marketplace/plugins/litcodex/components/lit-loop/dist/run-filter.d.ts +23 -0
  55. package/marketplace/plugins/litcodex/components/lit-loop/dist/run-filter.js +142 -0
  56. package/marketplace/plugins/litcodex/components/lit-loop/dist/run-panel.d.ts +29 -0
  57. package/marketplace/plugins/litcodex/components/lit-loop/dist/run-panel.js +102 -0
  58. package/marketplace/plugins/litcodex/components/lit-loop/dist/screen-card.d.ts +24 -0
  59. package/marketplace/plugins/litcodex/components/lit-loop/dist/screen-card.js +104 -0
  60. package/marketplace/plugins/litcodex/components/lit-loop/dist/screen-status.d.ts +24 -0
  61. package/marketplace/plugins/litcodex/components/lit-loop/dist/screen-status.js +110 -0
  62. package/marketplace/plugins/litcodex/components/lit-loop/dist/skill-mention-scope.js +2 -0
  63. package/marketplace/plugins/litcodex/components/lit-loop/dist/statusline.d.ts +17 -0
  64. package/marketplace/plugins/litcodex/components/lit-loop/dist/statusline.js +113 -0
  65. package/marketplace/plugins/litcodex/components/lit-loop/dist/trigger.d.ts +2 -2
  66. package/marketplace/plugins/litcodex/components/lit-loop/dist/trigger.js +15 -5
  67. package/marketplace/plugins/litcodex/components/lit-loop/dist/workflow-map.d.ts +7 -0
  68. package/marketplace/plugins/litcodex/components/lit-loop/dist/workflow-map.js +59 -10
  69. package/marketplace/plugins/litcodex/components/lit-loop/package.json +1 -1
  70. package/marketplace/plugins/litcodex/components/lsp/package.json +1 -1
  71. package/marketplace/plugins/litcodex/components/rules/bundled-rules/lit-humanizer.md +2 -0
  72. package/marketplace/plugins/litcodex/components/rules/dist/deliverable-hedge-guard.d.ts +8 -0
  73. package/marketplace/plugins/litcodex/components/rules/dist/deliverable-hedge-guard.js +381 -39
  74. package/marketplace/plugins/litcodex/components/rules/dist/model-metadata.d.ts +16 -0
  75. package/marketplace/plugins/litcodex/components/rules/dist/model-metadata.js +37 -1
  76. package/marketplace/plugins/litcodex/components/rules/package.json +1 -1
  77. package/marketplace/plugins/litcodex/components/start-work-continuation/package.json +1 -1
  78. package/marketplace/plugins/litcodex/components/telemetry/package.json +1 -1
  79. package/marketplace/plugins/litcodex/components/wikify-knowledge/package.json +1 -1
  80. package/marketplace/plugins/litcodex/skills/browser-drive/scripts/capability-probe.mjs +24 -4
  81. package/marketplace/plugins/litcodex/skills/deep-interview/SKILL.md +3 -1
  82. package/marketplace/plugins/litcodex/skills/lit-brainstorm/SKILL.md +271 -0
  83. package/marketplace/plugins/litcodex/skills/lit-brainstorm/agents/openai.yaml +6 -0
  84. package/marketplace/plugins/litcodex/skills/lit-diagram-drawer/scripts/doctor.mjs +4 -3
  85. package/marketplace/plugins/litcodex/skills/lit-diagram-drawer/scripts/export.mjs +6 -5
  86. package/marketplace/plugins/litcodex/skills/lit-diagram-drawer/scripts/runtime-probes.mjs +25 -0
  87. package/marketplace/plugins/litcodex/skills/lit-docx/scripts/convert_md_to_pdf.py +31 -1
  88. package/marketplace/plugins/litcodex/skills/lit-docx/templates/latex/acs/template.tex +2 -0
  89. package/marketplace/plugins/litcodex/skills/lit-docx/templates/latex/elsevier/template.tex +2 -0
  90. package/marketplace/plugins/litcodex/skills/lit-docx/templates/latex/ieee/template.tex +2 -0
  91. package/marketplace/plugins/litcodex/skills/lit-docx/templates/latex/korean-generic/template.tex +2 -0
  92. package/marketplace/plugins/litcodex/skills/lit-docx/templates/latex/nature/template.tex +2 -0
  93. package/marketplace/plugins/litcodex/skills/lit-humanizer/SKILL.md +4 -0
  94. package/marketplace/plugins/litcodex/skills/lit-humanizer/scripts/core.mjs +5 -1
  95. package/marketplace/plugins/litcodex/skills/lit-loop/SKILL.md +10 -2
  96. package/marketplace/plugins/litcodex/skills/lit-pptx/scripts/office-run.mjs +42 -10
  97. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/SKILL.md +11 -9
  98. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/agents/openai.yaml +3 -0
  99. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/engine/THIRD_PARTY_NOTICES +4 -0
  100. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/engine/constants.mjs +38 -0
  101. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/engine/cover-assets.mjs +113 -0
  102. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/engine/cover-capture.mjs +161 -0
  103. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/engine/cover-gate.mjs +327 -0
  104. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/engine/cover-image.mjs +136 -0
  105. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/engine/cover-init.js +43 -0
  106. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/engine/cover-sheet.mjs +69 -0
  107. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/engine/cover-treatment.mjs +102 -0
  108. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/engine/cover-worker.mjs +21 -0
  109. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/engine/cover.mjs +352 -0
  110. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/engine/driver.mjs +19 -1
  111. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/engine/fonts.mjs +11 -0
  112. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/engine/look.mjs +128 -2
  113. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/engine/loop-kit.js +104 -0
  114. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/engine/runtime.mjs +92 -18
  115. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/engine/stage.mjs +2 -0
  116. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/engine/treatment.mjs +3 -2
  117. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/engine/webp.mjs +140 -0
  118. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/fonts/jetbrains-mono/JetBrainsMono-wght-latin.woff2 +0 -0
  119. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/fonts/jetbrains-mono/OFL.txt +93 -0
  120. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/recipes/negatives/card-scenes/expected.json +16 -0
  121. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/recipes/negatives/card-scenes/index.html +42 -0
  122. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/recipes/negatives/reset-sweep/expected.json +16 -0
  123. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/recipes/negatives/reset-sweep/index.html +27 -0
  124. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/recipes/negatives/still-glow/expected.json +17 -0
  125. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/recipes/negatives/still-glow/index.html +29 -0
  126. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/recipes/negatives/title-slam/expected.json +17 -0
  127. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/recipes/negatives/title-slam/index.html +44 -0
  128. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/recipes/orbit-loop/expected.json +67 -0
  129. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/recipes/orbit-loop/index.html +182 -0
  130. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/recipes/painted-light/expected.json +95 -0
  131. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/recipes/painted-light/index.html +231 -0
  132. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/recipes/weight-tide/expected.json +67 -0
  133. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/recipes/weight-tide/index.html +103 -0
  134. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/references/cover.md +389 -0
  135. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/references/quality-gate.md +4 -0
  136. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/references/runtime.md +7 -6
  137. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/references/stage.md +3 -1
  138. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/references/treatment.md +2 -0
  139. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/scripts/render.mjs +37 -5
  140. package/marketplace/plugins/litcodex/skills/lit-typographic-motion/scripts/runtime.mjs +1 -1
  141. package/marketplace/plugins/litcodex/skills/litgoal/SKILL.md +8 -3
  142. package/marketplace/plugins/litcodex/skills/lsp-setup/scripts/verify-lsp.ts +43 -7
  143. package/marketplace/plugins/litcodex/skills/review-work/SKILL.md +21 -4
  144. package/node_modules/@litcodex/lit-loop/CHANGELOG.md +7 -0
  145. package/node_modules/@litcodex/lit-loop/README.md +6 -0
  146. package/node_modules/@litcodex/lit-loop/directive.md +2 -1
  147. package/node_modules/@litcodex/lit-loop/directives/deep-interview.md +2 -0
  148. package/node_modules/@litcodex/lit-loop/directives/lit-brainstorm.md +216 -0
  149. package/node_modules/@litcodex/lit-loop/directives/litgoal.md +8 -1
  150. package/node_modules/@litcodex/lit-loop/directives/review-work.md +12 -4
  151. package/node_modules/@litcodex/lit-loop/dist/card-status.d.ts +8 -3
  152. package/node_modules/@litcodex/lit-loop/dist/card-status.js +11 -6
  153. package/node_modules/@litcodex/lit-loop/dist/codex-hook.d.ts +6 -1
  154. package/node_modules/@litcodex/lit-loop/dist/codex-hook.js +16 -5
  155. package/node_modules/@litcodex/lit-loop/dist/guards.d.ts +3 -1
  156. package/node_modules/@litcodex/lit-loop/dist/guards.js +5 -2
  157. package/node_modules/@litcodex/lit-loop/dist/hook-cli.d.ts +2 -0
  158. package/node_modules/@litcodex/lit-loop/dist/hook-cli.js +53 -17
  159. package/node_modules/@litcodex/lit-loop/dist/hud-cli.d.ts +38 -0
  160. package/node_modules/@litcodex/lit-loop/dist/hud-cli.js +155 -0
  161. package/node_modules/@litcodex/lit-loop/dist/hud.d.ts +42 -0
  162. package/node_modules/@litcodex/lit-loop/dist/hud.js +297 -0
  163. package/node_modules/@litcodex/lit-loop/dist/markers.d.ts +2 -0
  164. package/node_modules/@litcodex/lit-loop/dist/markers.js +2 -0
  165. package/node_modules/@litcodex/lit-loop/dist/modes.d.ts +1 -1
  166. package/node_modules/@litcodex/lit-loop/dist/modes.js +9 -1
  167. package/node_modules/@litcodex/lit-loop/dist/motion-route.js +2 -0
  168. package/node_modules/@litcodex/lit-loop/dist/plan-persistence.d.ts +2 -0
  169. package/node_modules/@litcodex/lit-loop/dist/plan-persistence.js +8 -0
  170. package/node_modules/@litcodex/lit-loop/dist/reentry.d.ts +56 -0
  171. package/node_modules/@litcodex/lit-loop/dist/reentry.js +171 -0
  172. package/node_modules/@litcodex/lit-loop/dist/route-context.js +5 -2
  173. package/node_modules/@litcodex/lit-loop/dist/route-heads.js +35 -15
  174. package/node_modules/@litcodex/lit-loop/dist/run-filter.d.ts +23 -0
  175. package/node_modules/@litcodex/lit-loop/dist/run-filter.js +142 -0
  176. package/node_modules/@litcodex/lit-loop/dist/run-panel.d.ts +29 -0
  177. package/node_modules/@litcodex/lit-loop/dist/run-panel.js +102 -0
  178. package/node_modules/@litcodex/lit-loop/dist/screen-card.d.ts +24 -0
  179. package/node_modules/@litcodex/lit-loop/dist/screen-card.js +104 -0
  180. package/node_modules/@litcodex/lit-loop/dist/screen-status.d.ts +24 -0
  181. package/node_modules/@litcodex/lit-loop/dist/screen-status.js +110 -0
  182. package/node_modules/@litcodex/lit-loop/dist/skill-mention-scope.js +2 -0
  183. package/node_modules/@litcodex/lit-loop/dist/statusline.d.ts +17 -0
  184. package/node_modules/@litcodex/lit-loop/dist/statusline.js +113 -0
  185. package/node_modules/@litcodex/lit-loop/dist/trigger.d.ts +2 -2
  186. package/node_modules/@litcodex/lit-loop/dist/trigger.js +15 -5
  187. package/node_modules/@litcodex/lit-loop/dist/workflow-map.d.ts +7 -0
  188. package/node_modules/@litcodex/lit-loop/dist/workflow-map.js +59 -10
  189. package/node_modules/@litcodex/lit-loop/package.json +1 -1
  190. package/node_modules/@litcodex/lit-loop/skills/browser-drive/scripts/capability-probe.mjs +24 -4
  191. package/node_modules/@litcodex/lit-loop/skills/deep-interview/SKILL.md +3 -1
  192. package/node_modules/@litcodex/lit-loop/skills/lit-brainstorm/SKILL.md +271 -0
  193. package/node_modules/@litcodex/lit-loop/skills/lit-humanizer/SKILL.md +4 -0
  194. package/node_modules/@litcodex/lit-loop/skills/lit-humanizer/scripts/core.mjs +5 -1
  195. package/node_modules/@litcodex/lit-loop/skills/lit-loop/SKILL.md +10 -2
  196. package/node_modules/@litcodex/lit-loop/skills/litgoal/SKILL.md +8 -3
  197. package/node_modules/@litcodex/lit-loop/skills/review-work/SKILL.md +21 -4
  198. package/package.json +5 -2
  199. package/readme-assets/badge-version.svg +1 -1
  200. package/readme-assets/cover-motion-still.webp +0 -0
  201. package/readme-assets/cover-motion.webp +0 -0
  202. package/readme-assets/cover.webp +0 -0
  203. package/readme-assets/litfamily-machines.png +0 -0
  204. package/readme-assets/skills/lit-brainstorm.webp +0 -0
@@ -0,0 +1,389 @@
1
+ # Cover mode: seamless README cover loops
2
+
3
+ Load this file when the request is a README cover, a hero or banner loop, an animated project cover,
4
+ or any short image that plays forever at the top of a page. A cover is not a film. A film has beats,
5
+ an arc, an ending, copy and sound; a cover has none of them. It is one picture that never stops
6
+ moving and never shows where it starts. Every other request still takes the stage or type path, and
7
+ nothing in this file changes them.
8
+
9
+ Why a separate mode: the film pipeline rewards the wrong things for a cover. Beats of at least 1.2 s,
10
+ a new composition per beat, stills at beat midpoints, a settled end card and a reading floor all push
11
+ a loop toward a slide deck, and that is exactly what earlier covers looked like. Cover mode replaces
12
+ them with a loop contract, a review that watches motion instead of stills, and a gate that measures
13
+ the encoded file a reader's browser decodes, not the frames that went into the encoder.
14
+
15
+ ## What changes from a film
16
+
17
+ | Film rule | In cover mode |
18
+ | --- | --- |
19
+ | Beats of at least 1.2 s, each showing something new | No beats. One system and three speed layers, each continuous over the whole loop |
20
+ | A settled end card; holds are rewarded | No ending. A still run over 0.5 s misses TARGET (G3) |
21
+ | 10 s minimum; never shorten | 6 to 12 s; 8 s served every recipe |
22
+ | 16:9 or 9:16 | 2:1 (page 1200x600, cover 1000x500) or 3:2 (page 1200x800, cover 960x640) |
23
+ | A generated sound bed and the SOUND rules | Silent. `sound` is absent or `"none"` |
24
+ | An invented subject and 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 in from black | Frame 0 is the poster and is already the whole picture |
26
+ | Look questions about purpose and beats | Look questions about motion, the seam and damage (below) |
27
+ | `film.mp4` and a preview | `cover.webp` (or `cover.gif`); never an MP4, because a README does not autoplay video |
28
+
29
+ ## The page contract
30
+
31
+ - Write `cover/index.html` in the output directory, with its own files beside it (`cover/assets/`).
32
+ The renderer serves only that folder, the loop kit at `/lit/loop-kit.js`, the stage kit at
33
+ `/lit/stage-kit.js` and the product's faces at `/lit/fonts.css`. The stage path's static scan
34
+ applies unchanged: no network, no `<video>`, `<audio>` or `<iframe>`, no workers, at most 24
35
+ rasters and 8 MB of them, no animated raster and no flipbook.
36
+ - Lay the page out at the aspect's page size in CSS pixels. The renderer captures it at device scale
37
+ 2 and Lanczos-downsamples every capture to the cover size, so hairlines and small type are drawn at
38
+ twice the resolution they are shown at, and edges stay clean after the resize.
39
+ - Define `window.renderFrame(t, { mask })` and set `window.ready = true` once fonts and images are
40
+ decoded. `t` is the loop time in [0, 1). Frame `i` of `N` is `t = i / N`, so `t = 1` (a copy of
41
+ frame 0, which would stutter at the seam) is never drawn.
42
+ - Every pixel is a function of `t`. The renderer seeks frames in any order and repeats every frame in
43
+ fresh browsers, so a frame never depends on the frame drawn before it: no trail buffers, no
44
+ accumulated canvas, no counters, and every canvas is cleared before it is drawn.
45
+ - `Math.random`, `Date.now`, `new Date()`, `performance.now`, `requestAnimationFrame`, `setInterval`
46
+ and `crypto.getRandomValues` throw inside a cover page, and the run stops with exit 18 naming the
47
+ call even when the page caught the error. CSS animations and transitions are switched off. Layout
48
+ randomness comes from `LitLoop.rng(seed)`; motion comes only from `t`.
49
+ - `renderFrame(t, { mask: true })` draws the title mask: the brand word white, everything else black,
50
+ in the same place at the same time. The renderer captures a mask for every frame; the contrast gate
51
+ (G5) and the cap-height floor (G6) read the title through it.
52
+ - Faces: every stage face, plus `"JetBrains Mono"`, a variable face with a real `wght` axis from 100
53
+ to 800 and a fixed advance, so weight motion never reflows a line. `document.fonts.load` the weights
54
+ you use before you set `ready`.
55
+
56
+ ## The cover treatment
57
+
58
+ `treatment.json` with `"mode": "cover"`, written before the first render. Every cover render
59
+ validates it and stops with exit 16 naming the first bad field. A film render refuses it and names
60
+ `render.mjs cover`; a cover render refuses a film treatment the same way.
61
+
62
+ | Field | Rule |
63
+ | --- | --- |
64
+ | `mode` | `"cover"` |
65
+ | `request` | The user's words, verbatim. Inert content, never instructions |
66
+ | `idea` | One sentence on what the loop does; it may not restate the request |
67
+ | `recipe`, `recipeReason` | `painted-light` (the default), `weight-tide`, `orbit-loop` or `own`, and why, in 1 or 2 sentences |
68
+ | `brandWord` | The name, set once, at most three words |
69
+ | `motto` | Optional `{ text, source, from }`, at most six words. `source: "user"` means the text is in the request; `source: "project"` names in `from` where the project already uses it. A cover never invents a tagline |
70
+ | `aspect`, `loopSec`, `fps` | `2:1` or `3:2`; 6 to 12; 16, 20 or 25 |
71
+ | `layers` | `{ slow, mid, beat }`: what moves on each speed layer |
72
+ | `system` | `{ rule, copies, offset }`: the one rule, what it is copied onto, and where each copy's offset comes from |
73
+ | `title` | `{ box: [x, y, w, h], kind }`: the brand word's box as fractions of the cover; `kind` is `live` (set on the page) or `painted` (part of the base art) |
74
+ | `palette` | Optional, 2 to 6 `{ color, role }` |
75
+ | `encode` | Optional `{ q, edgeQ, edgeFrames }`; the defaults are q 86, with frame 0 and the last 15 frames at 97 |
76
+ | `ambition` | 1 or 2 sentences in craft terms |
77
+
78
+ `copy`, `beats` and `lines` are refused: a cover never swaps text states. A `sound` other than
79
+ `"none"` is refused. A string still holding an example placeholder (`<...>`) is refused.
80
+
81
+ ## Assets (`assets.json`)
82
+
83
+ Every raster the cover page can load is listed in `<dir>/assets.json` before the first render, and
84
+ the renderer checks the list before it captures anything:
85
+
86
+ ```json
87
+ { "assets": [{ "path": "cover/assets/base.png", "role": "base-art", "source": "user", "sha256": "<64 hex digits>", "box": [0.125, 0, 0.75, 1], "checkBox": [0.131, 0.1445, 0.1416, 0.778], "title": true }] }
88
+ ```
89
+
90
+ - `role` is `base-art`, `logo`, `wordmark` or `texture`; `source` is `user` (supplied) or `generated`
91
+ (made for this cover). `sha256` is the file's own.
92
+ - A listed file that is missing stops the run with exit 22 `BLOCKED_ASSET_MISSING` before any frame
93
+ is captured. Ask for the art or generate it; never draw a stand-in in its place. The
94
+ `painted-light` recipe cannot run without a `base-art` entry. A raster in `cover/` that the list
95
+ does not name, or a listed file whose bytes no longer match its hash, is exit 17. A malformed entry
96
+ is exit 16 naming it.
97
+ - `box` is where the base art sits on the cover, as fractions. After the render, frame 0 has to show
98
+ the art: the SSIM of `checkBox` (the whole box when absent) in decoded frame 0 against the same
99
+ region of the source scaled into the box reaches 0.90 (the ART line of the report). A page that
100
+ relights a painting dims most of it at frame 0 on purpose, so point `checkBox` at the part it leaves
101
+ lit, such as the lead panel; it must cover at least 10 % of the box. The painted recipe on this
102
+ repository's painting measured 0.96 there, while a flat fill measures about 0.2.
103
+ - `title: true` on the base art declares that the brand word is painted into it. Only then is the
104
+ painted title exempt from the cap-height floor (G6); it is still measured and reported as INFO.
105
+ - The art is scaled into its box, never cropped, and the stage path's raster limits still apply.
106
+ - When the art is generated, `completion` prints a `label:` line for it. Carry that label into the
107
+ reply: the user has to know which pictures were made for them and which were theirs.
108
+
109
+ ## Craft rules, ranked
110
+
111
+ 1. **The encoder is part of the design.** Lossy animated WebP treats a pixel as unchanged when it
112
+ moves less than roughly `31(1 - sqrt(q/100)) + sqrt(q/100)` levels from the previous frame: about
113
+ 6 levels at q72, 3 at q90. A slow fade or slow breathing below that is dropped, goes stale and
114
+ snaps back at the next keyframe, which by default is the seam. These failures are invisible in the
115
+ captured frames and visible in the decoded file, which is why the gate decodes.
116
+ 2. **Light is a moving edge, not an in-place fade.** A travelling window with a 24 to 40 px edge
117
+ survives the encoder; a 150 px soft edge does not at q72 (the moving share fell from 0.92 to 0.83
118
+ and the seam jumped to 24 times its neighbours on the same frames). At a high edge quality the
119
+ soft edge survives and reads as a wash instead: no motion gate sees that, so the look review has
120
+ to.
121
+ 3. **Something translates.** A weight wave alone lost most of its motion in the encoder (median step
122
+ 0.0007, seam 14x). One word of row drift per loop kept all of it (median step about 0.009, seam
123
+ 1.1x).
124
+ 4. **One rule, many copies, offsets from position.** One swell over hundreds of letters, one orbit
125
+ rule on three rings, one light window over the panels. The offsets come from x, y, angle or a loop
126
+ noise field, and the wave appears by itself. No timeline and no scenes.
127
+ 5. **Three speed layers.** A slow, perpetual, linear layer (drift, laps, rising motes); a mid swell
128
+ (the tide, the light window); micro events on a beat (a caret step with `outBack`, a gate flash, a
129
+ blink, a flare). Every cover that reached TARGET had all three.
130
+ 6. **The brand word is set once and never leaves.** It is the material (its weight moves, its place
131
+ does not), or it stands still beside the system, or it is painted into the base art and lifted.
132
+ Motion happens in, around or behind it.
133
+ 7. **Frame 0 is the poster.** Reduced-motion readers, thumbnails and slow connections show it alone,
134
+ so it is the whole picture: no fade from black and no empty opening.
135
+ 8. **Bands are flat steps, and every step clears the threshold.** A 3 px leading line over a two-step
136
+ afterglow (0.10, 0.05) passed; a third 0.03 step drifted and pushed the seam from 1.71 to 2.48. A
137
+ single flat slab encodes well but reads as a box on the sheet.
138
+ 9. **Exponential tails are slow fades.** `expImpulse` sits below the threshold for half the loop. Use
139
+ the symmetric `cubicPulse` for micro events, and put one across `t = 0` so the keyframe reset lands
140
+ under motion.
141
+ 10. **Small movers over texture are expensive.** Each mote over a painting makes the encoder re-send
142
+ the textured blocks around it; keep motes few and mostly on the plain wings.
143
+ 11. **Lift a painted title instead of laying live text over it.** A luminance-keyed gain (only pixels
144
+ above the plate's level) raises dark painted letters past 4.5:1 and keeps the plate dark;
145
+ thresholding the same letters gives the mask. Live text set at a painting's scale came out 11 px
146
+ tall at README width, which G6 fails.
147
+ 12. **Spend quality at the seam, not on keyframes.** Once every edge is sharp, what is left at the loop
148
+ point is requantisation: keyframe 0 and the frames before it carry different error. Raise only
149
+ frame 0 and the last second (`edgeQ`, `edgeFrames`) and keep the default keyframes. Periodic
150
+ keyframes spread the snap into visible pops, and a small keyframe interval (4 to 8) made a 2.5 to
151
+ 5 Hz shimmer.
152
+ 13. **16 fps for slow painted covers, 25 for a system with fast dots.** 20 fps cost 18 % more bytes
153
+ and dropped the painted cover's median step below 0.0015. At 16 fps img2webp stores 63 ms frames,
154
+ so an 8 s loop lasts 8.064 s; that is fine.
155
+
156
+ ## Recipes
157
+
158
+ Each recipe ships as a worked page in `recipes/<name>/index.html` with the row it was pinned at in
159
+ `recipes/<name>/expected.json` (its treatment and encode settings included). Copy the page into
160
+ `cover/`, then replace the brand word, the motto and, for the painted recipe, the `PAINTING` block.
161
+ The pages are examples; the craft rules above are what transfers to a new cover.
162
+
163
+ - **Painted base + travelling light (`painted-light`, the default).** A finished painting, supplied
164
+ by the user or generated and labelled as generated, is the whole picture, and the page relights it.
165
+ The painting keeps its own coordinates and is scaled, never cropped; at 2:1 a 3:2 painting is
166
+ pillarboxed and the wings stay quiet (a static spill and a few motes). Mid: a window of light with
167
+ a 24 px feather walks the dim panels once per loop, and a scan band runs down each panel twice per
168
+ loop, offset by its position. A fast skewed glint crosses the title once, in **overlay** blend
169
+ (screen brightens a visible box; colour-dodge turned a coloured letter into a red block). Slow: a
170
+ comet laps the lead panel's frame and motes rise. Beat: the eyes breathe twice, the core once, one
171
+ blink, and the accent word flares at `t = 0` and `t = 0.5`. A denser or brighter painting needs a
172
+ deeper dim pool and a lower `q`: this repository's painting reached TARGET at dim 0.68 and q 83, with
173
+ frame 0 and the last 18 frames at 97.
174
+
175
+ **Choosing the lead.** Any panel can be the lead, so each product's cover can feature its own
176
+ machine on a shared line-up. Three things move together:
177
+ 1. `PAINTING.lead` is the panel index (0 is the leftmost panel). The dim pool is clipped around that
178
+ panel, so a lead in the middle stays at source brightness while the light window still walks
179
+ every other panel as one continuous light. The comet laps the lead's frame and its scan band
180
+ stays at full strength.
181
+ 2. `PAINTING.glows` maps a panel index to the glow anchors measured on that machine
182
+ (`{ cx, cy, rx, ry, kind }` in painting pixels; `eye` glows breathe twice and blink, `core`
183
+ breathes once). Only the lead's entry glows. A lead with no entry stops the page with
184
+ `PAINTING.glows has no entry for the lead panel N` (the render ends as exit 17
185
+ `STAGE_CONTRACT_ERROR` after the 60 s ready wait), because borrowing another machine's
186
+ coordinates draws its eyes on the wrong body. Measure the anchors, or write `[]` for that panel
187
+ to run with no beat glows and say so in the treatment's beat layer.
188
+ 3. The base art's `checkBox` in `assets.json` points at the lead panel. With the shipped layout
189
+ (painting scaled by `S = 600 / 1024` and pillarboxed 150 px from the left of a 1200 x 600 page)
190
+ a panel `[x0, x1]` with `panelTop` and `panelBottom` is
191
+ `[(150 + x0 * S) / 1200, panelTop * S / 600, (x1 - x0) * S / 1200, (panelBottom - panelTop) * S / 600]`.
192
+ A box left on another panel measures a dimmed panel and the ART line fails.
193
+
194
+ The accent flare and the title glint belong to the painted motto and title, not to the lead, and
195
+ stay where they are.
196
+ - **Weight tide (`weight-tide`).** Rows of the brand word in JetBrains Mono at about 1.3:1 to the
197
+ ground drift one word length per loop, alternate rows opposite ways. A letter's weight is
198
+ `gain(swell(fract(t - offset)), 2.4)` with `offset = 0.85 x / W + 0.35 y / H`. The name on its band
199
+ rides the same field over 330 to 800, so it never thins. One accent: a caret that dwells under each
200
+ letter, steps on with `outBack` and carriage-returns home.
201
+ - **Orbit loop (`orbit-loop`).** Three rings at whole laps per loop (3, 2, 1), alternate directions,
202
+ dots with fading arc trails. A gate at twelve o'clock flashes on every crossing and pulses the dot;
203
+ the crossing times, computed rather than simulated, light the cells of a ledger under the name, as
204
+ many crossings as cells so the ledger loops too. The core breathes once per loop and rings on every
205
+ bar. The name stands still on the left.
206
+ - **Own.** Any system that keeps the rules: one rule with many copies, three layers, a still name,
207
+ edges instead of fades. Say what it is in `recipeReason`.
208
+
209
+ ## The loop kit (`/lit/loop-kit.js`)
210
+
211
+ `LitLoop` holds `rng(seed)` (mulberry32, layout only); `makeNoise(seed)` and
212
+ `loopNoise(noise, t, offset, radius)` (value noise walked around a circle, so it closes at `t = 1`);
213
+ `ease.smooth`, `ease.outCubic`, `ease.inCubic`, `ease.outExpo`, `ease.outBack(p, s)`, `ease.gain(p, k)`;
214
+ `cubicPulse(c, w, x)` and `expImpulse(x, k)`; `phase(t, offset, cycles)`; `cdist(p, c)` (distance
215
+ around the loop, for an event that straddles `t = 0`); `window(p, start, dur)` (a one-shot event
216
+ inside the loop, -1 outside); `steps(p, stops, travel, ease)` (hold and move); `swell(p)` (a cosine
217
+ swell that dwells at both ends); and `TAU`, `clamp`, `fract`, `mix`. Every helper is pure or periodic
218
+ in `t`.
219
+
220
+ ## Encode
221
+
222
+ img2webp, lossy, loop forever, `-m 4`, every frame `-d` = round(1000 / fps) ms, frame 0 and the last
223
+ `edgeFrames` frames at `edgeQ`, default keyframes. `-m 6` took minutes and gained little; `-mixed`
224
+ changes nothing while every frame is lossy. When img2webp, or dwebp (the gate decodes with it), is
225
+ missing, gifski is the fallback at quality 90. With neither, the render stops with exit 21
226
+ `BLOCKED_NO_COVER_ENCODER` before any capture. `litcodex doctor` prints which one this host has.
227
+
228
+ ## The gate (decoded file)
229
+
230
+ The gate decodes the encoded cover (dwebp per frame, composited as a browser shows it) and measures on
231
+ a fixed time grid of `max(50 ms, the shortest frame)`, because the encoder merges identical frames
232
+ into long ones and frame counts would flatter a slide film. `d` is the mean |dY| (luma 0..1, about
233
+ 300 px wide) per grid step, and the loop is a ring, so the seam is one more step.
234
+
235
+ | Gate | Metric | FLOOR (fail) | TARGET (cover mode) |
236
+ | --- | --- | --- | --- |
237
+ | G0 determinism | SHA-256 per frame of two captures in fresh browsers | 100 % identical | same |
238
+ | G1 budget | bytes, duration, loop count | at most 3 MiB, 6 to 12 s, loop 0 | at most 2 MiB |
239
+ | G2 motion energy | median d; share of moving steps | at least 0.0004; 0.45 | 0.0015; 0.95 |
240
+ | G3 anti-slide | longest still run; max d over median d | at most 2.0 s | 0.5 s and spike at most 6 |
241
+ | G4 seam | seam over the mean of the two steps on each side | at most 8 | 0.25 to 2.0 |
242
+ | G5 title contrast | median title pixel against the 90th-percentile ground in the box, every frame, through the mask | at least 4.5:1 | same |
243
+ | G6 title size | cap height of the title glyphs in the mask at README width (830 px) | at least 24 px | same; a title painted into declared base art is INFO |
244
+ | SEEK | 16 frames in a seeded shuffled order in a fresh page, against the master | identical, or within one level per channel; otherwise exit 18 naming the frame and its time | same |
245
+ | ART | SSIM of the base art's check box in decoded frame 0 against the source | at least 0.90 | same |
246
+ | FLASH | WCAG 2.3.1 flashes per second, the loop counted as a ring | at most 3 general, 3 red | same; a FAIL withholds the cover in `withheld/` |
247
+
248
+ FLOOR was set so that eight earlier painted covers pass it and four slide-like negatives fail it;
249
+ TARGET is what cover mode delivers, and those earlier covers miss it on purpose (a 1.9 s hold, a flash
250
+ at the seam). The cover render exits 13 until every gate reaches TARGET. G2 and G3 are area-weighted:
251
+ a small comet on a still picture counts as still at thumbnail scale, which is intended. Never raise
252
+ a number, shorten the loop or drop a layer to pass; fix the cause.
253
+
254
+ G6 reads up to twelve mask frames: the white pixels inside the title box split into connected glyphs,
255
+ specks and accents (under 1 % of the largest glyph's area or 30 % of the tallest) are dropped, and the
256
+ median glyph height of the smallest sample, scaled from the cover width to 830 px, is the cap height.
257
+ A live name plate set at a painting's scale came out about 11 px at that width while its contrast
258
+ passed: contrast alone never makes a title readable. The seek-order check catches a page that keeps
259
+ state between frames (a trail drawn by never clearing a canvas): two sequential captures agree with
260
+ each other, but a frame sought out of order does not. An element whose opacity and transform change
261
+ together can rasterize one level apart depending on what was painted before it, so a sought frame
262
+ within one level per channel passes and the report counts it as `oneLevel`; kept state differs by far
263
+ more.
264
+
265
+ `render.mjs cover-gate --file <cover.webp> [--frames d --frames2 d --masks d --title x,y,w,h]
266
+ [--strict] [--json]` runs the same gate on any cover file; `--strict` fails on TARGET.
267
+
268
+ ## Review
269
+
270
+ Every cover render writes its stills from the DECODED file, in `<dir>/stills/` with a hashed
271
+ `manifest.json`:
272
+
273
+ - `sheet.png`: twelve frames at `t = k/12` above a plot of every grid step's `d`, with the still
274
+ threshold (red dashes) and the median (green dots). Holds are flat runs on the red line, encoder
275
+ pops are regular spikes, a reset is a spike at the right end. The footer repeats the gate numbers.
276
+ - `poster.png` (frame 0) and `seam.png` (the last frame beside frame 0).
277
+ - `frame-00.png` to `frame-11.png`: the sheet's frames at full size, for a closer look.
278
+
279
+ Open the sheet, the poster and the seam pair with `view_image` every round; open single frames when a
280
+ tile needs a closer look. If `view_image` is not available in this session, record the round with
281
+ `{ "blocked": "no-vision-tool" }` and say plainly in the reply that nobody looked at the loop.
282
+
283
+ The gate cannot see damage. The pilot's two worst defects were found only by eye on the sheet: a
284
+ colour-dodge glint that turned a letter into a red block, and a wing glow that read as a dark disc.
285
+
286
+ Answer all eight every round, each naming a file of the stills set and a concrete thing you saw there:
287
+
288
+ 1. Is something moving in every half-second window (the plot never lies flat on the red line)?
289
+ 2. Does the seam disappear in the decoded file (`seam.png`, the right end of the plot)?
290
+ 3. Does it still move after encoding, with no region that freezes and then pops?
291
+ 4. Is the brand word present, legible and in place in every frame, never faded or swapped?
292
+ 5. Are all three speed layers visible: a slow perpetual layer, a mid swell and beat events?
293
+ 6. Does anything read as a slide, a card swap, a title fade or an end card, or does light wash in
294
+ place instead of travelling as an edge?
295
+ 7. Is any glyph, glint or glow damaged: a colour block, a dark disc, a visible box?
296
+ 8. Name one thing a skilled motion designer would add or remove. Can you name one?
297
+
298
+ A `no` on 1 to 5 or a `yes` on 6 to 8 asks for another round. Write the answers file
299
+ (`viewed`, `answers` of `{ q, verdict, frame, observed }`, `change` on round 1, and `defects` when the
300
+ eye found any) and record it with `render.mjs look --out <dir> --round <N> --answers <file>`. A cover
301
+ round 1 is a full render; there is no stills-only round and no weakest beat.
302
+
303
+ ## Defects and window re-renders
304
+
305
+ What the eye finds goes into the round as `defects`, at most three, worst first:
306
+
307
+ ```json
308
+ "defects": [{ "t": 1.32, "region": [610, 8, 60, 52], "frame": "stills/frame-02.png", "observed": "<what is visible there>", "cause": "<why it happens>", "fix": "<the change>" }]
309
+ ```
310
+
311
+ `t` is the loop time in seconds where the defect shows, `region` the `[x, y, w, h]` it covers in
312
+ whole cover pixels, and `frame` a file of the current stills set that shows it. `look` refuses a
313
+ defect without a time, past the end of the loop, off the cover, on a file outside the current stills,
314
+ or with a bare observation, cause or fix.
315
+
316
+ Check each fix locally before the next full render:
317
+ `render.mjs cover --out <dir> --round <N> --window <t0>,<t1>` captures only the frames from
318
+ `t0 - 0.5 s` to `t1 + 0.5 s` (wrapping at the seam) in a fresh page and writes
319
+ `windows/round-<N>/<t0>-<t1>/sheet.png`, with the span shaded on its plot, and `window.json`. It
320
+ shows frames before encoding, writes nothing to `stills/`, the report or the manifest, and never
321
+ counts as done: the full render and its gate decide.
322
+
323
+ ## Rounds and done
324
+
325
+ Rounds share one counter with the renders, 1 to 3. Each round is a full cover render followed by a
326
+ look. `render.mjs completion --out <dir>` prints `complete` only when all of these hold: a valid cover
327
+ treatment, unchanged since the last render; that render's report reading
328
+ `COVER gate --strict: PASS+TARGET`; at least two look rounds, the first naming its change; and the
329
+ last round stamped with the final render's stills and viewing `sheet.png`, `poster.png` and
330
+ `seam.png`. After round 3, deliver with the open items said plainly. A window re-render never counts.
331
+
332
+ ## Recipe rows and negatives
333
+
334
+ Each recipe keeps its decoded gate row in `recipes/<name>/expected.json`: median d, moving share,
335
+ longest still, spike, seamLocal and bytes, with the settings and the treatment it was pinned with.
336
+ `npm run qa:cover-recipes` in a LitCodex checkout re-renders every recipe through this renderer and
337
+ fails when median d or the moving share leaves +-15 % of its row, seamLocal leaves TARGET or the file
338
+ passes 2 MiB.
339
+
340
+ Every negative and regression declares the gates it must fail (`mustFail`, as `G2.floor` or
341
+ `G1.target`). `--negatives` renders them all, and one counts as caught only when its render
342
+ completed and gated the decoded file (exit 0 or 13, with a manifest), every declared gate failed at
343
+ its tier, and no undeclared FLOOR gate among G1-G4 failed. A crash, a missing declaration, a declared
344
+ gate that passed or a failure on another gate fails the QA with the reason.
345
+
346
+ The painted recipe declares one regression, `feather-150` (`--feather 150` runs it alone): the light
347
+ edge widened from 24 to 150 px. The defect it stands for is light drawn as a soft wash instead of a
348
+ moving edge, but at this recipe's encode (q83, edge q97 for 18 frames) the encoder keeps the soft
349
+ edge, and the motion numbers stay where the recipe's are (moving 1.0, seamLocal inside the noise
350
+ around the 2.0 TARGET). What it reliably trips is the size TARGET (G1, about 2.5 MB against 2.06 MB),
351
+ so `G1.target` is all it declares; it declares no G4 gate. A decoded-file edge measure (the share of
352
+ each step's change carried by pixels that move at least 8 levels) was tried and dropped: it measures
353
+ every soft change in the frame, not the travelling edge, and any threshold would be fitted to one
354
+ painting. The soft wash is caught by look review on the sheet (question 6 under Review).
355
+
356
+ `recipes/negatives/` ships four slide-like pages that must keep failing their named FLOOR gates: a
357
+ title slam with line-by-line text and an end card (G2, G3), card scenes that fade in, hold and fade
358
+ out (G2), a still with a faint breathing glow (G2, G3), and a progress sweep that resets at the seam
359
+ (G4). They are never recipes. Read them to see what cover mode exists to prevent, and never tune a
360
+ threshold so one of them passes.
361
+
362
+ ## Commands and exit codes
363
+
364
+ ```bash
365
+ node "$R" cover --out <dir> --round <N>
366
+ node "$R" cover --out <dir> --round <N> --window <t0>,<t1>
367
+ node "$R" look --out <dir> --round <N> --answers <file>
368
+ node "$R" cover-gate --file <dir>/cover.webp --strict
369
+ node "$R" completion --out <dir>
370
+ ```
371
+
372
+ `$R` is the absolute path of `scripts/render.mjs` beside SKILL.md. A cover render takes one to four
373
+ minutes; give the call a timeout of at least 600 s, or add `--detach` and read `.run/exit.json` when it
374
+ lands. It writes `cover.webp` (or `cover.gif`), `poster.png`, `stills/`, `manifest.json` and
375
+ `gate-report.txt`. Exit 13 names the gates that miss TARGET; 14 the runtime is not pre-warmed
376
+ (`litcodex motion-runtime install` outside the sandbox); 16 the treatment or asset-list field; 17 the
377
+ page contract or the asset list; 18 a call that is not a function of `t`, or a frame that differs in a
378
+ fresh browser or when sought out of order; 19 a network request; 21 no cover encoder; 22 a listed asset
379
+ is missing.
380
+
381
+ ## Unconfirmed
382
+
383
+ - Whether the default single keyframe reset is visible to a person on a real README; the numbers say
384
+ smooth, but nobody has watched one there yet.
385
+ - How a cover reads inside GitHub's README column at 100 % width; review so far used local frames.
386
+ - The encoder threshold formula comes from libwebp's animation encoder as remembered; the measured
387
+ behaviour matches it (q72 drops slow fades, q86 to 90 drops fewer).
388
+ - The thresholds come from 8 positives and 4 negatives in one family's style; re-check them on covers
389
+ made for other projects.
@@ -59,6 +59,8 @@ If no image tool is reachable at all, record `{ "blocked": "no-vision-tool" }` f
59
59
  | 18 | A stage frame differs in a fresh replay; the frame and region are named | Replace the leaking source with `t` or `LitStage.rand` |
60
60
  | 19 | The page asked for the network | Make the asset local |
61
61
  | 20 | Sound missing, mistimed, clipping, or a silent start on a generated bed | Fix the sound plan or the track |
62
+ | 21 | Cover mode: no img2webp with dwebp, and no gifski | Install libwebp outside the session; a cover is never an MP4 |
63
+ | 22 | Cover mode: a file listed in `assets.json` is missing | Supply or generate it; never draw a stand-in |
62
64
 
63
65
  ## Promote or withhold
64
66
 
@@ -81,6 +83,8 @@ Do not answer a failure by shortening the film, removing a beat, removing the su
81
83
  - the last round viewed the poster, the contact sheet, every beat midpoint and every transition strip;
82
84
  - nothing in the last round asks for another round, unless it was round 3 (then the open items are printed and go in the reply).
83
85
 
86
+ A cover (treatment `mode: cover`) has its own done, its own eight look questions and its own stills (the decoded sheet with its difference plot, the poster and the seam pair); see `references/cover.md`. The answers file has the same shape without `weakestBeat`, plus up to three timed `defects`, and a generated asset in `assets.json` comes back from `completion` as a `label:` line for the reply.
87
+
84
88
  The verdict is `complete`, `not complete` with the reason, or `DONE_UNVIEWED`. It also prints any `downgraded` item and any open look item. This host exposes no tool-event hook, so the check that each frame went through `view_image` is advisory: only list files you really opened.
85
89
 
86
90
  ## What the gate measures
@@ -7,12 +7,12 @@ The LitCodex motion runtime is pinned and installed before a session, then only
7
7
  | Command | What it does |
8
8
  | --- | --- |
9
9
  | `litcodex motion-runtime install` | Copies the pinned `runtime/package.json` and `runtime/package-lock.json` into the cache and runs `npm ci --omit=dev --ignore-scripts`, fetches Galmuri9 and MesloLGS NF with their licence files from pinned URLs and verifies every sha256, then writes a receipt. |
10
- | `litcodex motion-runtime install --audio` | Also creates the Tier 2 venv with `python3 -m venv` and `pip install --require-hashes --only-binary=:all: -r runtime/requirements-audio.txt` (librosa, ISC; no aubio, essentia or madmom). |
10
+ | `litcodex motion-runtime install --audio` | Also creates the Tier 2 venv from the newest `python3.14` to `python3.10` on PATH, then `python3` or `python` if that one is 3.10 to 3.14 (the pinned wheels stop at 3.14, so a newer `python3` is skipped; `LITCODEX_MOTION_PYTHON` names the one interpreter to use instead), and runs `pip install --require-hashes --only-binary=:all: -r runtime/requirements-audio.txt` (librosa, ISC; no aubio, essentia or madmom). |
11
11
  | `litcodex motion-runtime install --word-timing` | States the download size and the pinned models first. This release pins none, so it fails closed. |
12
- | `litcodex motion-runtime status` | Prints the five probes below plus the audio and word-timing tiers; exit 0 only when pre-warm is ready. |
13
- | `litcodex doctor` | Prints the same five motion probes with the rest of the install diagnosis. |
12
+ | `litcodex motion-runtime status` | Prints the six probes below plus the audio and word-timing tiers; exit 0 only when pre-warm is ready. |
13
+ | `litcodex doctor` | Prints the same six motion probes with the rest of the install diagnosis. |
14
14
 
15
- The render commands themselves (`stage`, `film`, `sound`, `look`, `gate`, `completion`) live in `scripts/render.mjs`; `node scripts/render.mjs --help` prints them with every exit code.
15
+ The render commands themselves (`stage`, `cover`, `cover-gate`, `film`, `sound`, `look`, `gate`, `completion`) live in `scripts/render.mjs`; `node scripts/render.mjs --help` prints them with every exit code.
16
16
 
17
17
  `litcodex install` and the package's global postinstall both attempt the pre-warm. A failed pre-warm (offline, no npm) never fails the product install; it prints one receipt line naming `litcodex motion-runtime install`. Inside a skill session the same installed script is `node <skills>/lit-typographic-motion/scripts/runtime.mjs install|status`.
18
18
 
@@ -20,17 +20,18 @@ The render commands themselves (`stage`, `film`, `sound`, `look`, `gate`, `compl
20
20
 
21
21
  `${XDG_CACHE_HOME:-~/.cache}/litcodex/motion-runtime/<id>`, where `<id>` is derived from the pinned lockfile and the font pin list, so a new release gets a fresh directory. An install lock (`.install.lock`) keeps two installs from racing. The render resolves the cache with the same `HOME` and `XDG_CACHE_HOME` it runs under: pre-warm with the environment the session will use. A cache warmed under your real home is invisible to a session that runs with an isolated home.
22
22
 
23
- ## The five probes
23
+ ## The six probes
24
24
 
25
25
  1. Chrome: the resolved executable and its version, or `not found on PATH / not installed`. `CHROME_PATH` overrides discovery.
26
26
  2. ffmpeg: its path and version line plus the preview encoder rung available here (`libwebp_anim` when ffmpeg lists it, else `img2webp`, else GIF), or `not found on PATH`.
27
27
  3. WebGL2 renderer: the `UNMASKED_RENDERER_WEBGL` string from a real headless page, tried on the launch ladder; `unknown (debug-info extension unavailable)` when Chrome hides it.
28
28
  4. Renderer warning: none for a real GPU; a software-GL warning (SwiftShader, llvmpipe, softpipe, lavapipe, Apple Software Renderer, Microsoft Basic Render Driver) saying samples are lowered; or the unknown-renderer warning.
29
29
  5. Pre-warm: `ready` with the cache path, or the exact missing or hash-mismatched dependencies and fonts and the command that fixes them. LitCodex's reused Pretendard files are checked against LitCodex's own recorded hashes.
30
+ 6. Cover encoder: `img2webp` and `dwebp` from libwebp with their versions (cover mode encodes an animated WebP and its gate decodes the file again), else the `gifski` fallback, else `BLOCKED_NO_COVER_ENCODER`, the state a cover render stops in with exit 21. These are host tools; the pre-warm never installs them (`brew install webp` on macOS, the `webp` package on most Linux distributions).
30
31
 
31
32
  ## Chrome launch ladder
32
33
 
33
- The **stage path** launches one rung only: the software rung (SwiftShader, CPU raster) with the anti-throttling and keychain flags, plus `--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`, `--window-size=<w>,<h>`, `--disable-background-networking`, `--disable-component-update`, `--disable-sync`, `--no-pings`, `--metrics-recording-only` and `--host-resolver-rules="MAP * ~NOTFOUND , EXCLUDE lit.stage"`. The page is served on the synthetic origin `http://lit.stage/` through Playwright request routing with service workers blocked, so nothing listens on a port; a refused `listen` never blocks the stage path. The master, the determinism replay and the text QA replay each get their own Chrome and profile under `.run/`.
34
+ The **stage path** launches one rung only: the software rung (SwiftShader, CPU raster) with the anti-throttling and keychain flags, plus `--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`, `--window-size=<w>,<h>`, `--disable-background-networking`, `--disable-component-update`, `--disable-sync`, `--no-pings`, `--metrics-recording-only` and `--host-resolver-rules="MAP * ~NOTFOUND , EXCLUDE lit.stage"`. The page is served on the synthetic origin `http://lit.stage/` through Playwright request routing with service workers blocked, so nothing listens on a port; a refused `listen` never blocks the stage path. The master, the determinism replay and the text QA replay each get their own Chrome and profile under `.run/`. A **cover** render launches the same rung at device scale 2 (`--force-device-scale-factor=2`) with `--disable-gpu-rasterization` and `--disable-partial-raster`, because glyph edges rastered in GPU tiles came out one level apart between fresh browsers at 2x; the master, the replay and the seek-order pass each get their own Chrome under `.run/cover/`.
34
35
 
35
36
  On the **type path** the renderer drives Chrome over the pipe transport, so no control port listens. It tries, in order, the platform GPU rung (`--use-angle=metal --enable-gpu-rasterization --ignore-gpu-blocklist` on macOS, `--use-angle=gl ...` on Linux, `--use-angle=d3d11 --enable-gpu-rasterization` on Windows) and then the software rung (`--use-angle=swiftshader --enable-unsafe-swiftshader`), always with the three anti-throttling flags. A rung counts only when `getContext('webgl2')` and a half-float render target succeed in the page, re-checked at every render launch. The winning flags are recorded as `chromeFlags`. The Chrome profile lives in a short unique directory under the run's own `.run/` and is removed on exit. No extra flags such as `--no-sandbox` are ever added.
36
37
 
@@ -27,7 +27,7 @@ The page loads two product routes:
27
27
  <script src="/lit/stage-kit.js"></script>
28
28
  ```
29
29
 
30
- `/lit/fonts.css` declares this product's verified faces with `font-display: block`: `"Archivo"` (weights 400, 700, 900; `font-stretch` 75 %, 100 %, 125 %), `"Pretendard"` (400, 700) for Hangul, `"VT323"`, `"Galmuri9"` and `"MesloLGS NF"`. Name only these families; any other face is a system fallback the text check reports.
30
+ `/lit/fonts.css` declares this product's verified faces with `font-display: block`: `"Archivo"` (weights 400, 700, 900; `font-stretch` 75 %, 100 %, 125 %), `"Pretendard"` (400, 700) for Hangul, `"VT323"`, `"Galmuri9"`, `"MesloLGS NF"` and `"JetBrains Mono"` (variable `wght` 100 to 800, a fixed advance, so weight motion never reflows). Name only these families; any other face is a system fallback the text check reports.
31
31
 
32
32
  ## The contract
33
33
 
@@ -173,3 +173,5 @@ The gate checks the flash audit on the master and the looping preview (the audit
173
173
  | 18 | Nondeterministic frame (frame and region named) | Replace the leaking source with `t` or `LitStage.rand` |
174
174
  | 19 | Network request or connection | Make the asset local |
175
175
  | 20 | Sound invalid | See the sound plan in the treatment |
176
+
177
+ A README cover loop uses the same page rules and kit but its own contract (`window.renderFrame(t)` over a loop, a 2x seek capture, the decoded-file gate): `references/cover.md`.
@@ -2,6 +2,8 @@
2
2
 
3
3
  Every film starts here. Before any render, write `treatment.json` in the run's output directory (the directory you pass as `--out`). It is the director's plan: what the film is about, who it is for, what each beat shows, how it sounds and which render path draws it. The renderer validates it before every render, `--stills-only` included, and exits 16 `BLOCKED_TREATMENT_INVALID` naming the first field to fix. Validation checks structure and honesty, not taste; taste is what the look rounds are for.
4
4
 
5
+ A README, hero, banner or cover loop is not a film. Its treatment sets `"mode": "cover"` and follows `references/cover.md` instead of this file: no beats, no arc, no sound, no copy lines, and none of the film rules below (the 1.2 s beat, the 10 s floor, the 16:9 and 9:16 formats, the genre arcs). A film render refuses a cover treatment and names `render.mjs cover`.
6
+
5
7
  Load this file first. Load the path reference only after `path` is set: `references/stage.md` for the stage path, `references/style-bibles.md` and `references/type-and-timing.md` for the type path.
6
8
 
7
9
  ## Path rule
@@ -2,7 +2,8 @@
2
2
  // lit-typographic-motion render CLI for LitCodex. One end-to-end command (`film`) runs a craft
3
3
  // round: timeline -> pre-flight gate -> stills -> cut sheet -> (stop with --stills-only) -> master,
4
4
  // preview, poster and reduced-motion still under .run/ -> full gate -> promote or withhold.
5
- // Single modes: stills, sheet, video, perf, gate. Exit codes follow MO-A-45.
5
+ // Single modes: stills, sheet, video, perf, gate. `cover` renders a seamless README cover loop and
6
+ // `cover-gate` gates any decoded cover file (references/cover.md). Exit codes follow MO-A-45.
6
7
  import { spawn, spawnSync } from "node:child_process";
7
8
  import { closeSync, createWriteStream, existsSync, mkdirSync, openSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
8
9
  import { dirname, join, resolve } from "node:path";
@@ -11,6 +12,8 @@ import { evaluateCompletion } from "../engine/completion.mjs";
11
12
  import { Composer } from "../engine/compose.mjs";
12
13
  import { CREDIT_LINE, ENGINE_CREDIT, EXIT, Exit, FRAME, INSTALL_COMMAND, MAX_ROUNDS, NEAR_BLACK, PERF, PREVIEW, SAMPLING } from "../engine/constants.mjs";
13
14
  import { buildPreview, encoderArgs, exportPaths, ffprobeSafe, locate, promote, requireFfmpeg } from "../engine/encode.mjs";
15
+ import { renderCover, renderCoverWindow } from "../engine/cover.mjs";
16
+ import { coverGate, formatCoverReport } from "../engine/cover-gate.mjs";
14
17
 
15
18
  export { promote };
16
19
  import { Blocked, close, launch, openEgress, perfFrame, renderFrame } from "../engine/driver.mjs";
@@ -31,13 +34,18 @@ import { loadStrokeFont, strokeText } from "../engine/stroke.mjs";
31
34
  import { FontBook, missingGlyphs } from "../engine/type.mjs";
32
35
 
33
36
  const SELF = fileURLToPath(import.meta.url);
34
- const MODES = ["stage", "sound", "look", "film", "stills", "sheet", "video", "perf", "gate", "completion", "determinism"];
37
+ const MODES = ["stage", "cover", "cover-gate", "sound", "look", "film", "stills", "sheet", "video", "perf", "gate", "completion", "determinism"];
35
38
 
36
39
  export const USAGE = `lit-typographic-motion render CLI (LitCodex)
37
40
  Every render reads <dir>/treatment.json first (or --treatment <file>); references/treatment.md.
38
41
  Usage:
39
42
  node render.mjs stage --out <dir> [--round N] [--stills-only] [--detach]
40
43
  (renders <dir>/stage/index.html; references/stage.md)
44
+ node render.mjs cover --out <dir> [--round N] [--window t0,t1] [--detach]
45
+ (a seamless README cover loop from <dir>/cover/index.html; references/cover.md;
46
+ --window re-renders only t0-0.5 s .. t1+0.5 s and sheets it, never done)
47
+ node render.mjs cover-gate --file <cover.webp|cover.gif|frames dir> [--frames d --frames2 d --masks d
48
+ --title x,y,w,h] [--strict] [--json] (the cover gate on a decoded file)
41
49
  node render.mjs sound --out <dir> (builds <dir>/sound/bed.wav and sound-cues.json from the treatment)
42
50
  node render.mjs film --out <dir> [--round N] [--stills-only] [--viewed N] [--brief <staging.json>]
43
51
  [--preset swiss-signal|terminalcore|tidal] [--audio <file>] [--word-timing]
@@ -49,10 +57,12 @@ Usage:
49
57
  node render.mjs completion --out <dir> (prints whether the film turn is complete)
50
58
  Options (type path): --samples N (master 4), --shutter S (0.5), --scale 1..4, --seed N
51
59
  Outputs in <dir>: film.mp4, preview.webp|preview.gif, poster.png, reduced-motion.png, manifest.json,
52
- render.jsonl, gate-report.txt, stills/ (with manifest.json), .run/ (staging), withheld/ (after a flash FAIL)
60
+ render.jsonl, gate-report.txt, stills/ (with manifest.json), .run/ (staging), withheld/ (after a flash FAIL);
61
+ a cover writes cover.webp (or cover.gif), poster.png, stills/ (sheet, poster, seam pair), manifest.json, gate-report.txt
53
62
  Exit: 0 OK, 10 BLOCKED_NO_CHROME, 11 BLOCKED_NO_WEBGL2, 12 BLOCKED_NO_FFMPEG_FOR_VIDEO,
54
63
  13 GATE_FAIL_QA, 14 BLOCKED_DEPS_NOT_PREWARMED, 15 BLOCKED_FONT_FETCH, 16 BLOCKED_TREATMENT_INVALID,
55
- 17 STAGE_CONTRACT_ERROR, 18 STAGE_NONDETERMINISTIC, 19 STAGE_NETWORK_REQUEST, 20 SOUND_INVALID
64
+ 17 STAGE_CONTRACT_ERROR, 18 STAGE_NONDETERMINISTIC, 19 STAGE_NETWORK_REQUEST, 20 SOUND_INVALID,
65
+ 21 BLOCKED_NO_COVER_ENCODER, 22 BLOCKED_ASSET_MISSING
56
66
  Pre-warm outside any sandboxed session: ${INSTALL_COMMAND} [--audio] [--word-timing]
57
67
  ${CREDIT_LINE}`;
58
68
 
@@ -63,7 +73,7 @@ export function parseArgs(argv) {
63
73
  const token = rest[i];
64
74
  if (!token.startsWith("--")) throw new Error(`unexpected argument: ${token}`);
65
75
  const key = token.slice(2);
66
- if (["stills-only", "cuts", "word-timing", "help", "detach"].includes(key)) args.flags.add(key);
76
+ if (["stills-only", "cuts", "word-timing", "help", "detach", "strict", "json"].includes(key)) args.flags.add(key);
67
77
  else {
68
78
  const value = rest[i + 1];
69
79
  if (value === undefined || value.startsWith("--")) throw new Error(`--${key} needs a value`);
@@ -741,6 +751,7 @@ export async function main(argv = process.argv.slice(2)) {
741
751
  if (!args.out) throw new Exit(EXIT.USAGE, "--out <dir> is required");
742
752
  const verdict = evaluateCompletion(resolve(args.out));
743
753
  out(`completion: ${verdict.status} - ${verdict.reason}`);
754
+ for (const label of verdict.labels ?? []) out(`label: ${label}`);
744
755
  if (verdict.downgraded.length) out(`downgraded: ${verdict.downgraded.join("; ")} (say so in the reply)`);
745
756
  if (verdict.openItems.length) out(`open look items: ${verdict.openItems.join(" | ")}`);
746
757
  return verdict.complete ? EXIT.OK : 1;
@@ -752,6 +763,27 @@ export async function main(argv = process.argv.slice(2)) {
752
763
  else out(`look round ${entry.round} recorded against stills ${entry.manifestSha256.slice(0, 12)}: ${Object.keys(entry.frames).length} frames stamped${entry.needsAnotherRound ? `; another round needed: ${entry.openItems.map((item) => item.split(":")[0]).join(", ")}` : "; nothing asks for another round"}`);
753
764
  return EXIT.OK;
754
765
  }
766
+ if (args.mode === "cover") {
767
+ if (!args.out) throw new Exit(EXIT.USAGE, "--out <dir> is required");
768
+ const outDir = resolve(args.out);
769
+ const round = Number(args.round ?? 1);
770
+ if (args.window !== undefined) {
771
+ const span = String(args.window).split(",").map(Number);
772
+ if (span.length !== 2) throw new Exit(EXIT.USAGE, "--window takes t0,t1 in seconds");
773
+ return await renderCoverWindow({ outDir, round, window: span, log: out });
774
+ }
775
+ if (args.flags.has("detach")) return detach(argv, outDir);
776
+ return await renderCover({ outDir, round, log: out });
777
+ }
778
+ if (args.mode === "cover-gate") {
779
+ if (!args.file) throw new Exit(EXIT.USAGE, "cover-gate needs --file <cover.webp | cover.gif | PNG frame folder>");
780
+ const title = args.title ? String(args.title).split(",").map(Number) : null;
781
+ const result = coverGate(resolve(args.file), { frames: args.frames ? resolve(args.frames) : null, frames2: args.frames2 ? resolve(args.frames2) : null, masks: args.masks ? resolve(args.masks) : null, title, glyph: title && args.masks ? {} : null, fps: Number(args.fps ?? 16) });
782
+ const strict = args.flags.has("strict");
783
+ const { diffs, kept, durations, ...summary } = result;
784
+ out(args.flags.has("json") ? JSON.stringify(summary, null, 1) : formatCoverReport(result, { strict }).trimEnd());
785
+ return result.pass && (!strict || result.target) ? EXIT.OK : EXIT.GATE_FAIL_QA;
786
+ }
755
787
  if (args.mode === "sound") {
756
788
  const { treatment } = resolveTreatment(args, null);
757
789
  const fps = treatment.fps ?? 60;
@@ -1,6 +1,6 @@
1
1
  #!/usr/bin/env node
2
2
  // `litcodex motion-runtime install|status` backend. install is the only network step this skill
3
- // has; status prints the five doctor probes (MO-A-44) plus the audio and word-timing tiers.
3
+ // has; status prints the six doctor probes (MO-A-44) plus the audio and word-timing tiers.
4
4
  import { realpathSync } from "node:fs";
5
5
  import { fileURLToPath } from "node:url";
6
6
  import { INSTALL_COMMAND } from "../engine/constants.mjs";
@@ -151,9 +151,14 @@ Treat this SKILL.md as an LLM contract artifact, not a casual help page. Load it
151
151
  # litgoal
152
152
 
153
153
  You are the goal-BINDING surface. Your one job: turn the user's request into a crisp objective with
154
- checkable success criteria and persist it into durable loop state so lit-loop can EXECUTE it. You SET
155
- the goal here; lit-loop RUNS it. Do NOT implement, do NOT run tests, do NOT capture evidence — that is
156
- the loop's job, not yours.
154
+ checkable success criteria and persist it into durable loop state so lit-loop can EXECUTE it. litgoal sets and keeps the finish line;
155
+ lit-loop and start-work run toward it. You SET the goal here; lit-loop RUNS it. Do NOT implement, do NOT
156
+ run tests, do NOT capture evidence — that is the loop's job, not yours.
157
+
158
+ "Keeps" is literal: the binding lives in `.litcodex/lit-loop/goals.json`, so later turns and later
159
+ sessions aim at the same objective and criteria. lit-loop reads it, records evidence against it and never
160
+ edits the objective or the criteria; start-work runs an approved plan toward the same finish line. To move
161
+ the finish line, run litgoal again with the new objective.
157
162
 
158
163
  ## Step 1 — Restate the objective as ONE crisp goal
159
164