scroll-world

scroll-world

Produces a landing page where scroll drives a camera: it dives from outside a scene into its interior, then flies out and into the next scene, continuously, with no visible cuts. The visuals are AI-generated (Higgsfield); the page just scrubs pre-rendered video by scroll position. This is the same technique behind Apple's scroll-through product pages — the camera genuinely moves, scroll only drives time.

What you generate: N scene stills (anchor-gated) → N "dive-in" camera clips → N-1 "connector" clips that join consecutive scenes seamlessly → encoded clips + extracted posters → an automated SSIM seam check → a portable scrub engine that plays the whole chain as one flight. Chain clips render on the cheap previz tier first by default; full-model credits are spent only after the user approves the draft.

The one rule that makes or breaks it: seams must be frame-identical. Read The seamless chain before generating any connector. Getting this wrong is the single most common failure and produces a visible "pop" between scenes.

Do not assume a frontend framework. The scrub engine in references/scrub-engine.js is self-contained vanilla JS (it builds its own DOM + injects its own CSS into a container you give it), so it drops into plain HTML, Next.js, Vue, a Python-served page, anything. The value of this skill is the Higgsfield pipeline, the prompts, and the seam method — not the framework.

---

Step 0 — Bootstrap

1. Higgsfield CLI. If higgsfield is not on $PATH, install per the higgsfield-generate skill. If higgsfield workspace list fails auth, ask the user to run higgsfield auth login (interactive OAuth — you cannot run it) and, if needed, higgsfield workspace set <id>. Confirm there are enough credits: a run is N image gens + N video gens (architecture A) or (2N-1) video gens (architecture B), plus re-rolls — the Step 1 budget tier sets N.
2. ffmpeg / ffprobe on $PATH (frame extraction + encoding).
3. An image tool for background knockout if you want floating scenes: PIL (python3 -c "import PIL"), or cwebp/sips. Optional — see Step 3.
4. Caveats: macOS ships bash 3.2 (no declare -A); don't use associative arrays in scripts. Higgsfield generations take 3–8 min each — always run them detached (background) and poll, never a foreground blocking call. Reference-by-job-UUID is rejected by media flags — pass local file paths to --image/--start-image/--end-image. Video models differ in accepted params (e.g. Kling has no --resolution) and in whether they support start/end-image conditioning at all — before batching, confirm the chosen model's schema with higgsfield model get <job_type> and see the Step 4 model table.

---

Step 1 — Interview the user

The subject is the user's to state — ask it as an open question in plain prose, never a fabricated multiple-choice. A made-up list of industries biases them and reads as you deciding their business for them; let them answer in their own words (their real business, a client's, or any idea). Reserve AskUserQuestion (with options) for the genuinely enumerable, lower-stakes choices below — art direction and brand-kit approach — and even there, signal they can go their own way ("Other"). Ask only what you can't sensibly default. Cover:

1. Subject (ask openly, not multiple-choice) — "What should this world be about? Your business, a client's, or any idea — a word or a sentence is fine." Capture the industry/product + a one-line pitch (e.g. "a bubble tea company, from leaf to last sip"), and a brand name if they have one; otherwise you'll propose one below.
2. Brand kit — offer three paths, pick one:
   • Import from a URL: higgsfield marketing-studio brand-kits fetch --url <site> --wait (pulls name, colours, tone). Then read it back with brand-kits list --json.
   • The user hands you palette + name + tone directly.
   • You propose a palette + name and let them approve. Capture 4–6 named hex values, a display name, and a tone word or two.
3. Art direction — default is "soft matte low-poly clay diorama, isometric, tilt-shift miniature, warm light." Offer alternatives (flat papercraft, glossy toy, claymation, neon night). Whatever is chosen becomes the shared style preamble reused verbatim in every scene prompt (this is what makes the world cohesive).
4. Budget tier — ask BEFORE proposing the journey; video generations dominate cost. The bill scales with scene count and architecture: architecture A (forward take) = N videos, architecture B (dives + connectors) = 2N-1 videos, plus N stills and a ~20–30% re-roll buffer. A 6-scene arch-B run is ~17 generations — a serious bite out of a subscription. Use AskUserQuestion with concrete numbers:
   • Lean (~8 gens) — 4 scenes, architecture A (4 stills + 4 legs), skip previz (small runs re-roll cheaper than a draft pass). Same site, same continuous flight — just 4 beats instead of 6.
   • Standard (~11–13 gens) — 5 scenes; arch A (10 gens) or arch B (5 + 9 = 14).
   • Showcase (~17+ gens) — 6–7 scenes, full arch-B world, previz pass, mobile tiers. Fewer scenes ≠ thinner site. 3–4 well-chosen beats read as a complete world: give each scene more scroll distance (scroll: 1.6–2) and linger, and let the copy carry more per beat. A tight 4-scene world beats a budget-starved 6-scene one. Two more levers when the user wants the B aesthetic on a lean budget: connectors are individually optional (a null slot crossfades that seam directly — honest tradeoff: that one transition is a dissolve, not a flight; spend connectors on the seams around the hero scenes) and seedance_2_0_mini can BE the final model if the user accepts 720p — it frame-locks, so the site stays seamless.
5. The journey (sections) — the ordered scenes the camera flies through, sized to the budget tier. Propose a set derived from the subject's own value chain and let the user edit. Boba example (6-scene showcase): farms → pearl kitchen → flagship shop → delivery → community plaza → the hero product; lean 4-scene cut: farms → kitchen → shop → hero product. Each section needs: a short subject description (what's IN the diorama), an eyebrow, a headline, one line of body, and 0–3 tag pills. The last section is usually the hero product + the CTA.
6. Mobile tier — ALWAYS ask this; never silently generate extra assets. Phones get the full scroll animation in every tier — the engine's hardening (seek-coalescing, iOS priming + Low Power Mode stills fallback, safe-area CSS, data-saver downgrade) is always on; the tiers only decide what ASSETS exist. Use AskUserQuestion, options in this order, with the credit cost stated:
   • Crop-safe (default, no extra cost) — phones scrub the desktop clips, centre-cropped to portrait. Every prompt already composes focal subjects centre-safe (prompts.md), so this reads fine for most worlds.
   • Mobile encodes (recommended, no extra credits — just encode time) — -m.mp4 siblings (720p, -g 4, Step 6) + clipMobile/connectorsMobile/posterMobile wiring (Step 7) + mobile QA (Step 8). Phone-class devices (NOT tablets — the engine tiers by screen, iPad gets the master) scrub the lighter files.
   • Hero reframe (small extra credit cost — state it) — mobile encodes + 9:16 re-renders of the 1–2 scenes where the focal subject can't hold a centre crop (usually hero + finale). Wire per-scene as the mobile clip/poster.
   • Full portrait chain (gold tier, ≈2× video credits — state it) — a parallel 9:16 chain: portrait stills, own frame handoffs, own connectors, own SSIM gate (aspect ratios can't mix mid-chain — a 9:16 clip can't continue a 16:9 frame). This is what Apple ships: the mobile asset is a differently-framed render, not a crop. Offer only when the user signals mobile traffic matters or the budget is loose.

Video model is not an interview question — default seedance_2_0 silently. If the user names a preference, honor it only if it can frame-lock seams (Step 4 roster: seedance_2_0, kling3_0, seedance_2_0_mini). This skill only ships seamless output, so a model that can't frame-lock is declined with a one-line why, not substituted in — use a roster model instead.

Close the interview with a spend estimate — get explicit go-ahead before any generation. State the bill in plain numbers from the chosen budget tier: N image gens + video gens (N for architecture A, 2N-1 for B; previz adds a mini-tier chain on showcase runs) + a re-roll budget (~20–30% extra on interiors, thanks to the NSFW filter), plus any mobile-tier extras, and roughly how long it runs (gens are 3–8 min each; architecture A is sequential). The user approves the spend once, here — after that the only further gates are the anchor-still approval (Step 2) and the previz review (Step 4), both of which exist to keep the big spend from being wasted, not to re-ask permission.

Keep the scroll mechanic fixed (continuous fly-through) — that's the point of the skill. See references/prompts.md for the intake checklist and copy structure.

---

Step 2 — Generate the scene stills

One image per section, all sharing the same style preamble for cohesion. Default model gpt_image_2 (crisp, great at isometric illustration; returns a solid/white background which is perfect for floating diorama "islands"). Use nano_banana_2 only if the brief is character/cartoon-heavy (note: nano_banana_2 is a CLI alias — it resolves to nano_banana_pro; it won't appear under that name in higgsfield model list).

Prompt shape (full templates in references/prompts.md):

<STYLE PREAMBLE, identical every time>. On a plain solid <bg> background with a soft
contact shadow. <PALETTE hexes>. No text, no letters, no logos, centered, 3:2.
Subject: <what is in THIS diorama>.

• Anchor first — never batch all N cold. Generate ONE anchor still (the most representative scene), show it to the user, and iterate the style preamble until they approve. Only then batch the remaining N-1 with the approved anchor passed as --image to lock the style. A style miss on the anchor costs 1 gen; after a cold batch it costs N. This is a hard gate — do not proceed past an unapproved anchor.
• Batch the rest concurrently, detached. Command per scene: higgsfield generate create gpt_image_2 --prompt "$(cat scene_i.txt)" --image anchor.png --aspect_ratio 3:2 --resolution 2k --quality high --wait --wait-timeout 15m --json > scene_i.json 2>scene_i.err
• Result URL is .[]0.result_url in the --wait --json output. curl it down.
• A generation may fail transiently (HTTP 503) — re-roll that one individually; don't restart the batch.
• Review the batch before continuing. It must read as one cohesive world (same angle, palette, light). Re-roll any off-style scene individually — the anchor style lock stays in force.

See references/pipeline.md for the exact batch script (idempotent — re-runs skip finished assets, so a crash or re-roll never repays for done work).

---

Step 3 — (Optional) Float the scenes

If you want the dioramas to float over an atmospheric background instead of sitting in a solid box, knock out the flat background to transparency with references/knockout.py (border-connected flood fill — preserves interior colour that matches the bg, e.g. cream walls). Then encode to webp. If you'd rather keep it simple, just make the page background the same colour as the scene background and skip this.

Keep the stills either way — they're the reduced-motion artwork and no-clip fallback. (Loading posters are NOT the stills: they're extracted from the encoded clips in Step 6, so the still→video swap can't pop.)

---

Step 4 — Camera architecture (pick one — this makes or breaks the feel)

How the camera moves between scenes is the single biggest quality lever. Two shapes; pick by aesthetic.

Video model — pick ONE for the whole chain

This skill only ships seamless output, so the only usable models are ones that can frame-lock a seam: every chained clip must accept --start-image, and connectors also need --end-image. That capability — not preference — is the selection rule. Check any model with higgsfield model get <job_type> and skip anything whose media inputs are reference-only (no start/end image): it can only condition a generation, not continue a shot, so it physically can't hold a seam. Schemas below were confirmed against the CLI:

Model	start/end image	Notes
seedance_2_0 (default)	✓ / ✓	Full chain (legs + connectors). --mode std --resolution 1080p. Its NSFW filter is the touchy one (see Gotchas).
kling3_0	✓ / ✓	Full chain — tested: --mode std --sound off --duration 5 with start+end images accepted, seams frame-lock cleanly. No --resolution param (don't pass one; --mode std returns 720p native — encode what ffprobe reports, never upscale). Sound defaults on → --sound off. --duration default 5, try 10 for legs. Different content filter than Seedance — the sanctioned NSFW fallback.
seedance_2_0_mini	✓ / ✓	Cheap draft tier that keeps frame-locking (720p). The previz tier: run the whole chain here first, then re-render final legs on the full model — still seamless, so it translates directly.

Those three are the roster — all do both architectures. (kling3_0_turbo also frame-locks via --start-image, but has no --end-image, so it's architecture-A-only and can't make connectors; it also takes a different flag set — no --mode, has --resolution — so it doesn't drop into the pipeline as-is. It's not in the default roster; only reach for it, and wire it by hand, if architecture A's sequential render time is a proven bottleneck and you've benchmarked it as actually faster.)

Previz first (default, not optional-extra). Unless the run is small (≤4 scenes), render the whole chain on seedance_2_0_mini first. It frame-locks, so everything that matters — journey order, camera grammar, seam continuity, copy pacing against the scrub — is validated at draft cost; assemble the page from the previz clips and review it with the user before a single full-model credit is spent. Then clear the draft clips, flip $VMODEL, and re-render final (stills are reused; the pipeline's idempotency makes the second pass mechanical — references/pipeline.md, setup block).

Rules:

• One model for all chained clips. Each renderer has its own motion/color/grain character; mixing models mid-chain keeps position continuity (frames still hand off) but the render-character shift reads as a subtle pop. The one sanctioned exception is the NSFW fallback for a single stubborn clip (Gotchas) — a slight character shift on one 5s connector beats a missing connector.
• Default to seedance_2_0; honor a user's stated preference only if the model qualifies (frame-locking). If it doesn't, say so and use a supported model — never ship a non-seamless build to satisfy a model request.
• The pipeline scripts take the model as $VMODEL with per-model flags already cased out (references/pipeline.md).

A) Continuous forward take — RECOMMENDED for grounded / realistic / walkthrough

One camera that only ever glides forward, first scene through last, as a single take. Generate the legs sequentially: leg 0 from scene-0's still (glide forward into it); then each leg's --start-image = the previous leg's ACTUAL last frame (extract with ffmpeg), prompt "continue gliding smoothly FORWARD into [scene i], never pulling back" (or an expressive mid-leg move under the motion-handoff contract — see Camera grammar below), and no --end-image — an end-image of a wide establishing shot forces the camera to pull back, which is the #1 cause of stutter. Extract each leg's last frame to feed the next. Result: every seam is frame-identical and the camera never reverses. There are no connectors (skip Step 5) — the legs ARE the journey. Wire each leg as a section clip with connectors: [] and a small crossfade (~0.08). Even without an --end-image the legs still arrive at distinct rooms (the prompt steers the content). Cost: strictly sequential (can't parallelize) and slower; interiors trip the NSFW filter, so build in re-rolls (3 attempts/leg).

B) Dive-in + aerial connector — only for diorama / miniature / god's-eye worlds

A "dive into each scene" clip + a connector that pulls up and out and flies over to the next scene (Step 5). The pull-out reverses camera direction at every seam (forward dive → backward pull-out). In a miniature/diorama world that reads as an intentional "zoom out to the map, fly to the next island"; in a grounded first-person walkthrough it reads as a jarring rewind/stutter. Use B only for the map-like aesthetic. When in doubt, use A.

Camera grammar — the move should fit the concept (A is NOT "forward only")

"Forward only" is the seam rule, not the leg rule. The physics of the chain:

• Position continuity at a seam comes from the frame handoff (next leg starts from the previous leg's actual last frame).
• Velocity continuity at a seam means the camera must never reverse across a seam — that's the rewind stutter.
• Inside a single leg the camera is free. One leg is one continuous render — there is no seam to break mid-leg, so orbits, crane-ups, lateral tracking, even a push-in that eases back out are all safe within the clip. Reversals are only fatal across seams.

So give each leg an expressive move chosen from the scene's own logic, under a motion handoff contract: every leg ends by settling into a slow, steady forward drift toward the next destination (final ~1 s), and every leg begins by continuing that same drift. Keep both clauses in the prompts verbatim (templates in references/prompts.md).

Pick the grammar from the concept:

Concept / tone	Mid-leg move
Product / luxury retail	slow half-orbit around the hero object, then continue past it
Real estate / hospitality	steadicam glide through doorways; gentle crane-up in atria
Industrial / process / logistics	low lateral track alongside the line, foreground parallax
Travel / outdoors / campus	drone-style rise-and-reveal, then a descending swoop
Food / craft / detail-driven	push in close to the craft moment, ease back, carry on
Playful miniature (arch. B)	dives + aerial hops — the connector IS the grammar

Honest costs: expressive mid-leg moves raise re-roll odds — the model can end a fancy move in a state that isn't a clean forward drift. Mitigations: keep the final-second settle clause verbatim; eyeball each leg's last frame before chaining the next (it should look like a frame from a gentle forward glide — if not, re-roll before wasting the next leg); budget ~1 extra re-roll per expressive leg. A plain forward glide stays the zero-risk default — use it for legs where the scene itself is the show.

Two related pacing knobs live in the engine (Step 7): per-section scroll (more scroll distance = longer dwell in that scene) and linger (the camera settles mid-scene exactly while the copy peaks, then picks up speed toward the seam). Prefer expressive motion in the clip and restraint in the scrub mapping — they compound.

And remember scroll is a scrubber: visitors can scroll up, so every move also plays in reverse. That's free and expected — no extra work — but it's another reason seam velocity must be consistent in both directions (a seam that reads fine forward reads as a stutter backward too if velocity flips).

For B, one camera flight per scene: starts high/outside, descends into the interior, structure opens. Model: the chain model you picked above (default seedance_2_0), --start-image = the scene still.

• Use the solid-background still (not the knocked-out transparent one) as the start image, so the video has a full frame.
• Prompt: "Single continuous cinematic camera move, no cuts. Begin high and far looking at the whole from outside … descend and fly inside toward … the roof/walls gently open to reveal the interior. , smooth graceful slow motion. No text." (Template in references/prompts.md.)
• Params (seedance): --mode std --resolution 1080p --aspect_ratio 16:9 --duration 8. For Kling: drop --resolution (no such param), add --sound off, --duration 10. Do not pass --generate-audio (it errors on seedance; audio is wasted anyway — you'll mute).
• Run concurrently, detached, then download each .result_url. Re-roll individual failures. Keep the raw 1080p sources — you need their frames next.

---

Step 5 — Connectors (architecture B only)

Skip this whole step for architecture A — the forward take has no connectors; its legs already chain seamlessly. This step applies to B (diorama/miniature), and note the reversal caveat from Step 4.

The connector clips are what make the world feel connected instead of cut. A connector flies from the end of scene i out and into the start of scene i+1. Both of its endpoints must be the ACTUAL RENDERED FRAMES of the neighbouring clips — never the original diorama still.

Why: every Higgsfield generation renders slightly differently. If a connector ends on a fresh render of "the kitchen diorama," but the next dive clip starts on its own different render of that same diorama, the two won't match and you get a pop at the seam. The fix is to hand off the exact pixels:

For each connector between dive_i and dive_{i+1}:
  start-image = the LAST frame extracted from dive_i's rendered video
  end-image   = the FIRST frame extracted from dive_{i+1}'s rendered video

Now every seam is frame-identical on both sides: dive_i.end == connector.start and connector.end == dive_{i+1}.start.

Extract the boundary frames from the rendered dives (not the stills):

ffmpeg -sseof -0.15 -i dive_i.mp4   -frames:v 1 -q:v 2 dive_i_last.png    # interior of i
ffmpeg -ss 0      -i dive_{i+1}.mp4 -frames:v 1 -q:v 2 dive_next_first.png # establishing of i+1

Generate the connector (--duration 5 is plenty). Connectors need --end-image, so the model must accept it — any roster model does (seedance_2_0, seedance_2_0_mini, kling3_0):

higgsfield generate create "$VMODEL" \
  --prompt "$(cat connector_i.txt)" \
  --start-image dive_i_last.png --end-image dive_next_first.png \
  $VOPTS --aspect_ratio 16:9 --duration 5 --wait --json
# seedance: VOPTS="--mode std --resolution 1080p"; kling3_0: VOPTS="--mode std --sound off"

Connector prompt: "Single continuous camera move, no cuts. Pull up and back out of , rise into the sky, glide across the connected miniature world, and arrive above <scene i+1>, beginning to descend toward it. Seamless flowing aerial transition.

. No text." (Template in `references/prompts.md`.) Insurance: Seedance lands *close* to the end-image but not always pixel-perfect, so the engine still applies a **short crossfade** (a few frames) at each seam. Frame-matched endpoints + a small crossfade = no visible cut. Never skip the actual-frame handoff and rely on the crossfade alone; a big content jump can't be hidden by a crossfade. Whether a handoff actually held is **machine-checkable** — don't wait for the browser QA to find out. After encoding, run the SSIM seam check (`references/pipeline.md` §5c): a true actual-frame handoff scores ≥0.95 across the boundary; <0.75 means an endpoint was a still or the wrong frame. Run it again after every re-roll — replacing one clip silently touches BOTH of its seams. --- ## Step 6 — Encode for smooth scrubbing Scrubbing = setting `video.currentTime` from scroll. Two things matter, and they are often gotten wrong: 1. **Seekability, not keyframe density, is what makes scrubbing work.** Many static hosts (and `python -m http.server`) don't serve HTTP byte-range requests, which pins `video.seekable` to `[0,0]` and clamps *every* seek to frame 0 — the video looks frozen. The robust fix is to **fetch each clip as a `Blob` and play it from an in-memory object URL** (blobs are always fully seekable). The engine does this. Because of it, you do **not** need all-intra video. 2. **Don't shrink quality to get smooth seeks.** Encode at the **native resolution** (1080p from Seedance — don't downscale), `crf ~20`, a **small GOP** (`-g 8`) rather than all-intra (all-intra bloats an 8s clip to ~25 MB; GOP 8 is ~8 MB and scrubs fine via blob). Strip audio, add faststart, and a light `unsharp` counters video softness: ```bash ffmpeg -i src.mp4 -an -vf "unsharp=5:5:0.8:5:5:0.0" \ -c:v libx264 -preset slow -crf 20 -pix_fmt yuv420p \ -g 8 -keyint_min 8 -sc_threshold 0 -movflags +faststart out.mp4 ``` Encode all 2N-1 clips (dives + connectors) with the same settings for uniform quality. **Extract posters from the ENCODED clips** (`references/pipeline.md` §5b). The still is a 3:2 image; the clip is a 16:9 *re-render* of it — if the still is the loading poster, the first video paint visibly jumps (crop + render drift) on the very first scene a visitor sees. Same doctrine as the connectors, applied to seam zero: the poster must be the clip's own extracted first frame. Wire it as `sections[k].poster` (Step 7); keep the still as the reduced-motion artwork. Then run the **automated seam check** (`references/pipeline.md` §5c) before touching a browser — every seam SSIM ≥0.90 or you have a redo, not a QA note. **Mobile encodes (only if the user picked a tier beyond crop-safe at Step 1.6).** Phone video decoders seek far slower than a laptop's, and seek cost scales with GOP length, so the 1080p `-g 8` master that scrubs smoothly on desktop can stutter on a phone. Produce a lighter `-m.mp4` sibling for every clip — **720p, `-g 4`** (more keyframes = cheaper seeks; keyframe-every-4-to-10 is the industry recipe for scrub-smooth mobile video), crf 23 — and wire them as `clipMobile` / `connectorsMobile` (Step 7). Extract each mobile encode's first frame as its `posterMobile` (same doctrine as §5b — the poster must match the encode the device actually gets). The engine serves mobile files on phone-class devices only (screen short side ≤600 CSS px — tablets and iPads get the master) and falls back to the desktop clip when absent. Scripts in `references/pipeline.md` §6; for the hero-reframe / portrait-chain tiers see §7. If the user chose crop-safe, skip this — the engine still hardens phone scrubbing regardless (seek-coalescing, iOS priming, Low Power Mode stills fallback), so the page degrades gracefully rather than breaking. --- ## Step 7 — Assemble the page Copy `references/scrub-engine.js` (and, if you want a fully standalone page, the tiny `references/index-template.html`) into the user's project — or adapt into their framework. It's config-driven and self-contained: ```js mountScrollWorld(document.getElementById('world'), { brand: { name: 'Pearl & Co.' }, diveScroll: 1.3, connScroll: 0.9, // viewport-heights of scroll per clip sections: [ { id:'farm', label:'The Farms', still:'assets/farm.webp', poster:'assets/farm-poster.webp', // encoded clip's extracted first frame (Step 6) clip:'assets/vid/farm.mp4', clipMobile:'assets/vid/farm-m.mp4', // mobile beta only scroll: 1.6, linger: 0.45, // optional pacing: longer dwell + camera settles mid-scene accent:'#8FB98A', eyebrow:'From leaf to last sip', title:'It starts in the hills.', body:'…', tags:['Single-origin','Hand-picked'] }, // …one per section; last may carry a `cta` ], connectors: ['assets/vid/conn1.mp4','assets/vid/conn2.mp4', /* … length = sections-1 */], connectorsMobile: ['assets/vid/conn1-m.mp4','assets/vid/conn2-m.mp4' /* … same length; mobile beta only */], }); ``` The engine handles: the ordered dive/connector chain, scroll→currentTime with rAF smoothing, blob loading, lazy prefetch of nearby clips, frame-matched crossfades, pinned per-section copy (first section greets on landing, last holds its CTA), a route rail, `prefers-reduced-motion`, and mobile. **Pacing per section:** `scroll` overrides `diveScroll` for that scene (more scroll = longer dwell) and `linger` (0–1, keep ≤ 0.6) remaps time so the camera settles mid-scene — exactly while the copy peaks — then speeds up toward the seam; seam frames are untouched (f(0)=0, f(1)=1). Give the hero and finale scenes a higher `scroll` + some `linger`; keep transit scenes brisk. Theme it with CSS variables (`--accent`, `--sw-bg`, `--sw-ink`, …) — the visual identity comes from the generated clips, so the chrome stays quiet. See the header of `scrub-engine.js` for the full config + CSS vars. **On phones the engine adapts automatically, along two separate axes.** *Clip tier* (which file) is decided by device class — screen short side ≤600 CSS px = phone → `clipMobile`/`posterMobile`; tablets (iPad Pro included — coarse pointer but desktop-class screen and decoder) and desktops get the master. *Behaviour hardening* (how it acts) keys off coarse pointer / ≤860px viewport: **coalesced seeks** (never queues a new `currentTime` mid-seek — what stops a fast flick freezing the clip), poster held until the clip paints, **video priming on first touch** (iOS blank-until-played fix), a longer scroll run per scene (`scrollMobileFactor`, default 1.2 — small viewports read the same flight as faster), dropped particles, URL-bar-safe resizes, safe-area insets. **Automatic stills fallback:** `prefers-reduced-motion`, Chromium data-saver, and iOS **Low Power Mode** (detected at runtime — a rejected muted `play()` on first touch) all flip the page to stills-with-crossfades instead of frozen video. On 2g/3g (Chromium signal) the clip prefetch window shrinks. All of this is on by default — no config. The `clipMobile`/`connectorsMobile`/`posterMobile` encodes are the opt-in tiers from Step 1.6: wire them only when the user picked one. **SEO copy is not optional — this is a landing page.** The engine renders all copy client-side, so on its own the page has zero crawlable text. Always put a plain-markup mirror of the copy (h1 = hero line, one h2 + p per scene, real CTA links) inside the container in a `data-sw-seo` block — the engine hides it on mount, crawlers/link previews/no-JS visitors read it from the served HTML. `references/index-template.html` ships the block; when adapting into a framework, server-render it. For non-JS backends (Python/Rails/etc.): serve the assets and drop the engine `<script>` into the rendered HTML; nothing about it is framework-specific. --- ## Step 8 — QA the seams (don't skip) **First, the machine check:** the SSIM seam gate (`references/pipeline.md` §5c) must already be green — every seam ≥0.90 (0.75–0.90 only where you've eyeballed the crossfade and accepted it). If you skipped it, run it now; browser QA below verifies the *page*, the SSIM gate verifies the *assets*, and a red asset can't be QA'd into a green page. Then drive the page in a headless browser and **verify frame continuity at the seams** end-to-end: - Screenshot at scroll positions just before and just after each seam. The two frames must be near-identical (the dive's last frame == the connector's first frame). If they pop, you used the diorama still instead of the actual rendered frame (redo Step 5), or the crossfade band is too short. - Confirm the first paint is clean: the poster (extracted frame) shows instantly, and the poster→video takeover does not shift the image (if it does, `poster` is missing or points at the still — Step 6). - Check the console for errors, confirm `video.seekable.end(0) > 0` (blob working), and that `currentTime` tracks scroll across each clip's band. - **Stills-mode fallbacks (every build, cheap to check):** - Data-saver: emulate `navigator.connection.saveData = true` (DevTools override or an init script) — page must render as stills-with-crossfades, zero clip fetches in the Network panel. - Low Power Mode: hardest to emulate — on a real iPhone, enable it and confirm the page falls back to stills on first touch instead of frozen video. Emulated proxy: stub `HTMLMediaElement.play` to return a rejected promise, tap, confirm stills mode. - Tablet tier: iPad viewport (834×1194, touch) must fetch the **desktop** clip (Network panel), not the `-m.mp4` — while still getting touch behaviour. - **Mobile — full checklist only if the user picked a mobile tier (Step 1.6).** For a crop-safe build, just sanity-check a phone viewport once: page loads, still posters show, nothing overlaps — the engine's hardening covers graceful degradation. For the mobile tiers (do this on a real phone or an emulated one, portrait + landscape): - Emulate a phone viewport **with CPU throttled 4–6×** and scroll fast — the clip should track without freezing (the seek-coalescing + `-m.mp4` encodes are what make this hold). - Confirm the first scene shows immediately (its still is the poster) and the video takes over the instant you scroll — no blank/black scene (the iOS priming fix). Test iOS Safari specifically; it's the one that goes blank if this regresses. - Verify the `-m.mp4` variant is actually served on mobile (Network panel), and the heavy 1080p master on desktop. - Slowly scroll so the URL bar collapses — the page must **not jump** (height-only resizes are ignored on touch). Rotate the device — layout should recompose cleanly. - Portrait crops a 16:9 clip to its centre; confirm the focal subject still reads. If a hero scene's subject sits off-centre and gets cut, recompose it (prompts.md) or generate a 9:16 variant for that scene. - Check reduced-motion (should fall back to the stills, no video, no particles). --- ## Gotchas — top 5 inline; full list in `references/gotchas.md` Read `references/gotchas.md` the moment any generation fails or any QA check reads wrong — it maps symptom → cause → fix for every failure seen in production (encode, theming, phone, iOS, Kling flags, portrait crops, and more). The five that block runs most often: - **Seam pop** → connector endpoints were the diorama stills, not the neighbouring clips' actual frames. Always extract real frames (Step 5); the SSIM gate (pipeline §5c) catches this before a browser ever opens. - **Seam stutter / camera "jumps backward"** → camera *velocity reverses* across a seam (inherent to architecture B's pull-outs). Grounded walkthroughs must use architecture A (Step 4). - **NSFW false-positives (Seedance `status "nsfw"`)** → flags innocuous interiors (bedroom/pool/spa; words like "bed", "wine", "swim"). In order: re-roll (often passes 2nd–3rd try) → strip trigger words + add "empty, unoccupied, no people, architectural" → regenerate that one clip on `kling3_0` with the same start/end frames → set the connector slot to `null` (engine crossfades that seam directly). Budget re-rolls on interiors. - **Frozen video / stuck at frame 0** → host doesn't serve byte ranges, `seekable=[0,0]`. Blob URLs fix it (engine does this). - **Concurrent gens 503 / "not_enough_credits" race** → transient under parallel launch; re-roll the individual failure (verify credits with `higgsfield workspace list`). ## References - `references/prompts.md` — the intake checklist, style-preamble pattern, and every prompt template (scene still, dive, connector) with fill-in slots. - `references/pipeline.md` — copy-paste batch scripts for the whole run (anchor-gated stills → previz → dives → frames → connectors → encode → posters → SSIM seam gate → mobile encode), idempotent + bash-3.2-safe. - `references/scrub-engine.js` — the portable, config-driven scrub engine (builds DOM + injects CSS; blob-seek, lazy load, seam crossfade, extracted-frame posters, hidden `data-sw-seo` static-copy block, copy, route rail, reduced-motion, and phone hardening: mobile encodes, seek-coalescing, iOS priming, safe-area, no-jump resize). - `references/index-template.html` — a minimal standalone page that mounts the engine, including the crawlable `data-sw-seo` copy block. - `references/knockout.py` — border-connected background knockout for floating scenes. - `references/gotchas.md` — the full symptom → cause → fix list, plus the canvas frame-sequence alternative for when video scrubbing isn't smooth enough.