Skip to content

Presentation Video UI Update Implementation Plan

Created: 2026-05-20 07:06 UTC Updated: 2026-05-20 07:06 UTC

Goal

Implement the approved Presentation Video setup flow so users generate and review the VO script before scene-detail generation, using Mastra narrative HITL behavior and preserving the existing scene editor as the post-generation surface.

Non-Goals

  • Do not use OpenSpec.
  • Do not remove scene-level image replacement in the Scene Editor.
  • Do not implement Brand Kit selection yet; show a disabled Brand Kit button and continue using the default Brand Kit.
  • Do not change Payload schema or add migrations unless implementation reveals an unavoidable blocker.
  • Do not rework final video rendering, audio generation, RAG ingestion internals, or the full scene editor.

Current Behavior

  • PresentationVideoPage has setup panels for Video Name, Business Docs, Video Description, Visuals, Visual Identity, a Regenerate VO Script checkbox, and a Generate Scenes button.
  • Video Description assistant can infer draftDescription and webSourceDescriptions; web sources are currently shown in an editable textarea.
  • Setup-stage visuals are selected alongside business docs and included in selectedRagSourceIds.
  • generatePresentationVideoScenesWithWorkflow starts presentationVideoWorkflow, which runs through narrative, visuals, slides, direction, compilation, persistence, job creation, and optional audio in one request.
  • regenerateVoScript controls whether existing voiceover/scenes are reused in the legacy compile path.

Target Behavior

flowchart TD
  name["Video Name"] --> docs["Business Docs"]
  docs --> desc["AI-assisted Video Description"]
  desc --> sources["Inferred Web Sources, read-only"]
  sources --> voBrief["VO Script Description: default tone/persona"]
  voBrief --> narrative["Run narrativeWorkflow"]
  narrative --> preview["VO Script Preview, one sentence per line"]
  preview --> identity["Visual Identity: Set, Bot, disabled Brand Kit"]
  identity --> resume["Go To Scene Details"]
  resume --> downstream["Resume/continue workflows: visuals, slides, direction, compile, persist, jobs"]
  downstream --> editor["Scene Editor"]
  • Video Description remains AI-assisted only. Display the inferred description in a non-editable formatted textarea or textarea-like surface.
  • Web data sources inferred by the assistant remain visible as a non-editable field.
  • Add a VO Script panel with default text:
Tone: Energetic, encouraging, and articulate.
Persona: Friendly, approachable and sophisticated.
  • VO Script assistant updates the VO Script Description and re-runs narrativeWorkflow.
  • VO Script Preview is generated before scene generation from narrative scene narration, formatted with each sentence on its own line.
  • Go To Scene Details replaces Generate Scenes; clicking it continues the workflow and opens the current Scene Editor after scenes/config are ready.
  • Existing presentations with reusable voiceover/scenes show the existing script in the preview. If edited, the modified narrative is used for subsequent scene generation.
  • Remove the setup Visuals panel and Regenerate VO Script checkbox.

Public Interfaces And Contracts

  • Add server action generatePresentationNarrativePreview(args) in src/app/(frontend)/app/presentation/actions.ts. It validates auth/workspace, video name, description, selected business-doc source IDs, web source descriptions, and optional prior suspended run; starts the Mastra flow through narrativeWorkflow; returns { presentationId, workflowRunId, suspendedStep, voiceoverPreview, narrativeScenes, webSourceDescriptions }.
  • Add server action continuePresentationFromNarrative(args). It accepts { presentationId, workflowRunId?, suspendedStep?, narrativeScenes?, setVariantId, botVariantId, skipAudioGeneration }, validates selected Set/Bot, resumes the suspended workflow when a run exists, or continues from persisted/approved narrative scenes for existing presentations.
  • Extend Mastra workflow contracts with a narrative review/HITL boundary after narrativeWorkflow. Use suspend() with payload containing presentationId, voiceoverPreview, and narrativeScenes; resume data includes { approved: true, setVariantId, botVariantId, brandKitId? }.
  • Keep Payload generated types unchanged. Store transient narrative review metadata in presentationStatusJson.setup.narrativeReview.

Affected Files

  • src/components/anuvax/presentation-video/presentation-video-page.tsx: setup UI, state, assistant wiring, preview/resume flow, removed Visuals panel and checkbox.
  • src/app/(frontend)/app/presentation/actions.ts: new narrative preview/continue actions, workflow run handling, existing-presentation VO preview loading.
  • src/mastra/workflows/presentationvideo.workflow.ts: add HITL suspend/resume step after narrativeWorkflow; defer Set/Bot persistence until resume.
  • src/mastra/tools/presentation/index.ts: allow prepare/update without Set/Bot for narrative preview; persist Set/Bot on resume.
  • src/mastra/schemas/config.schema.ts: update workflow input/resume-related schemas as needed.
  • src/mastra/workflows/sub/narrative.workflow.ts: accept VO Script Description guidance in narrative prompt.
  • tests/integration/** and E2E presentation tests: update old Generate Scenes, Visuals panel, and regenerate checkbox assumptions.

Affected Docs

  • Update this file as the source implementation plan.
  • During implementation, update ImplementationLog.md.
  • Update docs/core/PresentationVideoWorkflow.md to show the pre-scene narrative preview and HITL boundary.
  • Update docs/state/CurrentImplementationMap.md, docs/state/ServerActionsMap.md, and docs/state/WorkflowMap.md for the new actions and workflow split.
  • Update docs/state/KnownGaps.md only if any approved behavior is intentionally deferred.
  • No docs/web/mkdocs.yml nav change is needed unless files are renamed.

Data And Schema Impact

  • No Payload collection schema change.
  • No migration.
  • No src/payload-types.ts regeneration expected.
  • Use existing presentationStatusJson JSON field for transient review state:
{
  "setup": {
    "narrativeReview": {
      "status": "pending | approved | superseded",
      "workflowRunId": "string",
      "suspendedStep": "string | string[]",
      "voiceoverPreview": "string",
      "narrativeScenes": {},
      "voScriptDescription": "string",
      "updatedAt": "ISO datetime"
    }
  }
}
  • Existing presentationScript, persisted scenes, and compilation voiceoverJson remain the source for reusable VO preview on existing presentations.

Ordered Tasks

  • [x] 1. Add narrative preview helpers: format scene narration into one-sentence-per-line preview, derive preview from existing scenes/voiceover JSON, and normalize default VO Script Description text.
  • [x] 2. Update Mastra workflow: make Set/Bot optional before narrative, add narrative-review suspend step after narrativeWorkflow, and persist selected Set/Bot/default Brand Kit on resume.
  • [x] 3. Add server actions for narrative preview and continue-from-narrative, including best-effort cancellation of superseded suspended runs when VO guidance changes.
  • [x] 4. Update PresentationVideoPage setup UI: remove setup Visuals panel and Regenerate VO Script checkbox; render non-editable Video Description and web sources; add VO Script Description assistant and VO Script Preview; render Select Set, Select Bot, disabled Brand Kit buttons; rename button to Go To Scene Details.
  • [x] 5. Preserve Scene Editor visual replacement by keeping visual upload/library paths only where used from scene-level controls.
  • [x] 6. Update load/hydration behavior so existing presentations show existing VO preview and can continue without forcing a regenerate unless the user edits VO guidance.
  • [x] 7. Update tests and mocks for the new actions, suspended workflow result, resume behavior, removed controls, and button labels.
  • [x] 8. Update docs and ImplementationLog.md.

Verification Plan

  • Run pnpm lint.
  • Run pnpm typecheck.
  • Run pnpm test:int.
  • Run pnpm test:e2e because route-level presentation flow changes.
  • Add or update integration tests for:
  • narrative preview action returns preview, run id, suspended step, and persisted review metadata;
  • VO assistant re-runs narrative and supersedes the previous pending run;
  • Go To Scene Details resumes/continues downstream workflow and returns the existing compile result shape;
  • existing presentation VO script is shown and reused;
  • setup-stage visual sources are not included in generation, while scene-level visual override still works;
  • Regenerate VO Script control is absent.
  • Add or update UI/e2e assertions for:
  • Go To Scene Details label;
  • disabled Brand Kit button;
  • read-only inferred web sources;
  • no setup Visuals panel.

Docs Parity Checklist

  • [x] ImplementationPlan.md contains goal, non-goals, current/target behavior, affected files/docs, data impact, tasks, verification, docs checklist, and acceptance criteria.
  • [x] ImplementationLog.md records implementation decisions, files changed, commands run, deviations, and known gaps.
  • [x] Core/state docs describe narrative preview before scene details and the Mastra HITL boundary.
  • [x] Docs continue to clarify that setup-stage visuals are removed while scene-level replacement remains.

Acceptance Criteria

  • User can complete setup in the approved order: name, docs, AI-assisted description, inferred web sources, VO Script guidance, VO preview, visual identity, scene details.
  • VO preview is generated before scene-detail generation via narrativeWorkflow and is formatted one sentence per line.
  • Editing VO guidance re-runs narrative and updates the preview used for scene generation.
  • Go To Scene Details resumes or continues the downstream workflows and opens the existing Scene Editor with generated scenes.
  • Setup Visuals panel and Regenerate VO Script checkbox are gone.
  • Brand Kit button is visible but disabled, and default Brand Kit behavior still works.
  • Existing presentations with voiceover/scenes show their current VO script preview and can continue generation without requiring the removed checkbox.
  • No workspace boundary, auth validation, or scene-level visual override behavior regresses.