Studio · Asset Preview Pipeline

Purpose#

Plan preview renditions with the real planner: the Rendition Planning Lane fits each rendition within its max-dimension box preserving the aspect ratio, and never upscales beyond the source size. It is a live admin console wired to /v1/admin/studio/asset-renditions, not an in-page simulation.

Entry points#

• Direct URL / bookmark — /studio/asset-preview-pipeline (signed-in + studio entitlement; admin scope required to plan)
• Sibling Studio routes — reached via the quick-action panel on file-media-ingestion, review-approval-workflows, commenting-annotation-system, and activity-change-feeds

Layout regions#

page.tsx mounts <ShellLayout active="studio"> and renders <StudioAssetPreviewPipelineWorkspace /> followed by a single panel of quick-action links.

• Shell: ShellLayout chrome with the Studio tab active
• Workspace heading: WorkspaceHeading renders the page <h1> "Studio Asset Preview Pipeline", followed by the data-asset-preview-summary paragraph
• Rendition Planning Lane: an <h2> data-ar-lane-heading ("Rendition Planning Lane") section with the load states and, when ready, the plan form and result table
• Quick-actions panel: 4 sibling quickAction Links — "Back to File and Media Ingestion workspace", "Back to Review and Approval Workflows workspace", "Back to Commenting and Annotation System workspace", and "Back to Activity and Change Feeds workspace". No self-link and no Route Map panel.

States#

• Loading — data-ar-loading ("Loading rendition planner…")
• Unauthorized — data-ar-unauthorized ("Access restricted.") on 401/403
• Error — data-ar-error on a failed catalog GET
• Ready / form — the data-ar-form plan form seeded with the default payload
• Result — data-ar-result with the data-ar-headline (data-ar-aspect-ratio, rendition + scaled counts), and the data-ar-renditions table of data-ar-rendition-row rows (data-rendition-name, data-scaled, data-ar-dimensions)
• Plan error — data-ar-plan-error for invalid JSON or a non-200 response
• Offline — catalog GET fails closed to the error panel; the plan POST surfaces the generic error when the network is unreachable
• Gated — admin scope denied → data-ar-unauthorized; the route itself is proxy-gated to signed-in + studio
• Standalone PWA — renders within the shell; no URL-bar dependency

Interactions#

• Asset renditions (JSON) — textarea data-ar-payload, aria-label="asset renditions json", seeded with the source dimensions and the requested rendition boxes
• Plan renditions — button data-ar-submit (type="submit"); POSTs the parsed payload to /v1/admin/studio/asset-renditions/plan, setting data-ar-result on a 200 with a valid result, or data-ar-plan-error otherwise
• Quick-action links — each quickAction Link navigates to its sibling Studio route (see Layout regions for the 4 targets)

Data & contracts#

• Reads: GET /v1/admin/studio/asset-renditions on mount — returns the catalog
• Writes: POST /v1/admin/studio/asset-renditions/plan — returns { aspectRatio, summary: { renditionCount, scaledCount }, renditions[{ name, maxDimension, targetWidth, targetHeight, scaled }] }
• Realtime: none
• Caching: client fetch with cache: 'no-store'; buildBffAuthHeaders() attaches the bearer token; SSR shell only
• Auth/role check: admin-scoped fail-closed — admin:* or admin:studio, 401/403 under the studio workspace gate

Cross-references#

• Parent: ../studio-overview.md
• Siblings: studio-generation-gallery.md, studio-generation-living-scene.md, ../authoring/studio-file-media-ingestion.md
• Component source: apps/oshun/web/src/components/studio/StudioAssetPreviewPipelineWorkspace.tsx behind /v1/admin/studio/asset-renditions

Open questions / known gaps#

• Confirm whether the page will gain a breadcrumb/Route Map panel like other Studio surfaces, or keep the flat quick-action panel
• Document the live asset source the planner should pull rendition boxes from once it moves off a pasted JSON payload