Horizontal Scroll Scenes

The mechanism: scroll position is the only state. One pure function turns

scrollY / (scrollHeight - innerHeight)

into

{scene, dwell 0→1, move 0→1}

every frame, and everything on screen (camera, wipe line, craft clock, text, index) is written from that triple. Nothing remembers where you were, so every beat is a place on the page.

This is what Kibori does, and it is not a

translateX

slider. Verified by running it: the page is a

1742vh

native-scroll track (15,678 px at 1440×900); a fixed stage holds one WebGL world whose camera travels 0 → 49.7 world units left to right through eight stations; between stations a ragged burn line wipes from a frozen frame of the scene being left to the live scene already framed on the next. There is no wheel handler, no snap, no stored "current chapter". Reload at depth, scrollbar drag and anchor jumps work because state is derived, not accumulated.

Reach for

scroll-world-storytelling

build-threejs-scroll-worlds

for the story and 3D-world side,

gsap-scrolltrigger-storytelling

for pinned sticky sections,

scroll-progress-timeline

for a progress line. Reach for this when the deliverable is discrete chapters with a resting beat each, laid along an X axis, and the hard part is making that state machine survive reverse, skip and refresh. The demo is Vanilla JavaScript + DOM/CSS + inline SVG; the source is three.js. The state machine is identical.

The pace: two weights and a track height

Every number lives in

DWELL

MOVE

and the track height. One unit is one screen of scrolling.

constant	value	meaning
`DWELL`	1.15	scroll spent inside a scene while its craft advances (about 1,030 px at 900 tall)
`MOVE`	0.85	scroll spent crossing to the next scene (about 760 px); the last scene has none
`CYC`	2.00	one scene per two screens
`SPAN`	`NDWELL + (N-1)MOVE`	8 scenes: 15.15 plus a 1.35 footer = 16.5; demo, 5 scenes: 9.15
track	`(SPAN + 1) * 100vh`	so 1 unit ≈ 1 screen; Kibori is 1742vh for 16.5

function travel(sp){                              // sp = scrollY / (scrollHeight - innerHeight)
  const u  = Math.min(SPAN - 1e-5, sp*SPAN);
  const i  = Math.min(N - 1, Math.floor(u/CYC));
  const local = u - i*CYC;
  const dw = Math.min(1, local/DWELL);                        // the scene's own clock
  const f  = i >= N-1 ? 0 : clamp01((local - DWELL)/MOVE);    // the move
  const rc = clamp01((f - 0.01)/0.97);                        // the line's own clock
  return {i, u, dw, f, fe: sstep(0,1,f), L: -0.08 + 1.24*rc,  // L: line, off-frame at both ends
          live: Math.min(N-1, f < 0.39 ? i : i+1)};           // what the index shows
}

Normalise by

scrollHeight - innerHeight

, never a hard-coded pixel height: a phone's collapsing URL bar changes

innerHeight

mid-scroll and a px map drifts.

Rules, each with the failure it prevents

Derive, do not accumulate. Never keep
```
currentScene
```
or add wheel deltas. Stored state desyncs on scrollbar drag,
```
Home
```
/
```
End
```
, anchor jumps, back-forward and refresh. Prove it: record a signature of every visible style at 20
```
u
```
values going forward, then again in reverse, then by jumping straight to each, then after
```
reload()
```
at three depths. All must be equal (the demo run: 0 mismatches of 21, 0 skip, 0 reload).
No wheel hijack, no
scroll-snap
. Hijacking breaks touch, trackpad momentum,
```
Space
```
/
```
PageDown
```
and find-in-page. Snap fights the dwell, which is already the resting plateau (1.15 screens where nothing moves but the craft). Native scrolling stays 1:1: 2,000 px of wheel gave exactly
```
u = 2000/(scrollHeight - vh)*SPAN
```
.
Pin the craft clock outside its dwell. Scene
```
k
```
's progress is
```
1
```
if
```
k < i
```
,
```
dw
```
if
```
k == i
```
,
```
0
```
after. Then nothing snaps back behind you and reverse retraces exactly. Write it as
```
--p{k}
```
and eased
```
--e{k}
```
custom properties on the stage; both world copies read them, so it is one write per frame.
A move with nothing moving is dead scroll. Start the line at the frame's edge almost at once (
```
rc = (f-0.01)/0.97
```
); starting it further off made the first eighth of every move do nothing.
The wipe hides the camera. Freeze the outgoing frame ahead of the line and have the live world already standing on the destination behind it. A camera still travelling under the line reads as a double exposure. Demo: layer A at camera
```
i
```
clipped to the far side of the line, layer B at
```
i+1
```
clipped to the near side. Pan mode (
```
translateX(-(i+fe)/N*100%)
```
) is the alternative when no wipe is wanted.
The line writes the next chapter in. Alternate sweep direction from the side the incoming words sit on. Mask outgoing text
```
linear-gradient(a, transparent (L-.01)%, #000 (L+.016)%)
```
and incoming
```
#000 (L-.062)%, transparent (L-.048)%
```
, with
```
a = 90deg
```
or
```
270deg
```
. Two chapters never share a patch of frame. On a phone both sit in one slot: hide the incoming until the line has cleared,
```
sstep(1.00, 1.14, L)
```
.
The index flips at
f < 0.39
, not 0.5. At the midpoint the incoming title is already half written; flipping late labels the wrong scene. Fade the inactive rows to
```
0.55
```
, not
```
0
```
.
Chapter clocks overlap on purpose. Arrival starts
```
MOVE*0.80
```
before the scene's home and finishes
```
DWELL*0.62
```
into it; departure starts at
```
DWELL + MOVE*0.28
```
and takes
```
MOVE*0.34
```
. Each part (eyebrow, title, lede, numbers) takes its own slice of
```
arrive
```
(0, .12, .40, .60 plus a 0.30 ramp).
Fast-skip plays only the last move. More than one scene away: roll smoke in over 380 ms,
```
scrollTo
```
the station before the target (
```
(tgt-1)*CYC + DWELL*0.96
```
going forward,
```
(tgt+1)*CYC + 0.02
```
going back), then play the final move for 2,600 ms with
```
1-(1-x)^2.4
```
as the veil lifts over the first 24%. Hide the scene it passes through, or its words flash. Land at
```
tgt*CYC + DWELL*0.80
```
so the target is assembled. One scene away or fewer: plain leg of
```
clamp(700 + |dy|/vh*150, 900, 2400)
```
ms with cubic in-out. Without this a jump from 1 to 8 strobes six fires.
Any wheel, touch or nav key cancels the glide. Otherwise the page fights the hand.
html{scroll-behavior:smooth}
breaks both the glide and every capture. Per-frame
```
scrollTo
```
chases itself; playwright screenshots land mid-scroll and look like overlap bugs. Set
```
auto
```
.
Hidden chapters are
visibility:hidden
plus
inert
. Opacity 0 alone leaves invisible links focusable and readable to screen readers.
Render on
scroll
,
resize
,
pageshow
,
load
and
fonts.ready
. Reload restores scroll after first paint; a bfcache restore fires no scroll event. Guard a zero-size stage and size from a
```
ResizeObserver
```
.
Duplicate worlds need unique SVG ids. Two copies sharing a
```
clipPath
```
id resolve
```
url(#id)
```
to the first one only.
Announce committed changes only. A polite live region says "Scene 4 of 5: Yakisugi" once when a glide lands, not on every threshold crossed on the way.

Accessibility and lifecycle

Index rows are real links with
```
aria-current="step"
```
and a visible 1 px outline at 5 px offset; brand link returns to scene 1. The stage is
```
position:fixed
```
above a plain-height track so
```
Space
```
, arrows,
```
PageDown
```
,
```
Home
```
and
```
End
```
scroll natively.
```
prefers-reduced-motion: reduce
```
: no line, no travel. Scene B cross-fades over
```
f
```
0.30 → 0.70, the incoming chapter waits until
```
f = 0.64
```
, glides are an instant
```
scrollTo
```
, and the craft still advances with scroll (that is the user's own input). Controls stay live.
```
document.hidden
```
: settle any glide at its target so a resumed tab does not integrate the pause.
Mobile: keep the index to the current row (
```
03 / 05 Kigumi
```
), stack the chapter at the foot and the work above it.

Cost, measured

The state machine is free:

render()

sits at the 0.1 ms timer floor (p50 0, p90 0.1) over a 400-step sweep, and 8.3 ms p50 (120 Hz cap) with 9.2 ms max during a 2.6 s glide in the demo. The cost is whatever the scenes draw. In Kibori a dwell frame was slower than a transition until a 4096² shadow map stopped redrawing every frame, and a scissored live scene did the rest; see the

kibori-60fps

notes. Never spend effort optimising

travel()

Failure signatures

you see	cause
reload lands on scene 1	state kept in JS; derive from `scrollY` and render on `load` / `pageshow`
scene "sticks" between two beats	snap or wheel capture; delete it
two rooms overlap under the line	camera still travelling under the wipe
index shows the old scene as the title lands	flip threshold at 0.5 instead of 0.39
jump link strobes several scenes	glide plays every move instead of the last
jump link overshoots or stutters	`scroll-behavior:smooth` on `html`
second scene's clip does nothing	duplicated SVG `id`
screen reader reads chapters that are not on screen	opacity 0 without `inert`
phone shows two titles spliced at the line	incoming chapter not held back until the line clears

Provenance

Extracted from KIBORI 木彫, an eight-craft Kyoto woodshop page in one three.js file (

kibori.html

travel()

and the glide block near the end of its module script). Demo staged in that page's dark-and-ember look with five hand-drawn SVG crafts.

horizontal-scroll-scenes

NPX Install

Tags

SKILL.md Content