@autoaiai/aicut 0.1.11 → 0.1.13

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

@@ -1,72 +0,0 @@
-# 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

@@ -1,46 +0,0 @@
-# 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

@@ -1,121 +0,0 @@
-# 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.

package/skills/anidoodle/references/motion-grammar.md

@@ -1,234 +0,0 @@
-# Motion grammar: six ways to get from one picture to the next
-
-A film that shows one good thing, then another unrelated good thing, reads as a slideshow however
-well each is animated. These six mechanisms are ways to make the next picture come OUT of the
-current one. They are a grammar to compose from, never presets: pick the one the story is already
-asking for, and build it for that film's subject and medium.
-
-**The default does not change.** A gentle move (a bloom, a flip, a push) is still the standard
-seam (`workflows/launch-video.md`, Motion). Each mechanism below is a judgement with conditions.
-If its "use it when" does not clearly hold, use the gentle move.
-
-Three things hold for all six:
-
-- **The destination is in place before the move starts.** The next scene is already drawn under
-  or behind the move, so there is never an empty frame between scenes.
-- **Something is carried across**: a shape, a position, a direction of travel. That is what
-  separates a designed seam from a transition laid over a join.
-- **One or two mechanisms a film, each used for the seams that matter.** All six in 30 seconds is
-  a demo reel of moves, not a story.
-
-## 1. Foreground as transition
-
-Something already in the scene (a word, a mark, a shape) grows or sweeps until it covers the
-frame, and when it clears the next scene is there.
-
-- **Use it when** the covering thing is part of the story (the brand's ink, the product's mark,
-  the claim itself) and the two scenes share nothing else to carry across.
-- **Not when** the cover would be an arbitrary shape brought in only to hide the join, or when it
-  would happen on every seam: the third time, it reads as a wipe preset.
-- **Ours**: the type frames of the launch film (`launch3.ts`, `typeFrame` in `launchCut.ts`). Ink
-  blooms open from a point over the picture, the word letters itself on the page inside the
-  bloom, and the ink closes to a point on the NEXT picture. The bloom takes the content frame it
-  opens over and the one it closes onto as data (`type(lines, len, before, after)`), so the next
-  scene is always waiting under it.
-
-## 2. Persistent actor
-
-One object keeps its identity through the whole film while the scenes change around it.
-
-- **Use it when** the story already owns such an object (a cursor, the product's dot, a
-  character, a line being drawn) and it has a reason to be in every scene it visits.
-- **Not when** it has to be invented for the purpose, or dragged through scenes where it does
-  nothing: a mascot that only watches is decoration.
-- **Ours**: the ink drop in the launch template (`launchTemplate.ts`). Every press of Generate
-  sends a drop into the thread, where it blooms into the answer card; at the end it lifts off
-  Generate one last time, lands as the dot of the end card's mark, and the end card opens from
-  it. `motif.ts` holds it to the rule: same screen position and size on both sides of the seam,
-  within 2 px, or `checkRelay` throws.
-
-- **The general move**: `engine/src/canvas-core/morph.ts`. `handoff({ from, to, t0, t1 })` carries
-  one outline from a source shape to a target shape: it travels, stretches a little while it is
-  moving, and becomes the target in the second half of the trip, landing on it exactly.
-  `coverShape` grows a shape until it is the whole page. Keep the object's colour and edge the
-  same on both sides, and hold the seam with `checkShapes` (2 px). `morphDemo.ts`: a full stop
-  becomes a card, the card becomes the page.
-
-## 3. Selection to expansion
-
-One item in a set is picked, and it grows until it IS the next scene.
-
-- **Use it when** the story moves from many to one: a wall of options, then the one being used;
-  a list, then the item opened. The viewer sees where the next scene came from.
-- **Not when** the set was only there to be left (build the set because the story needs range,
-  not as a launch pad), or when the item's small and full-frame versions do not match: frame the
-  full scene's first frame exactly like the card it grew from.
-- **Ours**: the style wall (`launchGallery.ts`, used in `launch2.ts`). The camera punches into
-  cards and comes back out; the last punch does not come back, the card fills the frame and
-  becomes the scene. The koi does the same from a still: `koiWorld.ts` frames its first frame
-  exactly like the koi plate, so the card hands over to the swimming world with no seam.
-
-## 4. Registered decomposition
-
-A whole stays recognisable while its parts move into groups, each part traceable from where it
-was to where it lands.
-
-- **Use it when** the point is that the product sorts, extracts or reorganises something the
-  viewer has just seen: a crowded week becoming a plan, a document becoming fields.
-- **Not when** the parts cannot be followed. Past about seven moving at once, or with parts that
-  cross paths, the viewer loses the map; stagger them, or move groups rather than items.
-- **Ours**: `productUI.ts` (a `kind: "ui"` ask in the launch template). The interface is drawn
-  from data in two states. One press of the product's action and every item, matched by id,
-  springs from its place in the before state to its place in the after: rows travel to their new
-  slots, values count to their new numbers, new items arrive, old ones leave.
-
-## 5. Continuous canvas
-
-All the scenes live in one layout bigger than the frame, and the camera travels between them
-instead of cutting.
-
-- **Use it when** the places are really related in space (sections of one page, rooms of one
-  building, steps along one path) and the route between them tells the viewer how.
-- **Not when** the places are unrelated (the travel then invents a relationship that is not
-  there), or when the journey between two stops is long and empty: every second must change
-  (`craft-bar.md`, no dead air). One camera for every plane (`camera.md`).
-- **Ours**: `webTour.ts`. Three sections on one long page, a visible cursor, and a camera that
-  shows the whole page, then pushes in on every click and every field. `koiWorld.ts` is the
-  drawn version: a pond much bigger than the frame, with the scenery placed in the world so it
-  changes as the fish travels.
-
-## 6. Exploded layers
-
-One object separates into its layers along its depth, holds so each can be read, then closes
-back into the object.
-
-- **Use it when** what is inside is the point: how a thing is built, what a stack is made of.
-  The layers must be real parts of the subject, in their real order.
-- **Not when** the subject has no true layers and they would be invented for the effect, or when
-  the pieces are not held long enough apart to be read. If it never closes again, it is a
-  diagram, which may be what the film wants; decide which.
-- **Ours, in one direction only**: `paperCraft.ts`, the toy theatre. The scene is built from the
-  back, flat by flat, with real gaps between the flats: each piece travels held above the stack,
-  its shadow wide and far, and the shadow closes as it lands. That is the closing half. No film
-  of ours yet starts whole and separates; treat the opening half as unproven until one does.
-
-## Three ready-made seams
-
-For a plain change of scene that still wants a made mark, `engine/src/canvas-core/transitions.ts`
-has three calls. Each takes the two scenes as draw functions and a progress, at any frame size,
-with the incoming scene already complete underneath. `transitionsDemo.ts` shows each once.
-
-- **`brushWipe`**: a loaded brush pulled across; with `ink`, a band of wet ink ahead of the new
-  picture (without it, a clean bristled edge).
-  For the drawn register, in the direction the story is already moving. Not in the clean
-  register, and not more than once or twice a film.
-- **`iris`**: a round opening from a point, or closing to one. Open it from the thing the next
-  scene is about, close it on the thing this one was about; centred on nothing it is only a
-  shape. `shape: "blot"` for ink, the plain circle for the clean register.
-- **`flashCut`**: a hard cut under a short burst of light, so the hard cut's conditions apply
-  (a strong beat, in a piece whose energy asks for it). Never one frame, never full white by
-  default, never repeated quickly: declare a film's flashes to `checkFlashes`, which throws on
-  any two within half a second.
-
-## Cuts that carry motion
-
-A hard cut between two shots that are both moving can be the smoothest seam there is, or the
-roughest. The difference is arithmetic, and `engine/src/canvas-core/seams.ts` does it.
-
-- **Both sides at rest, or both at one speed.** A cut from a moving shot to a still one (or the
-  other way) reads as a jerk. So does a cut where the travel turns, halves or doubles.
-- **Accelerate out, cut after the fastest frame, arrive and settle.** The outgoing shot speeds up
-  over about 0.2 to 0.4 s; the incoming shot opens at that same speed, in that same screen
-  direction, and comes to rest over 0.8 to 1.4 s. The exit is the short side.
-  `matchedMove({ dir, exitDist, exitF, entryF })` gives both halves, to add to each scene's
-  camera look; the entry distance is worked out from the exit speed, so the two always agree.
-  The incoming shot owns the cut frame: the outgoing shot's last frame on screen is the one
-  before it, and that is its fastest.
-- **Through the cut, in depth.** `matchedZoom({ push, exitF, entryF })` does the same for a
-  camera that flies into one shot and out in the next: a dolly push through the cut. A push is a
-  ratio, so both sides run in log space and grow at the same rate per frame across the cut. With the default push the
-  incoming shot opens at about two thirds of its size, so its scene must be painted that much
-  wider than the frame; a zoom that would open it under 0.4 is refused.
-- **There is a top speed.** Past about two and a half frame widths a second
-  (`speedCeiling(W, fps)`), blur stops reading as motion and shows as a streak with stepped
-  copies. A move that needs more than that wants a shorter travel with the rest hidden behind
-  the cut, or a plain cut on the beat. Render fast seams with `--blur auto`.
-- **Match everything, once.** Whatever crosses the cut keeps its position, size, colour and
-  edge; a property that flips on the cut frame pops. And the resting pose is shown once: if one
-  shot settles onto a pose and the next opens on it, the first shot's last frame is the move's
-  last in-between, never the pose itself, or the film stops, holds and goes.
-- **Never dissolve two copies of one thing.** At the halfway point both are half there and the
-  eye sees a ghost. Move one object; change what it is at the middle of its trip.
-
-`checkSeam(velocity before, velocity after, { W, fps })` returns what is wrong with a cut, or
-nothing: one side at rest, a turn of more than 30 degrees, a speed that drops or jumps. `checkSeamPlan` reads the film's list of seams and flags a designed seam used a third
-time; plain and matched cuts are exempt, and the film's one signature move gets three (the open,
-the middle, the close). Use this when both scenes have room to travel the same way. When they do
-not, bring both to rest and cut on a beat.
-
-## Dealing a hand
-
-Left to choose, every film reaches for the same three moves. `node tools/deck.mjs deal --kind
-story --energy high --seconds 27` deals a hand from `references/motion-deck.json`: an opening, a
-close and a spread of seams, camera moves, reveals and acting notes, each with its numbers, its
-engine call and when not to use it. The deal is weighted toward what fits the film and is
-repeatable from its printed seed; `--avoid` keeps the next film off the last one's cards.
-
-A card is a prompt, never an order. Keep it, adapt it to this film's subject and medium, or drop
-it, and say which in the brief. The default at the top of this page still holds: a card whose
-"not when" applies is dropped, and the gentle move takes its place.
-
-## Names people use
-
-People ask for moves by the names they know: a whip pan, a mask reveal, a Vertigo shot, a J-cut.
-`node tools/deck.mjs find "<name>"` routes the words to the card that builds it, to an engine call
-that is not a card (an iris, a lens zoom, a typewriter), or to a refusal. Every card carries those
-names in its `aka`. Run it before building anything named, so a word never turns into an
-improvised effect; the card's numbers are the default unless the person gave their own
-(`workflows/start-here.md`, When they name a move).
-
-## Names we refuse
-
-Some names ask for an effect that breaks the contract or the craft bar. Say so in one line and
-offer the alternative; `deck.mjs find` prints the same reason.
-
-| Name | Why not | Make instead |
-|---|---|---|
-| glitch | colour split and torn pixels are a template overlay with no cause in the picture | a cut on the beat, or one shake on a real impact |
-| light sweep | a shine sliding over chrome that nothing in the picture casts | `reveal-by-light`: the light belongs to the world |
-| fade-in | marks are made, not faded or scaled up from nothing; a tell on the craft bar | drawn on, revealed from behind, or written |
-| particle burst | decoration with no force behind it, never a default | `emph-contact`: dust or splash born on a real contact |
-| cross dissolve | two copies of one thing read as a ghost; unrelated pictures, a slideshow join (a poster frame or a reduced-motion fallback may still dissolve) | one object moving and changing mid-trip; the gentle move |
-| lens flare | lens artefacts (flare, leaks, bokeh discs) painted onto a drawing read as stock overlays | one named light in the scene, or `reveal-by-light` |
-
-## Callouts and the label handoff
-
-`engine/src/canvas-core/callout.ts` names one thing in the picture: a dot lands on it, a leader
-line is drawn out, a label is written at the end. The dot follows the thing as the camera moves
-(pin it with `cam.toScreen`, `camera.md`); the label holds still so it can be read. It is type
-over the picture, so that judgement applies in full (`workflows/launch-video.md`, Type): a calm
-area, a label that names what it points at, one or two on screen at a time. Where the picture is
-busy, give the label a `backing` or leave the callout out.
-
-The label can also be the persistent actor across a seam. With `handoff`, the dot and line
-retract and the label travels to where the next scene starts, landing as its heading on that
-scene's first frame; the next scene draws it from there with `drawLabel` at the same pose.
-`checkHandoff` holds the two sides to within 2 px and throws if the seam jumps.
-`calloutDemo.ts` shows both.
-
-## Choosing
-
-Ask what the seam has to tell the viewer, then take the mechanism that says it:
-
-| The seam says | Mechanism |
-|---|---|
-| "and now this", with nothing shared but the brand | Foreground as transition |
-| "the same thing, further along" | Persistent actor |
-| "this one, out of all of those" | Selection to expansion |
-| "the same things, put in order" | Registered decomposition |
-| "next to that, over here" | Continuous canvas |
-| "and this is what is inside" | Exploded layers |
-
-If none of these is what the seam says, it is a plain change of scene: use the gentle move, or
-a matched hard cut where its conditions hold. Review every designed seam as a before/after pair
-of stills, and as a strip of the frames between them, before the film is rendered in full.