roboco/docs/ux_ui/design/01-video-request-composition-controls.md

Video request: project picker, re-render control, composition preview panel

Interaction spec for three additions to the existing on-demand video flow: a project picker in the request dialog, a re-render control with four visual states, and a composition preview panel (live iframe + captions side by side) in the approval screen. Written so a frontend developer can implement directly from this document without further design clarification.

Scope and where this lives

All three pieces extend one existing file: panel/src/components/dashboard/video-post-queue.tsx.

Piece	Existing component it extends	New sub-component to add
Project picker	RequestVideoDialog (the "Request a video" dialog)	none — reuses ProjectSelector
Re-render control	VideoPostRow (one card in the approval queue)	RerenderControl
Composition preview panel	VideoPostRow	CompositionPreviewPanel

None of this replaces the existing rendered-MP4 preview and caption textareas already in VideoPostRow (lines 145-258 of the current file) — the composition preview panel is a new block shown above them, giving the CEO a fast, pre-render look at the live composition before the MP4 cuts exist or while iterating.

This spec does not cover the backend contract (project_id on VideoRequestBody, the re-render action route, or the composition-HTML proxy route) — those are backend/frontend implementation details tracked on the sibling code task. Every prop name below is written as the request shape the frontend needs; the implementer wires it to whatever route lands.

Design bar dial read: this is dense product UI (an approval queue inside the existing panel chrome), not a landing surface — variance 2, motion 2, density 7, per the UX/UI cell's default for dashboard work. No new color, radius, or shadow tokens; every value below is a token or class already used in video-post-queue.tsx or release-proposal-card.tsx.

---

1. Project picker (RequestVideoDialog)

Component

Reuse ProjectSelector from panel/src/components/projects/project-selector.tsx as-is — it already renders a Select grouped by cell (Backend / Frontend / UX/UI / Other) with a FolderGit2 icon and a cell Badge, matching this dialog's existing shadcn/ui primitives (Select, Label, Input, Textarea, Checkbox are already imported in this file).

ProjectSelector today has no way to restrict the list to video-enabled projects. Add one optional prop rather than a new component:

interface ProjectSelectorProps {
  // ...existing props unchanged...
  videoEngineOnly?: boolean; // when true, filter `projects` to video_engine_enabled === true before grouping
}

video_engine_enabled is already a field on Project (panel/src/types/index.ts:1026) but is not on ProjectSummary (the shape useProjects() / GET /projects returns today, panel/src/types/index.ts:1081-1090) — the backend task must add video_engine_enabled: boolean to ProjectSummary for this filter to work client-side. RequestVideoDialog passes videoEngineOnly.

Placement

Insert the picker as the first field inside RequestVideoDialog's <div className="space-y-4"> (currently Occasion, Brief, Platforms — see video-post-queue.tsx:346-386), before Occasion, using the exact same space-y-2 wrapper and Label pattern every other field in this dialog uses:

<div className="space-y-2">
  <Label htmlFor="video-request-project">Project</Label>
  <ProjectSelector
    value={projectId}
    onChange={setProjectId}
    videoEngineOnly
    allowClear={false}
    placeholder="Select a project…"
  />
</div>

projectId is new dialog state (useState<string | null>(null)), reset in the same onSuccess/cancel paths that already reset occasion/brief/ platforms (video-post-queue.tsx:308-311).

States

State	Trigger	Visual
Loading	useProjects() still fetching	ProjectSelector's own disabled={disabled || isLoading} on the Select trigger — matches the dialog's existing pattern of disabling inputs while a mutation/query is in flight. No separate spinner needed; the trigger just reads inert.
Empty	Query resolved, zero projects have video_engine_enabled: true	Replace the Select with a one-line <p className="text-xs text-muted-foreground"> reading "No projects have the video engine enabled — turn it on in a project's settings first." — same copy pattern as the existing "No projects exist yet" hint under the MegaTask checklist in intake-form.tsx:176-180.
Populated, unselected	Projects loaded, none chosen	Trigger shows the placeholder text, muted-foreground color (shadcn default SelectValue behavior — no override needed).
Selected	A project is chosen	Trigger shows FolderGit2 icon + project name + cell Badge, exactly as ProjectSelector already renders it (project-selector.tsx:98-108).

Validation

canSubmit (video-post-queue.tsx:330-333) gains projectId !== null as a fourth condition alongside occasion/brief/platforms — the picker is required, matching every other field in this dialog.

---

2. Re-render control (VideoPostRow)

Component

New RerenderControl sub-component, colocated in video-post-queue.tsx next to VideoPostRow (mirrors how RequestVideoDialog already sits next to VideoPostQueue in the same file):

type RerenderState = "idle" | "loading" | "stale" | "error";

function RerenderControl({
  state,
  onRerender,
}: {
  state: RerenderState;
  onRerender: () => void;
}) { /* ... */ }

state is derived, not stored redundantly: stale when the draft's captions or occasion have been edited locally since the last successful render (compare against the same edited*/local-state pattern VideoPostRow already uses for captions, video-post-queue.tsx:98-101); loading while the re-render mutation is in flight; error when that mutation's last attempt failed; idle otherwise (freshly rendered, nothing pending, no error).

Placement

Directly above the cut-switcher buttons (video-post-queue.tsx:160-184), right-aligned, same row as the cut buttons on sm: and up:

┌ VideoPostRow ─────────────────────────────────────────────┐
│  [Film] Video   [occasion badge]                            │
│  Title                                                       │
│  Script excerpt…                                             │
│                                                                │
│  [9:16] [1:1]                          [Re-render ⟳ idle] ←  │
│  ┌ Composition Preview Panel ───────────────────────────┐   │
│  │  iframe            │  captions                        │   │
│  └────────────────────┴───────────────────────────────────┘   │
│  …existing edit-caption blocks, Reject / Approve…            │
└────────────────────────────────────────────────────────────┘

Visual spec per state

Same Button primitive already imported in this file, size="sm", plus lucide-react icons already available in the codebase (RefreshCw, AlertTriangle, CheckCircle2 — the last two already imported elsewhere in this file).

State	Button variant	Icon	Label	Disabled	Extra
idle	outline	RefreshCw (static, no spin)	"Re-render"	No	none
loading	outline	RefreshCw with className="animate-spin" (exact pattern used for the navbar refresh button, header.tsx:111)	"Re-rendering…"	Yes	aria-live="polite" wrapper so screen readers announce the state change
stale	default (filled — draws the eye, matches how bg-amber-500/10 gaps banner in release-proposal-card.tsx:181 is used to flag "needs attention") with an added text-amber-950 bg-amber-500 hover:bg-amber-500/90 override	RefreshCw	"Re-render (edited)"	No	A small Badge variant="outline" reading "stale" is not needed — the button label already carries the meaning; do not duplicate it in a second element
error	destructive	AlertTriangle	"Retry re-render"	No	title attribute carries the last error message (mirrors the disabled-cut-button title pattern at video-post-queue.tsx:166-169); a one-line <p className="text-xs text-destructive"> under the button shows the same message so it is not tooltip-only

State transitions: idle/stale/error → click → loading → mutation resolves → idle (success) or error (failure). Editing a caption or the occasion while in idle → stale. There is no user action that transitions directly out of loading except the mutation settling — the button stays disabled for the whole request, preventing double-submission (same re-entrancy concern already handled via submittingRef in spawn-agent-dialog.tsx:40).

---

3. Composition preview panel (VideoPostRow)

Component

New CompositionPreviewPanel sub-component:

function CompositionPreviewPanel({
  previewUrl,
  cut,
  captions,
}: {
  previewUrl: string; // the composition-HTML proxy route response, scoped to `cut`
  cut: VideoCut; // reuse the existing "vertical" | "square" type
  captions: { x?: string | null; tiktok?: string | null };
}) { /* ... */ }

It renders inside VideoPostRow, between the cut-switcher/re-render row and the existing MP4 <video> block, only when a live previewUrl is available (composition authored but not yet rendered, or re-rendering) — once the MP4 exists it stays visible as a lighter-weight way to sanity-check captions against the composition without scrubbing the video.

Layout

A two-column grid at md: and up, stacked single column below it — the same collapse breakpoint already used for this row's own action buttons (flex-col-reverse gap-2 pt-1 sm:flex-row, video-post-queue.tsx:260), but md: here because the iframe needs more horizontal room than a button row:

<div className="grid grid-cols-1 gap-3 rounded-lg border p-3 md:grid-cols-2">
  {/* left: iframe */}
  {/* right: captions */}
</div>

rounded-lg border p-3 matches the existing VideoPostRow container's own rounded-lg border p-4 (one step down in padding, since this is a nested block) — no new radius or border-color token.

Left column: iframe

<div className="flex items-center justify-center overflow-hidden rounded-md bg-muted">
  <iframe
    src={previewUrl}
    title={`${cut} composition preview`}
    sandbox="allow-scripts"
    className={cut === "vertical" ? "aspect-[9/16] w-full max-w-[180px]" : "aspect-square w-full max-w-[240px]"}
  />
</div>

• sandbox="allow-scripts" only — no allow-same-origin, no allow-popups, no network access implied (the compositions are already built offline-only per motion/README.md's render constraints, so the sandboxed iframe cannot reach anything the composition doesn't already vendor).
• The composition's native canvas is 1080px wide (vertical: 1080×1920, square: 1080×1080, per motion/README.md); the iframe is displayed at a fixed max-width scaled thumbnail (180px vertical / 240px square) rather than 1:1, matching how the MP4 <video> below it is already constrained (mx-auto max-h-96 w-full, video-post-queue.tsx:189) — full-size inspection is not this panel's job, it is a fast sanity check.
• bg-muted fills any letterboxing while the iframe loads, mirroring the "missing cut" placeholder's border-dashed box use of the same muted surface (video-post-queue.tsx:195-197).
• Reuses the row's existing cut state (the same vertical/square toggle buttons drive both the iframe and the MP4 preview below it — no second switcher).

Right column: captions

Read-only display of the same captions the composition's captions.json proposes (per motion/README.md's captions.json schema) — this is a preview of what will be sent, not an edit surface (editing already happens in the existing textareas further down the card):

<div className="space-y-2 text-sm">
  <div>
    <p className="text-xs font-semibold uppercase tracking-wide text-muted-foreground">X</p>
    <p className="whitespace-pre-wrap">{captions.x ?? "—"}</p>
  </div>
  <div>
    <p className="text-xs font-semibold uppercase tracking-wide text-muted-foreground">TikTok</p>
    <p className="whitespace-pre-wrap">{captions.tiktok ?? "—"}</p>
  </div>
</div>

Typography matches the "Drafted CHANGELOG" label pattern already used in release-proposal-card.tsx:200-205 (text-xs font-semibold uppercase tracking-wide text-muted-foreground for the eyebrow label).

Narrow-viewport behavior

Below md: (768px) the grid collapses to a single column: iframe first, captions second, each taking the full row width, gap-3 between them (the grid-cols-1 default already declared above — no separate mobile-only class needed). The iframe keeps its own max-w-[180px]/max-w-[240px] cap and centers via the parent's flex items-center justify-center, so it never stretches edge-to-edge on a narrow card even though the grid cell does. This matches how the existing cut-switcher buttons and action row already reflow from a row to a stacked column on narrow viewports (flex-col-reverse gap-2 ... sm:flex-row).

---

Implementation checklist for the frontend developer

• Add videoEngineOnly prop to ProjectSelector; backend adds video_engine_enabled to ProjectSummary.
• RequestVideoDialog: add projectId state, the picker field (first in the form), include it in canSubmit and in the requestVideo mutation payload, reset it alongside the other fields.
• RerenderControl: derive state from local edit-dirty tracking + mutation status; four visual states per the table above.
• CompositionPreviewPanel: two-column grid, sandboxed iframe scaled by orientation, read-only caption display; only rendered when a previewUrl exists.
• No new Tailwind tokens, colors, or radii — every class above already exists in video-post-queue.tsx or release-proposal-card.tsx.