# V1 Production Threshold Handoff

Date: 2026-07-08

This handoff keeps the current wireframe honest. `index.html` proves the user-facing flow shape; it does not prove backend extraction, native OS integration, provider reliability, account deletion, or persistence.

## Closure Stance

Covered at wireframe level:

- Library starts from one active listening item plus compact starter-book choices.
- Reader supports playback, Retelling/Original, progress, Continue next, and current-position return.
- Paste and Upload enter the Reader model with preparation, failure, retry, and fallback states.
- Selected text supports copy, highlight, share, Add note, Mark problem, saved-note detail, and Discuss with AI handoff.
- Voice and Settings expose local/cloud labels, premium preview, offline fallback, accessibility controls, and storage/account confirmation scaffolding.

Still production-threshold work:

- Real file extraction and parser confidence.
- Real speech recognition and voice-command capture.
- Real generation queues, provider errors, and local/cloud routing.
- Real Contents row rewrite lifecycle, playback-arrival behavior, style snapshots, persistence cues, and storage cleanup.
- Real TTS catalog, entitlement, voice download, and fallback behavior.
- Native iOS/Android share extension.
- Public-domain search source/API and rights-safe returned fields.
- Account deletion, local model cleanup, and privacy/legal copy.
- Accessibility persistence across app launches and text/file items.

## Threshold Matrix

| Area | Prototype guarantees | Production must implement | Acceptance checks |
|---|---|---|---|
| PDF/EPUB extraction | Upload enters Reader immediately with preparing, ready, failed, retry, choose-another-file, and fallback-position states. | Detect selectable text, EPUB structure, scanned/image-only PDFs, password protection, weak OCR, empty extraction, oversized files, parser timeout, and confidence scores from real parser results. | Fixture set includes clean PDF, EPUB, scanned PDF, password PDF, empty PDF, weak OCR, oversized file, and timeout simulation. Each maps to the matching UI state without fake fallback text being treated as extracted Original. |
| Long imports | Long-file state persists visually and can be reopened from Library while preparation continues. | Background job persistence, resumable progress, cancellation, retry policy, recoverable failed-file state, and app-restart recovery. | Start a long import, leave Reader, return from Library, background/foreground app, then cancel/retry. Position and recovery controls persist. |
| Speech recognition | Mic cycles through scripted note, question, and problem capture states using the same annotation composer as touch input. | Real hold-to-capture, permission prompts, audio ducking, partial/final transcripts, transcript editing, cancel/failure states, and no accidental save on recognition failure. | Denied permission, no speech, noisy speech, cancel mid-capture, edit transcript, and save note/question/problem all attach to the correct current range. |
| Retelling generation | Simulated on-phone/cloud rewrite states cover generating, failed, ready, use now, retry, cloud upgrade, and cancel. | Real queue, range scoping, conflict prevention, local/cloud route decision, provider timeout/failure handling, cost/entitlement policy, and no auto-switch on ready output. | Start rewrite, trigger provider failure, retry locally, choose cloud upgrade, cancel ready output, and verify Original remains available throughout. |
| Contents row rewrites | Contents row Rewrite starts background preparation inline without navigation or a separate rewrite-management panel. Prototype now covers ready/failure/cancel actions, row-only Listen/Use, playback-arrival copy, style snapshots, Contents-button count, audio-row cues, fallback-position failure/retry/cloud, and storage cleanup copy. | Enforce real background job persistence, 30-day expiration or revised policy, provider errors, local/cloud entitlement routing, cross-device sync decision, and durable storage cleanup. | Start multiple row rewrites, close Contents, return from Library, hit a still-preparing row during playback, use a ready row explicitly, cancel/remove a prepared row, and verify fallback positions stay labeled as fallback. |
| TTS voices | Voice catalog distinguishes included local voices, premium cloud previews, offline pack state, fallback, and selected/default voice behavior. | Real TTS provider catalog, local pack download/storage, offline availability, premium entitlement, cloud provider failure, fallback routing, and preview versus selection separation. | Premium preview never changes selected voice; local pack removal/failure/retry works; cloud failure switches to included offline voice without blocking playback. |
| OS share | No fake in-app share-import button; Library keeps Paste/Upload as current in-app entry points. | Native iOS/Android share extension, accepted payload types, file/text size handling, app-open routing, duplicate handling, and privacy copy. | Share selected text, PDF, EPUB, URL/text bundle, unsupported file, and oversized file from outside the app. Each lands in the same Reader preparation model or a clear unsupported state. |
| Public-domain search | Search is visibly paused until a source/API is chosen. | Choose source/API, rights audit, returned fields, search index behavior, unavailable-network behavior, duplicate with starter books, and result-to-reader import path. | Returned result includes title, author, rights/license, source, language, length/structure hint, and importability. No result appears without rights/source metadata. |
| Account/storage | Settings separates destructive actions from Reader and requires confirmation scaffolding. | Auth confirmation, final account deletion dialog, deletion scope, local model cleanup, cloud account deletion, retention policy, export-before-delete option, and legal/privacy text. | First tap arms confirmation, final confirmation is explicit, deletion does not occur from Reader, and local/cloud deletion scope is visible before commit. |
| Accessibility persistence | Reader visually responds to text size, dark/light mode, high contrast, reduced motion, spacing, speed, and skip interval. | Persist defaults globally and define per-book/text override policy; map to platform accessibility APIs and Flutter theme/state model. | Set each control, relaunch app, open a different item, and verify expected defaults/overrides persist without layout clipping at small mobile sizes. |

## Implementation Rules

- Do not treat fallback positions as real chapters.
- Do not treat placeholder Original text as extracted Original.
- Do not auto-switch to a newly generated retelling.
- Do not let premium/cloud paths block the included local listening path.
- Do not add an in-app OS-share substitute to Library.
- Do not expose document-manager structures such as section maps, loaded-document metadata, or generated source badges.
- Keep production-only behaviors named as thresholds until they are actually implemented.

## Next Product Decisions

1. Pick the public-domain search source/API and returned-field contract.
2. Define native OS share extension scope for V1: text only, PDF/EPUB, or both.
3. Decide whether Discuss with AI needs visible answer output in V1 or can remain a saved-annotation handoff until V1.1.
4. Define accessibility persistence policy: global defaults only, per-item overrides, or both.
5. Validate or revise the prototype defaults for Contents row rewrite expiration, storage cleanup, cross-device sync, and free/cloud entitlement policy.