@ericrisco/rsc 3.1.2 → 3.1.4

package/README.md

@@ -8,7 +8,7 @@
 
 [![npm](https://img.shields.io/npm/v/@ericrisco/rsc?color=63d68a&labelColor=12161c&label=npm)](https://www.npmjs.com/package/@ericrisco/rsc)
 [![downloads](https://img.shields.io/npm/dm/@ericrisco/rsc?color=63d68a&labelColor=12161c&label=downloads)](https://www.npmjs.com/package/@ericrisco/rsc)
-[![skills](https://img.shields.io/badge/skills-271-63d68a?labelColor=12161c)](#the-catalog)
+[![skills](https://img.shields.io/badge/skills-272-63d68a?labelColor=12161c)](#the-catalog)
 [![license](https://img.shields.io/badge/license-MIT-63d68a?labelColor=12161c)](LICENSE)
 [![stars](https://img.shields.io/github/stars/ericrisco/rsc-harness?color=63d68a&labelColor=12161c)](https://github.com/ericrisco/rsc-harness/stargazers)
 
@@ -60,7 +60,7 @@ The model is the brain your agent rents, and you already have it. rsc adds the r
 | --- | --- | --- |
 | **Memory** | `02-DOCS/` | A wiki the agent reads before it works and keeps up to date while it works. |
 | **Hands** | `01-TOOLS/` | One folder per tool, with a test that proves the connection works. |
-| **Trade** | skills | Only the skills your project needs: 271 available, a handful installed. |
+| **Trade** | skills | Only the skills your project needs: 272 available, a handful installed. |
 | **Reflexes** | hooks | Rules that hold even when the agent forgets them mid-session. |
 
 ### Why documentation comes first
@@ -468,7 +468,7 @@ snapshots the project first, so `rsc restore latest` undoes a bad update.
 
 ## The catalog
 
-271 skills, grouped by what you are trying to do. Click any skill to read its `SKILL.md`. It fires on
+272 skills, grouped by what you are trying to do. Click any skill to read its `SKILL.md`. It fires on
 its own when a task matches.
 
 ### 🧭 Core & control plane
@@ -561,7 +561,7 @@ whether, what and which platform.
 
 ### 🌀 Motion & interface craft
 
-[motion-craft](skills/motion-craft/) · [ui-engineering](skills/ui-engineering/) · [variant-explorer](skills/variant-explorer/)
+[motion-craft](skills/motion-craft/) · [ui-engineering](skills/ui-engineering/) · [variant-explorer](skills/variant-explorer/) · [scroll-film](skills/scroll-film/)
 
 ### 🎨 Design & content craft
 
@@ -628,6 +628,7 @@ Most of this catalog is written here. These are not, and they keep their author'
 | `design-eng` · `animate` · `animate-expo` · `review-animations` · `improve-animations` · `find-animation-opportunities` · `animation-vocabulary` · `apple-design` · `prototype` · `pick-ui-library` · `write-swift` · `ask-sonner` | [emilkowalski/skills](https://github.com/emilkowalski/skills) by Emil Kowalski, commit `d23d7f8` | MIT |
 | part of the AI-tell corpus in `design` | [Leonxlnx/taste-skill](https://github.com/Leonxlnx/taste-skill) | MIT |
 | the answer-first habits in `orient` | [ayghri/i-have-adhd](https://github.com/ayghri/i-have-adhd) | MIT |
+| the scroll-scrubbed camera flight, the frame handoff between clips and the phone fixes behind `scroll-film` (prose and engine rewritten) | [oso95/scroll-world](https://github.com/oso95/scroll-world) | MIT |
 
 Adapted, not mirrored: each carries rsc frontmatter, routing evals and hand-offs to its siblings. The
 craft bar in them is the original author's.

package/manifest.json

@@ -1,7 +1,7 @@
 {
-  "version": "3.1.2",
+  "version": "3.1.4",
   "counts": {
-    "skills": 271,
+    "skills": 272,
     "agents": 34,
     "commands": 53,
     "fixedCommands": 20
@@ -124,7 +124,8 @@
         "fal",
         "replicate",
         "remotion-video",
-        "video-shorts"
+        "video-shorts",
+        "scroll-film"
       ],
       "profiles": []
     },
@@ -4300,6 +4301,30 @@
       ],
       "profiles": []
     },
+    {
+      "id": "scroll-film",
+      "description": "Use when a page's hero is a pre-rendered camera flight the visitor scrubs by scrolling, Apple-style: AI clips chained frame to frame so seams never pop, encoded for seeking, mounted with an engine that holds up on phones. NOT scroll reveals or pinning (that is `design`), NOT a finished MP4 (that is `ai-media`).",
+      "tags": [
+        "scroll-scrub",
+        "scroll-video",
+        "scrollytelling",
+        "landing-hero",
+        "image-to-video",
+        "camera-flight",
+        "seamless-video"
+      ],
+      "recommends": [
+        "ai-media",
+        "fal",
+        "replicate-images",
+        "landing-copy",
+        "design",
+        "performance"
+      ],
+      "profiles": [
+        "full"
+      ]
+    },
     {
       "id": "sdd",
       "description": "Use when you want a disciplined, spec-driven path from a feature idea to shipped, verified software — the SDD dispatcher and front door, in any language. States the method, reads the user's register from 02-DOCS, and routes to the right phase: constitution -> specify -> clarify -> plan -> tasks -> analyze -> implement -> verify -> review -> ship, with debug / worktrees / parallel on demand. Use it to start a feature, to govern the whole flow, or when unsure which phase you are in. NOT a single phase itself (it dispatches), NOT the workspace harness (that is `harness`), NOT a stack build skill.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "3.1.2",
+  "version": "3.1.4",
   "description": "A guided harness builder that turns your goal into a minimal, verified AI-agent setup using strict best practices.",
   "type": "module",
   "bin": {

package/scripts/lib/domains.js

@@ -24,7 +24,7 @@ export const DOMAINS = [
   { title: 'Ship & operate — platforms', ids: ['vercel', 'netlify', 'cloudflare', 'railway', 'render', 'fly-io', 'coolify', 'hetzner', 'digitalocean', 'aws-essentials', 'gcp-essentials'] },
   { title: 'Ship & operate — devops', ids: ['docker', 'github-actions', 'git-workflow', 'domains-dns', 'monitoring', 'email-deliverability', 'scaling', 'deployment', 'deprecation'] },
   { title: 'Ship & operate — quality & security', ids: ['code-review', 'security-scan', 'secure-coding', 'testing-py', 'testing-web', 'testing-go', 'e2e-testing', 'accessibility', 'performance', 'error-handling', 'observability'] },
-  { title: 'Motion & interface craft', ids: ['motion-craft', 'ui-engineering', 'variant-explorer'] },
+  { title: 'Motion & interface craft', ids: ['motion-craft', 'ui-engineering', 'variant-explorer', 'scroll-film'] },
   { title: 'Design & content craft', ids: ['design-loop', 'design', 'design-dna', 'presentations', 'course-storytelling', 'course-builder', 'technical-writing', 'translation-l10n'] },
   { title: 'Knowledge & meta', ids: ['knowledge-ops', 'codebase-onboarding', 'research-ops', 'decision-records', 'continuous-learning', 'skill-scout', 'context-budget', 'roast-me', 'fable-operator'] },
 ];

package/skills/ai-media/SKILL.md

@@ -2,7 +2,7 @@
 name: ai-media
 description: "Use when a creative goal must become a finished media file: pick and order generative-media models per modality — AI voiceover, image-to-video clips, score — then glue them with ffmpeg (mux, duck, loudnorm, concat). NOT still-image generation/editing (that is `replicate-images`); NOT code-rendered React compositing (that is `remotion-video`)."
 tags: [ai-media, text-to-speech, image-to-video, voiceover, music-generation, ffmpeg, media-pipeline, elevenlabs]
-recommends: [replicate-images, fal, replicate, remotion-video, video-shorts]
+recommends: [replicate-images, fal, replicate, remotion-video, video-shorts, scroll-film]
 origin: risco
 ---
 
@@ -23,7 +23,7 @@ Map the goal to modalities and an ordered step list, and **lock that plan before
 | Just a clip from a still | img→video only | still (input) → clip | `fal`/`replicate` |
 | Code-rendered explainer | none of the above | render from React/TS | **stop — route to `remotion-video`** |
 
-If the video is *rendered from data/code* (charts, timelines, JSON-driven scenes), this is not your job → `../remotion-video/SKILL.md`. You handle *model-generated + ffmpeg-glued*.
+If the video is *rendered from data/code* (charts, timelines, JSON-driven scenes), this is not your job → `../remotion-video/SKILL.md`. You handle *model-generated + ffmpeg-glued*. If the clips will be scrubbed by scroll on a page instead of played as a file, the chain, its seams and the page are `../scroll-film/SKILL.md`.
 
 ## Modality 1 — Voice (TTS)
 

package/skills/cost-tracking/SKILL.md

@@ -152,9 +152,10 @@ Route every cloud alert into the **same alert pipe** as your app-level budget al
 |---|---|---|
 | Zero code change, fastest setup | Helicone (proxy, ~2-min) | adds a network hop / latency |
 | SDK-level capture + a ready cost table | Langfuse (MIT, ships model+tokenizer cost table) | you wire the SDK, but no proxy hop |
+| Hard spend caps at a gateway, per team or app key | Bifrost (self-hosted, Apache-2.0; budgets and rate limits per virtual key) | one more service to run; caps are per key, not per feature |
 | Full control / custom attribution / typed caps | DIY ledger (this skill) | you own pricing-table freshness and capture coverage |
 
-(firecrawl.dev best-llm-observability-tools; guptadeepak.com top-5-llm-observability-platforms-2026, accessed 2026-06-02.) Buy the proxy/platform when you want spend *visibility* fast; build the ledger when caps and per-feature attribution must live inside your own logic.
+(firecrawl.dev best-llm-observability-tools; guptadeepak.com top-5-llm-observability-platforms-2026, accessed 2026-06-02; docs.getbifrost.ai features/governance/virtual-keys, accessed 2026-10-19.) Buy the proxy/platform when you want spend *visibility* fast; build the ledger when caps and per-feature attribution must live inside your own logic.
 
 ## Anti-patterns
 

package/skills/design/references/motion-and-interaction.md

@@ -220,6 +220,10 @@ Both are opt-in above a motion budget, both stay inside
 `@media (prefers-reduced-motion: no-preference)`, and both collapse to a plain vertical stack
 below `768px` rather than pinning on a phone.
 
+A **pre-rendered video scrubbed by scroll** (a camera flying through scenes, Apple-style) is not a
+timeline animation. The clips, the seams between them and the scrub engine are
+`../../scroll-film/SKILL.md`.
+
 ## See Also
 
 - `visual-system.md` — the easing and duration tokens these animations consume.

package/skills/llm-pipeline/SKILL.md

@@ -83,7 +83,7 @@ resp = router.completion(model="smart",
                          messages=[{"role": "user", "content": prompt}])
 ```
 
-**Build vs buy:** raw SDK + a thin retry/timeout wrapper (fewest deps, fine for one provider) → LiteLLM SDK/proxy (widest provider coverage, fallbacks for free) → hosted gateway (Bifrost/Portkey, when you want it operated for you). Full config — all fallback buckets, redis cache params, budget/rate-limit settings, cost callbacks — is in [references/litellm-router.md](references/litellm-router.md).
+**Build vs buy:** raw SDK + a thin retry/timeout wrapper (fewest deps, fine for one provider) → LiteLLM SDK/proxy (widest provider coverage, fallbacks for free) → self-hosted open-source gateway (Bifrost: Go, Apache-2.0, per-key budgets and rate limits) → hosted gateway (Portkey, when you want it operated for you). Full config — all fallback buckets, redis cache params, budget/rate-limit settings, cost callbacks — is in [references/litellm-router.md](references/litellm-router.md).
 
 ## Reliability mechanics
 

package/skills/scroll-film/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: scroll-film
+description: "Use when a page's hero is a pre-rendered camera flight the visitor scrubs by scrolling, Apple-style: AI clips chained frame to frame so seams never pop, encoded for seeking, mounted with an engine that holds up on phones. NOT scroll reveals or pinning (that is `design`), NOT a finished MP4 (that is `ai-media`)."
+tags: [scroll-scrub, scroll-video, scrollytelling, landing-hero, image-to-video, camera-flight, seamless-video]
+recommends: [ai-media, fal, replicate-images, landing-copy, design, performance]
+profiles: [full]
+origin: risco
+---
+
+# scroll-film — the camera moves, the scroll is the playhead
+
+The page plays nothing. It holds a chain of pre-rendered clips and maps the scroll position to
+their playhead, so the visitor flies through scenes — outside a building, inside it, on to the
+next — without a cut. Three parts must be right, and each fails in its own way: the **chain**
+(seams), the **encode** (seeking) and the **page** (phones). This skill owns all three.
+
+**Not this skill — delegate:**
+- Scroll-linked reveals, parallax, pinned sections, a horizontal pan, with no video → `../design/SKILL.md`.
+- A finished MP4 with voice and music → `../ai-media/SKILL.md`.
+- The call to the model endpoint (queue, webhooks, cost per call) → `../fal/SKILL.md` or `../replicate/SKILL.md`.
+- The scene stills themselves → `../replicate-images/SKILL.md`.
+- The words over the film → `../landing-copy/SKILL.md`. A video rendered from code → `../remotion-video/SKILL.md`.
+
+## 1. The gate: nothing renders before the user agrees to a number
+
+A chain is many clips, each one slow and billed. Interview, price it, then wait for a yes.
+
+1. **Subject.** Ask it as an open question: what the world is about, in a sentence. A menu of
+   industries decides their business for them.
+2. **Scenes.** 4 to 7, in the order the camera visits them, proposed from their own value chain and
+   edited by them. The last one carries the call to action.
+3. **Look.** One art direction, written once as a style preamble and pasted unchanged into every
+   still prompt. Identical text is what makes separate renders read as one world.
+4. **Camera feel.** Always ask. It picks the chain shape (section 3).
+5. **Phones.** Always ask. A real phone version is a second chain (section 6) and doubles the video bill.
+6. **Brand.** 4 to 6 hex colours, a name, a tone. The page background is the scene background.
+
+Then the bill:
+
+| | Forward take (A) | Dive and hop (B) |
+| --- | --- | --- |
+| Video clips, desktop only | N | 2N − 1 |
+| Video clips, with the phone chain | 2N | 4N − 2 |
+
+Estimate = clips × seconds per clip × today's price per second, plus about 20% for re-rolls, plus N
+stills. Read the price from the provider at build time; it moves (reading cost per call →
+`../fal/SKILL.md`). State the total against the balance and wait for the yes. When money is tight,
+offer a previz pass: the whole chain on the **same** model at its lowest resolution, approve the
+journey, then render the finals.
+
+## 2. The model must continue a shot, not just start one
+
+A seam holds only if the model starts a clip on an exact frame you hand it. That capability, not
+quality or price, qualifies a model.
+
+- Every clip needs a **start-frame** input. Hops (shape B) also need an **end-frame** input. Field
+  names vary by endpoint (`image_url`, `start_image`, `first_frame`; `end_image_url`,
+  `tail_image_url`, `last_frame`): read the input schema before batching. Model landscape →
+  `../ai-media/SKILL.md`.
+- A **reference-image** input does not qualify. It steers the style; frame 0 is still a new
+  render, and the seam pops.
+- **Probe once before the batch**, with one cheap clip from a real still prepared at the clip's
+  aspect (16:9, or 9:16 for phones). Frame 0 must match the still and the bill must match the
+  advertised price. For hop duty, add an end frame from another still: the last frame must land on
+  that composition. A near miss is normal; the engine's dissolve covers it. Commands →
+  `references/chain.md`.
+- **One model for the whole chain.** Each model has its own grain, colour and motion; a swap
+  mid-chain keeps positions continuous and still pops. The one exception is a single clip a content
+  filter keeps blocking (`references/chain.md`).
+
+## 3. Pick the chain shape from the camera feel
+
+| The user says | Shape | Clip k starts on | Clip k ends on | Fits |
+| --- | --- | --- | --- | --- |
+| "one continuous walkthrough", "one fixed angle gliding over it" | **A — forward take** | leg k−1's real last frame (leg 0: the first still) | nothing — no end frame | photoreal, interiors, product, real estate |
+| "fly from one island to the next" | **B — dive and hop** | dive: its still. hop: dive k's real last frame | hop: dive k+1's real first frame | miniature, diorama, map-like worlds |
+
+- A renders one leg at a time, because each needs the previous one's last frame. B renders every
+  dive in parallel, then every hop.
+- Never give an A leg a wide establishing shot as its end frame. The camera pulls back to meet it,
+  and the take reverses.
+- **The velocity rule.** Inside one clip the camera is free: orbit, rise, push in and ease back.
+  Across a seam it never reverses. Position matches, the motion flips, and it reads as a rewind,
+  in both scroll directions. So every leg ends by settling into a slow forward drift, and the next
+  one begins inside it. B reverses at every seam on purpose (pull out, hop, dive): charming over a
+  miniature map, a stutter in a realistic walkthrough. If the user picks B for a photoreal look, say
+  so before rendering.
+
+Prompt templates (still, leg, dive, hop), the camera-move table by concept, the fixed-angle clause
+and the batch loops → `references/chain.md`.
+
+## 4. The seam law: hand off pixels, not descriptions
+
+Every render redraws its scene a little differently. A hop that ends on the *original still* of
+scene 3 meets a dive that starts on *its own render* of scene 3: two pictures of one place, and the
+seam pops. So both ends of every clip come from the neighbours' actual renders.
+
+```bash
+# The true last frame: -update 1 overwrites per decoded frame, so the final one is what stays.
+ffmpeg -v error -y -sseof -1 -i leg_02.mp4 -update 1 -q:v 2 leg_02_last.png
+ffmpeg -v error -y -i dive_03.mp4 -frames:v 1 -q:v 2 dive_03_first.png
+```
+
+A plain `-sseof -0.15 -frames:v 1` stops a few frames short of the end: 15 dB PSNR from the real
+last frame on a 24 fps test clip. The engine parks the outgoing clip on its real last frame, so a
+handoff from the earlier one starts the seam already off.
+
+- Look at each last frame before chaining the next clip. In A, one bad handoff poisons every leg
+  after it: re-roll that leg.
+- The engine dissolves over a tenth of a viewport at each seam. That hides an end frame that landed
+  close. It cannot hide a different picture.
+
+## 5. Encode for seeking, not for playback
+
+Scrubbing seeks on every frame, and each seek decodes every frame since the last keyframe. The
+keyframe interval sets how smooth the scrub feels.
+
+```bash
+# Desktop: native resolution (never upscale), a keyframe every 8 frames, no audio, index first.
+ffmpeg -i leg_01.mp4 -an -c:v libx264 -preset slow -crf 20 -pix_fmt yuv420p \
+  -g 8 -keyint_min 8 -sc_threshold 0 -movflags +faststart assets/vid/shot-01.mp4
+# Phone: 720 wide, a keyframe every 4 frames; a phone decoder pays more per frame.
+ffmpeg -i leg_01_portrait.mp4 -an -vf scale=720:-2 -c:v libx264 -preset slow -crf 23 -pix_fmt yuv420p \
+  -g 4 -keyint_min 4 -sc_threshold 0 -movflags +faststart assets/vid/shot-01-m.mp4
+# Poster: the clip's first frame. It is the LCP image and the reduced-motion fallback.
+ffmpeg -v error -i assets/vid/shot-01.mp4 -frames:v 1 -c:v libwebp -quality 82 assets/shot-01.webp
+```
+
+One recipe for every clip in the chain. All-intra (`-g 1`) is the last resort for a low-end phone
+that still stutters, at about three times the size.
+
+## 6. Phones get their own chain, not a crop
+
+A 16:9 film on a portrait phone shows its middle quarter. When the user asked for phones, render
+the chain again at 9:16, frame-locked to its own renders. A landscape frame inside the portrait
+chain pops on both sides. Start images: each still composited onto a 1080×1920 canvas in the page
+background colour. The encodes are the `-m.mp4` files above, and each portrait clip's first frame is
+its `posterMobile`.
+
+No budget for it: the engine crops the landscape film with `object-fit: cover`, steered by
+`--film-focus`. Tell the user this is a stopgap. Never ship it as "the mobile version".
+
+## 7. Mount the page
+
+Copy `assets/scrub-engine.js` and `assets/page-template.html` into the project. The template is a
+working page: its copy is real HTML that reads without JavaScript, and the script moves it onto the
+film once the engine mounts.
+
+```js
+const film = ScrollFilm.mount(document.getElementById('film'), {
+  shots: [
+    { section: 0, src: 'assets/vid/shot-01.mp4', srcMobile: 'assets/vid/shot-01-m.mp4',
+      poster: 'assets/shot-01.webp', posterMobile: 'assets/shot-01-m.webp', length: 1.4, hold: 0.4 },
+    { section: 0, src: 'assets/vid/hop-01.mp4', poster: 'assets/hop-01.webp', length: 0.9 },
+    // one entry per clip, in chain order
+  ],
+  onChange: ({ section, sectionProgress }) => { /* fade the copy block for `section` */ },
+});
+```
+
+What the engine does, and the failure each part prevents:
+
+- **Loads each clip as a Blob.** On a host that ignores byte-range requests, a streamed `<video>`
+  reports `seekable` as [0, 0] and every seek lands on frame 0. A Blob is always seekable.
+- **Keeps one seek in flight per clip.** Queued seeks are what freeze a phone on a fast flick.
+- **Keeps the poster up until a frame has painted**, and primes each clip with a muted play and
+  pause, again on the first touch. iOS paints nothing for a seeked video that never played.
+- **Picks phone sources at mount**, ignores height-only resizes on touch (the URL bar sliding), and
+  re-lays out on rotation.
+- **Reduced motion or Save-Data:** no video is fetched; posters dissolve with the scroll and the
+  copy still works.
+- **Fetches a clip once**, when the scroll comes within 1.5 viewports of it.
+- **`destroy()`** removes everything it added. Call it from the effect cleanup in React or Vue.
+
+`design` bans raw scroll listeners for animation. This one is passive and only requests a frame. If
+the page already owns a scroll source (ScrollTrigger, `useScroll`), pass `listen: false` and call
+`film.update()` from it. All options, the state object, theming, pacing and the Next.js and Vue
+wiring → `references/engine.md`.
+
+The film layer is `aria-hidden`; the meaning lives in the copy. Its words → `../landing-copy/SKILL.md`.
+Its type, colour and spacing → `../design/SKILL.md`.
+
+## 8. Verify before calling it done
+
+1. **The chain, by script.** Pass the clips in chain order:
+
+   ```bash
+   bash <skill-dir>/scripts/verify.sh --frames qa/seams \
+     assets/vid/shot-01.mp4 assets/vid/hop-01.mp4 assets/vid/shot-02.mp4
+   bash <skill-dir>/scripts/verify.sh --gop 4 --portrait \
+     assets/vid/shot-01-m.mp4 assets/vid/hop-01-m.mp4 assets/vid/shot-02-m.mp4
+   ```
+
+   It checks each clip's encode (H.264, yuv420p, no audio, index first, keyframe interval), that
+   the chain shares one size and frame rate, and scores every seam against the clips' own
+   frame-to-frame step. A fixed SSIM threshold cannot tell: on a soft landscape photo, a cut to a
+   different picture still scored 0.76 and a fresh render of the same scene 0.92. Measured against
+   the step (0.98 there), the frame-locked seam passed at 0.987 and both others were flagged. Open
+   every flagged pair in `qa/seams/` and judge by what you see: a wrong seam shows different objects.
+2. **In a browser.** Scroll slowly across each seam on desktop. Then emulate a phone at 4 to 6× CPU
+   throttle and flick fast. Turn reduced motion on: posters only. In the Network panel, the phone
+   gets the `-m.mp4` files and the desktop gets the masters.
+3. **On a real iPhone**, if phones shipped: the first scene shows at once and no scene goes blank.
+
+## Anti-patterns
+
+| Failure mode | Usually | Fix |
+| --- | --- | --- |
+| A visible pop at one seam | The hop's end frame was the original still, or came from `-sseof` a few frames early | Extract the true frames from the neighbouring renders (section 4) |
+| The camera seems to rewind at every seam | Velocity reverses across the seam: B in a realistic walkthrough, or an A leg given a wide end frame | Shape A with the settle-into-drift clauses and no end frame |
+| Stuck on the first frame in production, fine locally | The host ignores byte ranges | Load as Blob; keep it when porting the engine to a framework |
+| A phone freezes on a fast flick | A 1080p, 8-frame-GOP master on a phone decoder, plus queued seeks | `-m.mp4` encodes at GOP 4; keep one seek in flight |
+| Black scenes on iPhone until the first touch | The poster was hidden on `loadedmetadata`, or `muted`/`playsinline` lost in a port | Keep the poster until a frame paints; keep both attributes |
+| The film scrolls away instead of sticking | An ancestor has `overflow: hidden`, often `body { overflow-x: hidden }` | `overflow-x: clip` |
+| A cheaper model "just for the hops" | Each model renders its own grain and motion | One model for the chain; previz on the same model at low resolution |
+| A content filter blocks a harmless interior | Words like bed, pool, spa or wine in the prompt | Re-roll, neutral wording, then the remedies in `references/chain.md` |
+
+## Orientación (siempre)
+
+Habla con la voz de `orient`: frases cortas, una idea por frase, y cada respuesta se entiende sola. Registro técnico o con analogías según `technical_level` en `02-DOCS/wiki/harness/user-profile.md`. Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ➡️ siguiente, terminando en pregunta; ✅ y 🧭 cuando hay algo hecho o decidido). **Nunca termines en seco.** Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`. (Defiere a `suggest` el "¿instalo la skill que falta?".)

package/skills/scroll-film/assets/page-template.html

@@ -0,0 +1,128 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+<title>Brand — one-line promise</title>
+<meta name="description" content="One sentence on what the brand does, for search and link previews.">
+<!-- The first poster is the LCP image: fetch it before the engine asks for it. -->
+<link rel="preload" as="image" href="assets/shot-01.webp" fetchpriority="high">
+<style>
+  :root {
+    --film-bg: #f3ede4;      /* match the scene background so posters and seams sit on it */
+    --ink: #1e1a22;
+    --ink-soft: #5b5462;
+    --accent: #6d55b8;
+    --film-focus: 50% 45%;   /* where object-fit: cover keeps the subject when it crops */
+  }
+  html { background: var(--film-bg); color: var(--ink); font: 400 1rem/1.55 system-ui, sans-serif; }
+  /* clip, never hidden: overflow hidden turns body into a scroll container and the stage stops sticking */
+  body { margin: 0; overflow-x: clip; }
+  a { color: inherit; }
+  .skip { position: absolute; left: -9999px; }
+  .skip:focus { left: 16px; top: 16px; z-index: 2000; background: var(--ink); color: var(--film-bg); padding: 8px 14px; border-radius: 8px; }
+  .site-head { position: fixed; inset: 0 0 auto; z-index: 1500; display: flex; justify-content: space-between; align-items: center; padding: 16px clamp(16px, 5vw, 56px); }
+  .eyebrow { margin: 0 0 12px; font-size: .8rem; font-weight: 700; letter-spacing: .14em; text-transform: uppercase; color: var(--accent); }
+  .film-copy h1, .film-copy h2 { margin: 0; font-size: clamp(2rem, 4.4vw, 3.4rem); line-height: 1.05; letter-spacing: -.01em; }
+  .film-copy p { margin: 16px 0 0; max-width: 38ch; color: var(--ink-soft); font-size: clamp(1rem, 1.3vw, 1.15rem); }
+  .cta { display: inline-block; margin-top: 24px; padding: 13px 24px; border-radius: 999px; background: var(--ink); color: var(--film-bg); text-decoration: none; font-weight: 600; }
+
+  /* Without JavaScript the copy is a plain stacked page: readable, indexable, nothing hidden. */
+  .film-copy article { padding: 18vh clamp(16px, 6vw, 80px); }
+
+  /* With the engine mounted, the copy rides the sticky stage and the scroll drives its opacity. */
+  .sf-root .film-copy { position: absolute; inset: 0; }
+  .sf-root .film-copy::before { content: ""; position: absolute; inset: 0 auto 0 0; width: min(60vw, 760px);
+    background: linear-gradient(90deg, var(--film-bg) 0%, color-mix(in srgb, var(--film-bg) 70%, transparent) 45%, transparent 100%); }
+  .sf-root .film-copy article { position: absolute; left: clamp(16px, 6vw, 80px); top: 50%; transform: translateY(-50%);
+    width: min(40vw, 460px); padding: 0; opacity: 0; }
+  .sf-root .film-copy article.is-current { pointer-events: auto; }
+  @media (max-width: 860px) {
+    .sf-root .film-copy::before { inset: auto 0 0 0; width: auto; height: 60%;
+      background: linear-gradient(0deg, var(--film-bg) 10%, color-mix(in srgb, var(--film-bg) 65%, transparent) 50%, transparent 100%); }
+    .sf-root .film-copy article { top: auto; transform: none; left: 16px; right: 16px; width: auto;
+      bottom: calc(10svh + env(safe-area-inset-bottom)); }
+  }
+
+  .after-film { position: relative; z-index: 1; padding: 20vh clamp(16px, 6vw, 80px); background: var(--film-bg); }
+</style>
+</head>
+<body>
+<a class="skip" href="#after-film">Skip the film</a>
+<header class="site-head"><strong>Brand</strong><a href="#contact">Contact</a></header>
+
+<main>
+  <section id="film" aria-label="The journey, from first step to finished product">
+    <div class="film-copy">
+      <article data-section="0">
+        <p class="eyebrow">Where it starts</p>
+        <h1>Headline for the opening scene.</h1>
+        <p>One sentence, from the visitor's side.</p>
+      </article>
+      <article data-section="1">
+        <p class="eyebrow">Step two</p>
+        <h2>Headline for the second scene.</h2>
+        <p>One sentence, from the visitor's side.</p>
+      </article>
+      <article data-section="2">
+        <p class="eyebrow">The payoff</p>
+        <h2>Headline for the finale.</h2>
+        <p>One sentence that earns the click.</p>
+        <a class="cta" href="#contact">The one action</a>
+      </article>
+    </div>
+  </section>
+
+  <section id="after-film" class="after-film">
+    <h2 id="contact">The rest of the page scrolls normally after the film.</h2>
+  </section>
+</main>
+
+<script src="scrub-engine.js"></script>
+<script>
+  (function () {
+    var copy = document.querySelector('#film .film-copy');
+    var blocks = Array.prototype.slice.call(copy.querySelectorAll('article'));
+    var last = blocks.length - 1;
+    var EDGE = 0.15; // share of a section spent fading its copy in and out
+
+    var film = ScrollFilm.mount(document.getElementById('film'), {
+      // Architecture B shown: dive, connector, dive, connector, dive. A forward take (A) is
+      // the same list with one leg per section and no connectors.
+      shots: [
+        { section: 0, src: 'assets/vid/shot-01.mp4', srcMobile: 'assets/vid/shot-01-m.mp4',
+          poster: 'assets/shot-01.webp', posterMobile: 'assets/shot-01-m.webp', length: 1.4, hold: 0.4 },
+        { section: 0, src: 'assets/vid/hop-01.mp4', srcMobile: 'assets/vid/hop-01-m.mp4',
+          poster: 'assets/hop-01.webp', posterMobile: 'assets/hop-01-m.webp', length: 0.9 },
+        { section: 1, src: 'assets/vid/shot-02.mp4', srcMobile: 'assets/vid/shot-02-m.mp4',
+          poster: 'assets/shot-02.webp', posterMobile: 'assets/shot-02-m.webp', length: 1.2, hold: 0.3 },
+        { section: 1, src: 'assets/vid/hop-02.mp4', srcMobile: 'assets/vid/hop-02-m.mp4',
+          poster: 'assets/hop-02.webp', posterMobile: 'assets/hop-02-m.webp', length: 0.9 },
+        { section: 2, src: 'assets/vid/shot-03.mp4', srcMobile: 'assets/vid/shot-03-m.mp4',
+          poster: 'assets/shot-03.webp', posterMobile: 'assets/shot-03-m.webp', length: 1.6, hold: 0.5 },
+      ],
+      onChange: function (state) {
+        blocks.forEach(function (block, i) {
+          var opacity = 0;
+          if (i === state.section) {
+            var p = state.sectionProgress;
+            var fadeIn = i === 0 ? 1 : Math.min(1, p / EDGE);       // the first block greets on load
+            var fadeOut = i === last ? 1 : Math.min(1, (1 - p) / EDGE); // the last one holds its CTA
+            opacity = Math.min(fadeIn, fadeOut);
+          }
+          block.style.opacity = String(opacity);
+          block.classList.toggle('is-current', opacity > 0.5);
+        });
+      },
+    });
+
+    film.overlay.appendChild(copy);
+
+    // Keyboard users tab into copy that may be faded out: bring its scene to them.
+    blocks.forEach(function (block) {
+      block.addEventListener('focusin', function () { film.jumpTo(Number(block.dataset.section)); });
+    });
+  })();
+</script>
+</body>
+</html>