Skip to content

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.json
index 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.md
index 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 is
missing or the balance can't cover the chain, say so and fall back to
rendering the chain on Higgsfield credits instead — same model, same
pipeline, 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 generated
through Codex's built-in `image_gen` (the same gpt-image-2 model) billed to the
user'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 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
@@ -82,7 +82,8 @@ fabricated multiple-choice. A made-up list of industries biases them and reads a
deciding 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 Claude
Code; 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 even
there, signal they can go their own way ("Other"). Ask only what you can't sensibly
default. 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 a
set 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 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.
-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 a
two-option choice (`AskUserQuestion` in Claude Code; a plain question elsewhere):
*"Want a mobile-optimized version too? The mobile version is a second camera chain
rendered 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 a
desktop-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 the
render tiers (`AskUserQuestion`), then compute and state the estimated total for
the 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, zero
credits): same prompt files, same byte-identical preamble, generated by Codex's
built-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 flies
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.
+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 the
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.
+**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 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
@@ -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 is
the **native 9:16 portrait chain** (pipeline.md §6b): portrait renders of every dive and
connector, 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-area
insets 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), and
that `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, still
posters 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.md
index de87d77..f035e9e 100644
--- a/skills/scroll-world/references/pipeline.md
+++ b/skills/scroll-world/references/pipeline.md
@@ -42,7 +42,7 @@ gen_still() { # name
for 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, zero
credits; ~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` fo
the mobile encode still pays off — the tighter GOP is what makes phone seeks cheap. All-mobile encodes stay 16:9 — the engine
centre-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** rendered
natively for phones and shipped as the mobile variants — never the §6 crops (those are the
no-credits stopgap). Same seam laws as the main chain — the portrait chain frame-locks
against 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: composite
each scene onto a 1080×1920 canvas in the page bg colour (island at ~94% width, visual
diff --git a/skills/scroll-world/references/prompts.md b/skills/scroll-world/references/prompts.md
index 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 scene
Reversals are safe *inside* a leg (it's one continuous render) — only a seam may never
reverse. 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 hero
object], keeping it centered, then continuing past it"
- **Crane-up reveal** (scale, atriums, campuses): "rising smoothly as the full scale of