@litfamily/litgravity 0.1.0 → 0.1.2

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 (248) hide show
  1. package/CHANGELOG.md +32 -0
  2. package/README.md +72 -17
  3. package/README_ko-KR.md +72 -17
  4. package/package.json +1 -1
  5. package/plugin/hooks/lib/lanes.mjs +65 -0
  6. package/plugin/hooks/lib/motion.mjs +34 -5
  7. package/plugin/hooks/lib/reentry.mjs +7 -0
  8. package/plugin/hooks/lib/rewind/brief.mjs +332 -0
  9. package/plugin/hooks/lib/rewind/collect.mjs +328 -0
  10. package/plugin/hooks/lib/rewind/gauge.mjs +55 -0
  11. package/plugin/hooks/lib/rewind/next-step.mjs +77 -0
  12. package/plugin/hooks/lib/rewind/redact.mjs +60 -0
  13. package/plugin/hooks/lib/rewind/transcripts.mjs +211 -0
  14. package/plugin/hooks/lib/routes.mjs +79 -5
  15. package/plugin/hooks/lib/workflow-stack.mjs +213 -0
  16. package/plugin/hooks/post-tool-use.mjs +37 -1
  17. package/plugin/hooks/pre-invocation.mjs +91 -2
  18. package/plugin/hooks/session-start.mjs +26 -3
  19. package/plugin/hooks/stop.mjs +22 -2
  20. package/plugin/hud/looks.mjs +29 -0
  21. package/plugin/hud/render.mjs +234 -12
  22. package/plugin/plugin.json +1 -1
  23. package/plugin/skills/frontend-ui-ux/SKILL.md +12 -1
  24. package/plugin/skills/frontend-ui-ux/kit/components.css +417 -0
  25. package/plugin/skills/frontend-ui-ux/kit/fonts.json +22 -0
  26. package/plugin/skills/frontend-ui-ux/kit/layouts/landing.html +164 -0
  27. package/plugin/skills/frontend-ui-ux/kit/layouts/settings.html +114 -0
  28. package/plugin/skills/frontend-ui-ux/kit/layouts/workspace.html +115 -0
  29. package/plugin/skills/frontend-ui-ux/kit/styles/computational-brutalism.json +227 -0
  30. package/plugin/skills/frontend-ui-ux/kit/styles/field-notes.json +205 -0
  31. package/plugin/skills/frontend-ui-ux/kit/styles/graphite.json +200 -0
  32. package/plugin/skills/frontend-ui-ux/kit/styles/meadow.json +199 -0
  33. package/plugin/skills/frontend-ui-ux/kit/styles/neo-brutalism.json +222 -0
  34. package/plugin/skills/frontend-ui-ux/kit/ui.js +226 -0
  35. package/plugin/skills/frontend-ui-ux/references/house-styles.md +234 -0
  36. package/plugin/skills/frontend-ui-ux/scripts/design-lock.mjs +400 -0
  37. package/plugin/skills/frontend-ui-ux/scripts/interface-probe-lock.mjs +196 -0
  38. package/plugin/skills/frontend-ui-ux/scripts/interface-probe-page.mjs +30 -9
  39. package/plugin/skills/frontend-ui-ux/scripts/interface-probe-rules.mjs +20 -8
  40. package/plugin/skills/frontend-ui-ux/scripts/interface-probe.mjs +42 -9
  41. package/plugin/skills/frontend-ui-ux/scripts/pixel-art.mjs +60 -0
  42. package/plugin/skills/lit-adhd/SKILL.md +157 -0
  43. package/plugin/skills/lit-adhd/references/card-examples.md +101 -0
  44. package/plugin/skills/lit-adhd/references/status-taxonomy.md +32 -0
  45. package/plugin/skills/lit-adhd/scripts/rewind.mjs +5 -0
  46. package/plugin/skills/lit-diagram-drawer/SKILL.md +5 -3
  47. package/plugin/skills/lit-diagram-drawer/references/drawing-rules.md +1 -1
  48. package/plugin/skills/lit-diagram-drawer/references/style-guide.md +21 -12
  49. package/plugin/skills/lit-diagram-drawer/references/type-architecture.md +3 -3
  50. package/plugin/skills/lit-diagram-drawer/references/type-dependency.md +1 -1
  51. package/plugin/skills/lit-diagram-drawer/references/type-tree.md +3 -3
  52. package/plugin/skills/lit-diagram-drawer/references/type-wardley.md +1 -1
  53. package/plugin/skills/lit-diagram-drawer/scripts/diagram-craft-rules.mjs +1 -2
  54. package/plugin/skills/lit-diagram-drawer/scripts/visual-quality.mjs +1 -2
  55. package/plugin/skills/lit-docx/SKILL.md +3 -3
  56. package/plugin/skills/lit-handoff/SKILL.md +1 -0
  57. package/plugin/skills/lit-hijack/SKILL.md +263 -0
  58. package/plugin/skills/lit-hijack/references/capture-and-provenance.md +100 -0
  59. package/plugin/skills/lit-hijack/references/clean-room-build.md +75 -0
  60. package/plugin/skills/lit-hijack/references/distil-and-licence.md +67 -0
  61. package/plugin/skills/lit-hijack/references/gap-and-port-design.md +100 -0
  62. package/plugin/skills/lit-hijack/references/parity-and-report.md +85 -0
  63. package/plugin/skills/lit-hijack/scripts/hijack.mjs +953 -0
  64. package/plugin/skills/lit-plan/SKILL.md +1 -1
  65. package/plugin/skills/lit-pptx/SKILL.md +8 -8
  66. package/plugin/skills/lit-pptx/fonts/jetbrains-mono/JetBrainsMono-Bold.ttf +0 -0
  67. package/plugin/skills/lit-pptx/fonts/jetbrains-mono/JetBrainsMono-Regular.ttf +0 -0
  68. package/plugin/skills/lit-pptx/fonts/jetbrains-mono/OFL.txt +93 -0
  69. package/plugin/skills/lit-pptx/fonts/provenance.json +32 -1
  70. package/plugin/skills/lit-pptx/references/agents/analyst.md +34 -56
  71. package/plugin/skills/lit-pptx/references/agents/antithesis.md +49 -67
  72. package/plugin/skills/lit-pptx/references/agents/architect.md +38 -51
  73. package/plugin/skills/lit-pptx/references/agents/critic.md +25 -41
  74. package/plugin/skills/lit-pptx/references/agents/synthesizer.md +37 -46
  75. package/plugin/skills/lit-pptx/references/agents/thesis.md +29 -49
  76. package/plugin/skills/lit-pptx/references/anti-slop-checklist.md +119 -145
  77. package/plugin/skills/lit-pptx/references/authoring-guide.md +187 -278
  78. package/plugin/skills/lit-pptx/references/consensus-protocol.md +99 -97
  79. package/plugin/skills/lit-pptx/references/data-display-cookbook.md +36 -137
  80. package/plugin/skills/lit-pptx/references/density-and-fill.md +147 -216
  81. package/plugin/skills/lit-pptx/references/design-system-azure.md +56 -85
  82. package/plugin/skills/lit-pptx/references/direction-step.md +134 -176
  83. package/plugin/skills/lit-pptx/references/examples/01-pitch-signal-ko.md +114 -115
  84. package/plugin/skills/lit-pptx/references/examples/02-pitch-studio-ko.md +66 -66
  85. package/plugin/skills/lit-pptx/references/examples/03-business-review-ledger-ko.md +63 -63
  86. package/plugin/skills/lit-pptx/references/examples/04-business-review-night-en.md +96 -96
  87. package/plugin/skills/lit-pptx/references/examples/05-research-talk-paper-en.md +81 -81
  88. package/plugin/skills/lit-pptx/references/examples/06-lecture-chalk-ko.md +103 -103
  89. package/plugin/skills/lit-pptx/references/examples/07-data-review-night-en.md +100 -98
  90. package/plugin/skills/lit-pptx/references/examples/08-image-led-atlas-ko.md +76 -76
  91. package/plugin/skills/lit-pptx/references/examples/09-briefing-gazette-ko.md +96 -96
  92. package/plugin/skills/lit-pptx/references/examples/10-status-update-ledger-ko.md +80 -80
  93. package/plugin/skills/lit-pptx/references/examples/11-portfolio-studio-en.md +72 -72
  94. package/plugin/skills/lit-pptx/references/examples/12-research-tutorial-chalk-en.md +95 -95
  95. package/plugin/skills/lit-pptx/references/examples/13-engineering-review-computational-brutalism-ko.md +173 -0
  96. package/plugin/skills/lit-pptx/references/examples/14-launch-pitch-neo-brutalism-ko.md +154 -0
  97. package/plugin/skills/lit-pptx/references/examples/15-design-lecture-bauhaus-ko.md +139 -0
  98. package/plugin/skills/lit-pptx/references/examples/16-community-programme-riso-ko.md +158 -0
  99. package/plugin/skills/lit-pptx/references/examples/17-public-data-briefing-newsroom-ko.md +179 -0
  100. package/plugin/skills/lit-pptx/references/interview-protocol.md +83 -102
  101. package/plugin/skills/lit-pptx/references/layout-families.md +161 -265
  102. package/plugin/skills/lit-pptx/references/stages/autopilot.md +30 -70
  103. package/plugin/skills/lit-pptx/references/stages/interview.md +36 -68
  104. package/plugin/skills/lit-pptx/references/stages/plan.md +26 -67
  105. package/plugin/skills/lit-pptx/references/title-treatments.md +93 -145
  106. package/plugin/skills/lit-pptx/references/tonalities/atlas.md +95 -108
  107. package/plugin/skills/lit-pptx/references/tonalities/bauhaus.md +140 -0
  108. package/plugin/skills/lit-pptx/references/tonalities/chalk.md +107 -122
  109. package/plugin/skills/lit-pptx/references/tonalities/computational-brutalism.md +150 -0
  110. package/plugin/skills/lit-pptx/references/tonalities/gazette.md +87 -111
  111. package/plugin/skills/lit-pptx/references/tonalities/ledger.md +96 -125
  112. package/plugin/skills/lit-pptx/references/tonalities/neo-brutalism.md +161 -0
  113. package/plugin/skills/lit-pptx/references/tonalities/newsroom.md +144 -0
  114. package/plugin/skills/lit-pptx/references/tonalities/night.md +104 -131
  115. package/plugin/skills/lit-pptx/references/tonalities/paper.md +114 -130
  116. package/plugin/skills/lit-pptx/references/tonalities/riso.md +137 -0
  117. package/plugin/skills/lit-pptx/references/tonalities/signal.md +96 -103
  118. package/plugin/skills/lit-pptx/references/tonalities/studio.md +81 -112
  119. package/plugin/skills/lit-pptx/scripts/compile-deck.js +4 -6
  120. package/plugin/skills/lit-pptx/scripts/craft_extras.py +135 -91
  121. package/plugin/skills/lit-pptx/scripts/deck_craft.py +1 -1
  122. package/plugin/skills/lit-pptx/scripts/embed_fonts.py +13 -1
  123. package/plugin/skills/lit-pptx/scripts/layout_inventory.py +1 -1
  124. package/plugin/skills/lit-pptx/scripts/learn_template.py +1 -1
  125. package/plugin/skills/lit-pptx/scripts/lib/grid-resolver.js +101 -110
  126. package/plugin/skills/lit-pptx/scripts/lib/layout-resolver.js +9 -15
  127. package/plugin/skills/lit-pptx/scripts/lib/render-pack.js +370 -563
  128. package/plugin/skills/lit-pptx/scripts/lib/slide-grid.js +104 -0
  129. package/plugin/skills/lit-pptx/scripts/lib/template-registry.js +57 -6
  130. package/plugin/skills/lit-pptx/scripts/qa_deck.py +6 -6
  131. package/plugin/skills/lit-pptx/scripts/render_pages.py +31 -0
  132. package/plugin/skills/lit-pptx/scripts/validate_pptx.py +1 -1
  133. package/plugin/skills/lit-pptx/specs/markdown-slide-spec-v1.md +167 -191
  134. package/plugin/skills/lit-pptx/specs/markdown-slide-spec-v2.md +117 -166
  135. package/plugin/skills/lit-pptx/specs/template-enrollment-contract.md +307 -330
  136. package/plugin/skills/lit-pptx/templates/tonalities/atlas/pack.yaml +1 -1
  137. package/plugin/skills/lit-pptx/templates/tonalities/bauhaus/pack.yaml +98 -0
  138. package/plugin/skills/lit-pptx/templates/tonalities/chalk/pack.yaml +1 -1
  139. package/plugin/skills/lit-pptx/templates/tonalities/computational-brutalism/pack.yaml +99 -0
  140. package/plugin/skills/lit-pptx/templates/tonalities/gazette/pack.yaml +1 -1
  141. package/plugin/skills/lit-pptx/templates/tonalities/ledger/pack.yaml +1 -1
  142. package/plugin/skills/lit-pptx/templates/tonalities/neo-brutalism/pack.yaml +107 -0
  143. package/plugin/skills/lit-pptx/templates/tonalities/newsroom/pack.yaml +99 -0
  144. package/plugin/skills/lit-pptx/templates/tonalities/night/pack.yaml +1 -1
  145. package/plugin/skills/lit-pptx/templates/tonalities/paper/pack.yaml +1 -1
  146. package/plugin/skills/lit-pptx/templates/tonalities/riso/pack.yaml +99 -0
  147. package/plugin/skills/lit-pptx/templates/tonalities/signal/pack.yaml +2 -2
  148. package/plugin/skills/lit-pptx/templates/tonalities/studio/pack.yaml +1 -1
  149. package/plugin/skills/lit-schematic/SKILL.md +114 -0
  150. package/plugin/skills/lit-schematic/examples/iso-heat-exchanger/build.mjs +38 -0
  151. package/plugin/skills/lit-schematic/examples/iso-heat-exchanger/scene.mjs +133 -0
  152. package/plugin/skills/lit-schematic/examples/journal-adsorption-rig/build.mjs +87 -0
  153. package/plugin/skills/lit-schematic/examples/pid-dosing-skid/build.mjs +85 -0
  154. package/plugin/skills/lit-schematic/references/cutaway-outputs.md +70 -0
  155. package/plugin/skills/lit-schematic/references/isometric-craft.md +101 -0
  156. package/plugin/skills/lit-schematic/references/journal-figures.md +72 -0
  157. package/plugin/skills/lit-schematic/references/kit-api.md +134 -0
  158. package/plugin/skills/lit-schematic/references/pfd-and-layout.md +53 -0
  159. package/plugin/skills/lit-schematic/references/pid-drafting.md +103 -0
  160. package/plugin/skills/lit-schematic/references/pid-symbols.md +163 -0
  161. package/plugin/skills/lit-schematic/references/verification.md +100 -0
  162. package/plugin/skills/lit-schematic/scripts/doctor.mjs +57 -0
  163. package/plugin/skills/lit-schematic/scripts/lib/figure.mjs +81 -0
  164. package/plugin/skills/lit-schematic/scripts/lib/fonts.mjs +27 -0
  165. package/plugin/skills/lit-schematic/scripts/lib/geom.mjs +113 -0
  166. package/plugin/skills/lit-schematic/scripts/lib/interactive.mjs +292 -0
  167. package/plugin/skills/lit-schematic/scripts/lib/isa.mjs +115 -0
  168. package/plugin/skills/lit-schematic/scripts/lib/iso.mjs +719 -0
  169. package/plugin/skills/lit-schematic/scripts/lib/legend-sheet.mjs +162 -0
  170. package/plugin/skills/lit-schematic/scripts/lib/pid.mjs +937 -0
  171. package/plugin/skills/lit-schematic/scripts/lib/png.mjs +132 -0
  172. package/plugin/skills/lit-schematic/scripts/lib/qa-core.mjs +658 -0
  173. package/plugin/skills/lit-schematic/scripts/lib/route.mjs +218 -0
  174. package/plugin/skills/lit-schematic/scripts/lib/sheet.mjs +890 -0
  175. package/plugin/skills/lit-schematic/scripts/lib/svg.mjs +82 -0
  176. package/plugin/skills/lit-schematic/scripts/lib/theme.mjs +115 -0
  177. package/plugin/skills/lit-schematic/scripts/motion.mjs +129 -0
  178. package/plugin/skills/lit-schematic/scripts/qa.mjs +92 -0
  179. package/plugin/skills/lit-schematic/scripts/render.mjs +233 -0
  180. package/plugin/skills/lit-schematic/scripts/scaffold.mjs +60 -0
  181. package/plugin/skills/lit-scientific-visualization/SKILL.md +17 -6
  182. package/plugin/skills/lit-typographic-motion/SKILL.md +58 -48
  183. package/plugin/skills/lit-typographic-motion/engine/THIRD_PARTY_NOTICES +13 -2
  184. package/plugin/skills/lit-typographic-motion/engine/blender/runner.py +218 -0
  185. package/plugin/skills/lit-typographic-motion/engine/core/presets.mjs +1 -1
  186. package/plugin/skills/lit-typographic-motion/engine/node/analysis.mjs +65 -1
  187. package/plugin/skills/lit-typographic-motion/engine/node/assets.mjs +298 -0
  188. package/plugin/skills/lit-typographic-motion/engine/node/blender.mjs +143 -0
  189. package/plugin/skills/lit-typographic-motion/engine/node/board.mjs +136 -0
  190. package/plugin/skills/lit-typographic-motion/engine/node/brief.mjs +7 -1
  191. package/plugin/skills/lit-typographic-motion/engine/node/chrome.mjs +9 -12
  192. package/plugin/skills/lit-typographic-motion/engine/node/cover-assets.mjs +5 -3
  193. package/plugin/skills/lit-typographic-motion/engine/node/cover-capture.mjs +7 -6
  194. package/plugin/skills/lit-typographic-motion/engine/node/cover-treatment.mjs +37 -4
  195. package/plugin/skills/lit-typographic-motion/engine/node/cover.mjs +19 -8
  196. package/plugin/skills/lit-typographic-motion/engine/node/done.mjs +45 -6
  197. package/plugin/skills/lit-typographic-motion/engine/node/frame-worker.mjs +7 -5
  198. package/plugin/skills/lit-typographic-motion/engine/node/gallery.mjs +121 -0
  199. package/plugin/skills/lit-typographic-motion/engine/node/host.mjs +34 -0
  200. package/plugin/skills/lit-typographic-motion/engine/node/house.mjs +44 -0
  201. package/plugin/skills/lit-typographic-motion/engine/node/look.mjs +34 -20
  202. package/plugin/skills/lit-typographic-motion/engine/node/pipeline.mjs +19 -9
  203. package/plugin/skills/lit-typographic-motion/engine/node/scaffold.mjs +210 -0
  204. package/plugin/skills/lit-typographic-motion/engine/node/score.mjs +639 -0
  205. package/plugin/skills/lit-typographic-motion/engine/node/sound-cli.mjs +21 -4
  206. package/plugin/skills/lit-typographic-motion/engine/node/sound.mjs +127 -29
  207. package/plugin/skills/lit-typographic-motion/engine/node/stage-capture.mjs +7 -6
  208. package/plugin/skills/lit-typographic-motion/engine/node/stage-gate.mjs +59 -5
  209. package/plugin/skills/lit-typographic-motion/engine/node/stage-qa.mjs +141 -9
  210. package/plugin/skills/lit-typographic-motion/engine/node/stage-serve.mjs +28 -5
  211. package/plugin/skills/lit-typographic-motion/engine/node/stage.mjs +82 -14
  212. package/plugin/skills/lit-typographic-motion/engine/node/styles.mjs +213 -0
  213. package/plugin/skills/lit-typographic-motion/engine/node/treatment.mjs +311 -10
  214. package/plugin/skills/lit-typographic-motion/engine/stage/cover-init.js +14 -2
  215. package/plugin/skills/lit-typographic-motion/engine/stage/init.js +11 -1
  216. package/plugin/skills/lit-typographic-motion/engine/stage/qa.js +6 -1
  217. package/plugin/skills/lit-typographic-motion/engine/stage/stage-kit.js +83 -0
  218. package/plugin/skills/lit-typographic-motion/engine/vendor/three/LICENSE +21 -0
  219. package/plugin/skills/lit-typographic-motion/engine/vendor/three/addons/environments/RoomEnvironment.js +144 -0
  220. package/plugin/skills/lit-typographic-motion/engine/vendor/three/addons/geometries/RoundedBoxGeometry.js +155 -0
  221. package/plugin/skills/lit-typographic-motion/engine/vendor/three/three.module.js +54571 -0
  222. package/plugin/skills/lit-typographic-motion/recipes/hero-3d/expected.json +69 -0
  223. package/plugin/skills/lit-typographic-motion/recipes/hero-3d/index.html +139 -0
  224. package/plugin/skills/lit-typographic-motion/recipes/orbit-loop/expected.json +6 -4
  225. package/plugin/skills/lit-typographic-motion/recipes/painted-light/expected.json +4 -2
  226. package/plugin/skills/lit-typographic-motion/recipes/weight-tide/expected.json +7 -5
  227. package/plugin/skills/lit-typographic-motion/references/cover.md +394 -443
  228. package/plugin/skills/lit-typographic-motion/references/craft-loop.md +57 -87
  229. package/plugin/skills/lit-typographic-motion/references/depth.md +122 -0
  230. package/plugin/skills/lit-typographic-motion/references/look.md +94 -129
  231. package/plugin/skills/lit-typographic-motion/references/runtime.md +58 -91
  232. package/plugin/skills/lit-typographic-motion/references/sound.md +130 -99
  233. package/plugin/skills/lit-typographic-motion/references/stage.md +190 -215
  234. package/plugin/skills/lit-typographic-motion/references/studio.md +245 -0
  235. package/plugin/skills/lit-typographic-motion/references/style-bibles.md +108 -97
  236. package/plugin/skills/lit-typographic-motion/references/treatment.md +191 -143
  237. package/plugin/skills/lit-typographic-motion/scripts/motion-doctor.mjs +17 -5
  238. package/plugin/skills/lit-typographic-motion/scripts/motion.mjs +47 -7
  239. package/plugin/skills/lit-typographic-motion/styles/paper.json +41 -0
  240. package/plugin/skills/lit-typographic-motion/styles/swiss-signal.json +41 -0
  241. package/plugin/skills/lit-typographic-motion/styles/terminalcore.json +42 -0
  242. package/plugin/skills/lit-typographic-motion/styles/tidal.json +41 -0
  243. package/plugin/skills/litresearch/SKILL.md +1 -0
  244. package/plugin/skills/readme-studio/SKILL.md +2 -0
  245. package/plugin/skills/readme-studio/templates/hyperframes-cover/package-lock.json +3 -3
  246. package/plugin/skills/readme-studio/templates/remotion-cover/package-lock.json +3 -3
  247. package/plugin/skills/review-work/SKILL.md +1 -1
  248. package/plugin/skills/start-work/SKILL.md +1 -1
@@ -1,473 +1,424 @@
1
- # Cover mode: the seamless README loop
1
+ # Cover mode (README cover loops)
2
2
 
3
- Open this file when the request asks for a README cover, a hero or banner loop, an animated project
4
- header, or anything else that plays forever at the top of a page with no one pressing play. Such a
5
- loop is a different object from a film. A film is read once, from a first frame to a last one; a
6
- cover is glanced at, scrolled past and seen again, so it has to look finished in any frame, keep
7
- moving in every half second and never show the point where it starts over. Everything else in this
8
- skill (the stage path, the type path, sound, beats) stays as it is for films. Cover mode only takes
9
- over when `treatment.json` says `"mode": "cover"`.
3
+ Read this when the request is a README cover, a hero or banner loop, an animated project cover, or
4
+ any short image that plays forever at the top of a page. A cover is not a film. It has no beats, no
5
+ arc, no ending, no sound and no copy lines. It is one picture that never stops moving and never
6
+ shows where it starts. Film mode (the stage and type paths) is unchanged and still takes every
7
+ other request.
10
8
 
11
- The reason for a separate mode is practical. The film pipeline rewards things that make a cover
12
- worse: beats of at least 1.2 s that each show something new, stills taken at beat midpoints, a
13
- settled end card, reading floors for copy. Followed faithfully, they produce a slide deck that
14
- happens to loop. Cover mode swaps them for a loop contract on the page, a review of motion on a
15
- contact sheet, and a gate that measures the encoded file the reader's browser will decode.
9
+ The difference matters because the film pipeline rewards the wrong things for a cover: beats of at
10
+ least 1.2 s, a new composition per beat, stills taken at beat midpoints, a settled end card and a
11
+ reading floor all push the result toward a slide deck. Cover mode replaces those with a loop
12
+ contract, a review that watches motion instead of stills, and a gate that measures the encoded
13
+ file a reader's browser will actually decode.
16
14
 
17
- ## Which film rules relax, and what replaces them
15
+ ## What is different from a film
18
16
 
19
- | In a film | In a cover |
17
+ | Film rule | Cover mode |
20
18
  | --- | --- |
21
- | Beats of 1.2 s or more, each with new content | No beats. One system and three speed layers, each running for the whole loop |
22
- | An end card that settles; holds count as rhythm | No ending at all. A hold longer than 0.5 s fails the TARGET of G3 |
23
- | At least 10 s, and shortening is a recorded downgrade | 6 to 12 s; every shipped recipe uses 8 s |
24
- | 16:9 or 9:16 | 2:1 (page 1200x600 CSS px, cover 1000x500) or 3:2 (page 1200x800, cover 960x640) |
25
- | A generated sound bed and its gates | Silent. `sound` is absent or `"none"` |
26
- | An invented subject and copy lines | The brand word, plus at most one motto that the user wrote or the project already prints |
27
- | Titles fading in, a stage skeleton rising from black | Frame 0 is the poster and already the whole picture |
28
- | Nine look questions about purpose and beats | Eight questions about motion, the seam and visible damage (below) |
29
-
30
- The film's flash audit, its no-network rule, its raster limits and its determinism rule all stay.
31
-
32
- ## The cover page
33
-
34
- Write the page as `cover/index.html` inside the output folder (`motion-<slug>/cover/index.html`),
35
- with its rasters in `cover/assets/`. The renderer serves that folder and three things of its own: the
36
- loop kit at `/lit/loop-kit.js`, the bundled faces at `/lit/fonts.css`, and the init script that runs
37
- before any of your code. The stage path's static scan runs on the folder first, so the same limits
38
- hold: nothing fetched from the network, no `<video>`, `<audio>`, `<iframe>` or workers, at most 24
39
- rasters and 8 MB of them, no animated raster and no flipbook of numbered frames. A script that looks
40
- like a third-party library gets a warning; the page is your own code plus the kit.
41
-
42
- The page contract has four parts.
43
-
44
- 1. **Layout size.** Lay everything out at the aspect's page size in CSS pixels. Capture runs at
45
- device scale 2 and the frames are downsampled with Lanczos to the cover size, so hairlines and
46
- small type are drawn at twice the density at which they are shown.
47
- 2. **`window.renderFrame(t, { mask })`.** `t` is loop time in [0, 1). The renderer draws frame `i`
48
- of `N` at `t = i / N` (with `N = round(loopSec * fps)`), so `t = 1` never reaches the page; drawing
49
- it would duplicate frame 0 and stutter at the seam. The call may return a promise; capture waits
50
- for it and for `document.fonts.ready`.
51
- 3. **`window.ready = true`.** Set it only after fonts and images are decoded. A page that is not
52
- ready within 60 s, or that sets `ready` with no `renderFrame`, stops with exit 17.
53
- 4. **The mask variant.** `renderFrame(t, { mask: true })` paints the brand word white and everything
54
- else black, in exactly the place the normal frame puts it. A mask capture of every frame feeds the
55
- title gates G5 and G6.
56
-
57
- Everything visible is a function of `t` alone. The renderer seeks frames in sequence, repeats all of
58
- them in a fresh browser, and then seeks sixteen of them in a shuffled order in a third browser. A
59
- frame that depends on the one drawn before it (a trail made by never clearing a canvas, a counter,
60
- an accumulated buffer) agrees with itself in sequence and disagrees when sought out of order. Clear
61
- every canvas you draw into and compute each frame from `t`.
62
-
63
- ### What throws during capture
64
-
65
- The init script replaces every clock and every unseeded entropy source with a function that throws
66
- and records its own name: `Math.random`, `Date()` and `new Date()` without arguments, `Date.now`,
67
- `performance.now`, `requestAnimationFrame`, `setInterval` and `crypto.getRandomValues`. CSS
68
- animations and transitions are switched off. The renderer reads the recorded names after loading and
69
- after each frame, so even a page that catches the error stops with exit 18 naming the call. Use
70
- `LitLoop.rng(seed)` for layout choices and `t` for anything that changes. A `new Date(2026, 0, 1)`
71
- with explicit arguments is allowed because it reads no clock.
72
-
73
- ### Faces
74
-
75
- The page may use the stage faces plus `"JetBrains Mono"`, a variable face with a real `wght` axis
76
- from 100 to 800 and a fixed advance, which lets the weight move without reflowing a line. Load every
77
- weight you use with `document.fonts.load` before setting `ready`.
78
-
79
- ## The loop kit
80
-
81
- `/lit/loop-kit.js` (source: engine/stage/loop-kit.js) is a classic script that defines a frozen
82
- `window.LitLoop`. Every helper in it is either pure or periodic in `t`, which is what keeps the seam
83
- invisible.
84
-
85
- | Helper | What it gives you |
86
- | --- | --- |
87
- | `rng(seed)` | mulberry32; a function returning [0, 1). Use it for layout only: positions, sizes, which copy carries the accent |
88
- | `makeNoise(seed)`, `loopNoise(noise, t, offset, radius)` | 3D value noise walked on a circle, so the value at `t = 1` equals the value at `t = 0`; `offset` separates copies, `radius` (default 1.3) sets how much one loop varies |
89
- | `ease.smooth`, `ease.outCubic`, `ease.inCubic`, `ease.outExpo`, `ease.outBack(p, s = 1.6)`, `ease.gain(p, k)` | Shapes for events; linear stays reserved for motion that never stops |
90
- | `cubicPulse(c, w, x)` | A symmetric bump of half-width `w` around `c`, zero outside; the right shape for micro events |
91
- | `expImpulse(x, k)` | A sharp rise and an exponential tail; the tail is a slow fade (see rule 8) |
92
- | `phase(t, offset, cycles)` | `fract(t * cycles - offset)`: where one copy is in its own loop |
93
- | `cdist(p, c)` | Distance from `c` around the loop (0 to 0.5), for an event that straddles `t = 0` |
94
- | `window(p, start, dur)` | A one-shot inside the loop: -1 outside `[start, start + dur)` (wrapping), else progress 0..1 |
95
- | `steps(p, stops, travel, ease)` | Hold and move: dwell at `stops` poses and travel during the last `travel` of each slot |
96
- | `swell(p)` | A cosine swell 0 to 1 to 0 that lingers at both ends |
97
- | `TAU`, `clamp`, `fract`, `mix` | The usual small arithmetic |
19
+ | Beats of at least 1.2 s, each showing something new | No beats. Layers and one system, each continuous over the whole loop |
20
+ | Settled end card, MO-C-14 ink ratio, holds as a reward | No ending. Any hold over 0.5 s is a defect (G3) |
21
+ | 10 s minimum and the "never shorten" downgrade | 6–12 s; 8 s worked for every recipe |
22
+ | 16:9 or 9:16 only | 2:1 (page 1200×600, cover 1000×500) or 3:2 (page 1200×800, cover 960×640) |
23
+ | Authored score and the SOUND gates | Silent. `sound` is absent or `none` |
24
+ | Invented subject, invented copy lines | The brand word, plus at most one motto the user wrote or the project already uses |
25
+ | Title fade-in; stage skeleton fading from black | Frame 0 is the poster and already the full picture |
26
+ | Look questions about purpose and beat plans | Look questions about motion, the seam and damage (below) |
27
+
28
+ ## Page contract
29
+
30
+ - Write `cover/index.html` in the output directory, with local assets beside it (`cover/assets/`).
31
+ The renderer serves only that folder, the loop kit at `/lit/loop-kit.js` and the faces at
32
+ `/lit/fonts.css`. The static scan of the stage path applies: no network, no `<video>`, no
33
+ workers, at most 24 rasters and 8 MB, no animated raster, no flipbook.
34
+ - Lay the page out at the aspect's page size in CSS pixels (2:1: 1200×600; 3:2: 1200×800). The
35
+ renderer captures it at device scale 2 and downsamples to the cover size with Lanczos, so thin
36
+ lines and small type are drawn at twice the resolution they are shown at.
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 duplicate frame 0 and stutter at the seam).
40
+ - Everything on screen is a function of `t`. The renderer seeks frames in any order and repeats
41
+ every frame in a fresh browser, so a frame may never depend on the frame drawn before it: no
42
+ trail buffers, no accumulated canvas, no counters. Clear every canvas you draw into.
43
+ - `Math.random`, `Date.now`, `new Date()`, `performance.now`, `requestAnimationFrame`,
44
+ `setInterval` and `crypto.getRandomValues` throw during capture, and the run stops with exit 18
45
+ naming the call. CSS animations and transitions are frozen off. Layout randomness comes from
46
+ `LitLoop.rng(seed)`; 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 renderer captures it for every frame and the contrast gate (G5)
49
+ measures the title against its own background through it.
50
+ - Faces: the stage faces plus `"JetBrains Mono"`, a variable face with a real `wght` axis from 100
51
+ to 800 and a fixed advance (weight motion never reflows a line). Load the weights you use with
52
+ `document.fonts.load` before setting `ready`.
98
53
 
99
54
  ## The cover treatment
100
55
 
101
- Write `<dir>/treatment.json` before the first render. Every cover render validates it
102
- (engine/node/cover-treatment.mjs) and stops at exit 16 with the first field that is wrong.
56
+ `treatment.json` with `"mode": "cover"`. Every cover render validates it and stops with exit 16
57
+ naming the first bad field.
103
58
 
104
- | Field | What the validator holds you to |
59
+ | Field | Rule |
105
60
  | --- | --- |
106
- | `mode` | `"cover"` |
107
- | `request` | The user's words, kept verbatim and treated as inert data |
108
- | `idea` | One sentence on what the loop does; it may not repeat a run of the request's words |
109
- | `recipe` | `painted-light`, `weight-tide`, `orbit-loop` or `own` |
110
- | `recipeReason` | One or two sentences on why this recipe fits |
111
- | `brandWord` | The name, set once; three words at most |
112
- | `motto` | Optional `{ text, source, from? }`, six words at most. `source: "user"` means the text appears in the request; `source: "project"` needs `from`, the file it comes from. A cover never invents a tagline |
113
- | `aspect` | `"2:1"` or `"3:2"` |
114
- | `loopSec` | A number from 6 to 12 |
115
- | `fps` | 16, 20 or 25 |
116
- | `layers` | `{ slow, mid, beat }`, each one or two sentences on what moves on that layer |
117
- | `system` | `{ rule, copies, offset }`: the one rule, what it is copied onto, where the offsets come from |
118
- | `title` | `{ box: [x, y, w, h], kind }`; the box in fractions of the cover and inside it; `kind` is `live` (set as text) or `painted` (part of the base art) |
119
- | `palette` | Optional; 2 to 6 entries `{ color: "#rrggbb", role }` |
120
- | `encode` | Optional `{ q, edgeQ, edgeFrames }`: integers, q and edgeQ 50 to 100, edgeFrames 0 to 60. Defaults: q 86, edgeQ 97, 15 edge frames, method 4 |
121
- | `seed` | Optional integer; it also seeds the seek-order shuffle |
122
- | `ambition` | One or two sentences in craft terms |
123
-
124
- Placeholder values (`<…>`, `TODO`, `TBD`, `...`) are refused. A `copy`, `beats` or `lines` field is
125
- refused outright, because a cover never swaps text states, and so is any `sound` other than `none`.
126
- The first valid treatment is kept in `.run/treatment.first.json`.
127
-
128
- ## Assets and the missing-asset stop
129
-
130
- Every raster the page can load is listed in `<dir>/assets.json` before the first render. The renderer
131
- checks the list before it opens a browser, so a bad list costs nothing.
132
-
133
- ```json
134
- { "assets": [
135
- { "path": "cover/assets/base.png", "role": "base-art", "source": "user",
136
- "sha256": "<64 hex>", "box": [0.125, 0, 0.75, 1], "checkBox": [0.131, 0.1445, 0.1416, 0.778], "title": true }
137
- ] }
138
- ```
139
-
140
- - `path` is relative to the output folder and lies inside `cover/`. `role` is `base-art`, `logo`,
141
- `wordmark` or `texture`. `source` is `user` for supplied art or `generated` for art made for this
142
- cover (for example with the host's `generate_image` tool, where the build offers it). `sha256` is the file's own hash.
143
- - A listed file that is absent stops the run at exit 22 `BLOCKED_ASSET_MISSING` before any
144
- frame is written. Ask the user for the art or generate it and list it as generated, so that the real
145
- art always takes the place of a stand-in. The `painted-light` recipe without a `base-art` entry is the same exit 22.
146
- - A raster in `cover/` that the list leaves out, or a listed file whose hash has changed, is exit 17.
147
- After you edit an asset, list it again with its new hash. A malformed entry is exit 16.
148
- - Base art needs `box`, where it sits on the cover. `checkBox` (inside `box`, at least 10 % of its
149
- area) is the region the ART check compares; without it the whole box is compared.
150
- - `title: true` on the base art declares that the brand word is painted into it. Only then is the
151
- title exempt from the G6 size floor, and it is still measured and printed as INFO.
152
- - Art is scaled whole into its box, and the stage raster limits still apply.
153
-
154
- When the cover is done, every `generated` entry becomes a line the reply has to carry: the Stop hook
155
- holds the finished turn once so that the reply says which asset was generated.
156
-
157
- ## Craft rules, most important first
158
-
159
- These come from rendering and measuring real covers, including several that looked fine as PNG
160
- frames and fell apart once encoded.
161
-
162
- 1. **Design for the encoder.** Lossy animated WebP leaves a pixel alone when it changes by less than
163
- roughly `31(1 - sqrt(q/100)) + sqrt(q/100)` levels from the previous frame: about 6 levels at q72,
164
- about 3 at q90. A slow fade or a gentle breathing glow under that step is simply not sent; the
165
- region goes stale and jumps back at the next keyframe, which by default is the loop point. None of
166
- this shows in the frames you captured. It only shows in the decoded file, which is why the gate
167
- decodes.
168
- 2. **Light travels as an edge.** A lit window that moves across the picture with a 24 to 40 px edge
169
- survives encoding. The same window with a 150 px soft edge did not at q72 with default keyframes: on
170
- one painted cover the moving share fell from 0.92 to 0.83 and the seam jumped to 24 times its
171
- neighbouring steps. At a high edge quality the soft edge survives and reads as a wash in place of a
172
- travelling edge, which no motion gate sees; only look review does.
173
- 3. **Something must translate.** A weight wave with nothing else moving lost most of its motion in
174
- the encoder (median step 0.0007, seam 14 times its neighbours). Letting the background rows drift
175
- one word length per loop kept all of it (median 0.0098, seam 1.1).
176
- 4. **One rule, copied, offset by position.** One swell over hundreds of letters, one orbit rule on
177
- three rings, one light window over seven bays. The offset of each copy comes from x, y, its angle
178
- or a loop-noise field, and the wave appears by itself. There is no timeline and there are no scenes.
179
- 5. **Three speed layers.** A slow layer that never stops and moves linearly (drift, laps, rising
180
- motes); a mid layer that swells (the tide, the light window); and short events on a beat (a cursor
181
- step with `outBack`, a gate flash, a blink, a flare). Every cover that reached TARGET had all three.
182
- 6. **The brand word stays where it is.** It can be the material (its weight changes and its position
183
- does not), it can stand still beside the system, or it can be painted into the art and lifted.
184
- Motion happens inside it, around it or behind it.
185
- 7. **Frame 0 is the poster.** Thumbnails, reduced-motion readers and slow connections show frame 0
186
- alone, so it must be the complete picture: no black opening, no fade in.
187
- 8. **Exponential tails are slow fades.** `expImpulse` spends half the loop decaying below the encoder
188
- step. Use `cubicPulse` for micro events, and place one across `t = 0` so whatever the keyframe
189
- resets lands under motion.
190
- 9. **Bands are flat steps, and every step clears the encoder.** A 3 px leading line followed by a
191
- two-step afterglow (0.10, then 0.05) encoded cleanly; adding a third step of 0.03 drifted and
192
- pushed the seam from 1.71 to 2.48. One flat slab encodes well but reads as a box on the sheet.
193
- 10. **Few small movers over texture.** Each mote over a painting makes the encoder resend the
194
- textured blocks around it; halving the motes on one cover saved about 0.2 MB. Keep them few, and
195
- mostly on the plain wings.
196
- 11. **Lift a painted title instead of overlaying live text.** Raise only the pixels brighter than the
197
- plate behind the letters (a luminance-keyed gain): the letters reach 4.5:1 or more, the plate
198
- stays dark, and thresholding the same letters gives the mask. Live text set at the painting's
199
- scale ended up about 11 px tall at README width.
200
- 12. **Spend quality at the seam.** Once every edge is sharp, what remains at the loop point is
201
- requantisation: frame 0 is a keyframe and the frames before it carry different error. Raise the
202
- quality of frame 0 and the last stretch (`encode.edgeQ` over `encode.edgeFrames`) and keep the
203
- default keyframes. Periodic keyframes spread the snap into visible pops, and a very short keyframe
204
- interval made a 2.5 to 5 Hz shimmer.
205
- 13. **Size and frame rate.** Encode at 1000x500 for a README: the column is about 830 to 900 px
206
- wide, and the title still has room. Use 16 fps for slow painted covers (20 fps cost about 18 %
207
- more and thinned each step) and 25 fps for a system with fast dots. At 16 fps img2webp writes
208
- 63 ms frames, so an 8 s loop lasts 8.064 s; that is fine.
209
-
210
- ## Recipes
211
-
212
- Each recipe is a worked page in `recipes/<name>/index.html` with the treatment, settings and gate row
213
- it shipped with in `recipes/<name>/expected.json`. Start a cover by copying the page into `cover/`,
214
- then change the brand word, the motto, and for the painted recipe its `ART` block. Treat the pages as
215
- examples; the rules above are what carries over to an `own` recipe.
216
-
217
- ### Painted base + travelling light (`painted-light`, the default)
218
-
219
- A finished painting is the whole picture, and the page relights it. The painting is supplied by the
220
- user, or generated and labelled as generated, and listed as `base-art`. It keeps its own coordinates
221
- and is scaled into its box; at 2:1 a 3:2 painting is pillarboxed and the side wings stay quiet (a
222
- static spill and a few motes; nothing glows outside the frame). Macro layer: the dim bays sit in a
223
- dimmed pool, and a lit window with a 24 px feather walks across them once per loop. Mid layer: a scan
224
- band per bay at two passes per loop, offset by the bay's position; a comet lapping the hero's frame;
225
- one fast skewed glint across the title in **overlay** blend, which keeps the plate dark and
226
- brightens only the letters (screen brightens a visible box, and colour-dodge saturated a coloured
227
- letter into a red block). Beat layer: the eyes breathe twice with a phase offset, the core breathes
228
- once, one blink, and the accent word flares at `t = 0` and `t = 0.5`. A denser or brighter painting
229
- needs a deeper dim pool and a lower `q`; the settings that reached TARGET are in the recipe's row.
230
-
231
- **Choosing the hero.** Any bay can be the hero, so a cover can feature one machine on a shared
232
- line-up. Three things move together:
233
- 1. `ART.hero` is the bay index (0 is the leftmost bay). The dim pool is clipped around that bay, so a
234
- hero in the middle stays at source brightness while the light window still walks every other bay
235
- as one continuous light. The comet laps the hero's border and its scan band stays at full
236
- strength.
237
- 2. `ART.lights` maps a bay index to the light anchors measured on that machine
238
- (`{ cx, cy, rx, ry, k }` in painting pixels; `k` 0 and 1 are eyes that breathe twice and blink,
239
- `k` 2 is a core that breathes once). Only the hero's entry glows. A hero with no entry stops the
240
- page with `ART.lights has no entry for the hero bay N` (the render ends as
241
- `STAGE_CONTRACT_ERROR` after the 60 s ready wait), because borrowing another machine's
242
- coordinates draws its eyes on the wrong body. Measure the anchors, or write `[]` for that bay to
243
- run with no beat lights and say so in the treatment's beat layer.
244
- 3. The base art's `checkBox` in the asset list points at the hero bay. With the shipped layout
245
- (painting scaled by `S = 600 / 1024` and pillarboxed 150 px from the left of a 1200 x 600 page) a
246
- bay `[x0, x1]` with panel `top` and `bottom` is
247
- `[(150 + x0·S) / 1200, top·S / 600, (x1 - x0)·S / 1200, (bottom - top)·S / 600]`. A box left on
248
- another bay measures a dimmed bay and the ART line fails.
249
-
250
- The accent flare and the title glint belong to the painted motto and title, not to the hero, and
251
- stay where they are.
252
-
253
- ### Weight tide (`weight-tide`)
254
-
255
- Rows of the brand word in JetBrains Mono at about 1.3:1 against the background drift one word length
256
- per loop, alternate rows in opposite directions. Each letter's weight is
257
- `gain(swell(fract(t - offset)), 2.4)` with `offset = 0.85 * x / W + 0.35 * y / H`. The hero word sits
258
- on a knockout band and takes the same field over a narrower range (330 to 800) so it never thins. One
259
- accent: a terminal cursor that dwells under each letter, steps to the next with `outBack`, and
260
- returns home on the last stop.
261
-
262
- ### Orbit loop (`orbit-loop`)
263
-
264
- Three rings carry dots that complete 3, 2 and 1 laps per loop in alternating directions, each with a
265
- fading arc trail. A gate at twelve o'clock flashes on every crossing and pulses the dot that passes.
266
- The crossing times are computed analytically and light the cells of a ledger under the word, which
267
- then decay; there are as many crossings per loop as cells, so the ledger loops too. The core breathes
268
- once per loop and rings on each of four bars. The word stays still on the left.
269
-
270
- ### Own
271
-
272
- Any system that keeps the rules: one rule copied with positional offsets, three layers, a word that
273
- stays put, edges instead of fades. Name it in `recipeReason`.
274
-
275
- ### Rows and negatives
276
-
277
- Each `expected.json` keeps the decoded gate row the recipe reached (median d, moving share, longest
278
- still, spike, seamLocal, bytes) next to its encode settings and treatment. The repository's cover
279
- recipe QA re-renders every recipe through this renderer and fails when median d or the moving share
280
- leaves ±15 % of its row, seamLocal leaves TARGET, or the file grows past 2 MiB.
281
-
282
- Every negative and every regression declares the gates it must fail in `mustFail`, as `<gate>.<tier>` ids
283
- (`G2.floor`, `G1.target`). `--negatives` renders them all. A case counts as caught only when its render
284
- completed and gated the decoded file (exit 0 or 13, with a manifest), every declared gate failed at its
285
- declared tier, and no FLOOR gate among G1 to G4 failed without being declared. A crash, a missing or empty
286
- declaration, a gate that passed, or a failure on an undeclared FLOOR gate fails the QA and says which.
287
-
288
- The painted recipe declares one regression, `feather-150` (`--feather 150` runs it alone and needs the
289
- painting): the light edge widened from 24 to 150 px. The defect it stands for is light drawn as a soft wash
290
- in place of a travelling edge. At this recipe's encode (q83, edge q97 for 18 frames) the encoder keeps the
291
- soft edge, so the motion numbers stay near the recipe's own (moving 1.0, seamLocal wandering 1.91 to 2.01
292
- around the 2.0 TARGET from run to run). What it reliably trips is the 2 MiB size TARGET (about 2.5 to
293
- 2.6 MB against 2.06 MB), so `G1.target` is the only gate it declares and G4 stays undeclared. A decoded-file
294
- edge measure was tried and dropped: it rated a sharp-windowed cover below the soft wash, because it
295
- measures every soft change in the frame and not the travelling edge, and any threshold would be fitted
296
- to one painting. The wash belongs to look review (question 6 in `references/look.md`).
297
-
298
- `recipes/negatives/` holds four slide-like pages, each declaring the FLOOR gates it must keep failing as
299
- `mustFail` in its own `expected.json`:
300
-
301
- | Negative | What it does | Must fail |
302
- | --- | --- | --- |
303
- | `title-slam` | the name slams in, lines appear one by one, an end card holds | G2 and G3 |
304
- | `card-scenes` | cards fade in, hold, and fade out in turn | G2 |
305
- | `still-glow` | a still picture with a faint breathing glow | G2 and G3 |
306
- | `reset-sweep` | a progress sweep that resets at the loop point | G4 |
307
-
308
- They are never recipes. Read them to see what cover mode exists to prevent, and never move a
309
- threshold so that one of them passes.
310
-
311
- ## Encoding
312
-
313
- The frames are encoded with img2webp: lossy, `-loop 0`, `-m 4`, every frame shown for
314
- `round(1000 / fps)` ms, frame 0 and the last `edgeFrames` frames at `edgeQ`, the rest at `q`, default
315
- keyframes. Method 6 took minutes and gained little, and `-mixed` changes nothing while every frame is
316
- lossy. The gate decodes with dwebp, so img2webp counts only together with dwebp. When either is
317
- missing, gifski at quality 90 writes `cover.gif` instead. With neither, the render stops before
318
- capture at exit 21 `BLOCKED_NO_COVER_ENCODER`; tell the user to install libwebp (or gifski). A cover
319
- is never an MP4: README renderers do not autoplay video.
320
-
321
- ## The gate: measured on the decoded file
322
-
323
- `cover-gate` (engine/node/cover-gate.mjs) decodes the cover the way a browser composites it and turns
324
- each frame into a luma grid about 300 px wide. It then resamples to a fixed time grid of
325
- `max(50 ms, shortest frame)`. The grid matters: an encoder merges identical frames into one long
326
- frame, and statistics counted per frame would make a slide film look busy. `d` is the mean absolute
327
- luma change per grid step (0 to 1). The loop is a ring, so the step from the last sample back to the
328
- first, the seam, counts as one more step. A step below 0.0005 is still.
329
-
330
- | Gate | What it measures | FLOOR (fails the cover) | TARGET (`--strict`, the cover-mode goal) |
331
- | --- | --- | --- | --- |
332
- | G0 determinism | SHA-256 of every frame in two captures from fresh browsers | all identical | same |
333
- | G1 budget | bytes, duration, loop count | ≤ 3 MiB, 6 to 12 s, loops forever | ≤ 2 MiB |
334
- | G2 motion energy | median d; share of moving steps | ≥ 0.0004; ≥ 0.45 | ≥ 0.0015; ≥ 0.95 |
335
- | G3 anti-slide | longest still run; largest step / median step | ≤ 2.0 s | ≤ 0.5 s and spike ≤ 6 |
336
- | G4 seam | seam step / mean of the two steps on each side (`seamLocal`) | ≤ 8 | between 0.25 and 2.0 |
337
- | G5 title contrast | per frame, the median title pixel against the 90th-percentile background in the title box, read through the mask | ≥ 4.5:1 in every frame | same |
338
- | G6 title size | cap height of the title glyphs in the mask, scaled to an 830 px README width | ≥ 24 px | same; a declared painted title is INFO |
339
- | SEEK | 16 frames re-rendered in a seeded shuffled order in a fresh page, against the master | identical, or within one level per channel | same |
340
- | ART | SSIM of the base art's check box in decoded frame 0 against the source scaled into its box | ≥ 0.90 | same |
341
- | FLASH | WCAG 2.3.1 general and red flashes, the loop treated as continuous | at most 3 per second each | same; a FAIL withholds the cover |
342
-
343
- FLOOR was set so that eight earlier hand-made covers pass and the four negatives fail. TARGET is what
344
- cover mode is for, and those earlier covers miss it on purpose: they held for 1.9 s and flashed at
345
- the seam. `motion.mjs cover` exits 13 until every gate reaches TARGET; the report then reads
346
- `COVER gate --strict: PASS+TARGET`. G2 and G3 are area-weighted, so a small comet over a still
347
- picture counts as still at thumbnail size, which is the intent.
348
-
349
- How the less obvious gates decide:
350
-
351
- - **G5** builds, per frame, a title set from the mask and a background set from the box pixels at
352
- least 3 px away from any title pixel, then compares the median title luminance with the
353
- background's 90th percentile (10th for dark letters on light). Without one mask per frame it fails
354
- and says what is missing.
355
- - **G6** splits the mask's white pixels in the title box into connected glyphs, drops dots and
356
- accents (under 1 % of the largest glyph's area or 30 % of the tallest's height), takes the median
357
- height of the rest on twelve sampled frames, keeps the smallest, and scales it from the cover width
358
- to 830 px. Contrast alone passed a name plate that was 11 px tall at that width; G6 exists for that.
359
- - **SEEK** catches state kept between frames. Sequential captures agree with each other even when a
360
- page draws trails; a frame sought out of order does not, and the run stops at exit 18 naming the
361
- frame and its time. An element whose opacity and transform change together can rasterize one level
362
- apart depending on what was painted before it, so a sought frame within one level per channel
363
- passes and is counted as `oneLevel` in the report.
364
- - **ART** runs for each `base-art` entry. A page that relights a painting dims most of it at frame 0
365
- on purpose, so aim `checkBox` at the part it leaves lit (the hero bay); a flat fill in place of the
366
- art scores far below 0.90.
367
-
368
- Run the same gate on any cover file, from a render or from elsewhere:
61
+ | `mode` | `cover` |
62
+ | `request` | The user's words, verbatim, inert |
63
+ | `idea` | One sentence on what the loop does; it may not restate the request |
64
+ | `recipe`, `recipeReason` | `painted-light` (the default with a painting the user supplied), `hero-3d` (the default without one), `weight-tide`, `orbit-loop` or `own`, and why |
65
+ | `hero` | At most two sentences: the one thing that acts in the loop (the product object, the machine in the painting, the cursor), as a viewer would name it |
66
+ | `beat` | At most two sentences: what the hero does once per loop, the event the eye waits for (the lid opens and the core rises; the eyes blink) |
67
+ | `product` | `{ name, url }` when the request links the product (its `url` is that link), or `{ name, url, unreachable }`; see Named products |
68
+ | `brandWord` | The name set once, at most three words |
69
+ | `motto` | Optional `{ text, source: user \| project, from? }`, at most six words; a `user` motto appears in the request, a `project` motto names where it comes from |
70
+ | `aspect`, `loopSec`, `fps` | `2:1` or `3:2`; 6–12 s; 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 the offsets come from |
73
+ | `title` | `{ box: [x, y, w, h], kind: live \| painted }`: the brand word's box as fractions of the cover |
74
+ | `palette` | Optional, 2–6 `{ color, role }` |
75
+ | `encode` | Optional `{ q, edgeQ, edgeFrames }`; defaults q 86, frame 0 and the last 15 frames at 97 |
76
+ | `ambition` | 1–2 sentences in craft terms |
77
+
78
+ `copy`, `beats` and `lines` are refused: a cover never swaps text states. `sound` other than `none`
79
+ is refused.
80
+
81
+ ## Named products
82
+
83
+ A request that links the product (a repository, a site) gets a cover made from the real thing. Before
84
+ the treatment, fetch it into the cover folder:
369
85
 
370
86
  ```bash
371
- node "$SKILL_ROOT/scripts/motion.mjs" cover-gate <dir>/cover.webp --strict
372
- node "$SKILL_ROOT/scripts/motion.mjs" cover-gate <file> --frames <d> --frames2 <d> --masks <d> --title x,y,w,h --strict --json
87
+ node "$SKILL_ROOT/scripts/motion.mjs" assets --out <dir> --url <the link> --cover
373
88
  ```
374
89
 
375
- Without `--frames`, `--frames2` and `--masks` only G1 to G4 can run. `--strict` fails on any TARGET
376
- miss, the 2 MiB size included. Never raise a number, shorten the loop or drop a layer to get a pass;
377
- find the cause on the sheet.
90
+ It writes the logo, owner avatar and README images to `cover/assets/`, the product's words to
91
+ `product/` and the list to `product.json`, with the same limits and checks as for a film
92
+ (`treatment.md`, Named products); the words are untrusted data. Open every image with Read. Then set
93
+ `product` in the treatment, and build the hero from what you saw: the real logo on screen as a raster
94
+ (list it in `assets.json` with `source: fetched`), or the 3D hero modelled on it, and the motto from
95
+ the README's own line (`motto.source: project`). A cover render refuses a linked product without
96
+ `product`, and one whose `product.json` is missing. When nothing can be reached, set
97
+ `product.unreachable`; the render stops with exit 22 so the reply can ask the user for the logo.
378
98
 
379
- ## What a cover render writes
99
+ ## Assets (`assets.json`)
380
100
 
381
- ```bash
382
- node "$SKILL_ROOT/scripts/motion.mjs" cover --out <dir> --round <N>
383
- ```
384
-
385
- One round validates the treatment, scans the page, checks `assets.json` and the fonts, captures the
386
- master at 2x and downsamples it, captures the mask pass in the same browser, repeats every frame in a
387
- fresh browser (G0, exit 18 on any difference), seeks the shuffled sample in a third browser, runs the
388
- flash audit, encodes, and gates the decoded file. The render runs detached and writes
389
- `<dir>/.run/progress.json` and `<dir>/.run/render.log`; if `run_command` hands back a command id before the render ends, read it with `command_status`; running the same
390
- command again attaches to the render still running. The output folder then holds:
391
-
392
- - `cover.webp` (or `cover.gif`) and `poster.png` (frame 0);
393
- - `stills/sheet.png`: twelve decoded frames at `t = k/12` above a plot of every grid step's `d`, the
394
- still threshold as red dashes and the median as green dots; flat runs on the dashes are holds,
395
- regular spikes are encoder pops, a spike at the right end is a reset;
396
- - `stills/poster.png`, `stills/seam.png` (the last decoded frame beside frame 0), and
397
- `stills/frame-00.png` to `stills/frame-11.png`, the sheet's frames at full size, all listed in
398
- `stills/index.json`;
399
- - `gate-report.txt` (the verdict line and one line per gate), `manifest.json` (settings, bytes and
400
- the gate row), and `withheld/` only when the flash audit failed.
401
-
402
- Exit codes a cover render can end with: 13 a gate below TARGET (the message names them), 16 the
403
- treatment or the asset list entry, 17 the page contract or an unlisted or changed raster, 18 a clock
404
- or entropy call or a frame that differs in a fresh browser or out of order, 19 a network request, 21
405
- no encoder, 22 a missing asset.
406
-
407
- ## Looking at the cover
408
-
409
- The gate cannot see damage. On the painted pilot the two worst defects were found only by eye: a
410
- colour-dodge glint that turned one letter into a red block, and a wing glow that read as a dark disc.
411
- So every round ends with a look. Open `stills/sheet.png`, `stills/poster.png` and `stills/seam.png`
412
- with `read_file` (and any `frame-NN.png` you want closer), then answer the eight cover questions in
413
- `references/look.md` and record them:
101
+ Every raster the cover page loads is listed in `<dir>/assets.json` before the first render, and the
102
+ renderer checks the list before it captures anything:
414
103
 
415
- ```bash
416
- node "$SKILL_ROOT/scripts/motion.mjs" look --out <dir> --round <N> --answers <file>
104
+ ```json
105
+ { "assets": [{ "path": "cover/assets/base.png", "role": "base-art", "source": "user", "sha256": "<64 hex>", "box": [0.125, 0, 0.75, 1], "checkBox": [0.131, 0.1445, 0.1416, 0.778], "title": true }] }
417
106
  ```
418
107
 
419
- A cover has no stills-only round: round 1 is a full cover render followed by its look, and that
420
- look names the `change` you will make before round 2.
108
+ - `role` is `base-art`, `logo`, `wordmark` or `texture`; `source` is `user` (supplied), `fetched`
109
+ (by `assets --cover`, the product's own file) or `generated` (made for this cover, and labelled as
110
+ generated in the reply); `sha256` is the file's.
111
+ The painted recipe's base art must be `user`: a painting the request did not bring is not drawn or
112
+ generated for the occasion; that cover takes `hero-3d` (or `weight-tide`, `orbit-loop`) instead.
113
+ - A listed file that is missing stops the run with exit 22 `BLOCKED_ASSET_MISSING` and writes no
114
+ frame. Ask for the art; never draw a stand-in in its place. The `painted-light` recipe needs a
115
+ `base-art` entry with `source: user`, or the render exits 22 and names the recipes to take instead. A raster in `cover/` that the list does not name, or a listed
116
+ file whose hash no longer matches, is exit 17.
117
+ - `box` is where the base art sits on the cover (fractions). After the render, frame 0 must show the
118
+ art: the SSIM of `checkBox` (default: the whole box) in decoded frame 0 against the same region of
119
+ the source scaled into the box reaches 0.90 (the ART line of the report). A page that relights the
120
+ painting dims most of it at frame 0 on purpose, so point `checkBox` at a part it leaves lit (the
121
+ hero bay); it must cover at least 10 % of the box. The painted recipe on the repository painting
122
+ measured 0.96 there, 0.74 over the whole dimmed box, and a flat fill 0.20.
123
+ - `title: true` on the base art declares that the brand word is painted into it; only then is the
124
+ painted title exempt from the glyph-height floor (G6), and it is still measured and reported.
125
+ - The art is scaled into its box, never cropped, and the raster limits of the stage path still apply.
126
+
127
+ ## Craft rules, ranked
128
+
129
+ A cover is maximal by default, like a film: layered depth, the product's real parts with their names,
130
+ several accents by role, full 3D (`hero-3d`) where the subject has a back and an inside. It is minimal
131
+ only when the request asks for a calm, quiet or minimal cover. Density never breaks the rules below: it
132
+ is many copies of one rule, in three speed layers, around a brand word that never leaves.
133
+
134
+ 1. **The encoder is part of the design.** Lossy animated WebP treats a pixel as unchanged when it
135
+ moves less than about `31(1 - sqrt(q/100)) + sqrt(q/100)` levels from the previous frame: about
136
+ 6 levels at q72 and 3 at q90. Slow fades and slow breathing below that are dropped, go stale,
137
+ and snap back at the next keyframe, which by default is the loop point. Every failure of this
138
+ kind is invisible in the PNG frames and visible in the decoded file.
139
+ 2. **Light is a moving edge, not an in-place fade.** A travelling window with a 24–40 px edge
140
+ survives the encoder; a 150 px soft edge does not at q72 (moving share fell from 0.92 to 0.83 and
141
+ the seam jumped to 24 times its neighbours on the same frames). At a high edge quality the soft
142
+ edge survives and reads as a wash instead: no motion gate sees that, so the look review has to.
143
+ 3. **Something translates.** A weight tide alone lost most of its motion in the encoder (median
144
+ step 0.0007, seam 14×). One word of row drift per loop kept all of it (0.0098, seam 1.1×).
145
+ 4. **One rule, many copies, offsets from position.** One swell over 600 letters, one orbit rule
146
+ on three rings, one light window over the bays. Offsets come from x, y, angle or a loop-noise
147
+ field, and the wave appears by itself. No timeline, no scenes.
148
+ 5. **Three speed layers.** A slow, perpetual, linear layer (drift, laps, rising motes), a mid swell
149
+ (the tide, the light window), and micro events on a beat (a cursor step with `outBack`, a gate
150
+ flash, a blink, a flare). Every cover that reached TARGET had all three.
151
+ 6. **The brand word is set once and never leaves.** It is the material (its weight moves, its
152
+ position does not), or it is static beside the system, or it is painted into the base art and
153
+ lifted. Motion happens in, around or behind it.
154
+ 7. **Frame 0 is the poster.** Reduced-motion readers, thumbnails and slow networks show it alone,
155
+ so it is the whole picture: no fade from black, no empty opening.
156
+ 8. **Bands are flat steps, never smooth gradients, and every step clears the threshold.** A 3 px
157
+ leading line with a two-step afterglow (0.10, 0.05) passed; a third 0.03 step drifted and pushed
158
+ the seam from 1.71 to 2.48. A single flat slab encodes well but reads as a box.
159
+ 9. **Exponential tails are slow fades.** `expImpulse` decays below the threshold for half the loop.
160
+ Use the symmetric `cubicPulse` for micro events, and put one across `t = 0` so the keyframe
161
+ reset lands under motion.
162
+ 10. **Small movers over texture are expensive.** Each mote over a painting makes the encoder
163
+ re-send the textured blocks around it; keep motes few and mostly on the plain wings.
164
+ 11. **Lift a painted title instead of laying live text over it.** A luminance-keyed gain (only
165
+ pixels above the plate's level) raises dark painted letters to 4.5:1 and keeps the plate
166
+ black; thresholding the same letters gives the mask. Live text set at a painting's scale came
167
+ out 11 px tall on screen.
168
+ 12. **Spend quality at the seam, not on keyframes.** What is left at the loop point once every
169
+ edge is sharp is requantisation: keyframe 0 and the frames before it carry different error.
170
+ Raise the quality of frame 0 and the last second (`edgeQ`, `edgeFrames`) and keep the default
171
+ keyframes. Periodic keyframes (`-kmin 15 -kmax 16`) spread the snap into visible pops, and a
172
+ small `-kmax` (4–8) made a 2.5–5 Hz shimmer.
173
+ 13. **16 fps for slow painted covers, 20 for a 3D hero, 25 for a system with fast dots.** 20 fps
174
+ cost 18 % more and dropped the median step below 0.0015 on the painted cover. At 16 fps img2webp
175
+ writes 63 ms frames, so an 8 s loop is 8.064 s; that is fine. The gate measures on a 50 ms grid,
176
+ and a smooth 3D turn at 25 fps lands one grid step on two frames at the seam (seamLocal 2.35,
177
+ FLOOR only, while the raw frames were smooth); at 20 fps every grid step is one frame and the
178
+ same page reached TARGET (1.2).
179
+ 14. **A lit 3D object needs a clean shadow and a high `q`.** Shadow acne on a turning object flickers
180
+ and reads as flashes on the sheet: set the key light's `shadow.bias` (about -0.0004) and
181
+ `shadow.normalBias` (about 0.03). Smooth white surfaces blotch in lossy WebP at q86; the 3D hero
182
+ recipe encodes at q94 (edge 97 over 15 frames).
421
183
 
422
- ### Defects and the window re-render
184
+ ## Recipes
423
185
 
424
- What the eye finds goes into the round's `defects`, at most three and worst first:
186
+ Each recipe ships as a worked page in `recipes/<name>/index.html`. Copy it into `cover/`, then
187
+ replace the brand word, the motto and, for the painted recipe, the `ART` block. The pages are
188
+ examples; the rules above are what transfers. Every recipe has a hero and a beat: the treatment
189
+ names them, and look question 9 checks the beat on the stills.
190
+
191
+ - **3D hero (`hero-3d`, the default without a supplied painting).** One product object, lit in a
192
+ small studio, drawn with the vendored three.js on the GPU rung (`depth.md`). Slow: the object turns
193
+ exactly once per loop. Mid: the camera breathes twice. Beat: once per loop the lid opens
194
+ (0.28-0.44 of the loop), a lit core rises and settles back, a ring runs out across the floor, and
195
+ the lid closes (0.62-0.78), so every value is back at its start by `t = 1`. The brand word and the
196
+ motto sit still on the left in a 2D canvas over the GL canvas; the mask pass hides the GL canvas.
197
+ `AIM` is the pixel the object's origin lands on (`setViewOffset`), so the word keeps its side of
198
+ the frame. Replace the `HERO` group with the project's own object (its real logo as a texture or an
199
+ extruded shape is the usual start), keep the turn slow and the open eased, and keep 20 fps
200
+ and q94. On this machine it reaches TARGET (median d 0.0025, moving 1.0, seamLocal 1.2). If the GPU
201
+ is unavailable it renders on the software rung, slower, and the report says so.
202
+
203
+ - **Painted base + travelling light (`painted-light`, the default when the user supplies a painting).**
204
+ A finished painting the user supplied is the whole picture; the page relights it. With no painting,
205
+ `hero-3d` is the default.
206
+ The painting keeps its own coordinates and is scaled, never cropped; at 2:1 a 3:2 painting is
207
+ pillarboxed and the wings stay quiet (a static spill and a few motes). Macro: a light window
208
+ with a 24 px feather walks the dim bays once per loop. Mid: a scan band per bay at two passes per
209
+ loop, offset by the bay's position; one fast skewed glint across the title in **overlay** blend
210
+ (screen brightens a visible box; colour-dodge turned a coloured letter into a red block); a comet
211
+ lapping the hero border. Beat: the eyes breathe twice, the core once, one blink, the accent word
212
+ flares at `t = 0` and `t = 0.5`. A denser, brighter painting needs a deeper dim pool and a
213
+ lower `q` (the repository painting reached TARGET at dim 0.68, q 83, edge 97 over 18 frames).
214
+
215
+ **Choosing the hero.** Any bay can be the hero, so each product's cover can feature its own
216
+ machine on a shared line-up. Three things move together:
217
+ 1. `ART.hero` is the bay index (0 is the leftmost bay). The dim pool is clipped around that bay,
218
+ so a hero in the middle stays at source brightness while the light window still walks every
219
+ other bay as one continuous light. The comet laps the hero's border and its scan band stays
220
+ at full strength.
221
+ 2. `ART.lights` maps a bay index to the light anchors measured on that machine
222
+ (`{ cx, cy, rx, ry, k }` in painting pixels; `k` 0 and 1 are eyes that breathe twice and
223
+ blink, `k` 2 is a core that breathes once). Only the hero's entry glows. A hero with no entry
224
+ stops the page with `ART.lights has no entry for the hero bay N` (the render ends at once
225
+ as `STAGE_CONTRACT_ERROR` with that message), because borrowing another machine's
226
+ coordinates draws its eyes on the wrong body. Measure the anchors, or write `[]` for that bay
227
+ to run with no beat lights and say so in the treatment's beat layer.
228
+ 3. The base art's `checkBox` in `assets.json` points at the hero bay. With the shipped layout
229
+ (painting scaled by `S = 600 / 1024` and pillarboxed 150 px from the left of a 1200 x 600
230
+ page) a bay `[x0, x1]` with panel `top` and `bottom` is
231
+ `[(150 + x0·S) / 1200, top·S / 600, (x1 - x0)·S / 1200, (bottom - top)·S / 600]`. A box left on
232
+ another bay measures a dimmed bay and the ART line fails.
233
+
234
+ The accent flare and the title glint belong to the painted motto and title, not to the hero, and
235
+ stay where they are.
236
+ - **Weight tide (`weight-tide`).** JetBrains Mono rows of the brand word at about 1.3:1 to the
237
+ background drift one word length per loop, alternate rows opposite ways. Weight is
238
+ `gain(swell(fract(t - offset)), 2.4)` with `offset = 0.85·x/W + 0.35·y/H`. The hero word on a
239
+ knockout band takes the same field over 330–800 so it never thins. One accent: a cursor that
240
+ dwells under each letter, steps on with `outBack`, and carriage-returns home.
241
+ - **Orbit loop (`orbit-loop`).** Three rings with integer laps per loop (3, 2, 1), alternating
242
+ directions, dots with fading arc trails. A gate at twelve o'clock flashes on every crossing and
243
+ pulses the dot; the crossing times, computed analytically, light the cells of a ledger under
244
+ the word, as many crossings as cells so the ledger loops. The core breathes once per loop and
245
+ rings on each bar. The word stays static on the left.
246
+ - **Own.** Any system that keeps the rules: one rule many copies, three layers, a still word,
247
+ edges instead of fades. Name it in `recipeReason`.
248
+
249
+ ## Loop kit (`/lit/loop-kit.js`)
250
+
251
+ `LitLoop` holds: `rng(seed)` (mulberry32, layout only); `makeNoise(seed)` and
252
+ `loopNoise(noise, t, offset, radius)` (value noise walked on a circle, so it closes at `t = 1`);
253
+ `ease.smooth`, `ease.outCubic`, `ease.inCubic`, `ease.outExpo`, `ease.outBack(p, s)`,
254
+ `ease.gain(p, k)`; `cubicPulse(c, w, x)` and `expImpulse(x, k)`; `phase(t, offset, cycles)`;
255
+ `cdist(p, c)` (distance around the loop, for an event that straddles `t = 0`);
256
+ `window(p, start, dur)` (a one-shot event inside the loop, -1 outside); `steps(p, stops, travel,
257
+ ease)` (hold and move); `swell(p)` (a cosine swell that dwells at both ends); `TAU`, `clamp`,
258
+ `fract`, `mix`. Every helper is periodic in `t` or pure.
259
+
260
+ ## Encode
261
+
262
+ img2webp, lossy, loop forever, `-m 4`, every frame `-d` = round(1000 / fps) ms, frame 0 and the
263
+ last `edgeFrames` at `edgeQ`, default keyframes. `-m 6` took minutes and gained little; `-mixed`
264
+ changes nothing while every frame is lossy. When img2webp (or dwebp, which the gate decodes with)
265
+ is missing, gifski is the fallback at quality 90. Neither present is exit 21
266
+ `BLOCKED_NO_COVER_ENCODER`. A cover is never an MP4: README renderers do not autoplay video.
267
+
268
+ ## Gate (decoded file)
269
+
270
+ The gate decodes the encoded cover (dwebp per frame, composited as a browser does) and measures on
271
+ a fixed time grid of `max(50 ms, shortest frame)`, because the encoder merges identical frames into
272
+ long ones and frame counts would flatter a slide film. `d` is the mean |ΔY| (luma 0..1, about 300
273
+ px wide) per grid step, and the loop is a ring, so the seam is one more step.
274
+
275
+ | Gate | Metric | FLOOR (fail) | TARGET (cover mode) |
276
+ | --- | --- | --- | --- |
277
+ | G0 determinism | SHA-256 per frame, two captures in fresh browsers | 100 % identical | same |
278
+ | G1 budget | bytes, duration, loop | ≤ 3 MiB, 6–12 s, loop 0 | ≤ 2 MiB |
279
+ | G2 motion energy | median d; share of moving steps | ≥ 0.0004; ≥ 0.45 | ≥ 0.0015; ≥ 0.95 |
280
+ | G3 anti-slide | longest still run; max d / median d | ≤ 2.0 s | ≤ 0.5 s, spike ≤ 6 |
281
+ | G4 seam | seam / mean of the two steps on each side | ≤ 8 | 0.25–2.0 |
282
+ | G5 title contrast | median title pixel vs 90th-percentile background in the box, every frame, through the mask | ≥ 4.5:1 | same |
283
+ | G6 title size | cap height of the title glyphs in the mask, at the README display width (830 px) | ≥ 24 px | same; a title painted into declared base art is INFO |
284
+ | 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 |
285
+ | ART | SSIM of the base art's check box in decoded frame 0 against the source | ≥ 0.90 | same |
286
+ | FLASH | WCAG 2.3.1 flashes per second, looped | ≤ 3 general, ≤ 3 red | same; a FAIL withholds the cover |
287
+
288
+ FLOOR was set so that eight earlier painted covers pass and four slide-like negatives fail; TARGET
289
+ is what cover mode delivers, and those earlier covers miss it on purpose (a 1.9 s hold, a flash at
290
+ the seam). The cover render exits 13 until every gate reaches TARGET. G2 and G3 are area-weighted:
291
+ a small comet on a still picture counts as still at thumbnail scale, which is intended. Never
292
+ raise a number, shorten the loop or drop a layer to pass; fix the cause.
293
+
294
+ G6 measures the mask frames: the white pixels in the title box split into connected glyphs, dots
295
+ and accents (under 1 % of the largest glyph's area or 30 % of the tallest) are left out, and the
296
+ median glyph height of the smallest sample, scaled from the cover width to 830 px, is the cap
297
+ height. A live name plate set at a painting's scale came out about 11 px at that width; contrast
298
+ alone passed it. The seek-order check catches a page that keeps state between frames (a trail drawn
299
+ by never clearing a canvas): the sequential captures agree with each other, a frame sought out of
300
+ order does not. An element whose opacity and transform change together can rasterize one level
301
+ apart depending on which frames were painted before it, so a sought frame within one level per
302
+ channel of the master passes (the report counts them as `oneLevel`); kept state differs by far more.
303
+
304
+ `node "$SKILL_ROOT/scripts/motion.mjs" cover-gate <file> [--frames d --frames2 d --masks d
305
+ --title x,y,w,h] [--strict] [--json]` runs the same gate on any cover file.
306
+
307
+ ## Review
308
+
309
+ Every cover render writes, from the DECODED file:
310
+
311
+ - `stills/sheet.png`: twelve frames at `t = k/12` above a plot of every grid step's `d`, the still
312
+ threshold (red dashes) and the median (green dots). Holds are flat runs on the dashes; encoder
313
+ pops are regular spikes; a reset is a spike at the right end.
314
+ - `stills/poster.png` (frame 0) and `stills/seam.png` (the last frame beside frame 0);
315
+ - `stills/frame-00.png` … `frame-11.png`, the sheet's frames at full size, for a closer look.
316
+
317
+ The gate cannot see damage. The pilot's two worst defects were found only by eye on the sheet: a
318
+ colour-dodge glint that turned a letter into a red block, and a wing glow that read as a dark disc.
319
+
320
+ Answer all nine every round, each naming a frame from the stills set and what you saw there:
321
+
322
+ 1. Is something moving in every half-second window (the plot never lies flat on the dashes)?
323
+ 2. Does the seam disappear in the decoded file (`seam.png`, the right end of the plot)?
324
+ 3. Does it still move after encoding: no region that freezes and then pops?
325
+ 4. Is the brand word present, legible and in place in every frame, never faded or swapped?
326
+ 5. Are all three speed layers visible: a slow perpetual layer, a mid swell, beat events?
327
+ 6. Does anything read as a slide, a card swap, a title fade or an end card, or does light wash in
328
+ place instead of travelling as an edge?
329
+ 7. Is any glyph, glint or glow damaged: a colour block, a dark disc, a visible box?
330
+ 8. Name one thing a skilled motion designer would add or remove, or `none`.
331
+ 9. Does the hero act its beat once per loop, as the treatment's `beat` says, and is it the thing the
332
+ eye follows?
333
+
334
+ A `no` on 1–5 or 9, a `yes` on 6 or 7, or a `named` 8 asks for another round. Record the round with
335
+ `look --out <dir> --round <N> --answers <file>`; the answers file has the film's shape (`viewed`,
336
+ `answers` with `q`, `verdict`, `frame`, `observed`, `aids`) without `weakestBeat`, and round 1
337
+ names the `change` you make before round 2.
338
+
339
+ ## Defects and window re-renders
340
+
341
+ What the eye finds goes into the round as `defects`, at most three, worst first:
425
342
 
426
343
  ```json
427
- "defects": [{ "t": 1.2, "region": [340, 10, 330, 50], "frame": "stills/frame-02.png",
428
- "observed": "<what is visible there>", "cause": "<why it happens>", "fix": "<the change you will make>" }]
344
+ "defects": [{ "t": 1.2, "region": [340, 10, 330, 50], "frame": "stills/frame-02.png", "observed": "<what is visible there>", "cause": "<why>", "fix": "<the change>" }]
429
345
  ```
430
346
 
431
- `t` is the loop time in seconds where the defect shows, inside the loop's length; `region` is
432
- `[x, y, w, h]` in whole cover pixels and on the cover; `frame` is a file of the current stills set that
433
- shows it; `observed` is a real sentence; `cause` and `fix` each say something concrete. `look`
434
- refuses an entry that breaks any of these.
435
-
436
- Check each fix before paying for a full render:
347
+ `t` is the loop time in seconds where the defect shows, `region` the `[x, y, w, h]` it covers in
348
+ cover pixels, `frame` a file of the current stills set that shows it. `look` refuses a defect without
349
+ a time, outside the loop, off the cover, or on a frame that is not in the current stills set.
350
+
351
+ Before the next full render, check each fix locally:
352
+ `motion.mjs cover --out <dir> --round <N> --window <t0>,<t1>` captures only the frames from
353
+ `t0 - 0.5 s` to `t1 + 0.5 s` (wrapping at the seam) and writes
354
+ `windows/round-<N>/<t0>-<t1>/sheet.png` (the span shaded on its plot) and `window.json`. It shows the
355
+ frames before encoding, writes nothing to `stills/`, the report or the manifest, and never counts as
356
+ done: the full render and its gate decide.
357
+
358
+
359
+ ## Rounds and done
360
+
361
+ Rounds share one counter with the renders, 1 to 3. Each round is a full cover render followed by
362
+ a look. Done needs all of: a valid cover treatment; the last render's report reading
363
+ `COVER gate --strict: PASS+TARGET`; at least two look rounds, the first naming its change; the last
364
+ round stamped with the final render's stills and viewing `stills/sheet.png`, `stills/poster.png`
365
+ and `stills/seam.png`, each opened with Read. After round 3, deliver with the open items said
366
+ plainly. A window re-render never counts. The Stop hook checks every item, and when the cover is
367
+ done it asks the reply to label every asset `assets.json` marks as generated.
368
+
369
+ ## Recipe rows and negatives
370
+
371
+ Each recipe keeps its gate row in `recipes/<name>/expected.json` (median d, moving share, longest
372
+ still, spike, seamLocal, bytes, the settings and the treatment it shipped with). `npm run
373
+ qa:cover-recipes` in a LitGravity checkout re-renders every recipe through this renderer and fails
374
+ when median d or the moving share leaves ±15 % of its row, seamLocal leaves TARGET or the file passes
375
+ 2 MiB.
376
+
377
+ Every negative and regression declares the gates it must fail (`mustFail`, as `G2.floor` or
378
+ `G1.target`). `--negatives` renders them all, and one counts as caught only when its render
379
+ completed and gated the decoded file, every declared gate failed, and no undeclared FLOOR gate
380
+ among G1–G4 failed. A crash, a missing declaration or a failure on another gate fails the QA.
381
+
382
+ The painted recipe declares one regression, `feather-150` (`--feather 150` runs it alone): the
383
+ light edge widened from 24 to 150 px. The defect it stands for is light drawn as a soft wash
384
+ instead of a moving edge, but at this recipe's encode (q83, edge q97 for 18 frames) the encoder
385
+ keeps the soft edge, and the motion numbers stay where the recipe's are (moving 1.0, seamLocal
386
+ 1.91–2.01 across six renders, against 1.965). What it reliably trips is the size TARGET (G1:
387
+ 2.50–2.60 MB against 2.06 MB), so `G1.target` is all it declares. A decoded-file edge measure was
388
+ tried and dropped: the share of each step's change carried by pixels that move at least 8 levels
389
+ was 0.501 at 150 px against 0.587–0.660 for this painting at 24 px, but 0.319 for an earlier cover
390
+ of the same painting whose window edge was sharp and whose scan bands were soft. It measures every
391
+ soft change in the frame, not the travelling edge, and any threshold would be fitted to one
392
+ painting. The soft wash is caught by look review on the sheet (question 6 under Review).
393
+
394
+ `recipes/negatives/` ships four slide-like pages that must keep failing on their named gates: a title
395
+ slam with line-by-line text and an end card (G2, G3), card scenes that fade in, hold and fade out
396
+ (G2), a still with a faint breathing glow (G2, G3), and a progress sweep that resets at the seam
397
+ (G4). They are never recipes; read them to see what cover mode exists to prevent, and never tune a
398
+ threshold so one of them passes.
399
+
400
+ ## Commands
437
401
 
438
402
  ```bash
403
+ node "$SKILL_ROOT/scripts/motion.mjs" cover --out <dir> --round <N>
439
404
  node "$SKILL_ROOT/scripts/motion.mjs" cover --out <dir> --round <N> --window <t0>,<t1>
405
+ node "$SKILL_ROOT/scripts/motion.mjs" look --out <dir> --round <N> --answers <file>
406
+ node "$SKILL_ROOT/scripts/motion.mjs" cover-gate <dir>/cover.webp --strict
440
407
  ```
441
408
 
442
- It captures only the frames from `t0 - 0.5 s` to `t1 + 0.5 s` (wrapping across the seam) in a fresh
443
- page and writes `windows/round-<N>/<t0>-<t1>/sheet.png`, with the defect's span shaded on the plot,
444
- and `window.json`. These are frames before encoding. A window render never touches `stills/`, the
445
- cover file, the report or the manifest, and it never counts toward done: the next full render and its
446
- decoded gate decide.
447
-
448
- ## Done
449
-
450
- A cover is done when all of these hold:
451
-
452
- - the treatment is a valid cover treatment and has not changed since the last cover render;
453
- - the last render was a cover render whose report reads `COVER gate --strict: PASS+TARGET`;
454
- - `look.json` has at least two rounds, and the first names its `change`;
455
- - the last round is stamped with the final render's stills and lists `stills/sheet.png`,
456
- `stills/poster.png` and `stills/seam.png` as viewed, each one really opened with `read_file` in this
457
- session;
458
- - the last round asks for no further round, or it is round 3 and its open items go into the reply.
459
-
460
- The LitGravity Stop hook runs this check on the last output folder and holds the turn with the named
461
- reason, at most twice; after that it asks the reply to say plainly that the cover is not done and
462
- why. When the cover is done but an asset is generated or a look item stays open, it holds once so the
463
- reply says so. Rounds share one counter with the renders, 1 to 3.
464
-
465
- ## Not yet confirmed
466
-
467
- - Whether the single keyframe reset at the loop point is visible to a person on a real README page;
468
- the numbers say smooth, and nobody has watched it there.
469
- - How a cover reads inside GitHub's README column at full width; review so far used local frames.
470
- - The encoder step formula comes from libwebp's animation encoder as remembered. Measured behaviour
471
- matches it (q72 drops slow fades, q86 to q90 drops fewer), but the source was not re-read.
472
- - The FLOOR and TARGET numbers come from 8 positives and 4 negatives in one visual family; re-check
473
- them on the first covers made for unrelated projects.
409
+ A cover render runs detached with its log in `<dir>/.run/render.log`; give the call a timeout of at
410
+ least 600000 ms. It writes `cover.webp` (or `cover.gif`), `poster.png`, `stills/`, `manifest.json`
411
+ and `gate-report.txt`. Exit 13 names the gates that miss TARGET; 16 the treatment field; 17 the
412
+ page contract or the asset list; 18 a call that is not a function of `t`, or a frame that differs in
413
+ a fresh browser or when sought out of order;
414
+ 19 a network request; 21 no cover encoder; 22 a listed asset is missing.
415
+
416
+ ## Unconfirmed
417
+
418
+ - Whether the default single keyframe reset is visible to a person on a real README; the numbers
419
+ say smooth, nobody has watched it there yet.
420
+ - How a cover reads inside GitHub's README column at 100 % width; review so far used local frames.
421
+ - The encoder threshold formula comes from libwebp's animation encoder as remembered; measured
422
+ behaviour matches it (q72 drops slow fades, q86–90 drops fewer).
423
+ - The thresholds come from 8 positives and 4 negatives in one family's style; re-check them on
424
+ covers made for other projects.