prometeu-studio/docs/studio/specs/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
• 2. Studio UI Foundations Specification.md
• 3. Studio Components Module Specification.md

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

• ../../packer/specs/1. Domain and Artifact Boundary Specification.md
• ../../packer/specs/2. Workspace, Registry, and Asset Identity Specification.md
• ../../packer/specs/3. Asset Declaration and Virtual Asset Contract Specification.md
• ../../packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.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.