@ericrisco/rsc 3.1.2 → 3.1.4

package/skills/scroll-film/references/chain.md

@@ -0,0 +1,218 @@
+# Building the chain — prompts, probe, batch loops
+
+Everything the body of `scroll-film` points at for sections 1 to 4. Fill the slots; keep the
+clauses marked **verbatim** exactly as written, because they are what the seams depend on.
+
+## The brief to write down before anything renders
+
+```yaml
+subject: "a bubble-tea brand, from the tea field to the last sip"   # the user's words
+brand: { name: "Pearl & Leaf", tone: "warm, playful" }
+palette: { bg: "#F3EDE4", accent: "#6D55B8", others: ["#8FB98A", "#C88A5A", "#3A2E48"] }
+look: clay-diorama            # becomes the style preamble below
+camera: dive-and-hop          # walkthrough | fixed-angle | dive-and-hop  → shape A, A, B
+phones: true                  # true = a second, 9:16 chain
+scenes:                       # 4–7, in camera order; the last carries the CTA
+  - { id: field,   subject: "terraced tea field, pickers with baskets, a small drying shed", focus: "the drying racks" }
+  - { id: kitchen, subject: "a kitchen with copper pots of simmering tapioca pearls",      focus: "the pearl pots" }
+  - { id: shop,    subject: "the corner shop with a striped awning and a queue",          focus: "the counter" }
+model: { endpoint: "<from the probe>", seconds_leg: 8, seconds_hop: 5, price_per_second: "<read today>" }
+estimate_usd: "<clips × seconds × price + 20%>"
+approved: false               # nothing renders until this is true
+```
+
+## Style preamble — one block, pasted unchanged into every still prompt
+
+Write it once from the look the user picked. The background colour is the page background.
+
+```text
+Isometric miniature diorama on a plain solid #F3EDE4 background, a soft shadow beneath it.
+Matte clay materials, rounded toy-like shapes, warm low studio light, tilt-shift depth of field.
+Palette limited to #6D55B8, #8FB98A, #C88A5A, #3A2E48. Subject centred. No text, letters,
+numbers or logos anywhere.
+```
+
+Other looks change the first two sentences only and keep the palette and no-text lines:
+
+- **Paper cut:** "Layered paper-craft diorama, matte card, clean die-cut edges, thin shadows between layers."
+- **Vinyl toy:** "Glossy vinyl-toy diorama, smooth plastic shading, soft rim light."
+- **Night miniature:** "Miniature town at night, warm lit windows, neon signs, wet reflective streets."
+- **Photoreal:** "Architectural photograph of one continuous space, wide lens, late-afternoon light, natural
+  materials, no people." Photoreal scenes are full-bleed (no floating island), the camera moves
+  through doorways and glass instead of opening a roof, and it suits shape A. Do not pass one
+  approved still as a style reference here: it clones the same room into every scene.
+
+## Still prompt
+
+```text
+<STYLE PREAMBLE>
+Subject: <scene.subject>. Framed for a 16:9 picture with the focal point, <scene.focus>, in the centre.
+```
+
+- Render every still from **one** source and model. Two image models drift in warmth and line,
+  and the chain inherits the drift.
+- Prepare each still at the clip's aspect before it becomes a start image: 16:9 for desktop, and a
+  1080×1920 canvas in the background colour for the phone chain. Handed an off-aspect image, many
+  endpoints choose their own framing and frame 0 stops matching.
+- Review the set before any video: same angle, same light, same palette. Re-roll the odd one out.
+
+## Leg prompt — shape A
+
+Start frame: the previous leg's real last frame (leg 0: the first still). **No end frame.**
+
+```text
+One continuous camera move, no cuts. Continue the same slow, steady forward drift.
+<MID-LEG MOVE, optional>. The camera travels into <scene.subject> toward <scene.focus>.
+In the final second, settle into a slow, steady forward drift toward <where the next scene lies>.
+<last two sentences of the style preamble>. Smooth, unhurried motion. No text.
+```
+
+The first and the last sentence of that block are **verbatim**: they are the handoff contract
+that keeps velocity continuous across the seam.
+
+### Mid-leg moves by concept
+
+A reversal inside one leg is safe, since one render has no seam. Pick from the scene's own logic:
+
+| Concept | Mid-leg move |
+| --- | --- |
+| Product, luxury | "circling the <hero object> in a slow half orbit, keeping it centred, then moving past it" |
+| Real estate, hotels | "gliding through the doorway at eye height, rising gently as the room opens up" |
+| Production, logistics | "tracking low and level alongside the <line>, foreground objects sliding past" |
+| Travel, campus, outdoors | "climbing over the <terrain>, then swooping down toward the <next focus>" |
+| Food, craft | "pushing in until the <craft moment> nearly fills the frame, then easing back" |
+| The scene itself is the show | omit the slot: a plain forward drift is the safest leg |
+
+Expressive moves raise the re-roll rate: the model can end mid-orbit instead of in a clean forward
+drift. Budget one extra render for each expressive leg, and check its last frame before chaining.
+
+### Fixed-angle clause
+
+When the user picked "one fixed angle", put this in the mid-leg slot of **every** leg, **verbatim**:
+
+```text
+The camera holds the same high isometric angle the whole time, with no rotation, orbit or tilt.
+It only travels straight and level while the world slides past beneath it.
+```
+
+Long legs drift the angle slightly. When checking each last frame, also check the view has not
+turned; re-roll a leg that has.
+
+## Dive and hop prompts — shape B
+
+Dive. Start frame: the scene's still (the solid-background version, so the frame is full).
+
+```text
+One continuous camera move, no cuts. Start high and far, looking down at the whole <scene.subject>
+like a small model. The camera glides forward and descends toward <scene.focus>; as it closes in,
+the roof lifts gently away to reveal the interior. <style tail>. Smooth, unhurried motion. No text.
+```
+
+For an open scene with no roof (a field, a square), swap the last clause for "the camera skims low
+across <the scene> toward <scene.focus>".
+
+Hop. Start frame: dive k's real last frame. End frame: dive k+1's real first frame.
+
+```text
+One continuous camera move, no cuts. The camera rises up and out of <scene k>, climbs into the sky,
+crosses the connected miniature world and arrives above <scene k+1>, starting to descend toward it.
+<style tail>. Smooth, unhurried motion. No text.
+```
+
+For the hop into a hero-product finale, end it on "…and the world falls away toward a single giant
+<product> floating in open <bg colour> space."
+
+## Phone chain clause
+
+Prepend to every leg, dive and hop of the 9:16 chain:
+
+```text
+Vertical composition: the scene centred with open <bg colour> space above and below it.
+```
+
+The phone chain hands off frames from its own renders only.
+
+## The probe — one cheap clip before the batch
+
+```bash
+ssim() { ffmpeg -i "$1" -i "$2" -lavfi "[0]scale=960:540,setsar=1[a];[1]scale=960:540,setsar=1[b];[a][b]ssim" \
+  -f null - 2>&1 | grep -oE 'All:[0-9.]+'; }
+ffmpeg -v error -y -i probe.mp4 -frames:v 2 -vsync 0 probe_%d.png
+ssim probe_1.png still_01.png   # frame 0 against the still it was given
+ssim probe_1.png probe_2.png    # the clip's own frame-to-frame step, the yardstick
+# Hop duty: the last frame against the end frame it was given.
+ffmpeg -v error -y -sseof -1 -i probe_hop.mp4 -update 1 probe_last.png
+ssim probe_last.png still_02.png
+```
+
+- Frame 0 against the still should score about as high as the clip's own frame step. Judge it
+  against that yardstick, never a fixed number: how alike two frames look depends on the picture.
+  On a soft landscape photo, a fresh render of the same scene still scored 0.89. Clearly below the
+  step means the input steered a new render instead of starting the clip: the endpoint cannot
+  hold a seam.
+- The hop's last frame only has to land on the same composition. Look at it; a near miss is normal.
+- Compare the bill for the probe with the advertised price before multiplying it by the chain.
+- Re-run the probe whenever the endpoint's input schema changes. Catalogues gain and lose
+  start-frame support without notice.
+
+## Batch loops
+
+`make_clip` is the one function you write against the chosen endpoint (the call itself →
+`../../fal/SKILL.md` or `../../replicate/SKILL.md`). Its contract: `make_clip out.mp4 prompt.txt
+start.png [end.png]` renders one clip, downloads it at once (result URLs expire within hours) and
+appends the billed cost to `costs.log`. Run the loops as a background job and poll; a clip takes
+minutes. Keep them in a `bash` script: zsh arrays start at 1, and an inline loop in a zsh shell
+pairs each hop with the wrong scene.
+
+Shape A, one leg at a time:
+
+```bash
+#!/bin/bash
+set -e
+SCENES="field kitchen shop"
+start="stills/field.png"
+for s in $SCENES; do
+  make_clip "legs/$s.mp4" "prompts/leg_$s.txt" "$start"
+  ffmpeg -v error -y -sseof -1 -i "legs/$s.mp4" -update 1 -q:v 2 "frames/${s}_last.png"
+  start="frames/${s}_last.png"      # look at it before the next leg spends money
+done
+```
+
+Shape B, dives in parallel, then hops:
+
+```bash
+#!/bin/bash
+set -e
+SCENES="field kitchen shop"
+for s in $SCENES; do make_clip "dives/$s.mp4" "prompts/dive_$s.txt" "stills/$s.png" & done
+wait
+for s in $SCENES; do
+  ffmpeg -v error -y -i "dives/$s.mp4" -frames:v 1 -q:v 2 "frames/${s}_first.png"
+  ffmpeg -v error -y -sseof -1 -i "dives/$s.mp4" -update 1 -q:v 2 "frames/${s}_last.png"
+done
+prev=""; k=0
+for s in $SCENES; do
+  if [ -n "$prev" ]; then
+    k=$((k + 1))
+    make_clip "hops/hop_$k.mp4" "prompts/hop_$k.txt" "frames/${prev}_last.png" "frames/${s}_first.png" &
+  fi
+  prev="$s"
+done
+wait
+```
+
+Five or six renders at once is usually fine. Many more invites transient rate and credit errors:
+re-roll the one that failed, never the batch.
+
+## When a content filter blocks a harmless clip
+
+Video filters flag ordinary interiors, mostly bedrooms, pools, spas and bars, from the prompt words
+and from the frames themselves. In order:
+
+1. Re-roll. The verdict is often not deterministic.
+2. Take out the trigger words and add "empty, unoccupied, architectural".
+3. Render that one clip on another model that also passed the probe, with the same start and end
+   frames. Its render character differs slightly, which a short hop behind the seam dissolve
+   usually hides.
+4. Drop that hop. List the two dives next to each other in the engine config and it dissolves
+   between them directly. The film completes; that seam reads as a dissolve, not a flight.

package/skills/scroll-film/references/engine.md

@@ -0,0 +1,132 @@
+# The scrub engine — options, wiring, pacing
+
+`assets/scrub-engine.js` is plain JavaScript with no dependencies. Loaded as a script it defines
+`window.ScrollFilm`; under a bundler it also exports the same object. `assets/page-template.html` is
+a complete page that uses it.
+
+## Mounting
+
+```js
+const film = ScrollFilm.mount(container, options);
+```
+
+`container` is the element the film lives in, usually a `<section>`. The engine adds a sticky stage
+(the clips and an overlay slot for your copy) and a spacer that gives the section its scroll length.
+Content after the section scrolls normally once the film ends.
+
+### `options`
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `shots` | required | The clips in chain order (fields below). |
+| `fade` | `0.1` | Width of the seam dissolve, in viewport heights. |
+| `preload` | `1.5` | A clip is fetched when the scroll comes this many viewports from it. |
+| `ease` | `0.2` | How fast the playhead catches up with the scroll each frame (1 = instantly). |
+| `phoneWidth` | `860` | At or below this width, or on any touch-only device, the phone sources are used. |
+| `stillsOnly` | `false` | Posters only, no video. Also forced by reduced motion and by Save-Data. |
+| `listen` | `true` | `false` = the engine adds no scroll listener; call `film.update()` from your own scroll source. |
+| `onChange` | none | Called with the state object whenever the position changes. |
+
+### Fields of each shot
+
+| Field | What it is |
+| --- | --- |
+| `src` | The desktop clip (`-g 8` encode). |
+| `srcMobile` | The phone clip (`-m.mp4`, 9:16, `-g 4`). Optional; falls back to `src`. |
+| `poster` / `posterMobile` | The clip's first frame. Shown until the video paints, and as the fallback. |
+| `length` | Scroll distance in viewport heights. More length, longer dwell. Default 1. |
+| `hold` | 0 to 1. Slows the camera mid-shot and speeds it near the seams; the seam frames never move. Above 0.6 the stop starts to read as a stall. |
+| `section` | Which copy block this clip belongs to. A dive and the hop that leaves it share a section. Defaults to the shot's index. |
+
+### What `mount` returns
+
+| Member | Use |
+| --- | --- |
+| `overlay` | Append your copy here; it rides the sticky stage above the clips. |
+| `stage` | The sticky element, for styling. |
+| `stillsOnly` | Whether this visitor gets posters only. |
+| `update()` | Re-read the scroll position. Needed only with `listen: false`. |
+| `relayout()` | Recompute positions after content above the film changes height (a late banner, a font swap). |
+| `jumpTo(section)` | Smooth-scroll to the middle of a section; instant under reduced motion. |
+| `destroy()` | Remove listeners, cancel fetches, release the Blob URLs, remove the added nodes. |
+
+### The state object passed to `onChange`
+
+```js
+{ shot: 2, section: 1, sectionProgress: 0.42, progress: 0.37 }
+```
+
+`sectionProgress` runs 0 to 1 across every clip of that section. Fade a section's copy in over its
+first 15% and out over its last 15%; let the first block start visible and the last one hold its
+call to action. The template does exactly this.
+
+## Pacing
+
+- The hero and the finale earn more `length` (1.4 to 1.6) and a `hold` of 0.3 to 0.5, so the camera
+  settles while the copy is readable.
+- Hops are transit: `length` 0.8 to 1.0, no `hold`.
+- Expressive camera work belongs in the clip, restraint in the scroll mapping. Both compound.
+
+## Theming and layout
+
+- `--film-bg` is the colour behind the stage; set it to the scene background so posters and
+  dissolves sit on it. `--film-focus` (default `50% 45%`) is where `object-fit: cover` keeps the
+  subject when the viewport crops a clip.
+- The engine's own CSS sits in `@layer scroll-film`, so any unlayered page rule wins without
+  specificity tricks.
+- The stage is `position: sticky`. Any ancestor with `overflow: hidden` breaks it; use
+  `overflow-x: clip` on `body` if the page needs to stop horizontal overflow.
+- The stage is `100lvh` tall: the film fills the screen when the URL bar is hidden, and the bottom
+  edge sits under the bar while it shows. Keep copy clear of the bottom with `svh` units and
+  `env(safe-area-inset-bottom)`, as the template does, and add `viewport-fit=cover` to the
+  viewport meta tag.
+
+## Wiring it into a framework
+
+React or Next.js, in a client component (the effect never runs on the server):
+
+```tsx
+'use client';
+import { useEffect, useRef } from 'react';
+
+export function Film({ shots }: { shots: object[] }) {
+  const ref = useRef<HTMLElement>(null);
+  useEffect(() => {
+    let film: { destroy(): void } | undefined;
+    let cancelled = false;
+    import('./scrub-engine.js').then((mod) => {
+      const ScrollFilm = (mod as any).default ?? (window as any).ScrollFilm;
+      if (!cancelled && ref.current) film = ScrollFilm.mount(ref.current, { shots });
+    });
+    return () => { cancelled = true; film?.destroy(); };
+  }, [shots]);
+  return <section ref={ref} aria-label="The journey" />;
+}
+```
+
+The `cancelled` flag matters: a component that unmounts before the import resolves would otherwise
+mount a film nobody can destroy. Keep `shots` stable (a module constant or `useMemo`) or every
+render rebuilds the film.
+
+Vue: mount in `onMounted`, keep the returned object, call `destroy()` in `onBeforeUnmount`. A
+server-rendered page in any other stack: serve the assets and add two `<script>` tags, as the
+template does.
+
+To drive it from a scroll source the page already owns:
+
+```js
+const film = ScrollFilm.mount(el, { shots, listen: false });
+ScrollTrigger.create({ trigger: el, start: 'top top', end: 'bottom bottom', onUpdate: () => film.update() });
+```
+
+## Accessibility and weight
+
+- The clip layer is `aria-hidden`. Everything a visitor needs is in the copy, which is ordinary
+  HTML in reading order, available to screen readers and search engines with or without the film.
+- The template adds a skip link past the film and, when keyboard focus enters a faded copy block,
+  scrolls to that block's section.
+- Preload the first poster with `fetchpriority="high"`; it is the LCP element. Clips load by
+  proximity, so first paint costs one image and one or two clips, not the whole chain.
+- Measure the chain before shipping (`du -ch assets/vid/*.mp4`). A 1080p clip of several seconds
+  at GOP 8 runs to megabytes, so a whole chain runs to tens of them. That is why the phone chain is
+  720 wide and why a clip is fetched only when the scroll gets near it.

package/skills/scroll-film/scripts/verify.sh

@@ -0,0 +1,158 @@
+#!/usr/bin/env bash
+# verify.sh — check a scroll-film clip chain before it ships. Read-only.
+#
+#   bash verify.sh [--strict] [--gop N] [--min-ssim X] [--portrait] [--frames DIR] clip1.mp4 clip2.mp4 ...
+#
+# Pass the clips in chain order (the order the engine plays them). Per clip it checks the
+# encode a scrubbed video needs: H.264 yuv420p, no audio track, the index (moov) ahead of the
+# media so the first frame paints early, and a keyframe at least every N frames (default 8; use
+# --gop 4 for phone encodes). Across the chain it checks every clip shares one size and frame
+# rate, and scores each seam: the true last frame of clip i against the first frame of clip i+1.
+#
+# A seam is judged against the clips around it, not against a fixed number: how alike two
+# frames look depends on the picture, so a soft landscape scores high even across a cut. The
+# seam's SSIM must stay within --margin (default 0.03) of the ordinary frame-to-frame SSIM at
+# the end of clip i and the start of clip i+1. A frame-locked seam looks like one more frame; a
+# fresh render of the same scene drops below. --frames DIR writes each pair side by side.
+#
+# Warns by default and exits 0. --strict exits 1 on any warning. Exits 2 on bad usage.
+# bash 3.2-safe: no associative arrays, no mapfile.
+
+set -u
+
+STRICT=0
+GOP=8
+MARGIN=0.03
+PORTRAIT=0
+FRAMES_DIR=""
+CLIPS=()
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --strict) STRICT=1 ;;
+    --gop) shift; GOP="${1:-}" ;;
+    --margin) shift; MARGIN="${1:-}" ;;
+    --portrait) PORTRAIT=1 ;;
+    --frames) shift; FRAMES_DIR="${1:-}" ;;
+    -h|--help) sed -n '2,19p' "$0"; exit 0 ;;
+    -*) echo "verify.sh: unknown option $1" >&2; exit 2 ;;
+    *) CLIPS+=("$1") ;;
+  esac
+  shift
+done
+
+for tool in ffmpeg ffprobe awk; do
+  command -v "$tool" >/dev/null 2>&1 || { echo "verify.sh: $tool not found on PATH" >&2; exit 2; }
+done
+if [ "${#CLIPS[@]}" -eq 0 ]; then
+  echo "verify.sh: pass the clips in chain order (see --help)" >&2
+  exit 2
+fi
+
+WARNINGS=0
+ok()   { echo "ok    $*"; }
+warn() { echo "WARN  $*"; WARNINGS=$((WARNINGS + 1)); }
+
+TMP=$(mktemp -d "${TMPDIR:-/tmp}/scroll-film-verify.XXXXXX")
+trap 'rm -rf "$TMP"' EXIT
+[ -n "$FRAMES_DIR" ] && mkdir -p "$FRAMES_DIR"
+
+# Every decoded frame of the last second, one file each: the final file is the real last frame.
+# (A plain -sseof seek with -frames:v 1 stops a few frames short and judges the wrong frame.)
+# The two last and the two first frames give the clips' own frame-to-frame step at the seam.
+edge_frames() { # clip index
+  mkdir -p "$TMP/tail_$2" "$TMP/head_$2"
+  ffmpeg -v error -y -sseof -1 -i "$1" -vsync 0 "$TMP/tail_$2/%04d.png"
+  ffmpeg -v error -y -i "$1" -frames:v 2 -vsync 0 "$TMP/head_$2/%04d.png"
+  ls "$TMP/tail_$2" | tail -2 > "$TMP/tail_$2.list"
+}
+ssim() { ffmpeg -v info -i "$1" -i "$2" -lavfi "[0][1]ssim" -f null - 2>&1 | grep -oE 'All:[0-9.]+' | tail -1 | cut -d: -f2; }
+
+FIRST_SHAPE=""
+i=0
+for clip in "${CLIPS[@]}"; do
+  i=$((i + 1))
+  name=$(basename "$clip")
+  if [ ! -f "$clip" ]; then warn "$name: file not found"; continue; fi
+
+  video=$(ffprobe -v error -select_streams v:0 -show_entries stream=codec_name,pix_fmt,width,height,r_frame_rate -of csv=p=0 "$clip")
+  if [ -z "$video" ]; then warn "$name: no video stream"; continue; fi
+  codec=$(echo "$video" | cut -d, -f1)
+  width=$(echo "$video" | cut -d, -f2)
+  height=$(echo "$video" | cut -d, -f3)
+  pixfmt=$(echo "$video" | cut -d, -f4)
+  rate=$(echo "$video" | cut -d, -f5)
+
+  [ "$codec" = "h264" ] && ok "$name: h264" || warn "$name: codec $codec (h264 decodes and seeks everywhere)"
+  [ "$pixfmt" = "yuv420p" ] && ok "$name: yuv420p" || warn "$name: pixel format $pixfmt (Safari wants yuv420p)"
+
+  audio=$(ffprobe -v error -select_streams a -show_entries stream=index -of csv=p=0 "$clip")
+  [ -z "$audio" ] && ok "$name: no audio track" || warn "$name: has an audio track (dead weight on a muted scrub; encode with -an)"
+
+  first_atom=$(ffprobe -v trace "$clip" 2>&1 | grep -oE "type:'(moov|mdat)'" | head -1)
+  [ "$first_atom" = "type:'moov'" ] && ok "$name: moov before mdat (faststart)" \
+    || warn "$name: index after the media (encode with -movflags +faststart)"
+
+  max_gap=$(ffprobe -v error -select_streams v:0 -show_entries packet=flags -of csv=p=0 "$clip" \
+    | awk '{ n++; if (substr($0,1,1) == "K") { if (last && n - last > gap) gap = n - last; last = n } }
+           END { if (n - last + 1 > gap) gap = n - last + 1; print gap + 0 }')
+  if [ "$max_gap" -le "$GOP" ]; then ok "$name: keyframe every <= $max_gap frames"
+  else warn "$name: $max_gap frames between keyframes (> $GOP); every scrub seek decodes that many"; fi
+
+  if [ "$PORTRAIT" -eq 1 ]; then
+    [ "$height" -gt "$width" ] && ok "$name: portrait ${width}x${height}" \
+      || warn "$name: ${width}x${height} is not portrait (the phone chain is rendered at 9:16, not cropped)"
+  fi
+
+  shape="${width}x${height}@${rate}"
+  if [ -z "$FIRST_SHAPE" ]; then FIRST_SHAPE="$shape"
+  elif [ "$shape" != "$FIRST_SHAPE" ]; then
+    warn "$name: $shape differs from the first clip's $FIRST_SHAPE (one model and one encode for the whole chain)"
+  fi
+
+  edge_frames "$clip" "$i"
+done
+
+n=${#CLIPS[@]}
+s=1
+while [ "$s" -lt "$n" ]; do
+  next=$((s + 1))
+  label="seam $s→$next ($(basename "${CLIPS[$((s - 1))]}") → $(basename "${CLIPS[$s]}"))"
+  a_prev=""; a=""; b="$TMP/head_$next/0001.png"; b_next="$TMP/head_$next/0002.png"
+  if [ -s "$TMP/tail_$s.list" ]; then
+    a="$TMP/tail_$s/$(tail -1 "$TMP/tail_$s.list")"
+    [ "$(wc -l < "$TMP/tail_$s.list")" -ge 2 ] && a_prev="$TMP/tail_$s/$(head -1 "$TMP/tail_$s.list")"
+  fi
+  if [ -z "$a" ] || [ ! -f "$a" ] || [ ! -f "$b" ]; then
+    warn "$label: could not extract both frames"
+  else
+    score=$(ssim "$a" "$b")
+    step_out=""; step_in=""
+    [ -n "$a_prev" ] && step_out=$(ssim "$a_prev" "$a")
+    [ -f "$b_next" ] && step_in=$(ssim "$b" "$b_next")
+    step=$(echo "$step_out $step_in" | awk '{ m = ""; for (k = 1; k <= NF; k++) if (m == "" || $k < m) m = $k; print m }')
+    if [ -z "$score" ]; then
+      warn "$label: frames could not be compared (different sizes?)"
+    elif [ -z "$step" ]; then
+      warn "$label: SSIM $score, but the clips are too short to measure their own frame step; judge it by eye"
+    elif awk -v s="$score" -v t="$step" -v m="$MARGIN" 'BEGIN { exit !(s >= t - m) }'; then
+      ok "$label: SSIM $score (frame to frame inside the clips: $step)"
+    else
+      warn "$label: SSIM $score against $step frame to frame inside the clips; look at it. A different picture means the handoff used the wrong frame"
+    fi
+    if [ -n "$FRAMES_DIR" ]; then
+      ffmpeg -v error -y -i "$a" -i "$b" -filter_complex hstack "$FRAMES_DIR/seam_$(printf '%02d' "$s").png" \
+        && echo "      side by side: $FRAMES_DIR/seam_$(printf '%02d' "$s").png"
+    fi
+  fi
+  s=$next
+done
+
+echo
+if [ "$WARNINGS" -eq 0 ]; then
+  echo "RESULT: PASS ($n clip(s), $((n - 1)) seam(s))"
+  exit 0
+fi
+echo "RESULT: $WARNINGS warning(s)"
+[ "$STRICT" -eq 1 ] && exit 1
+exit 0