# 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.

## 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.

## 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.

## 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:
  - `asset_name`
  - 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.

### 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.
- 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.

### Summary

- `Summary` must always be present for a selected asset.
- `Summary` must show:
  - `asset_name`
  - 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.

## 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`.
- `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.

### 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`.
- 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;
- cross-workspace reuse beyond the `Assets` workspace;
- 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;
- and behaves as a didactic helper for the packer model.