@autoaiai/aicut 0.1.11 → 0.1.13

package/skills/framewright/references/audio.md

@@ -1,230 +0,0 @@
-# Sound
-
-Sound is written last, to locked scene lengths, and synthesized entirely inside
-`audio.mjs` (template in `assets/audio-template.mjs`; painting and landscape films start from
-`assets/audio-nature.mjs` and the blocks in `assets/nature.mjs`, section 8). No samples, no
-libraries. The script writes a 16-bit stereo WAV that `build.sh` muxes into the MP4.
-
-## 1. The timeline table
-
-```bash
-node scripts/export-curves.mjs curves.json    # make.sh and `npm run audio` do this first
-```
-
-`audio.mjs` builds `T` (plate starts in seconds, plus `end`) and `BPM` from `curves.json`, which
-the export script takes from the page's `RISO.curves()`, so the sound cannot drift from the
-picture when a plate changes length: export again, regenerate the WAV. The template warns when `curves.json`
-is older than `index.html`. For a page without `curves()` (projects made before it existed),
-copy the starts from `node scripts/look.mjs info` into the fallback table by hand. The beat
-grid is the same as the video's: at 120 BPM `BEAT = 0.5`, `BAR = 2.0`. An event that must land
-on a frame takes its time from the film, `T.plate + beats * BEAT` or `frame / fps`, never from
-seconds retyped by hand.
-
-A moment the picture marks (a splash, a stamp, a lamp) is named once in the page, `CUES` in the
-plate skeleton or `W.cues.push({name, f})` in a world builder, and read here with `cue('splash')`:
-its time in seconds on the frame the picture shows it. Move the moment in the picture, export the
-curves, and the hit moves with it. A hit that belongs to the groove (a drum pattern, hats on the
-off-beats) keeps `T.plate + beats * BEAT`: on an eighth at 120 BPM (7.5 frames) the two differ by
-17 ms, far below the 45 ms at which sound ahead of picture begins to show, while a pattern moved
-onto frames starts to swing. (`at(t)` in `audio.mjs` is the curve sampler of section 7, not the
-page's `at()`.)
-
-## 2. Cue map
-
-| On screen | In sound |
-|---|---|
-| power on, lights up | click plus a low sine falling 90 → 40 Hz over 120 ms; then a bed (hum, room, pad) that lasts until the end |
-| static, snow, waiting | white noise through a 6.5 kHz low-pass at low level with a slow amplitude wave |
-| a word or line appears | a data chirp (12 short square tones 1.2–2.6 kHz) or a single sine tick |
-| a cut, a channel switch | click plus a 40 ms noise burst |
-| a count, a timer | sine beep 880 Hz for 120 ms per count; the last one longer and higher |
-| something breaks | alternating 700/900 Hz square at 8 Hz, noise bursts, a 110 Hz square buzz |
-| a hold with text | a beat: kick on the beat, hat on the off-beat, rim on 2 and 4, a sine bass pulse |
-| a search, a sweep | filtered noise panned left to right over the sweep, a sine glide following a moving line |
-| a signal locks, a reveal | decaying noise with crackle, then a pad swelling over one second, a bright "click" of lock |
-| a lower third slides in | a short high-passed whoosh, 350 ms |
-| a stab, a big word | a short saw chord through a 2.6 kHz filter, 350 ms, two stabs on consecutive beats |
-| the end approaches | a riser: noise with a rising high-pass over the last bar |
-| power off | click, sine 120 → 38 Hz over 90 ms, a 15.7 kHz whine decaying over 1.5 s, then silence |
-| an end card | a soft bell: sine 1760 Hz plus 2640 Hz with 0.35 s decay |
-| paper, a drawing, colour washing in (a painting film) | a quiet bed only, from frame 0 under the master's 1.7-s fade-in: wind in a calm or a surf bed; no pencil, no whoosh |
-| the painting comes alive (`alive`) | the ambience opens over ~1.8 s: wind and leaves rise with the page's gust, a wave enters 0.35 s before the cue, birds from +0.6 s |
-| a bloom of wash (pencil and wash) | `paperTouch`, 0.25 s, at least 12 dB under the bed |
-| a bird or a gull crosses the painting | one call on its own cue; at most one accent every 6 s, never on `alive` itself |
-| the camera pushes in | nothing |
-
-Per style: retro TV uses hum, hiss, tones and beeps; risograph likes warm bass, brushes and
-paper; terminal uses key clicks and modem chirps; blueprint uses pencil, ruler and a
-metronome; poster uses a click track and snare hits on cuts; neon grid wants a
-four-on-the-floor kick, gated snare and detuned saw pads; pixel game uses square and
-triangle waves with noise drums; the painting styles use the nature ambience of section 8,
-with no music.
-
-## 3. Building blocks in the template
-
-- `osc(dur, f0, {f1, wave, amp, vib, vibHz, noiseAmt})`: sine, saw, square, triangle with
-  exponential glide from `f0` to `f1`.
-- `noise(dur, {amp, lpf, hpf})`: white noise with one-pole low- and high-pass filters.
-- `shape(buf, {att, rel, decay, hold})`: linear attack, hold, linear release, optional
-  exponential decay.
-- `mul(buf, fn)`: multiply by a function of time (tremolo, custom envelopes).
-- `lp`, `hp`: one-pole filters on any buffer.
-- `add(t, buf, pan, gain)`: mix into the master with constant-power pan.
-- Instruments: `kick`, `hat`, `rim`, `click`, `beep`, `chord` (detuned saw pad through a
-  low-pass), `chirp`, `riser`. Notes are MIDI numbers: A2 = 45, A3 = 57, E4 = 64.
-
-A drum pattern for one bar at `b0`:
-
-```js
-for (let k = 0; k < 4; k++) { const t = b0 + k*BEAT; kick(t, 0.5); hat(t + BEAT/2, 0.09); if (k === 1 || k === 3) rim(t, 0.16); }
-```
-
-## 4. Levels
-
-The master applies `tanh(x·1.3)` and normalizes to −1 dBFS. Aim for the loudest scene to
-peak around 0.7 before normalization; the template prints the pre-normalization peak. A bed
-(hum, hiss, pad) sits at 0.02–0.06, cues at 0.1–0.3, drums at 0.5. Nothing inside an active
-scene should fall silent unless the picture is silent too. A nature track uses `masterNature`
-instead (section 8): loudness normalisation, not peak normalisation.
-
-## 5. Checks without ears
-
-```bash
-node audio.mjs track.wav
-ffmpeg -y -i track.wav -filter_complex "showwavespic=s=1800x300:split_channels=1" -frames:v 1 shots/wave.png
-ffmpeg -i track.wav -af ebur128 -f null - 2>&1 | grep -A2 "Integrated"
-```
-
-Read the waveform against the plate table: every plate has visible activity, the beat
-sections show even spikes, the ending decays to zero, nothing is a solid block pinned to the
-ceiling. A voice that follows the picture (section 7) is checked alone: comment out the other
-events, render, and compare its loudness per few frames with the `sp` column of `curves.json`;
-the two must rise and fall together, the sound a frame or two behind. Loudness around −14 LUFS integrated suits social platforms; for a chat it does not
-matter. The waveform picture goes to the user only if they ask; the MP4 is the proof.
-
-## 6. Room for the user's track
-
-When the user brings a track: ask its BPM, set `BPM` in both the HTML and `audio.mjs`, keep
-cuts on bars, deliver the MP4 without audio (`build.sh` does that when `track.wav` is
-absent) and a note with the timecodes of the cuts. When a voice-over comes later, leave the
-bed only and no melodic elements under the lines of text.
-
-## 7. Sound that follows the picture
-
-In a world film (`references/world.md`) the sound can read the picture instead of a cue list.
-`RISO.curves()` adds one record per frame to `curves.json`:
-
-| field | meaning |
-|---|---|
-| `sp` | speed of the line's head on screen, logical px per frame; 0 while it rests |
-| `pan` | the head's position on screen, −1 left edge … 1 right edge |
-| `z` | the camera: world units across the short side |
-| `w` | line width at the head, 0 while the pen is lifted |
-
-And `strokes`: the frames where the pen touches down after a lift (`pen.lift`). A tick or a
-pencil tap on each of them lands exactly on the picture; detecting touch-downs from per-frame
-`w` misses lifts shorter than a frame. And `cues`, the moments the builders marked with
-`W.cues.push`, read with `cue(name)` (section 1).
-
-Add fields the sound needs (a character on screen, a second head) in `curves()` the same way.
-In `audio.mjs`, `at(t)` interpolates the records at time `t`, and `follow(fn, opts)` runs a voice
-sample by sample: `fn(c, t)` returns `{f, a, pan}`. Mapping that worked in a finished film:
-
-- loudness from speed with a soft curve and a ceiling: `a = amp · clamp(sp / sMax)^0.8`, with
-  `sMax` the speed of a brisk stroke, 20–35 px per frame;
-- pitch rises a little with speed, 2–6 %, never enough to read as a melody;
-- pan follows the head's screen position times 0.8, so nothing sits hard in one ear;
-- every control is smoothed by a one-pole follower of 20–30 ms (`follow` does it), or the 33 ms
-  steps between frames zipper;
-- a line being drawn: `tone`, a sine with 0.28 of the second harmonic on a chord tone of the pad,
-  around 0.05;
-- a creature in flight: `buzz`, two saws a hair apart (1 : 2.003) through two one-pole low-passes
-  near 1.1 kHz, at 200–250 Hz, louder and slightly higher in fast flight, a tremolo of 15–20 Hz
-  when it wiggles;
-- when the line stops for good, let the voice die with it; silence after a long drone is an event;
-- a pencil or a marker on paper: band-passed noise (1.3–5 kHz) whose loudness follows `sp` only
-  while `w` shows ink, roughened by a slow random grain, plus a tap on every entry of `strokes`.
-
-The curves come from the main aspect; one track serves the vertical cut too.
-
-## 8. Nature ambience
-
-A landscape or a painting wants air, water and birds, not beeps. `assets/nature.mjs` is a module of
-nature blocks in the template's conventions, and `assets/audio-nature.mjs` a soundtrack template
-built on it; `init.sh --painting` copies them as `nature.mjs` and `audio.mjs`. Use them when the
-picture shows a place (sea, lake, meadow, forest, rain); keep `audio-template.mjs` for cues, beats
-and voices that follow a line. The two mix: import `nature.mjs` into a template-based `audio.mjs`,
-or paste its sections 2–4 into the template (strip `export`) and use `masterNature` as its master.
-
-```js
-import * as NS from './nature.mjs';
-NS.init(END, curves, seed);        // seconds, the parsed curves.json (or null), film seed
-NS.wind(0, END, { gust });         // blocks, in absolute seconds
-NS.room();                         // a short diffuse room over the whole mix
-NS.masterNature({ lufs: -20 });    // fades, soft clip, loudness normalisation
-NS.writeWav('track.wav');
-```
-
-Fitted blocks were fitted to a recorded surf track (band envelopes within ~1.3 dB). Designed blocks
-are built from published acoustics (the facts sit above each block) and tuned on spectrograms.
-
-| Block | Kind | What |
-|---|---|---|
-| `surfBed(t0, dur, {gainDb, dips, wash, wide})` | fitted | the stationary sea: sub, body and hiss by band power; `dips` sink it 2–3 dB before each wave |
-| `surfWave(t0, {gainDb, stretch, lead, fade})` | fitted | one wave, surge, break and wash over 6.15 s; enter it 0.35 s before the moment its rise should land |
-| `backwash(t0, {from, fadeIn, gainDb})` | fitted | a receding wash, silent by +2 s; `{from: w.last, fadeIn: w.fade}` continues a wave `w` |
-| `surfWaves(from, to, {every, jitter, gainJitter})` | designed | the fitted wave every 8 ± 1 s (the spacing is a choice), each with its backwash; returns the onsets for the bed's `dips` |
-| `room({t60, wetDb, predelay, hp, ripple})` | fitted | a 0.12-s velvet-noise room over the mix: the fixed spectral ripple a recording has and dry noise lacks |
-| `masterNature({lufs, ceiling, fadeIn, fadeOut, end, peakGuard})` | fitted | a 1.69-s fade-in, a `0.9·tanh` soft clip, loudness to `lufs`, a 1.35-s fade-out ending on the last frame |
-| `followNoise(spec, fn, {tau, band, from, to})` | helper | filtered noise whose level and pan follow the page's curves: `fn(c, t)` returns `{db}` or `{a}`, and `{pan}` |
-| `wind(t0, dur, {level, f, q, lp, gust, width, whistle})` | designed | band-passed noise whose level, centre and top edge rise with `gust` 0..1; an optional aeolian whistle |
-| `rustle(t0, dur, {gust or rate, band, level, pan, spread})` | designed | leaves and grass as grains of 4–15 ms at 2.5–7 kHz, 30–280 per second with the gust |
-| `birds(t0, dur, {voices, phrase, notes, f, level, lp, trill, pan})` | designed | songbird phrases (sweeps, arches, whistles, buzzes, trills) at 2.5–6 kHz, singers taking turns |
-| `gulls(t0, dur, {every, notes, f0, level, lp})` | designed | harsh "kee-ow" calls every 6–15 s; only where the picture shows open sea |
-| `insects(t0, dur, {kind, tempC, level})` | designed | `'crickets'`: 4.5-kHz chirps, the rate from `tempC` by Dolbear's law; `'cicadas'`: swells at 4–8 kHz |
-| `rain(t0, dur, {intensity or mmh, level, leaf, ground, water})` | designed | a bed of far drops and near drops on leaves, ground and water; the rain rate may change with time |
-| `brook(t0, dur, {rate, flow, level, bedLevel})` | designed | a stream: rising bubble chirps (Minnaert resonance) over turbulence noise |
-| `thunder(t0, {distance, level, crack})` | designed | a roll from a random lightning channel; closer than 1.5 km it opens with a crack; returns `{start, end}` |
-| `lapping(t0, dur, {rate, level, pan, spread})` | designed | small waves at a jetty, a hull or a bank: slaps at 250–900 Hz, gurgles, trickles, ~1.5 per second in sets |
-| `paperTouch(t, {dur, level, pan})` | designed | a 0.25-s paper swell for a bloom of wash (pencil and wash only) |
-
-Levels. `level` is dBFS of the mono source before panning: band power (the mean square inside the
-stated band) for noise, RMS at the envelope's peak for a call. Calibrating by band, not by
-broadband level, is what makes a layer land where it was fitted: it moved the 6–11.5 kHz error of
-the surf from 6 dB to 1 dB. Levels that worked under a painting: wind bed −46, rustle −50,
-lapping −36, birds −39 (a nearer call −34), the surf as fitted (its body −35.5). The film's level
-comes last, from `masterNature`: −18.5 LUFS as fitted, −20 for a quiet ambience. The template's
-`tanh(1.3x)` master would lift a surf bed to −14.8 LUFS and flatten it.
-
-Seeds. Every block takes `o.seed`. Without it the seed is a hash of the film seed, the block's name
-and how many times that name was called before: adding birds leaves the sea sample-identical, and a
-second `birds()` call changes only the birds after it. Another film seed
-(`node audio.mjs track.wav 31`) is another take of the same soundtrack.
-
-Tying the sound to the picture:
-- Moments come from the page's cues, `cue('alive')`. In a painting film the drawing and the colour
-  are silent over the bed; the ambience opens with `alive` through a smoothstep of ~1.8 s on the
-  audio side, so it does not switch on in one frame; accents come after the cue, never on it. Guard
-  a cue the page may not mark with `has()`.
-- The painting kit writes per-frame `life` (0..1) and `gust` (the wind the painted trees sway on,
-  about −2..2) into `curves.json`; `NS.at(t)` samples them. The template maps them to 0..1 as
-  `0.1 + (0.45 + 0.28 * gust) * open(t)` for `wind` and `rustle`, so the leaves hiss when the crown
-  bends. `gust`, `rate`, `flow`, `intensity` and `mmh` take a number or a function of time.
-- `followNoise` does the same for a layer of your own, smoothed over 20–30 ms so the frame steps do
-  not zipper. The sea runs free by default; a stylised sea on a visual period (gouache poster)
-  takes a small `surfWave` per period, or a foam curve through `followNoise`.
-
-Checks without ears:
-
-```bash
-ffmpeg -y -i track.wav -lavfi "showspectrumpic=s=1600x600:legend=1:fscale=log" -frames:v 1 shots/spec.png
-ffmpeg -hide_banner -nostats -i track.wav -af ebur128=peak=true -f null - 2>&1 | tail -12
-node audio.mjs shots/again.wav && cmp track.wav shots/again.wav    # silent: the render is deterministic
-```
-
-Look at the spectrogram. Before `alive` only the bed shows, a band under ~1.5 kHz fading in from
-black. After it the wind brightens over about two seconds, rustle grains stand as thin vertical
-streaks at 2–15 kHz, birds as short strokes and hooks at 3–7 kHz, and a wave as a swell of the low
-band with foam at 4–10 kHz on its break. Integrated loudness sits on the target, the true peak under
-−1 dBTP, and `cmp` prints nothing. A layer the spectrogram does not show over the others is lost in
-the mix: raise it or cut it.

package/skills/framewright/references/guide.md

@@ -1,276 +0,0 @@
-# Engine, helpers and the way of working
-
-Read once before the first scene. Everything here is implemented in `assets/skeleton.html`
-and used at full scale in `examples/ris-tv/index.html`.
-
-There are three starting files. `assets/skeleton.html` is a film of separate plates joined by
-cuts: each plate draws its own picture. `assets/world.html` is one continuous world: plates are
-builders that append a line, camera keys, titles and light events to one timeline, and one
-function draws any frame of it (`init.sh --world`, method in `references/world.md`). Choose the
-world for a journey or a growth told without cuts; choose plates for bulletins, parodies, lists
-and anything cut on the beat. `assets/painting.html` is the plate engine with a painting kit: one
-still oil painting built from cached layers of brush marks, revealed through a pencil drawing of
-itself and brought to life; its plates are chapters of time (`init.sh --painting`, styles 13–16,
-method in `references/painting.md`). Everything below holds for all three.
-
-## 1. The file
-
-One HTML file, one canvas, one script. Sections in this order: parameters, generators,
-math, canvas pool, palette, helpers, generated data between markers, engine, plates, boot.
-Helpers stay above the plates block: a helper placed between two plates leaves with the
-plate you cut. Generated data (polygons from a photo) lives between
-`/*PORTRAIT_START*/` and `/*PORTRAIT_END*/` and is replaced by `scripts/inject.mjs`, never
-by hand.
-
-Size guide: the HTML stays under 200 KB; polygon data 30–70 KB as integers.
-
-## 2. Knobs and the script object
-
-```
-?f=140      draw one frame and set window.__ready
-?s=12       seed of the impression
-?w=1920     output width; height follows the aspect and is forced even
-?grid=24    contact sheet of evenly spaced frames with labels
-?cw=480     cell width of the sheet
-?from=480&to=720   with grid: the sheet covers only these frames (without grid: where the preview starts)
-?ar=16:9    aspect ratio
-no knobs    live preview in the browser, capped at 960 px
-```
-
-```js
-window.RISO = {
-  fps: FPS,
-  get total(){ return TOTAL() },
-  get plates(){ return PLATES.map(p => ({name: p.name, len: p.len})) },
-  frame(n, width, seed){ renderFrame(n, width, seed, MAIN); return MAIN.toDataURL('image/png') },
-  contact(n, cellW, f0, f1){ contactSheet(n, cellW, SEED, MAIN, f0, f1); return MAIN.toDataURL('image/png') },
-  curves(seed){ return {fps, bpm, total, start: {plate: frame}, frames: [...], cues: [{name, f}]} }   // for the soundtrack
-}
-```
-
-`curves()` gives plate starts and the cues (`CUES`, or `W.cues` in a world film); a world film
-adds per-frame values (head speed and position on screen, camera zoom).
-`scripts/export-curves.mjs` writes them to `curves.json` and `audio.mjs` builds its timeline from
-that file. The world skeleton also has `stats()`, the size of the
-world, which `look.mjs info` prints.
-
-Scripts call `RISO.frame` and save the data URL. They never screenshot the page: a
-screenshot depends on CSS and device scale; `toDataURL` returns exactly the drawn pixels.
-
-## 3. Coordinates and time
-
-- Logical coordinates with a fixed short side of 1080. `LW`, `LH` follow the aspect; `CX`,
-  `CY` are the centre. Scenes never touch output pixels; the engine scales the context.
-- Safe area: important content inside the central 92 % of each axis. On-screen labels start
-  at 7–8 % of the height from the edge. Styles that distort edges (CRT barrel, vignettes)
-  need this; other styles benefit anyway. In 9:16 the platform's UI covers the top 15 % and the
-  bottom 20 %: there labels, text and faces stay between them, lower titles on `TITLE_Y` (70 %).
-- 30 fps. `BEAT` and `BAR` derive from `BPM`. At 120 BPM a beat is 15 frames and a bar 60.
-  Plate lengths are multiples of `BEAT`; eighths (7.5 frames) are not cut points. A hit on an
-  eighth shows on frame 7 or 8, half a frame (17 ms) from the sound, which nobody sees. A film cut
-  on eighths takes a BPM where they are whole frames: 60, 75, 90, 100, 150 or 180.
-- Stepped motion (a pose held for several frames: sprites, cutouts) holds for a divisor
-  of `BEAT`, counted from the plate's start, `Math.floor(S.i / HOLD)`, so every beat opens a new
-  pose. At 120 BPM that is 3 or 5 frames, not 2: on twos every other beat falls inside a pose.
-  At 100 BPM (beat 18) 2, 3 or 6 fit; at 90 (20) 2, 4 or 5; at 150 (12) 2, 3 or 4.
-- Inside a plate use beats and progress, never global frame numbers:
-  `const beat = Math.floor(S.i / BEAT), inBeat = (S.i % BEAT) / BEAT;`
-  `span(S.i, a, b)` gives 0..1 between two local frames; wrap it in `ease.out`, `ease.io`,
-  `ease.back`.
-- What carries on across cuts (an island that grows through three plates) runs on the global
-  frame, measured from plates by name: `at('shore', 2)` is the frame of beat 2 of `shore`, rounded
-  to a whole frame, so `span(S.f, at('sea'), at('city', 4))` spans three plates whatever their
-  lengths. A moment the sound must hit goes into `CUES` as `[plate, beat, name]`; a plate reads
-  it with `cue('name')` (`S.f - cue('splash')` is the frames since it), `RISO.curves()` exports it.
-  Call both while drawing, never at the top level. A world film has `W.at` (not rounded: world
-  time is continuous) and `W.cues.push`; `curves()` rounds its cues up to the first frame that
-  shows them.
-
-## 4. Generators
-
-Three per frame, all seeded through `hash(seed, ...)` with the plate name, so inserting a
-plate never changes its neighbours:
-
-| generator | reseeded | use |
-|---|---|---|
-| `R` | once per plate | composition: positions, choices that must not move |
-| `S.b` | every 3 frames | the live line: jitter of outlines, flicker decisions |
-| `S.nz` | every frame | noise fields, snow, grain decisions |
-
-Compute a jittered path once and reuse it; two calls of `S.b` produce two different paths.
-Per-pixel effects use a linear congruential generator seeded with `hash(seed, 'grain', f)`.
-
-## 5. The engine
-
-`renderFrame(n, width, seed, target)`: even height, content canvas at output size, its
-context wiped (`wipe(g)`: `reset()`, so no save, clip, shadow or composite mode survives from
-the previous frame), background fill in device pixels, context scaled by `width / LW`,
-`P.fn(S, R)`, edge transition (`cutIn`, `cutOut`), reset transform, `post()` into the target,
-which is wiped too. It returns `S` so the sheet can label cells. `locate(n)` maps a global frame
-to a plate and a local frame, `at(name, beats)` a plate's beat back to a global frame. `TOTAL()`
-sums plate lengths; `look.mjs info` prints them, and the cues.
-
-`COL` and `ease` are frozen: a plate that edits a shared value throws at once instead of
-changing every later frame of its tab. Any offscreen canvas a plate keeps (`cvs(name, w, h)`)
-is wiped or cleared before it is drawn, in pixels: `wipe()` it, or `clearRect(0, 0, c.width,
-c.height)` under an identity transform. `clearRect(0, 0, LW, LH)` under the scale misses the last
-pixel row at widths where `LH * sc` falls short of the even height (9:16 at 480, 16:9 at 1200),
-and the previous frame shows through there: `check.mjs` fails only in some aspects. The default
-`cut()` and the world fade fill in pixels for the same reason. A plate's own full-frame fill in
-logical units leaves that row in `COL.bg`: harmless at the final sizes of 16:9, 9:16, 4:5 and 1:1,
-which are exact, a thin line at 21:9 when the plate's ground differs from `COL.bg`.
-
-`post(src, dst, S, o)` is the style's finisher. The skeleton ships grain and vignette;
-replace or extend it per `styles.md`. A per-pixel pass over 1920×1080 costs 50 ms for
-simple maths and up to 0.5 s with bilinear resampling in three channels. Cache anything that
-depends only on resolution (distortion maps) in a dictionary keyed by `W×H`.
-
-`cut(g, S, amt)` is the transition drawn at plate edges. The skeleton fades to black; a
-retro TV switches channels with band tearing and snow; a poster style cuts hard
-(`cutIn: false, cutOut: false` on every plate). The first plate has `cutIn: false`; the
-last has `cutOut: false`.
-
-When a plate needs the last frame of the previous one (a TV switching off over the
-portrait), move that plate's drawing into a function and call it with a fixed local frame.
-
-## 6. Contact sheet
-
-`contactSheet(n, cellW, seed, target)`: cells rendered at twice the cell width and scaled
-down, so per-pixel post-processing looks the way it will in the video. Labels: frame,
-plate, local `t`, seconds. Six columns for landscape, eight for portrait. Twenty-four cells
-cover a 40-second video every 1.7 seconds; for a 15-second video use 18.
-
-A sheet of one section: `FROM=480 TO=720 node scripts/look.mjs sheet 12 480 7 shots/sheet-b.png`
-(start frames of the plates come from `look.mjs info`). In a long film, and in a world film where
-plates flow into each other, review the section you just built this way: twelve cells over eight
-seconds catch a camera that stalls or jumps, which one cell every two seconds hides.
-
-## 7. Text
-
-Bitmap text (`pixText`): a system bold monospace at 14 px is drawn into a small canvas, the
-alpha is thresholded at 0.5, the mask is scaled up without smoothing by `cell` logical units
-per glyph pixel, aligned by its tight bounding box (never by font metrics), snapped to the
-glyph grid so letters do not shimmer between frames. `fit` shrinks `cell` to the largest
-integer that fits a width. This gives teletext, OSD menus, terminal type, pixel-game text.
-Vector text (`vecText`) for display sizes in poster, flat and blueprint styles. Measure
-before you place; multi-line layouts compute line height in units of `cell`, including any
-sub-line, so lines never touch.
-
-Lower titles sit on one baseline, `TITLE_Y` in both skeletons: 80 % of the height in 16:9, 70 %
-in 9:16, where the bottom fifth belongs to the platform's captions and buttons. Two titles never
-share the screen in the same place: end one before the next begins, even when both fade. The
-world skeleton warns about overlaps in the console.
-
-Cyrillic and Latin are both in Menlo and Helvetica Neue on macOS; on Linux install
-`fonts-dejavu` and use `DejaVu Sans Mono`. Rendering happens on one machine, so
-cross-machine font drift is not a concern unless the HTML is rendered elsewhere.
-
-## 8. Motion vocabulary
-
-- Reveal: `reveal` as a fraction of width for row-by-row text; `frac` for paths by
-  cumulative length (constant beam speed); scale pop `1.10 → 1` over 45 % of a beat on
-  every count; slide-in from the edge with `ease.out` over 10–12 frames.
-- Hold: a still that breathes. A ±1.5 unit drift from `S.b`, a blink at 1 Hz, a slow
-  brightness sine of ±2 %. Two adjacent sheet cells must still differ.
-- Cut: the engine does it. Inside a plate, a "flash frame" (one white frame) and a "shake"
-  (±8 units for 4 frames) are enough punctuation.
-- Camera: translate and scale the whole context inside the plate; ease between two
-  keyframes; never move more than 20 % of the frame per second on a hold. A camera that
-  travels far (a zoom from a detail to a landscape) interpolates the zoom in log space, or it
-  rushes at the close end and crawls at the far end, and is smoothed over ±18 frames; widths that
-  must stay constant on screen are divided by the scale. `world.html` has this camera
-  (`references/world.md`, section 4).
-- Transitions between two states of one object: interpolate polylines with the same point
-  count; morph by cross-fading fills only when shapes share topology.
-
-## 9. Parametric objects
-
-Everything is a function of a scale parameter, centred on `CX, CY`: seven-segment digits,
-a test card, a graticule, a paperclip from arcs and lines with cumulative length, a clock, a
-progress bar, a lower third, a stamp, a speech bubble. Build the object once as points, then
-draw it with the current style; the same points serve stroke reveal, fill and jitter.
-
-## 10. Review protocol
-
-```bash
-node scripts/look.mjs shot 0,45,115 1200 7          # first, middle, five before the end
-node scripts/look.mjs sheet 24 480 7 shots/sheet.png
-node scripts/look.mjs info                          # plates, lengths, seconds
-node scripts/check.mjs                              # before a full render: OK or a list of problems
-ffmpeg -y -i shots/f0770.png -vf "crop=900:300:160:560" shots/crop.png   # small text at full size
-```
-
-`check.mjs` is the machine half of the review: pixels of sample frames identical in seven
-render orders, no clock or `Math.random` in the source, no file requested by the page, plate
-lengths on the beat, a BPM that divides into frames, no flat frame inside a plate, no plate that
-stands still, and the time of one full-size frame. Every script starts Chrome with
-`--disable-accelerated-2d-canvas`: an accelerated canvas switches to software after a few
-readbacks, and the same frame then comes out slightly different in a fresh tab and in a used one.
-
-Look at every PNG with the image tool. The script prints page errors and console warnings;
-a black frame without an error message means a plate threw before drawing, so read the
-output. The checklist is in `SKILL.md`, step 4.
-
-Lessons from review of a finished film:
-
-- An empty scene is a scale problem. Make the object bigger or bring the camera closer; more
-  detail makes a scene busier, not fuller.
-- In an intimate scene the set competes with the subject. Dim the decor around it with a
-  spotlight measured on screen (full near the centre, gone at about 0.6 of the frame height),
-  and open the light when the world opens (`references/world.md`, section 6).
-- Where plates flow into each other, shoot the last frame of one plate and the first frame of
-  the next side by side: nothing may jump.
-
-## 11. Render and encode
-
-```bash
-node scripts/render.mjs frames 7 1920 5     # ~2 min per 1200 frames with per-pixel post on an M-series Mac
-START=600 END=780 node scripts/render.mjs frames 7 1920 5
-RESUME=1 node scripts/render.mjs frames 7 1920 5
-bash scripts/build.sh out.mp4               # CRF=22, maxrate 14M, yuv420p, faststart, AAC 192k
-AR=9:16 node scripts/render.mjs frames-v 7 1080 5 && bash scripts/build.sh out-vertical.mp4 frames-v
-```
-
-`build.sh` converts the sRGB frames with the BT.709 matrix and tags the file (BT.709 primaries
-and matrix, sRGB transfer, limited range). ffmpeg alone would convert with BT.601 and leave the
-matrix untagged; players read HD video as BT.709, so saturated colours shift, pure green by 39
-levels in a measured test. The MP4 is written under a temporary name and appears only when the
-encode succeeded.
-
-PNG frames weigh 1.5–2.5 MB each; a minute of video is 3–4 GB, ignored by git. CRF 22 with a
-14 Mbit/s cap gives about 0.7 MB per second on noisy styles and half that on flat styles;
-CRF 17 is five times larger with no visible gain on a contact sheet. Keep deliverables under
-50 MB for messengers. Verify the MP4: `ffprobe` frame count equals `RISO.total`, duration
-equals frames / 30, a tile made from the file matches the sheet.
-
-A film made vertical from the start sets its page's default aspect
-(`parseAR(Q.get('ar') || '9:16')`), so every script renders it vertical without `AR`; `render.mjs`
-without a width then takes 1080, and `check.mjs` times the frame at that width.
-
-For a vertical cut, composition needs its own sheet: `fit` saves the text, not the layout.
-Platform UI covers the top 15 % and bottom 20 % of vertical video: lower titles go up to 70 %
-of the height (`TITLE_Y` does it when the aspect is vertical). One soundtrack serves both cuts.
-
-## 12. Changing a finished video
-
-- Insert a plate: add it, shorten a neighbour to keep the total, export the curves again (the
-  sound's timeline follows; without `curves.json` update the `T` table by hand), reshoot the
-  sheet, re-render. In a world film the next plate's first stroke now starts from a new point:
-  reshoot that boundary (`references/world.md`, section 9).
-- Change a line of text: reshoot the frames that show it and one sheet.
-- Swap a photo: rerun `portrait.sh`, reshoot the portrait plate.
-- Change the seed: nothing else changes; render and compare two sheets side by side.
-
-## 13. Project layout after `init.sh`
-
-```
-index.html        the video
-audio.mjs         the soundtrack
-nature.mjs        the nature sound blocks audio.mjs imports (init.sh --painting only)
-storyboard.md     the plan
-curves.json       plate starts and per-frame curves for the sound, written by export-curves, ignored by git
-scripts/          look, check, render, build, make, export-curves, inject, portrait, trace, doctor
-shots/            frames and sheets for eyes, ignored by git
-frames/           PNG frames, ignored by git
-package.json      npm scripts and the puppeteer dependency
-```