293 lines
10 KiB
Markdown
293 lines
10 KiB
Markdown
# 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:
|
|
|
|
- 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.
|