Skip to content

A skill that turn any brand into a scrollable 3D world landing page

JavaScript

scroll-world: installable Claude Code plugin

cywefc291ae27bb
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
new file mode 100644
index 0000000..9fe701e
--- /dev/null
+++ b/.claude-plugin/marketplace.json
@@ -0,0 +1,17 @@
+{
+ "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+ "name": "scroll-world",
+ "description": "Immersive scroll-scrubbed 'fly through the world' landing pages, generated with Higgsfield.",
+ "owner": {
+ "name": "cyw",
+ "email": "[email protected]"
+ },
+ "plugins": [
+ {
+ "name": "scroll-world",
+ "source": "./plugins/scroll-world",
+ "description": "Build an immersive scroll-scrubbed landing page where a pre-rendered camera flies from outside each scene into its interior, then flows on to the next with no cuts. Interviews the user for topic, story beats, and brand kit; generates cohesive scenes + seamless camera clips with Higgsfield; wires a portable, framework-agnostic scrub engine.",
+ "category": "design"
+ }
+ ]
+}
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..646ac51
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,2 @@
+.DS_Store
+node_modules/
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..083f577
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cyw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c9c7157
--- /dev/null
+++ b/README.md
@@ -0,0 +1,88 @@
+# scroll-world
+
+A Claude Code skill that builds an immersive, **scroll-scrubbed "fly through the world"
+landing page** for any industry or brand — the kind where, as you scroll, a camera flies
+from *outside* each scene *into* its interior, then flows on to the next scene with **no
+cuts**. One continuous connected flight through a little generated world (think the Emons
+logistics site, applied to whatever you want).
+
+It 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
+by scroll position — the same technique behind Apple's scroll-through product pages. The
+camera genuinely moves; scroll only drives time.
+
+**The skill is framework-agnostic.** It gives you the Higgsfield pipeline, the prompt
+templates, and a portable vanilla-JS scrub engine that drops into plain HTML, Next.js, Vue,
+or a Python-served page — nothing assumes a stack.
+
+## What it does
+
+When 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
+ clip per scene, and the **connector** clips that join consecutive scenes.
+3. **Wires it up** — a config-driven scroll engine that plays the whole chain as one flight.
+
+### The part that makes it good
+
+The scenes connect **seamlessly** because each connector clip is generated with the
+*actual rendered frames* of its neighbours as its start/end images (not the original
+stills — those re-render slightly differently and would pop at the seam). Both sides of
+every seam end up frame-identical, so the camera never cuts. This is baked into the skill
+as the central rule.
+
+It also captures the non-obvious production gotchas: blob-URL loading so scrubbing works on
+hosts that don't serve HTTP byte-range requests, GOP/encoding settings that stay sharp
+without bloating, and Higgsfield's quirks.
+
+## Requirements
+
+- 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).
+
+## Install
+
+### As a plugin (recommended)
+
+```
+/plugin marketplace add oso95/scroll-world
+/plugin install scroll-world@scroll-world
+```
+
+Then just ask for a scroll-through world landing page, or invoke `/scroll-world`.
+
+### Manually (drop-in skill)
+
+Copy the skill folder into your Claude Code skills directory:
+
+```bash
+git clone https://github.com/oso95/scroll-world
+cp -R scroll-world/plugins/scroll-world/skills/scroll-world ~/.claude/skills/
+```
+
+## What's in the skill
+
+```
+skills/scroll-world/
+├── SKILL.md the procedure + the seam rule + gotchas
+└── references/
+ ├── prompts.md intake checklist + every Higgsfield prompt template
+ ├── pipeline.md copy-paste batch scripts (generate → frames → connectors → encode)
+ ├── scrub-engine.js portable, config-driven scrub engine (blob-seek, lazy load, seam crossfade)
+ ├── index-template.html a minimal standalone page that mounts the engine
+ └── knockout.py background knockout for floating scenes
+```
+
+## 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.
+- The generated `.mp4`/`.webp` assets are produced per project; they're not shipped here.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
diff --git a/plugins/scroll-world/.claude-plugin/plugin.json b/plugins/scroll-world/.claude-plugin/plugin.json
new file mode 100644
index 0000000..581589e
--- /dev/null
+++ b/plugins/scroll-world/.claude-plugin/plugin.json
@@ -0,0 +1,21 @@
+{
+ "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.1.0",
+ "author": {
+ "name": "cyw",
+ "email": "[email protected]"
+ },
+ "homepage": "https://github.com/oso95/scroll-world",
+ "license": "MIT",
+ "keywords": [
+ "higgsfield",
+ "landing-page",
+ "scroll",
+ "video",
+ "seedance",
+ "diorama",
+ "webgl-alternative",
+ "cinematic"
+ ]
+}
diff --git a/plugins/scroll-world/LICENSE b/plugins/scroll-world/LICENSE
new file mode 100644
index 0000000..083f577
--- /dev/null
+++ b/plugins/scroll-world/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cyw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/plugins/scroll-world/README.md b/plugins/scroll-world/README.md
new file mode 100644
index 0000000..b3de680
--- /dev/null
+++ b/plugins/scroll-world/README.md
@@ -0,0 +1,12 @@
+# scroll-world (plugin)
+
+Builds an immersive scroll-scrubbed "fly through the world" landing page for any 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.
+
+This directory is the installable plugin. The skill itself lives in
+[`skills/scroll-world/`](skills/scroll-world/SKILL.md). See the
+[repository README](../../README.md) for what it does, requirements, and install steps.
+
+Invoke by asking Claude Code for a scroll-through world / diorama landing page, or run
+`/scroll-world`.
diff --git a/plugins/scroll-world/skills/scroll-world/SKILL.md b/plugins/scroll-world/skills/scroll-world/SKILL.md
new file mode 100644
index 0000000..55d3f9c
--- /dev/null
+++ b/plugins/scroll-world/skills/scroll-world/SKILL.md
@@ -0,0 +1,294 @@
+---
+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 (Emons-style isometric diorama world,
+ or any art direction you pick). The skill interviews the user for the topic, the
+ story beats/sections, and brand kit, then generates cohesive scenes + seamless camera
+ clips with Higgsfield and wires a portable, framework-agnostic scroll-scrub engine.
+ Use when the user wants a "3D world" / "browse-through-the-industry" hero, a scroll
+ cinematic, a diorama landing, or to turn a business into a scrollable world.
+allowed-tools: Bash, Read, Write, Edit, AskUserQuestion, Skill
+---
+
+# 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 → N "dive-in" camera clips → N-1 "connector" clips
+that join consecutive scenes seamlessly → a portable scrub engine that plays the whole
+chain as one flight.
+
+**The one rule that makes or breaks it:** seams must be *frame-identical*. Read
+[The seamless chain](#step-5--the-seamless-chain-the-critical-part) 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 full run is
+ roughly `N` image gens + `(2N-1)` video gens.
+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`.
+
+---
+
+## Step 1 — Interview the user
+
+Use **AskUserQuestion**. Ask only what you can't sensibly default. Cover:
+
+1. **Subject** — the industry/product and a one-line pitch (e.g. "a bubble tea company,
+ from leaf to last sip"). If they have a brand name, get it; otherwise propose one.
+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. **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.
+
+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.
+
+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>.
+```
+
+- 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.
+- A generation may fail transiently (HTTP 503) — re-roll that one individually; don't
+ restart the batch.
+- **Review the stills before continuing.** They must read as one cohesive world (same
+ angle, palette, light). If one is off-style, regenerate it, optionally passing an
+ approved scene as `--image` to lock style.
+
+See `references/pipeline.md` for the exact batch script.
+
+---
+
+## 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.
+
+These stills double as **video posters and lazy-load fallbacks**, so keep them.
+
+---
+
+## Step 4 — Generate the dive-in clips
+
+One camera flight per scene: starts high/outside, descends into the interior, structure
+opens. Model **`seedance_2_0`** (image-to-video), `--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 <scene> from outside … descend and fly inside toward <focal point> … the
+ roof/walls gently open to reveal the interior. <style>, smooth graceful slow motion.
+ No text." (Template in `references/prompts.md`.)
+- Params: `--mode std --resolution 1080p --aspect_ratio 16:9 --duration 8`. 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 — The seamless chain (THE CRITICAL PART)
+
+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):
+
+```bash
+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):
+
+```bash
+higgsfield generate create seedance_2_0 \
+ --prompt "$(cat connector_i.txt)" \
+ --start-image dive_i_last.png --end-image dive_next_first.png \
+ --mode std --resolution 1080p --aspect_ratio 16:9 --duration 5 --wait --json
+```
+
+Connector prompt: "Single continuous camera move, no cuts. Pull up and back out of
+<scene i>, 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.
+<style>. 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.
+
+---
+
+## 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.
+
+---
+
+## 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', clip:'assets/vid/farm.mp4',
+ 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 */],
+});
+```
+
+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. 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.
+
+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)
+
+Drive the page in a headless browser and **verify frame continuity at the seams**, which
+is the thing most likely to be wrong:
+
+- 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.
+- Check the console for errors, confirm `video.seekable.end(0) > 0` (blob working), and
+ that `currentTime` tracks scroll across each clip's band.
+- Check mobile (full-bleed `cover`) and reduced-motion (should fall back to the stills).
+
+---
+
+## Gotchas (hard-won)
+
+- **Seam pop** → connector endpoints were the diorama stills, not the neighbouring
+ clips' actual frames. Always extract real frames (Step 5).
+- **Frozen video / stuck at frame 0** → `seekable=[0,0]`; the host isn't serving byte
+ ranges. Use blob URLs (engine does).
+- **Huge files** → you used all-intra. Use `-g 8` + blob instead.
+- **Soft / low quality** → you downscaled or over-compressed. Encode native 1080p,
+ crf ≤ 20, add `unsharp`. Video is inherently softer than the stills — keep the stills
+ as the lite fallback for max fidelity.
+- **Concurrent gens 503 / "not_enough_credits" race** → transient when many launch at
+ once; re-roll the individual failure, it's not really out of credits (verify with
+ `higgsfield workspace list`).
+- **`--generate-audio` errors on seedance** → omit it; mute in HTML and `-an` on encode.
+- **White-box scenes** → `gpt_image_2` returns a solid bg; either match the page bg to it
+ or knock it out (Step 3).
+- **bash 3.2** on macOS → no associative arrays in scripts.
+
+## 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 (generate →
+ extract frames → connectors → encode), bash-3.2-safe.
+- `references/scrub-engine.js` — the portable, config-driven scrub engine (builds DOM +
+ injects CSS; blob-seek, lazy load, seam crossfade, copy, route rail, reduced-motion).
+- `references/index-template.html` — a minimal standalone page that mounts the engine.
+- `references/knockout.py` — border-connected background knockout for floating scenes.
diff --git a/plugins/scroll-world/skills/scroll-world/references/index-template.html b/plugins/scroll-world/skills/scroll-world/references/index-template.html
new file mode 100644
index 0000000..9f2d1c0
--- /dev/null
+++ b/plugins/scroll-world/skills/scroll-world/references/index-template.html
@@ -0,0 +1,63 @@
+<!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 — the world of SUBJECT</title>
+ <meta name="description" content="Scroll to fly through the world of BRAND." />
+ <style>
+ /* Theme the engine here. These match your generated scenes' background + palette. */
+ :root, .sw-root {
+ --sw-bg: #F5EDE0; /* == the scene background colour */
+ --sw-ink: #241d2b;
+ --sw-ink-soft: #6a6072;
+ --sw-accent: #9B7EBD; /* per-section accents override this at runtime */
+ }
+ </style>
+</head>
+<body>
+ <div id="top"></div>
+ <div id="world"></div>
+
+ <script src="scrub-engine.js"></script>
+ <script>
+ mountScrollWorld(document.getElementById('world'), {
+ brand: { name: 'BRAND', href: '#top' },
+ cta: { label: 'Order now', href: '#finale' },
+ hint: 'scroll to fly in',
+ diveScroll: 1.3,
+ connScroll: 0.9,
+ sections: [
+ // One object per scene, in order. `accent` colours the copy/route for that scene.
+ // First section is the hero (its copy greets on landing); last carries the CTA.
+ {
+ id: 'sceneA', label: 'Scene A',
+ still: 'assets/sceneA.webp', clip: 'assets/vid/sceneA.mp4',
+ accent: '#8FB98A',
+ eyebrow: 'Value prop label',
+ title: 'The hero line.',
+ body: 'One plain-spoken sentence about this stage.',
+ tags: ['Proof', 'Proof', 'Proof'],
+ },
+ // …middle scenes…
+ {
+ id: 'finale', label: 'The Product',
+ still: 'assets/product.webp', clip: 'assets/vid/finale.mp4',
+ accent: '#9B7EBD',
+ eyebrow: 'And it all pours into',
+ title: 'One perfect thing.',
+ body: 'The payoff sentence.',
+ tags: [],
+ cta: { primary: { label: 'Get started', href: '#' },
+ secondary: { label: 'See more', href: '#' } },
+ },
+ ],
+ // length === sections.length - 1, in order. Generated per SKILL.md Step 5.
+ connectors: [
+ 'assets/vid/conn1.mp4',
+ // 'assets/vid/conn2.mp4', …
+ ],
+ });
+ </script>
+</body>
+</html>
diff --git a/plugins/scroll-world/skills/scroll-world/references/knockout.py b/plugins/scroll-world/skills/scroll-world/references/knockout.py
new file mode 100644
index 0000000..7b3bb1d
--- /dev/null
+++ b/plugins/scroll-world/skills/scroll-world/references/knockout.py
@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+"""Border-connected background knockout for diorama stills.
+
+Removes the flat background of a scene image (leaving the diorama floating on
+transparency) via a flood fill from the borders over pixels near the corner
+colour. Interior regions that happen to match the background (e.g. cream walls
+inside the scene) are preserved because the fill only reaches border-connected
+pixels. The soft contact shadow is kept as a natural base.
+
+Usage:
+ python3 knockout.py scene1.png scene2.png ...
+ # writes scene1.rgba.png, scene2.rgba.png, ...
+ # optional: TOL env var (default 34) widens/narrows the bg match
+
+Then encode to webp with alpha, e.g.:
+ cwebp -q 84 -alpha_q 95 -resize 1800 0 scene1.rgba.png -o scene1.webp
+
+No numpy/ImageMagick needed — pure PIL. Pairs with SKILL.md Step 3.
+"""
+import os
+import sys
+from collections import deque
+from PIL import Image, ImageFilter
+
+TOL = float(os.environ.get("TOL", "34")) # RGB Euclidean distance counted as background
+
+
+def corner_color(im):
+ w, h = im.size
+ px = im.load()
+ pts = [(1, 1), (w - 2, 1), (1, h - 2), (w - 2, h - 2)]
+ r = sum(px[x, y][0] for x, y in pts) // 4
+ g = sum(px[x, y][1] for x, y in pts) // 4
+ b = sum(px[x, y][2] for x, y in pts) // 4
+ return (r, g, b)
+
+
+def knock(inp, outp):
+ im = Image.open(inp).convert("RGB")
+ w, h = im.size
+ px = im.load()
+ cr, cg, cb = corner_color(im)
+ tol2 = TOL * TOL
+
+ def is_bg(x, y):
+ r, g, b = px[x, y]
+ dr, dg, db = r - cr, g - cg, b - cb
+ return dr * dr + dg * dg + db * db <= tol2
+
+ bg = bytearray(w * h)
+ seen = bytearray(w * h)
+ dq = deque()
+ for x in range(w):
+ for y in (0, h - 1):
+ i = y * w + x
+ if not seen[i] and is_bg(x, y):
+ seen[i] = 1; bg[i] = 1; dq.append((x, y))
+ for y in range(h):
+ for x in (0, w - 1):
+ i = y * w + x
+ if not seen[i] and is_bg(x, y):
+ seen[i] = 1; bg[i] = 1; dq.append((x, y))
+ while dq:
+ x, y = dq.popleft()
+ for nx, ny in ((x + 1, y), (x - 1, y), (x, y + 1), (x, y - 1)):
+ if 0 <= nx < w and 0 <= ny < h:
+ i = ny * w + nx
+ if not seen[i]:
+ seen[i] = 1
+ if is_bg(nx, ny):
+ bg[i] = 1; dq.append((nx, ny))
+
+ alpha = Image.new("L", (w, h), 255)
+ ap = alpha.load()
+ for y in range(h):
+ base = y * w
+ for x in range(w):
+ if bg[base + x]:
+ ap[x, y] = 0
+ alpha = alpha.filter(ImageFilter.GaussianBlur(1.4)) # soften the threshold contour
+ out = im.convert("RGBA")
+ out.putalpha(alpha)
+ out.save(outp)
+ print("knocked", outp)
+
+
+if __name__ == "__main__":
+ for name in sys.argv[1:]:
+ knock(name, name.rsplit(".", 1)[0] + ".rgba.png")
diff --git a/plugins/scroll-world/skills/scroll-world/references/pipeline.md b/plugins/scroll-world/skills/scroll-world/references/pipeline.md
new file mode 100644
index 0000000..6f2652c
--- /dev/null
+++ b/plugins/scroll-world/skills/scroll-world/references/pipeline.md
@@ -0,0 +1,116 @@
+# Pipeline: copy-paste scripts (bash 3.2 safe)
+
+Set these once. `NAMES` is the ordered section ids; the last is the hero/finale.
+
+```bash
+WORK=/tmp/scroll-world # scratch dir for prompts, sources, frames
+ASSETS=./assets # where the site reads stills (webp) + clips (mp4)
+mkdir -p "$WORK" "$ASSETS/vid"
+NAMES="farm kitchen shop delivery plaza finale" # <-- your section ids, in order
+```
+
+Higgsfield generations take minutes — every `higgsfield ... --wait` call below is meant
+to run inside a **backgrounded** script. Launch the whole script with your tool's
+background/detached mode and poll the progress log; never block the foreground.
+
+## 1. Scene stills (Step 2)
+
+Write one prompt file per section to `$WORK/still_<name>.txt` (see prompts.md), then:
+
+```bash
+gen_still() { # name
+ higgsfield generate create gpt_image_2 --prompt "$(cat "$WORK/still_$1.txt")" \
+ --aspect_ratio 3:2 --resolution 2k --quality high --wait --wait-timeout 15m --json \
+ > "$WORK/still_$1.json" 2> "$WORK/still_$1.err"
+ url=$(jq -r '.[0].result_url // empty' "$WORK/still_$1.json")
+ [ -n "$url" ] && curl -fsSL "$url" -o "$WORK/still_$1.png" && echo "still $1 ok" || echo "still $1 FAIL"
+}
+for n in $NAMES; do gen_still "$n" & done ; wait
+```
+
+Convert to webp for the site (and optionally run knockout.py first for transparency):
+
+```bash
+for n in $NAMES; do cwebp -quiet -q 84 -resize 1800 0 "$WORK/still_$n.png" -o "$ASSETS/$n.webp"; done
+```
+
+Review the stills for cohesion before continuing. Re-roll any off-style one (optionally
+add `--image "$WORK/still_<good>.png"` to lock style).
+
+## 2. Dive-in clips (Step 4)
+
+Prompt files at `$WORK/dive_<name>.txt`. Start image = the solid-bg still PNG.
+
+```bash
+gen_dive() { # name
+ higgsfield generate create seedance_2_0 --prompt "$(cat "$WORK/dive_$1.txt")" \
+ --start-image "$WORK/still_$1.png" \
+ --mode std --resolution 1080p --aspect_ratio 16:9 --duration 8 \
+ --wait --wait-timeout 20m --json > "$WORK/dive_$1.json" 2> "$WORK/dive_$1.err"
+ url=$(jq -r '.[0].result_url // empty' "$WORK/dive_$1.json")
+ [ -n "$url" ] && curl -fsSL "$url" -o "$WORK/dive_$1.mp4" && echo "dive $1 ok" || echo "dive $1 FAIL"
+}
+for n in $NAMES; do gen_dive "$n" & done ; wait
+```
+
+Re-roll individual failures (503 / credit race are transient):
+`gen_dive shop` (just that one).
+
+## 3. Extract boundary frames — the seam handoff (Step 5)
+
+For each adjacent pair, the connector's start = dive_i's LAST frame, end = dive_{i+1}'s
+FIRST frame — extracted from the **rendered videos**, never the stills.
+
+```bash
+set -- $NAMES
+prev=""
+for n in "$@"; do
+ ffmpeg -v error -ss 0 -i "$WORK/dive_$n.mp4" -frames:v 1 -q:v 2 "$WORK/first_$n.png" # establishing
+ ffmpeg -v error -sseof -0.15 -i "$WORK/dive_$n.mp4" -frames:v 1 -q:v 2 "$WORK/last_$n.png" # interior
+done
+```
+
+## 4. Connector clips (Step 5)
+
+Prompt files at `$WORK/conn_<i>.txt` (i = 1..N-1). Iterate adjacent pairs:
+
+```bash
+gen_conn() { # i startPng endPng
+ higgsfield generate create seedance_2_0 --prompt "$(cat "$WORK/conn_$1.txt")" \
+ --start-image "$2" --end-image "$3" \
+ --mode std --resolution 1080p --aspect_ratio 16:9 --duration 5 \
+ --wait --wait-timeout 20m --json > "$WORK/conn_$1.json" 2> "$WORK/conn_$1.err"
+ url=$(jq -r '.[0].result_url // empty' "$WORK/conn_$1.json")
+ [ -n "$url" ] && curl -fsSL "$url" -o "$WORK/conn_$1.mp4" && echo "conn $1 ok" || echo "conn $1 FAIL"
+}
+set -- $NAMES ; i=0 ; prev=""
+for n in "$@"; do
+ if [ -n "$prev" ]; then i=$((i+1)); gen_conn "$i" "$WORK/last_$prev.png" "$WORK/first_$n.png" & fi
+ prev="$n"
+done ; wait
+```
+
+## 5. Encode everything for scrubbing (Step 6)
+
+Native 1080p, crf 20, GOP 8, light sharpen, no audio, faststart. Same for dives + connectors.
+
+```bash
+enc() { ffmpeg -v error -y -i "$1" -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 "$2"; echo "enc $2 $(du -h "$2"|cut -f1)"; }
+
+for n in $NAMES; do enc "$WORK/dive_$n.mp4" "$ASSETS/vid/$n.mp4"; done
+i=0; for f in "$WORK"/conn_*.mp4; do i=$((i+1)); enc "$f" "$ASSETS/vid/conn$i.mp4"; done
+```
+
+Now the engine config's `sections[k].clip = assets/vid/<name>.mp4` and
+`connectors = [assets/vid/conn1.mp4, …]` (length N-1, in order).
+
+## Notes
+
+- `.[0].result_url` is the field on the `--wait --json` job object. `.min_result_url` is
+ a lower-res preview if you ever want it.
+- If a whole batch stalls, check `higgsfield workspace list` for credits and
+ `$WORK/*.err` for the reason.
+- Concurrency: launching ~5–6 gens at once is fine; much more can trigger transient
+ credit/race errors — stagger or re-roll.
diff --git a/plugins/scroll-world/skills/scroll-world/references/prompts.md b/plugins/scroll-world/skills/scroll-world/references/prompts.md
new file mode 100644
index 0000000..412e34f
--- /dev/null
+++ b/plugins/scroll-world/skills/scroll-world/references/prompts.md
@@ -0,0 +1,94 @@
+# Prompt templates & intake
+
+Everything here is fill-in-the-slots. Keep the **style preamble** byte-for-byte identical
+across all scene stills — that identical text is what makes the world feel like one place.
+
+## Intake checklist (Step 1)
+
+Collect and write down:
+
+- `SUBJECT` — the business + one-line pitch.
+- `BRAND_NAME` — display name.
+- `PALETTE` — 4–6 named hexes, e.g. `taro #9B7EBD, cream #F5EDE0, caramel #C88A5A, matcha #8FB98A, plum #3A2E48`. Pick ONE as the scene **background** colour (usually the lightest) and one as the primary **accent**.
+- `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.
+
+## Style preamble (default: clay diorama)
+
+Reuse verbatim in every scene prompt. Swap the bracketed bits for the brand's palette/bg.
+
+```
+Isometric low-poly 3D diorama floating as a small rounded island on a plain solid
+[BG_HEX] background with a soft contact shadow beneath it. Soft matte clay 3D render,
+rounded toy-model shapes, gentle warm studio lighting, soft long shadows, tilt-shift
+miniature look. Cohesive color palette of [PALETTE]. Highly detailed, centered
+composition, absolutely no text, no letters, no numbers, no logos.
+```
+
+Alternate directions (swap the first two sentences, keep the palette/no-text tail):
+- **Flat papercraft:** "Isometric layered paper-craft diorama, matte cardstock, clean die-cut edges, subtle drop shadows between layers."
+- **Glossy toy:** "Isometric glossy vinyl-toy diorama, smooth plastic shading, soft rim light, collectible figurine look."
+- **Claymation:** "Isometric stop-motion clay set, visible thumbprints, handmade plasticine texture, soft studio softbox light."
+- **Neon night:** "Isometric miniature at night, warm interior glow and neon signage, moody rim light, wet reflective ground."
+
+## Scene still prompt (Step 2)
+
+```
+[STYLE PREAMBLE]
+Subject: [SECTION.subject — describe the miniature scene: the building/space, a few
+characters doing the work, the props that signal this stage of the business].
+```
+
+Tips:
+- Name concrete props (they anchor the scene): tanks, cauldrons, conveyor, crates, awning, string lights, benches, scooters, map pins.
+- For the final "hero product" section, drop the diorama-island framing and prompt a
+ single oversized product centerpiece floating on the same background with a few small
+ orbiting props.
+- Aspect `3:2`, `--resolution 2k --quality high`.
+
+## Dive-in clip prompt (Step 4)
+
+`--start-image = the scene still` (solid-bg version).
+
+```
+Single continuous cinematic camera move, no cuts. Begin high and far, looking down at the
+whole [SECTION.subject] from outside like a tiny model. The camera slowly glides forward
+and descends toward it, sweeping in toward [FOCAL POINT — the counter/the cauldrons/the
+people], as if flying inside. As the camera pushes in, the roof and upper structure
+gently lift and open away to reveal the warm interior. [STYLE tail: soft matte clay
+diorama, tilt-shift miniature, warm light, [PALETTE]]. Smooth, graceful, slow motion,
+subtle parallax. No text, no captions.
+```
+
+For scenes with no building to open (a field, a plaza, a road), replace the roof clause
+with "the camera flies low across [the scene] toward [focal point]."
+
+`--mode std --resolution 1080p --aspect_ratio 16:9 --duration 8`. No audio flag.
+
+## Connector clip prompt (Step 5)
+
+`--start-image = dive_i LAST frame` (extracted), `--end-image = dive_{i+1} FIRST frame`
+(extracted). Both from the RENDERED videos, not the stills.
+
+```
+Single continuous cinematic camera move, no cuts. The camera smoothly pulls up and back
+out of [SCENE i], rising into the sky, then glides forward across the connected miniature
+world and arrives above [SCENE i+1], beginning to descend toward it. One connected
+miniature clay world, seamless flowing aerial transition. [STYLE tail + PALETTE]. Smooth
+graceful slow motion. No text, no captions.
+```
+
+For the last connector into a hero-product finale: "…glides forward and the world
+dissolves toward a single giant [PRODUCT] floating in soft [BG] space, arriving in front
+of it."
+
+`--mode std --resolution 1080p --aspect_ratio 16:9 --duration 5`.
+
+## Copy per section (for the engine config)
+
+- `eyebrow` — 2–4 words, uppercase feel (a value-prop label).
+- `title` — 3–6 words, the beat's headline. First section = the site's hero line; last =
+ the payoff + it carries the CTA.
+- `body` — one sentence, plain-spoken, from the visitor's side.
+- `tags` — 0–3 short proof chips (e.g. "Fresh-cooked", "30-min delivery").
diff --git a/plugins/scroll-world/skills/scroll-world/references/scrub-engine.js b/plugins/scroll-world/skills/scroll-world/references/scrub-engine.js
new file mode 100644
index 0000000..c558e25
--- /dev/null
+++ b/plugins/scroll-world/skills/scroll-world/references/scrub-engine.js
@@ -0,0 +1,341 @@
+/* ============================================================================
+ scroll-world — portable scroll-scrubbed camera-flight engine
+ ----------------------------------------------------------------------------
+ Framework-agnostic. Vanilla JS, zero dependencies. It builds its own DOM and
+ injects its own (namespaced) CSS into a container you give it, so it drops into
+ plain HTML, Next.js (call from a ref/useEffect), Vue (onMounted), a server-
+ rendered page, anything.
+
+ USAGE
+ mountScrollWorld(document.getElementById('world'), {
+ brand: { name: 'Pearl & Co.', href: '#top' },
+ diveScroll: 1.3, // viewport-heights of scroll per dive clip
+ connScroll: 0.9, // ...per connector clip
+ hint: 'scroll to fly in',
+ nav: true, // show the top section nav
+ atmosphere: true, // subtle gradient + drifting particles behind the clips
+ sections: [
+ { id, label, still, clip, accent,
+ eyebrow, title, body, tags:[…],
+ cta:{ primary:{label,href}, secondary:{label,href} } }, // last section only
+ …
+ ],
+ connectors: [clipUrl, …], // length = sections.length - 1 (nulls allowed)
+ });
+
+ THEME (CSS custom properties; set on the container or :root to override)
+ --sw-bg page background (match your scene bg for seamless posters)
+ --sw-ink primary text
+ --sw-ink-soft secondary text
+ --sw-accent default accent (each section overrides via its `accent`)
+ --sw-font-display / --sw-font-body
+
+ REQUIREMENTS ON YOUR ASSETS
+ - clips encoded native-res, crf~20, -g 8, +faststart, no audio (see pipeline.md)
+ - connectors' endpoints are the neighbouring dives' ACTUAL frames (see SKILL Step 5)
+ The engine loads each clip as a Blob (always seekable) and scrubs currentTime; it does
+ NOT depend on HTTP byte-range support.
+ ========================================================================== */
+
+function mountScrollWorld(container, config) {
+ const reduce = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+ const SECTIONS = config.sections || [];
+ const CONNECTORS = config.connectors || [];
+ const DIVE_W = config.diveScroll || 1.3;
+ const CONN_W = config.connScroll || 0.9;
+ const N = SECTIONS.length;
+ if (!N) return;
+
+ injectCSS();
+ container.classList.add('sw-root');
+
+ // ---- build the interleaved segment chain: dive0, conn0, dive1, … diveN-1 ----
+ const SEGMENTS = [];
+ SECTIONS.forEach((s, i) => {
+ const dive = { kind: 'dive', si: i, clip: s.clip, still: s.still, accent: s.accent, w: DIVE_W };
+ SEGMENTS.push(dive);
+ s._seg = dive;
+ if (i < N - 1) {
+ SEGMENTS.push({ kind: 'conn', si: i, clip: CONNECTORS[i] || null,
+ still: SECTIONS[i + 1].still, accent: SECTIONS[i + 1].accent, w: CONN_W });
+ }
+ });
+ const NSEG = SEGMENTS.length;
+
+ // ---- DOM ----
+ const sky = el('div', 'sw-sky');
+ if (config.atmosphere !== false) {
+ sky.appendChild(el('div', 'sw-sky__grad'));
+ sky.appendChild(el('div', 'sw-sky__glow'));
+ }
+ const particles = el('div', 'sw-particles'); sky.appendChild(particles);
+
+ const scrollbar = el('div', 'sw-scrollbar');
+ const scrollbarFill = el('span'); scrollbar.appendChild(scrollbarFill);
+
+ const topbar = el('div', 'sw-topbar');
+ if (config.brand) {
+ const brand = el('a', 'sw-brand'); brand.href = (config.brand.href || '#');
+ brand.appendChild(el('span', 'sw-brand__mark'));
+ const nm = el('span', 'sw-brand__name'); nm.textContent = config.brand.name || ''; brand.appendChild(nm);
+ topbar.appendChild(brand);
+ }
+ const nav = el('nav', 'sw-nav'); if (config.nav !== false) topbar.appendChild(nav);
+ if (config.cta && config.cta.label) {
+ const c = el('a', 'sw-topcta'); c.href = config.cta.href || '#'; c.textContent = config.cta.label;
+ topbar.appendChild(c);
+ }
+
+ const stage = el('div', 'sw-stage');
+ const copylayer = el('div', 'sw-copylayer');
+ const route = el('div', 'sw-route');
+ const hint = el('div', 'sw-hint');
+ const hintText = el('span'); hintText.textContent = config.hint || 'scroll'; hint.appendChild(hintText);
+ hint.appendChild(el('i'));
+ const track = el('div', 'sw-track');
+
+ [sky, scrollbar, topbar, stage, copylayer, route, hint, track].forEach(n => container.appendChild(n));
+
+ // segment scenes
+ SEGMENTS.forEach(s => {
+ const scene = el('div', 'sw-scene'); scene.style.setProperty('--sw-accent', s.accent || '');
+ const img = el('img', 'sw-scene__still'); img.alt = ''; img.decoding = 'async'; img.loading = 'lazy';
+ if (s.still) img.src = s.still;
+ scene.appendChild(img); stage.appendChild(scene);
+ s.el = scene; s.img = img; s.video = null; s.hasClip = false;
+ s.loading = false; s.ready = false; s.cur = 0; s.target = 0; s.visible = false;
+ });
+
+ // per-section copy / route / nav
+ const copies = [], dots = [];
+ SECTIONS.forEach((s, i) => {
+ const c = el('article', 'sw-copy'); c.style.setProperty('--sw-accent', s.accent || '');
+ c.innerHTML =
+ `<span class="sw-copy__num">${pad(i + 1)} / ${pad(N)}</span>` +
+ (s.eyebrow ? `<span class="sw-copy__eyebrow">${esc(s.eyebrow)}</span>` : '') +
+ (s.title ? `<h2 class="sw-copy__title">${esc(s.title)}</h2>` : '') +
+ (s.body ? `<p class="sw-copy__body">${esc(s.body)}</p>` : '') +
+ (s.tags && s.tags.length ? `<ul class="sw-copy__tags">${s.tags.map(t => `<li>${esc(t)}</li>`).join('')}</ul>` : '') +
+ (s.cta ? `<div class="sw-copy__cta">${ctaBtns(s.cta)}</div>` : '');
+ copylayer.appendChild(c); copies.push(c);
+
+ const dot = el('button', 'sw-route__dot'); dot.style.setProperty('--sw-accent', s.accent || '');
+ dot.innerHTML = `<span class="sw-route__label">${esc(s.label || '')}</span><i></i>`;
+ dot.addEventListener('click', () => jumpTo(i)); route.appendChild(dot); dots.push(dot);
+
+ if (config.nav !== false) {
+ const b = el('button', 'sw-nav__item'); b.textContent = s.label || '';
+ b.addEventListener('click', () => jumpTo(i)); nav.appendChild(b);
+ }
+ });
+
+ // ---- math ----
+ const clamp = (x, a = 0, b = 1) => Math.min(b, Math.max(a, x));
+ const smooth = x => { x = clamp(x); return x * x * (3 - 2 * x); };
+ let vh = window.innerHeight, stageX = 0, totalW = 0, activeIndex = -1, ticking = false;
+
+ function layout() {
+ vh = window.innerHeight;
+ stageX = window.innerWidth > 860 ? 4 : 0;
+ let off = 0;
+ SEGMENTS.forEach(s => { s.start = off * vh; off += s.w; s.end = off * vh; });
+ totalW = off;
+ track.style.height = (totalW * vh + vh) + 'px'; // +1vh so the last flight completes
+ read();
+ }
+
+ function jumpTo(i) {
+ const seg = SECTIONS[i]._seg;
+ window.scrollTo({ top: seg.start + (seg.end - seg.start) * 0.5, behavior: reduce ? 'auto' : 'smooth' });
+ }
+
+ function loadClip(s) {
+ if (s.loading || !s.clip) return;
+ s.loading = true;
+ fetch(s.clip).then(r => r.ok ? r.blob() : Promise.reject(new Error('404')))
+ .then(blob => {
+ const v = document.createElement('video');
+ v.className = 'sw-scene__video';
+ v.muted = true; v.playsInline = true; v.preload = 'auto';
+ v.setAttribute('muted', ''); v.setAttribute('playsinline', '');
+ v.src = URL.createObjectURL(blob);
+ v.addEventListener('loadedmetadata', () => { s.ready = true; s.el.classList.add('has-clip'); read(); });
+ v.addEventListener('loadeddata', () => { try { v.pause(); } catch (e) {} });
+ s.el.appendChild(v); s.video = v; s.hasClip = true;
+ }).catch(() => { s.loading = false; });
+ }
+
+ function read() {
+ const y = window.scrollY || window.pageYOffset;
+ const fade = 0.12 * vh;
+ let ci = 0;
+ for (let i = 0; i < NSEG; i++) if (y >= SEGMENTS[i].start) ci = i;
+
+ for (let i = 0; i < NSEG; i++) {
+ const s = SEGMENTS[i];
+ if (y > s.start - 1.6 * vh && y < s.end + 1.6 * vh) loadClip(s);
+ const local = clamp((y - s.start) / (s.end - s.start), 0, 1);
+ s.target = local;
+ let outside = 0;
+ if (y < s.start) outside = s.start - y; else if (y > s.end) outside = y - s.end;
+ const op = smooth(1 - outside / fade);
+ s.el.style.opacity = op; s.visible = op > 0.001;
+ s.el.style.zIndex = (i === ci) ? '120' : String(100 + Math.round(op * 10));
+ if (!s.hasClip || !s.ready) {
+ const sc = reduce ? 1 : 1.03 + local * 0.14;
+ s.img.style.transform = `translateX(${stageX - 2}vw) scale(${sc.toFixed(3)})`;
+ }
+ }
+
+ for (let i = 0; i < N; i++) {
+ const seg = SECTIONS[i]._seg;
+ const pr = clamp((y - seg.start) / (seg.end - seg.start), 0, 1);
+ const before = y < seg.start, after = y > seg.end;
+ let cop;
+ if (i === 0) cop = after ? 0 : smooth(1 - pr / 0.62); // greets on landing
+ else if (i === N - 1) cop = before ? 0 : smooth(pr / 0.4); // holds CTA at the end
+ else cop = (before || after) ? 0 : smooth(1 - Math.abs(pr - 0.5) / 0.5);
+ const c = copies[i];
+ c.style.opacity = cop;
+ c.style.transform = reduce ? 'none' : `translateY(${(0.5 - pr) * 4}vh)`;
+ c.style.pointerEvents = cop > 0.5 ? 'auto' : 'none';
+ }
+
+ const cur = SEGMENTS[ci];
+ const near = clamp(cur.kind === 'dive' ? cur.si
+ : (((y - cur.start) / (cur.end - cur.start)) > 0.5 ? cur.si + 1 : cur.si), 0, N - 1);
+ if (near !== activeIndex) {
+ activeIndex = near;
+ dots.forEach((d, k) => d.classList.toggle('is-active', k === near));
+ nav.querySelectorAll('.sw-nav__item').forEach((n, k) => n.classList.toggle('is-active', k === near));
+ container.style.setProperty('--sw-accent', SECTIONS[near].accent || '');
+ }
+ scrollbarFill.style.transform = `scaleX(${clamp(y / (totalW * vh))})`;
+ hint.style.opacity = clamp(1 - y / (0.5 * vh));
+ if (particles) particles.style.transform = `translate3d(0, ${-y * 0.05}px, 0)`;
+ ticking = false;
+ }
+
+ function raf() {
+ for (let i = 0; i < NSEG; i++) {
+ const s = SEGMENTS[i];
+ if (!s.hasClip || !s.ready || !s.video) continue;
+ if (!s.visible && Math.abs(s.cur - s.target) < 0.002) continue;
+ s.cur += (s.target - s.cur) * (reduce ? 1 : 0.18);
+ const dur = s.video.duration || 1;
+ const t = clamp(s.cur, 0, 0.999) * dur;
+ if (Math.abs(s.video.currentTime - t) > 0.008) { try { s.video.currentTime = t; } catch (e) {} }
+ }
+ requestAnimationFrame(raf);
+ }
+
+ seedParticles(particles, reduce);
+ window.addEventListener('scroll', () => { if (!ticking) { ticking = true; requestAnimationFrame(read); } }, { passive: true });
+ window.addEventListener('resize', layout);
+ window.addEventListener('orientationchange', layout);
+ window.addEventListener('load', layout);
+ layout();
+ requestAnimationFrame(raf);
+
+ // ---- helpers ----
+ function el(tag, cls) { const n = document.createElement(tag); if (cls) n.className = cls; return n; }
+ function pad(n) { return String(n).padStart(2, '0'); }
+ function esc(s) { return String(s).replace(/[&<>"]/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c])); }
+ function ctaBtns(cta) {
+ let h = '';
+ if (cta.primary) h += `<a class="sw-btn sw-btn--primary" href="${esc(cta.primary.href || '#')}">${esc(cta.primary.label)}</a>`;
+ if (cta.secondary) h += `<a class="sw-btn sw-btn--ghost" href="${esc(cta.secondary.href || '#')}">${esc(cta.secondary.label)}</a>`;
+ return h;
+ }
+}
+
+function seedParticles(host, reduce) {
+ if (!host || reduce) return;
+ const kinds = ['dot', 'dot', 'ring'];
+ const seeds = [7, 23, 41, 58, 71, 88, 12, 34, 52, 66, 83, 95, 18, 29, 47, 63, 77, 91, 5, 38, 55, 69, 82, 97];
+ for (let k = 0; k < 20; k++) {
+ const s = document.createElement('span');
+ s.className = 'sw-pt sw-pt--' + kinds[k % kinds.length];
+ s.style.left = seeds[k % seeds.length] + 'vw';
+ s.style.top = ((seeds[(k * 3) % seeds.length] * 1.3) % 100) + 'vh';
+ s.style.setProperty('--sw-sc', (0.5 + ((seeds[(k * 5) % seeds.length] % 60) / 60) * 1.1).toFixed(2));
+ const dur = 14 + (seeds[(k * 7) % seeds.length] % 22);
+ s.style.animationDuration = dur + 's';
+ s.style.animationDelay = (-(seeds[(k * 2) % seeds.length] % dur)) + 's';
+ host.appendChild(s);
+ }
+}
+
+function injectCSS() {
+ if (document.getElementById('sw-css')) return;
+ const css = `
+ .sw-root{--sw-bg:#F5EDE0;--sw-ink:#241d2b;--sw-ink-soft:#6a6072;--sw-accent:#8a7bb5;
+ --sw-font-display:ui-rounded,"SF Pro Rounded","Segoe UI",system-ui,sans-serif;
+ --sw-font-body:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,system-ui,sans-serif;
+ color:var(--sw-ink);font-family:var(--sw-font-body);}
+ html,body{margin:0;background:var(--sw-bg,#F5EDE0);overflow-x:hidden;}
+ .sw-sky{position:fixed;inset:0;z-index:0;overflow:hidden;pointer-events:none;background:var(--sw-bg);}
+ .sw-sky__grad{position:absolute;inset:-10%;background:linear-gradient(178deg,color-mix(in srgb,var(--sw-accent) 12%,var(--sw-bg)) 0%,var(--sw-bg) 55%,color-mix(in srgb,var(--sw-accent) 6%,var(--sw-bg)) 100%);}
+ .sw-sky__glow{position:absolute;inset:0;background:radial-gradient(60% 42% at 74% 16%,color-mix(in srgb,var(--sw-accent) 22%,transparent),transparent 70%),radial-gradient(46% 34% at 50% 50%,color-mix(in srgb,#fff 45%,transparent),transparent 70%);}
+ .sw-particles{position:absolute;inset:-6% -2%;will-change:transform;}
+ .sw-pt{position:absolute;width:13px;height:13px;transform:scale(var(--sw-sc,1));opacity:0;animation:sw-drift linear infinite;}
+ .sw-pt::before{content:"";position:absolute;inset:0;border-radius:50%;}
+ .sw-pt--dot::before{background:radial-gradient(circle at 34% 30%,color-mix(in srgb,var(--sw-accent) 60%,#000),#000 82%);}
+ .sw-pt--ring::before{background:transparent;border:2px solid color-mix(in srgb,var(--sw-accent) 55%,transparent);}
+ @keyframes sw-drift{0%{opacity:0;transform:scale(var(--sw-sc)) translate(0,12vh) rotate(0)}12%{opacity:.5}88%{opacity:.45}100%{opacity:0;transform:scale(var(--sw-sc)) translate(4vw,-22vh) rotate(210deg)}}
+ .sw-scrollbar{position:fixed;top:0;left:0;right:0;height:3px;z-index:60;background:color-mix(in srgb,var(--sw-accent) 14%,transparent);}
+ .sw-scrollbar span{display:block;height:100%;width:100%;transform-origin:0 50%;transform:scaleX(0);background:var(--sw-accent);}
+ .sw-topbar{position:fixed;top:0;left:0;right:0;z-index:50;display:flex;align-items:center;justify-content:space-between;gap:16px;padding:clamp(14px,2.4vw,26px) clamp(18px,5vw,64px);}
+ .sw-brand{display:flex;align-items:center;gap:10px;text-decoration:none;color:var(--sw-ink);}
+ .sw-brand__mark{width:24px;height:28px;border-radius:7px 7px 10px 10px;background:linear-gradient(160deg,var(--sw-accent),color-mix(in srgb,var(--sw-accent) 60%,#000));box-shadow:0 6px 14px color-mix(in srgb,var(--sw-accent) 40%,transparent);}
+ .sw-brand__name{font-family:var(--sw-font-display);font-weight:700;font-size:1.1rem;}
+ .sw-nav{display:flex;gap:4px;padding:5px;background:color-mix(in srgb,#fff 55%,transparent);backdrop-filter:blur(10px);border:1px solid color-mix(in srgb,var(--sw-accent) 16%,transparent);border-radius:999px;}
+ .sw-nav__item{font:inherit;font-size:.82rem;color:var(--sw-ink-soft);border:0;background:transparent;cursor:pointer;padding:7px 14px;border-radius:999px;transition:color .25s,background .25s;}
+ .sw-nav__item:hover{color:var(--sw-ink);} .sw-nav__item.is-active{color:#fff;background:var(--sw-accent);}
+ .sw-topcta{text-decoration:none;font-weight:600;font-size:.9rem;color:#fff;background:var(--sw-ink);padding:10px 20px;border-radius:999px;white-space:nowrap;}
+ .sw-stage{position:fixed;inset:0;z-index:10;pointer-events:none;}
+ .sw-scene{position:absolute;inset:0;opacity:0;overflow:hidden;will-change:opacity;}
+ .sw-scene__video,.sw-scene__still{position:absolute;inset:0;width:100%;height:100%;object-fit:cover;object-position:center 42%;}
+ .sw-scene__still{will-change:transform;} .sw-scene.has-clip .sw-scene__still{opacity:0;} .sw-scene__video{z-index:1;}
+ .sw-copylayer{position:fixed;inset:0;z-index:20;pointer-events:none;}
+ .sw-copylayer::before{content:"";position:absolute;inset:0;width:min(58vw,780px);background:linear-gradient(90deg,var(--sw-bg) 0%,color-mix(in srgb,var(--sw-bg) 82%,transparent) 34%,color-mix(in srgb,var(--sw-bg) 40%,transparent) 62%,transparent 100%);}
+ .sw-copy{position:absolute;left:clamp(18px,5vw,64px);top:50%;transform:translateY(-50%);width:min(42vw,460px);opacity:0;will-change:opacity,transform;}
+ .sw-copy__num{font-family:ui-monospace,Menlo,monospace;font-size:.74rem;letter-spacing:.12em;color:var(--sw-ink-soft);}
+ .sw-copy__eyebrow{display:block;margin-top:18px;font-family:var(--sw-font-display);font-weight:700;font-size:.8rem;letter-spacing:.16em;text-transform:uppercase;color:var(--sw-accent);}
+ .sw-copy__title{font-family:var(--sw-font-display);font-weight:700;color:var(--sw-ink);font-size:clamp(2rem,4.4vw,3.5rem);line-height:1.03;margin:12px 0 0;letter-spacing:-.01em;text-shadow:0 2px 20px color-mix(in srgb,var(--sw-bg) 70%,transparent);}
+ .sw-copy__body{margin-top:18px;font-size:clamp(1rem,1.25vw,1.14rem);line-height:1.55;color:color-mix(in srgb,var(--sw-ink) 78%,var(--sw-ink-soft));max-width:40ch;text-shadow:0 1px 12px color-mix(in srgb,var(--sw-bg) 90%,transparent);}
+ .sw-copy__tags{list-style:none;display:flex;flex-wrap:wrap;gap:8px;margin:24px 0 0;padding:0;}
+ .sw-copy__tags li{font-size:.82rem;font-weight:600;color:color-mix(in srgb,var(--sw-accent) 70%,#000);padding:7px 14px;border-radius:999px;background:color-mix(in srgb,var(--sw-accent) 14%,#fff);border:1px solid color-mix(in srgb,var(--sw-accent) 30%,transparent);}
+ .sw-copy__cta{display:flex;flex-wrap:wrap;gap:12px;margin-top:28px;pointer-events:auto;}
+ .sw-btn{text-decoration:none;font-weight:600;font-size:.95rem;padding:13px 24px;border-radius:999px;transition:transform .2s;}
+ .sw-btn--primary{color:#fff;background:var(--sw-ink);} .sw-btn--primary:hover{transform:translateY(-2px);}
+ .sw-btn--ghost{color:var(--sw-ink);border:1.5px solid color-mix(in srgb,var(--sw-ink) 25%,transparent);} .sw-btn--ghost:hover{transform:translateY(-2px);}
+ .sw-route{position:fixed;right:clamp(14px,2.4vw,30px);top:50%;z-index:40;transform:translateY(-50%);display:flex;flex-direction:column;gap:22px;padding:18px 10px;}
+ .sw-route::before{content:"";position:absolute;left:50%;top:22px;bottom:22px;width:2px;transform:translateX(-50%);background:var(--sw-accent);opacity:.28;}
+ .sw-route__dot{position:relative;border:0;background:transparent;cursor:pointer;width:14px;height:14px;display:grid;place-items:center;}
+ .sw-route__dot i{width:9px;height:9px;border-radius:50%;background:color-mix(in srgb,var(--sw-accent) 40%,transparent);transition:transform .3s,background .3s,box-shadow .3s;}
+ .sw-route__dot:hover i{transform:scale(1.25);background:var(--sw-accent);}
+ .sw-route__dot.is-active i{background:var(--sw-accent);transform:scale(1.4);box-shadow:0 0 0 5px color-mix(in srgb,var(--sw-accent) 22%,transparent);}
+ .sw-route__label{position:absolute;right:24px;top:50%;transform:translateY(-50%) translateX(6px);white-space:nowrap;font-size:.78rem;font-weight:600;color:var(--sw-ink);background:color-mix(in srgb,#fff 85%,transparent);backdrop-filter:blur(6px);padding:5px 11px;border-radius:999px;opacity:0;pointer-events:none;transition:opacity .25s,transform .25s;border:1px solid color-mix(in srgb,var(--sw-accent) 14%,transparent);}
+ .sw-route__dot:hover .sw-route__label,.sw-route__dot.is-active .sw-route__label{opacity:1;transform:translateY(-50%) translateX(0);}
+ .sw-hint{position:fixed;left:50%;bottom:26px;z-index:30;transform:translateX(-50%);display:flex;flex-direction:column;align-items:center;gap:10px;font-size:.76rem;letter-spacing:.14em;text-transform:uppercase;color:var(--sw-ink-soft);transition:opacity .3s;}
+ .sw-hint i{width:22px;height:34px;border-radius:12px;border:2px solid color-mix(in srgb,var(--sw-ink) 28%,transparent);position:relative;}
+ .sw-hint i::after{content:"";position:absolute;left:50%;top:7px;width:4px;height:7px;border-radius:2px;background:var(--sw-accent);transform:translateX(-50%);animation:sw-wheel 1.7s ease-in-out infinite;}
+ @keyframes sw-wheel{0%{opacity:0;top:6px}40%{opacity:1}100%{opacity:0;top:17px}}
+ .sw-track{position:relative;z-index:1;width:100%;pointer-events:none;}
+ @media (max-width:860px){
+ .sw-nav{display:none;}
+ .sw-copylayer::before{width:100%;height:60%;top:auto;bottom:0;background:linear-gradient(0deg,var(--sw-bg) 8%,color-mix(in srgb,var(--sw-bg) 70%,transparent) 46%,transparent 100%);}
+ .sw-copy{left:clamp(18px,5vw,64px);right:clamp(18px,5vw,64px);top:auto;bottom:clamp(64px,14vh,120px);transform:none;width:auto;max-width:560px;}
+ .sw-copy__body{max-width:none;} .sw-scene__video,.sw-scene__still{object-position:center 46%;}
+ .sw-route{gap:16px;right:8px;} .sw-route__label{display:none;}
+ }
+ @media (prefers-reduced-motion:reduce){ .sw-hint i::after{animation:none;} .sw-pt{display:none;} }
+ `;
+ const style = document.createElement('style'); style.id = 'sw-css'; style.textContent = css;
+ document.head.appendChild(style);
+}
+
+// Expose for module + global use.
+if (typeof module !== 'undefined' && module.exports) module.exports = { mountScrollWorld };
+if (typeof window !== 'undefined') window.mountScrollWorld = mountScrollWorld;