@autoaiai/aicut 0.1.7 → 0.1.11

package/skills/anidoodle/references/backends-and-adapters.md

@@ -0,0 +1,82 @@
+# Backends and adapters
+
+One art core, four backends, and the core cannot see any of them. An adapter is the only thing
+that knows how a film becomes pixels.
+
+## The interface
+
+Every adapter exports the same four things, so `tools/gate.mjs` can hold any of them to the same
+bar without knowing which it has:
+
+```js
+export const name = "html-player";
+export const describe = () => "one sentence: what this adapter DELIVERS";
+export const probe = () => ({ ok, why });        // can it run here, and if not, why not
+export const open = async (film, { scale, workers }) => session;
+```
+
+A session is:
+
+```js
+{ workers,                  // how many independent draw contexts it actually opened
+  info(),                   // -> film.meta
+  frame(n, w),              // -> { png: Buffer, shot, drawMs }
+  hash(n, w),               // -> stable digest of the drawn pixels
+  audio(sampleRate),        // -> { sampleRate, frames, pcm16 } | null
+  artifact(),               // -> the adapter's own deliverable, or null
+  close() }
+```
+
+`workers` is the number of independent contexts, and the gate uses it to redraw the same frames a
+different way. That is a stronger test than it sounds: each instance has its own texture tiles,
+its own layer pool and its own cache, so two instances agreeing means the caches are genuinely
+keyed on what the pixels depend on and not on the order somebody happened to ask for frames in.
+
+## The four
+
+| Adapter | Delivers | Needs |
+|---|---|---|
+| `playwright` | frames, as a means to an MP4 | playwright + a chromium build |
+| `html-player` | **the page**: one self-contained offline HTML file | playwright + a chromium build |
+| `remotion` | frames through a Remotion `<Composition>` | `remotion`, `@remotion/bundler`, `@remotion/renderer` |
+| `hyperframes` | frames seeked in headless Chrome by the Hyperframes engine | `@hyperframes/engine`, Node >= 22, ffmpeg |
+
+## Warm and cold catch different bugs
+
+This is the one thing to carry away.
+
+- **`html-player` shares one warm cache across frames.** It can catch a cache key that fails to
+  name everything its pixels depend on, because it draws frame 512 and then frame 128 into the
+  same session and compares.
+- **`remotion` renders every frame COLD** — each still is its own page, its own module state, its
+  own cache. It proves frame N owes nothing to the frames before it, and it **cannot** catch a
+  stale cache, because there never is one.
+
+On this film a real order-dependence sat in the plate composer: five cached surfaces baked the
+line's "boil" into their pixels while leaving it out of their key. The warm adapter found it and
+named the poisoning frame. The cold adapter passed happily. **Run both. Neither is the whole bar.**
+
+## Writing a new one
+
+Ninety percent of an adapter is plumbing; the film is already a pure function of the frame number,
+which is what every one of these backends actually wants. Two traps, both paid for:
+
+- **Remotion screenshots when React commits**, and a committed `<canvas>` is a blank one until the
+  effect runs. Hold the frame with `delayRender` / `continueRender` around the draw or you will
+  ship empty plates that pass every hash check, because they are consistently empty.
+- **Do not pass the film through props.** A `Film` carries functions (every shot's `draw`, the
+  score) and most frameworks serialize props. Close over it instead.
+
+For a backend that drives a **seekable page** rather than a component, the page-side contract is
+small and this engine already satisfies it: a finite frame count, forward, backward and random
+seeks, and the same state whenever the same frame is asked for again. `window.FILM.seek(n)` is the
+whole implementation. `tools/verify-frame-adapter.mjs` holds such an adapter to that contract
+using playwright, which means you can prove the page-side half **before** the backend is installed.
+
+## If a backend is not installed
+
+Say so. Keep every reference behind a dynamic import inside `open()` so the file imports clean,
+make `probe()` name what is missing and how to get it, and let the gate report `CANNOT RUN`
+(exit 2) rather than failing. Then check that the module really exports what you are about to
+call, and if it does not, say what it exported instead. A backend that is not installed should
+report that it is not installed — it should never quietly produce a wrong answer.

package/skills/anidoodle/references/camera.md

@@ -0,0 +1,148 @@
+# The camera: one dolly and one lens, keyed on the frame grid
+
+`engine/src/canvas-core/camera.ts` is the camera. A film either draws in world coordinates
+inside `begin()`/`end()` (the transform path: dirty boxes stay right because the camera rides
+the `Gfx` transform stack), or asks `toScreen()` where a world point lands and draws there (the
+projector path). Both come from the same state, so a caption pinned to the frame and the world
+it floats over can never disagree. Everything is a pure function of the frame: the same camera
+question gets the same answer on any machine, in any order.
+
+## The move
+
+```ts
+import { Camera } from "./camera";
+
+const cam = new Camera([W / 2, H / 2], [
+  { f: 0,   look: [400, 300], zoom: 1, ease: "inout" }, // ease governs the segment this key LEAVES
+  { f: 90,  look: [900, 300], zoom: 2 },
+  { f: 150, look: [900, 300], zoom: 2 },                // a hold: say it, don't imply it
+  { f: 240, look: [400, 300], zoom: 1 },
+]);
+cam.shake({ from: 96, to: 126, amp: 14, seed: 7, rot: 0.004 }); // an impact, ringing down
+```
+
+- **The `zoom` key is the dolly**: how close the camera stands (see Lens and dolly below). It is
+  interpolated in log2, because it is a ratio: halving the apparent size twice should take twice
+  as long as halving it once. Ease the value itself and a long push-in sprints at the near end
+  and crawls at the far one; easing log2(zoom) spends time evenly per stop. A `lens` key eases
+  the same way.
+- **Easing per segment, `inout` (easeInOutCubic) by default.** A camera move with no live
+  operator should accelerate gently and arrive gently. `linear` reads as mechanical, `out`
+  alone reads as interrupted, `in` alone as a fall.
+- **A dolly path with several keys** breathes at every key under per-segment easing. Pass
+  `monoZoom: true` to run one monotone cubic through all the `zoom` keys in log2 instead: smooth,
+  never overshooting into a scale it was not given, never reversing.
+- **Authored paths**: for a camera that follows a creature or a curve, pass
+  `path: (f) => ({ look, zoom, lens? })` instead of keys. Same camera, same shake, same projections.
+
+## Depth planes (parallax)
+
+The camera sits at distance D = 1/zoom from the hero plane (z = 0). A plane at depth z scales
+by `lens/(D + z)` and moves with it: near planes swing wide, far ones barely stir, and every
+element at a depth agrees with every other, because there is only one camera. Positive z
+recedes; a negative z crosses the lens (grass across the glass). Pass the plane's z to
+`begin(g, f, z)` or `toScreen(p, f, z)`. One dolly, one number, and the parallax is true for
+every element at once: do not hand each plane its own drift.
+
+## Lens and dolly
+
+Two different moves make the subject bigger, and directors name them apart:
+
+- **A dolly** moves the camera: the `zoom` key, distance D = 1/zoom. Near planes grow faster than
+  far ones, so the depth changes as it goes. This is a push-in, a pull-back, a dolly in or out.
+- **A lens zoom** changes the focal length with the camera standing still: the `lens` key (1
+  when no key sets it; once one does, frames before the first lens key hold that key's value, so
+  key `lens: 1` where the zoom starts, as below). It multiplies every plane by the same factor about the frame's centre, so nothing
+  shifts against anything else; the picture is magnified, flat. A crash zoom or punch-in is this.
+  It reads as an operator's or a documentary's move, more noticed than a dolly. Use it when that
+  is the voice; for travelling into a world, dolly.
+- **A dolly zoom** does both against each other: the camera dollies while the lens is solved on
+  every frame so the hero plane keeps its size, and the planes behind stretch away (dolly in) or
+  loom (dolly out). The subject holds still in a world that has just changed shape: the moment of
+  realisation (deck card `cam-vertigo-realisation`). It needs at least two planes behind the
+  subject; with nothing behind it, nothing visibly happens.
+
+```ts
+import { Camera, dollyZoom, heroScale } from "./camera";
+
+const lensIn = new Camera(c, [{ f: 0, look, zoom: 1 }, { f: 40, lens: 1, ease: "out" }, { f: 52, lens: 2.2 }]); // a crash zoom
+const dolly = new Camera(c, [{ f: 0, look, zoom: 1 }, { f: 60, zoom: 2.4 }]);
+const vertigo = new Camera(c, [], { path: dollyZoom((f) => dolly.at(f)) }); // holds frame 0's hero scale
+// dollyZoom(path, { hold: 1.5 }) holds a given scale; { at: 30 } holds the scale the path has at frame 30
+```
+
+`heroScale(cam)` is the hero plane's screen scale (dolly times lens), and the line-weight
+compensation `weight(cam)` follows it, for a lens zoom as for a dolly.
+
+## Time: speed ramps, slow motion, freeze frames
+
+`engine/src/canvas-core/timeRemap.ts` maps the film's frame to the scene's frame: draw the world at
+`t.at(f)` instead of `f`. Speed is what you key and scene time is its exact integral, so time is
+continuous, never runs backwards, and stays a pure function of the frame.
+
+```ts
+import { timeRemap } from "./timeRemap";
+
+const t = timeRemap([
+  { f: 84,  speed: 0.3, ramp: 8 },                              // ease into slow motion before the peak
+  { f: 120, speed: 0, keepsMoving: "her name writes itself" },    // freeze: the world stops, the writing does not
+  { f: 150, speed: 1, ramp: 14 },                               // ease back to real time
+]);
+world(g, t.at(f));          // the remapped scene
+name(g, f);                 // the writing, on the film's own frame
+cues.push({ frame: t.filmFrameOf(LANDING), kind: "paper" }); // a sound on a remapped event
+```
+
+- **A ramp eases the speed**, on a smoothstep (or `curve: "linear"`), so it starts and ends with
+  no kick. `ramp` defaults to 0, a deliberate hard change of speed; give it frames to glide. A slowed scene is asked for frames between its frames, so it must
+  draw at fractional time (motion is a function of time, never of a frame counter).
+- **Score and sound stay on real time.** The score never slows; effects are cued by film frame.
+  `filmFrameOf(sceneFrame)` gives the first film frame that shows a scene event, which is where
+  its sound goes.
+- **A freeze must keep something moving.** A `speed: 0` key without `keepsMoving` (in words)
+  throws, and so does a speed under 0.01 (`MIN_SPEED`), which looks frozen without saying so: a frozen frame with nothing moving is dead air, and the gate fails it. Drive the thing
+  that moves (the name being written, the camera still creeping in) from the film's frame `f`.
+  `t.freezes` lists each stop with what keeps moving.
+- **Once a film for each.** One slow motion at the peak, one freeze on the telling pose (deck
+  cards `emph-time-ramp`, `type-freeze-and-name`). The second halves the first.
+
+## Shake
+
+`shake({ from, to, amp, seed, freq, rot, attack })` registers an impact or a handheld stretch:
+
+- **amp in SCREEN pixels**, so the shake reads the same at any dolly or lens; **rot** in radians at full
+  strength, about the frame's centre. A small rotation is what actually sells handheld.
+- The envelope is an **attack ramp** (default 2 frames) into a **squared decay**: full strength
+  at the hit, gone a beat later. An impact rings down; it does not stop mid-air.
+- The motion is **low-frequency gradient noise**, seeded, never white noise per frame. Static
+  per frame reads as a faulty projector; smooth noise reads as mass. `freq` is cycles per frame
+  (default 0.35, about 10 Hz at 30 fps; drop it for a heavier camera).
+- Shake is folded into `shaken(f)`, which `begin` and `toScreen` read, so the drawn world and
+  any projected overlay shake together. `at(f)` stays clean for driving things that must not
+  shake (the score, a cue grid).
+
+## Line weight at close range
+
+Ink is authored at some view; at a screen scale S (dolly times lens) the same nib reads S times
+heavier. Divide stroke widths by `weight(cam)` = S^0.35. Not S: a little weight gain is what
+makes a close-up feel close rather than enlarged.
+
+## The two drawing paths
+
+```ts
+// transform path: the world moves, you draw in world units
+cam.begin(g, f);                    // hero plane
+meadow(g, f);
+cam.end(g);
+cam.begin(g, f, 2.2);               // a farther plane
+hills(g, f);
+cam.end(g);
+
+// projector path: ask where things are, draw them there (cached surfaces, screen-space type)
+const at = cam.toScreen(flower.centre, f, flower.z);
+const k = cam.scaleAt(cam.at(f), flower.z);
+```
+
+`toWorld(s, f, z)` inverts `toScreen`, for hit-testing or for pinning world content to a screen
+point. The camera never touches the context itself, the clock, or `Math.random`: it is
+arithmetic over `(frame, keys, seed)`, which is what keeps the determinism contract intact.

package/skills/anidoodle/references/craft-bar.md

@@ -0,0 +1,72 @@
+# The craft bar
+
+The test: would a proud human illustrator ship this, or is it mechanical shape-assembly?
+
+| The tell | What passes |
+|---|---|
+| A subject built from ellipses and capsules | Hand-placed control points over real anatomy |
+| One style recoloured to look like another | The mark, the edge and the order of marks all change |
+| Boxes and arrows standing for an idea | A real machine that does what the idea describes while you watch, built from many small parts that each have a job (`machines.md`) |
+| A line that stops in the air; a texture cut dead mid-surface | Lines meet another line or an edge; a row of ribs or pins thins out where the surface turns away |
+| Parts floating off or sunk into each other | Parts touch the way real ones do (bolted, resting, butted against), each held by something; zoom to 3x on the joints |
+| Flat colour fields | Wash, then pattern wet-on-damp, then line; one named light; cast shadows |
+| Every stroke the same weight and speed | Long strokes fast, fiddly ones slow, thick-thin, tapered |
+| Even scatter, one flower stamped 200 times | Hand-placed drifts with bare rests; 4-5 authored views per species |
+| Gradient sky, disc sun, oval bokeh | Granulating wash, sun as paper left light, lost edges |
+| Decoration | Every element has a one-line reason or it is not drawn |
+| A row of style vignettes (film) | One arc. The medium changes only when the STORY changes state |
+| Things fade or scale in | Marks are MADE, in the order a hand makes them |
+| Both sides do the same thing at once | One side leads, by a few frames, never half a cycle |
+| A hold | The camera may creep. The subject never stops |
+| People with rubber joints, mitten hands, floating feet | A canon (heads tall for the age), joints within their limits, five fingers where seen, weight over the feet (`anatomy.md`) |
+| The same character drawn differently shot to shot | One character module; shots pose it, never redraw it (`workflows/character-consistency.md`) |
+| A silhouette filled with texture, no mouth line, no toes | Interior contours: mouth, eyelids, nostrils, toes, joins between forms (the detail pass below) |
+| A drawing film where the finished picture fades in | Marks made in the medium's order; the last frames are the still (`workflows/drawing-process.md`) |
+| Words laid over busy art, a face or the UI | Type gets its own frame by default; over the picture only as a composed label or kinetic line on a calm area (`workflows/launch-video.md`, Type) |
+| A loop playing in place and called "alive" | Real travel through a world that changes as the subject moves |
+| An unmatched hard cut or a sharp swoosh between scenes | A gentle move (a bloom, a flip, a push, the card grows into the frame), or a cut matched on shape, position or beat |
+| Site art that brings its own background, so a pale box shows on a page of a different colour | `paper` is set to the page's exact colour and every neutral shifts to suit it; a light and a dark theme come out of the same code (`workflows/site-art.md`) |
+| A part, a cast shadow or a highlight straying into the headline's space | Nothing is drawn in the headline zone, and `tools/placement.mjs` proves it |
+| A spinner drawn as still blades turning slowly | Fainter copies of the blades, each a little further back, over a faint swept shape (`spin`), so it reads as speed |
+
+**No dead air** in anything that moves: something visibly changes in every second, from frame 0.
+Check it with the tool AND by eye: a creeping camera changes every pixel and satisfies the tool
+while the eye sees a still.
+
+
+**Words get time to be read, and a quiet ground.** A text stays on screen at least
+`max(0.7 s, 0.3 s per word)`: "ART OUT." needs 0.7 s, a six-word line 1.8 s. Count from the frame
+the last word is whole, and give a slower audience (children, a second language) more. Text is
+never set over a busy picture without a plate under it: a solid or softly tinted panel, a scrim, or
+a clear patch of the drawing, so every letter has a ground it can be read against. Squint at the
+frame; if a letter disappears, the plate is missing. `framecheck.mjs` holds the first rule on every
+declared text cue (`meta.captions`) and reports N/A for a film that declares none; the second is a
+review finding (`workflows/review.md`), because only an eye can judge busy.
+
+**Judge the design, not only the collisions.** A review still can have nothing overlapping and
+still fail: no hierarchy, cramped spacing, a frame that would not pass as a poster. Look at each
+review frame as a designer first, a checker second.
+
+**Preview options before full renders.** When a choice is open (a transition, a lettering
+medium, a palette), show a cheap still sheet of the options side by side and let the person
+pick. A full render per option spends the most expensive resource on the cheapest question.
+
+## The detail pass (run it on every piece before showing it)
+
+A silhouette filled with texture is not a drawing. Before any still, recreation or character is
+shown, crop into it at full size and check the interior, because that is where a viewer looks:
+
+- **Faces**: the mouth line and the split of the upper lip, the chin, the nose's outline and
+  nostrils, both eyelids and the inner corner of the eye, brow markings, the ear's inner rim.
+- **Hands, paws and feet**: every finger or toe separated, knuckles and pads where they show, nails
+  or claws, the way the foot meets the ground (contact shadow, weight).
+- **Joins between forms**: where a leg meets the body, where an arm crosses the chest, where cloth
+  folds at a joint. These are contour lines inside the silhouette, thinner than the outline and
+  broken where light hits.
+- **Markings and pattern**: stripes, spots, seams and patches follow the form's surface, not the
+  picture plane.
+- **Recreations from a photo**: trace each of the above from the photo and overlay-check it; tone
+  alone never supplies interior lines.
+
+Each medium says it in its own way (a carved keyblock line, a scratched cut, a pencil accent, a darker
+brick), but none of them may leave it out.

package/skills/anidoodle/references/determinism-and-contract.md

@@ -0,0 +1,46 @@
+# Determinism, or it is not a film, it is a performance
+
+> Doctrine earned making MECHANICAL LEPIDOPTERA, the worked example in `example/`. Every rule
+> below was paid for on that film; where a mistake was the director's own it says so, because
+> a rule with its scar attached is one people keep.
+
+**Why.** "Backend-agnostic" is a promise that a frame is a fact. Frame 731 is the same pixels on a laptop, in CI, inside Remotion at concurrency 8, rendered first or last or alone. Every convenience you allow yourself breaks that promise somewhere you will not be looking: parallel renderers draw frames out of order, Safari has no `ctx.filter`, a fetched font arrives late once in fifty runs.
+
+**The contract.**
+1. `renderFrame(frame, env)` is PURE. No state carried between frames, no module-level mutable state that touches pixels. Audio is the same: samples are a pure function of the sample rate.
+2. Randomness only from `rng(seed)`. Never `Math.random`. Never `Date`, never `performance.now` in the core; timing belongs to hosts.
+3. A restricted canvas: paths, fill, stroke, clip, transforms, alpha, composite operations, patterns, gradients, `drawImage`, image data, `fillText` with a preloaded font. **No `ctx.filter` in any form.** No DOM, no `window`, no `new OffscreenCanvas` or `new Image`; surfaces come from `env.canvas()`.
+4. **No assets.** No images, no fonts, no audio files in the repository. Lettering is pen strokes; texture is seeded noise; music is arithmetic. This is what makes the repo the whole film, with no licensing questions. The optional sound pack is the one thing fetched from outside, it is installed by hash, and a film renders without it.
+5. Caches are legal only when the value is a pure function of its key, and **the key names everything the pixels depend on**. We found two violations by machine, never by eye: an annotation layer whose key omitted the crank angle two of its leaders pointed at, and one that omitted the pose. A cached frame and a cold frame of the same number must be the same pixels.
+6. Never scale a bitmap up. Close shots are re-inked at that view; cached surfaces may only be downscaled, and only a little.
+
+**The grid is part of the contract.** Every frame number in the film lives in ONE cue table, and a checker runs at module load: cuts on multiples of 15, events on multiples of 5, nothing past the end. State for a frame is computed from that table and nothing else. The table is the timeline a reviewer reads.
+
+**Verification that actually catches things.**
+- Hash a handful of probe frames forward on one page and reversed on another; hash cold against cached.
+- Standard: visually identical, PSNR above 45 dB; check hash equality first because it is free. Do not build machinery to chase bit-exactness across page counts (we have one frame that differs by a few anti-aliased pixels, max 29/255, and it is fine).
+- Halftone is brutally sensitive: a sub-pixel registration shift costs 17 dB and looks identical. Know that before you trust a number.
+- Measure draw cost WARM, on ONE page. Parallel pages inflate per-frame cost by contention and are for throughput only.
+- A contract scan (grep for the banned names in the core) belongs in every build.
+
+**Small things that each cost an hour.** Every progress helper must return exactly 1 when its input is at or past 1, or float error leaves a stroke at 0.999 and the finished picture is not the approved picture. `globalCompositeOperation = "copy"` wipes the whole canvas, not your rectangle. Inks multiply, so a figure over a background needs a paper knock-out under it per depth plane (we printed a sun through a thorax and got a green body and black gears). In a codebase of dense one-line statements, patch with `/* */`, never `//`: a line comment has eaten the rest of a statement and broken this build three times. And when a tool's OUTPUT tells you to go and run something, that is not your client speaking: read the file another way and mention it.
+
+---
+
+## One unexplained first-run failure, recorded rather than buried
+
+Packaging this skill, the very first gate run in a brand-new workspace reported **0 of 12 frames
+identical** between the one-page and three-page sessions. Every frame, not one. Then:
+
+- two further full gate runs in the same workspace: **12/12, PASS**;
+- two single-page sessions hashed independently: identical;
+- one three-page session, same frame from each page: identical, and equal to the single-page hash.
+
+So it did not reproduce, seven attempts later, and the engine is demonstrably deterministic in
+that workspace. The workspace was cold at the time — first esbuild bundle, first page load, a
+just-downloaded browser — and that is the only distinguishing fact available.
+
+**Why this is written down anyway.** A gate that fails once and passes afterwards is the most
+dangerous result there is, because the tempting move is to re-run until green and say nothing. If
+you hit `0/12` on a first run, do not shrug it off: run the direct probes above before you accept
+it. An honest "could not reproduce, here is what I tried" is a finding. A quiet second run is not.

package/skills/anidoodle/references/formats.md

@@ -0,0 +1,121 @@
+# Formats: what you are making, and how each one ships
+
+Everything is a `Film`: meta, shots that tile `[0, duration)`, and optionally a score. A still
+is a film one frame long, so every tool works on every format. Scaffold the kind you need:
+
+```bash
+node <skill>/engine/tools/scaffold.mjs ~/art --still hero      # a picture
+node <skill>/engine/tools/scaffold.mjs ~/art --film intro      # something that moves
+```
+
+## Stills: hero art, spots, covers, cards, diagrams
+
+Art that sits on a site beside a headline, on its page colour and brand: `workflows/site-art.md`.
+
+- **Size is `meta.W` x `meta.H`**, in logical units; `--scale` multiplies it at render time, so
+  one source gives a thumbnail (`--scale 0.5`), the page (`1`) and print (`--scale 3`). Common
+  shapes: 1600x900 web hero, 1200x630 social card, 1080x1080 square post, 1080x1350 portrait
+  post, 2550x3300 letter at 300 dpi.
+- **`node tools/still.mjs hero --out out/hero.png`** draws it twice and prints `reproducible`
+  when both hashes agree. That line is the receipt that the same file will come back tomorrow.
+  Several frames of a moving piece in one browser: `--frames 0,450,900` (or `0-900:150`), with
+  `--sheet out/sheet.jpg` for a contact sheet at 0.4 scale (`working-method.md`).
+- **Transparent background**: skip the paper fill and the page stays clear, so a spot
+  illustration or an icon drops onto any website colour. Leave `g.paper()` off as well: over
+  clear pixels it lays its grain down as a grey veil. Carry the tooth in the marks instead
+  (`ink` and `paint` groups texture themselves).
+- **A series** is one draw function and many seeds or parameters: a set of blog headers, a card
+  per team member, a family of empty states. Put the variation in a table at the top of the
+  module and render each row; `styleGallery.ts` shows how several plates compose onto one sheet.
+- **An explainer or infographic** still: draw the thing, then label it with `drafting.ts`
+  `letter()` and leader lines drawn with `g.pen`. Numbers are content, so every figure on the
+  plate comes from a named source in a comment beside it.
+
+The approval gate for a still is the still itself: one render, a written self-critique against
+the craft table, then show it.
+
+## Motion without a story: loops, stickers, logos, ambient art
+
+- **Seamless loop**: drive everything from `t = local / DURATION` through functions that repeat
+  a whole number of times over `[0, 1)` (`sin(2 * PI * k * t)`, integer `k`). Frame `DURATION`
+  then equals frame 0 and the seam disappears. Check it: render the last frame and frame 0 and
+  compare them to a mid-loop neighbour pair, or run `node tools/verify-export.mjs <name> --loop`
+  on the rendered file, which judges the last-to-first step against the loop's own mid-loop
+  deltas.
+- **Animated logo / sticker**: 2 to 4 seconds, the mark DRAWN on (`progress` on `g.pen`,
+  `letter`), a settle, a small idle. Leave the background unpainted for transparency.
+- **Ambient / idle art** (a site header that breathes, a banner): the subject never stops; the
+  motion is small and everywhere. `banner.ts` is the worked example.
+- **Dead air still applies**: the gate measures it on any piece longer than one frame.
+
+## Films: the story ones
+
+30 to 90 seconds, a transformation, a score, the full workflow in `SKILL.md`, the doctrine in
+`storytelling.md`, `music/README.md` and `working-method.md`. `example/` is the worked one.
+
+## Delivering
+
+| Output | Command | For |
+|---|---|---|
+| PNG | `node tools/still.mjs <name> --out out/x.png [--scale 2]` | stills, print, anything static |
+| MP4 | `node tools/render.mjs <name>` | films with their score, social video |
+| GIF | `node tools/render.mjs <name> --out out/x.gif [--width 640] [--gif-fps 15]` | loops, README heroes, email |
+| WebM | `node tools/render.mjs <name> --out out/x.webm [--width 512]` | stickers and overlays, alpha kept (VP9) |
+| APNG | `node tools/render.mjs <name> --out out/x.apng [--width 512]` | alpha loops that play in every browser |
+| HTML | `node tools/emit.mjs <name> --out out/x.html` | the piece itself: one offline file that redraws it, with sound, on a double-click |
+
+Render options that hold for every moving format:
+
+- `--poster-frame N [--poster-fade 6]`: platforms show frame 0 as the thumbnail. The file opens
+  on frame N (the wall of styles, the logo, the prompt written big) and dissolves into the real
+  opening by frame 6. The frame count and the score are unchanged. A delivery whose frame 0 is
+  near-blank gets a warning after the encode.
+- `--blur auto` (or `--blur N`): motion blur, each output frame the average of subframes over the
+  shutter, in linear light and weighted by alpha (so a transparent WebM or APNG gets no dark
+  fringe). `auto` measures each frame's on-screen motion (two sharp renders at the shutter's ends,
+  block-matched; drawing strokes, typed letters and halftone patterns are not mistaken for motion)
+  and takes subframes at most `--blur-px` apart (default 3 px): 1 on a still frame, which comes out
+  untouched, up to `--blur-max` (32) on a whip. Deterministic. `--shutter DEG` is the shutter
+  angle, 180 by default (360 is the old whole-frame shutter). Stepped art (`meta.step` > 1,
+  `onTwos`) is never blurred.
+- `--shapes 16x9,1x1,4x5,9x16`: a launch template film rendered in each shape from one timeline
+  (each re-composed by its layout, never cropped) to `out/<name>-<shape>.mp4`. Any tool takes
+  `<name>-<shape>` as the film's name for one shape.
+- `--from F --to T`: frames `[F, T)` only, silent, written to `out/<name>.<F>-<T>.<ext>`, never
+  over the finished film. For checking a passage, not for shipping.
+- `--hashes out/x.md5`: the md5 of every frame handed to the encoder, for frame-exact
+  comparisons of two renders before any codec blurs the difference.
+
+Words on screen, wherever the shape:
+
+- **Reading time.** Each text stays up at least `max(0.7 s, 0.3 s per word)`. A launch film's cues
+  are `meta.captions`; `node tools/framecheck.mjs <name>` fails any cue held shorter and reports
+  `N/A` for a film that declares no cues (it cannot see words it was not told about).
+- **No text on a busy picture without a plate** (`craft-bar.md`).
+- **Phone safe zones, 9:16 only.** Reels, TikTok and Shorts lay their own name, caption, buttons
+  and progress bar over the frame. Keep text and key content out of the top 14 % and bottom 25 %
+  of the height, and the right 14 % of the width (the button column) between them. The shares are
+  the cautious end of the creator safe-area guidance those apps publish for vertical video,
+  rounded up; their layouts change, so re-check before a campaign. `framecheck.mjs` finds text in
+  those zones on any 9:16 frame (`SAFE-ZONES`) and `launch.mjs ship` fails the shape for it
+  (`--zones warn` only flags it). The launch template composes its 9:16 layout inside the safe
+  rectangle: the chat, the words, the split beat, the end card and the corner mark, with burned-in
+  captions (`captions: "burn"`) in a band at the safe rectangle's bottom. The background still fills
+  the frame. Other shapes report N/A.
+- **Claims** in a film, on screen or spoken, are listed with their sources in `facts.json`
+  (`workflows/facts.md`).
+
+After any encode, `node tools/verify-export.mjs <name> [--first-frame #hex] [--fidelity-psnr 40]`
+proves the file on disk is the film: size, exact frame count, duration, the score (an audio
+stream exactly when the film has one, as long as the picture, not silent), its SYNC (the decoded
+sound cross-correlated with the master mix at each of `meta.sync`'s markers, within 1 ms, and each
+cue's attack where the master put it), its true peak after the encode (-1 dBTP under
+`--delivery`), and optionally the
+first frame's average colour and its fidelity to the source frame (`--frame N` picks which
+frame `--fidelity-psnr` compares; default 0). All of it is opt-in beyond the container facts,
+so transparent and non-uniform pieces pass cleanly. For a file that ships, add `--delivery`: a
+near-blank frame 0 then FAILS instead of warning; the fix is `render --poster-frame N`.
+
+A still needs a browser only (`npx playwright-core install chromium`). Anything that moves also needs
+`ffmpeg`. `gate.mjs` runs on all of them and marks the checks that do not apply to the piece,
+a silent loop's audio or a still's dead air, as `----` rather than passing them.