# The device kit

Nine ways for scroll to change the page. Each one is a different answer to "what
does the visitor's hand actually do here."

Pick per beat, never per page. The variety law from SKILL.md Step 2 applies:
four or more families, never the same one twice in a row.

Every act publishes `--sc-p` (0 to 1) on its own element, so anything you want
to drive that the kit does not cover, you can drive from CSS with `calc()`
against that variable. Reach for that before asking for a new device.

---

## 1. `scrub`: the wheel is a scrubber

The anchor device. A pre-rendered camera move plays under the reader's hand,
one frame per notch. This is the thing people screenshot and send to each other,
so spend it on the open.

```html
<section data-sc-act="scrub" data-sc-span="2.6" data-sc-dwell="0.35"
         data-sc-drift="#0A0806">
  <div data-sc-stage>
    <img class="sc-stage__poster" src="assets/01-hero.webp" alt="">
    <video data-sc-scrub data-sc-src="assets/01.mp4"
           data-sc-src-mobile="assets/01-m.mp4" playsinline muted></video>
    <div class="sc-scrim"></div>

    <div class="sc-copy sc-copy--lead" data-sc-cue="0.08 0.62 0.34">
      <h1 class="sc-display sc-display--xl" data-sc-kinetic="lines">
        Your morning shouldn't need two drinks.
      </h1>
    </div>
  </div>
</section>
```

- `data-sc-span` is the act's scroll length in viewport-heights. 2.2 to 3.0 for
  a hero. Below 1.8 the clip flies past; above 3.5 the reader starts wondering
  whether the page is broken.
- `data-sc-dwell` (0 to 0.6) remaps time so the camera settles mid-act, exactly
  where the copy peaks, and moves quicker at the edges. It is the difference
  between a clip that plays and a shot that lands. Keep it at or below 0.6.
- `data-sc-src` (not `src`) is deliberate: the engine fetches the clip as a Blob
  so it seeks without needing HTTP range support, and skips the fetch entirely
  under reduced motion.
- The poster is a live frame-holder. It stays up until a real video frame has
  painted, because iOS keeps a seeked-but-never-played muted video blank and
  hiding the poster on metadata alone flashes an empty stage.

**At most two scrub acts per page.** The third one is no longer a surprise, and
it is the heaviest thing on the page.

### Clip time is not cue time

The single most damaging bug this device has, and it is invisible in every
screenshot taken one at a time.

A pinned stage is on screen for **one viewport before** its pinned travel begins,
sliding up into view, and **one viewport after** it ends, sliding off the top.
The act's progress `p` is 0 through the whole entry and 1 through the whole exit.
So a clip driven by `p` sits frozen on its first frame while it slides in, and
frozen on its last frame while it slides out. The reader has been scrubbing a
film with their hand, the film stops, and then the whole page slides a still
photograph past them. It reads as the site breaking, and it is the fastest way to
make an expensive page feel cheap.

The engine therefore maps the clip across the stage's **entire visible life**, not
across its pinned travel, and this is the **default**. Both ends are clamped to
scroll that actually exists, so a hero at the top of the document still starts on
frame one and an act near the bottom still reaches its last frame. Cues keep
using `p`, because cues belong to the pin.

**Pair it with `data-sc-dwell`.** Dwell moves quickly at the edges and settles in
the middle, which is exactly the shape this mapping wants: the fast motion lands
on the two slides, and the settle lands inside the pin where the copy is. The two
were built for each other.

`data-sc-clip-map="travel"` restores the old pinned-travel mapping. There is
almost no reason to reach for it, and reaching for it reintroduces the freeze.

The harness checks this now (see [verify.md](verify.md)), so a frozen clip fails
verification instead of shipping. Do not rely on noticing it by eye: every
individual frame of a frozen clip looks completely correct.

### The playhead is lerped

Scroll never writes `currentTime`. It writes a target, and a standalone rAF loop
walks the clip toward that target at a fixed fraction per frame. Wheel events do
not arrive at a constant rate, so a 1:1 write reproduces every gap in them and
the clip reads as a stutter rather than a glide. Three mechanisms, all on by
default:

- **Lerp 0.18 per frame.** `data-sc-lerp` overrides it, on the mount root for the
  whole page or on one `<video>`. Clamped to 0.02 to 1, and never read as 0, since
  a 0 lerp is a playhead that never moves. Reach for it only when a page's clips
  are short enough that 0.18 visibly lags the hand. Under reduced motion the
  rate is 1.0, which is no smoothing at all.
- **Deadband** of 8ms desktop, 20ms mobile. A write smaller than that costs a
  seek and shows nothing; on a phone it costs more than it shows.
- **Seek coalescing.** No seek is queued while the decoder is still resolving the
  last one. A fast flick otherwise piles seeks up and freezes the clip.

An offscreen clip that has already reached its target stops being touched at all.

This applies to every scrub clip on the page, act or worldflight. It is also why
`shoot.mjs` waits for the playhead to arrive before each shot: a frame captured
mid-lerp is a frame the page never actually holds.

---

## 2. `pin`: the frame holds, the content advances

The workhorse, and the cheapest premium effect there is. The stage sticks for a
few viewport-heights while copy states cross over inside it. Use it when the
beat is an argument rather than an image.

```html
<section data-sc-act="pin" data-sc-span="3" data-sc-drift="#12100E">
  <div data-sc-stage class="pf-argument">
    <p class="sc-lede" data-sc-cue="0.02 0.34">A cup of coffee. Then a shake.</p>
    <p class="sc-lede" data-sc-cue="0.30 0.66">Two things to buy, carry and wash.</p>
    <p class="sc-lede" data-sc-cue="0.62">Or one can.</p>
  </div>
</section>
```

**Minimum useful span is about 1.2.** A pinned act's travel is
`max(height - viewport, 1)`, so at a span of 1 or below that is one pixel:
progress jumps 0 to 1 between two scroll notches and every cue, reveal and
`--sc-p`-driven animation inside the act snaps instead of running. A short quiet
act is exactly when an author reaches for a small span, which is exactly when
this bites. If the beat genuinely wants less than a screen of travel, it is a
`flow` act, not a pinned one.

Cue windows overlap by design: the outgoing line is still fading while the next
arrives, so the reader never faces empty space. A gap between cues reads as a
loading failure. Overlap by roughly 15% of the act.

The last cue takes one value and holds, so the act ends on a statement rather
than fading to nothing before the next section arrives.

### The cue contract

`data-sc-cue="from [to [rampIn [rampOut]]]"`, all in act progress (0 to 1).

| Form | Behaviour |
|---|---|
| `"0.2"` | fades in at 0.2 and **holds to the end of the act** |
| `"0.1 0.6"` | in, plateau, out. Ramps default to 30% of the window each |
| `"0 0.78 0"` | **greet**: already at full opacity when the act begins, then fades |
| `"0.1 0.9 0.15 0.4"` | fast in, long slow out |
| `"0 1 0 0"` | **greet and hold**: full at p = 0, no ramp at either end |

The plateau is the point. Without one a cue is a triangle that touches full
opacity for a single 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.

Rules the verification pass will catch you on:

- **A hero cue needs the greet form.** `"0 0.7"` ramps up from nothing, which
  means the landing view, the one screen every visitor sees, has no headline on
  it. Use a third value of `0`.
- **The last act's cue must hold.** Give it one value. A closing CTA on a
  two-value cue fades out before the page ends, and the final screen is empty.
- **Only the last act may hold.** This is the inverse of the rule above and it
  is the one that bites. The engine parks a cue only once its act is a viewport
  and a quarter out of range, so a one-value cue on a *middle* pinned act stays
  lit through the entire un-pin slide: the line travels a full viewport upward,
  crosses any fixed header, and overlaps the section that follows. It is
  invisible until you measure it, and it shows up as a contrast failure on a
  headline nobody meant to still be on screen. Every act except the last closes
  its final cue with a two-value window ending at 1.
- **Ground or greet.** A pinned stage becomes fully visible roughly a viewport
  *before* its own progress leaves 0, so any pinned act whose first content is a
  plain two-value cue shows an empty stage for that whole travel. Give the act
  either a ground that is already there (an image, a held frame, a colour that
  is doing work) or a first cue in the greet form. The closing act needs a
  ground, because its hold cue cannot also greet unless you use `"0 1 0 0"`.
  The rule covers *any* progress-gated content on a pinned act, not just engine
  cues: a bespoke panel that populates from scroll state has the same empty-stage
  window and needs the same ground.

---

## 3. `pan`: vertical scroll, lateral travel

Sideways movement reads as *breadth* where vertical reads as *argument*. Use it
for a range, a lineup, a timeline. Do not use it for a hierarchy: the first item
in a rail is not read as the most important one.

```html
<section data-sc-act="pan" data-sc-span="3.2">
  <div data-sc-stage>
    <div class="pf-rail" data-sc-pan="0.08">
      <article class="pf-flavour">…</article>
      <article class="pf-flavour">…</article>
      <article class="pf-flavour">…</article>
    </div>
  </div>
</section>
```

The engine measures `scrollWidth` against the viewport and travels exactly the
overflow, so the last item lands flush at the right edge. `data-sc-pan="0.08"`
adds 8% overshoot if you want a breath after the final card.

Span rule: roughly 1 viewport-height per item, plus 1. Four cards want ~5.

**Measure the overflow, do not assume it.** The engine travels exactly
`scrollWidth - viewport`, so a rail narrower than the viewport travels **zero**
and the act becomes a pinned stage holding one motionless screen for its whole
span. Three cards at `clamp(16rem, 26vw, 24rem)` measured 1368px against a
1440px viewport: overflow **-72px**, travel 0, and the reader turns the wheel
through two viewport-heights of nothing. It is width-dependent, so it can be
correct on a phone and dead on a desktop at the same time, which is exactly how
it survives review: the mobile sheet pans and the desktop sheet looks like a
still. **The harness did not catch it** and reported `no dead scroll detected`
on every pass, so this is a manual measurement, not something a green run
covers:

```js
const rail = document.querySelector(".rail");
rail.scrollWidth - innerWidth        // must be a healthy positive number
```

Aim for at least half a viewport of overflow. If three items do not reach it,
the fix is not wider cards, it is **more rail**: put the act's heading in as the
first item and a closing note as the last. Both earn their place (the heading
stops competing with fixed chrome, the note gives the rail a resolution instead
of an end), and they add the width the travel needs.

**Give the rail's items a staggered settle driven from `--sc-p`.** Lateral
travel alone reads as a slideshow on rails; items that arrive in sequence read
as a drawer being pulled. Exempt the first item, because a pan act needs its
opening content already present, and floor the opacity around 0.55 so a
not-yet-settled card reads as arriving rather than as failing to load. Gate the
whole thing to `prefers-reduced-motion: no-preference`, or the scroll-region
fallback inherits a page of half-faded items.

**Card copy is read while cropped.** Items enter and leave through the viewport
edges, so a heading is half-shown for most of its life and two half-headings
side by side can read as a third word (`TRACE` beside `EVALUATE` becoming
`RE EVALUATE`). Keep card headings to one short word or two, and expect every
line of card copy to be read partially cut off.

**Reduced motion.** The rail's transform is not decoration, it is the
navigation, so it cannot simply be zeroed the way parallax is: that parks the
act on its first screenful and makes every item past the fold unreachable. The
engine handles the floor for you, turning the stage into a native
`overflow-x: auto` scroll region with proximity snapping, so the same items stay
gettable without motion. If your rail reads better stacked or as a grid at that
point, override it in your own CSS under `prefers-reduced-motion` (the agency
reference build relays its three phases out as a grid at desktop widths).

---

## 4. `reveal`: a wipe is a change of state

`clip-path` eating in from an edge. It costs nothing and it reads as
transformation, which makes it right for the beat where something becomes
something else. Wrong for merely introducing an image, where a cue is enough.

```html
<figure data-sc-reveal="up" data-sc-reveal-at="0.15 0.55">
  <img src="assets/03-carry.webp" alt="…">
</figure>
```

`up` `down` `left` `right` `iris`. Reach for `iris` roughly once per page; it is
the loudest of the five and stops reading as intentional if repeated.

A wipe that runs edge to edge across a full-bleed image is a transition. A wipe
on a small element is a fidget. Use it big.

**`clip-path` is relative to the border box, not to the ink.** A reveal on type
set with `line-height` below 1 has a border box shorter than the glyphs, so the
wipe clips the ascenders off the top and the descenders off the bottom and every
figure renders as a plain bar. Display numerals and drop figures are the usual
casualties, because those are the ones set tight. Either give the reveal element
room (`line-height: 1` and padding to cover the overshoot) or put
`data-sc-reveal` on a wrapper and leave the type's own box alone. No static
audit catches this; only a rendered screenshot does.

---

## 5. `kinetic`: type that assembles

Splits a heading into lines, words or characters and staggers them across the
cue window. Lines are almost always right; words for a short punch line;
characters approximately never, because it turns reading into waiting.

```html
<h2 class="sc-display sc-display--lg" data-sc-cue="0.1 0.7" data-sc-kinetic="lines">
  Coffee that pulls its weight.
</h2>
```

Each unit slides up from behind a mask, so it enters from a clean edge rather
than simply fading. Line masks reserve room for descenders; a mask clipped to
the line box shears the tails off g, y, p and j, and that is the single most
common way this effect looks broken.

Line splitting measures real line boxes, so it re-runs after `document.fonts.ready`.
Do not call it on text that is still loading its face.

**One kinetic headline per act, at most.** Two competing for attention is noise,
and every heading assembling the same way is the templated rhythm this skill
exists to avoid.

---

## 6. `parallax`: layers at different rates

Depth from differential movement. Subtle or nothing: past roughly 200px of total
travel it stops reading as depth and starts reading as a bug.

```html
<div class="pf-layer pf-layer--back"  data-sc-parallax="-1.4">…</div>
<div class="pf-layer pf-layer--mid"   data-sc-parallax="-0.6">…</div>
<div class="pf-layer pf-layer--front" data-sc-parallax="0.35">…</div>
```

**The rate is in hundreds of pixels, not viewport fractions.** The engine writes
`rate * (p - 0.5) * 100` px, so the total travel across a whole act is
`rate * 100` px regardless of screen height. At 0.35 that is 35px across three
viewport-heights of scroll, which is invisible: usable values are roughly 0.3 to
1.5 for a layer inside a frame and 1 to 2 for a full-bleed bed.

Negative moves up faster than the scroll, which pushes an element back. Three
layers is plenty; five is a diorama.

Never put body copy on a parallax layer. Text the reader is trying to read
should not move relative to the thing they are reading it against.

---

## 7. `count`: numbers that land

```html
<span class="sc-nums" data-sc-count="0 4200" data-sc-count-at="0.1 0.5">0</span>
```

Formatting is inferred from the target: decimals from its decimal places,
thousands separators above 10,000 **or whenever the target itself is written
with one**. Write the target exactly as it should render, commas included
(`data-sc-count="0 3,500"`); the engine strips them before parsing. The element
gets `tabular-nums` so the layout does not jitter while the digits change.

**Only real numbers.** A counter is a truth claim with motion attached, which is
what makes it persuasive and what makes an invented one a liability. If the
brand has no verified figure, there is no counter. Check the brand's rules
first; several forbid this outright.

**A concept, fictional or pre-launch brand has no verified figures, so it has no
counters.** The device suits a SaaS or agency page and it will look good in the
score table, which is exactly the trap: every number you could put in it would
be invented. Decide this before you design an act around a number, not after.
Real brand, real stats, or a different device.

---

## 8. `flow` + `in`: ordinary sections, done well

Not everything should be pinned. A page of nothing but pinned acts is
exhausting, and the contrast is what makes the pinned ones land. Normal
document sections with a reveal-on-entry are the rest of the page.

```html
<section class="sc-section">
  <div class="sc-wrap sc-stack" data-sc-stagger="70">
    <h2 class="sc-display sc-display--md">What is actually in it</h2>
    <p class="sc-body">…</p>
  </div>
</section>
```

This fires **once**, on entry, via IntersectionObserver. Content that re-hides
when the reader scrolls back up is a defect, not an effect. Stagger between 30
and 80ms; longer feels slow.

**A flow section directly after a pinned act takes reduced padding.** The pinned
stage needs a full viewport to scroll off, and full `--sc-section` padding on
top of that delays the flow section's first content by another screen. The
harness will not call it dead scroll, correctly, because the stage is moving.
The reader still sees a near-empty screen. Cut the block padding there and start
the first reveal near `p = 0`.

---

## 9. Pointer devices: interactivity that is not scroll

Scroll is a one-dimensional input. A page that only responds to scroll is a
film. These make it respond to the reader being *present*.

```html
<div class="pf-card" data-sc-tilt="7">…</div>
<a class="pf-cta" data-sc-magnet="0.28">Find a stockist</a>
<section data-sc-spotlight>…</section>
```

- `tilt`: 3D rotation toward the pointer. 5 to 9 degrees. Past 12 it is a toy.
- `magnet`: the element drifts toward the pointer. 0.2 to 0.35. Primary CTA
  only; a page of magnetic elements is unusable.
- `spotlight`: publishes `--sc-mx` / `--sc-my` for a light that follows the
  pointer across a surface.

**`magnet`, `parallax` and `cue` all write `transform`, so they cannot share an
element.** The magnet writes every frame in its own rAF loop, so it silently
wins and the cue's entrance rise is discarded. On a magnetic CTA, set
`data-sc-rise="0"` so the cue writes a no-op instead of losing a visible
animation to a race. A cued element that wants its own continuous transform
should drive an inner wrapper from `--sc-p` in CSS rather than stacking a second
device on the same node.

All three interpolate toward the pointer rather than tracking it directly.
Direct tracking reads as artificial because it carries no momentum. All three
are gated to `(hover: hover) and (pointer: fine)` and disabled under reduced
motion, so touch never fires a false hover.

---

## 10. `drift`: the ground moves with you

Not an act. A property of acts, and the thing that makes a page feel like one
continuous place rather than a stack of slides.

```html
<section data-sc-act="scrub" data-sc-drift="#0A0806"> …
<section data-sc-act="pin"   data-sc-drift="#161210"> …
<section data-sc-act="pan"   data-sc-drift="#0E1412"> …
```

The page ground interpolates between the values as each act takes over. Keep the
whole set inside one theme family. Drifting from near-black to cream mid-page
is not atmosphere, it is the reader wondering whether they clicked something.

Three to five stops across a page. Small steps. The effect should be invisible
frame to frame and obvious top to bottom.

**Scoping: drift belongs to the first act whose progress is strictly between 0
and 1.** That is the right pick when acts are long enough that only one is ever
part-way through, and it is wrong the moment several short acts satisfy it at
once. On a page of twelve short cuts the ground shown belongs to a section the
visitor left a screen ago, so a colour arrives late and reads as a bug rather
than as a slow lag. The advice above ("three to five stops") is written for six
long acts.

**If several acts can be part-way through at the same time, paint grounds per
section instead of drifting.** Set an opaque background on each section and let
the change land on a hard edge. That is also what a cutlist or a chaptered page
wants on its own terms: a cut is not an interpolation, and interpolating between
two chapter grounds is precisely the softness those grammars exist to refuse.
Drift is for pages that are one continuous place.

---

## Composing an act

Devices stack inside one act. A pinned stage can hold a scrubbing clip, a
parallax layer, a kinetic headline and a spotlight at once. The limit is
attention, not the engine: **one thing should be the reason each act exists**,
and everything else in it is support.

If you cannot say in one sentence what an act's moment is, it does not have one.