@machinal/mcp 0.0.0-stage → 0.4.0

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 (173) hide show
  1. package/README.md +361 -2
  2. package/bin/machinal-mcp.mjs +19 -0
  3. package/bin/machinal-stdio.mjs +14 -0
  4. package/package.json +47 -4
  5. package/skills/machinal-cinema/SKILL.md +18 -0
  6. package/skills/machinal-cinema/references/film-library/DIRECTOR.md +149 -0
  7. package/skills/machinal-cinema/references/film-library/LICENSE +21 -0
  8. package/skills/machinal-cinema/references/film-library/MY-STYLES.md +139 -0
  9. package/skills/machinal-cinema/references/film-library/README.md +13 -0
  10. package/skills/machinal-cinema/references/film-library/TECHNIQUE.md +162 -0
  11. package/skills/machinal-cinema/references/film-library/core/lib.js +44 -0
  12. package/skills/machinal-cinema/references/film-library/core/post/crt.js +144 -0
  13. package/skills/machinal-cinema/references/film-library/core/three/post.js +102 -0
  14. package/skills/machinal-cinema/references/film-library/manifest.json +394 -0
  15. package/skills/machinal-cinema/references/film-library/styleboard/catalog.json +1128 -0
  16. package/skills/machinal-cinema/references/film-library/styles/README.md +126 -0
  17. package/skills/machinal-cinema/references/film-library/styles/archive-lighttable/STYLE.md +107 -0
  18. package/skills/machinal-cinema/references/film-library/styles/art-deco/STYLE.md +110 -0
  19. package/skills/machinal-cinema/references/film-library/styles/ascii-crt/STYLE.md +113 -0
  20. package/skills/machinal-cinema/references/film-library/styles/backrooms/STYLE.md +123 -0
  21. package/skills/machinal-cinema/references/film-library/styles/blueprint/STYLE.md +118 -0
  22. package/skills/machinal-cinema/references/film-library/styles/brick-toy/STYLE.md +112 -0
  23. package/skills/machinal-cinema/references/film-library/styles/briefing-board/STYLE.md +120 -0
  24. package/skills/machinal-cinema/references/film-library/styles/caption-news/STYLE.md +135 -0
  25. package/skills/machinal-cinema/references/film-library/styles/cel-anime-80s/STYLE.md +117 -0
  26. package/skills/machinal-cinema/references/film-library/styles/chalkboard/STYLE.md +153 -0
  27. package/skills/machinal-cinema/references/film-library/styles/circuit-board/STYLE.md +149 -0
  28. package/skills/machinal-cinema/references/film-library/styles/city-symphony/STYLE.md +140 -0
  29. package/skills/machinal-cinema/references/film-library/styles/countdown/STYLE.md +130 -0
  30. package/skills/machinal-cinema/references/film-library/styles/crayon-book/STYLE.md +107 -0
  31. package/skills/machinal-cinema/references/film-library/styles/dark-keynote/STYLE.md +115 -0
  32. package/skills/machinal-cinema/references/film-library/styles/data-physical/STYLE.md +117 -0
  33. package/skills/machinal-cinema/references/film-library/styles/dataviz/STYLE.md +121 -0
  34. package/skills/machinal-cinema/references/film-library/styles/desktop-flythrough/STYLE.md +145 -0
  35. package/skills/machinal-cinema/references/film-library/styles/engraving/STYLE.md +121 -0
  36. package/skills/machinal-cinema/references/film-library/styles/game-show/STYLE.md +116 -0
  37. package/skills/machinal-cinema/references/film-library/styles/glass-product/STYLE.md +108 -0
  38. package/skills/machinal-cinema/references/film-library/styles/halftone-dossier/STYLE.md +120 -0
  39. package/skills/machinal-cinema/references/film-library/styles/hd-2d/STYLE.md +109 -0
  40. package/skills/machinal-cinema/references/film-library/styles/hologram-hud/STYLE.md +127 -0
  41. package/skills/machinal-cinema/references/film-library/styles/impasto/STYLE.md +122 -0
  42. package/skills/machinal-cinema/references/film-library/styles/ink-wash/STYLE.md +118 -0
  43. package/skills/machinal-cinema/references/film-library/styles/iso-infographic/STYLE.md +115 -0
  44. package/skills/machinal-cinema/references/film-library/styles/isometric-picture-book/STYLE.md +130 -0
  45. package/skills/machinal-cinema/references/film-library/styles/kino-montage/STYLE.md +149 -0
  46. package/skills/machinal-cinema/references/film-library/styles/lidar-survey/STYLE.md +116 -0
  47. package/skills/machinal-cinema/references/film-library/styles/living-screencast/STYLE.md +122 -0
  48. package/skills/machinal-cinema/references/film-library/styles/lowpoly-island/STYLE.md +110 -0
  49. package/skills/machinal-cinema/references/film-library/styles/memphis-diorama/STYLE.md +142 -0
  50. package/skills/machinal-cinema/references/film-library/styles/microgame/STYLE.md +120 -0
  51. package/skills/machinal-cinema/references/film-library/styles/microscope/STYLE.md +106 -0
  52. package/skills/machinal-cinema/references/film-library/styles/midcentury-toon/STYLE.md +122 -0
  53. package/skills/machinal-cinema/references/film-library/styles/news-package/STYLE.md +156 -0
  54. package/skills/machinal-cinema/references/film-library/styles/newsreel/STYLE.md +134 -0
  55. package/skills/machinal-cinema/references/film-library/styles/one-line/STYLE.md +112 -0
  56. package/skills/machinal-cinema/references/film-library/styles/paper-lantern/STYLE.md +120 -0
  57. package/skills/machinal-cinema/references/film-library/styles/paper-popup/STYLE.md +117 -0
  58. package/skills/machinal-cinema/references/film-library/styles/papercut-red/STYLE.md +108 -0
  59. package/skills/machinal-cinema/references/film-library/styles/pictogram-motion/STYLE.md +119 -0
  60. package/skills/machinal-cinema/references/film-library/styles/pixel-rpg/STYLE.md +115 -0
  61. package/skills/machinal-cinema/references/film-library/styles/printed-long-take/STYLE.md +141 -0
  62. package/skills/machinal-cinema/references/film-library/styles/risograph/STYLE.md +123 -0
  63. package/skills/machinal-cinema/references/film-library/styles/rubber-hose/STYLE.md +110 -0
  64. package/skills/machinal-cinema/references/film-library/styles/satellite-briefing/STYLE.md +114 -0
  65. package/skills/machinal-cinema/references/film-library/styles/scifi-toon/STYLE.md +119 -0
  66. package/skills/machinal-cinema/references/film-library/styles/shadow-puppet/STYLE.md +122 -0
  67. package/skills/machinal-cinema/references/film-library/styles/silent-film/STYLE.md +107 -0
  68. package/skills/machinal-cinema/references/film-library/styles/silkscreen-poster/STYLE.md +138 -0
  69. package/skills/machinal-cinema/references/film-library/styles/spy-titles/STYLE.md +114 -0
  70. package/skills/machinal-cinema/references/film-library/styles/stained-glass/STYLE.md +121 -0
  71. package/skills/machinal-cinema/references/film-library/styles/swiss-motion/STYLE.md +113 -0
  72. package/skills/machinal-cinema/references/film-library/styles/teardown/STYLE.md +125 -0
  73. package/skills/machinal-cinema/references/film-library/styles/telestrator/STYLE.md +135 -0
  74. package/skills/machinal-cinema/references/film-library/styles/tilt-shift/STYLE.md +105 -0
  75. package/skills/machinal-cinema/references/film-library/styles/transit-map/STYLE.md +194 -0
  76. package/skills/machinal-cinema/references/film-library/styles/ukiyoe/STYLE.md +110 -0
  77. package/skills/machinal-cinema/references/film-library/styles/urban-sketch/STYLE.md +124 -0
  78. package/skills/machinal-cinema/references/film-library/styles/visual-investigation/STYLE.md +138 -0
  79. package/skills/machinal-cinema/references/film-library/styles/watercolor/STYLE.md +111 -0
  80. package/skills/machinal-cinema/references/film-library/styles/white-model/STYLE.md +113 -0
  81. package/skills/machinal-cinema/references/film-library/styles/whiteboard/STYLE.md +116 -0
  82. package/skills/machinal-cinema/references/film-library/styles/woodcut/STYLE.md +120 -0
  83. package/skills/machinal-cinema/references/film-library/upstream-skill.md +13 -0
  84. package/skills/machinal-cinema/references/film-styles.json +1322 -0
  85. package/skills/machinal-cinema/references/film-techniques.json +107 -0
  86. package/skills/machinal-cinema/references/workflow.md +58 -0
  87. package/skills/machinal-credits/SKILL.md +24 -0
  88. package/skills/machinal-editing/SKILL.md +43 -0
  89. package/skills/machinal-editing/references/brief.md +98 -0
  90. package/skills/machinal-editing/references/effects.md +58 -0
  91. package/skills/machinal-editing/references/looks-motion.md +37 -0
  92. package/skills/machinal-editing/references/styles.json +15 -0
  93. package/skills/machinal-editing/references/styles.md +16 -0
  94. package/skills/machinal-editing/references/transitions.md +46 -0
  95. package/skills/machinal-editing/references/workflow.md +43 -0
  96. package/skills/machinal-media/SKILL.md +23 -0
  97. package/skills/machinal-media/references/workflow.md +160 -0
  98. package/skills/machinal-recipes/SKILL.md +32 -0
  99. package/skills/machinal-recipes/references/catalog.v1.json +10445 -0
  100. package/skills/machinal-recipes/references/commands.md +45 -0
  101. package/skills/machinal-recipes/references/example.edit.yaml +26 -0
  102. package/skills/machinal-recipes/references/examples/caption-audio.yaml +28 -0
  103. package/skills/machinal-recipes/references/examples/cinematic-sequence.yaml +21 -0
  104. package/skills/machinal-recipes/references/examples/client-scene.yaml +26 -0
  105. package/skills/machinal-recipes/references/examples/generated-media.yaml +25 -0
  106. package/skills/machinal-recipes/references/examples/modify-snapshot.yaml +22 -0
  107. package/skills/machinal-recipes/references/examples/montage-v3.yaml +28 -0
  108. package/skills/machinal-recipes/references/examples/narrated-documentary.yaml +112 -0
  109. package/skills/machinal-recipes/references/examples/narration-timing.yaml +43 -0
  110. package/skills/machinal-recipes/references/examples/scene-edit.yaml +19 -0
  111. package/skills/machinal-recipes/references/examples/scene-generated-image.yaml +36 -0
  112. package/skills/machinal-recipes/references/examples/scene-generation.yaml +35 -0
  113. package/skills/machinal-recipes/references/examples/scene-image-insert.yaml +41 -0
  114. package/skills/machinal-recipes/references/examples/scene-three-explainer.yaml +38 -0
  115. package/skills/machinal-recipes/references/examples/social-hook.yaml +26 -0
  116. package/skills/machinal-recipes/references/examples/tutorial-clean.yaml +19 -0
  117. package/skills/machinal-recipes/references/examples.md +28 -0
  118. package/skills/machinal-recipes/references/jobs-scenes.md +206 -0
  119. package/skills/machinal-recipes/references/text-audio.md +118 -0
  120. package/skills/machinal-recipes/references/yaml.md +72 -0
  121. package/skills/machinal-review/SKILL.md +18 -0
  122. package/skills/machinal-review/references/production.md +146 -0
  123. package/skills/machinal-scenes/SKILL.md +44 -0
  124. package/skills/machinal-scenes/references/authoring.md +97 -0
  125. package/skills/machinal-scenes/references/runtime.md +136 -0
  126. package/skills/machinal-scenes/references/scene-templates/blueprint-mechanism.svelte +62 -0
  127. package/skills/machinal-scenes/references/scene-templates/glitch-handoff.svelte +30 -0
  128. package/skills/machinal-scenes/references/scene-templates/image-reveal.svelte +33 -0
  129. package/skills/machinal-scenes/references/scene-templates/kinetic-type.svelte +38 -0
  130. package/skills/machinal-scenes/references/scene-templates/layered-parallax.svelte +31 -0
  131. package/skills/machinal-scenes/references/scene-templates/lens-assembly-3d.svelte +57 -0
  132. package/skills/machinal-scenes/references/scene-templates/paper-stage-3d.svelte +83 -0
  133. package/skills/machinal-scenes/references/scene-templates/signal-diagram.svelte +43 -0
  134. package/skills/machinal-scenes/references/scene-templates/swiss-grid-motion.svelte +54 -0
  135. package/skills/machinal-scenes/references/scene-templates.json +178 -0
  136. package/skills/machinal-scenes/references/scene-templates.md +50 -0
  137. package/skills/machinal-scenes/references/workflow.md +206 -0
  138. package/skills/machinal-support/SKILL.md +42 -0
  139. package/src/bridge.mjs +285 -0
  140. package/src/cli.mjs +155 -0
  141. package/src/configuration.mjs +148 -0
  142. package/src/connection.mjs +187 -0
  143. package/src/credential-store.mjs +61 -0
  144. package/src/credits.mjs +86 -0
  145. package/src/docker.mjs +93 -0
  146. package/src/download.mjs +90 -0
  147. package/src/errors.mjs +9 -0
  148. package/src/formats.mjs +140 -0
  149. package/src/keys.mjs +127 -0
  150. package/src/launch.mjs +29 -0
  151. package/src/local-setup.mjs +109 -0
  152. package/src/opencode-auth.mjs +246 -0
  153. package/src/opencode-checkpoints.mjs +90 -0
  154. package/src/opencode-configuration.mjs +53 -0
  155. package/src/opencode-media.mjs +139 -0
  156. package/src/opencode-plugin/index.mjs +7 -0
  157. package/src/opencode-plugin/package.json +5 -0
  158. package/src/opencode-recipes.mjs +130 -0
  159. package/src/opencode-routing.mjs +154 -0
  160. package/src/opencode-tools.mjs +30 -0
  161. package/src/opencode-workflow.mjs +32 -0
  162. package/src/presentation.mjs +30 -0
  163. package/src/prompts.mjs +32 -0
  164. package/src/reference-files.json +127 -0
  165. package/src/runtime.mjs +51 -0
  166. package/src/setup-options.mjs +64 -0
  167. package/src/setup-stdio.mjs +114 -0
  168. package/src/setup.mjs +173 -0
  169. package/src/skills.mjs +68 -0
  170. package/src/transfer-http.mjs +109 -0
  171. package/src/version.mjs +3 -0
  172. package/src/windows-key-prompt.mjs +37 -0
  173. package/src/windows-key-prompt.ps1 +77 -0
@@ -0,0 +1,121 @@
1
+ # Data Storytelling — Style Prompt
2
+
3
+ > A chart that tells a story: real data, drawn mark by mark on cream paper by a red–blue pencil, with handwritten notes pinned to the numbers. The chart itself is the camera, the rhythm and the plot.
4
+ > References (grammar only): Hans Rosling's *200 Countries, 200 Years, 4 Minutes* (one dot is a character), Ed Hawkins' warming stripes (a diverging ramp on a reference mean, no axes), The Pudding / NYT scrollytelling (one idea at a time, growing axes, pinned notes). Copy none of their charts, layouts or typefaces; never name them in the film.
5
+
6
+ ## 1. Essence, and what it is not
7
+
8
+ **The chart is the film.** Every mark is a real number and every movement is a meaningful chart operation (a mark lands, an axis grows, the scale changes, a series morphs, a note is pinned). The data is real, openly licensed and traceable. You change the framing, never the numbers.
9
+
10
+ **Pick the chart the data asks for:**
11
+
12
+ | The data is about | Chart |
13
+ |---|---|
14
+ | comparing categories, rankings | bars, a ranked bar race |
15
+ | a relationship between two measures | scatter or bubble chart (one dot can be a character) |
16
+ | place | map, choropleth, dots on a map |
17
+ | parts of a whole, counts of people | unit / waffle chart, proportional squares |
18
+ | before → after | slope or dumbbell chart |
19
+ | a distribution | histogram, beeswarm |
20
+ | where things go | flow / Sankey |
21
+ | change over time | line or dot series, stripes, area |
22
+
23
+ Three layers make it a story, not an infographic: **a human scale** (handwritten notes pinned to marks), **a performer** (a physical pencil that draws every mark), and **sonification** (each mark is a pitch; the trend is heard before it is read).
24
+
25
+ Not a dashboard (one idea at a time), not a keynote with charts (no slides), never decoration.
26
+
27
+ ## 2. Materials & rendering
28
+
29
+ - **Paper**: warm cream, fixed-seed fibre noise and a faint dot grid in world space. **Ink**: dark warm ink for axes and series, pale warm grey for grid and zero line, IBM Plex Mono ticks.
30
+ - **Marks**: data dots carry a thin ink ring so pale values stay visible on cream. A mark lands with a short pop and a thin ripple; suppress ripples when marks arrive closer than ~0.1 s.
31
+ - **Handwriting** (Caveat) in pencil, per-glyph jitter, graphite grain, written on as the tip dances over the x-height. Leaders are wobbly curves ending in an **un-closed** ring around the mark.
32
+ - **The red–blue pencil**: hex body, blue half / red half, sharpened wood cone. Only the tip end shows, from the lower right; its shadow drifts farther and softer with lift; sharp tip, soft body.
33
+ - **Layout**: a plot box fixed in world space, a **memory zone** for early notes, every note pinned in **data space** (value + pixel offset) so rescales keep the layout, a bottom band for the caption.
34
+
35
+ ## 3. Colour logic
36
+
37
+ - Colour encodes **one thing: the value**. Diverging data uses a ramp (ColorBrewer RdBu family) centred on the mean of a meaningful reference period, with a symmetric span; data with no natural centre uses one sequential ramp. Everything else is ink on cream.
38
+ - **Honesty beats drama**: pale values stay pale; never stretch a ramp to make a change look bigger.
39
+ - The two pencil leads have meanings: **blue for memories and human notes, red for records and warnings**. A change of lead marks a turn.
40
+ - One `accent` colour may bypass the ramp for a mark that is not data (a logo, a highlight).
41
+
42
+ ## 4. Type & subtitles
43
+
44
+ - **The subtitle is the figure caption**: a text serif (Newsreader), ink colour, left-aligned with the chart, ≤ 2 lines, with a hairline rule above it and a small mono kicker for the range drawn so far. Words appear on their whisper timestamps over a paper-colour band. Hold ≥ max(1.8 s, speech + 0.6 s).
45
+ - The title is the **chart's own headline** (Newsreader), set in world space above the plot; it fades when the camera is close and returns with the full view.
46
+ - No captions over a signature chart operation or a silence.
47
+
48
+ ## 5. Motion quality
49
+
50
+ - **The rhythm of the data is the rhythm of the film.** Map the marks to a musical grid; to accelerate, one option is to **divide the beat instead of changing tempo**. Pick a tempo whose finest subdivision lands on whole frames (at 24 fps a minute has 1440 frames; the count of finest notes per minute must divide it), so picture and sound never drift.
51
+ - **Pencil acting**: lift before each tap, land with the shadow meeting the tip, a tiny rebound; hurry as data densifies, tremble like a seismograph needle at a peak. It can **flinch** (recoil and freeze), **hesitate** (hover before a mark) and **exit** (hand the story to the viewer).
52
+ - **Rescale** reads as ratchet clicks (stepped, each step eased); a calm rescale is smooth.
53
+ - **Morph**: a staggered sweep, each mark easing into its new form; notes fade as it passes and return as tiny marks.
54
+ - **No fades to blank or dissolves.** Transitions are chart operations: axis growth, pull-backs, rescales, morphs, a cell widening into the next frame.
55
+
56
+ ## 6. Camera grammar
57
+
58
+ A 2D camera `{x, y, zoom, roll}` over **one sheet of paper**. A film is one take; a hard cut is rare and meaningful. The moves below are a vocabulary, not a route. Opening and ending come from the topic.
59
+
60
+ | Move | Expresses | Can serve |
61
+ |---|---|---|
62
+ | Extreme close-up on one mark, following its leader | One fact, one life | a single case; a named person |
63
+ | Full view first, then dive to one mark | The pattern before the case | a familiar trend; a myth to correct |
64
+ | Pull back as axes grow out of the marks | The frame arrives with the unit | naming the measure; widening a claim |
65
+ | Track the pencil, newest mark at ~60 % of width | Progress: the past behind, the future ahead | a series in time; a race; a queue |
66
+ | Pedestal with rising data, a Dutch angle creeping in | Escalation, unease | runaway growth; a debt |
67
+ | Punch-in over 2 frames, decaying shake, jolt on rescale | Surprise, a broken frame | an outlier; a crash |
68
+ | Fast pull-out, roll, small constant tremor | A rush | a boom; a cascade; a panic |
69
+ | Locked-off | The transformation is the movement | a morph; a slow reading |
70
+ | Hold on one mark, then pull back | The part inside the whole | a verdict; context |
71
+ | Pull and pan to add more real data | Scale switch | a longer record; the rest of the list |
72
+ | Lateral pan across notes in the memory zone | Recollection | a biography; a timeline of events |
73
+
74
+ Framing: subjects fill ≥ 1/3 of frame height at key moments. When the real axis scrolls off-screen, pin its tick labels to a paper strip at the frame edge (frozen pane).
75
+
76
+ ## 7. Sound palette
77
+
78
+ - **Ambience** follows the places the notes evoke (J-cuts in, L-cuts out). **Foley** is graphite, paper and wood: tick-and-paper taps, scratches for handwriting, a ruler hiss for axes, a paper puncture for a broken frame, a wooden click for the pencil flip, ratchet teeth for a rescale, a paper sweep for a morph.
79
+ - **Sonification** is the music: pitch = value, rhythm = time density. Low values snap to a pentatonic scale, middle ones to semitones, extreme ones unquantized, with detune growing away from the reference. Timbre: a **low-pass-gate "plonk"** (sine + FM whose index rises with the value: wood → metal). Dense passages: quieter notes, decay ≤ 1.5 × the gap.
80
+ - **Bed**: detuned-saw pad, soft kick, noise shaker, low-passed hats, sine sub, sample-and-hold blips, drones; harmony can darken or brighten with the data.
81
+ - **Silence** is a tool: true digital silence (all layers) where the data should be heard alone, before a key mark, a morph or a verdict; the first sound after it matters most.
82
+ - **Mix**: compressed calm, neutral narration, music ducked ~−11 dB, foley light except key taps; −14 LUFS, no grain. The voice never talks over a rush, a silence or a morph.
83
+
84
+ ## 8. Native moves
85
+
86
+ A menu: use the ones your story needs.
87
+
88
+ - **One mark = one fact.** *Fits content like:* the first store a chain opened; the first patient of a trial; the first satellite launched.
89
+ - **Axes grow with the story.** The y axis arrives when the narration first names the unit. *Fits content like:* revenue; a city's population; vaccination rates.
90
+ - **Pinned annotations.** Their content and colour carry the arc. *Fits content like:* an athlete's season; a family's migrations; releases on a usage curve.
91
+ - **Breaking the frame.** The chart must make room; the torn edge stays as a scar. *Fits content like:* a viral spike; a price bubble; a record-breaking flood.
92
+ - **Encoding morph.** Bars into a waffle, a map into a ranking, a line into a slope: the reveal of the whole. *Fits content like:* a budget as units of people; countries as a ranking; daily steps as a year strip.
93
+ - **Scale switch.** One value → the series → a longer real record, never extrapolated. *Fits content like:* one day's energy use → a year; one species count → a region.
94
+ - **The empty next cell.** A dashed slot for the value nobody knows yet. *Fits content like:* next year's election; the next launch; tomorrow's reading.
95
+
96
+ ## 9. Pitfalls of the medium
97
+
98
+ - Select data columns by header name, never by index; print every fact the narration claims.
99
+ - Notes collide with later data → data-space pins, a memory zone.
100
+ - A frame break rescaled too fast is invisible → hold the pierced state ≥ half a beat.
101
+ - Right-aligned notes are still written left to right → the pencil hops to the first letter.
102
+ - Helpers that set `globalAlpha` must multiply the incoming alpha, or fades skip them.
103
+ - Tails leak across a hard silence → render before/after in separate buffers; verify on decoded samples.
104
+ - In dense passages the pencil body lies across fresh marks → steepen its angle.
105
+ - Synthesized human sounds (a laugh) are uncanny → use a soft non-human sound.
106
+
107
+ ## 10. Engine
108
+
109
+ `demo/engine.js` (Canvas 2D, world units = chart pixels at zoom 1) is the style: paper, camera, value ramps, `pencilStroke` (any polyline in pencil), `inkShape` (any closed shape: bars, areas, map shapes), `plotShape`, `handText`, `dataDot`, `morphMark`, annotation geometry, `drawPencil`, `caption`. `demo/music/score.py` holds the sonification. The function table and a minimal example are in [DEMO.md](DEMO.md#engine-reference).
110
+
111
+ ## 11. Variation space
112
+
113
+ You decide the dataset, the chart, the human scale, the notes, the opening, the ending, the camera path, the pacing and the silences. All far from our demo:
114
+
115
+ - Structures: **a ranked race** (bars climb and overtake; one bar is the character; a newcomer breaks the frame from below); **a map that becomes a count** (dots gather on a map as events happen, then fall into a unit chart of people in one morph); **before → after dialogue** (two years face each other as a slope chart; one line left unfinished).
116
+ - Openings: **the finished chart** (the whole pattern is already drawn; the film works backwards); **the object before the axis** (a pencil drawing of the thing measured, a ticket, a shoe, becomes the first mark); **the question first** (an empty plot with only the unit and a handwritten question; the pencil hovers).
117
+ - Endings: **one mark, close** (end on a single value and its note, never the full view); **back to the object** (the chart folds into a drawing of the thing it measured); **the headline revised** (the pencil strikes a word of the title and writes the true one).
118
+
119
+ ---
120
+
121
+ How our demo was made (story, shots, score, end card, build): [DEMO.md](DEMO.md). Read it after your treatment exists.
@@ -0,0 +1,145 @@
1
+ # Desktop Flythrough 桌面穿梭 — Style Prompt
2
+
3
+ > App screens and tools lie on a sunlit desk as printed paper cards; small pixel characters, popped up into voxel toys, carry the work from card to card, while one unbroken camera flies after them, whips between stops and finally pulls back over the whole desk.
4
+ > References (grammar only): one-take desktop tours in software launch films (windows laid flat as places, a small helper as the guide); macro toy photography (low warm sun, long soft shadows); pixel-art sprites (the cast's look). Never copy their characters, layouts, icons or music.
5
+
6
+ ## 1. Essence, and what it is not
7
+
8
+ - **The desk is the world.** A matte paper mat with a regular dot grid lies on a light wooden desk, lit by one low warm sun through a window. Everything sits on it and casts a long, soft shadow. A few everyday desk things (a pen, sticky notes, a mug, earbuds) sit around the edges as foreground and background layers.
9
+ - **Interfaces are paper cards.** Phones, tools and dashboards are rounded slabs a few millimetres thick with the interface printed on top. They are places: characters stand and hop on them, and parts of the interface rise out of them as small 3D objects.
10
+ - **The cast are pixel sprites made solid.** One bevelled cube per pixel, thicker inside than at the edge, eyes standing proud. They lie on a card as flat stickers and pop up into toys; they blink, wait on the beat, get squashed and spring back.
11
+ - **Every stop is busy.** At each station something small moves besides the main action: debris bursts, data cubes hop, a lamp blinks, marks vibrate.
12
+ - **One take.** No cuts. The camera glides, orbits, cranes and whips between stops; it closes on the whole desk.
13
+ - **Everything lands on the beat.** Hops, pops, ticks and slams sit on the 16th-note grid of one steady tempo, and every action has a sound.
14
+
15
+ Not a screen recording (no cursor, no glowing monitor, no real app chrome or logos); not a brick or clay toy film (pixel voxels on printed paper); not an isometric infographic (perspective camera, real light); not flat motion graphics (everything has thickness and a shadow).
16
+
17
+ ## 2. Materials & rendering
18
+
19
+ - three.js, physically based, neutral tone mapping. Scale: a card is 0.3–0.7 units wide (1000 canvas px per unit); dots 0.03 apart. A character must be big enough to show its eyes: in the demo about 1/5–1/3 of the card it stands on (0.006–0.0075 units per pixel, so a 16-pixel sprite is about 0.1 wide); smaller casts lose their faces in a medium shot. A character may be scaled for a moment (`scale`) when the story needs it; it reads best on a beat, with a pop's overshoot.
20
+ - **Light**: one directional sun low from the back-left (about 20° up, so a toy's shadow is two or three times its height), a 4096 soft shadow map that follows the camera target and resizes with distance; a cool-sky / warm-ground hemisphere fill, so shadows read blue and lit faces warm; a faint room environment for highlights; exponential fog thinned as the camera pulls back.
21
+ - **Desk**: a dotted paper mat (a thin rounded slab whose size is a multiple of two dot spacings, so the printed dots line up with any 3D dots) on a procedural light-oak plane (planks, long soft grain). Soft window-light patches (blurred four-pane shapes, warm, additive, low opacity) lie under the cards. Props are plain primitives in matte or satin materials, placed so each close shot has something soft in front of or behind its subject.
22
+ - **Cards and screens**: a rounded slab plus a canvas texture on top with a faint deterministic grain. Print is flat: one ink, mono labels in spaced caps, bold numerals, thin rules; a card head carries two lines (English mono caps over the other language in bold). A phone is a card with a dark bezel and a whole interface of whatever app the story needs: a status bar, a header that names the screen, content filling the screen, controls at the bottom. Redraw a canvas only when its state changes; quantise continuous changes.
23
+ - **Voxel cast**: instanced bevelled cubes per pixel; depth grows with distance from the silhouette; pure-black pixels are eyes, which protrude and blink (they take the colour of the pixel above). Rig: root (feet, yaw) → hinge (lying flat ↔ standing) → squash (scaled at the feet) → spin. State: `e` (0 flat sticker … 1 full toy), `hinge`, `sq`. The same picture at half resolution is the same character, smaller and chunkier.
24
+ - **Props**: the same voxel recipe (crosses, ticks, bells) or plain rounded primitives (bricks, presses, drawers, towers, tent cards, stamps). Data that rises out of a card is extruded from its printed shape, so it still reads from above.
25
+ - **Impact ring**: a thin accent-coloured ring spreads over the paper from an impact and fades in about a second.
26
+ - **Post, per frame**: 16–24 sub-frames with Halton sub-pixel jitter (anti-aliasing, and a little motion blur on fast moves) → depth of field on each sub-frame, behind the focus plane only → bloom on highlights only → grade (light vignette, slight warmth, a little contrast and saturation). Subtitles are DOM on top.
27
+
28
+ ## 3. Colour logic
29
+
30
+ - **One light ground** (the mat) with a slightly darker dot, cool-tinted so the warm sun leaves it fresh; a warm wooden desk around it; cards in a near-white of the same temperature; **one dark ink** for print; **one accent reserved for what matters now**: the route, the current step's badge, the send button, the lit window, the key word.
31
+ - Two or three support hues for the cast and props, mid-saturated, never neon; one warm cast colour against the cool ground. **Red only for failure or trouble** (an error, a weak signal), **green only for success**; data in motion may take one bright support hue so it reads apart from the route.
32
+ - Judge the rendered frame: avoid grey on grey; keep the vignette light and the shadows tinted by the sky fill.
33
+ - Brand use: the brand colour becomes the accent; the brand's interface colours print on the cards; the ground stays light.
34
+ - Two example palettes besides the demo's (starting points, not a menu; the names are the keys of `COL` in `src/cards.js`):
35
+ - *Lilac and violet* (creative tools, music, learning): paper `#e7e4f3`, dot `#cbc5e2`, card `#fcfbff`, ink `#1d1a2e`, mute `#807a96`, line `#e2dfee`, accent `#6b4ce6`; support apricot `#f39a5b`, sky `#5fb4e8`, lemon `#f2c94c`; red `#e2483d`, green `#3fa57a`; haze `#e8e4e6`.
36
+ - *Cool grey and amber* (money, logistics, energy, food): paper `#e5e9ed`, dot `#c8cfd7`, card `#fdfdfc`, ink `#20252b`, mute `#7f8790`, line `#e0e4e8`, accent `#e8890c`; support teal-blue `#2f8fb0`, plum `#8a5a9e`, cream `#f4e3b5`; red `#d23a3a` (keep it clearly apart from the amber), green `#3c9c6e`; haze `#e6e4e1`.
37
+
38
+ ## 4. Type & subtitles
39
+
40
+ - **In the world, only keywords and numbers**: step badges (a camera-facing accent pill with a digit and one word), sizes, a name on a screen, a banner, a title card. Text meant to be read is framed above the subtitle area, held still for its reading time, and large enough at the angle it is seen: flat print reads from 55–70° down; a low camera reads a standing tent card.
41
+ - **Titles are objects on the desk**: an opening tent card beside the first stop; at the end a large paper card dropped onto open desk in the final frame. Where depends on the layout: wherever it covers no station, route or character and sits clear of the subtitle bar (the demo's stops leave the middle free; a zigzag layout may leave the front edge). Leave that space when laying out the desk.
42
+ - Every face on screen comes from the film's own font files (cards, pills, subtitles); the mono stack falls back to the film's CJK face, never to a system face.
43
+ - Three roles: a mono for labels and numbers (spaced caps), a sans with a heavy weight for pills, titles and subtitles, and a CJK (or other script) face both fall back to. The families are free (e.g. DM Mono or JetBrains Mono, Manrope or Space Grotesk, the Noto Sans of the film's language); the roles are not. Pixels belong to the cast, so no pixel font on the print.
44
+
45
+ ### Voice-over and subtitles
46
+
47
+ - When the film explains something, a voice tells it: short spoken lines, one idea each; the picture shows what the voice is saying at that moment, and the words on cards are only the keywords of the line.
48
+ - **One subtitle cue per spoken line**, in a quiet bar at the bottom centre (a rounded ink box at about 72 % opacity, about 64 px above the frame edge): the spoken language on the first line (bold, about 40 px), a whole-sentence translation on the second (about 26 px). One language per line, never wrapped. The cue appears with the line and leaves with it.
49
+ - The camera keeps its subject about 110 px above centre (a fixed vertical view offset), so nothing that matters sits under the bar.
50
+ - A version voiced in another language starts each line on the same second, so picture, subtitles and timing do not change.
51
+
52
+ ## 5. Motion quality
53
+
54
+ - 30 fps. One steady tempo (110–130 BPM); every action on the 16th grid, big moments on downbeats.
55
+ - **Hops**: an arc with squash and stretch (stretch about 14 % in the air, squash about 30 % for 0.2 s on landing, a small anticipation squash before take-off). Groups move follow-the-leader, each a 16th behind the one ahead, so they never close up.
56
+ - **Characters act**: they blink every couple of seconds, bounce on the beat while they wait, squint when they are squashed, lean towards what they look at.
57
+ - **Pop**: sticker → toy in 0.25–0.5 s (hinge up with overshoot, cells extrude from the centre, a small jump, squash on landing). **Reverse pop**: toy → sticker or print when it is stored, delivered or taped down.
58
+ - **Slam**: drops from above with ease-in, lands on a downbeat, squashes, jolts the card, sends out a ring.
59
+ - **UI comes alive in sequence**: digits, bars, ticks, typed characters appear on 16ths with an overshooting ease.
60
+ - Idle is a small bounce or a blink, never a dead hold of more than about 1.5 s. Paper and cards never move except for a jolt or a curtain-call hop.
61
+
62
+ ## 6. Camera grammar
63
+
64
+ | Move | What it expresses | Can serve |
65
+ |---|---|---|
66
+ | Macro glide with a slow orbit (close, 20–45° down) | being there, small scale | a character at work; one detail of an interface; a title standing on the desk |
67
+ | Whip from card to card (0.3–0.5 s, banking into the turn) | the next step, cause → effect | a process moving on; a hand-off between tools |
68
+ | Rise to near top-down (55–70° down) | reading, one card as a whole | a screen, a counter, a table; any verdict |
69
+ | Ride along, low behind the subject | travel, momentum, pursuit | a route; a delivery; a download |
70
+ | Pull back over the desk | the whole system, scale | a recap; the route so far; many stations at once |
71
+ | Hold with a shake | impact | a press, a stamp, a ring |
72
+
73
+ - One take, no cuts, no dissolves. Targets are live subjects; between keys the target follows a Hermite path with live end points; drift is a breath, not a handheld wobble.
74
+ - At a key where a whip starts, the target rests first (or the camera stutters). A character's take-off is the natural start of a whip. A whip between far-apart stops arcs up mid-way so the stops in between stay in frame.
75
+ - Wide shots frame the stations to fill at least 70 % of the frame width. **The film closes on the whole desk**: every stop and the route in one frame, everything moving once, the title landing in open space.
76
+
77
+ ## 7. Sound palette
78
+
79
+ - **Score**: bright and warm, acoustic in feel: marimba (with vibraphone under long notes), plucked bass, a soft synthetic kick (a short sine sweep), claps, shaker, a quiet string pad. One key, diatonic chords, about one chord per bar. Under a voice the score is a light bed ducked about 16 dB while someone speaks; the full mallet theme plays where nobody speaks.
80
+ - **Foley**: every action has a sound. Pop: a marimba note from the current chord plus an upward sweep. Hop: a soft tick. Landing: a felt thump. Press or stamp: a low thump with a crumble. Typing: dry key clicks. Ding: two bell notes from the chord. Camera whip: a whoosh sized by the measured camera speed. Pitched foley takes its notes from the score's chord table and sits on the 16th grid.
81
+ - **Mix**: the voice leads (about −16 LUFS before delivery, −14 after); music 15–18 dB under the voice and lifted in the gaps; foley under the voice; the mix peaks under −1.5 dBFS and `mux.sh` masters it to −14 LUFS, true peak −1.2 dBTP. The final chord holds to the last half-second.
82
+
83
+ ## 8. Native moves
84
+
85
+ - **Sticker pop.** A flat pixel sticker on a card stands up and extrudes into a toy on a 16th. *Fits content like:* a new user, file or job appearing; a feature switched on; an order placed.
86
+ - **Reverse pop.** A toy lies back down into a sticker or a print. *Fits content like:* a photo delivered into a chat; a snapshot saved; a task archived.
87
+ - **Press.** A heavy plate drops on a toy; pixel debris bursts out and rolls away; the same character pops out at half resolution beside a counter that runs down. *Fits content like:* compression; a budget cut; a summary of a long report.
88
+ - **Drawer.** A slab of a stacked tower slides open, a toy hops in, it closes and one window lights; small data cubes hop into the windows. *Fits content like:* storing something in the cloud; a queue; an archive.
89
+ - **Messenger.** A small voxel object (a bell, an envelope) flies an arc between two cards leaving a dotted trail, taps the target twice, and a banner drops on its screen. *Fits content like:* a notification; a hand-off; an alert.
90
+ - **Data run.** A stream of small bright cubes runs along the route between two stations. *Fits content like:* a download; a sync; a payment going through.
91
+ - **Blurry, then sharp.** A picture on a screen card is printed blurred, then snaps sharp as the toy lands in it. *Fits content like:* loading; focus; a draft becoming final.
92
+ - **UI rises.** Part of the printed interface grows into 3D out of its printed shape. *Fits content like:* progress; a metric climbing; a step badge.
93
+ - **Curtain call.** The closing pull-back frames every stop; each hops once, left to right, the characters pop back up, and a title card drops into open space. *Fits content like:* a recap; a team; a pipeline shown whole.
94
+
95
+ ## 9. Pitfalls of the medium
96
+
97
+ - **Softness**: depth of field and motion blur easily turn a subject or its words to mush. Blur only what lies behind a focus plane set a little beyond the subject, lightly (≤ 5 px), never anything in front; let the shutter shrink with camera speed so a streak never exceeds about 8 px; draw card and screen canvases at 3–3.4× (pills at 3×) so print stays crisp when a card fills the frame; no CSS or canvas blur on anything meant to be read.
98
+ - **Flat print read at a low angle**: text on a card seen from 20° is unreadable. Rise to 55–70° to read a card; put text the low camera must read on a standing object.
99
+ - **A standing toy hides the row behind it**: place characters beside or behind the text being read, or off the card, and check every reading frame for overlap.
100
+ - **Text under the subtitle bar or cut at the frame edge**: keep the fixed vertical offset; show name plates and labels only in the shots that frame them whole; take camera-facing pills away before the camera moves on.
101
+ - **Screens that read as blank**: a phone card without a whole interface reads as an empty white slab in close-up.
102
+ - **Shadows of floating labels**: with the sun at 20°, a pill a few centimetres up throws a long shadow across the card and greys out its print. Labels and pills cast no shadow (`pill()` turns it on: set `castShadow = false`); a real floating object (a bell) may, but no shadow falls across text being read.
103
+ - **Characters lost in the wide**: on screen a character is about `width × 1080 / (2 · dist · tan(fov / 2))` px wide. In the closing wide view keep every character at least about 35 px wide (the demo's smallest is about 37 px); otherwise frame closer, bring it forward, or scale it up for the curtain call.
104
+ - **Voxels seen edge-on**: a standing sprite seen from far to the side reads as stripes and its eyes vanish; turn it towards the camera (`yaw`) for its key moments, and give a large picture-like sprite a thinner `depthK` (0.6–0.9).
105
+ - **Whips over bare paper**: a fast move between far-apart cards crosses empty desk; arc it up so the stops in between pass through frame.
106
+ - **Dead stations**: a stop where only the main action happens looks static; give it one or two small moving things that do not compete with what the voice says.
107
+ - **Bars and ticks seen from above**: upright 3D bars and standing checkmarks turn into blobs in a top-down view; extrude them along the card or lay them flat.
108
+ - **Interpenetration**: characters at the same depth overlap; followers move one 16th apart; a knocked-flat pile goes back to sticker thickness before it stacks; check props against card edges, gates and drawers.
109
+ - **Ripples as pegs**: lifted 3D dots read as pegs from above; use a flat expanding ring.
110
+ - **Slow renders**: canvas redraws on every sub-frame; redraw on state change only.
111
+ - **A score made of fragments**: write whole phrases and put the accents on top.
112
+
113
+ ## 10. Engine
114
+
115
+ In `demo/` (three.js r170 + Canvas 2D). Copy the folder into the project; the engine files work as they are, the film is yours to write.
116
+
117
+ - **Use as is**: `world.js`, `cards.js` (change only `COL`), `voxel.js`, `anim.js`, `camera.js`, `post.js`, `main.js`, `captions.js`, `tools/`.
118
+ - **Write your own**: `src/film.js` (cards, props, cast, timeline, events, reading boxes), `src/shots.js` (camera keys), `audio/vo_timeline.py` (its English lines, gaps and length are the demo's), `audio/compose.py` (score); adapt `audio/foley.py` (event types) and `index.html` (title, fonts; empty `#credit`, which holds the library's sign-off).
119
+
120
+ Conventions:
121
+
122
+ - **Space**: 1 unit = 1000 canvas px; the mat's top is y = 0; a card's top is at its thickness. Card print reads upright from the +z side (camera `az` 0): the canvas top points to −z.
123
+ - `world.js`: `makeWorld({ mat: [w, h], haze })` (mat sizes multiples of 0.06) → `{ renderer, scene, camera, sun, SUNDIR, tex }`. `card(world, canvas, w, h, thick)` → a group centred on the card, `userData.redraw()` after you redraw its canvas. `pill(world, text, { bg, fg, h, size, font, wt })` → a mesh; call `.face(camera)` every frame; it casts a shadow unless you turn it off. `rbox(w, h, d, r)` rounded box geometry. `dotPatch()` (lifted dots) is superseded by the flat ring (§9).
124
+ - `cards.js`: `COL` is the whole film's palette (the mat, dots and route read it too); `MONO`, `SANS`, `CJK` are font stacks named in `index.html`'s `@font-face`; `canvas(w, h, scale)` (draw cards at 3–3.4), `txt`, `tag`, `cardBase(c, w, h, en, other)`, `grain`, `tick`, `cross`.
125
+ - `voxel.js`: `makeMonster({ w, h, cells: [[i, j, '#hex']] }, cell, name, depthK)`; `j = 0` is the top row; pure black cells are eyes. The root sits at the centre of the feet; at `hinge = 0` the sprite lies face up on the paper with its head towards −z (so it reads as print). `set({ pos, yaw, e, hinge, sq, tiltX, tiltZ, spinX, spinZ, scale, vis })` defaults to a standing toy (`e = 1, hinge = 1`), so pass both for a sticker; `pos` is the feet. Also `.width`, `.height`, `.blink(on)`.
126
+ - `anim.js`: `BEAT` and `BAR` are fixed at 120 BPM; change them for another tempo. `hops(t, list, rest)`: `list` in time order, each `{ t0, t1, from, to, h }` starting where the last ended; returns `{ pos, air, dir, lands, takeoffs }`, and `squash(t, lands, takeoffs, air)` turns that into `sq`. `pop(t, t0, dur, jump)` and `beatBounce(t, t0, t1, amp)` return offsets: add their `y` to `pos.y`, multiply their `sq` into yours.
127
+ - `camera.js`: `makeRig(ctx, camera, KEYS, SHAKES)`; a key is `[t, target, dist, az, el, fov, offset?, { ease: 1 }?]`, the target a `Vector3` or the name of a live subject `ctx.subj[name](t) → Vector3`; `ease` makes the target rest there (put it where a whip starts). Shakes are `[t, amplitude, decay]`.
128
+ - `main.js` expects `film.js` to export `DUR`, `MAT`, `GLYPHS` (characters to preload), `VO`, `END` (`{ credit }`, past `DUR` when there is no sign-off) and `build(ctx)` → `update(t)`. `build` fills `ctx.subj`, pushes sound events `{ t, type, … }` into `ctx.ev`, sets `ctx.fx = { flash }` and `ctx.read = [[id, text, t0, t1, () => corners]]` (the world points of each text meant to be read, reported through `TEXTS`). It also defines `window.DBG(t)`, which `tools/camspeed.mjs` reads. `?n=` sets the sub-frames, `?nosub=1` hides subtitles.
129
+ - `captions.js`: cues from `VO` (`{ t0, t1, zh, en }`: `zh` is the spoken line, whatever the language).
130
+
131
+ Build order (the demo's `build.sh` is the template): fonts → voice (`core/tts`, checked) → `vo_timeline.py` (writes `src/vo.js`, `vo/timeline.json`) → `tools/subset.py` (it reads `src/*.js`, so run it after the subtitles exist) → `core/render/events.mjs` → `LIB=<library> node tools/camspeed.mjs` → `compose.py` (also writes `music/harmony.json`; `foley.py` reads one chord per 2 s bar) → `foley.py` → `mix.py` → `core/render/video.mjs` → `mux.sh` → `readcheck.mjs`; the `.srt` from `vo/timeline.json` with `core/render/srt.py`. Outside `styles/` the scripts' guess of the library root is one level off: export `LIB` and point `compose.py` at it.
132
+
133
+ Minimal start: a to-do card and a calendar card; a ticket sticker pops on beat 1, blinks, hops to the calendar on beat 3 while the camera whips after it, and drops into a day as a printed tag.
134
+
135
+ ## 11. Variation space
136
+
137
+ The agent decides for each film: which apps or tools the cards are and how they lie on the desk, the cast (a mascot drawn as pixel art), the route, the props at each stop, the palette within §3, the tempo within §5, the language of the voice.
138
+
139
+ - **Structures**: one item travels card to card and changes at each stop; the same job on two halves of the desk, slow against fast; one tiny detail that grows out to a desk of many cards.
140
+ - **Openings**: a terminal types a command and its cursor becomes a character; the camera falls onto the desk and lands on beat 1; a title tent stands beside the first card while the hero pops up.
141
+ - **Endings**: the curtain call over the whole desk; the cast reverse-pops into a saved record; the camera rises until the cards become part of the dot pattern.
142
+
143
+ ---
144
+
145
+ How our demo was made (story, shots, voice, score, build): [DEMO.md](DEMO.md). Read it after your treatment exists.
@@ -0,0 +1,121 @@
1
+ # Copperplate Engraving — Style Prompt
2
+
3
+ > An intaglio plate that engraves itself: a burin cuts swelling lines into copper, a proof is pulled, and the figure builds up — outline, hatching, cross-hatching — until engraved lettering, magnified details and a hand-laid wash make a finished plate.
4
+ > References (grammar only): 19th-century natural-history plates — Haeckel, Audubon, Westwood, the *Britannica* copperplates (centred subject, numbered roundels, roman title over an italic name, "del." / "sculp." credits, the plate mark); Hogarth and Doré for the burin line (hatching that follows the form, crossing only in half-tones); hand-coloured plates for washes laid after printing. Never copy a plate, pose, border or title.
5
+
6
+ ## 1. Essence, and what it is not
7
+
8
+ An **intaglio print**: the line is ink held in a groove a burin cut into copper. Three rules:
9
+
10
+ 1. **Tone is made of lines, never of fills.** Light is bare paper; half-tone is one family of parallel lines; shadow a second family crossing it; the deepest dark a third, lozenge-making family. No grey fill anywhere in the ink.
11
+ 2. **Every line swells and tapers.** The burin enters fine, bites deeper mid-run and lifts out to a point. Lines thicken where the form turns from the light and vanish where it faces it; contours are cut in several runs and thin where runs hand over. A uniform-width line reads as a pen or vector drawing — never.
12
+ 3. **Colour comes afterwards, by hand**: transparent watercolour laid flat region by region over the finished black print, spilling past the lines, pooling at its edges, ink always on top. A film may stay monochrome long; colour arriving is an event.
13
+
14
+ Not a woodcut (black block, white gouges — `woodcut`), not a pen sketch (loose broken lines — `urban-sketch`), not an engineering drawing (`blueprint`), not a sepia filter.
15
+
16
+ ## 2. Materials & rendering
17
+
18
+ - **The sheet is the world**: 1920×1080 world units of laid paper (cream, ~`#f1e8d2`) with world-space texture (fibres, laid lines, sparse foxing) that zooms with the camera; a pressed, bevelled **plate mark** and a ruled border (rule + hairline) frame it.
19
+ - **Ink** is one warm near-black (~`#1c1510`). Width ratios: outlines heaviest (swelling ×0.45–1.35), first hatching from a hair (~0.18 px) to ~2 px, crossing ~0.8×, third family ~0.6×, hair and stipple finest. Spacing is **relative to the figure** (~1/180 of its height, a little wider per later family) so small figures never go grey.
20
+ - **Swell law** for every hatch line: width × (0.2 + 0.8·sin(πu)^0.7), tapered over its first and last ~22 %. Families switch on by tone thresholds (~0.14, ~0.5, ~0.75 on a 0–1 tone).
21
+ - **One light direction** for the whole film (upper left by convention); heavier outlines away from it; tone fields come from the shape (pillow lighting, analytic spheres and cylinders), never from texture. **Occlusion** is geometric: lines stop at the shapes in front.
22
+ - **Roundels**: double-ruled circle, ruled-machine ground with a white halo round the subject, content authored at a large radius and scaled in. **Leaders**: hairlines from a dot on the part to the rim, routed with clearance, a small italic figure number at the root.
23
+ - **Hand colouring** multiplies over paper and under ink: a few px of spill, slight misregister, tide-line at the wet edge, low-frequency density lift, occasional backruns, granulation; each region blooms from where the brush touched.
24
+ - **Copper** (when shown): polished warm metal, polishing hairlines, a soft reflected window; grooves = dark trough + bright burr toward the light. The **burin** (lozenge steel shaft, bevelled face, mushroom handle) is held low and turned ≤ 15° off the line so the fresh groove shows; **swarf** is a narrowing ribbon curling ahead of the point, one edge lit.
25
+
26
+ ## 3. Colour logic
27
+
28
+ - The print is two values, paper and ink; all tone is line density.
29
+ - Colour is **transparent wash only**, in muted earth and mineral pigments, one stronger pigment at most. Never opaque, never on lettering, rules or paper outside the figure.
30
+ - Reserve it: the whole subject at one moment, or only the part that matters — or none.
31
+ - Example wash sets: an amber insect with blue-grey wings; a map with a sea-green coastal band on buff land; one madder-rose organ on an otherwise black anatomy plate.
32
+
33
+ ## 4. Type & subtitles
34
+
35
+ - Lettering belongs to the plate: **roman capitals** (Bodoni Moda; title ~44–56 px, wide tracking; labels ~15–19 px), **italics** for scientific names (~20–24 px), **script** (Pinyon Script) for notes, fixed size, balanced over two lines, never shrunk.
36
+ - Roman letters are **cut glyph by glyph**; script is **written** in one left-to-right stroke. Nothing fades in.
37
+ - Subtitles: script on a deckled paper slip, bottom centre, ≤ 2 lines, never over a label. Hold ≥ max(1.8 s, speech + 0.6 s). An engraved note stays in frame chars ÷ 12 + 1 s from when it starts writing.
38
+
39
+ ## 5. Motion quality
40
+
41
+ - **Cutting order is the animation**: outline → first hatching sweeping across each form → crossing → darks, hair, stipple. Strokes run at constant burin speed, many at once (a few for outlines, dozens for hatching).
42
+ - A long single stroke may be followed by the camera; start it partly cut so no frame is empty. Keep a full build to a few seconds.
43
+ - Roundels fly on an eased arc with a small lift, growing log-linearly to size. Colour blooms from one point with a ragged front and a wet rim that dries; regions staggered.
44
+ - Nothing fades or slides like UI: lines are cut, text cut or written, colour blooms, sheets are pressed, peeled or laid down.
45
+
46
+ ## 6. Camera grammar
47
+
48
+ The camera is a **loupe over a sheet**. A vocabulary, not a route. Opening and ending come from the topic.
49
+
50
+ | Move | Expresses | Can serve |
51
+ |---|---|---|
52
+ | Loupe following the burin tip | One point of attention; making | a first mark; a signature |
53
+ | Log-zoom pull-out | The line was part of something larger | scale reveal; context |
54
+ | Push to a part, ride with its roundel | Where → what, in one take | an invisible detail; a mechanism |
55
+ | Tilt/pan along the sheet at reading zoom | Labels in order | a parts list; a coastline |
56
+ | Pull back while something flies | Everything placed in relation | acceleration; summary |
57
+ | Locked frame, or a ≤ 2 % breathing push | The plate as document | reading time; colour moving |
58
+ | Raking view across the copper | The groove as depth | the cost of craft |
59
+ | Cut from mirrored copper to true proof | Reversal | a hidden truth; before/after |
60
+
61
+ Framing: subject inside the plate mark, labels and roundels in the margins; order details so push-ins never crop a note early. Transitions from printmaking only (proof pulled, tissue guard laid over, region burnished out and re-cut, new sheet on the bed); no dissolves or wipes.
62
+
63
+ ## 7. Sound palette
64
+
65
+ - **Foley by material**: paper (peel crackle, slip tapped down, tissue rustle, sheet whoosh); press (roller rumble, thump); copper and steel (high band-passed burin hiss with chatter and faint plate ring, swarf pings, a tick on lift, circular scribe, burnishing rub); ink and water (pen scratch, ticks for cut letters, a water plip and wet brush swish). Hatching = micro-scratches denser each pass.
66
+ - **Room**: a quiet workroom (faint clock), paper room once the print exists.
67
+ - **Instruments** (choose): harpsichord, string quartet, solo cello or viola da gamba, lute, chamber organ, glass harmonica for a cold subject. Plucked and dry while lines are cut; bowed or sustained only when something soft arrives; tiny tings for a scribed ring, a low pluck on landing.
68
+ - **Silence** is real: cut room tone too, keep at most one small sound.
69
+ - **Mix**: melody an octave above the voice, music ~half under speech, −14 LUFS. Voice: a quiet curator or naturalist.
70
+
71
+ ## 8. Native moves
72
+
73
+ A menu: use the ones your story needs.
74
+
75
+ - **The cut.** Burin mid-stroke, swarf rising, nothing else. *Fits:* the first line of a treaty; a watchmaker's scribe; a coast being charted.
76
+ - **The three passes.** Form gains volume pass by pass. *Fits:* a building from its plan; a portrait emerging; a skill improving.
77
+ - **Magnification roundel.** Ring scribed, burnished, re-cut larger, flown to a margin with a leader, label cut on landing. *Fits:* a gear in a clock; a pollen grain; a harbour inset on a chart.
78
+ - **The proof.** Sheet peels off; mirrored copper becomes true paper. *Fits:* a secret out; a draft made final; a coin's die and strike.
79
+ - **States of the plate.** A region burnished out and re-cut. *Fits:* a border redrawn; before/after; a design revision.
80
+ - **Hand colouring.** Washes bloom after the print. *Fits:* one organ lit; a flag on a historical map; a ripening fruit.
81
+ - **Natural size.** A tiny true-scale figure beside the engraving. *Fits:* a seed by its tree; a chip by its circuit; a stamp by its enlargement.
82
+ - **The finished plate.** Every label and credit, locked. *Fits:* a museum label; a frontispiece; a certificate.
83
+
84
+ ## 9. Pitfalls of the medium
85
+
86
+ - Uniform width reads as pen → swell hatches, pinch contours between runs (`hatch({swell})`, `outline({run, pinch})`), keep wMin hair-fine.
87
+ - Overlaps without occlusion → pass occluders as `excl` (subtracted ring by ring; even-odd would cancel overlaps).
88
+ - Outline-only parts beside a hatched body → hatch along each part's axis, a dark at every joint.
89
+ - Burin along the cut hides the groove; big skew looks like poking → ≤ 15°. Regular swarf helix reads as a spring → vary winding, twist, light one edge.
90
+ - Reflections over grooves wash them out → copper light first. Roundels authored small freeze sub-pixel → author large, scale in. Leaders hugging the subject read as crossing it → clearance.
91
+ - A long early stroke never draws → the ink's early exit must look ahead by the longest stroke.
92
+ - A push-in cropping a fresh note breaks the reading rule → put consecutive details on one side.
93
+ - Scientific names: TTS may manage, ASR won't → give the checker a plain spelling.
94
+
95
+ ## 10. Engine
96
+
97
+ `demo/engine/`: `burin.js` (`B.Ink` ordered stroke store + `schedule`, `B.hatch`, `B.engraveTone`, `B.contourHatch`, `B.outline`/`B.stroke`, `B.stipple`, `B.fur`, tone fields), `plate.js` (`drawSheet`, `engraveText`, `writeScript`, `roundelFrame`), `wash.js` (`Wash`), `copper.js` (copper, burin, swarf), `index.js` (`engraveShape(svgPath, {at, light, spacing, style})`: any SVG shape → engraved figure). `demo/example/index.html` engraves and colours a four-pointed spark in ~20 lines; code and function table in DEMO.md "Engine reference".
98
+
99
+ ## 11. Variation space
100
+
101
+ You decide subject, details, order, opening, ending, camera path, colour, pacing and music. Use cases are **grammar for the order and duration of information**; build your own timeline from the user's facts.
102
+
103
+ | Use case | Information order | Hold per layer | Length |
104
+ |---|---|---|---|
105
+ | **Museum label / case screen** | title + scientific name → detail + term + note (×N) → where to see it | title ≥ 2.2 s; note ≥ chars/12 + 1 s; final ≥ 4 s | 30–40 s |
106
+ | **"One minute on …"** | question → name → 2–3 facts → one number → follow prompt | number ≥ 2.5 s alone | 35–60 s |
107
+ | **Textbook figure** | figure → parts labelled one by one → caption | label ≥ chars/12 + 1 s | 20–45 s |
108
+ | **Craft heritage** | object → 2–3 craft details → maker / edition | as above | 30–45 s |
109
+ | **Map / site plan** | place → insets → legend → visiting info | inset ≥ 3 s; legend ≥ 4 s | 30–45 s |
110
+
111
+ All far from our demo:
112
+
113
+ - Structures: **states of one plate** (one view re-cut three times as a place changes); **a book of plates** (four small plates turned like pages, one fact each, no roundels); **a dissection** (parts labelled in teaching order, colour only on the part taught).
114
+ - Openings: **the finished proof burnished back** to its first line; **on paper at 1×** (title cut first, figure grows below); **raking light over blank copper** as the design is traced.
115
+ - Endings: **plate beside its proof**; **the natural-size figure** held alone; **a blank new sheet** laid on the stack.
116
+
117
+ Swapping `demo/content.json` and rebuilding is a technical check that the engine re-flows, not a way to make a film.
118
+
119
+ ---
120
+
121
+ How our demo was made (story, shots, score, end card, build, content fields): [DEMO.md](DEMO.md). Read it after your treatment exists.
@@ -0,0 +1,116 @@
1
+ # Game Show Flat — Style Prompt
2
+
3
+ > A rhythm-game variety show in flat vector: toy-like mascots with thick ink outlines on candy-coloured stripes and sunbursts, every hit landing on a fixed tempo grid, call-and-response patterns, and a judgement word when each round is won.
4
+ > References (grammar only): rhythm-action party games in the Rhythm Heaven mould (cue → answer, round cards, judgement words), Japanese variety-show telops (thick outlined captions, stripe and sunburst sets), WarioWare-style stage cards. Never use their names, characters, UI, levels or music.
5
+
6
+ The length follows the number of rounds: each round is a title card plus its bars of play. Narration is optional: the style can carry a film on short shouts and telops alone.
7
+
8
+ ## 1. Essence, and what it is not
9
+
10
+ - **Everything is on the grid.** One fixed, fast tempo. Every pop, drop, stamp, typed character and camera punch sits at a (bar, beat) and is also a sound event; the score is generated from the picture's own timeline, so they can't drift.
11
+ - **One drawing kit, many sets.** Flat fills, one heavy ink outline, round caps, hard offset shadows; each round gets a new saturated background colour and pattern.
12
+ - **Characters are toys.** One body construction for the whole cast, told apart by colour, a belly patch, one head accessory and a name tag. They hop on the beat, squash on hits, throw arms up on a shout.
13
+ - **A round = a repeatable verb + a win.** The topic is split into rounds; each round has one action that can repeat on a beat, and ends on a judgement the audience reads in one glance.
14
+
15
+ Not a microgame frenzy (no timer or one-verb command per 3 s game, no change of art style per round), not a mid-century cartoon (no textured painted backgrounds, no character acting), not a keynote (no slow reveals, no gradients).
16
+
17
+ ## 2. Materials & rendering
18
+
19
+ - **Vector only**, SVG or canvas paths at 1920×1080: flat fills, one outline colour (near-black), 8 px outlines on characters and props, 5–7 px on small parts, round joins and caps.
20
+ - **No gradients, no blur, no texture, no soft shadow.** Depth is a **hard offset shadow**: the same shape in outline colour shifted ~10 px (stickers, banners) to ~14 px (cards), then the coloured shape on top.
21
+ - **Sets** = one saturated background + a same-hue pattern one step lighter: diagonal stripes (often scrolling slowly), offset polka dots (~20 % white), or a rotating sunburst. A darker floor band with an ink line on top grounds the characters.
22
+ - **Characters**: a rounded bean body, stubby arms with mitten hands, oval eyes with a catch-light, a mouth that swaps to an open one. Humans share the construction; older machines or eras read through a boxier silhouette.
23
+ - **UI kit**: round card, corner sticker banner, judgement word, burst (star + ring + speed lines), scoreboards.
24
+ - `render(t)` is a pure function of `t`: every element's state is recomputed from `t`, never carried over from the previous frame.
25
+
26
+ ## 3. Colour logic
27
+
28
+ - **Ink + paper + candy.** Near-black ink, white, and a warm cream for cards and paper props; around eight saturated candy hues (yellow, orange, red, pink, green, lime, sky, blue) plus two or three deep hues with darker partners for night or finale sets.
29
+ - **One set = one hue.** The background, its pattern and the round card share a hue; the card changes colour to match the set it introduces. Neighbouring rounds never share a hue.
30
+ - **Characters own colours.** A contestant's body colour is its identity and never changes; keep it distinct from the set it stands on (a character is never the same hue as the background).
31
+ - Big words are white or yellow with a thick ink stroke; judgement words may be pink or yellow.
32
+ - Set examples: tangerine ground `#FFB870` with `#FFA85A` stripes; teal with mint dots; navy with a gold sunburst.
33
+
34
+ ## 4. Type & subtitles
35
+
36
+ - **Display**: a heavy rounded sans for Latin and numbers (e.g. Fredoka 700); a black-weight sans for CJK (e.g. Noto Sans SC 900); a hand-lettered face only for handwritten props (e.g. ZCOOL KuaiLe).
37
+ - **Telop text**: white or yellow fill with an ink stroke ≈ 14 % of the font size painted *under* the fill (`paint-order: stroke`). Titles are built glyph by glyph so each character can pop in.
38
+ - **The telops are the subtitles.** Round cards, corner banners, labels, prop text and judgement words carry the meaning; keep them short (≤ ~20 CJK characters on a banner line, ≤ ~12 on a plate; Latin runs ~1.6× wider). With narration, subtitles are telop plates at the bottom in the same outlined type, never a thin generic caption.
39
+ - Hold every text ≥ max(1.8 s, speech + 0.6 s); a judgement word may be shorter because it is read at a glance.
40
+
41
+ ## 5. Motion quality
42
+
43
+ - **Idle = hop on the beat**: a parabola per beat (8–30 px); neighbours hop on the off-beat so a crowd ripples.
44
+ - **Hit = squash**: a damped wobble (~30 rad/s, ~0.35 s) after each hit; a small squash on every downbeat.
45
+ - **Entrances drop from the sky** with ease-in and land exactly on their beat, so the sound lands with them. Crowds drop in one per beat or half-beat.
46
+ - **Pops use back-ease** for anything appearing (cards, stickers, stamps, words); ease-in for exits. Nothing fades in slowly: things are either on or popping.
47
+ - **Shout pose**: arms up + open mouth for about half a beat.
48
+ - **Typewriter** reveals on fractions of a beat, with a click every few characters.
49
+ - Scene changes are **hard cuts on bar lines**, with a very short white flash. A fade is saved for the very end, if at all.
50
+ - Nothing moves off the grid: an event between beats sits on a subdivision.
51
+
52
+ ## 6. Camera grammar
53
+
54
+ The stage is a frontal, symmetrical proscenium; the frame itself does the moving. A vocabulary, not a route. Opening and ending come from the topic.
55
+
56
+ | Move | What it expresses | Can serve |
57
+ |---|---|---|
58
+ | Beat punch (zoom 0.8–5 % around centre, decays in ~0.16 s) | the hit, felt in the frame | any accent; a slam; a count-in |
59
+ | Several punches in one bar | the frame breathing with the music | a chorus; an escalating pattern |
60
+ | Locked frontal wide | the whole stage as a game board | a pattern being set up; a crowd; a scoreboard |
61
+ | Hard cut on the bar line + flash | a new round, a new set | chapter changes; a before/after |
62
+ | Split stage (two halves, two sets) | two sides answering each other | a rivalry; human vs machine; old vs new |
63
+ | Shrink to thumbnail (a finished bit scales down into a slot) | memory, accumulation | a recap; "and then all of this happened" |
64
+ | Vertical scroll of the set (floor to sky) | rising stakes or scale | a leaderboard; growth; a tower of items |
65
+ | Snap zoom onto one prop (hard cut to a 2× framing, back on the next bar) | this detail is the joke | a price tag; a number; a face reacting |
66
+
67
+ Keep the sum of simultaneous punches below ~0.06 so the frame edge never shows. Characters stand on the floor band; banners top-left, judgement words centre-top. Hard cuts only; no dissolves.
68
+
69
+ ## 7. Sound palette
70
+
71
+ - **All synthesized** from the picture's events: a sine kick with soft saturation, band-passed noise snare and clap, hats, slap bass, detuned-saw brass stabs with a closing filter, square lead with vibrato, marimba-like pluck, music-box bell, triangle pad, square arp, cowbell.
72
+ - **A bright major pop harmony** on a short chord loop, one chord per bar; each round gets its own flavour (funk, quiz, electro, dream, heavy…), not a new song.
73
+ - **Event foley is toy-like and pitched**: pops, plop + boing landings, stamps, typewriter clicks, buzzers, dings, servo whirs, splats; pitched pips can spell a melody as a crowd drops in.
74
+ - **Shouts, not sentences**: one- to three-word calls ("Hey!", a number, a verdict), placed 20–30 ms before the beat so the consonant lands on it. A crowd shout = several different voices stacked a few ms apart and panned across the stereo field.
75
+ - Options to vary intensity (pick what the film needs): a jingle (crash + rising brass + snare roll) into each round; a transposition up for a finale; dropping to drums only for one bar before a big hit; a half-time bar for a reveal; one bar of silence broken by a single shout.
76
+ - **Mix**: voices and foley on their own bus; music ducked from that bus's envelope; soft-clip rather than hard limit; −14 LUFS, true peak ≤ −1 dB.
77
+
78
+ ## 8. Native moves
79
+
80
+ A menu: use the ones your story needs.
81
+
82
+ - **Rounds with a card.** A 1-bar card (round number + name + a tag such as a year or a step) flies in on a jingle, then play. *Fits content like:* the steps of a recipe; the stages of a startup; the chapters of a museum tour.
83
+ - **Report card.** A typewritten recap with a grade stamp. *Fits content like:* a quarterly review; a trip summary; a final score.
84
+ - **Call-and-response.** Anything with a turn becomes a rhythm pattern; speeding up the pattern (quarters → eighths) *is* the plot. *Fits content like:* a teacher's question and the class answer; a customer order and the barista's reply; ping-pong between two negotiators.
85
+ - **Next-level tease.** Something hatches or unlocks. *Fits content like:* a next version; next season; a next grade.
86
+ - **Judgement word.** A big outlined word pops at an angle on the round's last hit. *Fits content like:* "Delivered!" on a logistics step; "Approved!" on a permit; "Personal best!" on a training plan.
87
+ - **Remix board.** One set with a timeline ribbon; each item gets a few bars centre stage, then shrinks into a slot along the bottom; at a climax all slots bounce together. *Fits content like:* a year in review; a team's release list; a festival line-up.
88
+ - **Stats as game UI.** Numbers become podium scores, counters racing to a target, price tags getting hammered, bar charts that grow per beat. *Fits content like:* fundraising progress; calories per dish; downloads of an app.
89
+ - **Crowd drop.** Many contestants drop in one per beat, each with a pitched pip. *Fits content like:* every member of a club; the planets; the ingredients of a dish.
90
+
91
+ ## 9. Pitfalls of the medium
92
+
93
+ - **Stateful updates break parallel renders**: a worker starting cold shows the initial state. Recompute every pose from `t`; compare single stills with a sequential render.
94
+ - **Cue lists drift** when cut flashes, jingles and arrangement are separate hand lists: derive them from one table.
95
+ - **Fixed-length audio buffers** cut the tail: size them from the duration.
96
+ - **Text measured before fonts load** overflows plates: load fonts, then build.
97
+ - **TTS misreads digits and symbols** in shouts: spell them out.
98
+ - **Real products as characters**: names on tags, original mascots, no logos or UI; real people only as generic stand-ins.
99
+
100
+ ## 10. Engine
101
+
102
+ `demo/frame_head.html` (SVG helpers: `el`, `txt`, `tf`, `op`, easing `E`, per-glyph `chars`/`charsPop`, `measure`), `demo/main_v1.js` (tempo grid `at(bar, beat)`, `ev()` sound events, `punch()`, `hopY`/`hitSq`, `gtext` telops, `stripes`/`dots`/`raysEl` sets, `burst`, `judge`, `banner`), `demo/main_b.js` (`bean()` characters + `pose()`, `human()`, `scene(t0, t1, build)`, `card()`, `dropY`, `heyAt`), `demo/music.py` + `demo/synth_lib.py` (event-driven score and SFX). The contract: `scene()` builds nodes once and returns `update(t)`, which only sets attributes. Module table and a minimal new round: [DEMO.md](DEMO.md#engine-reference).
103
+
104
+ ## 11. Variation space
105
+
106
+ You decide the rounds and their verbs, the cast, the sets and colours, whether there is narration, the tempo, the opening, the ending and the length. The grid, the drawing kit and the telop language stay.
107
+
108
+ All far from our demo:
109
+
110
+ - Structures: **a tournament bracket** (two contestants per round, the winner advances, the final is a split stage); **one long round** that keeps escalating its single pattern from quarters to sixteenths as the story's pressure rises; **a quiz show** with three contestants where each question is a fact of the topic and the scoreboard is the argument.
111
+ - Openings: **the judgement first** (a "Perfect!" pops on an empty stage, then we rewind to how it was earned); **a single contestant alone** hopping on a bare floor until the crowd drops in; **the scoreboard** showing a final number, then counting back to zero.
112
+ - Endings: **a group photo** (everyone freezes mid-hop, a flash, the frame becomes a polaroid on a card); **a level-select map** where every finished round is a lit node; **a curtain** falling bar by bar with the last shout under it.
113
+
114
+ ---
115
+
116
+ How our demo was made (story, shots, score, end card, build): [DEMO.md](DEMO.md). Read it after your treatment exists.