assets workspace agendas
This commit is contained in:
@@ -0,0 +1,292 @@
|
||||
# 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.
|
||||
@@ -53,6 +53,7 @@ The current Studio core corpus is:
|
||||
1. [`1. Studio Shell and Workspace Layout Specification.md`](./1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md)
|
||||
2. [`2. Studio UI Foundations Specification.md`](./2.%20Studio%20UI%20Foundations%20Specification.md)
|
||||
3. [`3. Studio Components Module Specification.md`](./3.%20Studio%20Components%20Module%20Specification.md)
|
||||
4. [`4. Assets Workspace Specification.md`](./4.%20Assets%20Workspace%20Specification.md)
|
||||
|
||||
## Reading Order
|
||||
|
||||
@@ -60,4 +61,5 @@ Recommended order:
|
||||
|
||||
1. shell and workspace layout;
|
||||
2. shared UI foundations;
|
||||
3. components module policy.
|
||||
3. components module policy;
|
||||
4. assets workspace behavior.
|
||||
|
||||
Reference in New Issue
Block a user