# product-film

Adopt this skill: https://proskills.md/skills/other/display-dev-product-film-hermes-design-product-film

Page: https://proskills.md/skills/other/display-dev-product-film-hermes-design-product-film
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: hermes/design/product-film/SKILL.md
size: 16287
sha: 24e78cad7e1f85edf9163c2c0f32fd4dafb7d8fe
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/SKILL.md

````text
---
name: product-film
version: 0.2.0
license: MIT
user-invocable: true
argument-hint: "[<what the film is about> | <film folder to recut>]"
allowed-tools:
  - Bash(ffprobe *)
  - Bash(bash $SKILL_DIR/templates/new-film.sh *)
  - Bash(bash */product-film/templates/new-film.sh *)
  - Bash(bash $SKILL_DIR/scripts/publish.sh *)
  - Bash(bash */product-film/scripts/publish.sh *)
  - Bash(dsp get-metadata *)
  - Bash(dsp comment list *)
description: "Make a short product film (website hero loop, landing section, launch film, feature walkthrough, store-listing promo, social cut, illustrated story film) in which the product appears as its own real UI, drawn frame by frame from an HTML timeline, rendered with Playwright and cut with ffmpeg. Four routes: licensed footage cut against cinematic product beats, product beats only, a pointer-driven walkthrough with captions or text cards (plain or kinetic), or a cut-paper collage in which an illustrated cast tells a story over real UI captured from the code with fictional data. Use when asked for a product film, hero video, promo or demo video, launch film, explainer, walkthrough video, paper or collage film, or to recut one. Not for plain screen recordings or voice-over walkthroughs; laying a supplied music track under a finished cut is in scope."
---

# Product film

Builds short product films, silent unless the user supplies a music track, in which the product is shown as its own real components, drawn frame by frame. Four routes in three registers: cinematic (Routes A and B: a 3D plate and a camera that never stops), plain (Route C: a still plate and a pointer that drives the UI) and illustrated (Route D: a cut-paper cast over real product screenshots, in stop-motion).

- **Route A, with footage.** Licensed live-action cuts of people alternate with product beats. Each product beat follows the human action that motivates it.
- **Route B, pure product.** Product beats only, joined by the plate, with captions or end cards if the surface needs words. For a launch that needs breadth (several capabilities in 25–35 s), the reel style cuts claim-and-proof sections to the music's bar lines on flat brand plates.
- **Route C, walkthrough.** A pointer drives the product through one causal story (select, comment, publish, share). Use it for store-listing promos and feature launch films. The default register is the kinetic style: isolated UI at extreme close-up on white, morphs instead of cuts, kinetic captions, almost no holds. A plain cut with a caption band over one take, or full-screen text cards between shots, is built only when the user asks for it.
- **Route D, paper collage.** An illustrated cast (jointed paper puppets, busts, marker doodles, captions on torn paper strips) tells a story with a problem, a turn and a payoff over real product UI: screenshots rendered by the product's own code on fictional data. Use it for social cuts, pinned posts and explainers where people and product appear together.

| Read | When |
|---|---|
| `references/camera-rig.md` | Routes A and B, before writing a beat: the rig code and the numbers tuned across sixteen cuts. Do not re-derive them. |
| `references/walkthrough.md` | Route C, and any kinetic or reel cut, before anything else: the pointer, flicker, current-UI and true-claims rules, the numbers, the engine, the checks and the pipeline they share. The cinematic defaults (3D rig, glows, particles, grain, drift, tilt, a zoom on every beat) were rejected for these films. |
| `references/kinetic-style.md` | Route C by default, and a Route B film that should feel fast and designed. It changes the look and pacing, not the pointer and flicker rules. |
| `references/reel-style.md` | A launch reel that shows breadth: claim-and-proof sections cut to the music's bar lines on flat brand plates. |
| `references/live-dom.md` | Product UI that must move at close range (typing, hover, menus, state changes): capture the real UI as DOM snapshots on fictional data and mount it live instead of rebuilding it. |
| `references/paper-collage.md` | Route D, before anything else. It replaces the rest of this file for that route. |
| `references/paper-capture.md` | Route D at the capture step, and any route that captures real UI. |
| `references/paper-lessons.md` | Route D, before building scenes and before every review. |
| `references/publish.md` | Before the first review page: publishing on display.dev, one page per film with a version per cut, and the comment loop. |

## When to use

- A new hero, section or launch film is asked for, or an existing one needs a recut, a new beat or a new ending.
- The product has to be shown at fidelity, in motion, without recording the real app.
- A store listing or a launch needs a short demo of a flow.
- A story film with characters is wanted: an illustrated, collage or paper look, or people reacting to the product without footage (Route D).

Not this skill: a plain screen recording of the app used as the film itself, a voice-over walkthrough cut from a screen recording, composing music or voice, or putting a finished file on a website (hand it to the site's video pipeline). Route D does capture the real app, but as stills composed into the collage.

## Project context

Read what the project already has before asking for it. Each item feeds the film; none is required.

| Look for | Use it for |
|---|---|
| `FILM.md` at the project root | The team's film notes: reference builds, looks they rejected, capture setup, house rules. Read it first; it overrides this skill's defaults where they conflict. |
| `DESIGN.md`, `tokens.css`, a Tailwind config, CSS custom properties, a component library | Colors, type, radii, borders and focus rings. Every template keeps its brand values in one custom-property block; replace that block. |
| The shipped UI code and a way to run it (a dev server, Storybook) | The components on screen (see Product fidelity). |
| `PRODUCT.md`, `VOICE.md`, a style guide | Audience, naming, tone and banned terms for captions and on-screen copy. |
| Docs, changelog, pricing page, specs, and the code | The truth sheet: every claim the film makes needs a source. |

When the project has none of these, ask for the brand colors, the font and the one-line story, and state every other assumption.

## Inputs to settle before any rendering

Ask only for what cannot be inferred; state assumptions otherwise.

1. **Reference.** A film the user points at. Fetch it, find the video URL, probe it (`ffprobe`: resolution, fps, length, bitrate, audio track, poster, `preload`). The spec becomes the target; the structure becomes the grammar.
2. **Story in one line and the subject on screen.** Who does what, what the product does in response, who receives the result. The copy on screen: prompt, headline, comments, notification, email.
3. **Route.** A if people footage is wanted and licensable; B if the film is product-only or footage is out of scope; C if the film shows someone using a flow step by step (kinetic, unless the user asks for captions or cards); B in the reel style if a launch should show several capabilities cut to music; D if an illustrated cast should tell a story around the product. For C, also settle the items in `references/walkthrough.md § Settle before building`. For D, settle the brief in `references/paper-collage.md § Settle the brief first`.
4. **Surface and length.** Home hero loop (30 s, silent, poster, `preload="none"`), landing section (20–25 s), social (45–60 s, captions; for Routes A–C the 9:16 reflow is a separate pass, while Route D builds every format at once). A length the user names wins over these defaults.
5. **Third-party products in the UI** (an AI assistant, a mail client, a chat app): name them in text; do not show their logos unless the user has the right to.

## Start a film

```sh
bash <skill>/templates/new-film.sh <cinematic|walkthrough|paper> <film folder>
```

`cinematic` serves Routes A and B, `walkthrough` serves Route C (kinetic by default) and the reel style, `paper` serves Route D. The script copies the route's template and the shared helpers into the folder, installs Playwright there once if it does not resolve, and runs the route's setup. It never overwrites an existing file.

Put the film folder outside the repository and outside any temporary or scratch directory: a film takes several sessions, and temporary folders get pruned. The script refuses temporary paths. Keep `NOTES.md` in the folder current: the current cut, the pipeline, what the user rejected and why.

## The engine

Every product beat is an HTML page that exposes `window.seek(t)` and draws frame `t` deterministically, from scratch, with no dependence on earlier frames. A renderer opens it headless with Playwright at device scale factor 2, calls `seek` for each frame, screenshots to JPEG, and ffmpeg encodes. An assembly script cuts footage segments (Route A) and concatenates everything into a master, a 1080p web file, a 720p review file, a poster and a contact sheet.

| Route | Template | Engine |
|---|---|---|
| A, B | `templates/cinematic/` | `beats.html` (one `<div class="beat">` per beat, real product markup and CSS inside, 3D world and camera, particles, `seek(t)`, lengths in `window.BEATS`), `render.js` (frames → `seg/<beat>.mp4`; `ONLY=b2` renders one beat, `ONLY=b2 FRAMES=40:60` a few frames for a look), `assemble.sh` (cut list → `film_master.mp4`, `film.mp4`, `film_720.mp4`, `poster.jpg`, `sheet.jpg`) |
| C, plain | `templates/walkthrough/` | `beats.html` (2D engine with holds, clip plans, captions and cards for the on-request cuts; plans `plan-A.json` and `plan-B.json`), plan-driven `render.js` and `assemble.sh` at 60 fps with dissolves, `plan-jobs.py` (parallel workers), `previewq.js` (single frames), `audit.js` (pointer rests, one-frame jumps, stateful seeks) |
| C, kinetic (default) | `templates/walkthrough/` | `kinetic.html` with `plan-K.json` (16:9) and `plan-Ksq.json` (square) on the same render, audit and assemble pipeline |
| B, reel | `templates/walkthrough/` | `reel.html` with `plan-R.json` on the same pipeline; `beatmap.py` finds a track's tempo and bar lines |
| D | `templates/paper/` | One canvas per frame from `timeline.json`, a frozen paper kit, capture harnesses for the real UI (the app, its CLI, an agent window), sound synthesis, review, gate and delivery tools; see `references/paper-collage.md` |

Every film folder also gets the shared helpers from `templates/common/`: `pw.cjs` (loads Playwright), `capture/lib.mjs` (boxes from the live DOM, fixture routing, in-flight states, `snapshot()` for live DOM) and `tools/make-chart-bg.mjs` (renders the engraved chart background in the brand colors into `backgrounds/`).

Copy the templates (new-film.sh does); do not start from a blank file. Each template's example product is the fictional Tidewell; replace its brand block, components and copy with the product's.

## Product fidelity

The UI on screen must be the product's own components, not a mock-up.

- Take markup and CSS from the product's shipped components and reuse them with new copy. The template's example components show the structure; replace them with the product's.
- For any surface the film zooms into and animates, prefer captured DOM from the running code (`references/live-dom.md`) to a hand-built copy: it is pixel-identical and stays true to recent UI changes.
- Colors, radii, borders and focus rings come from the product's tokens and shipped CSS. At 2× zoom a mismatched border reads as a defect.
- Emails, notifications and messages on screen follow the product's real templates: subject format, headline phrasing, link color.
- Before mirroring any UI, check for recent redesigns (`git log --since="1 month ago" -- <ui paths>`). Stale UI costs a full review round.
- Fonts: Routes A–C load web fonts at render time, and the renderer waits for `document.fonts.ready`. Route D uses local font files only (`tools/fetch-fonts.mjs`).
- Data on screen is fictional and looks real at a glance: fictional people, companies and emails (`@example.com`), never real customers.

When a component is not available in code, rebuild it from the product's tokens and shipped CSS, and say so on the review page.

## Procedure (Routes A–C)

Route D follows its own gated procedure in `references/paper-collage.md § Procedure`.

1. **Reference and concept.** Probe the reference. Write a one-page concept: what the film is not, who the protagonist is, the beat sheet, the register of the humans (Route A). Share it for review.
2. **Storyboard.** Route A: search the footage library (many stock sites block headless browsers; use a headed, persistent browser profile), sample frames, build the storyboard from real frames, all shots from one shoot, every shot 0.5–2 s. Routes B and C: the storyboard is the beat list with the copy per beat.
3. **Sources.** Route A: the user buys the license and downloads the files (download flows usually defeat automation); sources go in `footage/`. Routes B and C: nothing to fetch.
4. **Beats.** Start the film folder (§ Start a film); replace the example beats with the product's; build one beat at a time and check it with a contact sheet (`ffmpeg -vf "fps=2.5,scale=480:-1,tile=4x2" -frames:v 1`) before rendering the next. Route C: build the kinetic cut; build a captions or cards cut only when the user asks. Reel: set the tempo and section bars first (`beatmap.py` on the track), then build the sections on that grid.
5. **Render** with the template's `render.js`.
6. **Assemble** with `assemble.sh`: cut list with in-points, durations and per-cut comments; build; look at the whole-film contact sheet at 1 fps. Route C: run the checks in `references/walkthrough.md § Check before every publish`, `audit.js` first.
7. **Review page.** One HTML page with the 720p cut and the poster embedded as base64 and "What changed since cut vN" on top, published on display.dev (`references/publish.md`). Republish each cut as a new version of the same page (`--id`, `--base-version`); never a new page per cut. Send the MP4 as a file too. Post frames, not prose, when asking for a decision.
8. **Loop on feedback.** Read the open comment threads on the review page, act on each note in one new version, reply in each thread with what changed, resolve it, and record durable taste notes in the project's `FILM.md`.
9. **Ship.** Hand the 1080p web file and the poster (the same frame as the film's own poster) to the site's video pipeline.

## Review discipline

- One review page, many versions, the change log on top of each.
- Before sending any cut, look at four frames of every changed beat at full size: its start, middle, end and the frame after the last change. Clipping at the frame edge and blurred children are the two recurring defects.
- Every walkthrough-pipeline cut (plain, kinetic, reel): `audit.js` reports no problems before it is sent. Stuck pointers and one-frame flickers are hard to see in stills and easy for the viewer to see.
- Watch the 720p file once at real speed before sending. Pacing notes come only from watching.
- An agent cannot hear. When a cut has sound, measure it and say that it needs the user's ears.

## Gotchas already paid for

- A CSS `filter` on a parent blurs its children; sharp objects must be siblings of blurred panels.
- `zoompan` at 1080p jitters on slow pushes; compute it on a 7680-wide upscale.
- The concat list's paths resolve relative to the list file.
- zsh mangles `$var:flags` and aborts a chain on an unmatched glob; assembly scripts are bash.
- A phone-portrait UI in 16:9 is a floating device on the plate with the camera pushing into its screen.
- An email beat is the mobile mail app if the previous shot is a phone.

## What this skill does not do

- Choose the shoot, write the shot outline, buy a license, or make taste calls. Present candidates and frames; the user decides.
- Screen-record the real application as the film. Route D captures stills from the real code on fictional data and composes them.
- Compose music or record voice. Laying a track the user supplies under a finished cut is in scope: `references/kinetic-style.md § Music`.
- Publish anything except the review page on display.dev, and that only when the user asks.
````

## File: hermes/design/product-film/scripts/_common.sh
size: 3013
sha: a01d2a298368ec9bf7a2dd231ab3970528bd3331
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/scripts/_common.sh

```text
#!/usr/bin/env bash
# Sourced by publish.sh. Resolves jq, the dsp invocation, attribution,
# and the curl helper for the anonymous publish path.

set -euo pipefail

# Consumed by publish.sh after sourcing this file. ShellCheck can't follow
# into the sourcers, so silence its unused-variable warning rather than
# `export`-ing (we don't want API_URL leaking into child curl processes'
# environment — it's a shell-scope helper, not an env contract).
# shellcheck disable=SC2034
API_URL="${DISPLAYDEV_API_URL:-https://api.display.dev}"

# Resolve the bundled jq binary for the current platform. The skill
# ships statically-linked jq 1.7.1 binaries for the five common
# platforms (macOS/Linux on amd64/arm64 plus Windows amd64) — see
# bin/jq-* and the SHA-verified manifest at
# https://github.com/jqlang/jq/releases/tag/jq-1.7.1. Falls through to
# a system jq on PATH if no bundled binary matches the current host
# (BSD, Alpine on ARM, NixOS, etc).
SKILL_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/.." && pwd)"
JQ=""
case "$(uname -s)/$(uname -m)" in
  Darwin/arm64)              JQ="$SKILL_ROOT/bin/jq-macos-arm64" ;;
  Darwin/x86_64)             JQ="$SKILL_ROOT/bin/jq-macos-amd64" ;;
  Linux/x86_64|Linux/amd64)  JQ="$SKILL_ROOT/bin/jq-linux-amd64" ;;
  Linux/aarch64|Linux/arm64) JQ="$SKILL_ROOT/bin/jq-linux-arm64" ;;
  MINGW*/*|MSYS*/*|CYGWIN*/*) JQ="$SKILL_ROOT/bin/jq-windows-amd64.exe" ;;
esac
if [[ -z "$JQ" || ! -x "$JQ" ]]; then
  JQ="$(command -v jq 2>/dev/null || true)"
fi

DSP_CMD=${DSP_CMD:-}
if [[ -z "$DSP_CMD" ]]; then
  if command -v dsp >/dev/null 2>&1; then
    DSP_CMD="dsp"
  elif command -v npx >/dev/null 2>&1; then
    DSP_CMD="npx -y @displaydev/cli"
  else
    DSP_CMD=""
  fi
fi

# Skill version. Bump in lockstep with the git tag on every release —
# this value flows into `CLIENT_SOURCE` below as
# `product-film-skill@<version>` and is read by display.dev's analytics
# to attribute publish events to the product-film-skill channel.
# Set `SKILL_VERSION_OVERRIDE` to test attribution locally without retagging.
SKILL_VERSION="${SKILL_VERSION_OVERRIDE:-0.2.0}"
CLIENT_SOURCE="product-film-skill@${SKILL_VERSION}"

require_jq_or_exit() {
  if [[ -z "$JQ" ]]; then
    echo "Error: jq is required but not found." >&2
    echo "Install jq from https://jqlang.github.io/jq/ or run on a supported platform." >&2
    exit 1
  fi
}

# Wrapper around curl that sets the standard headers display.dev expects.
# Pass any pass-through actor headers via the environment:
#   X_ACTOR_TYPE / X_ACTOR_ID / X_ACTOR_NAME (optional)
curl_api() {
  local extra_headers=()
  [[ -n "${X_ACTOR_TYPE:-}" ]]  && extra_headers+=(-H "X-Actor-Type: $X_ACTOR_TYPE")
  [[ -n "${X_ACTOR_ID:-}" ]]    && extra_headers+=(-H "X-Actor-Id: $X_ACTOR_ID")
  [[ -n "${X_ACTOR_NAME:-}" ]]  && extra_headers+=(-H "X-Actor-Name: $X_ACTOR_NAME")
  curl --silent --show-error --fail-with-body \
    -H "X-Client-Type: skill" \
    -H "X-Client-Source: $CLIENT_SOURCE" \
    "${extra_headers[@]}" \
    "$@"
}
```

## File: hermes/design/product-film/scripts/publish.sh
size: 2084
sha: a6d680b57dadf5e34280cfa80adbd004b0cbe0c6
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/scripts/publish.sh

```text
#!/usr/bin/env bash
# Anonymous single-file publish to display.dev. No login, no setup —
# returns a 30-day preview URL + a claim URL the user can sign up against.
#
# Usage:
#   publish.sh <path-to-html-or-md> [--name "Artifact title"]
#
# Vendored from display-dev/skill's publish.sh (anonymous-single-file
# branch only), as in display-dev/visualize. Richer flows (--visibility, --share-with, multifile,
# SSO login) live in the @displaydev/cli npm package; this script keeps
# the no-dependency hot path working.

set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
# shellcheck source=./_common.sh
source "$SCRIPT_DIR/_common.sh"

require_jq_or_exit

FILE=""
NAME=""

while [[ $# -gt 0 ]]; do
  case "$1" in
    --name)
      NAME="$2"
      shift 2
      ;;
    --help|-h)
      echo "Usage: publish.sh <path-to-html-or-md> [--name \"Artifact title\"]" >&2
      exit 0
      ;;
    *)
      if [[ -z "$FILE" ]]; then
        FILE="$1"
        shift
      else
        echo "Unexpected argument: $1" >&2
        exit 2
      fi
      ;;
  esac
done

if [[ -z "$FILE" ]]; then
  echo "Usage: publish.sh <path-to-html-or-md> [--name \"Artifact title\"]" >&2
  exit 2
fi

if [[ ! -r "$FILE" ]]; then
  echo "File not readable: $FILE" >&2
  exit 1
fi

# Default the artifact name to the basename if not provided.
if [[ -z "$NAME" ]]; then
  NAME="$(basename "$FILE")"
fi

# Determine content type from extension.
case "$FILE" in
  *.html|*.htm) CONTENT_TYPE="text/html" ;;
  *.md|*.markdown) CONTENT_TYPE="text/markdown" ;;
  *)
    echo "Unsupported extension. Use .html, .htm, .md, or .markdown." >&2
    exit 1
    ;;
esac

CONTENT="$("$JQ" -Rs '.' < "$FILE")"
NAME_JSON="$("$JQ" -Rs '.' <<< "$NAME")"

PAYLOAD="$("$JQ" -n \
  --argjson content "$CONTENT" \
  --argjson name "$NAME_JSON" \
  --arg contentType "$CONTENT_TYPE" \
  '{name: $name, content: $content, contentType: $contentType}')"

RESPONSE="$(curl_api -X POST \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD" \
  "$API_URL/v1/public/artifacts")"

echo "$RESPONSE" | "$JQ" .
```

## File: hermes/design/product-film/references/camera-rig.md
size: 11757
sha: f3f282f3988e00270246c7fde0703ffbfbc7ac39
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/references/camera-rig.md

````text
# Camera rig and choreography reference

Extracted from the beat engine of a hero film after sixteen cuts. Numbers are the tuned values; the code is the working code. `templates/cinematic/beats.html` carries all of it.

This rig is for Routes A and B. Do not use it for a Route C walkthrough: the 3D camera softens text, and the drift, tilt, particles and glows were rejected there. See `walkthrough.md`.

## The numbers

These held across sixteen cuts. Start here; change one at a time and re-render only the beat you changed.

**Pacing**

- Route A: footage cuts 0.75–1.8 s (median 1.5 s), product beats 2.5–3.8 s, half the running time each. Five cuts per ten seconds, always short–short–long. Every product beat holds its end state ≥ 0.5 s.
- Route B: beats 2.5–5 s, joined by the plate; one idea per beat; captions change on beat boundaries.
- The longest hold goes on the text-heaviest beat. The first product beat carries the most text.

**Camera**

- Perspective world, `perspective:1500px`; the camera translates on z (a dolly), never a 2D scale. Magnification of a plane at depth z is `1500/(1500 − z_cam − z_obj)`.
- One move per beat, cubic ease-in-out over the whole beat: z from about −80 to +180…+500. Under it, residual drift `x += 6·sin(0.9t)`, `y += 4·sin(1.25t)` so a hold never freezes.
- Rotation only on hand-held objects (popovers, dialogs, phones): settle from 7°/−9° to 1.5°/−2° plus ±0.6–1.2° sine. Never on screen-fixed objects (composer, card); tilt there reads as a bug.
- Subject forward, ground back: the subject moves to z 260–280 and scales 1.45–1.7×; the ground scales 0.98, dims to 0.86, and the focus plane follows the subject so the ground blurs ≤ 1.6 px. The ground is never removed.
- Depth of field: `blur = clamp((|z − focus| − 90)/110, 0, 3.5)` px, opacity × (1 − 0.1·blur/3.5).

**Entrances**

- Every element has an entrance: y +44→0, scale 0.94→1, opacity 0→1, 0.3–0.6 s, cubic ease-out. Stagger siblings 60–140 ms in reading order. Chips and avatars pop with a back-ease (1.4→1).
- Text is typed, not faded: prompts at about 45 characters per second with a caret that follows; the camera tracks the caret.
- Unfolds use max-height 0→N with ease-out, not opacity alone.

**Plate and texture**

- Two soft color blobs on an off-white plate, 150–200 seeded particles drifting; on the publish beat they converge into the card as it lands.
- Glass panels: `background: rgba(255,255,255,.7)` with `backdrop-filter: blur(22px)`. Comments, pills and dialogs are solid white with a border and a deep shadow.
- Encode every beat with `noise=alls=6:allf=t+u` and `vignette=PI/6:mode=backward` so it sits with footage.

**Footage (Route A)**

- One shoot for every people shot; one protagonist; one mild grade (`eq=saturation=0.92:contrast=1.03`).
- Each product beat is preceded by the human action that motivates it.
- A wide exterior opens and closes the film so the loop seams.
- License at the highest tier and pull the largest file. Scaling footage up and refitting it does not make a zoom; a real push-in is `zoompan` on an 8K upscale.

## Stage

```html
<div id="stage">                                   <!-- 1920×1080, overflow hidden -->
  <div id="plate"><i id="bl1"></i><i id="bl2"></i></div>   <!-- two blurred colour blobs -->
  <canvas id="pf" width="3840" height="2160"></canvas>      <!-- particles, drawn at DSF 2 -->
  <div id="world"><div id="cam">                             <!-- perspective + camera -->
    <div class="beat" id="b1">…</div>
  </div></div>
</div>
```

```css
#world{position:absolute;inset:0;perspective:1500px;perspective-origin:50% 46%}
#cam{position:absolute;inset:0;transform-origin:50% 50%;transform-style:preserve-3d;will-change:transform}
.beat{position:absolute;inset:0;display:none;transform-style:preserve-3d}.beat.on{display:block}
.p3{transform-style:preserve-3d;will-change:transform,opacity}
/* glass */
.glass{background:rgba(255,255,255,.70)!important;backdrop-filter:blur(22px) saturate(1.15);border:1px solid rgba(255,255,255,.85)!important;box-shadow:0 44px 100px rgba(30,28,20,.12),0 2px 8px rgba(0,0,0,.04),inset 0 1px 0 rgba(255,255,255,.95)!important}
/* solid (comments, pills, dialogs) */
.solid{background:#fff!important;border:1px solid var(--border)!important;box-shadow:0 44px 100px rgba(30,28,20,.16),0 2px 8px rgba(0,0,0,.06)!important}
```

## Helpers

```js
const clamp=(x,a,b)=>Math.max(a,Math.min(b,x)), lerp=(a,b,u)=>a+(b-a)*u, seg=(t,a,b)=>clamp((t-a)/(b-a),0,1);
const eo=u=>1-Math.pow(1-u,3);                       // ease-out cubic: entrances
const ei=u=>u*u*u;                                   // ease-in cubic: particles converging
const eio=u=>u<.5?4*u*u*u:1-Math.pow(-2*u+2,3)/2;     // ease-in-out cubic: camera
const bo=u=>{const c1=1.70158,c3=c1+1;return 1+c3*Math.pow(u-1,3)+c1*Math.pow(u-1,2);}; // back-out: chips
```

## Camera

```js
const CAM={x:0,y:0,z:0,rx:0,ry:0};
// one move over the beat, plus residual drift; rot=false on beats whose objects are screen-fixed
function cam3(t,a,b,dur,rot=true){
  const u=eio(seg(t,0,dur)); for(const k of ['x','y','z','rx','ry']) CAM[k]=lerp(a[k]??0,b[k]??0,u);
  CAM.x+=6*Math.sin(t*.9+1.2); CAM.y+=4*Math.sin(t*1.25+.4);
  if(rot){CAM.ry+=.4*Math.sin(t*.7); CAM.rx+=.3*Math.sin(t*.55+2);}
  $('cam').style.transform=`translate3d(${-CAM.x}px,${-CAM.y}px,${CAM.z}px) rotateX(${-CAM.rx}deg) rotateY(${-CAM.ry}deg)`;
}
// keyframed camera for beats with several moves (typing → lift → land)
function camK(t,K,rot=false){
  let a=K[0],b=K[K.length-1]; for(let i=0;i<K.length-1;i++){ if(t>=K[i].t&&t<=K[i+1].t){a=K[i];b=K[i+1];break;} } if(t>b.t)a=b;
  const u=b.t>a.t?eio(seg(t,a.t,b.t)):1; for(const k of ['x','y','z','rx','ry']) CAM[k]=lerp(a[k]??0,b[k]??0,u);
  CAM.x+=6*Math.sin(t*.9+1.2); CAM.y+=4*Math.sin(t*1.25+.4); if(rot){CAM.ry+=.4*Math.sin(t*.7);CAM.rx+=.3*Math.sin(t*.55+2);}
  $('cam').style.transform=`translate3d(${-CAM.x}px,${-CAM.y}px,${CAM.z}px) rotateX(${-CAM.rx}deg) rotateY(${-CAM.ry}deg)`;
}
```

Magnification of a plane: `m = 1500 / (1500 − z_cam − z_obj)`. Camera z 180 on a ground at z 0 gives 1.14×; the same camera on a popover at z 260 gives 1.42×, and the popover's own `scale(1.5)` makes it 2.1×. That differential is the "pull-out".

## Placing objects with depth of field

```js
// z = depth, focus = the plane that is sharp; blur grows 1px per 110px beyond a 90px dead zone, capped at 3.5px
function put(el,o){
  const z=o.z??0, f=o.focus??z, d=Math.abs(z-f); const blur=clamp((d-90)/110,0,3.5);
  el.style.transform=`translate3d(${o.x??0}px,${o.y??0}px,${z}px) rotateX(${o.rx??0}deg) rotateY(${o.ry??0}deg) scale(${o.s??1})`;
  el.style.filter=blur>0.05?`blur(${blur.toFixed(2)}px)`:'';
  el.style.opacity=(o.op??1)*(1-0.10*clamp(blur/3.5,0,1));
}
// entrance: rises 44px, scales .94→1, fades in; tilt settles from 7°/−9° to 1.5°/−2° with a sine under it
function p3(el,t,t0,dur,extra='',o={}){
  const u=eo(seg(t,t0,t0+dur));
  put(el,{x:o.x??0,y:(o.y??0)+lerp(44,0,u),z:o.z??0,focus:o.focus,
    rx:o.tilt===false?0:lerp(7,1.5,u)+.6*Math.sin(.9*t), ry:o.tilt===false?0:lerp(-9,-2,u)+1.1*Math.sin(.7*t+1),
    s:lerp(.94,1,u)*(o.s??1), op:u*(o.op??1)});
  return u;
}
```

Blurred panels must not contain the sharp objects in front of them: a CSS `filter` on a parent blurs every child. Make popovers, pills and toasts siblings of the panel and position them absolutely.

## Particles

```js
let s=1337; const rnd=()=>{s=(s*1664525+1013904223)>>>0;return s/4294967296;};   // seeded: identical every render
const P=[]; for(let i=0;i<170;i++) P.push({bx:rnd()*1920,by:rnd()*1080,r:1.2+rnd()*3.6,d:.35+rnd()*.65,ph:rnd()*6.283,g:rnd()<.16});
// ACC: the brand accent as "r,g,b" (the template reads it from --accent); about 16 % of the particles carry it
function particles(t,coalesce){ cx.setTransform(2,0,0,2,0,0); cx.clearRect(0,0,1920,1080);
  const u=coalesce?ei(seg(t,1.35,2.35)):0, fade=coalesce?1-seg(t,2.05,2.65):1;
  for(const p of P){ let x=p.bx+22*p.d*Math.sin(.35*t+p.ph), y=((p.by-14*p.d*t)%1080+1080)%1080;
    if(coalesce){x=lerp(x,960+(p.bx-960)*.06,u); y=lerp(y,560+(p.by-560)*.06,u);}   // converge on the card
    const a=(.32+.4*p.d)*fade, c=p.g?ACC:'255,255,255'; const g=cx.createRadialGradient(x,y,0,x,y,p.r*2.2);
    g.addColorStop(0,`rgba(${c},${a})`); g.addColorStop(1,`rgba(${c},0)`);
    cx.fillStyle=g; cx.beginPath(); cx.arc(x,y,p.r*2.2,0,6.283); cx.fill(); } }
```

## Five beats of one hero film, as choreography

The template implements Publish, Comment → v2 and Share as `b1`–`b3`.

| Beat | Length | Camera | Choreography |
|---|---|---|---|
| Publish | 3.8 s | `camK` keyframes: (0 s) x −300 z 40 → (0.15) z 250 → (1.35) x +210 z 350 → (1.95) x −10 y −60 z 20 → (2.75) z 210 → (3.8) z 240. No rotation. | Prompt types 0.15–1.35 s (56 chars), caret blinks until 1.42; composer lifts 1.42–1.95 (y −330, scale .86, opacity .65, focus moves so it blurs 1 px); thinking dots 1.5–1.85; card enters 1.9–2.5 at z 200 (p3, no tilt, scale 1.1); preview unfolds 2.15–2.7 (height 0→400); title 2.3–2.55; three stat tiles from 2.35, 80 ms apart; five bars from 2.5, 60 ms apart; status flips 2.75; two buttons from 2.8, 80 ms apart. Particles converge 1.35–2.35, fade 2.05–2.65. |
| Comment → v2 | 3.2 s | `cam3` x −40→60, y 0→−16, z −20→180, ry −2→2 | Page: focus 0→260, scale .98, opacity .86 over 0.2–0.9. Comment enters 0.15–0.75 (tilt on), z 40→260, scale 1→1.5 over the same pull. Reply 0.85–1.25. Headline swap at 1.6 with a 5% scale pulse 1.45–1.8. v2 chip at 1.55, back-ease 1.4→1. Separator bar scaleY 1.6–2.1. Republish pill 1.85–2.25: y 18→0, z 60→200, scale 1→1.25. "Resolved" 2.2–2.45. |
| Teammates | 2.5 s | `cam3` x 40→−40, y 10→−10, z −10→190, ry 3→−3 | Same page pull 0.1–0.8. Comment A enters 0.1, z 40→260, scale →1.45. Avatar pops 0.55–0.9 (back-ease 1.5→1). Comment B enters 0.9, z 140→280, scale 1.15→1.45 over 0.9–1.5. |
| Share | 3.2 s | `cam3` x 0→30, y −10→20, z −40→220, ry 2→−2 | Dialog enters 0–0.55 at z 40, base scale 1.7, tilt on. Email types 0.3–1.45 (17 chars). Button hover 1.7, press pulse 1.85–2.05 (scale .92). Added row unfolds 2.0–2.45 (max-height 0→80, y −8→0). |
| Phone | 2.8 s | `cam3` to the email body's measured center, z −80→500, rotation on | Phone already in at the cut (enter −0.3–0.2: y 30→0, rx 5→1.5, ry −10→−3, both with sine). Body unfolds 0.35–1.0 (max-height 0→700). Reply pills 1.1–1.5. Link underline 2.1. Three resolved cards enter from 0.75, 140 ms apart, at z 170; scroll 1.15–2.45 by two card gaps; per card z 170→30, scale 1→.94, opacity ×(1−.5k), blur to 3.5 px by distance k from the focus line. |

## Render and encode

```
viewport 1920×1080, deviceScaleFactor 2 → JPEG q94 per frame at 25 fps
ffmpeg -framerate 25 -i f_%04d.jpg -vf "scale=1920:1080:flags=lanczos,noise=alls=6:allf=t+u,vignette=PI/6:mode=backward,format=yuv420p" -c:v libx264 -preset medium -crf 17 -an seg/<beat>.mp4
```

`templates/cinematic/render.js` does both for every beat in `window.BEATS`; `ONLY=b2` renders one beat, and `ONLY=b2 FRAMES=40:60` writes only those frames, without encoding, for a quick look.

## Removed after trying

- Rotational camera wobble on the publish beat (read as a tilt on flat UI).
- Glass (translucent) comment boxes over a softened page (read as a transparency bug).
- Floating mono labels, dust and a grid floor around the UI (competed with the product).
- `zoompan` push-ins computed at 1080p (pixel-snapped jitter).
- Product beats under 2.5 s and end holds under 0.5 s (illegible).
````

## File: hermes/design/product-film/references/kinetic-style.md
size: 16901
sha: 315e65d40ff79b05af24c5c1ecd2af360f0f4f1f
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/references/kinetic-style.md

````text
# Kinetic style

The default register for Route C walkthroughs and feature launches, and an option for a Route B film that should feel
made rather than demonstrated: isolated UI at extreme close-up on white, morphs instead of cuts, kinetic captions,
almost no holds. It changes the look and the pacing. It does not change the pointer rules or the flicker rules in
`walkthrough.md`.

The numbers below were measured on a studied reference: a 65 s product launch film at 1080p24, with a music bed and
no voice. `templates/walkthrough/kinetic.html` is a working example engine (§ Engine notes).

## What it does, measured

| Measure | Value |
|---|---|
| Hard cuts | 4 in 65 s. Every other change is a morph, a whip or a focus pull. |
| Still frames | 6 %. The only hold is the end card (2.6 s). No hold anywhere else. |
| Ideas | about 17 in 62 s, 2.5–5 s each |
| Rhythm | a slow move while you read (1–3 s), then a fast transition (0.3–0.6 s), then repeat |
| Typing | about 16 characters per second, with the text 60–100 px tall |
| Plate | pure white, no texture, no browser frame |
| Loudness | steady music bed at about −16 dBFS; it has no voice and nothing depends on sound |

It stays readable with almost no holds because of the way it frames text. Few words are on screen at a time and
they are very large. The camera follows the reading point, so the eye never has to search. A walkthrough fixes
readability with holds; this style fixes it with scale.

## Beat list of the reference

| Time (s) | Beat |
|---|---|
| 0–1.5 | A two-brand lockup builds letter by letter. |
| 1.5–4.5 | Close-up of an empty chat prompt. The cursor clicks and types a three-word command. |
| 4.5–6.5 | The text slides off. The app icon and wordmark build, then the wordmark leaves. |
| 7–8.5 | A ring of halftone dots in the brand color opens around the icon and reveals the chat window (iris). |
| 8.6–9 | The camera dives from the window into the prompt box, to one "@" character. |
| 9–18 | A long, multi-step command is typed at huge size and the camera tracks the caret. |
| 18.5–20.5 | The send button is pressed and breaks into squares in the brand colors (pixel burst). They re-form as the message card with "Working…". |
| 21–23.5 | A whip with horizontal motion blur. Real avatars fly past at several depths, tagged "Analysing lead…". |
| 24–26 | One avatar lands, and its profile card fills in field by field. |
| 26.5–28 | Caption: "Brings the right context into every message". It exits with motion blur. |
| 29–35.5 | A messaging app's chat. A greeting, then a push-in to one huge bubble, then typing dots. |
| 35.5–37 | The "Launch" button multiplies into brand-color blocks, and the blocks turn into avatars. |
| 37.5–39 | "Right here" with mixed sizes and baselines. A gap opens, a pill drops into it, and the line ends with the host app's name. |
| 39.5–40.5 | The pill morphs into the prompt, where the next command is typed. |
| 41–44.5 | A caption names the next step. The prospect replies; a chip reads "Thinking of the best reply". |
| 44.5–46 | The reply is sent. A focus pull: the chat blurs while a green check pops sharp in front. |
| 46.5–48 | Calendar close-up; the meeting block draws in under the cursor. |
| 48–51.5 | A caption names the host app as the interface. Its pill outline becomes a line, then a node, then three branches, one per capability. |
| 52–54 | "From one prompt". Then the prospect's confirmation. |
| 54.5–60 | An install button is clicked. The last prompt is typed huge and sent. |
| 60–65 | A spark, then the logo builds with the tagline. Hold 2.6 s. |

## Techniques to reuse

1. **Isolated UI at extreme close-up.** Show one component (a prompt box, a chat card, a profile card, a calendar
   block) on white, not a whole browser. Show the full window for 1 s or less to set the scene, then dive in.
   Body text is 60–100 px on a 1080 frame, and the component may run off the frame edge.
2. **Fade to white at the edges.** Anything that leaves the frame, or trails behind the caret, fades into white
   instead of being clipped. Use a mask on the stage, the inverse of a dark vignette.
3. **Caret-tracking ticker.** For a long prompt, the camera x follows the caret. Only about 15–20 characters are in
   frame, and the words behind the caret fade out.
4. **Wet-ink accent.** A new word arrives in the accent color (the reference used an orange-to-red gradient) and
   settles to ink in about 0.5 s. The accent marks what is new, not a fixed keyword.
5. **Kinetic captions as their own beats.** 2–6 words, 60–110 px, not an overlay band. Words enter one at a time,
   from blurred to sharp, sometimes at mixed sizes and baselines. They exit with motion blur along the direction
   of travel.
6. **Transitions without cuts.**
   - *Morph:* the last object of one beat becomes the first object of the next (a button to squares to a card, a
     pill to a prompt, blocks to avatars, an outline to a line to a node diagram).
   - *Whip:* a 0.2–0.35 s move with directional motion blur.
   - *Focus pull:* the outgoing beat blurs from 0 to about 12 px while the incoming subject pops in sharp in front.
   - *Halftone iris:* a ring of brand-color dots opens and reveals the next shot inside it.
   - *Pixel burst:* the clicked control breaks into brand-color squares that re-form as the result.
7. **Real content as particles.** Fly avatars and cards past at several depths, with size, blur and speed set by
   depth. Never abstract dots or glows.
8. **Flat surfaces.** Cards are white with a faint warm tint and a hairline edge, and have little or no shadow.
   The product's own colors (a messaging app's blue, a calendar block) carry the color.
9. **A large cursor** (about 60–70 px on a 1080 frame). A click is what starts each morph.
10. **End card.** The logo builds, the tagline follows, then the only hold in the film.

## Fitting it to the walkthrough rules

- **Move with purpose; never float.** Walkthrough reviews rejected slow drift, several objects floating on their
  own, and the same zoom on every beat. This style moves all the time, but every move goes to the next subject, is
  fast and eased, and ends. Nothing drifts in place.
- **Scale instead of holds.** In this style, get readability from size and a camera that follows the reading
  point. Keep holds for the end card and for any real waiting state.
- **Show results on the product itself.** When an agent changes something, show the change happening in the
  artifact (its header, version chip and page), not as a floating before and after. A centered, struck-through
  headline on white reads as commentary, not as the product. Kinetic captions are for claims, not for product state.
- **Default to this style.** For a walkthrough or a feature launch, build the kinetic cut. The plain look with a
  caption band or text cards (`#F3F3F3`, the engraved chart, a browser frame, 1.4–1.9× zooms; `walkthrough.md`
  § Captions or cards) does not mix with this one; build it only when the user asks for it.
- **Sound.** The reference gets part of its energy from the music. A kinetic cut must still work with the sound off:
  everything on screen carries the meaning. When the user supplies a track, lay it as a bed (see § Music); composing
  music or a voice-over stays out of scope.
- **Brand.** Use the product's accent as the wet-ink accent and follow the product's own wordmark rules. Do not copy
  a reference film's palette.

## Feature launch films

The second kinetic build was a feature launch film: five cuts, all kept. Each row closed one review note.

| Rule | Why |
|---|---|
| Say the promise in words at the start and at the end. The opening types the feature's name ("Introducing <Feature>"); then the name shrinks into the start of the value-proposition sentence and the rest types in (4.6 s). The end card is the same sentence, then the brand line and one scope line. | The first cut showed the feature without saying what it does for the viewer. |
| When two things belong together (a figure in the lede and the same figure in a tile), frame both with one push. Never pan to one, then the other, then back. | Panning to one and back read as a left-to-right flicker. |
| A changed value needs different digits, not transposed ones (94.6 → 96.4 read as unchanged). Shoot it at 3.3–3.7× and hold the new value in the accent for about 1.4 s (`ink(…, settle)`). | The change was not obvious. |
| Show the path the audience will take. Drop capabilities they won't use, even when they exist, from the film and the copy. | An option the audience would not use took screen time. |
| The struck-through "No X. No Y." closer is optional; default it off for feature launches. | It read as filler in a feature launch; a walkthrough promo kept it. |
| After the main flow, give two or three features a one-word caption beat ("Checklists.") and a short shot of the real UI doing it. Then a slot reel spins through the rest and lands on "And more." Every word on the reel must be a feature that works today. | One flow undersold what the feature can do. |
| Fixture data must look real at a glance. | "ext. 214" read as a placeholder; a shift time ("06:00–14:00") did not. |
| Close-ups on a control show its real hover state before the press. Take the hover values from the capture. | At 3× a header that differs from the shipped one is obvious. |

Beats that worked and were kept through every cut:

- **Morph out of the pressed control.** The next surface (an editor) starts inside the pressed button's screen rect
  and grows to fill the frame (0.5 s, log-space scale, clip opening from the button's height).
- **Burst from the saved state into the next surface.** The saved version chip breaks into squares that re-form as
  the version pill on the published page.
- **Menus in one direction.** Camera on the open menu, pointer lands on the item, one whip to where the result lands.
  No return trip.

**The reel.** Words at 150 px in a window that shows one word, with neighbors squashed and faded above and below and
two hairlines at the window edges. Motion: rest while the whip lands (0.32 s), spin up over 0.2 s, cruise at 7.2 words
a second, a quadratic ease-out that overshoots the last word by a quarter word, then a 0.26 s settle onto it, and a
5 % scale pop. The first version front-loaded an ease-out cubic, so most words flew past during the whip; readable
passing words need the cruise. Vertical motion blur from the reel's speed, as for camera moves.

**Length.** The final cut ran 38.9 s against a planned 20–25 s. With an opening sentence, one hero flow, three feature
beats, the reel and a 4.4 s end card, 35–40 s is the honest length; cut features, not holds, to go shorter.

### Square cut from the same engine

`?sq=1` sets the frame to 1080×1080 in the same page, so both cuts come from one timeline:

- The world stays 1920 wide; each camera needs a square framing (usually a smaller `m` or a center nearer the
  subject).
- Captions are laid out in the frame (`left:0; width: VW`), never `left:0; right:0` inside the 1920 world. Scale
  caption type by about 0.74, and let long sentences take two left-aligned lines.
- Anything read must sit inside the faded edge; at 1080 wide a 120 px sentence reached it and dropped to 98 px.
- Plans carry `"w": 1080, "h": 1080, "q": {"sq": "1"}` (`plan-Ksq.json`); `render.js`, `audit.js` and `assemble.sh`
  read them. For previews: `VW=1080 PAGE=kinetic.html node <film>/previewq.js sq.jpg "beat=K&sq=1@9.2"`.

### Music

When the user supplies a track and a start point ("from second 30, the drop"):

- Find the hit, not the second: an RMS envelope in 0.1 s windows shows the dip before the drop and the transient
  (in one track the first hit sat at exactly 30.0 s).
- Start the film on the hit, with a 30 ms fade-in only against a click, and a 2 s fade-out on the end card.
- Level the bed with `loudnorm` to −16 LUFS integrated and −1.5 dBTP true peak, then check with `ebur128`.
- Mux into copies (`film-*-music.mp4`) and keep the silent films for surfaces that autoplay muted.
- Note where the track came from and that its license allows commercial use before the film is published.

```
# RMS per 0.1 s from 28 s on (44.1 kHz: 4410 samples per window)
ffmpeg -v error -ss 28 -t 4 -i track.wav -af "asetnsamples=4410,astats=metadata=1:reset=1,ametadata=print:key=lavfi.astats.Overall.RMS_level:file=-" -f null - \
  | awk -v s=28 -F'pts_time:|=' '/pts_time/{t=$2} /RMS_level/{printf "%.1f s  %6.1f dB\n", s+t, $2}'
# the bed: from the hit, film length L, levelled, then the fades
ffmpeg -ss 30.0 -i track.wav -t $L -af "loudnorm=I=-16:TP=-1.5,afade=t=in:d=0.03,afade=t=out:st=$(awk "BEGIN{print $L-2}"):d=2" -ar 48000 bed.wav
ffmpeg -nostats -i bed.wav -af ebur128=peak=true -f null - 2>&1 | sed -n '/Summary/,$p'
ffmpeg -i film-K.mp4 -i bed.wav -map 0:v -map 1:a -c:v copy -c:a aac -b:a 192k -shortest -movflags +faststart film-K-music.mp4
```

## Engine notes

`templates/walkthrough/kinetic.html` is the example engine: a 21 s Tidewell film (lockup, a prompt typed as a
ticker, a burst into the result, a caption, an iris into the page, an in-line edit with a version change, the reel,
the end card). `new-film.sh walkthrough` copies it with the rest of the walkthrough template. It runs on the same
pipeline as `beats.html`: `plan-K.json` (`"page": "kinetic.html"`, one clip, `xf` 0) and `plan-Ksq.json` for the
square cut, with `render.js`, `audit.js`, `plan-jobs.py`, `assemble.sh`, and `previewq.js` with `PAGE=kinetic.html`.
Replace the shots and keep the engine. It mounts hand-built UI; when the UI must be the product's own at close range,
mount captured DOM instead (`live-dom.md`). Keep the two registers in separate pages: do not add these effects to
`beats.html`.

Its patterns:

- **One timeline, one camera per shot.** Each shot is a group (`.g` > `.gw`) with its own 2D camera and a time window.
  `DUR[]` holds the shot lengths and the section starts `ST[]` follow from it, so pacing changes in one place. Shots
  hand over through group-level transitions (`tin`/`tout`): a pan of one frame width in 0.4 s (sideways, or vertical
  with `up`), or a focus pull in 0.45 s.
- **Motion blur without extra frames.** An SVG `feGaussianBlur` per group, with separate x and y deviations set
  every frame from the camera's or the pan's speed: `blur = min(40, 0.18 × px per frame)` (about a 180° shutter).
  A factor of 0.45 smeared ordinary camera moves.
- **Wet ink.** `ink(el, text, t, t0, 16 cps, settle)` builds one span per word; a finished word goes from the accent
  to ink over 0.5 s. Mix in **oklab**: in oklch the hue swings through other hues on its way to the ink (a green
  accent passed through olive).
- **Caret-tracking ticker.** The camera x follows a continuous caret position (canvas `measureText` of the typed
  prefix, interpolated within the current character), with the text starting at about 300 px and the caret kept
  left of about 1250 px. Put the placeholder after the caret in the DOM, or it shifts the measured text start.
- **Iris and burst on one canvas** above the groups, both in the brand accent. The iris clips the incoming group with
  `clip-path: circle()` and draws a halftone ring of accent dots just outside it. Pass the burst plain
  `{x, y, w, h}` objects (`rr()`), not `DOMRect`s (they have `width`/`height`, and the burst silently drew nothing).
- **Measure hidden layout inside `seek`**, after the fonts have loaded, by showing the group for a moment.
  Measuring at load uses the fallback font's widths.
- **Hidden shots reset typed text** (`RESET`), so a frame never depends on the frames before it.
- **Pointers live in screen space**, drawn through their shot's camera, and fade out before the shot's transition:
  a pointer does not travel with its group. `audit.js` measures rests in screen space, so a pointer resting while
  the camera pushes does not list as a rest; check those moments in previews.

Bugs the builds found, now caught or fixed:

- **Stateful seek.** A render seeks through frames in order, a single-frame preview does not. Replacing an element's
  text wiped out the spans a helper had cached, so the edited headline was blank in the render and fine in every
  preview. `audit.js` now redraws sampled frames on a fresh page and flags any visible text that differs.
- **One-clip plans.** `assemble.sh` looped with `seq 1 0`, which counts down on macOS.
- **Borders.** Take radii, border widths and focus rings from the product's shipped CSS. At 2–3× zoom any mismatch
  shows: a 2px focus border read as a heavy double outline next to 1px fields. Scale radii with the film's larger
  controls (one build used 12px and 10px).
- **Frame edges.** Anything that has to be read, such as a send button, must sit inside the 6 % faded edge.
````

## File: hermes/design/product-film/references/live-dom.md
size: 5917
sha: a35b4b701200b34f7cc61843642fda1b290bd254
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/references/live-dom.md

```text
# Live product UI from captured DOM (Routes B and C)

Use this when a film shows product UI at close range that must also move: text typed into it, a hover state, a
menu opening, a version chip changing. Route D composes screenshots; screenshots go soft past about 2.7× and cannot
be typed into. Here the film mounts the product's own markup and CSS, captured from the running code with fictional
fixtures, and animates it like any other DOM.

One feature launch film was built this way: everything on screen was the product's real editor shell, toolbar, live
preview and page header; only the fictional document was written for the film. The steps are capture, extract and
mount; the mounting page is a kinetic or walkthrough engine page (`templates/walkthrough/`).

## 1. Capture

Follow `paper-capture.md` for the shared harness rules: the app on its dev server with every API call answered by
fixtures, fictional names only, nothing published, the user's repo unchanged (`git status` before and after). Then,
for each state the film needs, save a **DOM snapshot** as well as a PNG with `snapshot(page, file)` from
`capture/lib.mjs`. The paper template's app harness is a working harness of this kind: copy
`templates/paper/capture/app/` and `templates/paper/capture/story.json` into the film's `capture/` folder, point
`story.json` `app` at your dev server, and run `node <film>/capture/app/capture.mjs --dom` to save a snapshot of every
shot. A snapshot is one static HTML file that renders like the live page:

- `outerHTML` of the page with every stylesheet inlined as `<style>`, including rules a library inserted through the
  CSSOM (editors do this), written back as text. Scripts are removed.
- Open shadow roots serialized as `<template shadowrootmode="open">`. A **closed** shadow root (a component that
  closes its root in production) must be forced open for the capture: add the library's `INIT_SCRIPT` to the
  context before the page loads.
- State that lives in properties, not attributes, mirrored into attributes: checkbox `checked`, input `value`, scroll
  offsets (`data-snapshot-scroll="top,left"`). A `:hover` style cannot be saved; pin the hovered values inline.
- Chrome your server injects into a page (a header bar, a viewer frame) can be rendered by calling the real server
  function with fixture data and serving the result through Playwright routes.
- For a sequence (select → command → result), capture one snapshot per state in **one continuous session**, so each
  state keeps the earlier changes.

Write what the capture teaches into a notes file next to the snapshots: exact strings ("Save changes", never
"Save"), toolbar order, which command lives in which menu, hover values, scroll positions, and anything broken. One
capture found that a menu command was disabled outside the context the script assumed, that images rendered at
their natural width, and a real bug in the product (a trailing space dropped the next keystrokes).

## 2. Extract

A script, written per product because it depends on the product's DOM, reads the snapshots and writes one
`parts.js` with the pieces the film mounts: for example the header, the toolbar, a whole editor shell, a header bar,
and each state's styles. Replace `:root` with `:host` in every stylesheet, so the product's tokens apply inside a
shadow root. Re-run it whenever the snapshots change.

## 3. Mount

- One shadow root per product surface (editor chrome, page header, each captured state), so an app's 120 KB of
  CSS never touches the film's own styles. A toolbar that lived in its own shadow root gets a nested one.
- The film's fictional document sits in light DOM under the chrome, so the film controls its text directly.
- A sequence of states is a stack of shadow hosts in one window; show one at a time and switch on a click or
  under a whip. Unchanged regions are identical, so only the changed part appears to change.
- Drive state with small setters that set every property on every frame (version text, unsaved dot, Save
  disabled, a "Saving…" strip, which mode button is pressed), never with toggles that depend on the previous frame.

## Gotchas this build paid for

- **Fixed popovers.** Menus are `position: fixed` in the app, so in the film they anchor to the nearest transformed
  ancestor: the whole shot, not the app window. Give the window `transform: translate(0,0)` to make it the
  containing block, as the viewport is in the app.
- **Images in shadow roots are not in `document.images`.** Decode them yourself and expose the promise as
  `window.READY`; the walkthrough template's `render.js`, `previewq.js` and `audit.js` await it. Without it an
  inserted image rendered blank in some frames.
- **Fonts.** `@font-face` rules inside a shadow root are ignored; load the product's fonts in the document.
- **Scroll.** A hidden layer loses its scroll position. Apply snapshot scroll offsets as `translateY` on the
  scroller's children instead of `scrollTop`.
- **Positions.** `offsetParent` chains stop at a shadow boundary. Measure world coordinates from
  `getBoundingClientRect` relative to the shot's world layer, divided by its scale, after the fonts load.
- **Hidden shots keep typed text.** A shot that typed into the DOM and is now hidden must reset that text, or a frame
  reached by seeking differs from one reached on a fresh page and `audit.js` reports a stateful seek.
- **Large captures.** Text that must stay readable at 3× needs a 3× capture or live DOM; a 2× PNG at 3× is soft.

## Stills from the same captures

Marketing stills come out of the same session: a tighter viewport (1120×720 at DSF 3) frames the header and the
content together, which 1600-wide captures cannot. When one value in a still has to change later (one build
replaced a phone extension with a shift time), change it in the saved DOM snapshot and re-render it, rather than
running the capture again.
```

## File: hermes/design/product-film/references/paper-capture.md
size: 14247
sha: f9dad88873f5a8b8f0ed363c13d11762ef54ff02
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/references/paper-capture.md

```text
# Capturing real product UI (Route D)

Every product screen in a Route D film is **the product's real code rendering fictional data**: the web app on its
own dev server, the CLI, any other surface it ships. Route-fulfilled fixtures are fine; hand-built HTML replicas are
not. The two exceptions are the fictional artifact (a page written for the film) and the agent window, a neutral chat
window, because a real agent's UI brings third-party logos.

All harnesses live in `<film>/capture/`, read `capture/story.json`, write PNGs to `capture/shots/` and one manifest
per harness (`shots/manifest-<name>.json`, entries merged by file, so a partial run keeps the rest). They work from
any directory. Each ships with an example that runs as copied: Tidewell, a fictional shared-docs app, with its own
example web app and CLI.

| Harness | Renders | Command |
|---|---|---|
| `artifact/build.py` + `check-layout.mjs` | The fictional artifact's versions, one self-contained file each; the reflow gate | `python3 <film>/capture/artifact/build.py && node <film>/capture/artifact/check-layout.mjs` |
| `shoot-page.mjs` + `shoot.json` | Any local page with named boxes (the raw draft before it is published) | `node <film>/capture/shoot-page.mjs` |
| `agent/` | The agent window, every state, wide (1200×582) and narrow (720×652, for 9:16) | `node <film>/capture/agent/capture.mjs` and `… capture.mjs narrow` |
| `app/` | Your app on its own dev server, every API call answered by `fixtures.mjs` | `node <film>/capture/app/capture.mjs [scene …] [--dom]` |
| `cli/` | Your real CLI against a local fixture API, its output rendered in xterm.js | `node <film>/capture/cli/capture.mjs [run …]` |

Run them in that order: the agent window's card shows the draft screenshot, and the app and CLI serve the built
artifact versions. Fonts for the artifact go in `capture/fonts/`: `node <film>/tools/fetch-fonts.mjs --to
capture/fonts <file>=<Google family>` (OFL fonts only; record them in `notes/sources.md`). `setup.sh` fetched the
example's.

## Capture rules

- **Viewports.** Desktop 1280×800 at device scale 3; phone 390×844 at 3 with `isMobile` and `hasTouch`, so the app
  uses its real touch layout. The film zooms up to about 2.7× CSS size, and DSF 3 keeps text sharp there. Shoot a
  popup at its real popup size (`contextOptions('desktop', { viewport: { width: 420, height: 480 } })`).
- **Boxes from the live DOM**, measured just before each screenshot, in CSS px (`lib.mjs measure()`): `box:` for
  elements; `words:` for words, because an element box is not a word box (Range rects); `ink:` for glyph ink boxes,
  measured with canvas `measureText` in the element's own font, because a Range box spans the whole line box, much
  taller than headline capitals (one line only); `input:` for typed input values, which have no text node; `pixink:`
  for the ink box read from the screenshot's dark pixels, when the canvas measure is off. Zooms and circles target ink
  boxes. Boxes inside an iframe carry the iframe's offset (`_frames` in the app harness).
- **Clean frames.** No text caret, no dev overlay, no injected cursor: the film draws its own pointer. `INIT_SCRIPT`
  hides carets everywhere; `hygiene()` adds the clean-frame CSS as a CDP inspector stylesheet, not a `<style>` node, so
  pages that observe their own DOM do not react. Add the app's own fake carets in `story.json app.hygieneCss`. Park
  the real mouse off the page (`parkMouse()`) so no hover state shows.
- **Story clock.** Install the browser clock at the story's time (`page.clock.install({ time: story.clock })`; the app
  harness does it), so relative times read like the story ("2 min ago"). Fast-forward it to fire a poll instead of
  waiting (`clock.fastForward('00:31')`). Pause it to hold a timed state for a shot (`clock.pauseAt(…)`, then
  `resume()`); a paused clock also pauses `requestAnimationFrame`, so settle without it (`settle(page, ms, { raf:
  false })`).
- **In-flight states.** Hold a fixture response on a `gate()` to capture "Saving…", "Sending…" or "Verifying…"; open it
  for the next state.
- **Millisecond states.** A state that lasts milliseconds ("Saved. Opening…") is taken with `captureWhile()`: raw CDP
  polling, a screenshot the moment the text shows, and a check that it still showed. It warns when it misses; then cut
  from the state before to the state after.
- **Fiction only.** Names, emails and orgs come from `story.json`; avatars show initials. `assertCleanText()` warns on
  placeholder users, error strings and unrendered values ("Unknown user", "undefined", "Try again"…); add the real
  names that must never show to `app.leaks`.
- **Nothing reaches a real server.** `routeApi()` answers API calls from fixtures, lets the app's own hosts and
  `app.allowHosts` load, aborts `app.blockHosts` quietly (analytics, support widgets) and aborts and reports every
  other host. A run passes with zero unmocked calls and zero blocked requests. If the captures run your product's dev
  server, compare its repository's `git status --short` before and after a capture session: the dev server must write
  only ignored files. If a real publish ever becomes unavoidable, use a private throwaway item, delete it afterwards
  and list it in `notes/sources.md`.
- **Record what you learn.** The real code corrects the brief. Write each fact under "Facts the captures surfaced" in
  `notes/DECISIONS.md` and change the script to match, not the other way round.

## The fictional artifact

`capture/artifact/template.html` is a page written for the film, with its own fonts inlined. `story.json`
`artifact.versions[].fill` fills its placeholders per version. Story rules: every version keeps the earlier changes,
and a changed word is one the viewer has already read (the example moves the kickoff to "May 6" after the client asked
"Can we start in May?"). Avoid `vh` units in the artifact: the app shows it inside an iframe.

`check-layout.mjs` renders each version at 1280×800 and 390×844 and compares the boxes and visual line counts of
`artifact.layoutCheck` selectors. A reflow in a `swapViewports` viewport (default desktop) fails the gate: fix the
artifact's own layout and rebuild before any capture. Reflows elsewhere print as INFO; they are fine only while the
film never swaps versions in place in that viewport.

## Agent window

`agent/agent-window.html` draws a neutral chat window titled "Agent" from `agent/agent.json`: messages, typing dots,
tool cards (busy and done, with a preview of the page), a result line with the URL, and `scrollFrom` to drop the first
exchange when the second one starts. It has no tool name and no logo; `product` is your product's name as it appears
in the tool card. Its brand block holds only the accent. The film slides the window in at a state where the prompt is
already there. Its boxes include the URL as a Range box (`url1`), which is the zoom and circle target.

## App harness

`app/capture.mjs` opens your app on its own dev server and answers every API call from `app/fixtures.mjs`; no
backend or database runs. It writes `shots/manifest-app.json` and `app/last-run.json` (each scene's API calls, unmocked
calls, blocked requests and leak warnings) and exits 1 when anything is unmocked or blocked. `--dom` also saves a DOM
snapshot of each shot in `shots/dom/` (§ The capture library).

As shipped, `story.json app.baseUrl` is null and the harness serves the example app in `app/example-app/`. It is small
but has the traps real apps have: relative times, a version poll every 30 s, a one-time notice for a new browser, a
closed shadow root, CSSOM-only rules, a telemetry call to another host, a code form that submits itself on the last
digit and a status that shows for about 120 ms. Its scenes show the pattern for each: `share` (a share dialog: type an
address in three steps, tick an option, Save → Saving… → Saved), `page` (a new version while the tab is open: the poll
offers Refresh, one click loads v2 at the same URL) and `signin` (an invited sign-in on a phone: send the code, five
digits, then the sixth, which submits the form, so the "Verifying…" frame is the last one with all six digits; then
Verified, "Opening page…" over raw CDP, and the page).

To point it at your product:

1. Start your dev server. Point the server's own server-side API URL, if it has one, at a port nothing listens on:
   server-side fetches never pass through the browser, so a missed one must fail loudly instead of reaching a real
   backend. Stop the server when you finish.
2. Set `story.json app`: `baseUrl` (the dev server), `hostMap` (hostnames resolved to 127.0.0.1, when the app needs a
   real-looking host), `apiPrefixes` (where the browser sends API calls: a path on the app's origin or another origin),
   `allowHosts`, `blockHosts`, `testIdAttribute`, and `returningUser`: the localStorage keys that hide one-time notices
   for a returning browser. Grep your code for `localStorage`; the keys are often versioned.
3. Answer every call in `fixtures.mjs` and replace the example scenes at the bottom of `capture.mjs`.

## Writing a new capture flow

A new film usually needs new states. Build them from the real code, never as replicas.

1. Read the screen's components and note every test ID, every API call it makes (method, path, body, headers such as
   ETag and If-Match) and its loading and error strings. Take strings from the code, never from memory.
2. Add each call to `fixtures.mjs`, answering as the real API would: the status, the JSON shape, an ETag on reads, 412
   on a stale If-Match. Keep the values in `story.json` so every harness shares them.
3. Copy an example scene as the pattern: `newScene()` (kind, state, gates), open the route, act with trusted input
   (`typeSlow`, `clickCenter` on test IDs), use `gate()` for an in-flight state, and call `shot()` after each state
   with boxes for everything the film will point at or zoom into. Register it with `run('<name>', …)`.
4. Run it. `last-run.json` must list zero unmocked calls and zero blocked requests, and no leak warnings. Look at every
   PNG.

## CLI

`cli/capture.mjs` runs each `story.json cli.runs` entry in `cli/work/` (after copying its files there) with the CLI's
base-URL variable (`cli.baseUrlEnv`) pointing at `cli/fixture-api.mjs` and its key variable (`cli.keyEnv`) set to a
fake key, so the output is the CLI's own text with fictional data. `render-term.mjs` writes that output into xterm.js
5.5.0 (downloaded once) in Geist Mono and screenshots each typing state with row boxes. `typed` is what appears on
screen; `run` is what executes. The example runs `cli/tidewell.mjs`, a stand-in: set `run` to your CLI, answer the
calls it makes in `fixture-api.mjs` `ROUTES` (`api.log` lists every request), and check that the run reports zero
unmocked calls. A CLI with no base-URL variable cannot be captured safely; add one before filming it. Prefer the agent
window to show an AI agent at work; use a terminal when the film is about the CLI itself.

## The capture library

`capture/lib.mjs` is shared by every route (new-film.sh copies it into each film folder). It imports no Playwright:
harnesses pass in their page, context, CDP session and browser.

| Export | Use |
|---|---|
| `loadStory()`, `CAPTURE`, `FILM`, `SHOTS` | The story and the folders |
| `KINDS`, `contextOptions(kind, extra)` | The desktop and phone capture contexts (light, en-US, UTC, service workers blocked) |
| `INIT_SCRIPT` | Hides carets and forces every shadow root open; add it before the first navigation |
| `hygiene(cdp, css)`, `settle(page, ms)`, `parkMouse(page)` | Clean frames |
| `typeSlow`, `clickCenter` | Trusted input |
| `measure(frame, spec)`, `frameOffset(frame)`, `inkBoxes(browser, png, dsf, regions)`, `MEASURE` | Boxes |
| `manifest(name)` | A manifest merged by file |
| `routeApi(context, opts)`, `gate()` | Fixtures, host rules, in-flight states |
| `assertCleanText(page, extra)` | Leak warnings |
| `captureWhile(cdp, expression, opts)` | Millisecond states over raw CDP |
| `snapshot(page, file, opts)` | A static DOM copy of the page for live-DOM films |

`snapshot()` saves the page as one HTML file that renders like the live page when opened from disk: every stylesheet
inlined (linked, adopted, and CSSOM-only rules written back as text), open shadow roots as `<template
shadowrootmode="open">` (closed ones are forced open by `INIT_SCRIPT`), property state mirrored into attributes
(`checked`, `value`, textarea text, `selected`, scroll offsets as `data-snapshot-scroll="top,left"`), scripts and
inline handlers removed, iframes inlined as `srcdoc`, and assets inlined as `data:` URLs. It cannot save `:hover` or
`:focus` styles; pin those values inline before the snapshot.

## Facts captures surface

Captures correct the brief. These kinds of facts came up in real builds; look for them in every new film.

- **A form submits itself.** A one-time-code form submitted on the last digit, so the state after the last key showed
  "Verifying…", and the frame before it was missing a digit.
- **Relative times move.** "2 min ago" reads wrong unless the clock is pinned to the story's time.
- **Names resolve late.** A widget showed "Unknown user" until a profile poll ran a minute later.
- **A fresh browser sees one-time notices.** Policy, referral and changelog banners appear unless the returning-user
  keys are set.
- **Some states last milliseconds.** A "Saved. Opening…" status was gone before a normal screenshot finished.
- **Buttons do something other than their name.** An Edit button copied a prompt instead of opening the editor;
  check what each control the film shows does in the code.
- **Permissions differ from the brief.** A truth sheet said anyone could comment; only signed-in members could.
- **Third-party logos hide in standard flows.** A general sign-in page showed third-party sign-in buttons; an invited
  flow with one button did not.
- **Copy differs between steps.** One screen said "verification code" and the next "one-time password". The UI stays
  as it is; captions use one term.
- **Paid features look universal.** A version-history list was a paid-plan feature; the film showed version labels
  instead.
```

## File: hermes/design/product-film/references/paper-collage.md
size: 21073
sha: f7e04c1f9dac0ca4b6b6bdd68fa6acf460fd5bd5
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/references/paper-collage.md

```text
# Paper collage films (Route D)

An illustrated cut-paper cast (jointed puppets, busts, a crowd of paper heads) tells a small story over **real
product UI**: screenshots rendered by the product's real code on fictional fixtures. Captions sit on torn typewriter
strips, marker labels and doodles boil on 3s, the cast moves in stop-motion steps on 2s, and the UI never wobbles.
Silent first, with synthesized pen-and-paper sound and empty voice and music tracks ready for a later pass.

The numbers and rules below come from a 59.6 s build that took five cuts; every rule closed a failure in that build
or a note from its review. The template's example is a 22.8 s Tidewell story that exercises every engine primitive.

| Read | When |
|---|---|
| This file | Before anything else |
| `paper-capture.md` | At the capture step, and before any new product screen |
| `paper-lessons.md` | Before you build scenes, and again before every review |
| `templates/paper/` | Start every film from it with `new-film.sh paper`; never from a blank file |

## When to use it

Use Route D when the film needs **people and product together**: a hero with a problem, the product as the turn, a
payoff that shows other people (teammates, clients, a crowd). It suits social cuts (45–60 s), pinned posts, launch
explainers and website films, for any feature, audience or length. The cast, story and product screens change per
film; the kit, engine, capture harnesses and tools stay.

Use another route when:

- one person walks through one flow with a pointer and no cast → Route C (`walkthrough.md`)
- the film is cinematic, with a 3D camera → Routes A and B (`camera-rig.md`)
- the film is fast and designed, with isolated UI at close range → `kinetic-style.md`
- the film is a screen recording of the app → not this skill

A photo cut-out hero from licensed footage was planned once but never built. If you build it, keep one real person
used the same way throughout, and treat the cut-outs as paper prints in the same kit.

## Settle the brief first

Resolve every item and write it under "Preflight" in `notes/DECISIONS.md`. Ask only when the user is there and the
answer cannot be inferred; otherwise decide, and log the decision with its reason.

1. **Audience.** Who, in priority order (from `PRODUCT.md` or the product's positioning, if the project has one), and
   what they do today instead (for the example product: PDFs by email, screenshots in chat).
2. **Takeaways.** The two or three things a viewer knows afterwards, the feeling to leave, and the ending (the
   wordmark, a call to action, the URL).
3. **Truth sheet.** Every claim the film may make, each with its source: the product's docs, changelog, pricing page,
   specs, the voice and naming rules in `VOICE.md` or a style guide if the project has one, the feature's UI copy, and
   the code itself. Product names can mislead: a feature's name may promise more than it does, so read what it does.
   Then the list of what the film must not show or imply (prices, plan names, unshipped features, third-party logos or
   characters, paid-plan features shown as universal). Recheck each line in the code: one truth sheet said "anyone who
   can view can comment", and the code only let signed-in members comment.
   **Stop rule:** if the feature as briefed does not exist, or its core promise differs from what the code and specs
   say, stop before any capture. Ask when the user can answer. When the run is unattended, make the nearest true film,
   and lead the final report with the re-scope and the source that forced it; never quietly make a different film.
4. **Story with a causal chain.** A hero; the problem inside the first 5 s; the product as the turn; the payoff.
   Every change on screen is caused by something the viewer saw. Each version keeps the earlier changes. A changed
   word is one the viewer has already read. Who does what matches the product's permissions (who may view, comment,
   edit).
5. **Formats and length.** 16:9 1920×1080; 9:16 1080×1920 recomposed, not cropped; 16:9 without captions plus an
   .srt; 4:5 1080×1350 optional. 30 fps. 45–60 s for social.
6. **Safe zones and thumbnail.** In 9:16, captions, labels and key UI stay out of the top 250, bottom 480 and right
   150 px. Frame 0 is the thumbnail, and the first 2 s read on their own.
7. **Sound.** SFX only, or silent. Voice and music stay empty tracks unless the user funds and asks for them.
8. **Spend and publishing.** Zero spend by default: no stock, no image, video or audio models. The only thing
   published is the review page, when the user asks. Nothing is published for capture.
9. **Names.** Fictional people and companies only (the template's fiction: Tidewell, Northfield Studio, Maya Chen,
   Sam Rivera, Priya Nair, Jordan Ellis, `@example.com`). Name third-party tools in text, never with their logos.
   Follow the project's naming rules (`VOICE.md`, `PRODUCT.md` or the brief).

## Procedure

Every script works from any directory with absolute `<film>/…` paths; Playwright loads through `<film>/pw.cjs`.
Re-rendering a version starts clean (`render-all.sh` clears that version's mix and checks); prefer a new version
number for every changed cut anyway, so earlier cuts stay archived. Each step ends with a gate; do not start the next
step until it passes.

0. **Folder.** `bash <skill>/templates/new-film.sh paper <folder>`. It copies the template and the shared tools,
   makes sure Playwright resolves, then runs `templates/paper/setup.sh`: fonts, a Python venv (numpy, Pillow), the
   engraved chart background and the per-format plates, the sound set, and the notes skeleton (`NOTES.md`,
   `notes/DECISIONS.md`, `notes/SCRIPT.md`, `notes/sources.md`). Use a folder that persists, outside temporary folders
   (they are pruned) and outside the product's repository. If the captures will run the product's dev server, save
   `git status --short` of its repository now; it must be the same at the end. Check the template runs before you
   change it: the commands `setup.sh` prints.
1. **Truth.** Read the sources in brief item 3, plus `VOICE.md`, `DESIGN.md` and `PRODUCT.md` if the project has them.
   Write the truth sheet under "Truth sheet" in `notes/DECISIONS.md`. *Gate: every planned claim has a source line.*
1b. **Beat sheet.** In `notes/SCRIPT.md`, list each beat with its caption draft, the shot it needs (which harness,
   which state, which viewport) and the character's pose. Block the film out with placeholder scenes in `film.js` (the
   engine draws a labeled placeholder for a missing shot) and preview it, so the capture list comes from the story and
   not the other way round. *Gate: every beat names its shot and harness.*
2. **Brand and fixture story.** Put the product's tokens in `film/timeline.json` `brand` and in the brand blocks of the
   capture templates. Write `capture/story.json` (people, org, page, versions, the change, the one-time code) and the
   fictional artifact (`capture/artifact/template.html`); build it with `build.py`; run `check-layout.mjs`. *Gate: no
   reflow between versions at 1280×800.*
3. **Capture** the real UI with the harnesses in `paper-capture.md`. *Gate: zero unmocked API calls, no blocked
   requests, no leak warnings, the product repository's `git status` unchanged, nothing published.* Write what the
   captures taught you under "Facts the captures surfaced": they change the film.
4. **Kit.** Add the cast to `CAST` in `kit/puppet.js` (the file header says how), and any poses. Only full-body
   characters take poses; busts change faces. New props (a lock, a door, a stamp) are paper pieces in
   `kit/export.html`. Run `node <film>/kit/build-kit.mjs`, then `build-sheet.mjs 0`, `1` and `2`. *Gate: each
   character reads as one character in every pose and boil variant; colors are muted; no garment shares the accent's
   hue.*
5. **Script.** Fill `film/timeline.json`: set `name`, `title`, `summary`, `formats` and `outputs` for this film (they
   flow into file names and the review page), the `copy` rules (§ Quality gates), then scenes with named cues,
   captions, labels, SFX cues, and list every harness manifest you captured under `manifests`. Replace the example
   constants at the top of `film/film.js`. Keep a caption table in `notes/SCRIPT.md` (caption, words, minimum hold,
   hold). *Gate: `python3 <film>/tools/check-copy.py` passes.*
6. **Script review.** An independent review of the script, storyboard, truth sheet and brief by another agent or model
   when one is available (a subagent or a second model). Adjudicate every finding in `DECISIONS.md` as adopted or not
   adopted, with the reason.
7. **Scenes.** Write `film/film.js`, one scene at a time, every format at once (`V({...})`). Preview with the guides
   on: `node <film>/film/preview.mjs 9x16 1,4,7 "" 1 1 1`. *Gate: no warnings in the preview output (a missing shot,
   box or cue is an error in the render).*
8. **Render.** `bash <film>/film/render-all.sh v1 [workers]` renders and assembles every output in `timeline.json`
   `"outputs"`. *Gate: each `out/v1/checks.txt` line has the exact frame count and zero timing jumps.*
9. **Self-review.** Transition strips are cut around scene starts and cues whose names match `review.markCues` in
   `timeline.json` (a regex; the default covers `in`, `zoom…`, `pan`, `back`, `swap`, `click`, `editor`, `out`,
   `v1`…); add your cue names there. Then, for each output: `<film>/.venv/bin/python <film>/tools/review.py
   <film>/out/v1/<name>-<fmt>-v1_master.mov <fmt> <film>/review/v1-<fmt>`; for full-size stills, `bash
   <film>/tools/stills.sh <master> <outdir> [step seconds] [width]`. Look at the phone sheet, every transition strip
   and the difference trace. Fix, re-render and repeat. *Gate: `python3 <film>/tools/gates.py v1` exits 0 and you have
   answered its judgment checklist in `DECISIONS.md`.*
10. **Independent review of the cut.** Another agent or model, when one is available, reviews the contact sheets,
    transition strips, difference trace and full-size stills (reviewers read frames, not video). Adjudicate, fix,
    re-render as the next version, and pass the gates again. Run at least two full improvement rounds.
11. **Deliver.** `bash <film>/tools/deliver.sh vN <poster seconds>`; complete `notes/sources.md` (every asset,
    source, license, spend, anything published or deleted for capture); `python3 <film>/tools/readme.py vN`.
12. **Review page.** Write `notes/review-vN.json` (what changed, what only the user can judge, decisions) and run
    `python3 <film>/tools/build-review.py vN`. It warns over 45 MB.
13. **Publish, only when asked.** Publish the review page on display.dev (`publish.md`): one page, a new version per
    cut, "What changed since vN" on top; never a new page per cut. Read and answer reviewers' comments there. Update `NOTES.md`: current cut, pipeline, what the user
    rejected and why.

For a change to the sound only, remix and remux: `bash <film>/tools/remux-audio.sh vN vN+1` copies the pictures bit
for bit, so every picture check carries over.

## The engine

`film/film.html` loads `film.js`, which imports `engine.js`. `window.seek(t)` draws frame `t` on one canvas,
deterministically, from `timeline.json`, the frozen kit and the captures. Scenes register in `SCENES[id]` with
`draw(tq, s, t)`, `shots()`, and optional `pre`/`post` overlap; `s.cue('name')` gives a cue's absolute time. The
example `film.js` shows every primitive in a five-scene story.

| Primitive | Use |
|---|---|
| `print({ shot, crop, x, y, w, url, kind })` | A capture in a clean window: `browser` (title bar, URL pill), `photo` (card), `raw` (the capture is the window, for the agent window). Returns a layout for `toWorld`/`boxWorld`. |
| `layoutBox(L, box)`, `box(file, name)` | World box of a named capture element, before drawing (cameras, labels). Boxes come from the capture manifests. |
| `phone({ shot, x, y, s })`, `phoneBox` | A clean black phone with a 390×844 capture on its screen. |
| `character(id, x, y, s, t, poses, { look, blinks, face })` | A full-body CAST puppet; `poses = [[t, 'pose', dur?], …]`, eased and stepped. |
| `bust(id, x, y, s, { face, look, tilt })` | Any CAST character as head and shoulders. |
| `hop(t, t0, d, from, to)` | Walk a character in stepped hops: how the hero crosses a cut. |
| `cam(zoomTo(t, in, out, box, s))`, `camOn`, `camFit`, `kf` | One zoom onto the item, a hold, and back. `kf` keys with `'hold'` keep a framing. |
| `captions(t)` | Automatic from the timeline: typewriter strips, one accent word, stepped drop-in. |
| `label(text, x, y, { size, write })`, `note(text, lx, ly, ax, ay, t, t0)` | Hand lettering that writes on; an arrow plus label. |
| `ink(doodle.circle/underline/cross/tick/question/arrow(...), { progress })` | Marker doodles that draw on and boil. |
| `cursor(x, y, { clickAt })`, `pathAt(t, keys)`, `tap(...)` | The paper pointer: straight moves, rests, clicks; taps on a phone. |
| `swapAt(t, [[t, shot, lift?], …])`, `stateAt(t, states)` | Replace a print (lift and land), or step UI states in place (`lift: false` for typing). |
| `slideIn`, `slideOut`, `piece(name, …)`, `wordmark(x, y, h, { align })` | Entrances and exits, any kit piece (speech bubbles, tags, tape), the text wordmark for the end card. |

Query flags: `fmt`, `cap=0` (no captions), `guides=1` (safe-zone box and camera area), `strict=1` (missing shot,
box or cue throws; the render sets it), `tl=<file>` (another timeline), `t0`/`t1` (preload only a range).

**Brand.** `timeline.json` `brand` is the film's one brand block: `accent`, `accentText`, `ink`, `plate`,
`wordmark` and `font`. The kit, the captions, the end card, the chart background and the review page read it. Take the
values from the product's tokens (`DESIGN.md`, `tokens.css`, a Tailwind config or CSS custom properties, if the
project has them; else ask). The capture templates (example app, agent window, terminal) each have their own marked
brand block. After a change, rebuild the kit and the background.

**Background.** The default plate is an engraved nautical chart in the accent and ink: a valley, dense in the bottom
corners and clear in the center, so product UI and text sit on a quiet plate. `node <film>/tools/make-chart-bg.mjs`
renders it from `tools/chart-background.html` into `backgrounds/` (16:9 on the plate, and a transparent lines-only
copy), reading the colors from `brand` (or `--accent`, `--ink`, `--plate`); `<film>/.venv/bin/python
<film>/tools/make-bg.py` composes `film/bg/bg-<fmt>.png` (9:16 and 4:5 lay the lines on the plate, anchored to the
bottom). `setup.sh` runs both. Without them the engine uses a flat plate, which is fine for previews but not for a cut.

## The numbers

These held in a 59.6 s build. Start here and change one at a time.

| What | Value |
|---|---|
| Frames | 30 fps; the canvas renders at device scale 2 (3840×2160 for 16:9), JPEG q95, downscaled once in the master |
| Stop motion | Motion on 2s (15 poses a second); marker lines and labels boil on 3s with 3 seeded variants; UI prints never boil |
| Captures | Desktop 1280×800 at DSF 3; phone 390×844 at DSF 3; popups at their real size (a share popup, for example 420×480) |
| Zoom | 1.12–1.9×, only onto the item the beat is about; in 0.45 s, hold, out 0.45 s; a label written during a zoom lands off screen |
| Holds | 0.5–1.0 s on each key moment with the pointer at rest; a newly opened panel about 2 s; full-screen text about 2.6 s; end card about 4 s |
| Captions | At most 7 words; hold ≥ 1.5 s + 0.3 s per word + 0.5 s margin; one accent word; about 60 words per minute of film (62 in 59.6 s) |
| Caption type | Geist Mono 500 (the accent word 600, in the brand accent) on torn strips: 16:9 56 px centered, bottom 1040; 9:16 58 px, left 34, bottom 1432; 4:5 54 px centered, bottom 1300 |
| Labels | Caveat Brush 44–58 px (46 typical, 52–56 for the key label), arrow 0.3 s, write-on 0.35 s |
| Pacing | Scene boundaries at least 1 s apart; each beat lands 0.5–1 s before the next section; problem inside 5 s |
| Entrances | Slides 0.4 s (ease-out in, ease-in out); hops 0.5 s; caption strips drop in two stepped poses |
| Phone | Scale 1.0 and zoom 1.7× in 16:9 (1.18× showed a phone as two black bars) |
| Cast | Full-body hero about 620 px tall at scale 1; 0.64–0.98 in 16:9, 0.42–0.64 in 9:16 |
| Masters | ProRes 422 HQ, 10-bit 4:2:2, BT.709 limited range with matching tags, PCM 48 kHz |
| Upload copies | H.264 High, level 4.1, CRF 18, faststart, AAC; VMAF ≥ 95 against the master (96.9 in both full builds) |
| Web set | One click-to-play H.264 for the site's video pipeline; AV1, HEVC and H.264 at VMAF ≥ 96, smallest first (4.7, 4.9 and 6.3 MB for 59.6 s). Check the order in `deliver/web/vmaf.txt` and adjust CRFs if it is wrong. |
| Sound | True peak ≤ −1.5 dBTP (mix.py scales to −2.0); integrated ≤ −14 LUFS; an SFX-only track sits at −20 to −23 LUFS, which is fine |
| SFX gains | Caption strip (tape) −17 dB; slide −10; place −9 to −13; circle −13; lettering −17 to −19; click −15; key −19; pop −13 |
| Render | One worker per two cores; about 145 ms per 4K frame per worker (the example's 684 frames × 3 outputs took 3 minutes on 10 cores, with assembly and checks) |

## Formats

Every layout value goes through `V({ '16x9': …, '9x16': …, '4x5': … })`; a missing format falls back to 16:9.
Recompose each format; never crop one into another.

- The camera centers targets on `FOCUS`, the middle of the area captions and platform UI leave free; `camFit` keeps a
  box inside `FREE`. Turn on `guides=1` to see both.
- 9:16 captions sit left (x 34) above the bottom band. Use a narrower agent window capture (`agentn-*`, 720 px) so its
  text reads on a phone. Where two halves of an exchange cannot share a readable frame (a comment and the change it
  caused), put one half beside the page as a taped cut-out.
- In 9:16, labels, tags and bubbles stay out of the right 150 px; a label on the URL bar sits beside the URL, not above
  it. A name tag and a speech bubble beside a phone stack in the column between the phone and the safe-zone edge.
- 4:5 has no platform bands: captions center, and the cast rises above the caption band.
- Check 9:16 zooms separately: a zoom that fits in 16:9 can push a window past the frame edge in 9:16. Check the end
  card too: a headline that fits 16:9 at one scale clips in 9:16.

## Carrying things across a cut

At any moment exactly one scene draws a given character or window.

- The outgoing scene sets `post: 0` (or stops drawing the carried thing at `s.end`); the incoming scene draws it from
  where it was and moves it (`hop` for a character, a stepped move and scale for a window).
- One window moved in place reads as one page; two windows cross-faded read as two pages.
- Clear everything (stepped) before a flat end card fades in.
- Check every cut in its transition strip: a double hero or a doubled window shows there and nowhere else.

## Quality gates

A cut is done when all of these hold. `tools/gates.py vN` checks the first group and prints the second. It exits 0
when every mechanical gate passes, 1 when one fails, and 2 when nothing failed but a gate could not be measured (VMAF
needs an ffmpeg built with libvmaf): report that, and do not call the cut checked.

**Mechanical (gates.py):**

- `check-copy.py` passes. Its rules are `timeline.json` `copy`: banned terms read at run time from `voiceFile` (the
  project's `VOICE.md` or style guide, if it has one) or else from `bannedTerms`; the film's `extraBanned` regexes;
  `spelling` (`us`, the default, flags UK spellings; `uk` flags US ones; `off`); `emDash` (`ban`, the default: the
  house style uses en dashes with spaces, or none); words per caption, holds, one accent word, caption spacing and
  scene spacing. The style-guide format it reads is in the script header.
- Every master: exact frame count, zero timing jumps, BT.709 tags with limited range, VMAF ≥ 95, true peak ≤ −1.5
  dBTP, loudness ≤ −14 LUFS.
- `review.py` has run on every output, and no difference spike is UNEXPLAINED (including runs of 4+ changing frames,
  which mean motion off the 2s grid).

**Judgment (answer each in `DECISIONS.md`):**

- Phone sheet: every caption and label reads at 390 px; nothing overlaps; no UI text is unreadable.
- 9:16: captions, labels, zoom targets and bubbles stay inside the safe-zone box.
- Transition strips: no character or window drawn twice, no pop, no one-frame flash.
- Every zoom lands on the item the beat is about, holds with the pointer at rest, and returns.
- Truth: every caption and on-screen claim matches the truth sheet; nothing shows what may not be shown.
- An independent review of the rendered cut has a recorded verdict, and every finding is adopted or answered.
- You would be proud to post it. Say in the final report what only the user can judge: the cast's charm, the
  caption pacing on a phone, and the sound, which an agent cannot hear.
```

## File: hermes/design/product-film/references/paper-lessons.md
size: 12048
sha: f8b0423c8e91c6c21eed4865033f32eaf2060a52
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/references/paper-lessons.md

```text
# Paper collage: lessons and pitfalls (Route D)

Every failure a full paper build hit, plus the few found while turning it into `templates/paper/`, with what caused
each and the fix that held. Most fixes are built into the template; the rest are rules to apply by hand. Read this
before building scenes and before every review.

## House look rules

They came out of review rounds on real cuts and override a brief where they conflict.

| Rule | Why |
|---|---|
| Give the cast muted color: one skin tone, one hair color and one garment color each (mustard, coral, plum, charcoal trousers; never the accent's hue). Faces, glasses and hand details stay marker ink. | An ink, off-white and gray cast read as colorless and was rejected. |
| Paper only where it tells the story: the cast, caption strips, marker labels and doodles, speech bubbles, problem vignettes, tags, the crowd. | Paper on every surface read as a theme, not a story. |
| Product UI in clean windows: rounded, traffic-light bar, URL pill, soft shadow; no photo border, grain or tape. A clean black phone. | Prints on photo paper with tape made the product look like a prop. |
| A flat end card: the wordmark, a headline, a plain accent pill, the URL, on the plate. No paper card, tape or puppet. | A paper end card buried the call to action. |
| Show an AI agent as a neutral agent chat window, not a terminal, with no tool names or logos. | A terminal undersold how most people use an agent, and a real agent's UI brings third-party branding. |
| Background: the engraved chart (`tools/make-chart-bg.mjs`), not dot fields. | Dot fields and a halftone border read as a frame around the film. |
| Show every digit of a one-time code. | A frame with five of six digits read as a mistake. |
| Sound like a pen writing: toneless, high-passed, no thumps. | Pitched pops and low bodies read as unpleasant, not as paper. |
| No glows, particles or constant drift; things hold still between deliberate moves. | Floating items read as unsteady, and glows tinted the UI. |
| Zoom only onto the item the beat is about, then return. Leave some beats wide. | The same zoom on every beat reads as a template. |
| Hold 0.5–1.0 s on each key moment with the pointer at rest. When in doubt, slower. | Viewers could not read the text in two earlier films. |
| The jitter belongs to the collage. UI text never boils, wobbles or blurs. | The product must read as the real product. |

## Workspace and tooling

| Symptom | Cause | Fix |
|---|---|---|
| Work lost mid-run | A temporary folder was wiped by a session restart | Build in a folder that persists; `new-film.sh` refuses temporary folders |
| `fetch()` fails, the film page never loads | `file://` pages cannot fetch the timeline or the kit manifest | Serve the film folder over http (`tools/static.mjs`); every script already does |
| A script cannot find a file in a folder with a space in its path | `new URL(…).pathname` percent-encodes spaces | Use `fileURLToPath` (the templates do) and quote shell variables |
| `require('playwright')` fails from a film folder | Playwright is not installed where the script runs | Every script loads it through `<film>/pw.cjs`; `new-film.sh` installs it once per folder, or set `PLAYWRIGHT_DIR` |
| `pip install` refused | PEP 668 | The film's `.venv` (numpy, Pillow), made by `setup.sh` |
| No burned-in timecodes | Some ffmpeg builds have no `drawtext` | Name frames by index; review sheets label times with Pillow |
| VMAF missing from the checks | The ffmpeg has no libvmaf | `check-master.sh` writes "VMAF not measured" and `gates.py` exits 2; install an ffmpeg built with libvmaf |
| A reference-library connector unavailable | It needs an interactive sign-in an unattended session cannot do | Fall back to open references and note it |
| The second reviewer model unavailable | Out of quota | Use another available model or a subagent, and record which |
| The CLI harness hung | A synchronous child process blocked the fixture API in the same process | Run the CLI asynchronously (the template does) |

## Capture

| Symptom | Cause | Fix |
|---|---|---|
| The one-word edit made the page jump | At 1280 px the new headline wrapped to two lines, the old one did not | Fix the artifact's layout (a wider text column) and re-shoot; `check-layout.mjs` gates it |
| Zoomed UI text soft | Captured at DSF 2 at 1440 px | Desktop 1280×800 at DSF 3, phone at DSF 3 |
| The film claimed a click opened the editor | The button copied a prompt; the editor lived at its own URL | Read what each control does in the code; show the editor print replacing the page print with no click |
| The truth sheet said anyone can comment | Only signed-in members could comment | Only a member comments on screen, labeled "teammate"; the client only views |
| Third-party logos on screen | A general sign-in page showed third-party sign-in buttons; a demo had a rail of tool logos | Use a flow without them (an invited sign-in with one button); leave the rail out; name tools in text |
| The one-time code missed its last digit | The form auto-submits on the last digit, so the state after five digits was the last full frame | Capture the "Verifying…" frame: it shows every digit |
| A reply showed "Unknown user" | The widget resolved new authors on a 60 s profile poll | Fast-forward the clock past the poll before the shot; `assertCleanText` warns |
| A banner in the first app shot | One-time notices (policy, referral, changelog) for a new browser | Set the returning-user localStorage keys (`app.returningUser`); they are versioned, re-read them |
| "Saved. Opening…" missing | The status lasted milliseconds before the next page replaced it | `captureWhile()` polls over raw CDP and screenshots while the text is present; accept the settled state if it misses |
| Zoom and circle targets too tall | Range boxes span the whole line box, far taller than headline capitals | Use glyph ink boxes (`ink:`, or `pixink:` from the screenshot) |
| A circle landed beside the word | The canvas ink box was measured in the parent element's font | Measure in the element that holds the text (fixed in `lib.mjs`); compare `ink:` with `pixink:` when in doubt |
| A DOM snapshot lost a focus ring | `:focus` and `:hover` are live states, not markup | Pin those values inline before `snapshot()`, or accept the unfocused state |

## Kit and engine

| Symptom | Cause | Fix |
|---|---|---|
| A piece silently changed shape | Two kit pieces shared a name and the second overwrote the first | Names are `<character>.<part>`; `export.html` throws on a duplicate |
| 4K frames took seconds each | Each marker stroke drew into a full-frame offscreen canvas | Stroke-sized offscreen canvases in device space (`kit.js marker`) |
| Every render worker held every capture in memory | All shots preloaded in each of 6–7 workers | Scenes declare `shots()`; a worker preloads only its range (`t0`/`t1`) |
| A mistyped cue drew at the scene start without any error | `cue()` fell back to 0 for an unknown name | An unknown cue, shot or box is an error in the render (strict mode) and a warning with a placeholder in preview |
| Captions stepped between motion steps (a "1 s cadence") | Caption steps ran from each caption's start, often an odd frame | Caption steps use the same 2-frame grid as motion |

## Story and cuts

| Symptom | Cause | Fix |
|---|---|---|
| The hero drawn twice for a few frames at two cuts | The outgoing scene slid the hero out while the incoming scene drew the hero again | Carry one character: the outgoing scene stops drawing; the incoming one `hop`s the character from where it was |
| The same page window drawn twice in the late transitions | Each scene drew its own copy of the window | Carry one window and move or scale it in place (on 2s); clear everything before the end card |
| An empty agent window at the turn | It slid in before its first message | Slide it in with the prompt already there |
| A caption said something the screen did not show | "The agent reads the comment" with no reading on screen | Add the beat (the agent window returns and quotes the comment) or cut the claim |
| Viewers read the client as the commenter | Two new faces in a row with no names | A name tag ("Priya · teammate") and a label on the client ("client") |
| A later edit felt arbitrary | The new word had no cause | The comment or question contains the new word; the new version keeps the earlier change |
| A plan claim ("unlimited X on every plan") risked implying plans | Plan claims in a pinned film | Say what the product does; no prices, no plan names |

## Layout and formats

| Symptom | Cause | Fix |
|---|---|---|
| Labels, "same URL" or bubbles under platform UI in 9:16 | Placed in the top 250, bottom 480 or right 150 px | `guides=1` in preview; the review sheet draws the safe-zone box; move labels beside the target |
| A window clipped at the frame edge in 9:16 | A zoom that fits 16:9 overshoots in a narrow frame | 9:16 zooms less, or the agent window stays at base framing |
| A label cropped by the zoom | The label was written during the zoom | Write it after the zoom-out, or inside the zoomed area |
| A name tag sat over a button in 9:16 | The tag stayed during the zoom | The tag leaves when the zoom starts, or arrives after it |
| A name tag hidden under the caption | Placed in the caption band | Keep tags and bubbles above the caption strips in every format |
| Captions hard to read on a phone | 50 px captions at 390 px width | 56 px in 16:9, 58 px in 9:16; check the 390 px sheet |
| The halftone read as a frame | A dense accent-color dot border | Toned down, then replaced by the engraved chart |
| The agent window's text unreadable in 9:16 | The 1200 px window scaled down | A 720 px narrow capture for 9:16 |
| The comment and its change could not share a readable 9:16 frame | The page is too wide | Show the thread as a taped cut-out beside the page |
| The end-card headline clipped in 9:16 | The 16:9 scale was reused | A smaller end-card scale in 9:16 |

## Review, encode and deliver

| Symptom | Cause | Fix |
|---|---|---|
| Flicker and double draws missed in stills | You read frames, not video | Transition strips (every frame ±0.5 s) and the difference trace; every spike must match a timeline event |
| Frames dropped, audio drifted | Joining H.264 chunks by stream copy | One ffmpeg pass over numbered frames into ProRes; check exact frame count and zero timing jumps |
| VMAF misaligned frames for AV1 | A WebM's 1 ms timebase | AV1 in MP4 (1/30 s timebase) |
| Colors shifted between players | Tags that did not match the pixels | Convert with `scale=out_color_matrix=bt709:out_range=tv` and tag bt709 primaries, transfer and matrix |
| The web set was not ordered by size | CRFs not tuned for this content | Read `deliver/web/vmaf.txt`; at VMAF ≥ 96 the order should be AV1 < HEVC < H.264 |
| A review page over display.dev's 50 MB limit | Videos are embedded as base64 | 720p CRF 24, a 1080p CRF 22 download, 9:16 at 540×960 CRF 25; `build-review.py` warns over 45 MB (50 MB fits most hosts) |
| ffmpeg in a loop ate the loop's input | ffmpeg reads stdin | `-nostdin` everywhere (the templates have it) |

## Sound

The first set was rejected in review as unpleasant and unlike writing. Measured cause: a stick-slip marker squeak
with 50–60 % of its energy at 300–1,200 Hz and spectral flatness 0.05; pops sweeping 900 → 260 Hz (flatness 0.007);
clicks, keys and an end-card stamp with 48–98 % of their energy below 300 Hz. The v2 set in `sfx/synth.py` has no
pitched tones and is high-passed at about 420 Hz: labels are 3–5 short pen strokes with lifts, circles one continuous
scratch that speeds through the curve, Xs two quick strokes, pops toneless pen-tip taps. Measured: 0 % below 300 Hz,
centroid 4.7–6.7 kHz, flatness 0.2–0.35. A crowd's 23 taps were thinned to 12. `sfx/measure.py` flags PITCHED and LOW
sounds.

An agent cannot listen. Measure every sound, and tell the user the sound is unheard and needs their ears.
```

## File: hermes/design/product-film/references/publish.md
size: 4432
sha: 36d8760b82ba312f8f43a936118537dae682b5b0
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/references/publish.md

````text
# Publish and review on display.dev

Every film is reviewed on one display.dev page: the review page (cut, poster, what changed, scene table) is published
there, each new cut becomes a new version of the same page, and feedback arrives as comments on it. This is the only
step that reaches an external service. Publish only when the user asks, or when the procedure reaches the review step
and the user has asked for a review page.

## Transport: the first one available wins

Detect at run time, in this order. Do not retry across tiers.

1. **MCP.** If the host's tool list has a display.dev `publish` tool (an OAuth-connected remote server, or a local
   stdio bridge), call it. Remote MCP takes `content` (the HTML string); local MCP takes `content` or `file_path`.
   Both need `name`; pass `visibility` when the user named one.
2. **CLI.** If `dsp` is on `PATH` (or `npx -y @displaydev/cli` works), use it. It is the tier for versions,
   visibility, sharing and comments:

   ```sh
   dsp publish <film>/review/review-vN.html --name "<Film title> – review" --company --client-source product-film-skill@0.2.0
   ```

3. **Anonymous helper.** With neither, run the bundled helper. It needs no account: it returns a 30-day preview URL and
   a claim URL the user can sign up against. It cannot version, share or read comments; after the user claims the
   page, later cuts go through the CLI.

   ```sh
   bash $SKILL_DIR/scripts/publish.sh <film>/review/review-vN.html --name "<Film title> – review"
   ```

   `scripts/_common.sh` resolves the bundled jq (`bin/`), the API URL (`DISPLAYDEV_API_URL`, production by default)
   and attribution.

If the host has no shell, go straight from tier 1 to telling the user where the file is.

## One page per film, one version per cut

- **First cut:** publish with company visibility (`--company`, the CLI default) unless the user named another;
  reviewers are usually the team. Use `--share-with <emails>` to add outside reviewers by name, `--visibility public`
  only when asked.
- **Every later cut:** a new version of the same page, never a new page:

  ```sh
  dsp get-metadata <shortId>            # read currentVersion first
  dsp publish <film>/review/review-vN.html --id <shortId> --base-version <currentVersion> --client-source product-film-skill@0.2.0
  ```

  `--base-version` must equal the current version; a mismatch means someone else published since, so read the page
  before overwriting it.
- Record the shortId in the film's `NOTES.md`, next to the current cut.

## The review page

Self-contained HTML, one file: transports publish a single file and do not upload a separate video, poster or image,
so embed them as base64. Keep it under 50 MB (the routes' review builders re-encode the review copy to fit, and
`build-review.py` warns over 45 MB). On top: the player and poster, then "What changed since vN", then a scene-by-scene
table (time, section, what is on screen), then decisions and what only the user can judge (taste, the sound). Offer
the MP4 as a download from the page and send it as a file too.

## Loop on comments

Reviewers comment on the page, anchored to the part they mean. Read and answer them there:

```sh
dsp comment list --artifact <shortId> --status open --actor-name <agent-name>
dsp comment add --artifact <shortId> --parent <rootCommentId> --body "Changed in v4: ..." --actor-name <agent-name>
dsp thread resolve <rootCommentId> --actor-name <agent-name>
```

Batch a round of changes into one new version rather than many small publishes; each publish is a version reviewers
see in the history. Reply to each thread with what changed and in which version, resolve it once the new version is
up, and leave taste calls the change did not settle open for the user. Record durable notes in the project's
`FILM.md`. Pass `--actor-name` on every call so the agent's work is attributed to the agent, not to the person whose
login the CLI uses.

## After a publish

Tell the user, in plain prose:

- the URL, first;
- the shortId (the handle for the next version);
- one line on what was published (the film and the cut);
- for an anonymous publish, the claim URL and that the preview expires in 30 days unless claimed;
- one question about the next step.

Leave out transport details, headers and analytics fields. On failure, say what to do next (sign in with `dsp login`,
retry, check the network) instead of pasting the raw error.
````

## File: hermes/design/product-film/references/reel-style.md
size: 9894
sha: f7bb3b29a60b3ba3642dcf65bd4e9d2245c632ae
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/references/reel-style.md

````text
# Reel style

A launch reel cut to music on flat brand plates. Each section is one claim and the real product doing it, and every
cut lands on the music's bar lines. Use it when a launch needs **breadth** in 25–35 s: a product or a release with
several capabilities, each shown once. For one flow told in depth, use the kinetic style (`kinetic-style.md`); for an
illustrated story, Route D.

It is a Route B film (product beats only) on the walkthrough pipeline: `templates/walkthrough/reel.html` with
`plan-R.json` renders, audits and assembles like the other walkthrough pages. The pointer and flicker rules in
`walkthrough.md` still apply.

The numbers below were measured on a 33.5 s reference reel at 1080p60 (4K masters), cut to a 126 BPM bed with no
voice, mixed to −14 LUFS.

## Structure

| Section | Bars | What happens |
|---|---|---|
| Range | 2 | A wall of the product's range (its templates, pages, designs) builds row by row, one row per beat. On the second bar the wall dims under a veil and a big claim types in at left, its second sentence in the accent. |
| Reveal | 2 | The drop. The wordmark focus-pulls in from blur (about 0.15 s), with a blinking caret. A mono feature line types word by word under it. On the second bar the wordmark shrinks to a small header and the tagline rises in, one line per half-beat, its second half in the accent. |
| The default | 2 | The problem as real artifacts, not words: the same generic result three times (or the same thing in three scattered places), stacked into a row and red-lined with small labels: code-like when the problem is technical (`font-family: Inter`), a handwritten red pen when it is human ("which version?"). The claim names the problem in one sentence. |
| Proof | 1 | One claim of proof ("We made this page with it", "Your client opens one link") with its key word tinted in the accent, and a real page sliding up in a browser window and scrolling. |
| Capabilities | 1–4 each | One section per capability: a mono kicker with the exact command or feature, a claim, and the product doing it. A section with several examples (three before-and-afters) gets 4 bars; a quick one gets 1. |
| Verbs | 1 | A list beat: the product's commands or options pop in one per half-beat; the newest is highlighted, the rest settle. |
| Setup | 2 | How to start: a command or prompt types in a field, a pointer clicks Copy → Copied ✓, and a status row shows the next state. The music drops back here. |
| End card | 2 | The hit. Wordmark with the caret, a mono tagline, a hairline, a mono feature line, a URL pill, and optionally a small maker line. |

The reference ran range, reveal, default, proof, four capability sections, setup, end. Keep the arc
(range → name → problem → proof → capabilities → start → end); the capability sections change per product.

## Timing on the music

| What | Value |
|---|---|
| Grid | One tempo for the whole film (126 BPM in the reference: beat 0.476 s, bar 1.905 s). Section boundaries fall on bar lines. |
| Section lengths | Main beats 2 bars, quick beats 1 bar, a multi-example beat up to 4 bars. The reference's bar lines fell at 0.005 s + n × 1.904 s; its cuts at 3.82, 22.87, 26.67 and 30.48 s sat on them and one (7.73 s) landed 0.11 s late. |
| Events inside a section | Wall rows on beats. Product state changes, list words and tagline lines on half-beats (0.24 s). Product clicks through options on half-beats too. |
| Drop and hit | The drop lands on the reveal (the wordmark); the second hit lands on the end card. Put a quieter stretch under the setup section so the end card has something to land on. |
| Track | Lay a track the user supplies (`kinetic-style.md` § Music for start point and loudness). Find its tempo and bar lines with `beatmap.py`, then set `BPM` and the offset at the top of `reel.html`. With no track yet, pick a tempo (120–128 BPM suits a launch) and cut to its grid, so a track can go under it later without re-timing. Composing music stays out of scope. |

A transition may start up to 0.1 s before the bar so that it lands on it. Never cut between beats.

## The look

| Rule | Why |
|---|---|
| Two flat brand plates, one dark and one light, alternating by section. No texture, grain, vignette, glows or particles. | The plate change is the reel's rhythm; texture fights the brand colours and the product screens. |
| Claims top-left, about 106 px from the left and 84 px from the top on a 1920×1080 frame, 64–72 px bold with tight tracking (−0.045em), one or two lines, ending with a period. | A fixed claim position lets the eye go straight to the product beside it in every section. |
| A mono kicker above each claim names the exact command or feature, in a faint pill on dark plates. | It ties each claim to something the viewer can type or find. |
| One accent: the second half of the tagline, one tinted word in a claim, the highlighted list word. | More accents compete with the product's own colours. |
| Product screens in clean windows with a soft shadow, at fidelity, playing their own loops where they have them. | The proof is the real product, not an illustration of it. |
| A small mono "Fictional brands" label bottom-right whenever made-up brands appear in product screens. | Viewers read polished fixtures as customers. |
| List words about 100 px; the range claim about 128 px, the reveal tagline about 106 px, the reveal wordmark about 230 px, the end-card wordmark about 190 px. | List beats read at a glance; the opening and the last frame belong to the name and the promise. |

## Motion and transitions

- **Text** rises in from a mask: clip the line box and translate the line up into it, one line per half-beat. No
  fades on text.
- **Typing** is a burst at about 50 characters per second with a caret, so a full setup prompt fits in one bar. This is
  faster than the kinetic style (16) or a walkthrough (25–32) because the reel never holds to read a prompt; the claim
  above it carries the meaning.
- **Lists** pop one word per half-beat; the newest word takes the accent (or a hand-drawn dashed box and a small
  sparkle), earlier words settle to the plate's text colour.
- **Pointer** only for a click that changes state (Copy → Copied ✓): arrive, press at scale 0.84, release.
- **Between sections:** a hard cut exactly on the bar for most boundaries. Between a light and a dark section inside a
  phrase: a plate wipe, the next plate rising from the bottom in 0.10–0.15 s. To leave a product section: a dive, the
  window scaling up to fill the frame over about 0.25 s, then the cut. No dissolves.

## Copy

- One claim per section, 3–6 words, a complete sentence with a period: "Comment on the exact line.", "Every version,
  same link.", "Start in one line." Claims come from the product's README, docs or landing page,
  checked against the truth sheet.
- The problem section's claim names what the audience lives with today ("Feedback lives in five places."); its artifacts
  prove it.
- The kicker is literal: the command, flag or menu item, as the product spells it.
- "Free" or "open source" qualifies exactly what is free or open; a reel moves too fast for footnotes.

## Template and commands

`templates/walkthrough/reel.html` (with `plan-R.json`) is a working Tidewell reel of 14 bars at 126 BPM (26.7 s):
range, reveal, default, proof, two capability sections, a verbs list, setup and the end card, with every device above.
Its first script holds `const BPM, OFFSET` and the `SECTIONS` table (id, bars, plate, entry `in: 'wipe'`, exit
`out: 'dive'`, kicker, claim, the "Fictional brands" flag); every time on the page derives from them, and
`window.SECTIONS` exposes the section times for previews and the review page's scene table.

```
python3 <film>/beatmap.py <track> [--start S] [--bars N] [--hits N]   # BPM, bar grid, strongest hits, a BPM/OFFSET line to paste
PAGE=reel.html node <film>/previewq.js out.jpg "beat=R@12.4"          # single frames
node <film>/audit.js plan-R.json                                      # pointer rests, one-frame jumps, stateful seeks
node <film>/render.js plan-R.json                                     # or PLANONLY + plan-jobs.py for parallel workers
bash <film>/assemble.sh plan-R.json                                   # film-R.mp4, film-R_master.mp4, film-R_720.mp4, poster-R.jpg, sheet-R.jpg
```

- `OFFSET` is the film time of the first bar line; before it the first section's plate holds as a lead-in.
  `beatmap.py` prints the track start point that makes it 0, and an ffmpeg line that lays the track under the film;
  level and fade it as in `kinetic-style.md` § Music.
- Times inside a section are beats from its bar line, and a dive counts back from the section's end, so giving a
  section more bars adds a hold at its end. Re-audit after any change to `BPM`, `OFFSET` or bars.
- Hard cuts need no marking for the audit: each section is its own element, hidden outside its bars.
- There is no square cut yet; recompose for 1:1 or 9:16 as a separate pass.

## Review page

Add a scene-by-scene table (time, section, what is on screen) under the player, then review notes and open questions.
A reel is too fast to discuss without timestamps, and reviewers comment against the table.

## Gotchas already paid for

- A product's preview or fixture stylesheet can override the colors a real user sees (dark previews rendered light).
  Check every captured screen against the shipped product before it goes on the wall.
- Captured internal tools carry internal names and real third-party product names (segment names in a title, an agent
  product named in mock comments). Scan every capture's visible text and replace them with fictional names.
- A 44 s first cut tightened to 24 s and settled at 33 s. Cut capabilities, not bars: a section shorter than one bar
  cannot be read, and the grid only works in whole bars.
````

## File: hermes/design/product-film/references/walkthrough.md
size: 12700
sha: c0effcfa32c8c4dd74a8260ff7bd3aa2f65559b5
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/references/walkthrough.md

````text
# Walkthrough films (Route C)

A pointer drives the product through one causal story: select, comment, publish, share, and so on. This is the
route for store-listing promos and feature launch films, and its default register is the kinetic style
(`kinetic-style.md`): isolated UI at close range on white, no caption band. This file holds what every film on the
walkthrough pipeline shares, kinetic and reel cuts included: the pointer, flicker, current-UI and true-claims rules,
the numbers, the engine patterns, the checks and the pipeline. It also holds the plain look with a caption band or
text cards, which is built only when the user asks for it.

The rules below come from one store-listing promo that took seven published versions and about twenty renders. Each
rule closed one review note. Apply them from the first cut. `templates/walkthrough/` has the engine and pipeline with
every rule below built in.

## The plain look (captions and cards, on request)

The cinematic defaults of Routes A and B were rejected for this kind of film, one review round at a time.

| Rule | Why |
|---|---|
| Neutral plate `#F3F3F3` with a static background image. No color glows, particles, grain or vignette. | Color glows tinted the UI. |
| Default background: the engraved chart background (`tools/chart-background.html`; `node tools/make-chart-bg.mjs` renders it in the brand accent to `backgrounds/`, where `beats.html` picks it up). The alternative is a static halftone field in the brand accent. Either way, the center stays clear (valley shape), and the image is the same in every clip. | Chosen after 27 options. |
| Only the subject moves. No camera drift, no slow scale-up on cards or titles, no push while nothing happens, no tilt. | Floating items read as unsteady. |
| A 2D camera, not a 3D rig. | 3D perspective made text soft at 1.8×. |
| One base framing per scene. Zoom 1.4–1.9× only onto the item the step is about, then go back to base. Leave some steps wide. | The same zoom on every beat reads as a template; with no zooms the key items were lost. |
| Pointer and highlight move as one. A selection highlight's width comes from the pointer tip, and a drag is a straight line. | A highlight that trails the pointer reads as a bug. |
| Editing never shifts the layout. The caret is always in the DOM and blinks by opacity; edited text keeps a min-height. | The text flickered and jumped vertically while it was typed. |
| Slow enough to read (see the numbers). | Text and key items were not on screen long enough to read. |
| The UI is the current UI. | The film showed UI the product had already removed. |
| The pointer never stops in the middle of a move, and never waits long before the next one. | A pause mid-move, or before the next move, reads as a stuck pointer. |
| A newly opened panel stays on screen long enough to read. | A panel that closed at once could not be read. |

These look rules apply to the captions and cards cuts. The kinetic style replaces them and is the default; its
example engine, `templates/walkthrough/kinetic.html`, runs on the same pipeline. The pointer, flicker, current-UI and
true-claims rules apply to every cut.

## Settle before building

1. **Persona and one causal story.** Who, which page, what they do, and who receives the result. For example: a
   product marketing consultant reviews a client's homepage, comments on three lines, publishes it privately to
   the client, an agent applies the comments, and the consultant trims the headline in-line. Every UI change on
   screen is caused by a visible click. State carries across scenes (v2 shows all three comment outcomes).
2. **Current UI.** Take strings and layout from the shipped code. Run `git log --since="1 month ago" -- <ui paths>`
   to catch recent redesigns before you mirror anything. Stale UI cost a full round.
3. **True claims.** Check every limit, client name and plan claim on screen against the product's truth sources:
   the docs, changelog, pricing page, specs and the code itself (for example a per-page comment limit, or which
   clients are documented as supported). Drop lines that do not help this audience ("Free to start" was cut as
   irrelevant).
4. **Closer copy from evidence.** A "No X. No Y." closer names what the audience does today. Research it first
   (for website feedback: email threads, screenshots, spreadsheets, PDFs, screen recordings).
5. **Say what it is.** For a browser extension, the title subline names what it is and whose it is ("The browser
   extension by <brand>"), and the first shot launches it from the browser's extensions menu.
6. **Fact-check real-world conventions** (charts, maps, code, legal text) before you show them. Reviewers check.

## Captions or cards (on request)

Build these only when the user asks for a caption band or text cards; otherwise make a kinetic cut. When asked,
build both from the same scenes, put them on one review page, and let the team pick.

- **A, captions.** One continuous take per scene. Captions sit in a band at the top, and a new caption cross-fades
  in at each chapter boundary inside the take. One build's cut A ran 47.7 s.
- **B, cards.** Full-screen text cards (116 px, one accent word, an optional 34 px subline) between product
  shots. The shots are cut from the same scene timelines with `toff`/`tend` and run in `mode=cards` (browser
  centered, no caption band). The same build's cut B ran 60.4 s.

A scene list that worked: title 2.4 · main take about 17 (scene seconds) · agent 4.2 · in-line edit 4.4 · closer
2.9 · end card 5.0. A length of 45–65 s was acceptable.

## The numbers

| What | Value |
|---|---|
| Frames | 1920×1080, device scale factor 2, 60 fps, JPEG q93; x264 CRF 15 per clip, CRF 14 master |
| Dissolve | 0.5 s (A), 0.45 s (B) |
| Global slowdown | scene time × 1.2 (`slow`) |
| Holds | 0.5–1.0 s on each thing worth reading, only where the pointer rests; 0.4 s after a state-changing click |
| New panel before a cut | ≥ 2 s on screen (use a plan `tail` to hold the last frame) |
| Cards | 2.6 s; 2.9 s with a subline. Title 2.4 s, end card 5 s |
| Caption | 76 px, weight 800, −0.045em, top 74 px; subline 28 px at 170 px; band 174 px solid + 20 px fade |
| Caption timing | First caption starts 0.3 s (scene) into the clip, after the dissolve midpoint. The last one fades out before the dissolve is half done. Text never dissolves into text. |
| Base framing | browser 1500×810 at (210, 228), camera m 1.1 |
| Zoom | 1.4–1.9×, 0.5–0.8 s cubic in-out, scale interpolated in log space, clamped so the browser fills the frame |
| Entrances | fade + 12–20 px rise + scale 0.98→1 over 0.3–0.5 s ease-out; chips pop 0.7→1 with a back-ease over 0.34 s |
| Ground | page blur 0.9 px and 5 % darker behind a popover or dialog |
| Pointer travel | 0.3–0.7 s for a hop, 1.1–1.7 s for a glide across the frame; slight arc (≤ 60 px) |
| Drag | straight, 0.35–0.7 s |
| Click | arrive, then press ≥ 0.05 s later; press dips to scale 0.84 over 0.08 s and releases over 0.16 s |
| Idle before the next move | about 0.5 s, unless a hold or typing is the point. Start the next move while the UI changes. |
| Typing | 25–32 characters per second of real time. Caret blink 2.2 Hz, 55 % on. |
| Closer ("No screenshots. No email threads.") | 116 px, line-height 1.36, strike bars 0.085em at 53 % |

## Engine patterns

All of these are in `templates/walkthrough/beats.html`, with comments. Its brand block (accent, ink, plate, grays,
fonts) is the one place to rebrand.

- **Holds by time warp.** Write scene timelines at authored speed. `HOLDS[scene] = [[sceneTime, realSeconds], …]`
  freezes the scene there. `warp(real) → scene` and `unwarp(scene) → real` apply the slowdown and the holds.
  `window.clipDur(a, b)` gives render.js the real length of any scene range, so plans list scene ranges and never
  real durations.
- **Plans.** `plan-A.json` / `plan-B.json` list clips as `{id, beat, toff, tend, tail?, i?, dur?}` with the plan's
  `xf`, `slow` and `mode`, and optionally `page`, `w`, `h` and `q` (extra query parameters). `tail` holds the frame
  at `tend` for extra real seconds. Cards give `dur` directly.
- **Camera.** `cam(t, [B0(t), Z(t, cx, cy, m), …])`: eased keyframes; `clampK` keeps the browser filling the
  frame; `#band` lets zoomed content pass under the caption.
- **Pointer.** `cursor(el, t, keyframes, presses, show)` returns the tip. Drive a highlight with
  `(tip.x − box.x) / box.w`. Put a hold only on a keyframe pair where the pointer rests.
- **Caret.** `caret(t, focus, typingEnd, off)`: solid while typing, blinking from the scene-time phase after that,
  with no one-frame flash before `off`. A blink phased on film time flashed for one frame in one cut and not in the
  other.
- **Film time.** Anything that must run continuously across a dissolve (a blinking cursor in a wordmark, a ticking
  clock) runs on film time, `g0 + t`, which render.js passes per clip.
- **Centring.** Set the text, then center (`centreText`). The reverse shows the element off-center for one frame.
  Give changing status text a fixed `min-width`.
- **Class names.** Scope classes per component. A toolbar `.eb` once restyled the page's eyebrow `.eb`.

## Check before every publish

1. `node <film>/audit.js plan-A.json` (and plan B). It lists pointer rests, flags any hold that freezes a moving
   pointer, flags any element that jumps for one frame (box, opacity or text), and flags a stateful `seek` (a frame
   whose visible text differs when reached from a fresh page). Fix every flag. Then look at each rest longer than
   about 1 s: is it typing or a deliberate hold? If not, start the next move sooner.
2. `node <film>/previewq.js out.jpg "beat=s1&dur=10.08@4.2" …` at each hold and each click, full size. Take `dur`
   from `plans.txt`: captions time their exit from it. The tiles land in `<film>/preview/`.
3. The contact sheet `assemble.sh` writes (1 fps), for continuity and framing.
4. Watch the 720p file once at real speed. Pacing notes come only from watching.

## Pipeline

Every script resolves its paths from its own folder, so it runs from any working directory.

```
PLANONLY=1 node <film>/render.js plan-A.json > <film>/plans.txt         # durations and film offsets
PLANONLY=1 node <film>/render.js plan-B.json >> <film>/plans.txt
python3 <film>/plan-jobs.py 5 plan-A.json:s0,s1,s2 plan-B.json:B02     # split across workers → jobs.sh
bash <film>/jobs.sh                                                     # about 1 worker per 2 cores
bash <film>/assemble.sh plan-A.json    # → film-A_master.mp4, film-A.mp4 (1080p60), film-A_720.mp4, poster-A.jpg, sheet-A.jpg
node <film>/render.js plan-A.json s1:600:780                            # re-render only a frame range of a clip
```

The whole A+B render took about 10 minutes on 5–6 workers. After a change to one scene, re-render only the clips
that use it.

**Review page.** One page for every cut of the film, published on display.dev (`publish.md`): a new version per cut,
"What changed since vN" on top; never a new page per cut. Embed each cut once as base64, re-encoded at CRF 23 so the
page stays under 50 MB, each with its own poster (A: a caption over the product; B: a
card). A browser-extension store usually takes the promo as a video-host URL; upload `film-X_master.mp4` or
`film-X.mp4`.

## Gotchas already paid for

- Wait for fonts and image decode before the first screenshot (render.js does). For canvas text, call
  `document.fonts.load()` for each face first, or it falls back to serif.
- Under load a screenshot can stall; render.js reloads and retries the frame.
- Playwright `setContent` on `about:blank` cannot load `file://` images. Go to a `file://` page first.
- ffmpeg writing one image needs `-update 1` or `-frames:v 1`; a tile sheet with more frames than tiles needs
  `-frames:v 1`.
- zsh aborts a command chain on an unmatched glob (`rm frames/s*`). Use explicit paths or fresh folders.
- Removing a function with a range edit can take its neighbor with it. Keep a `beats-vN.html` backup per cut.
- `seek(t)` must not depend on earlier frames. Renders seek in order; previews load a fresh page per frame, so a
  stateful `seek` passes every preview and breaks the render. Look at the rendered contact sheet, not only previews.
- Size every container for its fullest state (three comments, the longest label). A list that overflows its panel
  shows the footer's border running through the last card, and a close-up makes it obvious.
- Take radii, borders and focus rings from the product's shipped CSS. At 2× zoom a 2px focus border next to 1px
  fields reads as a heavy double outline.
````

## File: hermes/design/product-film/bin/jq-linux-amd64
size: 2319424
sha: 37a7a66811fb37eb8592d79fdcc56e50abdb4f1a
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/bin/jq-linux-amd64

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/bin/jq-linux-amd64

## File: hermes/design/product-film/bin/jq-linux-arm64
size: 1709616
sha: e93932ca12e4fe9b9d53dc780061a50f06650429
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/bin/jq-linux-arm64

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/bin/jq-linux-arm64

## File: hermes/design/product-film/bin/jq-macos-amd64
size: 851328
sha: 4fbf7ae77e1646daa7f2143d0627e47697959f54
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/bin/jq-macos-amd64

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/bin/jq-macos-amd64

## File: hermes/design/product-film/bin/jq-macos-arm64
size: 807984
sha: 8842adb71bb450171d656a9906dca2c90c7b7ce3
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/bin/jq-macos-arm64

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/bin/jq-macos-arm64

## File: hermes/design/product-film/bin/jq-windows-amd64.exe
size: 985088
sha: 70b52888220a0d9e3d1cfbf4eab3372d41871e31
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/bin/jq-windows-amd64.exe

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/bin/jq-windows-amd64.exe

## File: hermes/design/product-film/bin/jq.LICENSE
size: 6026
sha: c162125a4f50c72ab96a63719519692844bc94df
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/bin/jq.LICENSE

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/bin/jq.LICENSE

## File: hermes/design/product-film/templates/cinematic/assemble.sh
size: 3535
sha: a8292788d501d3285f2fe4301193722186154983
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/cinematic/assemble.sh

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/cinematic/assemble.sh

## File: hermes/design/product-film/templates/cinematic/beats.html
size: 23846
sha: 931caf6d7ac434753e1df8f0681a73110dcd8bcc
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/cinematic/beats.html

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/cinematic/beats.html

## File: hermes/design/product-film/templates/cinematic/render.js
size: 2504
sha: 8b0e72a6a43ad0c330fdb9ca750d7a3bbadebc2b
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/cinematic/render.js

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/cinematic/render.js

## File: hermes/design/product-film/templates/common/capture/lib.mjs
size: 32473
sha: 394b9a850728cde4dea40d2476d03d4659bb77fa
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/common/capture/lib.mjs

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/common/capture/lib.mjs

## File: hermes/design/product-film/templates/common/pw.cjs
size: 1297
sha: 1dbb01ff236780c4f23753338861919f7e56f9e7
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/common/pw.cjs

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/common/pw.cjs

## File: hermes/design/product-film/templates/common/tools/chart-background.html
size: 10053
sha: 518bc82e2c238ec104885fedd43366dc85878346
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/common/tools/chart-background.html

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/common/tools/chart-background.html

## File: hermes/design/product-film/templates/common/tools/make-chart-bg.mjs
size: 3969
sha: b190477a9c31fb548beb6ba01d825404a40f6187
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/common/tools/make-chart-bg.mjs

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/common/tools/make-chart-bg.mjs

## File: hermes/design/product-film/templates/new-film.sh
size: 1972
sha: 84ef4dac06fd833c80e28c4a78563f1a0b89eb6c
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/new-film.sh

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/new-film.sh

## File: hermes/design/product-film/templates/paper/capture/agent/agent-window.html
size: 7346
sha: bb54d265ca73cc3a9b1d6ae59b0cea12acb2d129
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/agent/agent-window.html

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/agent/agent-window.html

## File: hermes/design/product-film/templates/paper/capture/agent/agent.json
size: 1670
sha: a5bfaded1d2e3327fe1dc3efcb1b7af0e721e005
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/agent/agent.json

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/agent/agent.json

## File: hermes/design/product-film/templates/paper/capture/agent/capture.mjs
size: 2566
sha: 6d8e7fa7c1f3ec058f7e6b8267605d22de2de83d
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/agent/capture.mjs

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/agent/capture.mjs

## File: hermes/design/product-film/templates/paper/capture/app/capture.mjs
size: 16920
sha: b678abed33642b0155a1eb716558e15096f0056e
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/app/capture.mjs

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/app/capture.mjs

## File: hermes/design/product-film/templates/paper/capture/app/example-app/app.css
size: 5091
sha: 874b0b5ee2be36e7a79feaa5271e32ea1ebdec70
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/app/example-app/app.css

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/app/example-app/app.css

## File: hermes/design/product-film/templates/paper/capture/app/example-app/app.js
size: 10756
sha: 1489bf40fee095b50a0e0dbc8dfc5f9ccfaab6c3
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/app/example-app/app.js

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/app/example-app/app.js

## File: hermes/design/product-film/templates/paper/capture/app/example-app/index.html
size: 677
sha: aa6d0a6bd6b80c5cac4e40f0d797b6b2f708a2f4
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/app/example-app/index.html

```text
<!doctype html>
<!-- EXAMPLE APP: Tidewell, a fictional shared-docs product, so the app harness runs out of the box. It stands in for
     your product's dev server. capture/app/capture.mjs serves this folder (any path falls back to this file) and
     answers every /api/ call from capture/app/fixtures.mjs. Replace it by pointing story.json app.baseUrl at your app. -->
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Tidewell</title>
<link rel="stylesheet" href="/app.css">
<style id="theme"></style>
</head>
<body>
<div id="app"></div>
<script type="module" src="/app.js"></script>
</body>
</html>
```

## File: hermes/design/product-film/templates/paper/capture/app/fixtures.mjs
size: 4418
sha: d9da6628b704212ef82564f7d40ab898a5a6589f
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/app/fixtures.mjs

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/app/fixtures.mjs

## File: hermes/design/product-film/templates/paper/capture/artifact/build.py
size: 1214
sha: ff4ee4b9d54d3c3474db7f160d009850d91bf344
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/artifact/build.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/artifact/build.py

## File: hermes/design/product-film/templates/paper/capture/artifact/check-layout.mjs
size: 2546
sha: a8a8b0f06b1b33b346ed3fa12f58b3322aa6cf0a
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/artifact/check-layout.mjs

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/artifact/check-layout.mjs

## File: hermes/design/product-film/templates/paper/capture/artifact/template.html
size: 4293
sha: 7c472dfbb9183ea70d0307145fc26beca2236ed3
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/artifact/template.html

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/artifact/template.html

## File: hermes/design/product-film/templates/paper/capture/cli/capture.mjs
size: 2571
sha: 4b226915023ab18e36ea4559247aa2aa011be30f
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/cli/capture.mjs

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/cli/capture.mjs

## File: hermes/design/product-film/templates/paper/capture/cli/fixture-api.mjs
size: 2956
sha: 89f4ff46df927a3f4a3438c479649acd4067d090
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/cli/fixture-api.mjs

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/cli/fixture-api.mjs

## File: hermes/design/product-film/templates/paper/capture/cli/render-term.mjs
size: 5122
sha: e98a8505a18bd1ffde1d4f90188d32e39cd32c10
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/cli/render-term.mjs

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/cli/render-term.mjs

## File: hermes/design/product-film/templates/paper/capture/cli/tidewell.mjs
size: 1707
sha: 9f3dd95bc2771841a04354e098b4ac3d60770baa
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/cli/tidewell.mjs

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/cli/tidewell.mjs

## File: hermes/design/product-film/templates/paper/capture/shoot-page.mjs
size: 1959
sha: cac42d51006d29bce7f937f47793f23914b9f96f
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/shoot-page.mjs

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/shoot-page.mjs

## File: hermes/design/product-film/templates/paper/capture/shoot.json
size: 465
sha: 6c67f32f07175992b9122b405fd9a6032c07eb3d
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/shoot.json

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/shoot.json

## File: hermes/design/product-film/templates/paper/capture/story.json
size: 3831
sha: 24baab05005d0d5d9acfde23da0db86c7ded8420
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/story.json

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/capture/story.json

## File: hermes/design/product-film/templates/paper/film/assemble.sh
size: 1975
sha: d6adfa1f30d94a4d5d1f7e50c7004b4378cadef9
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/film/assemble.sh

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/film/assemble.sh

## File: hermes/design/product-film/templates/paper/film/engine.js
size: 26793
sha: 685f146e47ec2ebee49a85b4fe98f7857c72f61f
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/film/engine.js

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/film/engine.js

## File: hermes/design/product-film/templates/paper/film/film.html
size: 257
sha: a7314306214fa976fb1a9e42a32eef1f7167067a
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/film/film.html

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/film/film.html

## File: hermes/design/product-film/templates/paper/film/film.js
size: 11826
sha: ebe15959a42560a1bd70d065a488704a7e8f0ec6
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/film/film.js

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/film/film.js

## File: hermes/design/product-film/templates/paper/film/jobs.sh
size: 793
sha: 3dbcdcb0a861e246934d4390c5435cde3984398f
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/film/jobs.sh

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/film/jobs.sh

## File: hermes/design/product-film/templates/paper/film/preview.mjs
size: 2291
sha: 530c633c5a05968a82bdbb12efbbf7dde9c55a36
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/film/preview.mjs

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/film/preview.mjs

## File: hermes/design/product-film/templates/paper/film/render-all.sh
size: 877
sha: a07a663231c592bb5d87ceb1d0e7903b49f0bf81
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/film/render-all.sh

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/film/render-all.sh

## File: hermes/design/product-film/templates/paper/film/render.mjs
size: 2257
sha: cf85ae39c1fe5d2f15bab13a3a7304f328658e0b
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/film/render.mjs

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/film/render.mjs

## File: hermes/design/product-film/templates/paper/film/timeline.json
size: 5829
sha: bb619daca56db40bba42822246ab39cdd50888a6
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/film/timeline.json

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/film/timeline.json

## File: hermes/design/product-film/templates/paper/kit/build-kit.mjs
size: 1371
sha: d5995e7e38edf354164d44e9abb8de15bfecdbc3
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/kit/build-kit.mjs

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/kit/build-kit.mjs

## File: hermes/design/product-film/templates/paper/kit/build-sheet.mjs
size: 1023
sha: 15f33ccab57f01f8aa543b207b99f4cc9e92a66a
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/kit/build-sheet.mjs

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/kit/build-sheet.mjs

## File: hermes/design/product-film/templates/paper/kit/export.html
size: 2920
sha: ac1e387251e002231b145d9d963dcf6695e39943
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/kit/export.html

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/kit/export.html

## File: hermes/design/product-film/templates/paper/kit/kit.html
size: 4572
sha: 9a9b6aa363c0bd6bf8b0a27d45e5afdef3f74524
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/kit/kit.html

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/kit/kit.html

## File: hermes/design/product-film/templates/paper/kit/kit.js
size: 25792
sha: 54e428f2562a23b81a27cf899eddbec371ce8031
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/kit/kit.js

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/kit/kit.js

## File: hermes/design/product-film/templates/paper/kit/puppet.js
size: 13087
sha: 29d04aa75de013b5f411e8d40aa3738613744f34
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/kit/puppet.js

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/kit/puppet.js

## File: hermes/design/product-film/templates/paper/kit/rig.js
size: 5243
sha: 77a743dbd6eb0ca891b9580c5b8e0552a1ca7827
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/kit/rig.js

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/kit/rig.js

## File: hermes/design/product-film/templates/paper/setup.sh
size: 3748
sha: 115982ebafa00b58b4de8d8611d83bef246bbe5c
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/setup.sh

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/setup.sh

## File: hermes/design/product-film/templates/paper/sfx/measure.py
size: 1674
sha: 0dfd289441539d625fe7ba2e347df475d31985f8
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/sfx/measure.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/sfx/measure.py

## File: hermes/design/product-film/templates/paper/sfx/mix.py
size: 2956
sha: 8a561d562395aa2cbb7842dbac57a95747bf1b94
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/sfx/mix.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/sfx/mix.py

## File: hermes/design/product-film/templates/paper/sfx/synth.py
size: 7860
sha: 80dc50fdd795baae70a50e4e93b8027cf7109481
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/sfx/synth.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/sfx/synth.py

## File: hermes/design/product-film/templates/paper/tools/build-review.py
size: 12866
sha: 47ad04cb73c43487990dd55fa46b5627e1bc43ba
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/tools/build-review.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/tools/build-review.py

## File: hermes/design/product-film/templates/paper/tools/check-copy.py
size: 6145
sha: 46c49bacda62aa72caa624c4b70c9e09f45a7c0f
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/tools/check-copy.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/tools/check-copy.py

## File: hermes/design/product-film/templates/paper/tools/check-master.sh
size: 2146
sha: b5fab2df4e5fcafb6a1702cb49f920c02d7cbdb1
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/tools/check-master.sh

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/tools/check-master.sh

## File: hermes/design/product-film/templates/paper/tools/deliver.sh
size: 2870
sha: c3f589a59a5ac10362018ab0646549d4e69d1735
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/tools/deliver.sh

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/tools/deliver.sh

## File: hermes/design/product-film/templates/paper/tools/fetch-fonts.mjs
size: 2177
sha: fd499e67b1c147c1406f1b2d67c28d5d31eacd9a
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/tools/fetch-fonts.mjs

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/tools/fetch-fonts.mjs

## File: hermes/design/product-film/templates/paper/tools/gates.py
size: 3926
sha: ff6dbba6bd85cdec58d6d43a5aae7c924852c696
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/tools/gates.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/tools/gates.py

## File: hermes/design/product-film/templates/paper/tools/make-bg.py
size: 1992
sha: b0ceba3af0d684a3991477950f257e4e21374e3f
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/tools/make-bg.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/tools/make-bg.py

## File: hermes/design/product-film/templates/paper/tools/pw.mjs
size: 234
sha: 3f8512f071a7d597b3a86eb4279287ee67b19f3a
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/tools/pw.mjs

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/tools/pw.mjs

## File: hermes/design/product-film/templates/paper/tools/readme.py
size: 2573
sha: ea0079c55008686e8b2442c9f5ed82ef8f4b812a
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/tools/readme.py

````text
<p><img src="assets/cover.png" alt="product-film — short product films from your product's real UI, made by your AI assistant" width="1280"></p>

# product-film

**Short product films from your product's real UI — without screen recordings, stock motion templates or AI-video slop.**

Ask an agent for a launch film today and you get one of three things: a screen recording with a zoom on every click, a motion-graphics template that could be any product, or a generated video in which the UI melts. product-film gives the agent a fourth way. It rebuilds your product's screens from your own components, animates them on a deterministic HTML timeline, renders every frame with Playwright and cuts the film with ffmpeg. The UI stays sharp at 3× zoom, every frame can be re-rendered exactly, and a note like "hold the comment longer" changes one number, not the whole film.

## Install

```sh
npx skills add display-dev/product-film --skill product-film
```

Works across Claude Code, Cursor, Codex, OpenCode, Hermes, and Pi. Documentation: [display.dsp.so/Zgh7hwEe-product-film](https://display.dsp.so/Zgh7hwEe-product-film). Rendering needs Node 18+, ffmpeg and (for the paper route) Python 3 on the machine the agent runs on — see [HARNESSES.md](HARNESSES.md).

## Why product-film?

**1. The product is the star, at full fidelity.** Beats are built from your shipped markup and CSS, or from DOM snapshots captured from your running app on fictional data. Text is typed into the real composer, menus open with their real hover states, and nothing goes soft when the camera pushes in.

**2. Taste that held up in review, written down.** The numbers come from films that went through many review rounds: how long a pointer may rest, how fast captions can change, how far to zoom and when to come back, which effects read as polish and which read as bugs. Each rule names the failure it prevents.

**3. Checks that watch the film before people do.** `audit.js` finds stuck pointers, one-frame flickers and frames that depend on the frame before. The paper route gates every cut on exact frame counts, caption length and hold time, safe zones, loudness and encode quality, and builds transition strips so double-drawn characters show up in review, not in the comments.

**4. Recuts are cheap.** One timeline, one camera per beat, one plan per cut. Re-render one beat or one frame range, keep every earlier cut, and publish each new one as a version of the same review page.

## What's inside

### Four routes, and the styles they come in

| Route | Register | What it is | Good for |
|---|---|---|---|
| A, with footage | Cinematic | Licensed live-action cuts alternate with product beats on a 3D plate with a camera that never stops | Website hero loops |
| B, pure product | Cinematic | Product beats only, joined by the plate, with captions or end cards | Landing sections, launch teasers |
| B, reel | Beat-cut | Claim-and-proof sections cut to the music's bar lines on flat brand plates, one capability per section | Launch reels that show breadth |
| C, walkthrough | Kinetic | A pointer drives the product through one causal story; isolated UI at extreme close-up, morphs instead of cuts, kinetic captions (a plain cut with a caption band or text cards on request) | Store-listing promos, feature launches |
| D, paper collage | Illustrated | A cut-paper cast tells a story with a problem, a turn and a payoff over real product screenshots, in stop-motion, in 16:9, 9:16 and 4:5 at once | Social cuts, explainers |

### Templates

Every route starts from a working template with a fictional example product (Tidewell, a shared-docs app), so the first render works before you change anything. The agent starts each film with:

```sh
bash <skill>/templates/new-film.sh walkthrough ~/films/launch
```

| Template | Contents |
|---|---|
| `cinematic/` | 3D beat engine with camera rig, depth of field and seeded particles; renderer; assembly into master, web, review and poster files |
| `walkthrough/` | 2D engine with time-warp holds, clip plans, pointer and caret; the kinetic example (morphs, wet-ink type, a slot reel, a square cut) and the reel example (sections on a tempo grid, plate wipes, a beat-map tool for your track) on the same pipeline; parallel rendering; frame preview; motion audit |
| `paper/` | Canvas engine driven by one timeline, a frozen paper kit and jointed cast, capture harnesses for your app, CLI and an agent window, synthesized pen-and-paper sound, review sheets, quality gates and a delivery set |
| `common/` | Playwright loader, DOM capture and snapshot library, an engraved-chart background generator in your brand color |

### References

Per-route numbers, engines, gotchas and lessons: [camera rig](product-film/references/camera-rig.md), [walkthrough](product-film/references/walkthrough.md), [kinetic style](product-film/references/kinetic-style.md), [reel style](product-film/references/reel-style.md), [live DOM](product-film/references/live-dom.md), [paper collage](product-film/references/paper-collage.md), [paper capture](product-film/references/paper-capture.md) and [paper lessons](product-film/references/paper-lessons.md).

## Using it

Describe the film: "make a 30-second launch film for the new share dialog", "recut the hero film with a shorter ending", "a paper-collage explainer of how comments reach the client". On Claude Code, `/product-film <what the film is about>` works too.

Review happens on display.dev: the agent publishes one review page per film, each new cut becomes a new version of the same page, and it reads and answers your comments there. Without an account, the first publish is a 30-day preview you can claim.

The skill reads what your project already has — `FILM.md` (your team's film notes), `DESIGN.md` or design tokens, `PRODUCT.md` or a voice guide, docs and changelog for the truth sheet — and asks only for what it cannot find. It presents candidates and frames; the taste calls stay with you.

## License

MIT — see [LICENSE](./LICENSE). Bundles [jq 1.7.1](https://github.com/jqlang/jq) (MIT, © 2012 Stephen Dolan) for the publish helper; full text in [`product-film/bin/jq.LICENSE`](product-film/bin/jq.LICENSE).
````

## File: hermes/design/product-film/templates/paper/tools/remux-audio.sh
size: 1163
sha: 76803a8ebf6f256ec0dd3bb47a3fec880aa521b5
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/tools/remux-audio.sh

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/tools/remux-audio.sh

## File: hermes/design/product-film/templates/paper/tools/review.py
size: 6619
sha: 13825f8d98b7e216cbb1f5a72b95ae5530362b5b
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/tools/review.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/tools/review.py

## File: hermes/design/product-film/templates/paper/tools/srt.py
size: 667
sha: 640e77d6e4634d17b1b907bf2b57ec2d89854bd3
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/tools/srt.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/tools/srt.py

## File: hermes/design/product-film/templates/paper/tools/static.mjs
size: 1487
sha: 62379c5fc1a13c8ab35b7ca7b0392f7f425f9fff
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/tools/static.mjs

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/tools/static.mjs

## File: hermes/design/product-film/templates/paper/tools/stills.sh
size: 667
sha: b3cbf24a158a9a434ec59799c7f04c454385715a
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/tools/stills.sh

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/paper/tools/stills.sh

## File: hermes/design/product-film/templates/walkthrough/assemble.sh
size: 2617
sha: 0e9fa311eb2626555bf739dd4032b5820246b43a
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/walkthrough/assemble.sh

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/walkthrough/assemble.sh

## File: hermes/design/product-film/templates/walkthrough/audit.js
size: 9270
sha: baf367db08a02892b259df32c02162897b14d61b
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/walkthrough/audit.js

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/walkthrough/audit.js

## File: hermes/design/product-film/templates/walkthrough/beatmap.py
size: 10034
sha: c74dfd5dbe6930e4e12990c14f7a15fe9c165304
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/walkthrough/beatmap.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/walkthrough/beatmap.py

## File: hermes/design/product-film/templates/walkthrough/beats.html
size: 20682
sha: 76cde96e035e6e25d35f5c5907ccda1ff25e0a06
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/walkthrough/beats.html

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/walkthrough/beats.html

## File: hermes/design/product-film/templates/walkthrough/kinetic.html
size: 31929
sha: a9d8511d4b500394455148ff34dd0bc8abb8c141
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/walkthrough/kinetic.html

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/walkthrough/kinetic.html

## File: hermes/design/product-film/templates/walkthrough/plan-A.json
size: 171
sha: 1d6157f05d433fbe21165c9c7584e608aefa5ca5
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/walkthrough/plan-A.json

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/walkthrough/plan-A.json

## File: hermes/design/product-film/templates/walkthrough/plan-B.json
size: 332
sha: 62c90af23e9776e99621fe981676a16c3919b9ad
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/walkthrough/plan-B.json

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/walkthrough/plan-B.json

## File: hermes/design/product-film/templates/walkthrough/plan-jobs.py
size: 1625
sha: 11cb136e6892a774061c52108aac81d3b7f267a1
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/walkthrough/plan-jobs.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/walkthrough/plan-jobs.py

## File: hermes/design/product-film/templates/walkthrough/plan-K.json
size: 102
sha: 30a7be024c5d1933d1e0c98a103477dca15d5de0
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/walkthrough/plan-K.json

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/walkthrough/plan-K.json

## File: hermes/design/product-film/templates/walkthrough/plan-Ksq.json
size: 139
sha: c66b76254511f0f3f053dbdc77d2d097134cf5d2
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/walkthrough/plan-Ksq.json

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/walkthrough/plan-Ksq.json

## File: hermes/design/product-film/templates/walkthrough/plan-R.json
size: 99
sha: 390c85aaeb38d693eb55138f92da5ecdf4433724
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/walkthrough/plan-R.json

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/walkthrough/plan-R.json

## File: hermes/design/product-film/templates/walkthrough/previewq.js
size: 2169
sha: 7bda0811d15673e3d97e4a571f94cf0d9b3d9df1
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/walkthrough/previewq.js

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/walkthrough/previewq.js

## File: hermes/design/product-film/templates/walkthrough/reel.html
size: 50818
sha: bd559942c4dfb357d0d5d8a59dad07254e1a29d6
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/walkthrough/reel.html

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/walkthrough/reel.html

## File: hermes/design/product-film/templates/walkthrough/render.js
size: 3913
sha: b1dacc74dd08e460e7f9d76a3f4c2051b988b8a8
upstream: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/walkthrough/render.js

Content is not inlined in the catalog. Read the upstream file: https://github.com/display-dev/product-film/blob/main/hermes/design/product-film/templates/walkthrough/render.js

## File: README.md
upstream: https://github.com/display-dev/product-film/blob/main/README.md

````text
<p><img src="assets/cover.png" alt="product-film — short product films from your product's real UI, made by your AI assistant" width="1280"></p>

# product-film

**Short product films from your product's real UI — without screen recordings, stock motion templates or AI-video slop.**

Ask an agent for a launch film today and you get one of three things: a screen recording with a zoom on every click, a motion-graphics template that could be any product, or a generated video in which the UI melts. product-film gives the agent a fourth way. It rebuilds your product's screens from your own components, animates them on a deterministic HTML timeline, renders every frame with Playwright and cuts the film with ffmpeg. The UI stays sharp at 3× zoom, every frame can be re-rendered exactly, and a note like "hold the comment longer" changes one number, not the whole film.

## Install

```sh
npx skills add display-dev/product-film --skill product-film
```

Works across Claude Code, Cursor, Codex, OpenCode, Hermes, and Pi. Documentation: [display.dsp.so/Zgh7hwEe-product-film](https://display.dsp.so/Zgh7hwEe-product-film). Rendering needs Node 18+, ffmpeg and (for the paper route) Python 3 on the machine the agent runs on — see [HARNESSES.md](HARNESSES.md).

## Why product-film?

**1. The product is the star, at full fidelity.** Beats are built from your shipped markup and CSS, or from DOM snapshots captured from your running app on fictional data. Text is typed into the real composer, menus open with their real hover states, and nothing goes soft when the camera pushes in.

**2. Taste that held up in review, written down.** The numbers come from films that went through many review rounds: how long a pointer may rest, how fast captions can change, how far to zoom and when to come back, which effects read as polish and which read as bugs. Each rule names the failure it prevents.

**3. Checks that watch the film before people do.** `audit.js` finds stuck pointers, one-frame flickers and frames that depend on the frame before. The paper route gates every cut on exact frame counts, caption length and hold time, safe zones, loudness and encode quality, and builds transition strips so double-drawn characters show up in review, not in the comments.

**4. Recuts are cheap.** One timeline, one camera per beat, one plan per cut. Re-render one beat or one frame range, keep every earlier cut, and publish each new one as a version of the same review page.

## What's inside

### Four routes, and the styles they come in

| Route | Register | What it is | Good for |
|---|---|---|---|
| A, with footage | Cinematic | Licensed live-action cuts alternate with product beats on a 3D plate with a camera that never stops | Website hero loops |
| B, pure product | Cinematic | Product beats only, joined by the plate, with captions or end cards | Landing sections, launch teasers |
| B, reel | Beat-cut | Claim-and-proof sections cut to the music's bar lines on flat brand plates, one capability per section | Launch reels that show breadth |
| C, walkthrough | Kinetic | A pointer drives the product through one causal story; isolated UI at extreme close-up, morphs instead of cuts, kinetic captions (a plain cut with a caption band or text cards on request) | Store-listing promos, feature launches |
| D, paper collage | Illustrated | A cut-paper cast tells a story with a problem, a turn and a payoff over real product screenshots, in stop-motion, in 16:9, 9:16 and 4:5 at once | Social cuts, explainers |

### Templates

Every route starts from a working template with a fictional example product (Tidewell, a shared-docs app), so the first render works before you change anything. The agent starts each film with:

```sh
bash <skill>/templates/new-film.sh walkthrough ~/films/launch
```

| Template | Contents |
|---|---|
| `cinematic/` | 3D beat engine with camera rig, depth of field and seeded particles; renderer; assembly into master, web, review and poster files |
| `walkthrough/` | 2D engine with time-warp holds, clip plans, pointer and caret; the kinetic example (morphs, wet-ink type, a slot reel, a square cut) and the reel example (sections on a tempo grid, plate wipes, a beat-map tool for your track) on the same pipeline; parallel rendering; frame preview; motion audit |
| `paper/` | Canvas engine driven by one timeline, a frozen paper kit and jointed cast, capture harnesses for your app, CLI and an agent window, synthesized pen-and-paper sound, review sheets, quality gates and a delivery set |
| `common/` | Playwright loader, DOM capture and snapshot library, an engraved-chart background generator in your brand color |

### References

Per-route numbers, engines, gotchas and lessons: [camera rig](product-film/references/camera-rig.md), [walkthrough](product-film/references/walkthrough.md), [kinetic style](product-film/references/kinetic-style.md), [reel style](product-film/references/reel-style.md), [live DOM](product-film/references/live-dom.md), [paper collage](product-film/references/paper-collage.md), [paper capture](product-film/references/paper-capture.md) and [paper lessons](product-film/references/paper-lessons.md).

## Using it

Describe the film: "make a 30-second launch film for the new share dialog", "recut the hero film with a shorter ending", "a paper-collage explainer of how comments reach the client". On Claude Code, `/product-film <what the film is about>` works too.

Review happens on display.dev: the agent publishes one review page per film, each new cut becomes a new version of the same page, and it reads and answers your comments there. Without an account, the first publish is a 30-day preview you can claim.

The skill reads what your project already has — `FILM.md` (your team's film notes), `DESIGN.md` or design tokens, `PRODUCT.md` or a voice guide, docs and changelog for the truth sheet — and asks only for what it cannot find. It presents candidates and frames; the taste calls stay with you.

## License

MIT — see [LICENSE](./LICENSE). Bundles [jq 1.7.1](https://github.com/jqlang/jq) (MIT, © 2012 Stephen Dolan) for the publish helper; full text in [`product-film/bin/jq.LICENSE`](product-film/bin/jq.LICENSE).
````
