mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-11-17 04:11:35 +00:00
Optional skill: scroll-as-timeline landing pages on a deterministic CSS/JS engine, with interview → page grammar → signature move workflow and screenshot-based scroll verification. Engine and scripts vendored verbatim; asset generation re-anchored on image_generate with the upstream kie.ai flow kept as an optional path.
349 lines
16 KiB
Markdown
349 lines
16 KiB
Markdown
# Worldflight: the continuous-world page mode
|
||
|
||
Act mode cuts the page into pinned blocks. That is the right shape for a page of
|
||
chapters and the wrong shape for one unbroken camera move, and building a
|
||
continuous world out of acts produces exactly the page an owner described as
|
||
"awful": you scroll down, the stage unsticks, a static page slides past, clean
|
||
horizontal edges travel up the screen, and then you start scrolling down again.
|
||
Every one of those defects is the same defect. A pinned act is a block in the
|
||
document, and a document made of blocks has seams.
|
||
|
||
Worldflight removes the seams by removing the blocks.
|
||
|
||
There is **one** `position: fixed` stage for the whole page. Every leg of the
|
||
flight is mounted in it at once and stays mounted. The only element in document
|
||
flow is an empty spacer. Scroll drives two things and nothing else: the film
|
||
timeline and the opacity of the overlay. Nothing travels, nothing pins, nothing
|
||
unpins, and there is no boundary anywhere for a seam to show at.
|
||
|
||
---
|
||
|
||
## 1. The markup
|
||
|
||
```html
|
||
<div data-sc-mode="worldflight" data-sc-seam="0.12">
|
||
|
||
<div data-sc-world>
|
||
<div data-sc-segment data-sc-w="0.95" data-sc-linger="0.3"
|
||
data-sc-waypoint="Surface">
|
||
<img class="sc-world__poster" src="assets/p1.webp" alt="" decoding="async">
|
||
<video data-sc-src="assets/leg1.mp4"
|
||
data-sc-src-mobile="assets/leg1-m.mp4"></video>
|
||
</div>
|
||
<div data-sc-segment data-sc-w="0.9" data-sc-linger="0.42"
|
||
data-sc-waypoint="Thermocline">
|
||
<img class="sc-world__poster" src="assets/p2.webp" alt="" decoding="async">
|
||
<video data-sc-src="assets/leg2.mp4"
|
||
data-sc-src-mobile="assets/leg2-m.mp4"></video>
|
||
</div>
|
||
<!-- legs in flight order, as many as the world has -->
|
||
</div>
|
||
|
||
<div data-sc-world-copy>
|
||
<div class="sc-world__scrim sc-scrim sc-scrim--band"></div>
|
||
<div class="sc-copy sc-copy--lead" data-sc-copy data-sc-window="hero"> … </div>
|
||
<div class="sc-copy sc-copy--trail" data-sc-copy data-sc-window="0.38 0.66"> … </div>
|
||
<div class="sc-copy sc-copy--lead" data-sc-copy data-sc-window="finale"> … </div>
|
||
</div>
|
||
|
||
<div data-sc-spacer aria-hidden="true"></div>
|
||
</div>
|
||
```
|
||
|
||
`ScrollCraft.mount(document)` as usual. The mode composes with nothing else on
|
||
the page: a worldflight page has no acts.
|
||
|
||
### Attributes
|
||
|
||
| Attribute | On | Default | What it does |
|
||
|---|---|---|---|
|
||
| `data-sc-mode="worldflight"` | mode root | n/a | Turns the page into one flight. |
|
||
| `data-sc-seam` | mode root | `0.12` | Crossfade band, in viewport-heights of scroll. Clamped 0.02 to 0.4. |
|
||
| `data-sc-world` | stage | n/a | The single fixed stage. Gets `.sc-world`. |
|
||
| `data-sc-segment` | leg | n/a | One leg. Holds a poster and a clip. |
|
||
| `data-sc-w` | leg | `1.3` | Scroll this leg owns, in viewport-heights. |
|
||
| `data-sc-linger` | leg | `0` | Dwell remap for this leg only. Clamped to 0.6. |
|
||
| `data-sc-waypoint` | leg | n/a | Label published on the waypoint event. |
|
||
| `data-sc-world-copy` | copy layer | n/a | Fixed overlay. Gets `.sc-world__copy`. |
|
||
| `data-sc-copy` | copy block | n/a | A windowed block of type. |
|
||
| `data-sc-window` | copy block | n/a | `hero` \| `finale` \| `from to [in [out]]`. |
|
||
| `data-sc-spacer` | spacer | n/a | The scroll track. Engine sets its height. |
|
||
| `data-sc-lerp` | root or `<video>` | `0.18` | Playhead smoothing. See devices.md. |
|
||
|
||
The engine generates no DOM here, the same as in act mode. It sets the spacer's
|
||
height, and it writes opacity, visibility and z-index on the legs. Everything
|
||
else is markup you wrote.
|
||
|
||
---
|
||
|
||
## 2. The scroll track
|
||
|
||
The spacer's height is **(sum of the leg weights + 1) viewport-heights**, set in
|
||
pixels so it and the stage are measured on the same ruler (the stage is sized in
|
||
`svh`, and on a phone `vh` and `svh` are different numbers).
|
||
|
||
The `+ 1` is not padding. Without it the track ends at the exact scroll position
|
||
where the last leg reaches progress 1, so the final second of the last clip is a
|
||
place the reader can never come to rest. One extra viewport gives the last
|
||
flight room to land.
|
||
|
||
Position along the track, `t`, is measured in viewport-heights, which is the
|
||
same unit the weights are written in. Leg *i* owns `[c_i, c_i + w_i)`, and its
|
||
local progress is `(t - c_i) / w_i`, remapped through `lingerEase`.
|
||
|
||
---
|
||
|
||
## 3. The seam
|
||
|
||
Two things make a boundary between clips invisible, and both are required.
|
||
|
||
**The assets have to match at the seam** (section 6). The engine cannot fix a
|
||
mismatched cut.
|
||
|
||
**The crossfade has to be one-sided.** Over the seam band the incoming leg fades
|
||
up from 0 to 1 while the outgoing leg holds at full strength underneath it, and
|
||
the outgoing leg only drops to zero once it is completely covered. Fading both
|
||
sides at once puts the page ground through the middle of every seam, which reads
|
||
as a flash, and it is the obvious implementation. z-index favours the current
|
||
leg (120) over the rest (100 + opacity × 10).
|
||
|
||
Each side of the band is half a seam width, so each leg holds its seam frame for
|
||
about 0.06vh of scroll. Those are exactly the frames the seam law matched, so a
|
||
held frame there is invisible by construction.
|
||
|
||
Nothing ever swaps a `src`. A src swap is a black frame, and a black frame is
|
||
the cut this mode exists to remove.
|
||
|
||
---
|
||
|
||
## 4. The copy contract
|
||
|
||
Copy lives in one fixed layer above the stage. Each block declares a window
|
||
against the **whole track**, not against a leg.
|
||
|
||
- `data-sc-window="hero"`: present from the first pixel, fades out by 0.62 of
|
||
the first leg. A hero that fades IN has to fade in over an empty first screen,
|
||
which is the one moment on the page with nothing else to look at.
|
||
- `data-sc-window="finale"`: fades in from 0.4 of the last leg and holds to the
|
||
end.
|
||
- `data-sc-window="0.38 0.66"`: a plateau window across those track fractions:
|
||
ramps in over the first 30%, holds at full opacity, ramps out over the last
|
||
30%. Add a third and fourth number to set the ramps yourself. The plateau is
|
||
not decoration: a pure triangle touches opacity 1 for one instant, so the
|
||
reader has to stop on exactly the right pixel to see the line at full strength
|
||
and every heading reads slightly faded.
|
||
|
||
**The only transform on the copy side is `translateY`, and it is capped at 4vh
|
||
across the whole window** (from +2vh to -2vh). Anything larger stops reading as
|
||
a layer over a moving world and starts reading as a second page scrolling at a
|
||
different speed, which is the cheapness this mode replaces. Pointer events are
|
||
handed back to a block only above opacity 0.5.
|
||
|
||
`.sc-world__scrim` is provided for a scrim div on the copy side. Shape it to
|
||
where the copy actually sits. The stock `.sc-scrim--band` tops out at 58% of the
|
||
frame, and footage that stays bright past that will fail the contrast pass even
|
||
though the page looks fine.
|
||
|
||
---
|
||
|
||
## 5. The route rail
|
||
|
||
The engine publishes the current leg index as `--sc-seg` and its local progress
|
||
as `--sc-segp`, on the mode root and on `:root`, and fires a `sc:waypoint`
|
||
CustomEvent (bubbling, `detail: { index, count, label, el, progress }`) whenever
|
||
the leg changes.
|
||
|
||
It renders no rail. A gauge, a map, a depth readout, a leg counter and a set of
|
||
chapter dots are all the same two numbers, and a runtime that ships one of them
|
||
ships it to every page that uses this mode. Build the rail in the page:
|
||
|
||
```js
|
||
addEventListener('sc:waypoint', (e) => {
|
||
document.querySelectorAll('.rail__leg').forEach((el) => {
|
||
el.setAttribute('aria-current', String(+el.dataset.leg === e.detail.index));
|
||
});
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
## 6. The seam law for assets
|
||
|
||
A worldflight is only as good as the joins between its clips. Two architectures
|
||
work; nothing else does.
|
||
|
||
**Architecture A (preferred): chain on start images only.** Each leg is
|
||
generated from a start image and left to end wherever it ends. The next leg's
|
||
start image is a frame pulled from the previous leg's **encoded** mp4. Never
|
||
force an end-image wide shot: an image-to-image model asked to hit both ends
|
||
resolves the conflict by pulling the camera back, and every leg ends up as the
|
||
same wide establishing shot.
|
||
|
||
**Architecture B: connector legs.** Where two existing clips have to meet, cut a
|
||
short connector whose start frame comes from the previous leg and whose end
|
||
frame is the next leg's actual first frame.
|
||
|
||
Extract from the ENCODED mp4, not the source render. The encode changes the
|
||
pixels, and a poster or a chain frame taken from the pre-encode master does not
|
||
match the frame the browser will actually decode:
|
||
|
||
```bash
|
||
# last frame of the previous leg, as the next leg's start image
|
||
ffmpeg -sseof -0.15 -i legN.mp4 -frames:v 1 -q:v 2 chainN.png
|
||
# first frame of a leg, for its poster
|
||
ffmpeg -i legN.mp4 -frames:v 1 -q:v 3 pN.webp
|
||
```
|
||
|
||
### Encoding
|
||
|
||
Same rules as any scrub clip, and they matter more here because a worldflight
|
||
has more of them mounted at once.
|
||
|
||
- **GOP 8 desktop, GOP 4 mobile.** Scrubbing is random access; a long GOP means
|
||
every seek decodes a run of frames and the playhead lags behind the hand.
|
||
- Ship `data-sc-src-mobile` for every leg. The engine picks it on coarse
|
||
pointers and narrow viewports.
|
||
- Posters as WebP, extracted as above.
|
||
|
||
---
|
||
|
||
## 7. Loading
|
||
|
||
A leg is fetched only while the reader is within **±1.6vh** of it. Loading the
|
||
whole flight up front is tens of megabytes before the first frame paints;
|
||
loading on arrival means arriving at a poster.
|
||
|
||
Until a leg's first real frame has painted, its poster carries the move with a
|
||
push-in (`scale(1.03 + local × 0.14)`). A still that sits perfectly still while
|
||
the page scrolls announces itself as a placeholder; a slow push reads as the
|
||
camera already flying.
|
||
|
||
Under reduced motion **no clip is ever fetched**. The posters are the film, they
|
||
cross-dissolve through exactly the same seams at exactly the same scroll
|
||
positions, the same copy windows open and close, and every transform is dropped.
|
||
The whole story still reads.
|
||
|
||
---
|
||
|
||
## 7b. The spacer is sized once, at mount
|
||
|
||
`layout()` writes the spacer height as `(total + 1) * innerHeight`. If
|
||
`innerHeight` reports 0 at that moment the spacer is set to **0px**, the page
|
||
has no scroll track, and the flight never advances.
|
||
|
||
It fails silently and it looks like success. The engine mounted, every leg
|
||
registered, the clips fetched and decoded, `sc-has-clip` is on the segments, and
|
||
there is nothing in the console. The page is simply a still image that cannot be
|
||
scrolled. Embedded preview panes and some early loads do exactly this.
|
||
|
||
Do not fix it in the engine. One resize makes it re-measure correctly, so send
|
||
one from the page once the window and the fonts have settled:
|
||
|
||
```js
|
||
function relayout() { dispatchEvent(new Event('resize')); }
|
||
addEventListener('load', relayout);
|
||
if (document.fonts && document.fonts.ready) document.fonts.ready.then(relayout);
|
||
```
|
||
|
||
The `fonts.ready` half earns its place independently: a webfont swapping in
|
||
changes the measured height of every copy block, and anything the page sized
|
||
against those blocks (a scrim plate, a rail) is wrong until it re-measures.
|
||
|
||
Check it with one line, and check it before blaming anything else:
|
||
|
||
```js
|
||
document.documentElement.scrollHeight // must be ~(sum of weights + 1) * innerHeight
|
||
```
|
||
|
||
## 7c. Pace: one speed, and slower than you think
|
||
|
||
Two separate faults get described as "it doesn't feel smooth", and only one of
|
||
them is smoothing.
|
||
|
||
**Inconsistent pace is the worse one.** Leg weight divided by clip length is how
|
||
fast the world moves under the reader's hand. If that number varies from leg to
|
||
leg, the world surges and drags for no reason the reader can see, and it reads
|
||
as a fault in the page rather than as pacing. Give every leg with the same clip
|
||
length the **same weight**, and give a longer clip a proportional one. On
|
||
`orrery` that number varied by 36% across ten legs on the first cut, and the
|
||
owner's word for it was "not smooth". Evened to a 6% spread, the same footage
|
||
reads as one continuous move.
|
||
|
||
```
|
||
rate = weight / clip_seconds // hold this within a few percent everywhere
|
||
```
|
||
|
||
**Then slow it down.** The instinct is to spend as little scroll as possible. A
|
||
fly-through wants the opposite: the reader is steering a camera, and a camera
|
||
that answers too eagerly feels twitchy. **0.21 to 0.22vh per second of film is a
|
||
good floor for a world you fly through.** 0.14 to 0.19, which is what the per-8s
|
||
line yields, is noticeably fast.
|
||
|
||
That line is a **dead-scroll guardrail, not a taste ceiling.** Exceeding it is
|
||
fine and often correct; exceeding it without checking is not. The harness
|
||
defines dead scroll mechanically and will tell you. At 0.216vh/s a 0.12vh sample
|
||
gap still advances the clip by half a second, nowhere near dead.
|
||
|
||
**Damp the playhead and widen the joins.** `data-sc-lerp` defaults to 0.18;
|
||
**0.12 is the better default for a worldflight**, because a flight has more legs
|
||
mounted and more seams than an act page, and the extra damping is what actually
|
||
removes wheel-event judder. Widen `data-sc-seam` from 0.12 to ~0.16 for the same
|
||
reason: a longer crossfade band gives each join more room to disappear in.
|
||
|
||
Changing weights moves every leg boundary, so **every `data-sc-window` has to be
|
||
recomputed** against the new track and then re-checked on screen. A copy window
|
||
is tuned to a frame of film, not to a number.
|
||
|
||
## 8. Hard rules
|
||
|
||
| Rule | Why |
|
||
|---|---|
|
||
| **Nothing in document flow but the spacer.** | The moment a real block scrolls past the fixed stage, the page has a seam and the mode is pointless. If you want a section, you want act mode. |
|
||
| **Copy translate ≤ 4vh across a window.** | Larger reads as a second page scrolling at a different speed. |
|
||
| **The lerp is never disabled** except under reduced motion. | A 1:1 playhead reproduces every gap in the wheel event stream as a stutter. |
|
||
| **One pace for the whole flight**, and slower than feels necessary. | Weight divided by clip length must match across legs, or the world surges and drags. ~1.5vh per 8s is the dead-scroll guardrail, not the target. See section 7c. |
|
||
| **Every clip stays mounted. Never swap a `src`.** | A src swap is a black frame. |
|
||
| **Seam frames come from the encoded mp4.** | The encode changes the pixels. |
|
||
| **One accent, one scrim shape, copy anchored off the bright centre.** | Verified by the contrast pass, which grades copy blocks exactly like cues, at the worst frame each line is ever shown on. |
|
||
|
||
---
|
||
|
||
## 9. Verifying
|
||
|
||
`shoot.mjs` detects `[data-sc-mode="worldflight"]` and switches modes. It samples
|
||
across the spacer track at the same density it samples acts, plus four extra
|
||
positions across every seam, and it waits for the lerp to settle before each
|
||
shot (a screenshot taken mid-lerp is a frame the page never actually holds, and
|
||
it makes the run unrepeatable).
|
||
|
||
It reports:
|
||
|
||
- **dead scroll**, defined here as no leg advancing its `currentTime`, no
|
||
crossfade progress, and no copy-window opacity change between two samples more
|
||
than 0.12vh apart. Skipped under reduced motion, where each leg legitimately
|
||
holds one still frame.
|
||
- **legs that never reach full opacity**: a weight or a seam that is wrong: the
|
||
reader is shown a permanent dissolve and never the leg itself.
|
||
- **legs stuck on poster**: a clip that never loaded or never decoded. It passes
|
||
every other check, because a poster looks exactly like a paused film.
|
||
- **contrast** on visible copy blocks, through the same direction-aware
|
||
compositing path as cues.
|
||
|
||
```bash
|
||
node scripts/serve.mjs --root builds/<name> --port 45XX
|
||
node scripts/shoot.mjs --url http://localhost:45XX --out lab/<name>-shots --per-act 8
|
||
node scripts/shoot.mjs --url http://localhost:45XX --out lab/<name>-reduced --reduced-motion
|
||
```
|
||
|
||
The mechanical assertions ship with the skill as
|
||
`scripts/worldflight-assert.mjs` and run against **any** worldflight page, not a
|
||
special rig: spacer height, fixed stage, nothing in document flow, lerp
|
||
convergence and non-overshoot, seam monotonicity, the copy transform cap, and
|
||
the reduced-motion contract.
|
||
|
||
```bash
|
||
node <skill>/scripts/worldflight-assert.mjs --url http://localhost:45XX
|
||
```
|
||
|
||
Run it against your own build before the contact sheet. It answers "does the
|
||
mode actually hold" in a way a screenshot cannot.
|