# Unified media: project artifacts, shared models, deliberate presentation

Status: implementation contract, 2026-10-16. Follows the delivered dashboard
reconstruction (`6cfaebbd`). Track verification in `media-unification-TODO.md`.

## Ownership and discovery

Model weights and runtimes remain in the existing configured shared media store.
Changing projects or opening another session must not create a second model cache.
Generated images belong to `<project>/.omnius/images`, video to `.omnius/videos`,
and sound/music to `.omnius/audio`, matching the existing execution tools.

Browser requests capture the selected project when the operation starts. The
daemon resolves that identity through the project registry; a request cannot
substitute an arbitrary filesystem root. Generation, gallery, preview, download
and deletion carry the same captured identity. Switching projects while a job or
preview is pending must not attach its result to the new project's gallery.

Existing project artifacts are discoverable without import or duplication.
Metadata sidecars enrich records but cannot redirect file access outside the
project. File operations validate actual containment, supported extensions and
regular files, rejecting symlinks/traversal. Existing global gallery copies stay
available through an explicitly labeled legacy scope; they are not moved or
deleted automatically. Deletion confirmations state the actual selected artifact
and scope. Shared weight deletion remains a separate control.

The REST project registry is an access boundary: admin scope is required to
register, rename or unregister roots, and to write project preferences that
create discovery sentinels. Switching an existing registered project and listing
or scanning projects remain read operations; scanning does not register its
results. `registerIfMissing` on project switching requires admin scope. Local
trusted project discovery remains separate from these REST operations.

Media APIs require the captured `projectRoot`; they never fall back to the
daemon's current project. Project-root aliases resolve to the same physical
artifact identity. Optional known `session_id` values must belong to that
project. New requests carry a bounded `request_id` alongside the server's
`generation_id`, and all terminal receipts retain that identity. Preview and
deletion accept `If-Match` against the inspected artifact revision; video
deletion also removes its exact derived regular thumbnail, never a path supplied
by a sidecar. Legacy global gallery access requires `scope=legacy-global` and
does not accept a project attribution.

Configured shared-store root aliases resolve to one physical lease. Nested cache
and lease-file symlinks are rejected. The existing conservative store lease
serializes generation with weight/cache mutation because generation can download
or evict weights; it does not add a per-project model cache. Stop receipts remain
`stopping` until the owned invocation actually settles. Generation status records
are bounded in daemon memory and do not survive a daemon restart.

## Generation lifecycle

One invocation has one updating module in its parent turn. The module shows kind,
model, a single current phase and measured progress, then output controls. It
does not append every subprocess line to the transcript. Raw warnings and bounded
diagnostics live in an explicit disclosure. Download, runtime setup, loading,
inference steps and saving are distinct phases. Unknown progress stays unknown.
Heartbeat updates preserve the latest meaningful phase; they do not regress from
inference to a stale “downloading/loading” label. Subprocess records must survive
split lines and UTF-8 chunks.

Model browsing uses the existing nested module pattern. Selecting weights,
downloading files, deploying a runner and generating output are distinct actions;
their state labels must describe actual behavior. Existing broker and live
inference hardware gates still apply. No visual test should load a model.

## Media presentation

Image/video previews derive dimensions from the available content width and
aspect ratio. Sidebar dragging and terminal/browser resizing update that fit.
Opening media is an explicit clickable preview or Open action, with keyboard
access and a quiet hover treatment. File location is available in the module,
not repeatedly injected as log lines. The browser uses the same artifact identity
and exposes preview, download and scoped delete actions together.

Generated audio uses OpenTUI's native audio stream API with bounded PCM decoding
when the file format requires it, and measured waveform/progress visualization.
OpenTUI streaming has no pause/resume API; file transport must implement any such
control explicitly by disposing and restarting at a captured position. Decoder,
stream, timer and device cleanup belongs to the module lifecycle.

Video updates the native image frame while playing, at a bounded cadence. Only
active visible playback does decoding work; pause, navigation, removal and exit
must stop owned decoder processes/timers. Playback failures stay inside the media
module with a usable Open fallback. Tests exercise real fixture decoding and
native rendering without claiming audible output or actual model inference.

Reference: https://opentui.com/docs/application-apis/audio-streaming/ (checked
against the installed `@opentui/core` 0.6.6 audio declarations).
