From 14e65a933b6e5abeff270243fc217d5cf1a7cba9 Mon Sep 17 00:00:00 2001 From: Lovebug MCP Date: Sun, 17 May 2026 16:26:57 +0000 Subject: [PATCH] =?UTF-8?q?mcp:=20project-plan=20=E2=80=94=20PBS=20Hub=20?= =?UTF-8?q?=E2=80=94=20Scene=20Management=20&=20Pre-Production=20Extension?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Sources/Dev/pbs-hub-scene-management.md | 285 ++++++++++++++++++++++++ 1 file changed, 285 insertions(+) create mode 100644 Sources/Dev/pbs-hub-scene-management.md diff --git a/Sources/Dev/pbs-hub-scene-management.md b/Sources/Dev/pbs-hub-scene-management.md new file mode 100644 index 0000000..14f3f58 --- /dev/null +++ b/Sources/Dev/pbs-hub-scene-management.md @@ -0,0 +1,285 @@ +--- +created: '2026-05-17' +path: Sources/Dev +project: pbs-hub-scene-management +tags: +- pbs +- pbs-hub +- flask +- mysql +- video-production +- scenes +- ui +- sortablejs +- tablet +type: project-plan +--- + +## Goal + +Extend pbs-hub (the merged successor to pbs-video-manager + pbs-api) to support the full video production lifecycle — not just the post-shoot/publish work the tool covers today. Add pre-production authoring surfaces (outline, treatment, scenes with per-scene scripts), a structured scene/shot list model, and a tablet-friendly Present Mode for shoot day that solves the specific pain of *forgetting shots while shooting*. + +The original animating idea of pbs-hub was a sidecar to Trello — Trello holds the project board, the Hub holds the depth Trello can't (file management, ffmpeg, description building). This extension stays true to that philosophy: Trello can't model "intro scene has three shots, two done, one not." The Hub adds that depth, in the same pattern. + +CLI is untouched. Existing post-shoot surfaces (Overview, Publish Check, Desc Build) are untouched. Project Detail navigation shifts from tabs to a persistent card rail (C2 pattern). + +--- + +## Locked Decisions + +### Schema (all new tables → `pbs_automation` database) + +**`Project` (extended):** +- `outline` TEXT, nullable — rough story scratch +- `treatment` TEXT, nullable — narrative prose, scene-by-scene + +**`ProjectMetadata` (new):** +- `id` PK, `project_id` FK → `projects.id` +- `key` VARCHAR, `value` TEXT, `sort_order` INT +- Generic key/value to allow new metadata fields via Settings CRUD without schema migrations + +**`ProjectMetadataField` (new, Settings-managed):** +- `id` PK, `key` VARCHAR, `label` VARCHAR, `sort_order` INT +- Seeded: `logline`, `working_title`, `tagline` + +**`Scene` (new):** +- `id` PK, `project_id` FK → `projects.id`, `sort_order` INT +- `title`, `purpose`, `in_shot`, `background` (text fields, freeform) +- `script` TEXT — per-scene script (the narrative lives at scene level, not project level) + +**`SceneItem` (new — Path B, separate from `ChecklistItem`):** +- `id` PK, `scene_id` FK → `scenes.id`, `sort_order` INT +- `label` VARCHAR +- `item_type` ENUM: `shot`, `reminder` +- `is_complete` BOOLEAN, `created_at` TIMESTAMP + +**`DefaultScene` (new):** +- Template scenes seeded on `pbs init`. Same shape as `Scene` minus `project_id`. + +**`DefaultSceneItem` (new):** +- Template scene items. `default_scene_id` FK → `default_scenes.id`. Same shape as `SceneItem` minus `scene_id` and `is_complete`. + +**Path B rationale:** `ChecklistItem.category` is workflow-stage-shaped (export/wordpress/youtube/instagram/email). Scene items don't have a workflow-stage equivalent. Forcing them into `ChecklistItem` would either compromise the category column's clear meaning or create silent-leak bugs (every existing `ChecklistItem` query becomes a future bug site). The duplication cost is bounded: one new model + ~60-80 LOC service module. The new code lives next door, doesn't touch the working publish-check path, and can't poison it. + +**`ChecklistItem` and `DefaultChecklistItem` are UNCHANGED.** + +### Status workflow + +`Project.status` stays free VARCHAR. Adds: + +``` +planned → scripted → raw → editing → exported → final → published → archived +``` + +All transitions manual. Coexists with reel-flavored statuses (`draft / ready / live-matched / live-needs-review`) — disambiguated by `project_types.name`. + +### Terminology + +- **Scene list** — new pre-production surface (scenes + scene items) +- **Checklist** — existing publish-pipeline surface (unchanged) +- **Outline / Treatment / Script** — industry-standard authoring vocabulary +- **Scene / Shot / Shot list** — industry-standard production vocabulary +- **Item types** — `shot` (visual capture) and `reminder` (non-shot task) + +### UI: Persistent Card Rail + Canvas (C2 pattern) + +Project Detail tabs are replaced by a persistent left rail of live status cards, with the selected surface filling the canvas. Rail collapses on tablet for Present Mode. + +**Rail card order (lifecycle):** + +``` +Overview / Outline / Treatment / Scenes / Publish Check / Desc Build +``` + +**Each rail card shows live status**, not just a label: +- Overview — project title, status badge, last activity +- Outline — first line preview or "empty" +- Treatment — paragraph count, last edit timestamp +- Scenes — scene count + mini completion indicator (color-coded per completion state) +- Publish Check — X of Y complete with progress bar +- Desc Build — drafted / not started / complete + +**Surfaces:** + +- **Overview** — existing, unchanged +- **Outline** — single freeform markdown field, standard editor +- **Treatment** — split-pane: treatment prose on left, running scene title list on right with "Add scene" button and drag-to-reorder. Right pane is a live view of `Scene` records; edits sync with the Scenes surface +- **Scenes** — two modes: + - *Edit Mode* (default): full CRUD on scenes (briefing fields, per-scene script) and scene items (label, type, complete, reorder) + - *Present Mode* (shoot day): scene strip across top, color-coded per scene completion (gray = empty, red = none complete, amber = partial, green = all complete); focused scene shows briefing fields (read-only) + shot list split above/below the line + X of Y indicator + inline "Add item"; non-sequential scene navigation; shows project title + date for on-camera recording context +- **Publish Check** — existing, unchanged +- **Desc Build** — existing, unchanged + +**Drag-drop:** SortableJS (CDN, touch-friendly). Used for scene reordering (in Treatment right pane and Scenes Edit Mode) and item reordering (in Scenes Edit Mode). + +**Pre-shoot handling:** Pre-shoot is the first scene of every project, populated with `reminder`-type items. No separate model or surface. Defaults seeded via `DefaultScene` + `DefaultSceneItem` on `pbs init`. + +**Scene completion derivation (not stored):** +- Empty scene (no items) → gray +- Items exist, none complete → red +- Partial completion → amber +- All complete → green + +Above/below-the-line in the item list driven by `is_complete`. Single `sort_order` drives both zones. Un-check pops item back above the line naturally. New items added mid-shoot land at the end of the above-the-line group. + +### Tests + +Bootstrap pytest scaffold (pyproject section, `conftest.py`, in-memory SQLite fixture) as part of this work. Write tests for the new code: scenes model, scene items, completion derivation, migration smoke tests. Do not backfill tests for existing untested code. + +### Deploy + +Lovebug builds and tests on the dev environment, stops short of deploy. Travis runs deploy via the `wordpress-install` Ansible repo (`wp-i`) to staging first, then production. Pre-deployment verification: confirm Phase 5 baseline is live on prod MySQL before this migration runs: + +```bash +mysql -u pbs_api -p pbs_automation -e 'SHOW TABLES' +``` + +If `projects`, `project_types`, and `platform_posts` are present, prod is cut over and this migration adds on top. If not, Phase 5 baseline lands first. + +### CLI + +No CLI changes. No `sync_checklist_items()` changes — Path B isolates scene items in their own table, so the existing sync mechanism is untouched. Scene-aware sync, if ever needed, is a separate endpoint with its own shape (future enhancement, not v1). + +--- + +## Open Items + +These need verification or input before or during implementation: + +- [ ] **Production MySQL state** — confirm Phase 5 baseline tables (`projects`, `project_types`, `platform_posts`) are live on prod before deploying this migration. If not, reconcile first. +- [ ] **`sql/create_tables.sql` cleanup** — add a one-line note marking the database housing question (was `pbs_automation` or `pbs_content_hub`?) as **RESOLVED → `pbs_automation`**. Saves the next reader from hitting the same TBD. +- [ ] **Default scene/item seed content** — implementation agent picks reasonable defaults for `DefaultScene` + `DefaultSceneItem` (e.g., a "Prep" scene with charge-batteries / format-cards reminders). Fully editable via CRUD after init. +- [ ] **Migration files location** — recommend `sql/migrations/NNN_.sql` with numbered files since there's no Alembic. This work adds the first such files; future schema changes follow the pattern. + +--- + +## Phases + +### Phase 1 — Schema migration + +One numbered migration file in `sql/migrations/` that adds all new tables and columns in a single transaction. Targets `pbs_automation` database. + +- [ ] `ALTER TABLE projects ADD COLUMN outline TEXT DEFAULT NULL` +- [ ] `ALTER TABLE projects ADD COLUMN treatment TEXT DEFAULT NULL` +- [ ] `CREATE TABLE project_metadata (...)` +- [ ] `CREATE TABLE project_metadata_fields (...)` + seed `logline`, `working_title`, `tagline` +- [ ] `CREATE TABLE scenes (...)` +- [ ] `CREATE TABLE scene_items (...)` +- [ ] `CREATE TABLE default_scenes (...)` + seed reasonable defaults +- [ ] `CREATE TABLE default_scene_items (...)` + seed reasonable defaults +- [ ] Bootstrap pytest scaffold + first migration smoke test +- [ ] Update `sql/create_tables.sql` to match (so fresh deploys are consistent) + +### Phase 2 — Rail framework + +Replace the existing 3-tab implementation in `project_detail.html` with the persistent card rail + canvas pattern. Existing surfaces (Overview, Publish Check, Desc Build) become canvas-rendered with placeholder rail cards. + +- [ ] Rail component (Jinja partial), styled with Tailwind +- [ ] Rail card with live-status props (label, status indicator, click handler) +- [ ] Canvas slot in Project Detail layout +- [ ] Wire existing surfaces (Overview / Publish Check / Desc Build) into canvas +- [ ] Active card visual treatment +- [ ] Rail collapse mechanism (for Present Mode later) +- [ ] Verify `/pbscontenthub` URL prefix awareness in new routes + +### Phase 3 — Outline surface (end-to-end) + +Simplest of the new surfaces. Validates the rail-card live-status pattern with real data. + +- [ ] Service method to read/write `Project.outline` +- [ ] API endpoint +- [ ] Route + template (single textarea, autosave or save button) +- [ ] Rail card shows first-line preview or "empty" +- [ ] Tests + +### Phase 4 — Treatment surface (end-to-end) + +Split-pane layout. Right pane is a live `Scene` title list with reorder + "Add scene." Requires `Scene` CRUD basics in place but not the full Scenes Edit Mode. + +- [ ] Scene model + basic service (create, read, update title, delete, reorder) +- [ ] API endpoints for scene list management +- [ ] Treatment route + split-pane template +- [ ] SortableJS integration for scene reorder in right pane +- [ ] Rail card shows paragraph count + last edit timestamp +- [ ] Tests + +### Phase 5 — Scenes surface (Edit Mode first) + +Build out full scene CRUD with briefing fields, per-scene script, and scene items (the scene list). Edit Mode only — no Present Mode yet. + +- [ ] Scene briefing fields editor (purpose, in_shot, background) +- [ ] Per-scene script editor (textarea, autosave) +- [ ] SceneItem service + API endpoints (CRUD, toggle, reorder, set type) +- [ ] Scene Edit Mode template — scene selector, briefing form, script editor, item list with above/below-the-line split +- [ ] Item type indicators (shot vs reminder, visually distinguished) +- [ ] Add/remove items inline +- [ ] SortableJS for item reorder +- [ ] Rail card shows scene count + completion summary +- [ ] Tests + +### Phase 6 — Scenes surface (Present Mode) + +Tablet-optimized shoot-day view. Layered on top of the Edit Mode infrastructure. + +- [ ] Mode toggle ("Present" button in Edit Mode, "Edit" button / back in Present Mode) +- [ ] Scene strip component — horizontal banner of color-coded chips (gray/red/amber/green per scene completion state), 44px+ tap targets, horizontal scroll if needed +- [ ] Active chip treatment (border or background accent) +- [ ] Focused scene view — project title + date header, briefing fields (read-only), item list with above/below-the-line, X of Y indicator +- [ ] Inline "Add item" on focused scene +- [ ] Item toggle works directly in Present Mode (taps the action, no mode switch) +- [ ] Rail collapses on Present Mode entry +- [ ] Tests + +### Phase 7 — Metadata fields + +Project metadata key/value system with Settings CRUD for adding new fields. + +- [ ] ProjectMetadata service + API +- [ ] ProjectMetadataField management in Settings +- [ ] Metadata display + edit on Overview surface (or wherever fits best — implementation call) +- [ ] Tests + +### Phase 8 — Status workflow + +Small, slots anywhere after schema is live. + +- [ ] Add `planned` and `scripted` to status options +- [ ] Status dropdown / picker UI on Overview +- [ ] Document status semantics (planned = idea, scripted = ready to shoot, raw = footage exists) + +--- + +## Notes + +### Cross-references + +- **Existing codebase:** `pbs-video-manager` (internally branded "PBS Hub"), at `/opt/projects/pbs/pbs-video-manager`, git remote `git-real-projects-pvm:trucktrav/pbs-video-manager.git`, branch `master` +- **Phase 5 architecture:** `content-hub-phase5-architecture` +- **Phase 5 schema:** `content-hub-database-schema` +- **Phase 5 planning:** `content-hub-phase5-planning` +- **Original master plan:** `instagram-automation-content-hub-plan` + +### Design philosophy notes + +- **Sidecar to Trello philosophy preserved.** Trello is the project board, the Hub is where the work lives. New pre-production surfaces (outline, treatment, scenes, scene list) are *more work that lives in the Hub* — same philosophy, more depth. Not a different pattern grafted on. +- **Custom is appropriate.** Off-the-shelf tools can't do "scene strip color-coded by completion across multiple scenes during a tablet-on-the-counter shoot." That's why this exists. The customization solves a specific pain (forgetting shots) that Trello, Notion, etc. can't. +- **Function over polish for v1.** Visual polish ("modern and sexy") is deferred to a follow-on project. Tablet-friendly drag-drop is the one place where polish and function overlap — bad drag-drop on a tablet is bad function. SortableJS handles that. + +### Flagged for plan readers + +- **`platform_posts` n8n lookup chain unaffected.** The comment-reply automation path (`platform_posts → projects → pbs_recipes`) is untouched. Schema additions are purely additive to `projects`. No risk to existing automation. +- **Status vocabulary coexistence.** `projects.status` holds both reel-flavored values (`draft / ready / live-matched / live-needs-review`) and video-flavored values (`planned → scripted → ... → archived`). Disambiguated by `project_types.name`. The eventual status-as-lookup-table refactor (when Trello integration lands) needs to accommodate both. +- **Rail vs. intra-page filter chips.** Project Detail now uses the rail nav. Library/Settings keep their existing filter chip pattern (different metaphor, both stay). Future polish pass may unify them — flagged below. + +### Out of scope (deferred / future) + +- **Auto-generation of scenes from treatment** (structured parsing of treatment headings into Scene records). Manual handoff for v1. +- **Take tracking / version notes** (the active "clapper" with per-take metadata). +- **Quick-action affordances on rail cards** (e.g., one-tap to Present Mode from the Scenes card without entering Edit Mode first). +- **Visual polish pass.** Typography, motion, refined cards, dark mode, color-change animations on scene strip chips, progress dots inside chips, etc. Its own future project. +- **Jinja macro extraction.** Status pill, card, badge components. Done as part of the polish pass, coherently across old and new surfaces. +- **Rail vs. filter chip pattern unification.** Done as part of the polish pass. +- **Inline briefing editing in Present Mode.** v1 is read-only in Present Mode; switch to Edit Mode for changes. +- **Scene-aware CLI sync.** If push/pull ever needs to round-trip scene data, build a separate endpoint with its own shape. Not v1. +- **Unified "everything checkable" aggregation.** If a project-wide progress meter across publish items + scene items is wanted, it's a service-layer `UNION` aggregator. Not v1; flagged so it doesn't drive premature data-model fusion. +- **From existing out-of-scope list (unchanged):** YouTube API integration, thumbnail management, multi-user roles, notification system. \ No newline at end of file