← home

WHAT STORY ARE WE TELLING

we wanted our landing page to *show* the product instead of describing it. so I
built a thing that turns the real app into a guided, narrated, clickable little
walkthrough. no signup, no backend, plays in about a minute. a few of them, one per
workflow.

here's the bet I'm proudest of, and it sounds boring until you see it: instead of
recording a video, each demo plays back the *real page*. at build time a script walks
the actual app and snapshots the live HTML at every step, and the player just replays
that. it's the same trick the session-replay tools use. why bother? because a snapshot
of real HTML stays razor sharp when the camera zooms into a button, the text is
actual selectable text and not pixels, it's a fraction of the size of video, and you
can re-theme it to dark mode or swap the language without re-recording a single frame.
a recording can't do any of that. it's just frozen.

the part that humbled me wasn't the tech though. it was the writing.

first version of the scripts, I went "dessert first." cold open inside the finished
result, all shiny, then rewind to show how you got there. felt very cinematic in my
head. I wrote them all that way, recorded everything... and then someone watched it and
just asked: "what story are we telling?" oof. yeah. it was disorienting. you'd open
inside a finished screen, jump to an empty dashboard, jump back, and the viewer loses
the thread completely. so I threw it out and rebuilt every one as a single continuous
journey, where every scene change has to be caused by a click you literally just
watched happen. start here, do the thing, watch it work, see the result. the
excitement goes in the narration's tone, not in hopping around in time. clever lost to
coherent.

then the fun engineering problem: it had to feel instant, even on a bad connection.
the naive version popped a loading spinner every time you picked a demo. gross. the fix
is sneaky and I love it. each demo is kind of heavy in total, but the *first frame*
only needs a tiny handful of files. so the moment your mouse hovers over a demo, before
you've even clicked, it quietly fetches exactly those few files in the background. the
half-second between hover and click hides the whole load. cold, it took about 3.5
seconds. hover first, and it opens in 46 milliseconds. same files, just fetched a beat
earlier. 🪄

oh and one habit that saved me: I stopped saying "should work" and started attaching
the actual number. the gap is 14px. it opens in 46ms. and I wrote a little script that
walks every single step of every demo and fails loudly if a tooltip ever slips off the
edge of the screen. turns "looks fine to me" into something that can't quietly rot.

funny how the thing you're building keeps trying to teach you how to build it. the
whole project was about showing instead of telling, and somewhere in the middle I
realized that was also the only way I got anything decided.


---

this blog runs on [pre](github.com/connect-kai/pre)