prometeu-studio/docs/specs/studio/4. Assets Workspace Specification.md

# Assets Workspace Specification

## Status

Active

## Applies To

- `prometeu-studio`
- the Studio `Assets` workspace
- packer-facing Studio service integration for asset browsing, inspection, diagnostics, and staged mutations

## Purpose

Define the normative Studio contract for the `Assets` workspace.

This specification stabilizes:

- the information architecture of the workspace,
- the navigation and selection model,
- the selected-asset details structure,
- the relationship between activity, progress, and logs,
- and the preview/confirm/apply flow for sensitive mutations.

## Authority and Precedence

This specification extends:

- [`1. Studio Shell and Workspace Layout Specification.md`](1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md)
- [`2. Studio UI Foundations Specification.md`](2.%20Studio%20UI%20Foundations%20Specification.md)
- [`3. Studio Components Module Specification.md`](3.%20Studio%20Components%20Module%20Specification.md)

For packer-facing semantics, this specification must align with:

- [`../../packer/specs/1. Domain and Artifact Boundary Specification.md`](../../packer/specs/1.%20Domain%20and%20Artifact%20Boundary%20Specification.md)
- [`../../packer/specs/2. Workspace, Registry, and Asset Identity Specification.md`](../../packer/specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
- [`../../packer/specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../../packer/specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
- [`../../packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../../packer/specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)

If this document conflicts with the global Studio shell specifications, the shell specifications control shell-wide behavior and this document controls workspace-local behavior.

## Normative Inputs

The `Assets` workspace is a Studio view over packer services.

The workspace must assume:

- registered and unregistered assets may coexist inside `assets/`;
- unregistered assets remain visible but excluded from builds;
- assets may aggregate many internal inputs;
- runtime-facing output contract data exists for each asset;
- diagnostics, activity, progress, and staged mutation responses are available from Studio-facing services;
- packer-facing operational freshness may surface states such as `healthy`, `stale`, `diverged`, `reconciling`, or `failed`.

Packer-backed operational events consumed by this workspace are expected to enter Studio through the container-owned typed event bus path rather than through workspace-local ad hoc bus creation.

## Workspace Model

The `Assets` workspace is:

- `asset-first`,
- `path-aware`,
- didactic toward the packer model,
- and explicitly not a raw filesystem explorer clone.

The workspace must help the user understand:

- what the asset registration and build status are;
- where the asset root lives;
- which internal inputs belong to that asset;
- what the asset declares toward the runtime-facing contract;
- which operations are safe, staged, blocked, or destructive;
- whether the current view reflects healthy, stale, diverged, or reconciling packer state.
- what the canonical symbolic asset address is when Studio surfaces compile-facing identity.

The `Assets` workspace is also the first concrete consumer of the Studio event-driven workspace framework.

That means:

- `Assets` must prove the canonical Studio workspace architecture in real use;
- reusable lifecycle and projection patterns extracted here should be consumable by future Studio workspaces;
- `Assets` must not rely on a monolithic workspace root that redraws most of the UI after local interactions.

## Baseline Layout

The baseline workspace layout is:

- a custom `Asset Tree` / `Asset Navigator` on the left;
- a selected-asset details area in the main panel;
- inline diagnostics and action surfaces attached to the selected asset;
- global `Activity` in the shell right-side utility area;
- logs in the lower workspace region.

Filesystem structure may be visible and actionable as supporting context, but it is not the primary identity model of the workspace.

## Component Ownership Rules

The `Assets` workspace must be implemented as a composition root plus lifecycle-managed child controls.

Rules:

- the workspace root should coordinate service calls, workspace state, and structural synchronization;
- the workspace root should not own the render and update path of every navigator row, details section, and form control directly;
- the navigator host, asset rows, selected-asset details host, and details-internal sections/forms should subscribe only to the events and state they consume;
- event-consuming controls must subscribe only while mounted in the UI tree;
- reusable framework primitives should be consumed where the Studio already provides them instead of duplicating local refresh-oriented mechanisms.

## Asset Navigator Rules

### Primary Navigation Unit

- The primary navigation unit is the asset, not the raw file.
- The navigator must not degrade into a generic file tree.
- Grouping may reflect path or parent-folder structure, but asset nodes remain the primary navigable and selectable unit.

### Visual Rules

- The left navigation surface must be a custom `Asset Tree` / `Asset Navigator`.
- Asset nodes must expose strong visual semantics through icons, badges, and state styling.
- Asset nodes must surface:
  - registration status,
  - build participation,
  - diagnostics presence,
  - preload intent,
  - and broad asset family or type where available.
- Path context may appear as secondary information.

### Filters and Search

- The baseline filters are:
  - `Registered`
  - `Unregistered`
  - `Diagnostics`
  - `Preload`
- The navigator must support textual search.
- Baseline search must cover at least:
  - canonical asset address
  - `asset_name` when still present as an editorial label
  - asset root path
  - path context

### Workspace Actions

- Workspace-scoped actions must appear above the main asset workspace split, not inside the navigator list region.
- Workspace-scoped actions must not be mixed into the selected-asset details surface.
- Workspace actions should remain visible without requiring a selected asset.
- Global asset-manager actions such as `Add Asset`, `Doctor`, and `Pack` belong to this workspace-level action area.

### Navigator Actions

- Navigator-local controls may include search and filters that are specifically about asset discovery and navigation.

### Selection Rules

- The baseline navigator is single-select.
- Registered asset selection must be preserved by `asset_id`.
- Unregistered selection must be preserved by asset root path until the asset becomes registered.
- If an asset changes state while preserving identity, selection must remain attached to it.
- If the selected asset is removed from the navigator, selection must clear explicitly.
- Selection must never silently drift to another asset due to refresh ordering.
- If the selected asset keeps the same `asset_id` but its canonical address changes after a move or rename, Studio must preserve selection and refresh the visible address.

### Local Rendering Rules

- The workspace must use event-directed local redraws for routine interactions.
- The navigator host must react to projection-level events rather than whole-workspace rerender requests.
- Asset row items should react to row-scoped patch and selection events when identity is preserved.
- Selecting an asset must update navigator selection styling and the selected-asset details surface without rebuilding the entire workspace shell.
- Search and filter changes must redraw the navigator projection only.
- Details-local interactions such as preview input selection, preview zoom, or runtime-contract edits must redraw the selected-asset details surface only.
- Structural operations such as asset creation, removal, relocation, or full workspace reload may rebuild both navigator and details projections.
- Workspace-scoped progress and logging updates must not force navigator or selected-asset details redraw unless the underlying projection actually changed.

### State Rules

- The navigator must define explicit `loading assets` state.
- The navigator must define explicit `no assets` state.
- The navigator must define explicit `no results` state.
- The navigator must define explicit `workspace error` state.
- The workspace must define explicit operational freshness states when packer runtime divergence is surfaced.
- Unregistered assets must appear in the same navigator flow as registered assets.
- Unregistered styling must communicate `present but not yet registered`, not `broken`.

### Inputs Expansion

- Internal inputs may appear only as optional expansion or inspection surfaces.
- Inputs must not replace asset nodes as the default navigation unit.

## Selected Asset Details Rules

The selected asset view must use this stable composition:

1. top row with `Summary` and `Actions` side by side
2. `Runtime Contract`
3. `Inputs / Preview`
4. `Diagnostics`

This composition is stable across asset families.

The selected-asset details area must follow component-local ownership.

Rules:

- the details host should react to details lifecycle events such as loading, ready, and error;
- details sections should update independently when only one section's projection changed;
- forms and preview-local controls should publish and consume narrow typed events rather than trigger full details rebuild by default.

### Summary

- `Summary` must always be present for a selected asset.
- `Summary` must show:
  - canonical asset address
  - `asset_name` when available as an editorial label
  - registration status
  - build participation
  - `asset_id` when available
  - family/type
  - asset root path

### Runtime Contract

- `Runtime Contract` must present runtime-facing asset output data in short, didactic form.
- `Runtime Contract` must surface:
  - `output.format`
  - `codec`
  - `preload`
- Runtime-facing output information must not require raw JSON inspection.

### Inputs / Preview

- `Inputs / Preview` must expose internal inputs as part of the selected asset.
- Inputs should be structured by role where that information is available.
- Preview should be available for previewable materials such as:
  - images
  - palettes
  - audio
  - text
  - similar lightweight input artifacts
- Preview of derived output may exist, but input preview has baseline priority.

### Diagnostics

- Diagnostics for the selected asset must appear inline in the selected asset view.
- Blockers, warnings, and hints must be distinguishable.
- Inline diagnostics must not be replaced by raw logs.

### Actions

- Actions must be explicit.
- Actions that target the selected asset must appear beside `Summary`, not in the navigator area.
- Safe and routine actions must be visually separated from sensitive mutations.
- Hidden or automatic repair behavior is not allowed in the selected-asset view.
- If packer surfaces stale/diverged/reconciling state, the selected-asset view may expose explicit refresh or reconcile-oriented actions, but it must not invent repair semantics locally.

## Action Rules

- Registered assets excluded from builds must expose an explicit `Include In Build` action.
- Primary actions for unregistered assets include `Register`.
- `Register` is a direct action in Studio UX. If registration is valid, clicking it must register immediately without an extra acknowledgement step.
- If registration is blocked, Studio may surface the blocking preview inline so the user can inspect why registration cannot proceed.
- Sensitive actions such as `Exclude From Build`, `Remove`, and `Relocate` must be visually separated from routine actions.
- Sensitive actions must not look interchangeable with routine actions.
- `Relocate` must collect an explicit user-chosen destination root before the staged preview is generated.
- Automatic relocation targets are not sufficient Studio UX for `Relocate`.

## Namespace Collision Rule

Studio must respect the symbolic asset namespace contract used by compile-time authoring surfaces.

Rules:

- Studio must not allow creation of a new asset root whose canonical address would collide with an existing terminal asset or namespace prefix.
- Studio must not allow a terminal asset root to coexist with descendant asset roots that would require the same canonical path to act as both terminal and namespace.
- If a move or rename would create such a collision, Studio must block the action and surface the conflict explicitly.
- `Exclude From Build` and `Remove` must confirm in a modal review surface rather than an inline staged panel.

## Activity, Progress, and Logs Rules

### Activity

- `Activity` belongs to the global right-side shell panel.
- `Activity` is the structured operational timeline of the Studio.
- Activity entries must be user-oriented rather than service-trace-oriented.
- Repetitive background events must be aggregated or summarized.
- Significant lifecycle milestones should remain visible in the feed.

### Progress

- Progress must be visible globally in the shell.
- Progress may also appear inline when the current asset or action clearly owns that progress.
- Progress tick events must update progress state rather than create feed spam.

### Logs

- Logs belong to the lower workspace region as detailed textual output.
- Logs are secondary drill-down, not the primary explanation surface.
- The user must not need raw logs to understand ordinary operational state.

### Failure Retention

- Recent actionable failures must remain visible until acknowledged.
- Failures tied to the selected asset should also surface inline in the selected asset view.
- Critical failures must not disappear merely because low-value events continue to arrive.

## Staged Mutation Rules

Sensitive asset mutations are `preview-first`.

The review surface depends on the mutation class.

Inline staged panels are allowed for non-destructive blocked or inspect-only flows.

Modal review and confirmation is required for `Exclude From Build`, `Remove`, and relocation commits.

Routine state patches such as `preload`, `Include In Build`, and `Exclude From Build` must patch the affected asset projection locally when identity is preserved. Full workspace refresh is reserved for operations that change workspace structure or identity resolution.

Operation orchestration must follow this rule:

- local patch when stable identity and local projection are preserved;
- explicit structural sync when collection shape, identity, or projection membership changes;
- no routine mutation path should fall back to whole-workspace refresh merely for implementation convenience.

### Mutations Requiring Preview

- `Exclude From Build`
- `Remove`
- relocational changes such as move or rename of asset roots
- batch operations

Navigator-level `Doctor` and `Pack`, plus asset-level `Include In Build` and successful `Register`, remain outside this sensitive mutation staging flow.

### Preview Content

- Preview must show affected assets.
- Relocation preview must show the planned target root chosen by the user.
- Preview must show proposed actions.
- Preview must distinguish registry impact from workspace impact.
- Preview must show blockers, warnings, and safe fixes as separate visual sections.
- Preview must show diff-style effects such as:
  - create
  - move
  - delete
  - registry update

### Apply Rules

- `Apply` must remain disabled while blockers exist.
- Batch operations must present an aggregate summary first.
- Batch operations may expose drill-down detail after the aggregate summary.
- Destructive or relocational actions must not bypass preview.

### Activity Integration

- `preview_ready` should surface in global `Activity`.
- `action_applied` should surface in global `Activity`.
- `action_failed` should surface in global `Activity`.
- reconcile or divergence state transitions should remain visible when they affect current workspace truth.
- The preview itself remains a workspace-local review surface.

## Non-Goals

This specification does not define:

- the exact JavaFX component tree or control class structure of the `Assets` workspace;
- final reusable component boundaries for all preview surfaces;
- future multi-select or bulk-edit UX beyond the currently defined staged batch summary rules.

## Exit Criteria

This specification is satisfied when the Studio `Assets` workspace:

- navigates by assets rather than raw files;
- preserves path awareness without collapsing into a file explorer;
- explains the selected asset through summary, contract, inputs, diagnostics, and actions;
- keeps activity, progress, and logs clearly separated;
- stages sensitive mutations through preview-first flows;
- proves the Studio event-driven workspace framework through lifecycle-managed local ownership;
- and behaves as a didactic helper for the packer model.