Riso film

Deliver films/<name>/index.html plus a verified MP4 in out/. Every pixel is drawn in Canvas 2D; the deliverable has no libraries, fonts, images or network calls. External subject references may be studied, never embedded. Paths are relative to the repo root; commands run in tools/. Reference exclusions in the user's request take precedence.

1. Direction

Read .claude/rules/riso-plates.md, docs/brief.md and docs/visual-development.md first. Add docs/drawing.md and docs/motion.md for what is being built, docs/characters.md for people, animals or hands, docs/scene-space.md for complex objects, framing, perspective or precise speed changes, and docs/quality-bar.md for print finish and playback defects. Load docs/sound.md only when scoring. examples.md maps techniques to the shipped films; open the matching source before inventing a routine that already exists.

Extract subject, feeling, scope and constraints. For an open aesthetic brief, choose a direction and proceed; if the user asks for proposals, propose first. Write FILM.md early: design decisions, observed references, shot/action plan, user constraints, remaining work.

Plan actions and consequences, not illustrated nouns. Per substantial shot: camera and shot size, what changes, a readable arrival/hold, and where the eye goes at the next cut. Keep subject motion, camera motion, transition and atmosphere distinct. docs/forms/resonance.md is an optional call-and-response form (used by films/lumen and films/emergence); use it only when asked or deliberately chosen. A single journey through one fixed frame (films/window-seat) or one continuous take of one event (films/roost, films/nonpareil, films/eclosion, films/passenger) is an equally valid alternative to a montage. Preserve approved direction in revisions.

2. Prove the hard part first

Before filling a timeline, inspect real subject references and build one representative hard frame. For complex art, compare small viewpoint/value thumbnails first. When the request remakes a known video, measure the file itself (cuts, shots, actions) before choosing what to keep. Figures get debug views and photo comparisons before shots: likeness judged at recognition scale, a posable 3D hand per grip, 3D-solved arms (docs/characters.md). A subject that recurs at several sizes goes on one sheet at its smallest and largest size first. Fix generic silhouettes and inconsistent perspective before adding grain, hatching or more scenes.

Then build a short sample of the hardest action: the subject doing something, not just arriving. Check attachments, mass, timing and aftermath. Encode that sample as soon as it exists (render.mjs --from a --to b) and read its fastest frame at 1:1: strobing, mushy dots and bitrate only show in the MP4. For a long film, make a full-duration silent rough cut before polishing. Set holds and cut lengths from information and action, not equal slots or an inherited timeline. These are working checks, not extra approval steps.

3. Build from a clean engine

node new-riso.mjs --kind film --duration 60 --out ../films/<name>/index.html

Choose the real duration. The generator refuses to overwrite and copies only the print, drawing and motion kits plus tools/lib/visual-kit.mjs; it gives a blank drawArt(t), a player and the __riso contract. Edit the generated HTML directly. Copy routines from donors (prints/workings, studies/index.html, the films in examples.md), never their scenes. When most of the frame moves with tone (parallax, smears, moving gradients), copy the live-plate compositor from films/window-seat/index.html (see docs/live-plates.md).

• Bake static scenes at displayed size. Screen moving geometry in page space. Reproject vectors for camera moves; never resize a screened bitmap.
• Share geometry between marks and their knockouts, and one clock between actions coupled across shots.
• Build in small batches; inspect each scene at its real duration and its render cost. Live plates run 100–200 ms/frame; profile per draw function before optimising (docs/live-plates.md, cost). The generated player buffers slow films, so share MP4s for judging pace.
• Keep __riso.shots = [{id,start,end,readAt,action,transition}] derived from the one authoritative timeline; readAt is a representative visible moment. No second set of timing constants.

4. Review picture and motion

node review.mjs ../films/<name>/index.html
node verify.mjs ../films/<name>/index.html
node shoot.mjs ../films/<name>/index.html --range 6.6:6.9:0.0333333333 --sheet --engine firefox

Use this film's event times. Read every sheet you generate. verify.mjs proves seek purity in both browsers across the actual duration and shot boundaries; it proves repeatability, not beauty or stable adjacent-frame texture, and a sheet cannot judge pacing or choppiness at speed. When it fails, its DIAGNOSIS line names the per-seek state or the earlier frame that poisons the time. Measure the playback defects in docs/quality-bar.md (flicker, jitter, pops, held stretches) and watch a silent range render; docs/motion.md lists the traps that pass verify.

Inspect frame-spaced strips around handoffs, contacts, mask completions and visible wraps, on both sides of each reset. For a retimable effect check 0.5x, 1x and 2x and move coupled clocks and holds together. Settle texture questions on native PNGs or 1:1 crops; reduced sheets invent moiré and hide small subjects. docs/quality-bar.md separates art, construction, print, action, pacing and delivery evidence.

5. Export and finish

node render.mjs ../films/<name>/index.html --from 0 --to 6 --engine firefox --out ../out/section.mp4
node render.mjs ../films/<name>/index.html --fps 30 --size 1080 --engine firefox
node review.mjs ../films/<name>/index.html --mp4 ../out/<name>.mp4

Range renders are silent; render the whole film after picture review. review.mjs --mp4 lists every held stretch with its shot; confirm each is an intended hold (--from for a range render). Score with riso-score first when sound is wanted. Decode the final MP4 and check duration, dimensions, frame count and audio; inspect encoded motion too. Record evidence, remaining weaknesses and anything not reviewed in FILM.md. Technical validity is not the user's artistic approval.

For revisions, read FILM.md and edit the authoritative HTML; never rerun an old assembly script over revised art. Keep the previous render for comparison and preserve approved pacing and score during local fixes. Cut secondary detail before compromising the hard frame, the full progression or verification.

When handing a revision to a fresh session, write a self-contained prompt: the film path; read FILM.md first and treat index.html as authoritative; the user's words quoted; what is approved and must not change, by time range; copy the delivered MP4 and WAV to -v1 before editing; each suspected cause labelled unconfirmed with the check that would confirm it; and how to read the file safely (sampled films carry multi-MB lines). Keep it in the film folder (HANDOVER.md).