[umiyosh]

Summary

Gives html films more expressive range with five techniques, all chosen by Claude per film from the user's request and the theme. No new options or settings for the user.

Part of #16. Closes #36. Closes #37.

Changes

• references/html-film.md
  • Decide before you build: before writing index.html, Claude writes a short plan as a comment at the top of the page: one idea that carries the whole film, the palette (one accent), type roles, motion rules, and what this film will not use. It is decided from the request and the theme, never asked
  • Restraint: a list of things not to use unless the theme calls for them (particle bursts, glows, lens flares, whole-frame shake, pointless rotation or zoom, too many kinds of motion, bouncing on anything but marks and numbers, long text on screen, unrelated decoration)
  • Join scenes with objects: carry an element across scenes in #stage and turn it into the next scene's part (a card becomes a step, a chart line becomes a connector); clear and rebuild only at chapter changes
  • Kinetic type: headings rise one character at a time with film.typeIn, at most once per scene; move a word the way it means
  • Show the real mechanism: run a small seeded simulation, use real numbers, exploded views, or a continuous zoom with a scale, instead of drawing something that looks like it
• kit/player.js: film.typeIn(tl, el, at, { dur, stagger }) splits an element's text into one span per character (Latin words and numbers stay whole) and raises them from below a mask line. Characters are hidden until their turn, so the layout check does not see them sticking out of the line
• kit/base.css: the mask and character styles for typeIn
• SKILL.md (3B): write the plan before the page
• Two fixes found while making films with this guide (film.spot cannot measure SVG elements #36, Catch an id used twice in an html film #37):
  • film.spot and film.arc now measure SVG elements: an <svg> icon (it has no offsetLeft, so the offsets came out NaN) and a shape inside a diagram whose viewBox scales it (GSAP moves it in the svg's own units, so the move was off by the scale). Agents no longer need to wrap icons in a div
  • a page that uses an id twice now fails to load, naming the id. A selector #id reaches every element with it, so a chip named like its scene hid the whole scene. The check also caught a past film (WIF v4) whose STS scene was drawn at 35% opacity because a card shared the scene's id

Left out on purpose: a set of visual styles (paper and pencil, blueprint, collage). It needs each style checked against the layout check and render time, so it can come after v1.

Inspired by prompts collected in awesome-opus5-5-videos (each prompt belongs to its creator). Only the techniques were taken; the guide and code are written from scratch, with no prompt text copied.

Demo

The 194 s "loop engineering" film was remade with the same script, narration, BGM and sound effects, following the new guide:

• the plan comment at the top of the page
• one loop ring carried across three scenes: it takes the prompting seat, becomes the top floor above the harness, then grows into the plan-act-check-judge cycle
• every scene heading, the title and the closing line rise with film.typeIn
• decorative shakes removed (only rejection and failure shake now)
• "trust what you can check": a seeded simulation of work items; the cheap check lets them flow, the person in front of the costly one builds a queue

check reports no layout issues; the build took 4 min 23 s with 7 pages.

A second film, "the AI-native SDLC playbook" (155.7 s, 14 scenes), was made with this branch including the two fixes: six stages start in a row, become a ring that stays to the end, and a file chip travels the ring as intent.md, spec.md, plan.md, diff and tests, and PR. A point inside the metric chart (an SVG shape in a scaled viewBox) and a bell icon (an <svg> root) are moved with film.spot / film.arc. check reports no layout issues.

Test plan

• make check: lint, format, typecheck, 110 tests with the coverage gate, quality gates
• New test: film.typeIn hides the characters before their turn, keeps Latin words whole, settles them on one baseline left to right, and the page has no layout issues
• New tests: an <svg> icon and a shape inside a 2x viewBox reach their targets; a page with an id used twice fails to load. Both fail on the player before the fix
• Six earlier films re-checked with the new player: five pass, WIF v4 stops on its duplicated id (the real bug above)
• End to end: the demo films above (layout check ok, stills reviewed, MP4 194.0 s with video and audio)
• CI