Skip to content

Give the page one module for what it does in response to the viewport - #9

Merged
xirothedev merged 2 commits into
mainfrom
q2-on-screen-motion
Sep 30, 2026
Merged

xirothedev merged 2 commits into
mainfrom
q2-on-screen-motion

Conversation

@xirothedev

Copy link
Copy Markdown
Collaborator

What

Second candidate from the architecture review, and the one that makes the
repository's first tests worth having. lib/motion.ts is one seam for the
three questions the page was answering separately: has this come into view,
has the pointer or the page moved since the last frame drawn, and how deep is
each card in this sticky stack.

fd06ce4 lib/motion.ts replaces lib/use-reveal.ts; stackDepths is pure and tested; the test script, turbo task and CI step land

pnpm lint, pnpm typecheck, pnpm test and pnpm build all pass. 17 tests.

The sticky-depth arithmetic is now testable

It was 24 lines inside a useEffect closure, so the only way to check it was
to scroll the page and watch the cards. It is stackDepths(tops, stickyTops, tolerance) — pure, in, out — and the 2px tolerance that decides whether a
card counts as arrived is a parameter rather than a magic number visible in
exactly one place.

Nine tests, and they caught my own misreading of the function twice while
being written. Depth is what is stacked on a card, not how far down it is,
so one card reaching its sticky position raises the depth of all three cards
below it. Both of my first drafts asserted the opposite and failed, which is
the point of extracting it.

Three easing curves, not one

They were written out ten times across four files. They are not
interchangeable: the intro curtain retracts on a symmetric ease-in-out and the
letters leave on a slow-out one. So they are named — EASE, EASE_CURTAIN,
EASE_EXIT — rather than collapsed into one constant that would be wrong in
two of three places. A test asserts the four components import the curve rather
than typing it.

useFrameCallback is the rAF coalescing that three call sites each hand-rolled
in three different shapes. It guarantees one call per frame, holds the most
recent callback, and cancels on unmount.

The two reveal recipes are deliberately not merged

The bento card fades and lifts 28px; the heading also blurs, in 12px, with a
different threshold and a different duration. Unifying them means flags, and
AGENTS.md rule 1 is that this repository has no boolean props. They stay
apart, and the module says why.

ADR-0003's condition is now met, so CI runs the tests

That ADR said a second test file carries the decision to add the test script,
the turbo task and the CI step. This is the second file, so all three are here
and the workflow is renamed "Lint, typecheck, test, build". The ADR's real
position — node --test, no test dependency — is unchanged.

The gate was verified rather than assumed: setting the tolerance to 0 fails a
test and turns the turbo task red, so the build would not pass on it. An
earlier attempt at that check silently didn't apply and looked like a pass; the
mutation is now confirmed by re-reading the source afterwards.

One lint rule scoped, in its own reviewed commit

promise/prefer-await-to-callbacks fires on the requestAnimationFrame inside
useFrameCallback. A frame callback is not a promise: it fires on the next
paint whether or not anything awaits it, and the callers are a mousemove and
a scroll listener. Making the wrapper async would mean awaiting a paint
before writing, which is a frame of latency added to work whose whole point is
to write once per frame.

Per ADR-0001 this is a change to the config, not a suppression. It is scoped
with an overrides block to apps/web/lib/motion.ts rather than disabled
repo-wide, and I verified the rule still fires on a probe file outside it.

Not in this PR

PixelIcon's observer is untouched. It counts how many icons are on screen
so the 60fps loop idles when nobody is looking, which is a different question
from "have I been seen" and would need a special case in the interface. Folding
it in should be a consequence of the interface, not a requirement of it.

The DOM-shaped parts of this module are still untested. useReveal and
useFrameCallback need a DOM, and the review's reasoning was that a test
needing a DOM is the signal to move to Vitest. That has not arrived.

Three questions were each answered separately, in three files: has this come
into view, has the pointer or the page moved since the last frame, and how
deep is each card in this sticky stack. lib/motion is now one seam for all
three, and lib/use-reveal.ts is gone into it.

The sticky-depth arithmetic was 24 lines inside a useEffect closure, so the
only way to check it was to scroll the page by hand and watch the cards. It
is now stackDepths, pure, and the 2px tolerance that decides whether a card
counts as arrived is a parameter with nine tests rather than a magic number
visible in exactly one place. The tests caught my own misreading of it twice
on the way in: depth is what is stacked ON a card, not how far down it is, so
one card arriving raises the depth of all three below it.

useFrameCallback is the rAF coalescing three call sites hand-rolled in three
shapes, and the easing curves were written out ten times across four files.
The curves are three, not one — the curtain retracts on a symmetric ease-in-out
and the letters leave on a slow-out one — so they are named rather than
collapsed into a single constant that would be wrong in two of three places.

The two reveal recipes are deliberately not merged. The bento card fades and
lifts, the heading also blurs, and the distances differ; unifying them means
flags, and a flag is a prop with two meanings and no name.

ADR-0003 said a second test file carries the decision to add the test script,
the turbo task and the CI step. That condition is met, so all three are here
and CI runs `pnpm test`. The gate was verified to turn the task red: setting
the tolerance to 0 fails a test and fails the build.

oxlint.config.ts gains one override. promise/prefer-await-to-callbacks fires on
requestAnimationFrame inside useFrameCallback, where a frame callback is not a
promise: it fires on the next paint whether or not anything awaits it, and the
callers are a mousemove and a scroll listener. Scoped to lib/motion.ts by
overrides, and confirmed still firing on a probe file outside it.
@vercel

vercel Bot commented Sep 30, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
aris-web Ready Ready Preview Sep 30, 2026 4:49pm UTC

CI failed on the Test step: node --test lib/ was resolved as a module path
rather than a directory to search, and Node 24 has no directory discovery —
the argument is matched as a literal glob, resolves to the directory itself,
and then gets run as a test file (nodejs/node#64555).

The local machine is on Node 26, where the same command worked, which is why
it passed here and failed there. The repo pins 24.x in engines and CI, and
that pin is deliberate: a previous commit moved CI to 24 because it had been
validating a runtime nothing deployed on.

node --test "lib/*.test.ts" is the documented form. The quotes matter and
have to be double: an unquoted pattern is expanded by the shell rather than
by Node, which is why it works interactively and fails under a package
script on a different shell.

Verified on node 24.20.0, the version CI runs: the directory form fails with
MODULE_NOT_FOUND, the quoted glob passes 17. The full gate — lint, typecheck,
test, build — passes on 24 as well as on the local 26.
@xirothedev
xirothedev merged commit 929e22f into main Sep 30, 2026
3 of 4 checks passed
@xirothedev
xirothedev deleted the q2-on-screen-motion branch September 30, 2026 16:50

This branch was successfully deployed

1 active deployment
Preview — 10104471 Deployed Sep 30, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant