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:

• managed assets are the primary unit of identity and operation;
• orphan declarations may exist and must remain visible;
• 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 managed asset is;
• 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:
  • managed/orphan state,
  • 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:
  • Managed
  • Orphan
  • Diagnostics
  • Preload
• The navigator must support textual search.
• Baseline search must cover at least:
  • asset_name
  • asset root path
  • path context

Selection Rules

• The baseline navigator is single-select.
• Managed asset selection must be preserved by asset_id.
• Orphan selection must be preserved by asset root path until the asset becomes managed.
• 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.
• Orphan assets must appear in the same navigator flow as managed assets.
• Orphan styling must communicate declared, not managed, 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 fixed section order:

1. Summary
2. Runtime Contract
3. Inputs / Preview
4. Diagnostics
5. Actions

This section order is stable across asset families.

Summary

• Summary must always be present for a selected asset.
• Summary must show:
  • asset_name
  • managed/orphan state
  • 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.
• 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

• Primary actions for managed assets include Doctor and Build.
• Primary actions for orphan assets include Adopt.
• Register must remain available when explicit registration is the correct flow.
• Sensitive actions such as Forget, Remove, and quarantine-like actions must be visually separated from routine actions.
• Sensitive actions must not look interchangeable with routine actions.

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 default review surface is an inline staged panel inside the workspace.

Modal confirmation is reserved for high-risk final commits such as destructive delete or major relocation.

Mutations Requiring Preview

• Adopt
• Forget
• Remove
• Quarantine
• relocational changes such as move or rename of asset roots
• batch operations

Doctor and Build remain outside this sensitive mutation staging flow.

Preview Content

• Preview must show affected assets.
• 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.