Read a whole document: element children, a provider, and Player

[awlevin]

Closes #4

<SpokenText> took a string, so a real page had to be cut into one component
per paragraph, each wired by hand, and nothing read continuously across them.
It now takes the elements themselves and reads the lot.

Scope

• Children walk: collect text leaves, preserve element structure, wrap words.
  walkDocument walks the tree it is handed, wraps only text, and rebuilds
  the same structure: an h2 stays an h2, a link stays a link. A string
  child renders byte for byte what it rendered before — asserted against the
  old markup in a test.
• Block-level segmentation and a segment-aware controller. Each heading,
  paragraph, list item and blockquote is its own alignment request.
  currentWordIndex is one index across the document; segments: { start, end, status }[] says where each block begins and ends. Words in
  a block that has not landed are future, untimed and seekable: false.
• Lazy fetch with next-segment prefetch. The first block is fetched on
  mount so the play button is live; the next is warmed while the current one
  plays; clicking a word in a block nobody has asked for fetches it and
  plays from that word.
• Estimate-and-correct duration. duration counts unloaded blocks at a
  reading pace and durationIsEstimate says so. <Player> shows the total
  dimmed with a tilde — ~1:47 — until every block has landed.
• <SpokenTextProvider> and context wiring. The provider holds the
  controller; <SpokenText> registers what it says and <Player> drives it,
  so the player can sit in a sticky header. Either still works alone, and
  useSpokenText stays the headless primitive.
• Skip mechanism: skip, only, data-spoken-skip, and defaults. Both
  props take a tag, a .class, an [attr] or a predicate over the React
  element. only fences the field, skip cuts inside it. Skipped content
  still renders where it was written and is dropped only from the text handed
  to the aligner, so the words either side of an inline <code> stay timed.
  Headings are read; skip={["h1","h2","h3"]} is the opt-out.
• Tests. Nested elements, a link inside a sentence, an inline code skip
  with the following word timed to the second, a block skip, only, block
  boundaries and global index offsets, an estimate correcting itself as the
  second block lands, provider wiring, a click in an unfetched block, and the
  string-child path rendering identically to today. 50 pass.
• Docs and a demo built from a realistic multi-heading article.
  /article reads a short piece about sourdough starters: a provider, a
  sticky <Player>, a pre block and an inline 1:5:5 that render but are
  not read. README usage and prop tables updated; changeset is a minor bump
  to 0.2.0.

Breaking

<Transport> is <Player>, and TransportProps / TransportClassNames are
PlayerProps / PlayerClassNames. No alias and no shim: nothing depends on the
package yet.

Two judgement calls the issue did not cover

• A word is clickable whenever clicking it does something — it has a
  timestamp, or its block has not been fetched. The issue asks for both
  seekable: false in an unloaded block and for a click there to fetch it, so
  seekable keeps its documented meaning ("this word has a timestamp") and the
  click handler is decided separately. In the loaded state the markup is
  unchanged; before a block lands, its words now carry cursor: pointer.
• A block that fails is not retried on its own. Found while looking at the
  page in a browser with no API key: the error re-ran the fetch effect, which
  hammered the route in a loop. It now stays failed until the reader presses
  play or clicks a word, which is a fresh attempt. Covered by a test.

Checks

pnpm build, pnpm lint, pnpm test and pnpm typecheck are all clean. The
demo's Vercel build needs no configuration change: /article is an ordinary
static route.

docs/demo.gif is deliberately not re-recorded — that comes after review.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EsXEwJ2uf1TnHXhuwfg1Eb

[vercel]

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

Project	Deployment	Actions	Updated
spoken-text	Ready	Preview	Sep 2, 2026 10:24pm UTC