docs/content-studio-foundation.md

# Content Studio Foundation

## Scope and status

Content Studio Phase 1 adds a real, project-scoped editing foundation at
`/projects/[projectId]/studio`. It uses the authenticated Workspace Shell,
existing project provider, canonical project assets, centralized BFF client,
runtime OpenAPI discovery, TanStack Query, command registry, permissions, and
MediaRouter design system.

This phase does not add a backend editor document, rendering pipeline,
captions/effects authoring workflow, AI editing, publishing, analytics, or
collaboration. Nothing in the Studio fabricates assets, persistence, render
jobs, progress, or successful exports.

## Feature architecture

The feature boundary is `frontend/features/editor/`:

- `types/` defines the persisted editor document and temporary UI state types.
- `stores/` contains a per-project Zustand store factory and React provider.
- `selectors/` derives narrow UI views without subscribing components to the
  complete store.
- `utils/` contains deterministic timeline and source-time math.
- `api/` discovers exact OpenAPI contracts and routes supported calls through
  the centralized API client.
- `services/` separates editor-state and canonical project-asset adapters.
- `commands/` and `hooks/` integrate commands and keyboard shortcuts.
- `components/` contains the Studio workspace, media panel, preview, timeline,
  inspector, toolbar, and playback controls.
- `tests/` verifies math, state, capability, command, shortcut, UI, preview,
  asset, and architecture behavior.

The Studio route is nested below the existing authenticated project route. It
does not replace `/projects` or `/projects/[projectId]`.

## Domain model

`ProjectEditorState` is a versioned, typed document containing a project ID,
timeline, and render settings. The timeline uses one extensible track model for
`video`, `audio`, `caption`, and `overlay` tracks. Clips are a discriminated
union of media, audio, caption, and effect clips; core editor state does not use
`any[]` or `Record<string, any>`.

Every clip has an ID, owning track ID, timeline start, duration, label,
visibility, opacity, and safe primitive metadata. Source-backed media and audio
clips also carry the canonical asset ID, source start, and source duration.
Media clips include transform and volume; audio clips include volume and fade
values. Transitions and markers have typed extension points but no authoring UI
in this phase.

Incoming authoritative documents are validated at runtime before hydration.
Validation covers schema version, project identity, render settings, unique
tracks/clips, track ordering, clip discriminators, finite time/property values,
source timing, transitions, and markers.

## Timeline coordinate system

All timeline and source coordinates are integer milliseconds. Pixels are only
a viewport projection:

`pixels = milliseconds / 1000 * pixelsPerSecond`

Moving a clip changes its timeline `startMs`. Left trimming changes timeline
start, duration, source start, and source duration while enforcing source-in and
minimum-duration bounds. Right trimming changes duration/source-out and can
expand only to browser/backend-discovered source duration. Splitting creates
two clips with contiguous timeline and source ranges. The source asset is never
modified.

The current minimum clip duration is 100 milliseconds. Negative time,
non-finite values, duplicate IDs, mismatched track ownership, and invalid source
ranges are rejected by timeline validation.

## State ownership

TanStack Query remains authoritative for backend resources:

- project metadata and permissions;
- project assets;
- project jobs and activity;
- runtime OpenAPI discovery;
- future editor-state and render mutations when contracts exist.

A per-project Zustand store owns only client editing state:

- the in-memory working editor document;
- playhead, playback, rate, and duration;
- selection and project-asset preview selection;
- timeline zoom and scroll viewport;
- active tool and mobile editing mode;
- media metadata discovered by the browser;
- temporary pointer interactions;
- bounded undo/redo history and dirty state.

The store is created inside `EditorStoreProvider`; it is not a second global
project store. Project changes cause a new provider/store instance. Components
use narrow selectors and stable store actions.

## Undo, redo, and editing invariants

History records meaningful immutable timeline mutations: clip insertion,
removal, move, trim, split and properties; track addition, removal, update and
reorder. Pointer previews do not create history entries. A completed pointer
interaction creates at most one entry. Playback frames, seeking, hover, media
metadata discovery, selection, zoom, and temporary mobile UI modes are not
recorded.

History is bounded to 100 entries. Undo/redo recalculates timeline duration,
stops playback, reconciles selection when entities disappear, and compares the
result to the last hydrated/saved timeline for accurate dirty state. Locked
tracks are protected inside the store as well as in the UI.

## Timeline interaction

The timeline provides a time ruler, keyboard-seekable playhead, horizontally
scrollable multi-track canvas, track headers, clip selection, clip duration
visualization, viewport culling, zoom, fit-to-width, and accessible empty state.

Clip movement and edge trimming use controlled pointer capture, with keyboard
left/right movement in 100 millisecond steps. Track reordering and canonical
asset insertion support controlled drag/drop, while up/down track controls and
the Add to timeline button provide keyboard and touch alternatives. Dropping an
asset validates compatible track type and lock state before updating the local
editor session.

Drag payloads are never authorization evidence. Any future persistence or
render backend must independently validate workspace, project, asset ownership,
document contents, and permissions.

## Preview and playback

The preview uses real `<video>`, `<audio>`, and `<img>` elements with the
existing authenticated BFF media path:

`/api/backend/v1/media/{request_id}/{filename}`

No raw storage credential or provider secret is exposed. Browser
`loadedmetadata` supplies real media duration and dimensions when backend asset
metadata is absent. Video/audio insertion remains unavailable until a positive
real duration is known. Still-image insertion remains unavailable because no
authoritative default image duration exists.

Seeking converts timeline time to source time. While playing, animation-frame
synchronization converts the media element's source time back to the timeline
playhead. Playback stops at the selected clip boundary or when no playable clip
exists. Video transform and opacity plus track/clip volume state are applied to
the real preview element.

Phase 1 previews one active source-backed clip. It does not composite multiple
video/overlay tracks or mix multiple audio tracks; that requires the future
render/preview engine contract.

## Inspector

With no selection, the inspector shows real timeline properties. With a clip,
it exposes only implemented values: timeline start/duration, volume, opacity,
video transform, audio fades, caption text, and removal from the timeline.
Removal never deletes the canonical asset. Source-in/out values are visible but
read-only until richer source metadata/validation is available. Locked and
read-only project states disable mutation controls.

Effect parameters are not editable. The inspector describes their unavailable
capability instead of presenting a working-looking control.

## Persistence contract

`PERSISTENCE = UNAVAILABLE` in the current backend.

Runtime OpenAPI discovery only activates persistence when one exact
project-scoped path exists with GET and PUT or PATCH:

- `GET /v1/projects/{project_id}/editor-state`
- `PUT /v1/projects/{project_id}/editor-state` or
  `PATCH /v1/projects/{project_id}/editor-state`

The current project metadata endpoint is not used as an editor document store.
Its 16 KB limit and lack of editor schema versioning, revisions, and optimistic
concurrency do not provide a durable editing contract. The Studio therefore
labels the working document `Session only`; Save is disabled with the exact
capability reason. The session is intentionally not stored in `localStorage` as
an authoritative substitute.

A future backend persistence phase must provide:

- a typed, versioned editor document schema with timeline-sized limits;
- revision/ETag or equivalent optimistic concurrency semantics;
- workspace/project authorization for user and API-key authentication;
- database ownership/RLS isolation;
- validation of all asset references against project/workspace ownership;
- safe audit events and structured errors;
- GET plus idempotent PUT or revision-aware PATCH in runtime OpenAPI.

Optional local crash recovery may be added later, but it must remain explicitly
non-authoritative and must never replace the backend document.

## Render contract

`RENDER_CONTRACT = UNAVAILABLE` in the current backend.

Runtime discovery only activates Render when OpenAPI advertises:

- `POST /v1/projects/{project_id}/renders`

The Render control is disabled with a truthful reason today. No request is sent,
no progress is generated, and no success toast can occur while the contract is
absent.

A future render phase must accept a validated editor revision/reference and
render settings, then return a durable job identity using the existing job
infrastructure. The backend must validate project and asset ownership, execute
the FFmpeg/render pipeline, attach the output to the canonical project asset
system, and define progress, failure, cancellation, retry, and audit semantics.
The runtime OpenAPI contract must include typed request, job, and error schemas.

## Capabilities and permissions

The Studio route requires the real project API and `projects:read`. Timeline
mutations require the existing `projects:update` permission and an active
project. Save additionally requires the editor-state write contract. Render
requires the render contract plus `projects:update` and `jobs:create`.

The UI treats frontend permission/capability checks as presentation gates only.
The backend remains authoritative for project ID, workspace, asset ownership,
editor metadata, and render permission.

## Commands and keyboard shortcuts

Commands are registered dynamically through the shared command registry and
removed when the Studio unmounts. Unsupported commands are not registered.

- Open Content Studio: project read capability.
- Play/Pause (`Space`): an active playable clip.
- Undo (`Ctrl/Cmd+Z`): editable project and non-empty undo history.
- Redo (`Ctrl/Cmd+Shift+Z`): editable project and non-empty redo history.
- Split Clip (`S`): editable unlocked selection and valid playhead split.
- Delete Clip (`Delete`/`Backspace`): editable unlocked selection.
- Zoom In, Zoom Out, Fit Timeline: open Studio.

Shortcuts ignore input, textarea, select, and content-editable focus targets.
Browser/system shortcuts are otherwise left intact.

## Responsive and accessible design

Desktop uses a dense project-media, preview, inspector, and full-width timeline
workspace. Tablet prioritizes preview and timeline while moving the inspector
into a lower panel. Mobile exposes dedicated Preview, Timeline, and Inspector
modes with 44-pixel minimum touch targets instead of shrinking every desktop
panel simultaneously.

Timeline clips are focusable options with selected semantics and spoken
time-range labels. The ruler is a keyboard slider. Track controls, trim handles,
asset actions, toolbar actions, and mobile tabs have accessible names. Focus
uses the design-system focus ring, and the global reduced-motion rule applies.
Drag actions have keyboard/touch alternatives.

## Performance strategy

- The route is isolated below the project feature and does not load on Home or
  Projects.
- Components subscribe to narrow Zustand selectors rather than the complete
  store.
- Clip views are memoized and callbacks/store actions are stable.
- The timeline calculates the visible time range and culls off-screen clips
  with an overscan window.
- Browser media uses metadata preloading instead of eagerly downloading every
  project asset.
- TanStack Query owns deduplication and caching for project resources.
- Timeline data remains time-based, allowing later lane virtualization without
  changing the document schema.

Track virtualization is intentionally deferred because Phase 1 has no evidence
of track counts requiring it. Clip viewport culling is already in place.

## Error and empty states

The Studio reuses project loading, not-found, permission, API error, and retry
states. Project media has unavailable, loading, API error, empty, no-search-
results, and normal states. Preview handles no selection, missing/deleted asset,
unsupported format, loading, network/codec failure, and image failure without
crashing the editor. Invalid authoritative documents are rejected rather than
hydrated.

## Future extension points

The typed clip union, track types, transitions, markers, schema version,
render settings, API adapters, command registration, and project provider allow
future phases to add captions, transitions, effects, AI editing, audio
processing, templates, aspect-ratio presets, publishing, and collaboration
without replacing this boundary. Those features remain outside Phase 1.