# AGENTS.md — Build guide for Teleprompter.com

## Project scope
Build a browser-only teleprompter with readable text, keyboard speed/pause controls and an explicit mirror toggle. Store scripts locally, export JSON/text and optionally record a consented camera take.

Catalogue verdict: yes. A teleprompter is text that moves down the screen at an adjustable speed, and every browser can already do that. The genuinely useful extras, mirror flip for beam-splitter rigs, large-type layout, keyboard speed control, camera preview behind the words, are all standard web APIs and fit in one session. Even voice-tracked scrolling, the feature people assume is magic, is a Web Speech API loop that matches recognized words against your script. What you cannot casually rebuild is the polished phone app you actually hold at arm's length while filming, plus remote control between two devices. If you record at a desk with a webcam, the DIY version is not a compromise, it is the same thing.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- A modern browser and Node for the static build. Serve the static output on localhost during development or HTTPS for optional camera/microphone recording, and request those permissions explicitly. No application backend, accounts, model API or external requests are needed.
- Implementation components: Vite, React and TypeScript with requestAnimationFrame-controlled text scrolling. IndexedDB/localStorage for scripts and settings; optional getUserMedia and MediaRecorder for a separate camera take.
- Scope boundary: A real iOS/Android app that behaves well when the screen is your only prompter; Remote control from a second device without you building the socket plumbing

## Stack and architecture
- Vite, React and TypeScript with requestAnimationFrame-controlled text scrolling.
- IndexedDB/localStorage for scripts and settings; optional getUserMedia and MediaRecorder for a separate camera take.
- Domain model: scripts, font/line-height preferences, scroll position, speed settings and optional recording manifests

## Security and data integrity
- Import only bounded text or schema-validated script JSON and render script bodies as text, never executable HTML. Request camera/microphone only after an explicit action; stop all media tracks on stop/navigation and cap recording size/duration. Release recording object URLs and temporary buffers after download/reset.
- Correctness boundary: No external requests or account are required; camera denial leaves prompting usable and mirroring the display does not rewrite the script.
- Persist script edits before playback. Drive scrolling by elapsed time, preserve the current passage on resize and apply mirror transforms to the text layer only.
- Export scripts as text and versioned JSON; import with a preview and never overwrite an existing script silently. Recording downloads are separate from script backups.

## Agent implementation rules
- Project rule — data model: scripts, font/line-height preferences, scroll position, speed settings and optional recording manifests
- Project rule — preserve this invariant: No external requests or account are required; camera denial leaves prompting usable and mirroring the display does not rewrite the script.
- Project rule — acceptance evidence: Pause scrolling, resize the window and retain the current passage; reload a saved script and recover settings, while recording errors never discard text.

## Optional agent skills and references
- Optional external skill: [vercel-composition-patterns](https://github.com/vercel-labs/agent-skills/blob/main/skills/composition-patterns/SKILL.md) — Design reusable React components with composition, context and explicit component variants. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission.
- Optional external skill: [web-design-guidelines](https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md) — Review web interfaces for accessibility, keyboard focus, forms, navigation and interaction quality. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate the actual Teleprompter.com-inspired workflow with owned or clearly labeled sample data: Build a browser-only teleprompter with readable text, keyboard speed/pause controls and an explicit mirror toggle. Store scripts locally, export JSON/text and optionally record a consented camera take.
- Publish a reproducible walkthrough with this observable result: Pause scrolling, resize the window and retain the current passage; reload a saved script and recover settings, while recording errors never discard text.
- Explain who can operate this scoped tool, its setup and ongoing costs, and these remaining product gaps: A real iOS/Android app that behaves well when the screen is your only prompter; Remote control from a second device without you building the socket plumbing Avoid guaranteed savings, performance scores or implied endorsement.

## Engineering roadmap
1. Phase 1 — Scope and fixtures. Implement this bounded workflow: Build a browser-only teleprompter with readable text, keyboard speed/pause controls and an explicit mirror toggle. Store scripts locally, export JSON/text and optionally record a consented camera take. Record prerequisites, select representative user-owned fixtures and document the unsupported features: A real iOS/Android app that behaves well when the screen is your only prompter; Remote control from a second device without you building the socket plumbing
2. Phase 2 — Durable model. Model scripts, font/line-height preferences, scroll position, speed settings and optional recording manifests Add migrations or a versioned document format, explicit validation, stable IDs and a visible import-error report. Preserve this rule: No external requests or account are required; camera denial leaves prompting usable and mirroring the display does not rewrite the script.
3. Phase 3 — Complete the first useful path. Implement the workflow's input, review and output interface, with clear controls and explicit empty/error states. Persist script edits before playback. Drive scrolling by elapsed time, preserve the current passage on resize and apply mirror transforms to the text layer only.
4. Phase 4 — Permissions and integration failure. Import only bounded text or schema-validated script JSON and render script bodies as text, never executable HTML. Request camera/microphone only after an explicit action; stop all media tracks on stop/navigation and cap recording size/duration. Release recording object URLs and temporary buffers after download/reset. Request integration credentials and permissions only for the enabled feature; show a disconnected state instead of mock results.
5. Phase 5 — Portable handoff. Export scripts as text and versioned JSON; import with a preview and never overwrite an existing script silently. Recording downloads are separate from script backups. Include setup, operating limits, fixture walkthrough and shutdown/restart instructions in the README.
6. Phase 6 — Acceptance scenarios. Pause scrolling, resize the window and retain the current passage; reload a saved script and recover settings, while recording errors never discard text. Repeat the workflow after restart and with a denied permission or unavailable dependency; show recoverable failure rather than a success placeholder.

## Paid-product capabilities outside this build
- A real iOS/Android app that behaves well when the screen is your only prompter
- Remote control from a second device without you building the socket plumbing
- Cloud sync of scripts across phone, laptop and someone else's machine
- Reliable voice tracking in noisy rooms; browser speech recognition drifts
- Export niceties: burned-in captions, project organization, team script sharing

## Implementation prompt
WORKING SLICE
Build a browser-only teleprompter with readable text, keyboard speed/pause controls and an explicit mirror toggle. Store scripts locally, export JSON/text and optionally record a consented camera take.

Build this scoped Teleprompter.com-inspired workflow with a documented data model and visible failure states.

Architecture
- Vite, React and TypeScript with requestAnimationFrame-controlled text scrolling.
- IndexedDB/localStorage for scripts and settings; optional getUserMedia and MediaRecorder for a separate camera take.

Prerequisites and limits
A modern browser and Node for the static build. Serve the static output on localhost during development or HTTPS for optional camera/microphone recording, and request those permissions explicitly. No application backend, accounts, model API or external requests are needed.
Outside this release: A real iOS/Android app that behaves well when the screen is your only prompter; Remote control from a second device without you building the socket plumbing

Data model and correctness
scripts, font/line-height preferences, scroll position, speed settings and optional recording manifests
Invariant: No external requests or account are required; camera denial leaves prompting usable and mirroring the display does not rewrite the script.
Persist script edits before playback. Drive scrolling by elapsed time, preserve the current passage on resize and apply mirror transforms to the text layer only.

Security and privacy
Import only bounded text or schema-validated script JSON and render script bodies as text, never executable HTML. Request camera/microphone only after an explicit action; stop all media tracks on stop/navigation and cap recording size/duration. Release recording object URLs and temporary buffers after download/reset.

Recovery and export
Export scripts as text and versioned JSON; import with a preview and never overwrite an existing script silently. Recording downloads are separate from script backups.

Implementation order
1. Phase 1 — Scope and fixtures. Implement this bounded workflow: Build a browser-only teleprompter with readable text, keyboard speed/pause controls and an explicit mirror toggle. Store scripts locally, export JSON/text and optionally record a consented camera take. Record prerequisites, select representative user-owned fixtures and document the unsupported features: A real iOS/Android app that behaves well when the screen is your only prompter; Remote control from a second device without you building the socket plumbing
2. Phase 2 — Durable model. Model scripts, font/line-height preferences, scroll position, speed settings and optional recording manifests Add migrations or a versioned document format, explicit validation, stable IDs and a visible import-error report. Preserve this rule: No external requests or account are required; camera denial leaves prompting usable and mirroring the display does not rewrite the script.
3. Phase 3 — Complete the first useful path. Implement the workflow's input, review and output interface, with clear controls and explicit empty/error states. Persist script edits before playback. Drive scrolling by elapsed time, preserve the current passage on resize and apply mirror transforms to the text layer only.
4. Phase 4 — Permissions and integration failure. Import only bounded text or schema-validated script JSON and render script bodies as text, never executable HTML. Request camera/microphone only after an explicit action; stop all media tracks on stop/navigation and cap recording size/duration. Release recording object URLs and temporary buffers after download/reset. Request integration credentials and permissions only for the enabled feature; show a disconnected state instead of mock results.
5. Phase 5 — Portable handoff. Export scripts as text and versioned JSON; import with a preview and never overwrite an existing script silently. Recording downloads are separate from script backups. Include setup, operating limits, fixture walkthrough and shutdown/restart instructions in the README.
6. Phase 6 — Acceptance scenarios. Pause scrolling, resize the window and retain the current passage; reload a saved script and recover settings, while recording errors never discard text. Repeat the workflow after restart and with a denied permission or unavailable dependency; show recoverable failure rather than a success placeholder.

Acceptance
Pause scrolling, resize the window and retain the current passage; reload a saved script and recover settings, while recording errors never discard text.
Use real source data or clearly labeled fixtures. Explain unsupported input and provider failures; do not fabricate analytics, delivery receipts, accuracy claims or security guarantees.

Optional agent guidance
Optional external skill: [vercel-composition-patterns](https://github.com/vercel-labs/agent-skills/blob/main/skills/composition-patterns/SKILL.md) — Design reusable React components with composition, context and explicit component variants. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission.
Optional external skill: [web-design-guidelines](https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md) — Review web interfaces for accessibility, keyboard focus, forms, navigation and interaction quality. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission.
Project rule — data model: scripts, font/line-height preferences, scroll position, speed settings and optional recording manifests
Project rule — preserve this invariant: No external requests or account are required; camera denial leaves prompting usable and mirroring the display does not rewrite the script.
Project rule — acceptance evidence: Pause scrolling, resize the window and retain the current passage; reload a saved script and recover settings, while recording errors never discard text.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.