# MUST OBEY — Mobile-first build requirements

This app's PRIMARY surface is a mobile phone. Build it impeccably on mobile FIRST, then verify on tablet and desktop. Treat the rules below as non-negotiable hard constraints, not suggestions.

## Viewports to verify (every screen, every state)
- 320 px, 360 px, 375 px, 390 px, 414 px, 480 px
- 768 px, 834 px (iPad portrait / Pro 11)
- 1024 px, 1280 px, 1440 px, 1920 px, 2560 px
- Plus: 200% browser zoom, landscape orientation on every mobile width, iPhone with safe-area insets visible

## Hard layout rules
- Mobile-first CSS. Default styles target mobile; `@media (min-width: ...)` for larger viewports.
- Use `dvh` and `svh` instead of `vh` for full-height surfaces (iOS Safari URL-bar bug).
- Use `clamp()` for fluid typography across all viewports.
- Prefer container queries (`@container`) over media queries for component-level responsiveness.
- Use `min(100%, ...)` widths so content never overflows. Zero horizontal overflow at any viewport.
- Add `<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">` to every page.
- Apply `padding: max(safe-area-inset-X, fallback)` on every edge-bleeding container so notched iPhones in landscape never clip content.
- Wide tables and code blocks scroll INSIDE their container (`overflow-x: auto`), never push the body.
- Use `background-attachment: scroll` on mobile, not `fixed` (iOS Safari repaint bug).
- Avoid `backdrop-filter` on animated elements. Use it sparingly on static surfaces only.
- **Canvas Scaling**: Canvases must dynamically scale with window resize events and properly handle high-DPI screens (`window.devicePixelRatio`). Set physical dimensions (`canvas.width`/`canvas.height`) using pixel ratio and render relative to this grid, using CSS to control responsive viewport scaling.
- **Robust Storage**: Every access to `localStorage`/`sessionStorage` (especially `JSON.parse` of loaded state or writes) MUST be wrapped in a `try-catch` block to handle disabled storage, private browsing mode, quota limits, or corrupted JSON gracefully. Fall back to a robust in-memory object store.

## Touch & accessibility
- Tap targets ≥ 44 × 44 px on touch (Apple HIG). Increase to 48 px under `@media (hover: none) and (pointer: coarse)`.
- All interactive controls reachable by keyboard with a visible focus ring; respect `:focus-visible`.
- Color contrast ≥ 4.5:1 for body text, 3:1 for UI components.
- All images have meaningful `alt`. Decorative images use `alt=""`.
- Respect `prefers-reduced-motion: reduce` — zero animation durations under that query.
- Forms validate inline; error messages are specific, not "Invalid input".
- Modals: focus trap, `Esc` closes, `role="dialog"`, `aria-modal="true"`, focus restored on close.

## Performance bar (Lighthouse mobile, throttled 3G/4G)
- LCP < 2.5 s · INP < 200 ms · CLS < 0.1
- JS bundle gzip < 200 KB mobile-first; lazy-load non-critical screens via `React.lazy` / dynamic imports.
- No render-blocking resources above the fold.
- Images: WebP/AVIF preferred, `loading="lazy"`, explicit `width`/`height` attributes (zero CLS), `srcset` for retina.
- Videos: `preload="metadata"`, low-resolution poster, max 720p mobile fallback. Never autoplay with audio.
- Fonts: `font-display: swap`; preload only the one used above the fold.
- Smooth scroll honoured via CSS `scroll-behavior: smooth` with reduced-motion fallback.

## Pre-ship mobile checklist (the deployer MUST verify before declaring done)
1. Open at 375 px in DevTools — every screen scrolls vertically only; zero horizontal scroll.
2. Browser zoom 200% — layout reflows without overlap.
3. iPhone Safari with the URL bar visible AND landscape — no content under the home indicator; no notch clipping.
4. iPad portrait (768 px) and landscape (1024 px) — no awkward gaps; tablet-specific breakpoints land cleanly.
5. Tap every interactive element with a thumb at real-device size — every target is easy to hit.
6. `prefers-reduced-motion: reduce` — every transition / animation skips cleanly, scroll-behavior becomes instant.
7. Lighthouse mobile score ≥ 90 across all 4 categories.
8. Zero `console.error` and zero CLS shift in real-device testing on a mid-tier Android (e.g. Pixel 6a) and an iPhone SE.

---

The original template starts below. All rules above apply on TOP of whatever this template specifies.

---

# Read This To Me

## 1. Project

**Read This To Me** turns any long article, essay, newsletter, paper,
PDF, or web page into expressive, walk-paced narration you can listen
to while doing dishes, commuting, walking the dog, or sitting on a
train with the phone face-down. Paste a URL or drop a PDF, tap play,
and within three seconds a natural human-feeling voice — warm,
focused, or casual — is reading the piece out loud at a comfortable
walking pace of about 130 words per minute, with subtle emphasis on
the load-bearing sentences, slightly different timbre on direct
quotes, and natural breath at every paragraph break. Every word is
read; nothing is skipped or paraphrased. The player locks the phone,
keeps playing in your pocket, and remembers exactly where you stopped.

This is the kind of app a commuter wants on the morning walk to the
station — they saved a 6,000-word longform piece in a "read later"
tab three weeks ago and have never opened it. It is the kind of app a
PhD student wants when they have a 40-page paper to read before a
meeting at three and would rather hear it on a walk than skim it on a
screen. It is the kind of app a parent wants on Sunday afternoon when
the dishes need doing and there is a newsletter sitting in the inbox
they actually want to hear. Same job, three different scales of
attention. The app handles all three.

The single demo that proves the magic: a visitor pastes the URL of a
4,000-word essay, taps "Read this to me", and within three seconds
the narration starts. The voice is warm and unhurried. At the end of
each paragraph there is a real breath. Quoted dialogue lands with a
slightly different vocal colour so the listener feels the speaker
change without being told. The key claim of the second section gets
a faint emphasis the listener notices but cannot quite name. Chapter
markers appear at every heading; one tap skips ahead. The lock-screen
shows a clean cover, the article title, and play / pause / skip
controls. The phone goes in the pocket and the listener walks.

In the harder cases — a 78-page PDF research paper with figures and
footnotes, a newsletter with embedded code blocks the listener does
not want read out, a long-form interview where two speakers alternate
— the app reads the long arc too: pages are stitched cleanly across
column breaks, footnotes get a one-line "footnote 14, three sentences,
tap to expand" mention rather than a full read-through that derails
the flow, code blocks are skipped with a "code block, twelve lines,
tap to read" handoff, and the two speakers in an interview get two
distinguishable voice timbres so the listener can follow who is
talking.

**Tagline:** _Paste a URL, drop a PDF. Walk away with the essay read
to you — at walking pace, in a real human-feeling voice, every word._

## 2. Target audience

- Commuters and walkers who already have a stack of saved-for-later
  longform pieces and never make it back to the tab
- PhD students, lawyers, policy analysts, and anyone whose inbox
  fills with PDFs they should read on the train but read poorly on a
  screen
- Parents doing dishes, folding laundry, walking the dog — listening
  is the only time of day they actually have to read
- People with dyslexia, post-concussion symptoms, eye strain,
  migraine, or visual fatigue for whom an audio companion to written
  longform is genuinely accessible
- Newsletter readers who subscribe to ten weekly essays and never get
  through more than two; the audio version cuts through
- Researchers who want to "read" a paper while running and form an
  opinion before the lab meeting
- Listeners on flights, in airports, in long car queues, on the bus —
  anywhere the eyes are taxed but the ears are free
- People who simply prefer audio — they would buy an audiobook
  version of every essay if such a thing existed, and find paid
  per-article narration services (which exist but stop reading after
  one weekly piece) too restrictive

## 3. Core value propositions

Surface these clearly through copy, visual emphasis, and section
ordering — they are the reasons users pick this app.

- **Expressive voice, not robotic TTS** — the post-I/O 2026 expressive
  TTS model (`gemini-3.1-flash-tts-preview`) produces narration with
  real prosody: natural breath at paragraph breaks, subtle emphasis on
  the sentence the author is leaning on, a different vocal colour for
  quoted material, and a pace that matches how a friend would read
  the piece aloud — not the flat, equal-stress cadence of stock TTS.
- **Every word, no shortcuts** — the app NEVER skips or paraphrases.
  Summarisation is a separate, opt-in mode; the default contract is
  "every word the author wrote, in order, read out loud". This is the
  load-bearing trust contract — a listener who has been burned by
  summaries that skipped the part they wanted to hear can rely on this
  app to read the whole piece.
- **Walking pace by default** — narration runs at ~130 words per
  minute by default, the pace at which a thoughtful friend reads a
  piece aloud on a walk. Adjustable from 100 wpm (close-listen) to
  180 wpm (fast catch-up); the default is tuned for ambient listening
  while moving. The pace knob lives on the player face, not in a
  settings page.
- **Three voices, three jobs** — _Warm_ for personal essays,
  newsletters, memoir; _Focused_ for research papers, technical
  pieces, policy writing; _Casual_ for blog posts, light writing,
  conversational longform. The voice change is conveyed via a single
  style-directive sentence prepended to the input (Gemini 3.1 Flash
  TTS does not support SSML), and the listener picks it once per
  piece via a one-tap chooser.
- **Reading-aware pause structure** — paragraph breaks become real
  pauses; sentence boundaries become micro-pauses. Encoded as the
  textual cues `…` for sentence pauses and a blank line plus `—` for
  paragraph pauses (since Gemini 3.1 TTS has no SSML `<break>` tag).
  Headings get a short tonal lift; quotations get a slightly more
  intimate timbre. Foot-of-page and end notes are flagged inline
  rather than read full-bleed.
- **Offline-cached playback** — once the narration has been generated,
  the MP3 is cached on-device so the user can listen on a flight,
  underground, or in dead-zone wilderness. The download chip on the
  player face shows MB size and percent cached.
- **Background-audio first-class** — the app implements the Media
  Session API with full lock-screen art, scrubbing, play/pause, skip
  forward / back by chapter, and per-15s seek. The phone screen
  locks and the audio keeps playing. The user can answer a call, take
  a photo, or run another app and come back without losing position.
- **Honest about what gets skipped** — code blocks, large tables,
  raw equations, and figures that do not render as prose are
  surfaced as one-line spoken handoffs ("code block, twelve lines,
  tap to read") rather than awkwardly narrated. The listener decides
  whether to break narration flow to engage with them, and a
  per-piece toggle "read everything verbatim, even code" exists for
  the listener who wants no exceptions.

## 4. Features to build

- Paste-URL flow — single text input on the home screen accepts a URL
  to an article, a Substack post, a Medium post, a personal-blog page,
  a Wikipedia article, an arXiv preprint page, a news article. The
  fetcher resolves the canonical reading view (boilerplate stripped)
  before passing prose to the TTS pipeline.
- Drop-PDF flow — drag-and-drop a PDF, or tap to upload from the
  device; PDFs up to 200 pages handled in a single pipeline pass with
  multimodal page-parsing on Gemini 3.5 Flash.
- Share-extension entry (iOS Share Sheet / Android Share intent / web
  Web Share Target) — share any URL from any app and the piece is
  queued and ready to play before the user opens the app.
- Player face — large cover art (generated or extracted), title,
  author, estimated runtime, voice picker, pace knob, chapter list,
  scrubbing timeline, play/pause/skip-15/back-15/skip-chapter/
  back-chapter, sleep timer.
- Voice picker (one tap, three options) — Warm / Focused / Casual,
  with a 6-second preview clip of each reading the article's opening
  line so the listener picks the right tone for the piece.
- Chapter skip — headings (`<h1>`–`<h4>` for HTML; outline tree for
  PDFs) become chapter markers. The listener can jump between
  chapters with one tap.
- Highlight-emphasis pipeline — Gemini 3.5 Flash reads the prose
  before TTS generation and emits a JSON map of `paragraph_index →
  emphasis_directive`. Directives are encoded as inline textual cues
  the expressive TTS model honours (italics-equivalent slight slow,
  inline emphasis on a single phrase via short pre-pause). Never more
  than 1-2 emphasis cues per paragraph.
- Quote-aware voicing — quoted material inside the prose is detected
  by the prose-analyser call and rendered with a slight tonal shift
  by prepending a short directive sentence to the TTS input for that
  segment (e.g. "the next sentence is a direct quotation; read it
  with a slightly more intimate timbre"). For interviews with two
  speakers, the second speaker's segments get a different voice
  selection within the same family.
- Reading-position persistence — the player remembers exactly where
  the listener stopped, to the second, across sessions and devices.
- Offline cache — generated MP3s saved on-device (IndexedDB on web,
  on-disk on mobile). Cache chip shows size and "downloaded" state.
- Background audio — Media Session API, lock-screen controls,
  Bluetooth headphone controls, Airpods double-tap, CarPlay /
  Android Auto when available.
- Sleep timer — 5 / 10 / 20 / 30 minutes or "end of chapter".
- Search-within-piece — full-text search over the parsed prose;
  tapping a match plays from that sentence.
- Listening queue — a simple linear queue of pieces; auto-advance to
  the next piece when the current one finishes.
- Listening history — what was listened to, when, how much. Local
  only; never sent to a server unless the user explicitly turns on
  cross-device sync.
- Per-piece "read everything verbatim" toggle — for listeners who
  want zero handoffs (every code block, table, footnote read in
  full).
- Per-piece "skip footnotes" toggle — for listeners who want a
  cleaner narrative pass; the footnotes are listed at the end and
  can be played as a single trailing segment.
- Article-cover generation — Nano Banana 2 generates a clean cover
  image for the piece based on the title and the first paragraph,
  used in lock-screen art and in the queue list.
- Cross-device sync (opt-in) — Firestore stores the listener's
  position and queue, syncs across devices when the user signs in
  with Google or Apple. Off by default.
- Personal-feed import — connect an RSS reader (Feedly, Inoreader,
  generic OPML upload) and saved-for-later items appear as a
  listening queue.
- One-tap "send to my phone" from a web session — when the listener
  pastes a URL on desktop and wants to listen on the walk home, a
  signed-in user can push the piece to their phone with one tap
  (Firestore real-time listener; no notifications needed).

## 4b. Required Gemini capabilities + backend services

**This template's intelligence comes from the Gemini capabilities
below. Wire them up explicitly — don't substitute generic LLM calls.**

### Gemini capabilities (the load-bearing intelligence)

- **Expressive TTS** (`gemini-3.1-flash-tts-preview`) — the
  load-bearing hero. Generates expressive, prosody-rich narration
  from plain prose at ~24 kHz output. Style is steered by a single
  one-sentence directive prepended to the input ("Read this with a
  warm, unhurried voice, like reading a friend's essay aloud on a
  walk. …"); there is no SSML in Gemini 3.1 Flash TTS — pauses are
  encoded as `…` for sentence breaks and blank-line `—` for paragraph
  breaks. The model produces noticeably more natural prosody than the
  prior `gemini-3.1-flash-tts-preview` (released 2026-04-15;
  pre-I/O 2026 templates used the older ID — replaced here).
- **Prose analyser + emphasis planner** (`gemini-3.5-flash`,
  thinkingLevel `medium`) — reads the parsed prose of the whole
  piece in a single 1M-context call and emits a structured
  `NarrationPlan` that describes per-paragraph metadata: paragraph
  type (body / heading / quote / footnote / code / table-handoff),
  emphasis directives (at most 1-2 per paragraph), voice handoff
  cues for multi-speaker interviews, chapter boundaries. **Guardrail**:
  a 60-page PDF or 30,000-word longform can run to ~100k tokens of
  prose; cap at 500k input tokens (well below the 1M ceiling) and if
  the parsed prose exceeds that, chunk on top-level headings and
  emit a per-chunk NarrationPlan, then concatenate.
- **URL / PDF prose extractor** (`gemini-3.5-flash`,
  thinkingLevel `low`, multimodal image/PDF input) — accepts the
  full PDF or fetched HTML and emits a structured `ParsedPiece`:
  title, author, publication, date, ordered list of `Paragraph`
  blocks with type and content. For PDFs the model reads page
  images directly via the Files API; for HTML the server pre-strips
  boilerplate (using a Readability-style heuristic) before sending
  the residual prose. **Multipage / multi-image input** uses the
  Gemini Developer API Files API (`files/*` resource name, e.g.
  `files/abc123xyz`, passed via `fileData: { fileUri, mimeType }`)
  for PDFs over 5MB; sub-5MB PDFs can be sent as `inlineData`
  (base64). NEVER pass Firebase Storage public URLs to
  `generateContent` — the API does not fetch them server-side.
  `gs://` URIs belong to Vertex AI / Cloud Storage — a different
  surface, not accepted on the Developer API.
- **Cover-art generator** (`gemini-3.1-flash-image`, Nano Banana 2) —
  generates a clean cover image for each piece based on title and
  first paragraph. Used in lock-screen art and queue thumbnails.
  Reserved hero use of `gemini-3-pro-image` (Nano Banana Pro) for
  the optional 4K poster export feature (see section 5).
- **Structured output / JSON Schema** — the prose extractor returns
  the `ParsedPiece` schema; the analyser returns the `NarrationPlan`
  schema. Both schemas are seeded verbatim in the system instruction
  and in `responseSchema`. Convert the Zod schema to Gemini's
  `Schema` type via the SDK helper before passing as
  `responseSchema` — do NOT pass raw Zod. Numeric `min`/`max`
  constraints in the schemas are documentation only; clamp on the
  server after the response arrives.
- **Thinking levels** — `medium` for the analyser (it must reason
  about emphasis, structure, speaker turns across the whole piece);
  `low` for the prose extractor (mechanical structure extraction);
  not applicable to TTS or image generation calls (TTS and image-gen
  models do NOT accept `thinkingConfig` — omit the field entirely).
- **Optional: streaming TTS** — the TTS call can stream PCM audio
  back as it generates so playback can start within ~3 seconds
  rather than waiting for the full file. The server forwards the
  PCM stream as a chunked HTTP response; the client wraps it in a
  Media Source Extensions buffer for the `<audio>` element and
  begins playback as soon as the first ~2 seconds of audio are
  buffered.

### Backend services

- **Auth — Required, but anonymous-first.** The first listen does
  NOT require sign-in. The listener pastes a URL and listens; the
  position is stored in `localStorage`. Sign-in is offered when the
  listener wants cross-device sync, a persistent queue, or to push
  a piece from desktop to phone. Firebase Auth with Google sign-in
  is auto-provisioned by AI Studio Build. Apple sign-in is optional
  but user-configured — it requires an Apple Developer account,
  Service ID, Key ID, and private key wired into the Firebase Auth
  console. Magic-link email is the cross-device sign-in fallback;
  the sender domain must be authorised in Firebase Auth.
- **Database — Required.** Firestore for `users`, `pieces`,
  `narration_plans`, `playback_positions`, `queues`. Auto-
  provisioned by AI Studio Build.
- **File storage — Required.** Firebase Storage for cached narration
  MP3s (server-side cache; clients hit signed URLs), uploaded PDFs,
  and cover images. **Storage is NOT auto-provisioned by AI Studio
  Build today** — enable it in the Firebase console and wire the
  bucket name into the AIS Build project before first PDF is
  uploaded. Pre-signed URLs only; no public-by-default access.
- **Cloud Run server functions — Required.** All Gemini API calls
  happen server-side; API key lives in Secrets Manager, never in
  client bundle. AI Studio Build auto-provisions these. **Free
  2-app Cloud Run deploy from Build** (post-I/O 2026 perk) covers
  the typical demo-tier deploy at no charge.
- **Email — Required (transactional).** Magic-link sign-in;
  optional weekly "what you didn't get to" digest for signed-in
  users. Sender domain authorised in Firebase Auth.
- **Payments — Not needed for v1.** A future "Plus" tier (longer
  PDFs, premium voice models, unlimited offline cache) might charge
  a small monthly fee via Stripe; not built in v1. The free tier
  caps each listener at 60 minutes of TTS per day, which the
  capabilities panel discloses transparently.
- **External APIs:** Gemini API for all intelligence; optional
  Mercury / Diffbot / Readability for the boilerplate-stripping
  pre-pass (server-side fallback only — the Gemini 3.5 Flash prose
  extractor handles boilerplate competently on its own; the
  external API is a defence-in-depth fallback for paywalled
  articles where the listener has supplied their own reader cookie).

**Environment variables:** every secret (Gemini API key, Firebase
service-account JSON, optional Mercury / Diffbot key, optional
Stripe key if Plus tier added) lives in environment variables —
never in client bundle. Include a `.env.example`.

**Auth + data privacy reminders:** never log secrets · never store
passwords in plain text · use HTTPS everywhere · honour 'delete my
account' inside the UI · explicit opt-in for any analytics · the
listener's URLs, PDF contents, listening history, and queue are
never sent to Gemini for model training (use the Gemini API on the
paid tier, where Google does not use your content for model
training, per the Gemini API Additional Terms) · uploaded PDFs are
held in Firebase Storage and deleted on listener request within 60
seconds via the "Delete this piece" control.

**Read this first — prompt-craft rules that apply to every call in
this template:**

1. **Name the model variant explicitly** in every Gemini API call.
   Do not let the agent pick the model. See the per-call matrix
   below.
2. **Pin `thinkingLevel` explicitly** per call. See the matrix.
   Models that don't take `thinkingConfig` (TTS, image-gen):
   omit the field entirely; the matrix row shows `n/a`.
3. **Seed the JSON Schema as a fenced TypeScript / Zod block** in
   the system instruction or `responseSchema` field. The literal
   schemas are below. **Convert the Zod schema to Gemini's
   `Schema` type via the SDK helper** before passing to
   `responseSchema` — do NOT pass raw Zod. **Numeric `min`/`max`
   constraints are documentation only inside `responseSchema`;
   clamp on the server after the response arrives.**
4. **Pin the system instruction separately** from user input. Use
   the `systemInstruction` field for persona + behavioural rules;
   use `contents` for user input. Never concatenate.
5. **Pre-declare tools as an enable/disable list** per call. The
   matrix below names which tools are enabled per call. Tools NOT
   listed for a call should be disabled.
6. **State negative constraints explicitly** — they are listed
   below. They are NOT "be careful" suggestions; they are hard
   rules the model must follow.
7. **`responseSchema` and `google_search` grounding are mutually
   exclusive in one call.** No call in this template needs both;
   if a future feature does, instruct the model to emit JSON in
   the text body and parse server-side, with citation URLs read
   from `response.groundingMetadata.groundingChunks[].web.uri`.
   Use this `safeExtractJSON` utility on any grounded JSON-in-text
   response:
   ```typescript
   function safeExtractJSON<T>(raw: string): T {
     const clean = raw.replace(/```json\s*|```/gi, '').trim();
     const s = clean.indexOf('{'); const e = clean.lastIndexOf('}');
     if (s === -1 || e === -1) throw new Error('No JSON boundaries in grounded response');
     return JSON.parse(clean.slice(s, e + 1)) as T;
   }
   ```
8. **Strip unsupported Zod modifiers before passing to
   `responseSchema`** — Gemini's OpenAPI subset rejects `.regex()`
   / `pattern`, fixed-length `z.tuple()`, and other custom
   validators. Use a sanitizer that flattens tuples to arrays and
   removes regex patterns before serializing. Validate those
   constraints in middleware AFTER parsing.
9. **Files API uses `files/*` resource names, not `gs://` URIs.**
   The AI Studio Build runtime uses the Gemini Developer API
   (`@google/genai` SDK). Files API `upload` returns a resource
   name of the form `files/abc123xyz`, passed via `fileData:
   { fileUri, mimeType }`. `gs://` URIs belong to Vertex AI /
   Cloud Storage — a different surface.

### Per-call model + tools matrix

| Call | Model | thinkingLevel | Tools enabled |
|------|-------|---------------|---------------|
| URL → `ParsedPiece` (HTML extractor, post-boilerplate-strip) | `gemini-3.5-flash` | low | (none) |
| PDF → `ParsedPiece` (multimodal pages via Files API) | `gemini-3.5-flash` | low | (none) |
| `ParsedPiece` → `NarrationPlan` (prose analyser + emphasis planner) | `gemini-3.5-flash` | medium | (none) |
| `NarrationPlan` segment → MP3 audio (expressive TTS) | `gemini-3.1-flash-tts-preview` | n/a | n/a |
| Cover-art generation (per piece, cached) | `gemini-3.1-flash-image` | n/a | n/a |
| Optional 4K poster export (one-off, listener-initiated) | `gemini-3-pro-image` | n/a | n/a |

*Note for builders:* on TTS and image-generation calls, omit
`thinkingConfig` entirely — the field is not supported on those
models. The `n/a` cells in this matrix are documentation only; do
not serialise them into the request body. TTS pauses are encoded
as `…` (sentence) and blank-line `—` (paragraph) since Gemini 3.1
Flash TTS has no SSML. The single per-piece voice directive (Warm /
Focused / Casual) is prepended as a one-sentence style instruction
inside the TTS input itself — there is no separate `style` API
field.

### Primary structured-output schemas (seed verbatim in the prompt)

```typescript
import { z } from "zod";

const ParagraphType = z.enum([
  "title",                        // the piece title
  "byline",                       // author / publication / date
  "heading_1",                    // top-level section heading
  "heading_2",                    // sub-section heading
  "heading_3",                    // sub-sub-section heading
  "heading_4",                    // deeper heading
  "body",                         // normal prose paragraph
  "blockquote",                   // pulled-out quotation block
  "inline_quote_run",             // a paragraph dominated by quoted dialogue
  "list_item",                    // one item in a bulleted / numbered list
  "footnote_marker",              // an in-line footnote reference
  "footnote_body",                // the text of a footnote (rendered at the end)
  "code_block",                   // code; default skipped with handoff
  "table",                        // tabular data; default skipped with handoff
  "figure_caption",               // caption attached to a figure
  "image_alt",                    // alt text for a figure; spoken if useful
  "equation_block",               // a display equation; default skipped
  "pull_quote",                   // a pulled-out emphasis quote
  "interview_speaker_tag",        // "DR. ALI:" — a speaker label in dialogue
  "interview_turn_body",          // the speaker's utterance after the tag
  "section_break",                // a horizontal rule or asterisk break
  "skip_marker",                  // explicitly skipped content (e.g. paywall)
]);

const EmphasisDirective = z.object({
  span_start_char: z.number(),                    // offset in the paragraph text
  span_end_char: z.number(),                      // offset (exclusive)
  kind: z.enum([
    "lift",                                        // gentle emphasis on this phrase
    "slow",                                        // slight slow-down for this phrase
    "intimate",                                    // quieter, closer timbre
    "deliberate",                                  // each word slightly more weighted
  ]),
  reason: z.string(),                              // why the analyser chose this
});

const Paragraph = z.object({
  paragraph_index: z.number(),                     // 0-indexed, contiguous
  type: ParagraphType,
  text: z.string(),                                // the prose, exactly as it will be read
  speaker_id: z.string().nullable(),               // for interview_turn_body, etc.
  chapter_index: z.number(),                       // which chapter this belongs to
  emphasis_directives: z.array(EmphasisDirective), // 0-2 entries per paragraph
  is_quoted: z.boolean(),                          // true for blockquote / inline_quote_run
  handoff_summary: z.string().nullable(),          // for code / table / equation
});

const Chapter = z.object({
  chapter_index: z.number(),
  title: z.string(),
  starts_at_paragraph: z.number(),
  ends_at_paragraph: z.number(),
});

const Speaker = z.object({
  speaker_id: z.string(),                          // "dr_ali", "interviewer"
  display_name: z.string(),                        // "Dr. Ali"
  suggested_voice_variant: z.enum(["primary", "secondary"]),
});

const ParsedPiece = z.object({
  source_kind: z.enum(["url", "pdf", "raw_text"]),
  source_locator: z.string(),                      // URL or storage path
  title: z.string(),
  author: z.string().nullable(),
  publication: z.string().nullable(),
  published_iso: z.string().nullable(),            // ISO-8601 if known
  language: z.string(),                            // BCP-47, e.g. "en-US"
  estimated_word_count: z.number(),
  paragraphs: z.array(Paragraph),
  chapters: z.array(Chapter),
  speakers: z.array(Speaker),                      // empty for non-interviews
  is_multi_speaker: z.boolean(),
  has_footnotes: z.boolean(),
  has_code: z.boolean(),
  has_tables: z.boolean(),
  has_equations: z.boolean(),
  parse_confidence: z.number().min(0).max(1),
  flagged_for_user_review: z.array(z.object({
    paragraph_index: z.number(),
    reason: z.string(),
  })),
});

const VoicePreference = z.enum(["warm", "focused", "casual"]);

const NarrationSegment = z.object({
  segment_index: z.number(),                       // 0-indexed contiguous
  chapter_index: z.number(),
  starts_at_paragraph: z.number(),
  ends_at_paragraph: z.number(),
  speaker_id: z.string().nullable(),
  voice_directive_sentence: z.string(),            // prepended to TTS input verbatim
  rendered_text_with_pause_cues: z.string(),       // text with `…` and `—` baked in
  estimated_duration_seconds: z.number(),
});

const NarrationPlan = z.object({
  piece_id: z.string(),
  voice_preference: VoicePreference,
  target_words_per_minute: z.number().min(80).max(220),
  skip_footnotes: z.boolean(),
  skip_code_blocks: z.boolean(),
  skip_tables: z.boolean(),
  segments: z.array(NarrationSegment),
  total_estimated_duration_seconds: z.number(),
  planner_notes: z.array(z.string()),              // analyser's structural notes
  planner_confidence: z.number().min(0).max(1),
});

type ParsedPiece = z.infer<typeof ParsedPiece>;
type NarrationPlan = z.infer<typeof NarrationPlan>;
```

### Common failure modes (and how to avoid them)

- Agent picks `gemini-3.5-flash` or `gemini-3.5-flash` (legacy pre-I/O
  strings) for the extractor / analyser — those endpoints are
  deprecated. Pin `gemini-3.5-flash` explicitly. The post-I/O 2026
  Flash tier beats the previous Pro tier on multimodal benchmarks
  and is the right default for both prose extraction and the
  emphasis planner.
- Agent passes the old `gemini-3.1-flash-tts-preview` for narration
  to "save money" — the new `gemini-3.1-flash-tts-preview` is the
  expressive TTS the template's value proposition depends on. Pin
  it explicitly. The older model is markedly flatter.
- Agent tries to use SSML `<break time="…">` or `<emphasis>` tags
  inside the TTS input — Gemini 3.1 Flash TTS does not support
  SSML. The system instruction must encode pauses as `…` for
  sentence-end and a blank line plus `—` for paragraph-end. Emphasis
  is conveyed via the one-sentence style directive at the top and
  via subtle textual cues inside the line (e.g. slight slow on a
  comma-fronted clause), not via tags.
- The analyser proposes too much emphasis — the schema caps
  `emphasis_directives` at 2 per paragraph; the server enforces
  this and discards any third entry. Over-emphasis sounds theatrical
  and breaks trust; 1-2 per paragraph is the production setting.
- The extractor reads PDF page images and silently rewrites prose
  to be more readable — the system instruction must require that
  `text` is the verbatim prose from the page. Where a hyphenated
  line-break splits a word, rejoin the word; where a page-break
  splits a paragraph, join the paragraphs; do NOT paraphrase, do
  NOT shorten, do NOT correct grammar.
- Listener pastes a URL behind a paywall — the server falls back to
  the user's own reader cookie (passed via authenticated session)
  if configured, or reports the failure honestly: "this URL is
  behind a paywall we can't bypass — paste the text directly or
  download the PDF". The system never silently produces a summary
  in place of the actual content.
- The cover-art generator depicts a person and the listener finds it
  uncanny — the cover-art system instruction forbids depicting
  identifiable people and prefers abstract / typographic /
  landscape compositions. Falls back to a clean typographic cover
  if generation fails.
- Footnotes interrupt narration flow — by default, footnote bodies
  are NOT read in-line; the analyser sets `paragraph.type =
  "footnote_marker"` for the reference and inserts a one-line
  spoken handoff: "footnote 14, three sentences, tap to expand".
  The footnote bodies are rendered as a trailing segment after the
  main piece, so listeners who want them get them at the end.
- Code blocks get read out character-by-character — the default
  behaviour skips code blocks with a one-line spoken handoff. A
  per-piece toggle "read everything verbatim" exists for listeners
  who want code read; the system instruction respects this toggle.
- A multi-speaker interview gets one voice and the listener loses
  track of who is talking — the extractor sets
  `is_multi_speaker: true` and populates `speakers[]` and
  `paragraphs[*].speaker_id`. The analyser uses the
  `voice_directive_sentence` per segment to swap between "primary"
  and "secondary" voice variants within the chosen family.
- TTS generation times out on a 30-minute piece — the server splits
  the narration into per-chapter or per-15-minute segments, generates
  them in parallel, and stitches the resulting MP3s back together
  client-side via the audio buffer queue. The user perceives one
  continuous narration.
- The listener's URL points to a video page (YouTube, Vimeo) — the
  system instruction makes the extractor return `source_kind: "url"`
  with a `flagged_for_user_review` entry: "this URL appears to be a
  video; we read text, not video". A future capability could pass
  the YouTube URL to the multimodal model for transcription, but
  v1 declines the input honestly rather than silently fail.

### Negative constraints (hard rules)

- Do NOT skip, paraphrase, condense, or "improve" the author's prose.
  Every word the author wrote must be read, in order, unless the
  paragraph type is explicitly `code_block`, `table`, `equation_block`,
  or `footnote_body` AND the listener has opted to skip that
  category. The "every word" contract is the load-bearing trust of
  this app.
- Do NOT use SSML tags inside the TTS input. Gemini 3.1 Flash TTS
  does not support SSML. Encode pauses as `…` (sentence) and
  blank-line `—` (paragraph). Style comes from the one-sentence
  directive prepended to the input.
- Do NOT pass Firebase Storage public URLs to `generateContent`.
  Use the Gemini Developer API Files API (`files/*` resource
  name via `fileData.fileUri`) for PDFs over 5MB; use
  `inlineData` (base64) for smaller PDFs. `gs://` URIs are not
  accepted on the Developer API surface.
- Do NOT chain `responseSchema` with `google_search` grounding in
  the same call. They are mutually exclusive. No call in this
  template uses grounding; if a future feature adds one, the
  model emits JSON in the text body and the server parses it.
- Do NOT auto-summarise. Summarisation is a separate, future
  feature, opt-in per piece, surfaced as a clearly different
  "Summary mode" — never silently replace narration with
  summary.
- Do NOT use the listener's URLs, PDFs, prose, or listening
  history to train or fine-tune any model. Use the Gemini API on
  the paid tier, where Google does not use your content for model
  training, per the Gemini API Additional Terms. The capabilities-
  info panel says this in plain English.
- Do NOT auto-play. Audio playback always requires an explicit
  user gesture. Auto-play violates browser policies and is
  hostile.
- Do NOT translate the author's prose. Read it in its native
  language using the matching TTS locale voice. Translation is a
  separate, future, opt-in feature.
- Do NOT depict real identifiable people in cover art. The cover-
  art prompt forbids portraits, uses abstract / typographic /
  landscape compositions, and falls back to a clean typographic
  cover on any prompt the model flags.
- Do NOT cache a copyrighted PDF on a server unless the listener
  uploaded it themselves. URL-fetched articles are processed
  in-memory and only the listener's own playback position and
  per-piece NarrationPlan are persisted; the underlying prose is
  not retained server-side beyond the generation window unless the
  listener turns on cross-device sync.
- Do NOT propose accessibility shortcuts that bypass screen
  reader behaviour. The narration coexists with screen readers
  — both must work cleanly.
- Do NOT read tracker-blocked sentences, GDPR consent banners,
  cookie notices, or footer chrome from web pages. The extractor
  must strip boilerplate before narration.
- Do NOT auto-renew offline downloads on cellular. Cellular
  downloads require an explicit per-piece tap.

<!--SYSINSTR-START-->

### Per-call `systemInstruction` strings

Use these as the literal `systemInstruction` field for each Gemini
API call the built app makes. They complement the series-wide
rules already uploaded as the global instructions file
(`00-series-instructions.txt`).

### Call: URL → `ParsedPiece` (HTML extractor)
Model: `gemini-3.5-flash` · thinkingLevel: low · Tools: (none)

```
You receive the already-boilerplate-stripped HTML of an article,
essay, newsletter, blog post, Wikipedia page, or news piece. The
server has run a Readability-style heuristic to remove navigation,
sidebars, comment sections, related-content modules, cookie
banners, and advertising chrome. Your job is to parse the remaining
prose into a structured ParsedPiece JSON object.

Inputs:
- source_kind: "url"
- source_locator: the original URL string
- the stripped HTML body
- a one-line context header: e.g. "Substack post, English"

Output: a single ParsedPiece JSON matching the provided schema.

Hard rules:
- `paragraph.text` is the VERBATIM prose. Rejoin hyphenated line
  breaks ("re-\nadable" → "readable"). Rejoin paragraphs split by
  rendering hacks. Do NOT paraphrase. Do NOT shorten. Do NOT
  correct the author's grammar or spelling.
- Classify each paragraph by `type` per the schema enum. Headings
  get `heading_1` through `heading_4` matching the HTML heading
  level. Pulled-out quotations get `blockquote`. Lists get
  `list_item` per item.
- Detect footnote markers (numbered or symbolic) and create a
  `footnote_marker` paragraph at the reference site and a
  `footnote_body` paragraph at the end of the piece.
- Detect inline code (`<code>`) and code blocks (`<pre><code>`).
  Code blocks become `code_block` with the verbatim code in
  `text` and a `handoff_summary` like "twelve lines of TypeScript
  defining a User type".
- Detect tables and create `table` paragraphs with a
  `handoff_summary` ("a 3-column table comparing three voice
  models"); preserve the table prose in `text` for listeners who
  toggle "read everything verbatim".
- Detect interview / dialogue structure when speaker labels are
  consistent ("DR. ALI:", "Q:", "JANE:"). When detected, set
  `is_multi_speaker: true`, populate `speakers[]` with display
  names, and tag each turn with `speaker_id`.
- Compute `chapters[]` from heading_1 / heading_2 boundaries.
  Pieces with no headings get one default chapter "Full piece".
- `parse_confidence` reflects the cleanness of the source.
  Boilerplate-heavy pages get lower confidence; clean essays get
  higher. Below 0.6 → flag for user review with specific reasons.
- Do NOT translate. Read the prose in its source language; set
  `language` to the BCP-47 code.
- Do NOT invent author / publication / date metadata if not
  present. Leave nullable fields null.
- Do NOT include cookie consent text, GDPR banners, paywall
  prompts, newsletter signup forms, or "subscribe to read more"
  blocks. Treat as boilerplate and skip.
- The piece's first paragraph after the byline becomes the lede.
  Do NOT promote a subheading or pull-quote to the title position.

Output ONLY the ParsedPiece JSON. No commentary. JSON only.
```

---

### Call: PDF → `ParsedPiece` (multimodal pages via Files API)
Model: `gemini-3.5-flash` · thinkingLevel: low · Tools: (none)

```
You receive a PDF — up to 200 pages — passed via the Gemini
Developer API Files API as a `files/*` resource name (e.g.
`files/abc123xyz`) via `fileData: { fileUri, mimeType:
"application/pdf" }`, or as `inlineData` for sub-5MB files. Your
job is to read the pages directly and parse the prose into a
structured ParsedPiece JSON object.

Inputs:
- source_kind: "pdf"
- source_locator: the `files/*` resource name or "inline"
- the PDF itself
- a one-line context header: e.g. "academic paper, English, 40
  pages, single column"

Hard rules:
- Read every page in order. Stitch column breaks cleanly: if the
  page is two-column, the natural reading order is left column
  fully, then right column fully, not zig-zag.
- Rejoin paragraphs split by page breaks. A paragraph that ends
  mid-sentence at the bottom of a page and continues at the top
  of the next page is ONE paragraph in the output.
- Rejoin hyphenated line breaks within words.
- Headings, sub-headings, and sub-sub-headings get `heading_1`,
  `heading_2`, `heading_3` per the visual hierarchy on the page.
  Section numbers (e.g. "3.2.1") become part of the heading
  text, not a separate paragraph.
- Captions under figures become `figure_caption`. Alt-text where
  available becomes `image_alt`. The figure itself is NOT
  narrated; the caption is, and a one-line handoff is inserted
  ("figure 3, a scatter plot of voice naturalness scores, tap to
  view").
- Equations get `equation_block` with the source LaTeX or
  Unicode in `text` if extractable, and a `handoff_summary`
  ("a display equation; the gradient of a loss function with
  respect to model parameters"). Equations are NOT narrated by
  default.
- Tables get `table` with a `handoff_summary` and the cell prose
  preserved in `text`.
- Footnotes / endnotes — recognise marker positions in the body
  and create `footnote_marker` paragraphs there; gather the
  footnote bodies (typically at the bottom of each page or at
  the end of the document) into `footnote_body` paragraphs at
  the end of the piece, numbered to match.
- Do NOT paraphrase or summarise. Verbatim prose only.
- Do NOT translate.
- Do NOT skip pages with figures. Read the figure captions; the
  body text on figure-heavy pages is just as important as on
  prose pages.
- If a page is unreadable (low-quality scan, handwriting,
  watermark obscuring text), create a `skip_marker` paragraph
  with a `handoff_summary` ("page 17 unreadable, scan quality
  poor — tap to view the original").
- `parse_confidence` reflects scan quality and structural
  cleanness. Scans below DPI ≈ 200 get lower confidence.

Output ONLY the ParsedPiece JSON. No commentary. JSON only.
```

---

### Call: `ParsedPiece` → `NarrationPlan` (prose analyser + emphasis planner)
Model: `gemini-3.5-flash` · thinkingLevel: medium · Tools: (none)

```
You receive a ParsedPiece JSON and three listener preferences:
- voice_preference: "warm" | "focused" | "casual"
- target_words_per_minute: integer 80-220 (default 130)
- skip_footnotes / skip_code_blocks / skip_tables: booleans

Your job is to emit a NarrationPlan: an ordered list of
NarrationSegments, each with a one-sentence voice directive and
a `rendered_text_with_pause_cues` field that bakes in the textual
pause and emphasis cues for the TTS model. The TTS model
(`gemini-3.1-flash-tts-preview`) does NOT support SSML — pauses
and emphasis come from textual cues and the prepended directive
sentence.

Hard rules for `rendered_text_with_pause_cues`:
- End every sentence with "…" (a literal Unicode ellipsis) to
  cue a natural sentence-end pause. The TTS model interprets the
  ellipsis as a slight breath.
- End every paragraph with a blank line followed by "—" (em dash)
  on its own line, then continue. The blank line plus em dash
  cues a longer paragraph-break breath.
- For headings, surround with two blank lines before and after.
- For blockquote / inline_quote_run paragraphs, prepend a soft
  cue inside the text: "the next passage is a direct quotation"
  is too literal — instead, rely on the per-segment voice
  directive sentence to convey the timbre shift, and bracket the
  quote with em dashes for visual rhythm.
- For emphasis_directives, encode `lift` as a hyphen-space prefix
  on the emphasised phrase (subtle), `slow` as a comma-space
  prefix and a comma-space suffix (cues slight slow-down),
  `intimate` via the segment-level voice directive, `deliberate`
  by inserting an ellipsis between each word of the emphasised
  phrase — but use sparingly; at most one emphasis directive per
  paragraph is rendered to the TTS layer.

Hard rules for `voice_directive_sentence` per segment:
- Always one short sentence, ≤ 18 words. Always English. Always
  imperative. Always ends with "…" so the model picks up the
  pacing cue right away.
- For voice_preference: "warm" — "Read this with a warm,
  unhurried voice, like reading a friend's essay aloud on a
  walk. …"
- For voice_preference: "focused" — "Read this with a calm,
  clear, professional voice, paced for close listening. …"
- For voice_preference: "casual" — "Read this conversationally,
  like chatting to a friend in a café. …"
- For a blockquote / inline_quote_run segment, append: "The
  next passage is a direct quotation; read it with a slightly
  more intimate timbre. …"
- For a heading_1 / heading_2 segment, append: "This is a
  section heading; lift slightly and then settle. …"
- For interview_turn_body of the secondary speaker, append:
  "This is a different speaker; subtly shift voice timbre
  while keeping the same pace and style. …"

Hard rules for segment boundaries:
- A segment groups consecutive paragraphs that share the same
  voice directive. A speaker change ends a segment; a heading
  ends the prior segment and starts a new one; a long
  blockquote becomes its own segment.
- Aim for segments of 60-300 seconds of estimated audio. Very
  short segments (e.g. one-sentence headings) are fine; very
  long segments (>5 min) should be split on the nearest
  paragraph boundary so the client can begin playback within
  3 seconds of the first segment finishing generation.

Hard rules for `estimated_duration_seconds`:
- Compute as `words / (target_words_per_minute / 60)`.
- Round to one decimal.

Hard rules for content selection:
- If skip_footnotes is true, footnote_marker paragraphs become
  one-line handoffs ("footnote 14, three sentences, tap to
  expand"); footnote_body paragraphs become a single trailing
  segment after the piece.
- If skip_code_blocks is true, code_block paragraphs become
  one-line handoffs ("code block, twelve lines of TypeScript,
  tap to read").
- If skip_tables is true, table paragraphs become one-line
  handoffs ("a 3-column table, tap to view").
- Equation blocks ALWAYS become one-line handoffs (equations do
  not narrate naturally).
- `skip_marker` paragraphs always become one-line handoffs.

Do NOT:
- Do NOT change the author's words. Every word in
  `paragraph.text` for narrated paragraphs must appear in
  `rendered_text_with_pause_cues`. Only the pause and emphasis
  cues are inserted; nothing is removed.
- Do NOT translate.
- Do NOT add commentary, introductions, or sign-offs ("Today
  we'll be reading…", "That was…").
- Do NOT propose more than 2 emphasis directives per
  paragraph; the schema caps at 2 and the server enforces.

Output ONLY the NarrationPlan JSON. No commentary. JSON only.
```

---

### Call: `NarrationPlan` segment → MP3 audio (expressive TTS)
Model: `gemini-3.1-flash-tts-preview` · n/a · n/a

```
You receive one NarrationSegment as input. The input you generate
audio for is constructed as:

    {voice_directive_sentence}
    {rendered_text_with_pause_cues}

Where `voice_directive_sentence` is the one-sentence style
directive the analyser produced (e.g. "Read this with a warm,
unhurried voice, like reading a friend's essay aloud on a walk.
…"), and `rendered_text_with_pause_cues` is the segment's prose
with `…` for sentence pauses and blank-line `—` for paragraph
pauses already baked in.

Pre-processing (server-side, BEFORE the text reaches TTS):
- Run a markdown-stripping preprocessor on every paragraph
  before passing to TTS. Remove:
  - `#` heading markers (`# Title` → `Title`)
  - `**bold**` / `__bold__` / `*italic*` / `_italic_` markers
    (`**word**` → `word`; do not voice-emphasise here — emphasis
    comes from the directive sentence)
  - `[link text](url)` → keep just `link text`; drop the URL
  - ` ```code blocks``` ` → replace the whole block with the
    phrase "code sample omitted"
  - inline ` `code spans` ` → keep just the inner text
  - `>` blockquote markers (strip the `>` prefix; keep the text)
  - table pipes `|` and separator rows (`|---|`) → flatten to
    sentences if the table is small, otherwise replace with
    "table omitted — see written piece"
  - lingering HTML entities (`&amp;` → `&`, `&nbsp;` → ` `)
- After stripping, insert the pause markers `…` (short pause)
  and blank-line `—` (paragraph break) as already specified by
  the NarrationPlan. The pause markers must NEVER survive into
  the visible written piece — they live only in the TTS input.

Voice selection:
- Pick the TTS voice whose locale matches the piece's `language`.
  English-language pieces get an English voice; French-language
  pieces get a French voice; etc.
- Within the locale, prefer voices labelled with the
  voice_preference family (warm / focused / casual). If exact
  family voices are not available in a given locale, fall back
  to the locale's most natural-sounding default voice.

Pace:
- Target ~130 wpm by default (set via `target_words_per_minute`).
  The directive sentence anchors pace; the textual ellipses and
  paragraph dashes anchor breath. The model adjusts pace based
  on these cues without an explicit rate parameter.

Phoneme overrides:
- Gemini 3.1 Flash TTS does not expose `<phoneme>` overrides. If
  the prose contains proper nouns or technical terms with
  unusual pronunciation, rely on the voice's native locale to
  handle them. Where confidence is low, the listener can
  contribute a per-piece pronunciation hint in a future
  feature.

Hard rules:
- Output audio only. Return the audio stream / MP3 file.
- Do NOT skip text. Do NOT paraphrase. Read every word.
- Do NOT inject pauses beyond what the textual cues request.
  Long pauses break flow.
- Do NOT change emotional register mid-segment. The directive
  sentence at the top of the input sets the register; honour
  it for the whole segment.

Output: PCM audio at 24 kHz (decoded server-side and re-encoded
as MP3 for storage and playback).
```

---

### Call: Cover-art generation (per piece, cached)
Model: `gemini-3.1-flash-image` · n/a · n/a

```
You generate ONE cover image for an article, essay, newsletter,
or PDF. The cover is shown in the listener's queue, on the
player face behind a soft scrim, and as the lock-screen art
when audio is playing in the background.

Inputs you receive:
- title: the piece title
- author: the piece author (or null)
- first_paragraph: the opening paragraph, truncated to 400 chars
- voice_preference: "warm" | "focused" | "casual"

Prompt anchors:
- For "warm" (essays, memoir, newsletters): "soft natural light,
  warm domestic textures, a hint of paper or fabric or wood,
  shallow depth of field, no people, no faces, abstract
  composition referring obliquely to the piece's subject"
- For "focused" (research, technical writing): "clean
  typographic composition, generous whitespace, calm muted
  palette, a single subtle geometric or diagrammatic element,
  no people, no faces"
- For "casual" (blogs, light essays): "playful flat composition,
  a single iconic object or scene, friendly palette, no
  people, no faces"

Aspect ratio: 1:1 (used as queue thumbnail and lock-screen art).

Hard rules:
- NO identifiable people. No portraits. No human faces. Fall
  back to typography or landscape if the prompt evokes a
  person.
- NO commercial branding visible (no real brand logos, no
  product packaging).
- NO text rendered in the image (Nano Banana 2 cannot reliably
  render legible text at this tier; reserve text-in-image for
  the optional 4K poster export call which uses
  `gemini-3-pro-image`).
- Warm, slightly imperfect, organic lighting; avoid the glossy
  AI-render look.
- Avoid clichés: no glowing orbs, no neon gradients, no
  geometric "AI brain" imagery, no robot illustrations.

If generation fails or the image is rejected by safety, return a
clean typographic fallback: title set in serif over a soft
neutral background.
```

---

### Call: Optional 4K poster export (listener-initiated)
Model: `gemini-3-pro-image` · n/a · n/a

```
You generate a high-quality 4K poster (3840 × 2160) for a single
piece, designed to be hung on a wall or shared as a "best
articles of the year" image. This is the only call in the
template that uses Nano Banana Pro — reserved for the listener's
explicit "Save as poster" action, not run automatically.

Inputs you receive:
- title: the piece title
- author: the piece author
- publication: the publication or source
- a short quote (≤120 chars) the listener has pinned from the
  piece

Prompt anchors:
- Render the title at large size in a serif typeface, legible at
  4K (Nano Banana Pro's post-I/O-2026 hero capability: legible
  in-image text).
- Render the author and publication smaller, beneath the title.
- Render the pinned quote in italics, below the byline.
- Background: a calm abstract composition referring obliquely to
  the piece's subject (no people, no faces, no commercial
  branding).

Hard rules:
- Text MUST be legible at 4K. Title, byline, and quote are all
  in-image text.
- NO identifiable people.
- NO commercial branding.
- ONE poster per call; do not produce variants. The listener
  re-rolls by tapping "regenerate" if unhappy.
- Output: 3840 × 2160 PNG.
```

<!--SYSINSTR-END-->

## 5. Use cases & content to include

Build dedicated UI sections or flows for each of these — they tell
you what content the app must support.

- **Morning walk to the station.** A commuter has saved a 4,200-word
  essay on city planning to "read later" three weeks ago. On the
  morning walk they paste the URL into the app, tap "warm", tap
  play. Within three seconds the narration starts. They lock the
  phone, slip it into their coat pocket, and walk to the station
  for twenty-eight minutes. The piece finishes at the platform.
- **Pre-meeting paper, on a run.** A PhD student has a 38-page
  PDF to read before a 3 pm lab meeting. At noon they drop the
  PDF into the app, pick "focused" voice, set pace to 140 wpm,
  and run for forty-five minutes. The narration handles the
  abstract, the introduction, the methods (skipping the
  equation-heavy half-pages with one-line handoffs), the
  results, and the discussion. Figures get one-line spoken
  handoffs the runner can flag to re-open at their desk. They
  form a working opinion before the meeting.
- **Sunday dishes, three newsletters.** A parent has three
  Substack posts in the queue. The app reads them back-to-back
  while the dishes get done — twenty-two minutes of audio, one
  in a Manchester writer's longform voice, one in a New York
  essayist's, one in a São Paulo journalist's. Each piece's
  cover appears on the lock-screen as it plays; the parent
  catches the queue advancing with one glance from across the
  kitchen.
- **The interview piece.** A long-form magazine interview with
  two speakers — the journalist and the subject — is parsed
  with `is_multi_speaker: true`. The analyser tags each turn
  with a `speaker_id`. The TTS uses a "primary" voice variant
  for the journalist and a "secondary" variant for the subject.
  The listener follows the conversation without effort.
- **The footnote-heavy academic essay.** A 9,000-word essay on
  philosophy of mind has 47 footnotes. The listener picks "skip
  footnotes" before tapping play; footnote markers become one-
  line spoken handoffs ("footnote 14, two sentences, tap to
  expand"); the full footnote bodies play as a single trailing
  segment after the main essay, for completeness. The listener
  hears the argument cleanly and then decides which footnotes
  to revisit.
- **The flight without WiFi.** A frequent flyer queues five
  pieces the night before a transatlantic flight, taps
  "download" on each (the offline-cache chip shows MB size and
  percent), and at 35,000 feet listens through all five without
  a connection. The Media Session API drives the in-flight
  entertainment controls; lock-screen art is in place.
- **The post-concussion reader.** A reader with post-concussion
  symptoms cannot tolerate screens for more than a few minutes
  but wants to keep up with reading. They paste URLs from
  their reading list via the share extension. The expressive
  narration with paragraph breaths is calming where flat
  robotic TTS would be agitating; the play-pause control is
  large and high-contrast; reduced-motion is honoured.
- **The book-length PDF.** A 180-page non-fiction PDF book is
  uploaded. The extractor pulls 12 chapters from the table of
  contents; the analyser splits each chapter into segments of
  5-10 minutes; the player exposes the chapter list as a
  navigable index. The reader works through it over a week of
  evening walks.
- **The paywalled article.** A listener pastes a URL behind a
  paywall they have not authenticated with. The fetcher
  reports the failure honestly: "this URL appears to be behind
  a paywall we can't bypass — paste the text directly or
  upload the PDF". The app NEVER silently produces a summary
  from the article's preview snippet.
- **The "send to my phone" handoff.** Desktop session: the
  listener pastes a URL, browses the cover art and chapter
  list, but is heading out for a walk. They tap "send to my
  phone" — the piece appears in the queue on the phone within
  a second (Firestore real-time listener), ready to play when
  they open the app on the walk.
- **The cover-poster export.** After listening to a piece they
  particularly loved, the listener pins a single short quote
  and taps "Save as poster". The optional 4K-poster export
  (Nano Banana Pro) generates a 3840 × 2160 PNG with the
  title, author, and pinned quote rendered as legible
  in-image text, ready to print or share. The poster export
  is one tap, ten seconds, $0.10 of generation cost — the only
  call in the app that uses Nano Banana Pro.

## 6. Page structure

Build the following screens / sections in this order. Adjust copy
to fit the voice, but keep the structural intent.

1. **Landing / first-paste.** A clean, single-input screen.
   Top: the wordmark, set in a display serif. Centre: a single
   text input with the placeholder "Paste a URL or drop a
   PDF". A subtle dotted border indicates the drop zone. One
   secondary action below: "Try with a sample piece →" (loads
   the demo piece in section 8a). No sign-in gate. No "AI"
   badge. No marketing copy. The promise is in the doing.
2. **Voice-and-pace chooser.** After paste / drop, the piece is
   parsed (a 3-second progress arc shows "reading the piece…",
   "finding chapters…", "planning the narration…"). Three
   voice cards appear: Warm (illustration: warm light through
   a window), Focused (illustration: a desk lamp on an open
   book), Casual (illustration: a café table with two
   coffees). Tap any card to hear a 6-second preview reading
   the article's opening line. Below: a pace knob (default
   130 wpm, range 80-220), and three checkboxes (read
   footnotes inline / skip footnotes; read code blocks / skip;
   read tables / skip). Big "Read this to me" button at the
   bottom.
3. **Player face.** Full-screen cover art at top, with a soft
   scrim. Title and author below. Estimated runtime. Pace
   readout next to a small +/- nudge (live, no settings
   detour). Voice readout next to a tap-to-swap chip. Full
   scrubbing timeline with chapter markers as faint vertical
   lines. Play / pause / skip-15 / back-15 / skip-chapter /
   back-chapter controls. Sleep timer button. Download chip
   (MB size, percent cached). A small "transcript" toggle in
   the corner exposes the rendered prose as a scrolling
   transcript synced to the audio cursor (accessibility +
   reading-along usage).
4. **Queue.** A vertical list of pieces the listener has
   queued, each with cover, title, author, estimated runtime,
   and a tap-to-play arrow. Drag-to-reorder. Swipe to remove.
   Tap "play queue" at the top to play all in order.
5. **Listening history.** A simple chronological list of
   pieces the listener has finished or partially listened to,
   with completion percentages and last-played timestamps. Tap
   to resume. Local-only by default; signed-in users see
   cross-device history.
6. **Search-within-piece.** Inside the player, a search icon
   opens a full-text search over the parsed prose. Matches
   show with surrounding sentence context; tap a match to play
   from that sentence.
7. **Library import.** A modal accessible from the queue:
   "Import from your RSS reader". Options: Feedly, Inoreader,
   generic OPML upload. Once authorised, saved-for-later
   items become a feed the listener can selectively queue
   from.
8. **Cross-device sync.** A modal accessible from settings:
   "Listen on more than one device". One paragraph explains
   sync (Firestore-backed, only the position and queue, never
   the prose). Google sign-in button; Apple sign-in next to
   it; magic-link email below.
9. **Settings & privacy.** Default voice preference, default
   pace, default skip-footnotes / skip-code / skip-tables.
   "Cellular download policy": ask each time / always
   download / never download on cellular. "Listening history":
   keep / clear all. "Delete this piece" buttons next to
   uploaded PDFs. "Delete my account" with a 60-second
   cool-off. Privacy panel restates the not-trained-on policy
   in plain English.
10. **Capabilities panel.** Same as 6c — the persistent `(i)`
    icon opens it. Names every Gemini model used, every
    Firebase service, and the per-piece cost.
11. **Footer.** "Made for the walk to the station. And the
    dishes. And the flight." Privacy: "Your URLs, PDFs, and
    listening history are yours. We never train on them."
    Capabilities `(i)` icon in header.

## 6b. First-visit onboarding

Show a **first-visit onboarding** the first time a visitor lands
on the app (detect via `localStorage` flag; do not show on return
visits). Three slides, dismissible at any time. Persistent
re-entry: a `?` icon in the header reopens it.

**Slide 1 — What this is.**
- Headline: "Welcome to Read This To Me."
- Subhead: "Paste a URL, drop a PDF. Walk away with the essay
  read to you — at walking pace, in a real human-feeling voice,
  every word."
- One paragraph (≤ 60 words) explaining who this is for and
  what makes it different from stock TTS: the expressive
  post-I/O 2026 voice model with real prosody, the
  every-word-no-shortcuts contract, the walk-paced default,
  the lock-screen-friendly background audio, and the offline
  cache for flights.
- Visual: a small annotated illustration of the player face
  showing the chapter timeline, the pace knob, the voice
  chip, and the download chip — not a stock pair of
  headphones.

**Slide 2 — Try it now.**
- One short prompt: "Try with a sample piece".
- A live demo input pre-loaded with the sample essay from the
  seed content in section 8a.
- 1-2 sentences pointing at *the specific page elements*
  where the Gemini magic happens (the voice preview, the
  chapter list extracted from the headings, the lock-screen
  cover art generated by Nano Banana 2, the streaming TTS
  that starts within three seconds).

**Slide 3 — How to remix this.**
- Headline: "Make this yours."
- Three short bullets:
  - "Swap the sample piece in `/data/seed-pieces/` for your
    own URL or PDF."
  - "Adjust the voice directives in `/server/prompts/` to fit
    your locale and reading style."
  - "Wire up your Gemini API key and Firebase project via the
    env-var list in the capabilities panel."
- Primary CTA: "Use this template" → links to AI Studio Build
  remix entry point.
- Secondary: "Just exploring — close" (sets localStorage
  flag, never auto-shows again).

**Accessibility:** focus trap, `Esc` closes, `role="dialog"`,
`aria-modal="true"`, `aria-labelledby`, focus restored to
trigger on close. Respect `prefers-reduced-motion`.

**Don't:**
- Don't gate content behind the modal. The page beneath must
  be fully usable.
- Don't auto-reshow on return visits. Use
  `localStorage['onboarding-seen-v1']`.
- Don't include unrelated CTAs (newsletter signup, social
  follow). Keep it about the template only.

## 6c. Capabilities info button (persistent in header)

Add a persistent `(i)` icon in the top-right of the header (next
to the primary nav). Click → opens a modal/panel titled **"What
powers this app"**.

**Panel contents (in this order):**

**Gemini capabilities used (the hero list):**
- **Gemini 3.1 Flash TTS (preview)** (`gemini-3.1-flash-tts-preview`)
  — the expressive voice that reads your pieces. Released
  2026-04-15. More natural prosody than the previous TTS
  generation, with real breath at paragraph breaks and subtle
  emphasis on load-bearing sentences. Three voice families:
  Warm, Focused, Casual. The voice family is steered by a
  one-sentence directive prepended to each segment, since
  Gemini 3.1 Flash TTS has no SSML.
- **Gemini 3.5 Flash** (`gemini-3.5-flash`) — the post-I/O 2026
  default flagship that beats the previous Pro tier on most
  benchmarks. Used here for two jobs: (1) reading the URL or
  PDF and parsing it into a structured ParsedPiece, and (2)
  reading the full piece and emitting a NarrationPlan with
  per-paragraph metadata (paragraph type, emphasis directives,
  chapter boundaries, multi-speaker voice cues). The 1M-token
  context window means even a 60-page PDF fits in a single
  analyser call.
- **Gemini 3.5 Flash (multimodal PDF input)** — the same model
  reads PDF pages directly via the Files API. Two-column
  layouts, page breaks, hyphenated line breaks, footnote
  positions, and figure captions are all handled in a single
  pass.
- **Nano Banana 2** (`gemini-3.1-flash-image`) — generates the
  cover image for each piece. Used in queue thumbnails and
  lock-screen art.
- **Nano Banana Pro** (`gemini-3-pro-image`) — optional, only
  when you tap "Save as poster" on a piece. Generates a 4K
  poster with legible in-image text (the title, author, and a
  pinned quote rendered as crisp typography). This is the only
  call that uses the Pro image model; the rest of the app
  stays on the fast workhorse.
- **Firebase Auth** — Google sign-in by default; Apple sign-in
  next to it (requires Apple Developer account configuration);
  magic-link email for cross-device sync.
- **Firestore** — stores your queue, your position, and your
  listening history when you sign in for cross-device sync.
  Off by default; you can listen anonymously forever.
- **Firebase Storage** — stores your uploaded PDFs and the
  cached MP3s so playback can start instantly on repeat
  listens. Storage is NOT auto-provisioned by AI Studio Build
  today — enable it once in the Firebase console.
- **Cloud Run server functions** — every Gemini API call
  happens server-side; your API key never ships to the
  browser. AI Studio Build auto-provisions Cloud Run; the
  first 2 apps deploy free, post-I/O 2026.
- **Cost note** — see the detailed breakdown in 6d. A typical
  4,000-word article is about $0.06 of TTS + ~$0.01 of
  parsing + analyser ≈ $0.07 per piece. A 60-minute audiobook-
  length narration is ~$0.50 in total.
- **Privacy note** — your URLs, PDFs, prose, listening
  history, and queue are private to you. The app uses the
  Gemini API on the paid tier, where Google does not use your
  content for model training, per the Gemini API Additional
  Terms.
- **Every-word note** — this app reads every word the author
  wrote. Summarisation is not the job. If you want a summary
  you can read in two minutes instead of the full piece in
  forty, that is a different app.

**Backend services this app depends on:**
- Auth: see section 4b
- Database: see section 4b
- Storage: see section 4b — REQUIRES manual enable in Firebase
  console; AIS Build does not auto-provision Storage today.
- Email: see section 4b — magic-link sign-in requires the
  sender domain to be authorised in Firebase Auth.
- Apple sign-in: optional, requires an Apple Developer
  account and Service-ID config. See section 4b.
- Payments: see section 4b (not used in v1)
- External APIs: see section 4b — optional fallback
  boilerplate stripper only

**Environment variables you'll need to configure:**
- `GEMINI_API_KEY` — your Google AI Studio API key
- `FIREBASE_PROJECT_ID` — your Firebase project id
- `FIREBASE_SERVICE_ACCOUNT` — service-account JSON
  (server-side only)
- `MERCURY_API_KEY` — optional, only if you want the
  defence-in-depth boilerplate-stripping fallback

**Cost + privacy notes:**
- TTS is the dominant cost line — typically $0.05-0.50 per
  piece depending on length. Parsing and analysis are ~$0.01
  per piece. Cover-art generation is ~$0.005 per piece
  (cached forever).
- Privacy: where the data lives (your Firebase project), how
  to delete it (Settings → "Delete this piece" — gone in 60
  seconds), what is never sent for training.

**Documentation links:**
- AI Studio Build docs
- Gemini API expressive TTS, multimodal PDF input,
  long-context, structured output docs
- Firebase Auth, Firestore, Firebase Storage docs
- Media Session API spec (for lock-screen controls)
- IndexedDB spec (for offline cache)

**Accessibility:** same standards as the onboarding modal —
focus trap, `Esc`, ARIA, restored focus.

**Behaviour:**
- Always available — single click from anywhere in the app.
- Tooltip on the `(i)` icon: "How this app is built".
- Mobile: opens as a full-screen sheet that slides up.
- Should be the most honest part of the app — never hand-wave
  service requirements; never say "AI" without naming the
  specific Gemini model and capability.

## 6d. Detailed cost breakdown (deployer reads this BEFORE shipping)

- **URL → ParsedPiece (`gemini-3.5-flash`, low thinking)** — a
  typical 4,000-word article post-boilerplate-strip averages
  ~5,500 input tokens and ~3,000 output tokens (the structured
  ParsedPiece). At Gemini 3.5 Flash pricing ($1.50/M input,
  $9/M output) that is ~$0.035 per article. A long 9,000-word
  essay is ~$0.06.
- **PDF → ParsedPiece (`gemini-3.5-flash`, low thinking,
  multimodal)** — a 40-page PDF averages ~80,000 input tokens
  (the pages as images plus the model's internal pass) and
  ~25,000 output tokens (the structured ParsedPiece for a
  long piece). That is ~$0.35 per 40-page PDF. A 180-page
  book-length PDF is ~$1.50 — the dominant cost line for
  book-length material. Cached per upload.
- **ParsedPiece → NarrationPlan (`gemini-3.5-flash`, medium
  thinking)** — a 4,000-word article ParsedPiece is ~3,000
  input tokens and the NarrationPlan output is ~4,000 tokens.
  ~$0.04 per article. A 30,000-word longform is ~$0.20.
- **TTS narration (`gemini-3.1-flash-tts-preview`)** — pricing
  in token-equivalents: approximate ~$10/M output character-
  tokens (Google has not pinned an exact public TTS character-
  token price for the 3.1 Flash TTS preview; treat as a working
  estimate and verify on the Gemini API pricing page before
  shipping). A 4,000-word article is ~24,000 characters → ~$0.24
  per article on the working estimate. A 30,000-word longform is
  ~$1.80. The dominant cost line. Cached as MP3 forever once
  generated.
- **Cover-art generation (Nano Banana 2)** — ~$0.005 per
  cover. Generated once per piece, cached forever.
- **Optional 4K poster export (Nano Banana Pro)** — ~$0.10
  per poster. Listener-initiated only; one tap per save.
- **Expected per-piece cost (4,000-word article):** ~$0.32 —
  $0.035 extractor + $0.04 analyser + $0.24 TTS + $0.005
  cover. The MP3 caches forever so re-listens are free.
- **Expected per-piece cost (40-page PDF):** ~$2.20 — $0.35
  PDF extractor + $0.20 analyser + $1.60 TTS + $0.005 cover.
- **Free-tier listening cap recommendation:** 60 minutes of
  TTS per listener per day ≈ ~$0.50 of Gemini spend per
  listener per day at the cap. The capabilities panel
  discloses this transparently.
- **Cache strategy:** MP3s and ParsedPieces are stored in
  Firebase Storage and Firestore respectively; both are
  free up to generous quotas on the Spark plan and cheap
  thereafter (Storage ~$0.026/GB/month; a 4-minute MP3 at
  64 kbps is ~2 MB, so 1,000 pieces ≈ 2 GB ≈ ~$0.05/month).

## 7. Design language

- **Mood:** A quiet listening companion, not a media-player chrome
  showpiece. Apple-light surfaces, warm paper textures, a hint of
  the public library and the pocket notebook. The phone in the
  coat pocket on a winter walk. Headphones on the train. The
  kitchen at Sunday evening light. The app's chrome recedes; the
  audio is the experience.
- **Typography:** A display serif for piece titles (Source Serif
  Pro, Fraunces, or Tiempos) — the title is the only place the
  app feels editorial. A clean grotesque for app chrome and
  controls (Inter or Geist). Title sizes scale fluidly via
  `clamp()` so a long title shrinks gracefully on a 375 px
  phone.
- **Palette:** Warm paper background `#F7F4EE` for the player
  surface, deep ink `#1A1815` for body text, a single warm
  accent `#B5613E` (terracotta) for primary actions and the
  audio scrubber's filled segment, soft `#D9C9A5` (warm sand)
  for chapter-marker tick lines and the cover-art scrim, muted
  `#6B6760` (warm grey) for secondary text and inactive
  controls. The voice chip uses a different soft tint per voice
  family: Warm `#F2C291` (peach), Focused `#A8B7C9` (sky), Casual
  `#C8D5B9` (sage). The download-cached chip uses `#7FA677`
  (sage green) when 100%; muted grey when partial.
- **Imagery:** Photographic generated cover art per Nano Banana
  2 prompts emphasising warmth, soft natural light, no people,
  no faces, abstract or oblique composition. A typographic
  fallback cover (serif title over warm paper) when generation
  fails or the piece has no clean visual anchor.
- **Hand-feel touches:** The play button has a slight tactile
  press (8 ms scale-down on press, springs back on release).
  The pace knob nudges with a tiny haptic-style visual tick
  (a brief 50 ms bar pulse) at each integer step. The chapter
  boundary lines on the timeline are thin warm-sand ticks, not
  full-bleed verticals. The transcript scrolls in sync with
  the audio cursor with a soft easing — never a snap.
- **Spacing:** consistent 4-px base. Generous whitespace — the
  player face needs air around the cover and around the
  scrubber.
- **Radius:** consistent token set (e.g. 8 / 16 / 24 px). The
  player cover uses 24; the voice cards use 16; the inline
  chips use 8.
- **Shadows:** subtle, layered, warm-tinted. Avoid heavy drop-
  shadows. The cover art on the player face has a single soft
  shadow with a slight warm cast (terracotta tint at 6%
  opacity).
- **Motion:** purposeful — entrance fades, hover lifts, page
  transitions. Respect `prefers-reduced-motion`. The progress
  arc when parsing a piece is the one place motion carries
  meaning; respect reduced-motion by jumping between the three
  named states ("reading the piece", "finding chapters",
  "planning the narration") with text alone, no animated arc.
  No bouncing splash animations. No theatrical hero
  animations.
- **States:** every interactive element has hover, focus,
  active, disabled. Loading uses skeletons not spinners where
  possible. The "thinking…" state for the analyser shows a
  text indicator ("planning your narration…") not a spinner.
  Empty states have helpful next-action guidance ("Paste your
  first URL — we'll do the rest"), not "Add your first item".

## 8. Content generation rules

- Write **realistic, specific copy**. NO Lorem Ipsum. NO generic
  placeholders like 'Your tagline here'.
- Invent plausible piece titles, author names, publication
  names, and prose snippets that fit the domain (use the seed
  content in section 8a as a starting point). When inventing
  prose, never reproduce real article text; the sample piece
  in section 8a is fictional, authored fresh for this template.
- Tone: warm, direct, free of corporate language. This template
  is for a listener, not a media-platform marketing page.
- Headlines: punchy and concrete. No 'Empower your X' filler.
  No 'Revolutionize'. No 'Seamless'. No 'AI-powered'.
- Body copy: short paragraphs (2-4 sentences). Use lists where
  appropriate.
- Plain language. Avoid jargon — but the listener knows what
  "lock-screen", "footnote", "chapter", "voice", "pace" mean;
  don't over-translate.
- Where the app outputs AI-generated content (the parsed prose,
  the cover art, the narration itself), never label it as "AI
  says". Let it speak naturally. The honest framing in the
  capabilities panel is enough.

## 8a. Seed content (use these specific examples)

Anchor every generated copy + sample data point in the concrete
content below. Use these names, numbers, and snippets verbatim
where helpful, or generate close variants that sit in the same
world.

**Sample piece in detail view (this is what the demo should
show):**
- **Title:** "On Walking the Long Way Round"
- **Author:** Naomi Eriksen
- **Publication:** Slow Reader (a fictional small-press
  newsletter)
- **Published:** 2026-03-14
- **Source kind:** url
- **Source locator:** `https://slow-reader.example/walking-the-long-way`
- **Estimated word count:** 4,210
- **Language:** en-GB
- **Estimated runtime at 130 wpm:** 32:25
- **Chapters (extracted from the headings):**
  1. "Why the long way" (paragraphs 1-9)
  2. "The map I drew at seven" (paragraphs 10-19)
  3. "Three walks that taught me something" (paragraphs 20-34)
  4. "On the use of getting lost" (paragraphs 35-47)
  5. "Coming back" (paragraphs 48-56)
- **Sample paragraph (paragraph 4, type: body):** "I have walked
  the long way home from the same train station for fourteen
  years. The short route runs along a four-lane road; the long
  one cuts through three small parks and adds eleven minutes.
  In those eleven minutes, the things I was anxious about on the
  train tend to soften. I have never once regretted taking the
  long way. I have, more times than I can count, regretted not."
- **Sample paragraph (paragraph 21, type: blockquote):** "It is
  not the destination that humbles us — it is the bit between
  the destination and the next one, the bit nobody photographed
  and nobody named."
- **Emphasis directives on paragraph 4 (analyser output):**
  one `lift` directive on "fourteen years"; one `slow` directive
  on "I have never once regretted taking the long way".

**Sample voice previews (6-second clips per voice family):**
- _Warm:_ "I have walked the long way home from the same train
  station for fourteen years."
- _Focused:_ "I have walked the long way home from the same
  train station for fourteen years."
- _Casual:_ "I have walked the long way home from the same
  train station for fourteen years."

**Sample queue (demo seed for the queue view):**
- "On Walking the Long Way Round" — Naomi Eriksen — Slow Reader
  — 32 min — Warm
- "The Quiet Year Inside the Loud One" — Théo Martel — Le Très
  Lent (fictional French-language newsletter, the app reads it
  in fr-FR) — 18 min — Warm
- "Inverse Functions in Conversational Drafting" — a fictional
  39-page arXiv preprint by H. Pham and L. Ortega — 1 h 24 min
  — Focused
- "What I Learned Cooking with My Grandmother in Manila for a
  Month" — a fictional Substack memoir by Therese Aquino —
  21 min — Warm
- "Six Short Notes on Tuesdays" — Ardit Krasniqi — Loose Pages
  (fictional Albanian-language essay newsletter, the app reads
  it in sq-AL) — 9 min — Casual
- "The Use of Long Walks in the Recovery From Burnout" — a
  fictional research paper by Dr. M. Saito — 47 min — Focused

**Sample interview piece (for multi-speaker demo):**
- **Title:** "A Conversation with Petra Voll on Walking and
  Memory"
- **Speakers:** "host" (the journalist), "voll" (Dr. Petra
  Voll, the subject)
- The host's turns play in the chosen voice family's "primary"
  variant; Dr. Voll's turns play in the "secondary" variant of
  the same family. The listener follows the conversation
  without effort.

**Sample PDF (for the upload demo):**
- A fictional 38-page paper "Pace, prosody, and listener
  comprehension in expressive synthetic narration" by Dr. L.
  Ortega et al. Includes an abstract, six sections, two
  figures (captions narrated, figure body skipped with a
  one-line handoff), one equation block (skipped with handoff),
  one table (skipped with handoff, prose preserved for the
  listener who toggles "read everything verbatim"), and 22
  footnotes (skipped by default; trailing segment after the
  paper).

**Sample voice copy:**
- Empty home / first-paste: "Paste a URL or drop a PDF.
  We'll read it to you."
- Parsing progress: "Reading the piece…" / "Finding chapters…"
  / "Planning the narration…"
- Voice preview tap: "Hear how each voice reads the first
  line."
- Pace knob: "How fast should we read?" (default 130 wpm —
  "walking pace")
- Save confirmation: "Added to your queue. Tap play when
  you're ready."
- Offline-download confirmation: "Downloaded. Listen on the
  flight without WiFi."
- Sleep-timer set: "We'll pause at the end of this chapter."
- Failure (paywall): "This URL looks like it's behind a
  paywall we can't bypass. Paste the article text or upload a
  PDF and we'll read it to you."
- Failure (video URL): "This URL points to a video, not an
  article. We read text. Try a written piece instead."
- Footnote toggle: "Read footnotes inline / Skip footnotes
  (we'll play them at the end)."
- Multi-speaker indicator: "This piece has two speakers. We'll
  use a subtle voice change so you can follow who's talking."
- Lock-screen art: title in serif, author below, the warm-paper
  cover behind a soft scrim.

**Sample errors and recoveries:**
- Audio generation timed out → "We couldn't finish generating
  the audio in time. Tap to retry."
- PDF was a scanned image, low quality → "This PDF is a scan
  and the quality is low. We'll do our best, but some pages
  may have unreadable patches we'll skip."
- Network dropped mid-listen → playback continues from
  IndexedDB cache; lock-screen art remains; no interruption.

## 9. Media & assets

- **Hero image (landing screen):** No hero image. The landing
  screen is a single text input on a warm paper surface; the
  paste-or-drop affordance is the whole hero. (Resist the
  AI-template tendency to add a gradient or a stock image
  here. The product is the doing.)
- **App icon / wordmark:** Set in the display serif on warm
  paper. No icon — just type. A subtle paper-grain texture.
- **Empty-state illustration (queue, history):** A simple hand-
  drawn line illustration of a folded paper map and a pair of
  headphones on a table. Hand-drawn aesthetic, not a flat
  icon. Generate once at build time via Nano Banana 2
  (`gemini-3.1-flash-image`), 1:1 WebP at 1024×1024, prompt:
  "single hand-drawn ink line illustration of a folded paper
  map on the left and a pair of over-ear headphones resting
  on the right on a flat table surface, slight perspective,
  off-white paper background, slight pen imperfection, no
  shading, no colour fill, no text, no commercial branding".
  Ship as a seed asset at
  `/public/samples/empty-state-map-headphones.webp`.
- **Cover art per piece:** Generated via Nano Banana 2 per the
  prompts in section 4b. 1:1 aspect ratio. Used in queue list,
  player face, and lock-screen. Falls back to a clean
  typographic cover (serif title over warm paper) if
  generation fails or the safety filter rejects.
- **Voice-card illustrations (three cards in the chooser):**
  Generated once per voice family, cached forever, used across
  every piece's voice-chooser screen:
  - Warm: "soft natural light through a window, a paperback
    open on a wooden table, no people, abstract composition"
  - Focused: "a desk lamp casting a warm pool of light on an
    open book, calm muted palette, no people"
  - Casual: "a café table with two coffees and a folded
    newspaper, friendly palette, no people"
- **Optional 4K poster (per "Save as poster" action):**
  Generated via Nano Banana Pro per the prompt in section 4b.
  3840 × 2160. Listener-initiated only.
- **Stock fallbacks:** If image generation fails, the cover
  falls back to a clean typographic composition: title in
  serif over warm paper. Never to a generic "music note" or
  "speaker" emoji.
- **Generated imagery:** prefer Nano Banana 2 over stock
  photography. Prompt for warmth, asymmetry, and slight
  imperfection — avoid the glossy 'AI render' look. NO people
  in cover art (explicit rule, enforced in the generation
  system instruction).
- **Optimisation:** WebP/AVIF for covers, MP3 (44.1 kHz, 96
  kbps mono — narration doesn't need stereo or higher) for
  audio. `loading="lazy"` on cover thumbnails in the queue.
  Explicit `width`/`height` on every image to prevent layout
  shift. `decoding="async"` on offscreen covers.
- **Icons:** `lucide-react` for UI (play, pause, skip-forward,
  skip-back, sleep, download, search). Use sparingly — never
  decorative-only.

## 10. Interactivity & states

- Every interactive element has hover, focus, active, and
  disabled states.
- The paste input validates inline: a URL with no protocol
  ("walking-the-long-way") gets a gentle hint "Looks like a
  URL — add `https://` and we'll try"; a URL that resolves
  but returns 404 gets "We couldn't reach that page — check
  the URL or paste the text directly"; a YouTube/video URL
  gets "This URL points to a video, not an article. Try a
  written piece."
- The drop zone highlights on `dragenter` with a soft warm-
  sand fill and a "Drop your PDF" label; cancels on
  `dragleave`.
- Loading states use skeletons that match the eventual layout,
  not spinners. The parsing progress shows three named stages
  ("Reading the piece…", "Finding chapters…", "Planning the
  narration…") with a slim progress arc; the analyser stage
  streams the chapter list in as it appears so the listener
  sees structure before audio starts.
- Empty states explain the next action with a button whose
  label fits THIS app's domain: "Paste your first URL",
  "Drop a PDF", "Connect your RSS reader" — never a generic
  "Add your first item".
- Smooth scroll for in-page anchors (chapter list, search
  results).
- The TTS audio streams in: playback begins within ~3 seconds
  of the analyser finishing. A clear "starting…" indicator
  shows briefly before audio begins, then disappears the
  moment the first audio frame plays. The pause-on-tap is
  instant; the resume is instant.
- If an AI call fails (TTS timeout, PDF parse failure), show a
  calm, specific error ("We couldn't finish generating the
  audio in time. Tap to retry.") and offer retry. NEVER fall
  back to a silent skip or a silent summary.
- The play button is the largest tap target on the player
  face (88 × 88 px on touch, 64 × 64 px on desktop). Skip and
  back are 56 × 56 px. The pace knob is reachable one-handed
  from the bottom edge of the screen.
- The chapter list updates the timeline highlight on tap; the
  audio seeks to the chapter start.
- The voice chip on the player face is tap-to-swap (without
  detouring through settings); swapping mid-piece regenerates
  the remaining narration in the new voice family and resumes
  from the current playback position.
- The transcript toggle exposes the rendered prose synced to
  the audio cursor; tapping a sentence in the transcript
  seeks the audio to that sentence.
- Lock-screen controls (Media Session API) expose play, pause,
  skip forward (15s + chapter), skip back (15s + chapter),
  and seek. The lock-screen art updates within 1s of cover
  generation completing.
- Offline cache uses IndexedDB on web; a small download chip
  on the player face shows MB size and cached percent. On
  cellular, the download requires an explicit per-piece tap.
- The transcript supports text selection; selected text can be
  copied with a single tap-and-hold gesture (preserves the
  every-word contract for listeners who want to revisit a
  passage in text form).

## 11. Tech & responsive requirements

- **Stack:** React + TypeScript + Tailwind CSS. Functional
  components + hooks. Use Shadcn UI primitives where
  appropriate. Audio rendering via `<audio>` element backed
  by a Media Source Extensions buffer for streaming
  playback.
- **Build runtime:** AI Studio Build — full-stack with Cloud
  Run server-side functions. All Gemini API calls happen
  server-side; API key lives in Secrets Manager, never in
  client bundle. Free first-2-app Cloud Run deploy
  (post-I/O 2026 perk) covers the typical demo deploy.
- **Model selection:** explicitly pin
  `gemini-3.5-flash` for URL/PDF parsing and the NarrationPlan
  analyser; `gemini-3.1-flash-tts-preview` for narration;
  `gemini-3.1-flash-image` for cover art;
  `gemini-3-pro-image` for the optional 4K poster export.
  Set `thinkingLevel` explicitly per call (medium for the
  analyser, low for the parsers). Omit `thinkingConfig`
  entirely on TTS and image-gen calls.
- **Database:** Firestore (auto-provisioned by AI Studio
  Build). Show the seed queue on first launch.
- **Auth:** Firebase Auth — anonymous-first; Google sign-in
  for cross-device sync; Apple sign-in next to it;
  magic-link email as fallback.
- **Storage:** Firebase Storage for uploaded PDFs and cached
  MP3s. Pre-signed URLs only. NOT auto-provisioned today —
  enable manually.
- **Audio handling:** the TTS server function streams PCM
  audio chunks back as it generates; the client wraps them
  in a Media Source Extensions buffer for the `<audio>`
  element. Playback begins within ~3 seconds of the
  analyser finishing the first NarrationSegment. Subsequent
  segments are generated in parallel server-side and
  enqueued client-side; segment boundaries are inaudible.
  The final stitched MP3 is uploaded to Firebase Storage and
  cached server-side for instant repeat-listen.
- **PDF handling:** upload to Firebase Storage; the server
  function re-uploads the bytes to the Gemini Developer API
  Files API and passes the resulting `files/*` resource name
  (e.g. `files/abc123xyz`) via `fileData.fileUri` to
  `generateContent`. Do NOT pass Firebase Storage public URLs to
  `generateContent` — the API does not fetch them
  server-side. Use the Files API.
- **Media Session API:** wire up `navigator.mediaSession` for
  metadata (title, author, cover art) and action handlers
  (`play`, `pause`, `previoustrack`, `nexttrack`, `seekbackward`,
  `seekforward`, `seekto`). Verified on iOS Safari 17+, Chrome
  on Android, and desktop Chrome / Safari / Firefox.
- **Offline cache:** IndexedDB stores cached MP3 blobs keyed
  by piece-id. Service Worker (if present) intercepts audio
  requests and serves from IndexedDB when offline.
- **Mobile-first.** Verify layouts at 375 px (iPhone SE),
  768 px (iPad), 1024 px, 1440 px+.
- Use `clamp()` for fluid typography. Prefer container
  queries over media queries for component-level
  responsiveness.
- Use `dvh` / `svh` instead of `vh`. Respect safe-area insets
  on iOS (the player face hugs the safe area; the pace knob
  sits above the home-indicator bar).
- Zero horizontal overflow at any width. Zero layout shift on
  load.
- Persist position in Firestore (signed-in) or
  `localStorage` (anonymous). Use real-time listeners on the
  queue so the "send to my phone" handoff feels instant.
- Optimistic UI on writes; reconcile on response.
- Streaming PCM playback uses Web Audio API as a fallback on
  browsers that lack robust MSE for the streamed mime-type.
- **Local save fallback (FSA non-Chromium):** the "download MP3
  for offline / save poster" affordance uses
  `showSaveFilePicker()` on Chromium; on Safari / Firefox, fall
  back to an `<a download>` element pointed at a blob URL — FSA
  `showSaveFilePicker()` is not supported there.

## 12. Accessibility (WCAG 2.2 AA)

- Semantic HTML — `header`, `nav`, `main`, `section`,
  `article`, `footer`. The transcript view uses an ordered
  list of `article` elements per paragraph.
- All interactive controls reachable by keyboard with a
  visible focus ring. The player face is fully operable
  keyboard-only: Space toggles play/pause, arrow keys seek
  ±5 s, Shift+arrow seeks ±15 s, J/K seek by chapter, +/−
  nudge pace, V cycles voice family, T toggles transcript.
- Color contrast ≥ 4.5:1 for body, 3:1 for large text and
  UI components. The terracotta `#B5613E` against warm paper
  `#F7F4EE` meets 4.5:1 for body and 3:1 for large text and
  controls. Re-verify with the live token values.
- All cover-art images have meaningful `alt` text. The
  generated covers have alt describing the piece ("cover
  art for 'On Walking the Long Way Round' by Naomi Eriksen,
  abstract warm composition in terracotta and sand"); the
  typographic fallback covers have alt simply naming the
  title and author.
- Form fields (the paste input, the search box) have
  associated `<label>`s; errors announced via
  `aria-describedby`.
- All modals (onboarding, capabilities panel, sync,
  settings): focus trap, `Esc` to close, `role="dialog"`,
  `aria-modal="true"`, `aria-labelledby`, restore focus to
  trigger on close.
- Respect `prefers-reduced-motion`. The parsing-progress arc
  jumps between named states instead of animating; the
  scrubbing timeline does not animate the playhead, it
  updates discretely.
- Tap targets ≥ 44 × 44 px on touch; play button ≥ 88 × 88
  px; skip / back ≥ 56 × 56 px; pace knob nudges ≥ 44 × 44
  px each.
- Transcript view exposes the prose as a screen-reader-
  navigable structured document, synced to the audio cursor
  via ARIA live-region announcements ("now reading paragraph
  4 of 56"). The listener can navigate by chapter with
  standard heading-navigation shortcuts.
- The narration audio always coexists with screen readers
  without competing. A "pause narration for screen reader"
  helper duck-pauses TTS when the user invokes a screen-
  reader rotor; resumes on rotor dismiss.
- Subtitle / caption view: a live captioning track shows
  the current sentence in large type at the bottom of the
  player face for listeners who prefer reading along; the
  captions track is the verbatim rendered prose, not a
  re-transcription of the audio.
- The voice-preview clips have a visible play button and a
  text label "Preview voice 'Warm'", reachable by keyboard.
- Cellular-download confirmations are announced via
  `role="status"` and `aria-live="polite"`.
- The error states (paywall, video URL, parse failure) are
  announced via `role="alert"` and clearly differentiated
  visually (warm muted orange `#C77A4B`, not red — red
  reads as failure-of-the-app rather than nature-of-the-
  input).

## 13. Quality bar — avoid AI clichés

Do **not** ship any of the following unless the design
explicitly calls for it:
- Hero with a gradient background and floating geometric / orb
  shapes.
- A row of 4 'by the numbers' stat cards below the hero ("12
  voices, 4 languages, 30s to start, ∞ pieces").
- Emoji bullets in body copy. No 🎧. No 📚. No 🚶.
- 'Lorem ipsum' or 'Your headline here' placeholders.
- A pricing table with three identical tiers when the product
  has no real pricing.
- Faux testimonials with stock-photo headshots.
- Hero CTA labelled 'Get started' with no second action.
- "AI" or "Powered by AI" badges plastered everywhere. The
  intelligence is in the experience, not the marketing.
- Loading spinners on AI calls — show a meaningful 'thinking'
  state (the three-stage parsing progress, the streaming
  audio "starting…" indicator).
- Toast notifications for routine actions (save, delete) —
  use inline confirmation instead.
- Decorative audio-themed iconography in app chrome — no
  giant speaker icons, no wave-form watermarks, no
  vinyl-record imagery. The piece is the user's; the app
  chrome is plain.
- A robotic computer-voice marketing motif — the whole
  selling point is that this does NOT sound like that.
- Any "AI says" labelling — let the narration speak for
  itself.
- Auto-play. Audio playback always requires an explicit
  user gesture.
- Animated waveforms on the player face — the audio is the
  point, the chrome is calm.

Aim for the polish of a hand-crafted production app —
specific, considered, with real domain knowledge in the copy.
A reviewer should not be able to tell this came from a
template.

## 14. Deliverables

A single working app I can preview immediately, with:
- All sections populated with realistic seed data (see
  section 8a) — the demo queue includes "On Walking the Long
  Way Round" (4,210 words, warm voice, 32 min) plus the
  five additional sample pieces.
- All AI features wired to real Gemini API calls (server-
  side) with the per-call matrix respected exactly:
  `gemini-3.5-flash` for URL/PDF parsing and the analyser;
  `gemini-3.1-flash-tts-preview` for narration;
  `gemini-3.1-flash-image` for cover art;
  `gemini-3-pro-image` for the optional 4K poster.
- All interactive states implemented (loading, empty, error,
  paywall, video-URL, parse-failure, low-confidence flagged
  paragraphs).
- Onboarding modal working on first visit (and accessible
  via `?` icon thereafter).
- Capabilities info button working in header (`(i)` icon →
  panel) — fully populated with model names, costs,
  privacy notes, the every-word contract.
- Auth flow working with anonymous-first, Google sign-in,
  Apple sign-in (where configured), magic-link email.
- Firestore persistence wired up with security rules that
  scope pieces and positions to the owner; anonymous users
  have data in `localStorage` only.
- PDF upload to Firebase Storage working end-to-end, with
  the bytes then re-uploaded server-side to the Gemini
  Developer API Files API and the resulting `files/*`
  resource name passed via `fileData.fileUri` to
  `generateContent`.
- Streaming TTS playback working — first audio frame
  within 3 seconds of paste/drop on a 4,000-word article.
- Voice swap mid-piece working — picking a new voice
  family regenerates remaining narration and resumes
  from current playback position.
- Multi-speaker pieces use distinguishable voice variants
  per speaker, driven by the analyser's per-segment
  voice directive sentences.
- Cover-art generation working end-to-end; failed
  generations fall back to typographic covers.
- Media Session API wired up so lock-screen controls,
  Bluetooth headphones, Airpods double-tap, and CarPlay /
  Android Auto (when present) all work.
- Offline cache working — downloading a piece on WiFi,
  going offline, and continuing playback from
  IndexedDB.
- Transcript view synced to audio cursor; tapping a
  sentence seeks the audio.
- Search-within-piece working — full-text search over
  parsed prose; tap a match to play from that sentence.
- "Send to my phone" working via Firestore real-time
  listener.
- Optional 4K poster export working — listener pins a
  quote, taps "Save as poster", a 3840 × 2160 PNG is
  generated by Nano Banana Pro with legible in-image
  text.
- Cellular-download policy honoured — explicit per-piece
  tap required on cellular.
- Responsive across the four viewport breakpoints (375,
  768, 1024, 1440+).
- Zero TODOs, zero console errors, zero placeholders.
- Player face works keyboard-only with the documented
  shortcuts (Space, arrows, Shift+arrows, J/K, +/−, V, T).
- Screen-reader experience: transcript navigable by
  heading, audio coexists without conflict, errors
  announced via `role="alert"`.
- Every-word contract honoured: no silent skipping, no
  silent paraphrase, no silent summary. Code blocks,
  tables, equations, and footnotes are surfaced as
  one-line spoken handoffs by default; the verbatim
  toggles work per piece.