[6627bc00] Restore deleted preview-frames @router.get handlers in video.py + 10 tests + schemas (#792)

* [6627bc00] feat(video): restore deleted preview-frames @router.get handlers + schemas + 10 tests

Restore the two preview-frames @router.get handlers that were wrongly
deleted during the route-helper extraction: GET /preview-frames/{task_id}
(listing) and GET /preview-frames/{task_id}/{orientation}/{filename} (PNG
serve). Both are thin handlers in roboco/api/routes/video.py that delegate
to previews_root() and list_orientation_frames() in roboco/utils/video.py
(new), reusing the existing resolve_preview_path confinement guard from
video_engine for the per-frame route. Add PreviewFrameResponse and
VideoPreviewFramesResponse schemas to roboco/api/schemas/video.py. Restore
10 integration tests in test_video_routes.py covering listing, metadata,
404 cases, non-CEO forbidden, and symlink traversal confinement.

* [6627bc00] docs(video): map preview-frames helper extraction to roboco/utils/video.py

Update docs/map/video-engine.md to reflect that the two preview-frames
@router.get handlers are now thin route handlers delegating to new helpers
in roboco/utils/video.py (previews_root, list_orientation_frames), with
resolve_preview_path reused from video_engine. Add a Files-table row for
the new utils module and a Changes-Since-Baseline entry for the PR #792
restoration of the wrongly-deleted handlers, schemas, and 10 tests.

---------

Co-authored-by: Backend Developer 1 <be-dev-1@roboco.tech>
Co-authored-by: Backend Documenter <be-doc@roboco.tech>

docs/map/video-engine.md

@@ -17,7 +17,8 @@ The RoboCo video engine: a default-off subsystem that authors bespoke short mark
 | `roboco/services/gateway/content_actions.py` `propose_video` | Server-side action: team-gated (`_caller_team` rejects be-dev/fe-dev), resolves the caller's open video task, `markers.set_video_draft` with the metadata. | — |
 | `roboco/services/gateway/content_actions.py` `request_render` | Do-verb (developer/QA): renders the caller's ACTUAL composition to keyframe PNGs via the sidecar's frames mode and stamps the `render_preview` marker — dev renders their own tree (worktree-aware, `head_sha`/`dirty` stamped), QA a read-only branch export (`WorkspaceService.export_branch_motion`). Frames land at the container-shared `{workspaces_root}/{project}/.previews/{task8}/{orientation}/`. | — |
 | `roboco/foundation/policy/tracing.py` `RENDER_VERIFIED` | `i_am_done` requirement on `source=video` tasks: no stamped `render_preview` → tracing gap naming `render_preview` (hint: call `request_render`, Read every frame). Mirrored in the possibilities-matrix fast path. | — |
-| `roboco/api/routes/video.py` `GET /video/preview-frames/{task_id}` / `.../{orientation}/{filename}` | CEO-gated routes serving the dev's already-rendered `request_render` preview frames — a `source=video` authoring task reaches `awaiting_ceo_approval` with no MP4 yet (rendering only happens post-completion), so the CEO otherwise has nothing to review. Frame listing is parsed from the self-describing `.previews/{task8}/{orientation}/frame-<idx>-of-<n>-at-<t>s.png` filenames (`_FRAME_NAME_RE`) rather than the `render_preview` marker (which only holds the LAST call's single orientation); the per-frame route streams a PNG behind the same `_resolve_preview_path` confinement guard the composition-HTML proxy already used. | — |
+| `roboco/api/routes/video.py` `GET /video/preview-frames/{task_id}` / `.../{orientation}/{filename}` | CEO-gated thin route handlers serving the dev's already-rendered `request_render` preview frames — a `source=video` authoring task reaches `awaiting_ceo_approval` with no MP4 yet (rendering only happens post-completion), so the CEO otherwise has nothing to review. `list_preview_frames` delegates listing to `previews_root` + `list_orientation_frames` in `roboco/utils/video.py` (frame index/timestamp parsed there from the self-describing `.previews/{task8}/{orientation}/frame-<idx>-of-<n>-at-<t>s.png` filenames via `_FRAME_NAME_RE`, rather than the `render_preview` marker which only holds the LAST call's single orientation); `get_preview_frame` streams a PNG behind `resolve_preview_path` reused from `video_engine` (the same confinement guard the composition-HTML proxy uses). Response schemas `PreviewFrameResponse` / `VideoPreviewFramesResponse` live in `roboco/api/schemas/video.py`. | — |
+| `roboco/utils/video.py` | Pure path/listing helpers for the CEO preview-frames routes — no DB access, no route definitions. `previews_root(task_id, project_slug)` returns the container-shared `{workspaces_root}/{project}/.previews/{task8}/` dir; `list_orientation_frames(orientation_dir)` parses the `frame-<idx>-of-<n>-at-<t>s.png` filenames (`_FRAME_NAME_RE`) into `ParsedFrame` namedtuples sorted by index. Extracted out of the route module so the route layer holds only `@router`-decorated handlers. | 55 |
 | `alembic/versions/062_tiktok_credentials.py` | Migration 062 — the `tiktok_credentials` singleton row (Fernet-encrypted OAuth2 secrets, all-or-nothing set/clear, mirroring the git-token / `x_credentials` pattern). | 44 |
 | `video-renderer/` | The sidecar: `server.js` (HTTP+tarball boundary), `render.js` (`@hyperframes/producer` `createRenderJob` + `executeRenderJob`, system `ffmpeg`, headless Chromium). Credential-free and git-free — reads only what's POSTed. pnpm-managed (`pnpm-lock.yaml`, no npm `package-lock.json`); `@hyperframes/producer` pinned exact at `0.7.36` (`0.7.60` fails every render). | — |
 | `docker/video-renderer.Dockerfile` | Sidecar image (`roboco-video-renderer`): Node + Chromium + system `ffmpeg`; installs `@hyperframes/producer`. No RoboCo source, no creds. | — |
@@ -47,6 +48,7 @@ CEO ACT: `GET /api/video/posts` lists held drafts (including `mp4_paths`); `GET
 ## Changes Since Baseline
 
 - **2026-07-20** (#608, `a5d8c6bd`, "CEO can preview a video authoring task's frames before approving"): two CEO-gated routes serve the `request_render` preview frames (see Files above) so the CEO has something concrete to review at `awaiting_ceo_approval` before any MP4 exists. The task-detail Overview gains a Video preview card — a 9:16/1:1 toggle + prev/next/scrubber frame stepper with composition id, duration, and a dirty badge — shown for a video task with preview frames or awaiting CEO approval.
+- **2026-08-01** (PR #792, `26560bcb`, "Restore deleted preview-frames handlers + schemas + tests"): a prior route-helper extraction (#769) wrongly deleted both preview-frames `@router.get` handlers, the `PreviewFrameResponse`/`VideoPreviewFramesResponse` schemas, and all 10 integration tests instead of only moving the non-decorated helpers. This restores the two handlers in `roboco/api/routes/video.py` as thin `@router.get` delegators (route layer keeps the decorated handlers; only module-level helpers move), the two schemas in `roboco/api/schemas/video.py`, and the 10 integration tests in `tests/integration/test_video_routes.py` (listing, metadata, 404s, non-CEO forbidden, symlink traversal confinement). The listing/path helpers now live in `roboco/utils/video.py` (`previews_root`, `list_orientation_frames`); `resolve_preview_path` is reused from `video_engine`. No observable behavior, route path, or schema shape change — placement-only.
 - **2026-07-17** (PR #543, `3e801697`): Two renderer root causes fixed — `@hyperframes/producer` was floating (`^0.7.36`, no lockfile), so image builds silently picked up `0.7.60`, which fails EVERY render ("Cannot access 'rt' before initialization"); pinned exact (`0.7.36`, no caret) and committed a lockfile (regenerated as `pnpm-lock.yaml` by the immediate follow-up `a12fefcb`, not the npm `package-lock.json` this PR first wrote — this package is pnpm-managed). Second: the producer's per-clip visibility scheduler runs on a clock that lags ~50% behind the encoded timeline on a long cut, so tail scenes (past roughly the halfway mark) were silently missing from the MP4 regardless of authoring — fixed by treating `class="clip"` + `data-start`/`data-duration` as a structural-layer-only primitive and driving every beat with base-hidden styles + a delayed CSS animation instead (documented in `motion/README.md`'s "Clip windows are for structural layers only" rule). Also added the two choreography engines to `motion/kit/kit.js` (`choreographCursor` / `choreographCamera`, see Files above) plus a "Cinematography & rhythm" section in `motion/README.md` and a craft-bar block in the dev video spawn prompt (`roboco/runtime/orchestrator.py`) so a locked-off camera or a popping/freezing cursor reads as an automatic revision.
 - **2026-07-17** (PR #544, `fd621f0d`): The three craft capabilities wired one hop closer to the hands doing video work — vendored the vendor's own official HyperFrames agent skills (`hyperframes-core`/`-creative`/`-keyframes.md`, see Files above; supersedes the external-pointer-only version briefly added by the intervening `1416bd1d`); registered the `playwright` MCP for a ux-dev spawned onto a `source=video` task (`_is_video_authoring_spawn`, fail-closed role/team/task-source probe — gating-only, `agent-ux`'s image already bakes the browser); and added a video-mode override to the `ux_ui` team prompt's design bar ("video-authoring tasks are FILMS, not UI — these dials do not apply") so a video task no longer reads its own "dense product UI → motion 2-3" dial as license to ship a static slideshow.
 - **2026-07-17** (Wave 6, PR #550): Authoring craft, not engine code — `motion/README.md` gained `## Visual design bar (demo/kit register)` (spacing/hierarchy, beat pacing, `pk-chip`/`pk-pill` semantic discipline, camera+cursor+rhythm, anti-generic tells for the `kit/` register), four upstream HyperFrames craft references vendored verbatim under `motion/skills/references/` (fixing `hyperframes-creative.md`'s previously-dead `references/` pointers), and a new `motion/skills/hyperframes-catalog-index.md` (133-entry HyperFrames catalog vocabulary index, read-on-demand). No service/verb/schema change; the render/post pipeline documented above is untouched.