A skill that turn any brand into a scrollable 3D world landing page
JavaScript
v0.8.0: camera style is the user's choice at the interview
cywe3c13a80a2d2
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.jsonindex a59d529..00afdde 100644--- a/.claude-plugin/plugin.json+++ b/.claude-plugin/plugin.json@@ -1,7 +1,7 @@{"name": "scroll-world","description": "Build an immersive scroll-scrubbed 'fly through the world' landing page for any industry or brand using Higgsfield. As the visitor scrolls, a pre-rendered camera flies from outside each scene into its interior, then flows on to the next scene with no cuts — one continuous connected flight. Interviews the user for the topic, story beats, and brand kit, then generates cohesive scenes + seamless camera clips and wires a portable, framework-agnostic scroll-scrub engine. Use for a '3D world' / 'browse-through-the-industry' hero, a scroll cinematic, or a diorama landing.",- "version": "0.7.0",+ "version": "0.8.0","author": {"name": "cyw","email": "[email protected]"diff --git a/skills/scroll-world/SKILL.md b/skills/scroll-world/SKILL.mdindex d016f0b..8adcd22 100644--- a/skills/scroll-world/SKILL.md+++ b/skills/scroll-world/SKILL.md@@ -46,7 +46,7 @@ not the framework.1. **Monid CLI — the default video-chain backend.** Check `monid --version`,`monid keys list` (active key) and `monid balance` — the chain is billed per- clip in USD (Step 1.6 has the numbers; a 1080p N=6 chain ≈ $27). If the CLI is+ clip in USD (Step 1.7 has the numbers; a 1080p N=6 chain ≈ $27). If the CLI ismissing or the balance can't cover the chain, say so and fall back torendering the chain on Higgsfield credits instead — same model, samepipeline, different biller (Step 4 → Monid backend).@@ -64,7 +64,7 @@ not the framework.`codex login status` reports a ChatGPT login, the scene stills can be generatedthrough Codex's built-in `image_gen` (the same gpt-image-2 model) billed to theuser's ChatGPT subscription instead of Higgsfield credits — offer it at- Step 1.6, command in Step 2. Absence just removes the option.+ Step 1.7, command in Step 2. Absence just removes the option.6. Caveats: macOS ships **bash 3.2** (no `declare -A`); don't use associative arrays inscripts. Higgsfield generations take **3–8 min each** — always run them detached(background) and poll, never a foreground blocking call. Reference-by-job-UUID is@@ -82,7 +82,8 @@ fabricated multiple-choice. A made-up list of industries biases them and reads adeciding their business for them; let them answer in their own words (their real business,a client's, or any idea). Reserve structured multiple-choice (`AskUserQuestion` in ClaudeCode; a plain either/or question elsewhere) for the genuinely-enumerable, lower-stakes choices below — art direction and brand-kit approach — and even+enumerable, lower-stakes choices below — art direction, camera style, and brand-kit+approach — and eventhere, signal they can go their own way ("Other"). Ask only what you can't sensiblydefault. Cover:@@ -100,13 +101,32 @@ default. Cover: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. **The journey (sections)** — the ordered scenes the camera flies through. Propose a+4. **Camera style — ALWAYS ask; it's the film's personality, not a technical+ detail.** Ask by feel (`AskUserQuestion` in Claude Code; a plain question+ elsewhere) and record the answer as `CAMERA`. The options map to the Step 4+ architectures — Step 4 then *implements* the choice, it never re-decides it:+ - **"Fly through the world"** — the camera dives into each scene, pulls up and+ out, and hops across the miniature world to the next; angles change+ constantly, big expressive aerial moves (this is the flagship-demo look).+ → Architecture B. Recommend as the default for diorama/miniature art+ directions.+ - **"One continuous walkthrough"** — a single forward flight that glides+ through each scene straight into the next, never pulling back; expressive+ but always-forward moves per scene (camera grammar table). → Architecture A.+ Recommend as the default for grounded/photoreal art directions.+ - **"Locked isometric glide"** — the camera keeps one fixed angle for the whole+ film, Emons-style; the world slides past/toward it, no rotation, no reveals.+ → Architecture A + the locked-iso clause in every leg prompt (prompts.md).+ State the trade-off in one line each (B reverses direction at seams — charming+ in miniature, jarring in realism; locked-iso is the calmest and cheapest to+ re-roll; walkthrough sits between).+5. **The journey (sections)** — the ordered scenes the camera flies through. Propose aset derived from the subject's own value chain and let the user edit. 5–7 works well.Boba example: farms → pearl kitchen → flagship shop → delivery → community plaza →the hero product. Each section needs: a short subject description (what's IN thediorama), an eyebrow, a headline, one line of body, and 0–3 tag pills. The lastsection is usually the hero product + the CTA.-5. **Mobile version — ALWAYS ask this; never silently generate both.** Ask as a+6. **Mobile version — ALWAYS ask this; never silently generate both.** Ask as atwo-option choice (`AskUserQuestion` in Claude Code; a plain question elsewhere):*"Want a mobile-optimized version too? The mobile version is a second camera chainrendered natively in **9:16 portrait** — composed for phones, not a crop of the@@ -128,7 +148,7 @@ default. Cover:a "mobile version," it's just the page not breaking when a phone visits — so adesktop-only build still degrades gracefully.-6. **Budget — engines shown by cost, decided before anything renders.** Present the+7. **Budget — engines shown by cost, decided before anything renders.** Present therender tiers (`AskUserQuestion`), then compute and state the estimated total forthe user's N scenes — `N stills + (2N−1) videos [videos ×2 if mobile] + ~15%re-roll headroom` — and get a go before generating.@@ -206,7 +226,7 @@ Subject: <what is in THIS diorama>.- Run all N concurrently, detached. Command per scene:`higgsfield generate create gpt_image_2 --prompt "$(cat scene_i.txt)" --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.-- **Codex stills variant** (if chosen at Step 1.6 — subscription-billed, zero+- **Codex stills variant** (if chosen at Step 1.7 — subscription-billed, zerocredits): same prompt files, same byte-identical preamble, generated by Codex'sbuilt-in `image_gen`:@@ -242,10 +262,13 @@ These stills double as **video posters and lazy-load fallbacks**, so keep them.----## Step 4 — Camera architecture (pick one — this makes or breaks the feel)+## Step 4 — Camera architecture (implements the Step 1.4 choice)-How the camera moves *between* scenes is the single biggest quality lever. Two shapes;-pick by aesthetic.+How the camera moves *between* scenes is the single biggest quality lever. The user+already chose the style at the interview (`CAMERA`, Step 1.4): fly-through → **B**,+walkthrough → **A**, locked-iso → **A + the locked-iso leg clause** (prompts.md). If+the interview somehow skipped it, ask now — never silently pick for them. The two+shapes, and the grammar that colors them:### Video model — pick ONE for the whole chain@@ -360,7 +383,10 @@ A "dive into each scene" clip + a connector that pulls **up and out** and fliesnext 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 outto 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.+jarring **rewind/stutter**. Use B only for the map-like aesthetic — which is exactly+what the "fly through the world" interview answer opts into; the reversal reads as+intentional there. If the user picked B against a grounded/photoreal direction, say+why it will read as a stutter and confirm before rendering.### Camera grammar — the move should fit the concept (A is NOT "forward only")@@ -397,6 +423,15 @@ like a frame from a gentle forward glide — if not, re-roll before wasting thebudget ~1 extra re-roll per expressive leg. A plain forward glide stays the zero-riskdefault — use it for legs where the scene itself is the show.+**Locked-iso variant** (`CAMERA` = locked isometric glide): architecture A where every+leg pins the view instead of taking a mid-leg move — "the camera keeps exactly the same+high isometric angle throughout, no rotation, no orbit, no tilt; it only travels+straight and level, the world sliding past beneath the same view" (verbatim clause in+prompts.md). The handoff contract is unchanged. Seedance drifts the angle slightly on+long legs — the existing eyeball-each-last-frame rule is the catch; re-roll a leg whose+view has rotated. Calmest look, cheapest re-rolls, and the closest to the Emons+reference.+Two related pacing knobs live in the engine (Step 7): per-section `scroll` (more scrolldistance = longer dwell in that scene) and `linger` (the camera settles mid-scene exactlywhile the copy peaks, then picks up speed toward the seam). Prefer expressive motion in the@@ -507,7 +542,7 @@ ffmpeg -i src.mp4 -an -vf "unsharp=5:5:0.8:5:5:0.0" \Encode all 2N-1 clips (dives + connectors) with the same settings for uniform quality.-**Mobile encodes (only if the user opted in at Step 1.5).** The mobile version is+**Mobile encodes (only if the user opted in at Step 1.6).** The mobile version isthe **native 9:16 portrait chain** (pipeline.md §6b): portrait renders of every dive andconnector, encoded **720 wide (`scale=720:-2`), `-g 4`** (more keyframes = cheaper seeks —phone decoders' seek cost scales with GOP length), crf 23 — wired as `clipMobile` /@@ -565,7 +600,7 @@ and **primes each video on first touch** (fixes iOS's blank-until-played video),drifting particles, ignores URL-bar-only resizes (no scroll jump), and uses safe-areainsets so copy clears the notch/home indicator. All of this hardening is on by default —no config needed. The `clipMobile`/`connectorsMobile` encodes are the opt-in part-(Step 1.5): only wire them when the user asked for the mobile version.+(Step 1.6): only wire them when the user asked for the mobile version.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.@@ -583,7 +618,7 @@ is the thing most likely to be wrong:the crossfade band is too short.- Check the console for errors, confirm `video.seekable.end(0) > 0` (blob working), andthat `currentTime` tracks scroll across each clip's band.-- **Mobile — full checklist only if the user opted into the mobile version (Step 1.5).**+- **Mobile — full checklist only if the user opted into the mobile version (Step 1.6).**For a desktop-only build, just sanity-check a phone viewport once: page loads, stillposters show, nothing overlaps — the engine's hardening covers graceful degradation.For the mobile build (do this on a real phone or an emulated one, portrait + landscape):diff --git a/skills/scroll-world/references/pipeline.md b/skills/scroll-world/references/pipeline.mdindex de87d77..f035e9e 100644--- a/skills/scroll-world/references/pipeline.md+++ b/skills/scroll-world/references/pipeline.md@@ -42,7 +42,7 @@ gen_still() { # namefor n in $NAMES; do gen_still "$n" & done ; wait```-Codex variant (STILLS_SOURCE=codex, SKILL Step 1.6 — subscription-billed, zero+Codex variant (STILLS_SOURCE=codex, SKILL Step 1.7 — subscription-billed, zerocredits; ~1–3 min each, parallelize in small batches):```bash@@ -170,14 +170,14 @@ If phone scrubbing still stutters, tighten the GOP further (`-g 2`, or `-g 1` fothe mobile encode still pays off — the tighter GOP is what makes phone seeks cheap. All-mobile encodes stay 16:9 — the enginecentre-crops them; see the portrait note in SKILL Step 8 / prompts.md.-## 6b. Native 9:16 portrait chain — THE mobile version (Step 1.5 opt-in)+## 6b. Native 9:16 portrait chain — THE mobile version (Step 1.6 opt-in)When the user opts into mobile, this is what they get: a **parallel 9:16 chain** renderednatively for phones and shipped as the mobile variants — never the §6 crops (those are theno-credits stopgap). Same seam laws as the main chain — the portrait chain frame-locksagainst its own rendered frames, never the landscape ones. Budget ~2N-1 video gens +re-rolls (interiors trip the NSFW filter in portrait too); state the credit cost at the-Step 1.5 interview.+Step 1.6 interview.1. **Portrait start canvases.** Don't hand the video model a 3:2 still and hope: compositeeach scene onto a 1080×1920 canvas in the page bg colour (island at ~94% width, visualdiff --git a/skills/scroll-world/references/prompts.md b/skills/scroll-world/references/prompts.mdindex 0562cce..bdcb4f8 100644--- a/skills/scroll-world/references/prompts.md+++ b/skills/scroll-world/references/prompts.md@@ -13,15 +13,22 @@ Collect and write down:- `TONE` — a word or two (cozy/premium, playful, industrial…).- `STYLE` — the art direction (default below).- `SECTIONS[]` — ordered list; for each: `id`, `label`, `subject` (what's in the diorama), `eyebrow`, `title`, `body` (≤ 1 sentence), `tags[]` (0–3). Last section = hero product + CTA.-- `MOBILE` — yes/no. **Always asked** (SKILL Step 1.5), presented to the user- with the ~2× credit cost stated.-- `VIDEO_TIER` — draft (`seedance_2_0_mini`) | standard (`seedance_2_0`, default) |- alternate (`kling3_0`). Chosen by cost at SKILL Step 1.6, with the calibrated- total estimate stated before anything renders.+- `CAMERA` — fly-through (arch B: dives + aerial hops — the flagship-demo look) |+ walkthrough (arch A: one continuous forward flight) | locked-iso (arch A + the+ locked-iso clause below: one fixed angle for the whole film). **Always asked**+ (SKILL Step 1.4), presented by feel with a one-line trade-off each.+- `MOBILE` — yes/no. **Always asked** (SKILL Step 1.6), presented to the user+ with the ~2× credit cost stated. Yes = the **native 9:16 portrait chain**+ (pipeline §6b): portrait renders of every dive/connector ++ `clipMobile`/`connectorsMobile`/`stillMobile` wiring + the full mobile QA. The+ §6 crop encodes are a no-credits stopgap only.+- `VIDEO_TIER` — default is `seedance_2_0` **via Monid** (pay-per-clip; previz =+ same endpoint at 480p, final at 1080p). Higgsfield-credit alternates: draft+ (`seedance_2_0_mini`) | standard (`seedance_2_0`) | alternate (`kling3_0`).+ Chosen by cost at SKILL Step 1.7, with the estimated total stated before+ anything renders.- `STILLS_SOURCE` — higgsfield (`gpt_image_2`, spends credits) | codex- (`image_gen`, subscription-billed; only offer when the Codex CLI is present). Yes = the **native 9:16 portrait chain** (pipeline §6b):- portrait renders of every dive/connector + `clipMobile`/`connectorsMobile`/`stillMobile`- wiring + the full mobile QA. The §6 crop encodes are a no-credits stopgap only.+ (`image_gen`, subscription-billed; only offer when the Codex CLI is present).## Style preamble (default: clay diorama)@@ -82,6 +89,20 @@ steady forward glide toward [the doorway / opening / direction of the next sceneReversals are safe *inside* a leg (it's one continuous render) — only a seam may neverreverse. That's why "ease back out" is fine mid-leg.+**Locked-iso clause** (`CAMERA` = locked isometric glide — SKILL Step 1.4/Step 4):+skip this library entirely and put this clause, verbatim, in the mid-leg slot of+EVERY leg:++```+The camera keeps exactly the same high isometric angle throughout — no rotation, no+orbit, no tilt. It only travels straight and level, the world sliding past beneath+the same view.+```++Keep the handoff-contract clauses around it unchanged. When checking each leg's last+frame, also check the ANGLE hasn't drifted (Seedance rotates slightly on long legs) —+re-roll the leg if the view has turned.+- **Half-orbit** (product, luxury): "sweeping in a slow half-orbit around [the heroobject], keeping it centered, then continuing past it"- **Crane-up reveal** (scale, atriums, campuses): "rising smoothly as the full scale of