A skill that turn any brand into a scrollable 3D world landing page
JavaScript
v0.4.0: budget interview — engines shown by cost before rendering
cyw2912048246d0
diff --git a/README.md b/README.mdindex 36e9993..31ed634 100644--- a/README.md+++ b/README.md@@ -49,12 +49,18 @@ cp -R scroll-world/skills/scroll-world ~/.codex/skills/ # Codex- The [Higgsfield CLI](https://higgsfield.ai), authenticated (`higgsfield auth login`),with credits.- `ffmpeg` / `ffprobe` for frame extraction and encoding.-- Python 3 with Pillow (optional — only for the transparent-scene knockout).+- Python 3 with Pillow (for the mobile portrait canvases; also the optional+ transparent-scene knockout).+- The [Codex CLI](https://github.com/openai/codex) (optional) — if present, the scene+ stills can be generated through Codex's built-in `image_gen` (the same GPT Image+ model), billed to a ChatGPT subscription instead of Higgsfield credits.## What it doesIt leans on [Higgsfield](https://higgsfield.ai) for the art: cohesive isometric diorama-scenes (GPT Image 2) and the camera flights themselves (Seedance image-to-video), scrubbed+scenes (GPT Image 2 — via Higgsfield, or the Codex CLI on a ChatGPT subscription) and the+camera flights themselves (Seedance or Kling image-to-video — only models that can+frame-lock a seam), scrubbedby scroll position — the same technique behind Apple's scroll-through product pages. Thecamera genuinely moves; scroll only drives time. It's **framework-agnostic**: you get theHiggsfield pipeline, the prompt templates, and a portable vanilla-JS scrub engine that@@ -63,11 +69,18 @@ drops into plain HTML, Next.js, Vue, or a Python-served page — nothing assumesWhen invoked, the skill:1. **Interviews you** — the subject/industry + pitch, a brand kit (import from a URL, hand- it over, or have it proposed), art direction, and the ordered scenes the camera visits.-2. **Generates the assets** with Higgsfield — one still per scene, one "dive-in" camera+ it over, or have it proposed), art direction, the ordered scenes the camera visits,+ whether you want the **mobile version** (a second chain rendered natively in 9:16+ portrait — composed for phones, not a crop of the landscape film), and the **budget** —+ render tiers and stills source shown with estimated credit costs, approved before+ anything generates.+2. **Generates the assets** — one still per scene, one "dive-in" cameraclip per scene, and the **connector** clips that join consecutive scenes, generatedfrom the actual rendered frames of their neighbours so every seam is frame-identical.-3. **Wires it up** — a config-driven scroll engine that plays the whole chain as one flight.+ Mobile opt-in renders a parallel portrait chain the same way, frame-locked against its+ own 9:16 renders.+3. **Wires it up** — a config-driven scroll engine that plays the whole chain as one+ flight, serving the portrait clips and posters automatically on phones.## What's in the skill@@ -84,8 +97,11 @@ skills/scroll-world/## Notes-- Asset generation costs Higgsfield credits (~N image gens + ~2N-1 video gens for N scenes)- and takes a while — the skill runs generations in the background and polls.+- Asset generation costs Higgsfield credits (~N image gens + ~2N-1 video gens for N+ scenes; the mobile chain doubles the video gens) and takes a while — the skill runs+ generations in the background and polls. Per-generation pricing isn't exposed by the+ CLI, so the skill calibrates against your live balance and states the estimated total+ before spending.- The generated `.mp4`/`.webp` assets are produced per project; they're not shipped here.## Star Historydiff --git a/skills/scroll-world/SKILL.md b/skills/scroll-world/SKILL.mdindex 17e9f7c..6792ab7 100644--- a/skills/scroll-world/SKILL.md+++ b/skills/scroll-world/SKILL.md@@ -48,7 +48,12 @@ not the framework.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+4. **(Optional) Codex CLI** — if `codex` is on `$PATH` (≥ 0.125) and+ `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.+5. 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 isrejected by media flags — pass **local file paths** to `--image/--start-image/--end-image`.@@ -111,11 +116,42 @@ default. Cover:a "mobile version," it's just the page not breaking when a phone visits — so adesktop-only build still degrades gracefully.-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.+6. **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.+ - **Video tier** (roster only — every option frame-locks seams, Step 4):++ | Tier | Model | Rough cost |+ |---|---|---|+ | Draft / previz | `seedance_2_0_mini` (720p) | ~¼ of Standard |+ | Standard (default) | `seedance_2_0` (1080p) | baseline |+ | Alternate | `kling3_0` (720p native) | ≈ Standard; different look + content filter |++ Draft doubles as the previz path: run the whole chain cheap, approve the+ journey, re-render final legs on Standard (pipeline.md Notes) — suggest it+ unprompted when the balance reads tight.+ - **Stills source** (only offer if the Codex CLI is present, Step 0.4):+ Higgsfield `gpt_image_2` (spends credits) vs **Codex `image_gen`** — the same+ gpt-image-2 model billed to the ChatGPT subscription (zero credits; counts+ toward Codex usage limits; 1536×1024 output — exactly 3:2, slightly under+ Higgsfield's 2k). Stills are plain PNGs handed to `--start-image`, so the+ video chain is indifferent to their source. Command in Step 2. **One source+ for all N stills of a build** — the two render with slightly different+ character (verified: Codex runs warmer/lighter), and mixing sources across+ scenes reads as style drift, same reason the video chain uses one model.+ - **Calibrate costs, don't guess.** The CLI exposes no pricing and plans differ.+ Run ONE still and ONE video first, diff `higgsfield workspace list` before/+ after, extrapolate to the full run, and warn the user whenever the estimate+ exceeds ~70% of the balance. (Observed on a plus plan, 2026-07: Standard+ video ≈ 40–55 credits, still ≈ 15.) A real `not_enough_credits` mid-run is+ recoverable (finished clips survive; resume after top-up) but ugly — the+ whole point of this step is that the user decides *before* the spend.++If the user names a video model outside the roster, honor it **only if it can+frame-lock seams** (Step 4). 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.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.@@ -141,6 +177,20 @@ 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+ credits): same prompt files, same byte-identical preamble, generated by Codex's+ built-in `image_gen`:++ ```bash+ codex exec -C "$WORK" -s workspace-write --skip-git-repo-check \+ 'Use the image generation tool ($imagegen) to generate: '"$(cat "$WORK/still_i.txt")"' Wide 3:2 landscape, high resolution. Save it as ./still_i.png. Do not do anything else.'+ ```++ Single-quote the `$imagegen` segment (the shell must not expand it); if editing+ with reference images, the prompt goes BEFORE any `-i` flag (it's variadic).+ ~1–3 min per image; run a few in parallel, not all N at once. Output lands at+ 1536×1024 (3:2) — fine for `--start-image` and posters. Everything downstream+ (cohesion review, knockout, dives) is unchanged.- A generation may fail transiently (HTTP 503) — re-roll that one individually; don'trestart the batch.- **Review the stills before continuing.** They must read as one cohesive world (samediff --git a/skills/scroll-world/references/pipeline.md b/skills/scroll-world/references/pipeline.mdindex 9d7332c..9a72f0e 100644--- a/skills/scroll-world/references/pipeline.md+++ b/skills/scroll-world/references/pipeline.md@@ -39,6 +39,18 @@ gen_still() { # namefor n in $NAMES; do gen_still "$n" & done ; wait```+Codex variant (STILLS_SOURCE=codex, SKILL Step 1.6 — subscription-billed, zero+credits; ~1–3 min each, parallelize in small batches):++```bash+gen_still_codex() { # name+ codex exec -C "$WORK" -s workspace-write --skip-git-repo-check \+ 'Use the image generation tool ($imagegen) to generate: '"$(cat "$WORK/still_$1.txt")"' Wide 3:2 landscape, high resolution. Save it as ./still_'"$1"'.png. Do not do anything else.' \+ > "$WORK/still_$1.codex.log" 2>&1+ [ -f "$WORK/still_$1.png" ] && echo "still $1 ok (codex)" || echo "still $1 FAIL (see .codex.log)"+}+```+Convert to webp for the site (and optionally run knockout.py first for transparency):```bashdiff --git a/skills/scroll-world/references/prompts.md b/skills/scroll-world/references/prompts.mdindex af8f737..0562cce 100644--- a/skills/scroll-world/references/prompts.md+++ b/skills/scroll-world/references/prompts.md@@ -14,7 +14,12 @@ Collect and write down:- `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. Yes = the **native 9:16 portrait chain** (pipeline §6b):+ 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.+- `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.