# TextBro improvement backlog

Audited 2026-11-09 against `main`. Priorities are ordered to improve user
experience (UX), developer experience (DX), and agent experience (AX) together.

## P0 — protect production and make builds trustworthy

1. **Add authentication before exposing the backend.** Protect generation,
   file, cache, delete, model-check, and restart routes with a shared-token
   middleware at minimum; prefer OIDC for multi-user hosting. Keep restart
   disabled for remote clients by default.
2. **Finish the MoviePy retirement.** The direct FFmpeg engine now covers the
   declared workflows and MoviePy is no longer installed by default. After a
   Linux integration test matrix proves parity, delete the optional MoviePy
   implementation and its progress adapter. This removes roughly 270 lines and
   permanently avoids MoviePy's Pillow `<12` constraint.
3. **Add CI quality gates.** Every pull request should run frontend lint/build,
   backend compile/tests, dependency audits, a Docker build, and a small FFmpeg
   smoke encode. The current GitHub workflow only force-syncs `main` to Hugging
   Face and can publish code that has never been tested.
4. **Expand backend integration coverage.** Package imports and typed settings
   are now self-contained; add real browser and FFmpeg fixtures in CI.
5. **Add capacity preflight for 4K.** Before export, check free disk, RAM,
   FFmpeg codecs, writable output paths, and concurrency. Refuse unsafe starts
   with an actionable message instead of failing after minutes of work.

## P1 — reduce change risk and operating cost

### Add

- Generated/shared TypeScript response types from the OpenAPI contract.
- A downloadable diagnostic bundle per run, building on structured JSON logs.
- Real FFmpeg integration fixtures for one slide, 100 slides, transitions,
  voiceovers, intro/outro clips, music, watermark, cancellation, and 4K output.
- Frontend component/accessibility tests plus mobile visual regression tests at
  390, 768, and 1440 px.
- Optional object storage for media when deployments outgrow local disk.
- Redis-backed queue/rate-limit adapters for multi-worker deployments.

### Upgrade/refactor

- Split `TextToVideo.tsx`, `Processes.tsx`, `routes/runs.py`, and
  `video_engine.py` by feature and responsibility. They are the highest-risk
  files for humans and coding agents.
- Delete the unreachable legacy `/generate-sse` implementation after the
  compatibility window; its live adapter already uses `/runs/*`.
- Finish converting remaining relative output paths to an absolute path
  registry resolved at startup.
- Add audio ducking/normalization controls and configurable watermark
  position, opacity, and scale.

### Remove after migration

- Duplicate inline `/generate-sse` orchestration after all tools use queued
  runs.
- Optional MoviePy fallback and proglog adapter after parity tests pass.
- Unused generic `caveman*` agent skills unless they are part of the supported
  contributor workflow; replace them with a project-level `AGENTS.md` that
  documents commands, invariants, and safe edit boundaries.

## P2 — product clarity and polish

- Hide or disable platform-incompatible controls dynamically (PPTX on Linux,
  PowerPoint cleanup toggles on FFmpeg hosts).
- Add an export estimate showing duration, expected temporary disk use, output
  size range, and why transition-heavy video costs more than static VFR video.
- Add queue controls: pause pending work, reprioritize, retry from a failed
  stage, and preserve/reuse completed intermediate artifacts.
- Add keyboard and screen-reader testing for dialogs, thumbnail editing,
  galleries, and the command palette.
- Replace browser-local settings/run state with server profiles when multi-user
  authentication is introduced.

## Changes completed during this audit

- Fixed mobile banner/card/wizard layout and removed duplicate offline noise.
- Removed dead duplicated screenshot JSX, corrected mojibake, and restored a
  clean frontend lint/build.
- Updated production frontend dependencies; production audit is now clean.
- Updated Flask, Werkzeug, Flask-CORS, Requests, and Pillow requirements.
- Removed mandatory MoviePy/proglog and unused `ffmpeg-python` dependencies;
  direct FFmpeg remains the default while optional fallback code is retained.
- Tightened default CORS origins, restricted remote restart, and made preflight
  report FFmpeg/ffprobe truthfully.
- Updated user-facing Linux MP4 guidance and workspace capability labels.
- Packaged backend imports and removed runtime/test `sys.path` mutation.
- Replaced executable config modules with frozen typed environment settings.
- Migrated runs, history, AI cache, pending queue, and ETA samples to WAL-mode
  SQLite with one-time JSON import.
- Added Linux artifact retention and a 2-GiB free-disk floor for small VMs.
- Added OpenAPI 3.1, request/run-correlated JSON logs, and FFmpeg media-time ETA.
- Routed legacy `/generate-sse` traffic through the persisted `/runs/*` pipeline.
- Removed the unused Flask UI and consolidated docs into architecture and
  operations guides.