365 lines
16 KiB
Markdown
365 lines
16 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:
|
|
|
|
- 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.
|
|
|
|
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:
|
|
- `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.
|
|
|
|
### 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:
|
|
- `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.
|
|
- 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`.
|
|
- `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.
|