assets workspace agendas
This commit is contained in:
parent
fcfe732eac
commit
3c5f949910
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
@ -108,6 +108,6 @@ The preferred Studio documentation flow is:
|
||||
- `specs/` stores the normative Studio contract.
|
||||
- `learn/` stores teaching-oriented Studio knowledge.
|
||||
|
||||
The current Studio core has already been consolidated into [`specs/`](./specs/) and [`learn/`](./learn/). The `agendas/` and `decisions/` directories remain available for future cycles.
|
||||
The current Studio core and first `Assets` workspace wave have already been consolidated into [`specs/`](./specs/) and [`learn/`](./learn/). The `agendas/` and `decisions/` directories remain available for future cycles.
|
||||
|
||||
If implementation exposes a missing UI or interaction decision, stop and return to `agendas/` or `decisions/`.
|
||||
|
||||
@ -1,100 +0,0 @@
|
||||
# Asset Workspace Information Architecture Agenda
|
||||
|
||||
## Status
|
||||
|
||||
Closed
|
||||
|
||||
## Purpose
|
||||
|
||||
Define the baseline information architecture of the Assets workspace.
|
||||
|
||||
The goal is to decide which panels and data views the user needs in order to manage assets through Studio services rather than through ad hoc file inspection.
|
||||
|
||||
## Domain Owner
|
||||
|
||||
`docs/studio`
|
||||
|
||||
## Current Code Context
|
||||
|
||||
`WorkspaceId.ASSETS` is still backed by a placeholder workspace.
|
||||
|
||||
Meanwhile, the packer domain already defines:
|
||||
|
||||
- managed assets,
|
||||
- diagnostics,
|
||||
- preview/apply mutation flows,
|
||||
- an asset event lane,
|
||||
- structured service responses.
|
||||
|
||||
The Assets workspace must therefore be designed as a Studio view over those services, not as a file browser clone.
|
||||
|
||||
## Core Questions
|
||||
|
||||
1. Which panels are baseline for the Assets workspace?
|
||||
2. What should the primary unit of navigation be: asset list, tree, or diagnostic inbox?
|
||||
3. Which information should always be visible for the selected asset?
|
||||
4. How should diagnostics, preload, and managed/orphan state surface in the workspace?
|
||||
5. What belongs in the workspace body versus a global Studio activity region?
|
||||
|
||||
## Options
|
||||
|
||||
### Option A
|
||||
|
||||
List-first asset workspace with details panel and diagnostics section.
|
||||
|
||||
### Option B
|
||||
|
||||
File-tree-first asset workspace with asset details as a secondary mode.
|
||||
|
||||
### Option C
|
||||
|
||||
Dashboard-first asset workspace focused on diagnostics and actions.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
- Option A aligns best with the managed asset model already defined by the packer.
|
||||
- Option B is familiar, but risks collapsing the Studio into a glorified file explorer.
|
||||
- Option C is useful for operations, but weak as a day-to-day authoring workspace.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Prefer Option A.
|
||||
|
||||
Recommended baseline:
|
||||
|
||||
- a custom visual `Asset Tree` / `Asset Navigator` on the left,
|
||||
- asset details in the main panel,
|
||||
- diagnostics and action surfaces attached to the selected asset,
|
||||
- broader activity/progress outside the asset details body when possible.
|
||||
|
||||
The Assets workspace must remain asset-first, but it must not hide physical organization.
|
||||
|
||||
Baseline path and structure rules:
|
||||
|
||||
- the primary navigation unit is the managed asset, not the raw file;
|
||||
- the left navigation surface should not be a generic file tree; it should be an asset-aware tree that teaches the packer model;
|
||||
- asset root path must remain visible for the selected asset;
|
||||
- the asset list may be grouped by path or parent folder to preserve project structure awareness;
|
||||
- the selected asset view should include a location section for asset root and relocational actions;
|
||||
- the selected asset view should include an inputs/preview section that exposes internal files and folders as part of the asset;
|
||||
- filesystem structure is supporting context, not the primary identity model.
|
||||
|
||||
Baseline visual navigation rules:
|
||||
|
||||
- the Assets workspace should use a custom `Asset Tree` / `Asset Navigator` component rather than a plain `TreeView` clone;
|
||||
- asset nodes should carry strong visual semantics such as icons, badges, and state styling;
|
||||
- the navigator should clearly surface managed/orphan state, preload intent, diagnostics presence, and broad asset family where available;
|
||||
- grouping nodes may reflect path structure, but asset nodes remain the primary navigable unit;
|
||||
- optional expansion of an asset into internal inputs is allowed as supporting inspection, not as a replacement for asset-first navigation.
|
||||
|
||||
This exists so the Assets workspace teaches the packer model while still letting users understand and organize the project's directory layout.
|
||||
|
||||
## Expected Follow-up
|
||||
|
||||
- an information architecture decision,
|
||||
- a workspace spec,
|
||||
- a PR/plan for the first concrete `AssetsWorkspace`.
|
||||
|
||||
## Resolution
|
||||
|
||||
Closed by [`../decisions/004-asset-workspace-information-architecture-decision.md`](../decisions/004-asset-workspace-information-architecture-decision.md).
|
||||
@ -1,50 +0,0 @@
|
||||
# Asset List, Filters, and Selection Model Agenda
|
||||
|
||||
## Status
|
||||
|
||||
Open
|
||||
|
||||
## Purpose
|
||||
|
||||
Define how users navigate and select assets inside the Assets workspace.
|
||||
|
||||
## Domain Owner
|
||||
|
||||
`docs/studio`
|
||||
|
||||
## Current Code Context
|
||||
|
||||
The Studio shell already has workspace switching, but no concrete Assets workspace.
|
||||
|
||||
The packer model already distinguishes:
|
||||
|
||||
- managed assets,
|
||||
- orphan declarations,
|
||||
- diagnostics,
|
||||
- preload intent,
|
||||
- stable `asset_id` and logical `asset_name`.
|
||||
|
||||
The list model should make those distinctions visible without forcing users into raw registry inspection.
|
||||
|
||||
## Core Questions
|
||||
|
||||
1. Should the main asset view be flat, grouped, or tree-based?
|
||||
2. Which filters are baseline?
|
||||
3. How should the current selection be preserved across refreshes and background events?
|
||||
4. How should empty, loading, and error states appear?
|
||||
5. How much of the filesystem path should be exposed in the primary list?
|
||||
|
||||
## Recommendation
|
||||
|
||||
Baseline direction:
|
||||
|
||||
- registry-aware flat or grouped asset list,
|
||||
- lightweight filters for `managed`, `orphan`, `diagnostics`, and `preload`,
|
||||
- selection preserved by stable identity when possible,
|
||||
- path treated as supporting information, not primary identity.
|
||||
|
||||
## Expected Follow-up
|
||||
|
||||
- a decision on the asset list model,
|
||||
- a UI state spec for selection and filtering,
|
||||
- a plan for list rendering and refresh behavior.
|
||||
@ -1,47 +0,0 @@
|
||||
# Asset Details, Diagnostics, and Action Surface Agenda
|
||||
|
||||
## Status
|
||||
|
||||
Open
|
||||
|
||||
## Purpose
|
||||
|
||||
Define what the selected asset view shows and which actions are directly available there.
|
||||
|
||||
## Domain Owner
|
||||
|
||||
`docs/studio`
|
||||
|
||||
## Current Code Context
|
||||
|
||||
The packer service model already expects:
|
||||
|
||||
- structured diagnostics,
|
||||
- preview/apply mutation flows,
|
||||
- operations such as `register_asset`, `adopt_asset`, `forget_asset`, `remove_asset`, `doctor`, and `build`.
|
||||
|
||||
The selected asset view should therefore be designed around explicit state and explicit actions.
|
||||
|
||||
## Core Questions
|
||||
|
||||
1. What summary information is always visible for the selected asset?
|
||||
2. Which diagnostics belong inline versus in a separate panel?
|
||||
3. Which actions should be primary, secondary, or hidden behind confirmation?
|
||||
4. How should managed and orphan assets differ visually?
|
||||
5. How should runtime-facing information such as preload and output format appear?
|
||||
|
||||
## Recommendation
|
||||
|
||||
Baseline direction:
|
||||
|
||||
- a summary card for identity and state,
|
||||
- explicit diagnostics panel,
|
||||
- explicit action group,
|
||||
- clear differentiation between safe actions and sensitive mutations,
|
||||
- no hidden automatic repair behavior.
|
||||
|
||||
## Expected Follow-up
|
||||
|
||||
- a decision on asset details composition,
|
||||
- a spec for diagnostics and actions in the workspace,
|
||||
- a plan for Studio service integration in the asset details view.
|
||||
@ -1,81 +0,0 @@
|
||||
# Background Events, Progress, and Activity Feed Agenda
|
||||
|
||||
## Status
|
||||
|
||||
Open
|
||||
|
||||
## Purpose
|
||||
|
||||
Define how Studio surfaces background asset activity, progress, and logs coming from the packer event lane.
|
||||
|
||||
## Domain Owner
|
||||
|
||||
`docs/studio`
|
||||
|
||||
## Current Code Context
|
||||
|
||||
The packer already defines a Studio-facing asset event lane with events such as:
|
||||
|
||||
- `asset_discovered`
|
||||
- `asset_changed`
|
||||
- `diagnostics_updated`
|
||||
- `build_started`
|
||||
- `build_finished`
|
||||
- `cache_hit`
|
||||
- `cache_miss`
|
||||
- `preview_ready`
|
||||
- `action_applied`
|
||||
- `action_failed`
|
||||
- `progress_updated`
|
||||
|
||||
Current `BuilderWorkspace` already contains a logs area, which is a useful signal but not yet a coherent Studio-wide activity model.
|
||||
|
||||
## Core Questions
|
||||
|
||||
1. Should activity be global to the Studio shell or local to the Assets workspace?
|
||||
2. How should progress, logs, and state changes be distinguished?
|
||||
3. What should persist in history versus only appear transiently?
|
||||
4. How noisy should automatic background reporting be?
|
||||
5. How should action failures and blockers surface?
|
||||
|
||||
## Recommendation
|
||||
|
||||
Baseline direction:
|
||||
|
||||
- global activity region in the Studio shell,
|
||||
- structured event rendering rather than raw log dumping,
|
||||
- progress visible both inline and in the activity surface,
|
||||
- recent actionable failures retained until acknowledged,
|
||||
- normal background noise summarized rather than streamed endlessly,
|
||||
- use the right-side panel for structured activity and progress,
|
||||
- reserve the bottom region for logs and detailed textual output,
|
||||
- support a tabbed right-side panel so activity can coexist with other contextual surfaces such as diagnostics or inspector views.
|
||||
|
||||
## Distinction Between Activity and Logs
|
||||
|
||||
Baseline distinction:
|
||||
|
||||
- `activity` is the structured operational timeline of the Studio;
|
||||
- `logs` are detailed textual outputs from compiler, packer, and other services.
|
||||
|
||||
Examples of `activity`:
|
||||
|
||||
- project opened;
|
||||
- asset scan started;
|
||||
- diagnostics updated;
|
||||
- build started or finished;
|
||||
- preview ready;
|
||||
- action applied or failed.
|
||||
|
||||
Examples of `logs`:
|
||||
|
||||
- compiler output;
|
||||
- packer trace output;
|
||||
- stack traces;
|
||||
- detailed technical diagnostics and execution text.
|
||||
|
||||
## Expected Follow-up
|
||||
|
||||
- a decision on activity feed and progress UX,
|
||||
- a shell or integration spec,
|
||||
- a plan for event rendering and background updates.
|
||||
@ -1,47 +0,0 @@
|
||||
# Preview, Confirm, and Apply Mutation Flows Agenda
|
||||
|
||||
## Status
|
||||
|
||||
Open
|
||||
|
||||
## Purpose
|
||||
|
||||
Define how Studio stages sensitive asset mutations before applying them.
|
||||
|
||||
## Domain Owner
|
||||
|
||||
`docs/studio`
|
||||
|
||||
## Current Code Context
|
||||
|
||||
The packer model already requires:
|
||||
|
||||
- preview/apply for sensitive mutations,
|
||||
- explicit consent for destructive or relocational changes,
|
||||
- structured responses with blockers, proposed actions, and applied actions.
|
||||
|
||||
The Studio must turn that into clear interaction flows instead of accidental one-click mutations.
|
||||
|
||||
## Core Questions
|
||||
|
||||
1. Which actions require preview by default?
|
||||
2. What should a preview surface show before confirmation?
|
||||
3. How should blockers, warnings, and safe fixes be separated?
|
||||
4. When does the user see a modal confirmation versus an inline staged action panel?
|
||||
5. How should batch operations differ from single-asset mutations?
|
||||
|
||||
## Recommendation
|
||||
|
||||
Baseline direction:
|
||||
|
||||
- use preview-first flows for sensitive mutations,
|
||||
- show proposed actions and blockers explicitly,
|
||||
- keep safe fixes distinct from destructive actions,
|
||||
- favor inline staged review where possible,
|
||||
- reserve modal confirmation for high-risk commits such as delete or relocation.
|
||||
|
||||
## Expected Follow-up
|
||||
|
||||
- a mutation-flow decision,
|
||||
- a Studio interaction spec,
|
||||
- a plan for preview/apply service integration.
|
||||
@ -2,24 +2,9 @@
|
||||
|
||||
This directory contains active Studio discussion agendas.
|
||||
|
||||
## Active Agendas
|
||||
There are currently no active Studio agendas.
|
||||
|
||||
The initial Studio UI planning wave is:
|
||||
|
||||
1. [`01.2. Asset List, Filters, and Selection Model Agenda.md`](./01.2.%20Asset%20List,%20Filters,%20and%20Selection%20Model%20Agenda.md)
|
||||
2. [`01.3. Asset Details, Diagnostics, and Action Surface Agenda.md`](./01.3.%20Asset%20Details,%20Diagnostics,%20and%20Action%20Surface%20Agenda.md)
|
||||
3. [`01.4. Background Events, Progress, and Activity Feed Agenda.md`](./01.4.%20Background%20Events,%20Progress,%20and%20Activity%20Feed%20Agenda.md)
|
||||
4. [`01.5. Preview, Confirm, and Apply Mutation Flows Agenda.md`](./01.5.%20Preview,%20Confirm,%20and%20Apply%20Mutation%20Flows%20Agenda.md)
|
||||
|
||||
Recommended discussion order:
|
||||
|
||||
`01.2 -> 01.3 -> 01.4 -> 01.5`
|
||||
|
||||
The shell, UI foundations, and components admission baselines were already consolidated into [`../specs/`](../specs/) and [`../learn/`](../learn/).
|
||||
|
||||
The asset workspace information architecture baseline is already closed in [`../decisions/004-asset-workspace-information-architecture-decision.md`](../decisions/004-asset-workspace-information-architecture-decision.md).
|
||||
|
||||
The remaining order closes the detailed interaction model on top of that structure.
|
||||
The shell, UI foundations, components admission baselines, and the first asset workspace wave were already consolidated into [`../specs/`](../specs/) and [`../learn/`](../learn/).
|
||||
|
||||
## Purpose
|
||||
|
||||
|
||||
@ -1,96 +0,0 @@
|
||||
# Asset Workspace Information Architecture Decision
|
||||
|
||||
## Status
|
||||
|
||||
Accepted
|
||||
|
||||
## Date or Cycle
|
||||
|
||||
Studio asset workspace wave `01.1`
|
||||
|
||||
## Context
|
||||
|
||||
The Studio shell, UI foundations, and component rules are already defined in the Studio specifications.
|
||||
|
||||
The remaining open issue is how the `Assets` workspace should present packer-managed assets to the user.
|
||||
|
||||
The packer domain already establishes that:
|
||||
|
||||
- the managed unit is the asset, not the raw file;
|
||||
- each managed asset has a root and a declaration contract;
|
||||
- assets may aggregate many internal inputs;
|
||||
- diagnostics, preview/apply flows, and runtime-facing output contracts already exist at the domain level.
|
||||
|
||||
The Studio must therefore present the Assets workspace as a didactic view over the packer model, not as a generic filesystem explorer.
|
||||
|
||||
## Decision
|
||||
|
||||
The Studio `Assets` workspace is `asset-first`, `path-aware`, and taught through a custom visual `Asset Tree` / `Asset Navigator`.
|
||||
|
||||
The baseline workspace layout is:
|
||||
|
||||
- a custom visual `Asset Tree` / `Asset Navigator` on the left;
|
||||
- asset details in the main panel;
|
||||
- diagnostics and action surfaces attached to the selected asset;
|
||||
- broader Studio activity and progress outside the asset details body when possible.
|
||||
|
||||
The primary navigation unit is the managed asset, not the raw file.
|
||||
|
||||
Filesystem organization remains visible and usable as supporting context, but it is not the primary identity model of the workspace.
|
||||
|
||||
## Invariants and Constraints
|
||||
|
||||
- The left navigation surface must not be a generic file tree or a plain filesystem browser clone.
|
||||
- The navigator must be asset-aware and must teach the packer model.
|
||||
- Asset root path must remain visible for the selected asset.
|
||||
- The navigator may group assets by path or parent folder to preserve spatial awareness of the project.
|
||||
- Grouping nodes may reflect path structure, but asset nodes remain the primary navigable unit.
|
||||
- The selected asset view must include a location section for asset root and relocational actions.
|
||||
- The selected asset view must include an inputs/preview section that exposes internal files and folders as part of the asset.
|
||||
- Filesystem structure is supporting context, not the primary identity model.
|
||||
|
||||
## Visual Navigation Rules
|
||||
|
||||
- The Assets workspace must use a custom `Asset Tree` / `Asset Navigator` component.
|
||||
- Asset nodes must carry strong visual semantics such as icons, badges, and explicit state styling.
|
||||
- The navigator must clearly surface managed/orphan state, preload intent, diagnostics presence, and broad asset family where available.
|
||||
- Optional expansion of an asset into internal inputs is allowed as supporting inspection, not as a replacement for asset-first navigation.
|
||||
|
||||
## Didactic Requirement
|
||||
|
||||
The Assets workspace must act as a didactic helper for the packer.
|
||||
|
||||
This means 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.
|
||||
|
||||
The workspace must therefore explain the packer model through structure and presentation, not only through diagnostics text.
|
||||
|
||||
## Explicit Non-Decisions
|
||||
|
||||
This decision does not yet define:
|
||||
|
||||
- the exact filter and selection model of the asset list;
|
||||
- the exact action layout of the selected asset;
|
||||
- the detailed event, progress, and logging surfaces of the workspace;
|
||||
- the preview/confirm/apply flow for mutating operations.
|
||||
|
||||
Those belong to the follow-up decisions for `01.2` through `01.5`.
|
||||
|
||||
## Propagation Targets
|
||||
|
||||
- `docs/studio/agendas/01.2. Asset List, Filters, and Selection Model Agenda.md`
|
||||
- `docs/studio/agendas/01.3. Asset Details, Diagnostics, and Action Surface Agenda.md`
|
||||
- `docs/studio/specs/` for the eventual Asset Workspace specification
|
||||
- the first implementation plan for a concrete `AssetsWorkspace`
|
||||
|
||||
## Validation Notes or Examples
|
||||
|
||||
A good baseline outcome is:
|
||||
|
||||
- a user can browse the project through asset-aware groups;
|
||||
- a selected asset clearly shows identity, location, inputs, and previewable materials;
|
||||
- the workspace feels like a visual helper for the packer rather than a raw file explorer with extra buttons.
|
||||
@ -2,11 +2,9 @@
|
||||
|
||||
This directory contains Studio decision records.
|
||||
|
||||
## Active Decision Records
|
||||
There are currently no retained Studio decision records.
|
||||
|
||||
1. [`004-asset-workspace-information-architecture-decision.md`](./004-asset-workspace-information-architecture-decision.md)
|
||||
|
||||
The first Studio decision wave was already consolidated into:
|
||||
The first Studio decision wave and the first asset workspace wave were already consolidated into:
|
||||
|
||||
- normative specifications under [`../specs/`](../specs/)
|
||||
- didactic material under [`../learn/`](../learn/)
|
||||
|
||||
@ -48,3 +48,5 @@ Start here:
|
||||
|
||||
1. [`mental-model-studio-shell.md`](./mental-model-studio-shell.md)
|
||||
2. [`mental-model-studio-events-and-components.md`](./mental-model-studio-events-and-components.md)
|
||||
3. [`mental-model-assets-workspace.md`](./mental-model-assets-workspace.md)
|
||||
4. [`mental-model-asset-mutations.md`](./mental-model-asset-mutations.md)
|
||||
|
||||
128
docs/studio/learn/mental-model-asset-mutations.md
Normal file
128
docs/studio/learn/mental-model-asset-mutations.md
Normal file
@ -0,0 +1,128 @@
|
||||
# Mental Model: Asset Mutations
|
||||
|
||||
## The Problem
|
||||
|
||||
Asset mutations are easy to get wrong in a Studio UI.
|
||||
|
||||
Why?
|
||||
|
||||
Because some actions only update registry state, while others change the physical workspace.
|
||||
|
||||
If the Studio hides that difference, users lose trust quickly.
|
||||
|
||||
## The Rule
|
||||
|
||||
Sensitive asset mutations are `preview-first`.
|
||||
|
||||
That is the most important rule.
|
||||
|
||||
The Studio must not perform destructive or relocational asset changes as if they were harmless button clicks.
|
||||
|
||||
## What The User Must Understand Before Apply
|
||||
|
||||
Before applying a mutation, the user should be able to answer:
|
||||
|
||||
- Which assets are affected?
|
||||
- Is this touching only the registry, or also the workspace?
|
||||
- Will something be created, moved, or deleted?
|
||||
- Are there blockers?
|
||||
- Are there warnings?
|
||||
- Is this a safe fix or a risky mutation?
|
||||
|
||||
If the UI cannot answer those questions, the mutation flow is not ready.
|
||||
|
||||
## Why Inline Review Is The Baseline
|
||||
|
||||
The default review surface is an inline staged panel, not a modal.
|
||||
|
||||
That keeps the user anchored in the asset and its surrounding context.
|
||||
|
||||
It lets the user compare:
|
||||
|
||||
- the selected asset,
|
||||
- the diagnostics,
|
||||
- the proposed changes,
|
||||
- and the action consequences
|
||||
|
||||
without bouncing between unrelated windows.
|
||||
|
||||
## Why Modals Still Exist
|
||||
|
||||
Modals are still useful, but only for high-risk final commits.
|
||||
|
||||
Examples:
|
||||
|
||||
- destructive delete;
|
||||
- major relocation;
|
||||
- other strongly irreversible actions.
|
||||
|
||||
The mistake would be using modals as a substitute for review.
|
||||
|
||||
Preview is the review.
|
||||
|
||||
Modal confirmation is only the final safety gate when the risk is high enough.
|
||||
|
||||
## The Most Important Distinction
|
||||
|
||||
The Studio must distinguish:
|
||||
|
||||
- registry impact
|
||||
- workspace impact
|
||||
|
||||
This is one of the most important didactic duties of the asset workspace.
|
||||
|
||||
A user should never have to guess whether a button:
|
||||
|
||||
- merely forgets an asset from management,
|
||||
- or actually deletes or moves files.
|
||||
|
||||
## Blockers, Warnings, and Safe Fixes
|
||||
|
||||
These categories must stay visually and semantically separate.
|
||||
|
||||
They are not interchangeable kinds of “message”.
|
||||
|
||||
- `blockers` stop the apply path;
|
||||
- `warnings` tell the user the action is still meaningful but risky or noteworthy;
|
||||
- `safe fixes` are low-risk corrections and should not be grouped as if they were destructive operations.
|
||||
|
||||
If those three collapse into one list, users stop trusting the flow.
|
||||
|
||||
## Batch Operations
|
||||
|
||||
Batch operations are not just “single asset, repeated many times”.
|
||||
|
||||
They need:
|
||||
|
||||
- an aggregate summary first,
|
||||
- then drill-down detail.
|
||||
|
||||
Without that, the flow becomes unreadable and users either miss risk or abandon the tool.
|
||||
|
||||
## How Activity Fits In
|
||||
|
||||
The preview itself belongs to the workspace.
|
||||
|
||||
But the shell should still reflect lifecycle milestones such as:
|
||||
|
||||
- preview ready;
|
||||
- action applied;
|
||||
- action failed.
|
||||
|
||||
That way the workspace remains the place of review, while the shell keeps the broader operational timeline visible.
|
||||
|
||||
## Common Failure Modes
|
||||
|
||||
Avoid these:
|
||||
|
||||
- destructive apply without preview;
|
||||
- using raw logs as the main explanation surface;
|
||||
- mixing safe fixes with deletes;
|
||||
- showing technical diff data with no user-facing interpretation;
|
||||
- forcing the user into modal-only flows for ordinary review.
|
||||
|
||||
## Read With
|
||||
|
||||
1. [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
2. [`mental-model-assets-workspace.md`](./mental-model-assets-workspace.md)
|
||||
3. [`../../packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../../packer/specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
|
||||
119
docs/studio/learn/mental-model-assets-workspace.md
Normal file
119
docs/studio/learn/mental-model-assets-workspace.md
Normal file
@ -0,0 +1,119 @@
|
||||
# Mental Model: Assets Workspace
|
||||
|
||||
## Why This Workspace Exists
|
||||
|
||||
The `Assets` workspace is not a nicer file browser.
|
||||
|
||||
It exists to make the packer model understandable and usable from the Studio.
|
||||
|
||||
That means the workspace must help a contributor answer questions like:
|
||||
|
||||
- What is the managed asset here?
|
||||
- Where does it live?
|
||||
- Which files belong to it?
|
||||
- What does it produce toward the runtime?
|
||||
- Is it managed, orphaned, preload-marked, or diagnostically unhealthy?
|
||||
|
||||
If the workspace answered those questions only by showing folders and files, it would teach the wrong mental model.
|
||||
|
||||
## The Core Shift
|
||||
|
||||
The key shift is:
|
||||
|
||||
- not `file-first`
|
||||
- but `asset-first`
|
||||
|
||||
An asset may contain many files.
|
||||
|
||||
Those files still matter, but they matter as inputs of an asset, not as the primary unit of identity.
|
||||
|
||||
So the workspace is designed to feel like:
|
||||
|
||||
- a structured asset navigator,
|
||||
- plus a didactic explanation surface for the currently selected asset.
|
||||
|
||||
## Why It Is Still Path-Aware
|
||||
|
||||
`Asset-first` does not mean `filesystem-blind`.
|
||||
|
||||
People still organize projects by directories.
|
||||
|
||||
They still need to know:
|
||||
|
||||
- where the asset root lives;
|
||||
- which broader folder group it belongs to;
|
||||
- how to reason about the project layout.
|
||||
|
||||
That is why the workspace remains `path-aware`.
|
||||
|
||||
The important nuance is:
|
||||
|
||||
- path is supporting context
|
||||
- asset identity is primary
|
||||
|
||||
## What The Left Side Teaches
|
||||
|
||||
The left-side navigator is a custom `Asset Tree` / `Asset Navigator`.
|
||||
|
||||
It teaches the model visually:
|
||||
|
||||
- groups may reflect location or parent folders,
|
||||
- asset nodes are the real unit of navigation,
|
||||
- icons and badges tell the story quickly,
|
||||
- orphan and managed assets can coexist without becoming ambiguous.
|
||||
|
||||
This is better than a raw file tree because the user learns the packer model by looking at the navigation itself.
|
||||
|
||||
## What The Main Area Teaches
|
||||
|
||||
The selected asset view is intentionally structured in a fixed order:
|
||||
|
||||
1. `Summary`
|
||||
2. `Runtime Contract`
|
||||
3. `Inputs / Preview`
|
||||
4. `Diagnostics`
|
||||
5. `Actions`
|
||||
|
||||
That order matters.
|
||||
|
||||
It starts by explaining what the asset is, then what it produces, then what it contains, then what is wrong, and finally what the user can do.
|
||||
|
||||
That is a teaching sequence, not just a layout sequence.
|
||||
|
||||
## Why Preview Matters
|
||||
|
||||
Preview is not decorative.
|
||||
|
||||
Preview is part of how the workspace bridges the conceptual asset model with the real materials inside the project.
|
||||
|
||||
Examples:
|
||||
|
||||
- an image bank should let the user inspect images and palettes;
|
||||
- an audio asset should let the user inspect sound inputs;
|
||||
- text-like artifacts should be inspectable as text when that helps understanding.
|
||||
|
||||
This makes the workspace feel grounded in real project materials while still preserving an asset-first model.
|
||||
|
||||
## What To Avoid
|
||||
|
||||
Common mistakes:
|
||||
|
||||
- turning the workspace into a raw filesystem explorer with extra badges;
|
||||
- making path the true identity instead of the asset;
|
||||
- showing only diagnostics and forgetting the actual asset model;
|
||||
- treating orphan as if it meant broken;
|
||||
- hiding runtime-facing information behind technical dumps.
|
||||
|
||||
## Practical Read Order
|
||||
|
||||
Read these together:
|
||||
|
||||
1. [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
2. [`mental-model-asset-mutations.md`](./mental-model-asset-mutations.md)
|
||||
3. [`../../packer/learn/mental-model-packer.md`](../../packer/learn/mental-model-packer.md)
|
||||
|
||||
That path explains:
|
||||
|
||||
- what the packer believes,
|
||||
- how the Studio presents it,
|
||||
- and how the user should reason about asset operations.
|
||||
@ -0,0 +1,71 @@
|
||||
# PR-05a Assets Workspace Foundation and Service State
|
||||
|
||||
## Briefing
|
||||
|
||||
Implement the first executable slice of the `Assets` workspace based on:
|
||||
|
||||
- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
|
||||
This PR creates the workspace foundation, service-facing state model, and event wiring required by all later `Assets` workspace slices.
|
||||
|
||||
## Objective
|
||||
|
||||
Replace the current `WorkspaceId.ASSETS` placeholder with a concrete `AssetsWorkspace` foundation that can:
|
||||
|
||||
- boot inside the Studio shell,
|
||||
- request and refresh asset data from Studio-facing services,
|
||||
- maintain stable selection state,
|
||||
- surface loading/empty/error states,
|
||||
- and expose internal state in a way that later UI slices can reuse.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- existing Studio shell and event bus foundations
|
||||
- existing packer-facing Studio contracts and specifications
|
||||
|
||||
## Scope
|
||||
|
||||
- create a concrete `AssetsWorkspace`
|
||||
- define workspace-local view state models for:
|
||||
- navigator state
|
||||
- selected asset state
|
||||
- loading/error state
|
||||
- define service-facing DTO adapters needed by the workspace
|
||||
- define workspace event publications for asset refresh and selection updates
|
||||
- integrate the workspace into the existing shell/workspace switch flow
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no final asset navigator visuals yet
|
||||
- no final preview rendering yet
|
||||
- no final staged mutation UI yet
|
||||
- no production-grade packer backend implementation if stubs or adapters are still required
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Replace the placeholder assets workspace with a concrete class and root layout.
|
||||
2. Introduce workspace-local state objects for navigator, selection, and detail hydration.
|
||||
3. Introduce a Studio-facing service boundary for loading asset collections and selected-asset details.
|
||||
4. Wire the workspace into `StudioWorkspaceEventBus` for refresh and selection lifecycle.
|
||||
5. Define stable loading, empty, no-results, and error states in code.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- selecting `Assets` opens a real workspace rather than a placeholder
|
||||
- the workspace can request asset data through a Studio service boundary
|
||||
- loading, empty, and error states are visible and distinct
|
||||
- selection state is modelled explicitly and can be preserved by identity
|
||||
- the workspace has enough state structure to support the later navigator and details PRs without redesign
|
||||
|
||||
## Validation
|
||||
|
||||
- unit tests for workspace state transitions
|
||||
- unit tests for selection retention logic
|
||||
- UI smoke validation that the Assets workspace mounts cleanly in the shell
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `prometeu-studio` workspace classes
|
||||
- Studio event wiring
|
||||
- Studio-facing asset service abstractions
|
||||
- tests for workspace state and selection behavior
|
||||
@ -0,0 +1,72 @@
|
||||
# PR-05b Asset Navigator Search Filters and Selection
|
||||
|
||||
## Briefing
|
||||
|
||||
Implement the left-side `Asset Tree` / `Asset Navigator` for the `Assets` workspace.
|
||||
|
||||
This PR applies the navigator and selection rules from:
|
||||
|
||||
- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
|
||||
## Objective
|
||||
|
||||
Deliver the first concrete asset navigator with:
|
||||
|
||||
- asset-first grouped navigation
|
||||
- semantic filters
|
||||
- textual search
|
||||
- stable single selection
|
||||
- explicit loading/empty/no-results/error states
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-05a-assets-workspace-foundation-and-service-state.md`](./PR-05a-assets-workspace-foundation-and-service-state.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- implement the custom visual asset navigator control
|
||||
- render group nodes and asset nodes
|
||||
- implement baseline filters:
|
||||
- `Managed`
|
||||
- `Orphan`
|
||||
- `Diagnostics`
|
||||
- `Preload`
|
||||
- implement textual search over asset name and path context
|
||||
- preserve selection by `asset_id` or orphan root path as appropriate
|
||||
- allow optional expansion into asset inputs only as supporting inspection
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no final selected-asset details composition yet
|
||||
- no final mutation staging UI yet
|
||||
- no heavy sorting or multi-select support
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Implement the navigator control and node rendering model.
|
||||
2. Add the baseline filters and search composition logic.
|
||||
3. Add stable selection reconciliation during refresh.
|
||||
4. Add explicit navigator states for loading, empty, no-results, and workspace error.
|
||||
5. Add the visual markers for managed/orphan, diagnostics, preload, and broad asset family.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- the `Assets` workspace shows a real asset navigator on the left
|
||||
- assets are grouped by path-aware structure without degrading into a raw file tree
|
||||
- filters and search work together
|
||||
- selection remains stable across refresh when identity is preserved
|
||||
- orphan assets appear in the same navigator flow with clearly differentiated styling
|
||||
|
||||
## Validation
|
||||
|
||||
- unit tests for filter/search composition
|
||||
- unit tests for selection preservation rules
|
||||
- UI smoke validation for node rendering and navigator states
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `AssetsWorkspace`
|
||||
- custom navigator controls
|
||||
- navigator view models
|
||||
- selection reconciliation logic
|
||||
- tests for filters, search, and selection behavior
|
||||
@ -0,0 +1,80 @@
|
||||
# PR-05c Selected Asset Details Contract and Preview
|
||||
|
||||
## Briefing
|
||||
|
||||
Implement the selected-asset details surface in the required fixed order:
|
||||
|
||||
1. `Summary`
|
||||
2. `Runtime Contract`
|
||||
3. `Inputs / Preview`
|
||||
4. `Diagnostics`
|
||||
5. `Actions`
|
||||
|
||||
This PR materializes the didactic core of the `Assets` workspace.
|
||||
|
||||
## Objective
|
||||
|
||||
Deliver the first usable selected-asset details experience, including:
|
||||
|
||||
- summary identity/state rendering
|
||||
- runtime-facing contract rendering
|
||||
- inputs-by-role rendering
|
||||
- first previewable input surfaces
|
||||
- inline diagnostics
|
||||
- action groups with routine vs sensitive separation
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-05a-assets-workspace-foundation-and-service-state.md`](./PR-05a-assets-workspace-foundation-and-service-state.md)
|
||||
- [`./PR-05b-asset-navigator-search-filters-and-selection.md`](./PR-05b-asset-navigator-search-filters-and-selection.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- render the fixed details skeleton
|
||||
- render summary metadata and location
|
||||
- render runtime contract fields such as `output.format`, `codec`, and `preload`
|
||||
- render input groups and input selection
|
||||
- implement first preview surfaces for previewable inputs
|
||||
- render inline diagnostics by severity
|
||||
- render action groups for:
|
||||
- `Doctor`
|
||||
- `Build`
|
||||
- `Adopt`
|
||||
- `Register`
|
||||
- sensitive operations placeholders where needed
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no final staged preview/apply workflow yet
|
||||
- no final lower log integration yet
|
||||
- no exhaustive preview support for every asset family
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Build the selected-asset details layout in the mandated section order.
|
||||
2. Render summary and runtime contract from workspace state.
|
||||
3. Implement inputs-by-role rendering and input selection.
|
||||
4. Implement baseline preview handling for previewable types.
|
||||
5. Render inline diagnostics and action grouping.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- selecting an asset hydrates a full details view in the fixed section order
|
||||
- runtime-facing contract fields are visible without raw JSON inspection
|
||||
- previewable inputs can be inspected from the details area
|
||||
- diagnostics are visible inline and differentiated by severity
|
||||
- routine actions and sensitive actions are visibly separated
|
||||
|
||||
## Validation
|
||||
|
||||
- unit tests for selected-asset detail mapping
|
||||
- unit tests for action availability by asset state
|
||||
- UI smoke validation for previewable input rendering
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `AssetsWorkspace` details area
|
||||
- preview components
|
||||
- diagnostics rendering
|
||||
- action surface wiring
|
||||
- tests for selected-asset detail behavior
|
||||
@ -0,0 +1,63 @@
|
||||
# PR-05d Assets Activity Progress and Logs Integration
|
||||
|
||||
## Briefing
|
||||
|
||||
Integrate the `Assets` workspace with Studio activity, progress, and logs according to the assets workspace specification.
|
||||
|
||||
## Objective
|
||||
|
||||
Make the `Assets` workspace operationally legible by wiring:
|
||||
|
||||
- structured activity into the shell right-side panel
|
||||
- contextual progress into the workspace
|
||||
- detailed textual logs into the lower region
|
||||
- failure retention and acknowledgement surfaces where required
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-05a-assets-workspace-foundation-and-service-state.md`](./PR-05a-assets-workspace-foundation-and-service-state.md)
|
||||
- [`./PR-05c-selected-asset-details-contract-and-preview.md`](./PR-05c-selected-asset-details-contract-and-preview.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- map asset-service events into Studio activity entries
|
||||
- aggregate repetitive background events into user-facing summaries
|
||||
- wire `progress_updated` into progress surfaces without feed spam
|
||||
- expose lower-region textual logs for asset operations
|
||||
- retain recent actionable failures until acknowledgement
|
||||
- mirror selected-asset failures inline where applicable
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no generic all-workspace activity framework redesign beyond what Assets needs now
|
||||
- no final cross-workspace logs unification
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Define asset-workspace activity mapping rules.
|
||||
2. Wire workspace and global bus publications for asset activity.
|
||||
3. Implement feed aggregation for repetitive events.
|
||||
4. Implement inline progress and lower-region logs integration.
|
||||
5. Retain and surface actionable failures across shell and workspace surfaces.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- asset events appear in the global `Activity` feed as user-oriented entries
|
||||
- progress updates do not spam the feed
|
||||
- logs are visible in the lower region for technical drill-down
|
||||
- actionable failures remain visible until acknowledged
|
||||
- selected-asset failures also appear inline when relevant
|
||||
|
||||
## Validation
|
||||
|
||||
- unit tests for activity aggregation mapping
|
||||
- unit tests for failure retention logic
|
||||
- UI smoke validation for shell/workspace activity interplay
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- activity event adapters
|
||||
- progress surfaces
|
||||
- workspace log region integration
|
||||
- failure retention state
|
||||
- tests for activity mapping and failure behavior
|
||||
@ -0,0 +1,75 @@
|
||||
# PR-05e Assets Staged Mutations Preview and Apply
|
||||
|
||||
## Briefing
|
||||
|
||||
Implement the preview-first mutation flows for the `Assets` workspace.
|
||||
|
||||
This PR applies the staged mutation rules from:
|
||||
|
||||
- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
|
||||
|
||||
## Objective
|
||||
|
||||
Deliver inline staged mutation review for sensitive asset operations, including:
|
||||
|
||||
- preview generation
|
||||
- blockers, warnings, and safe-fix separation
|
||||
- registry vs workspace impact explanation
|
||||
- apply gating
|
||||
- activity integration for preview/apply lifecycle
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [`./PR-05a-assets-workspace-foundation-and-service-state.md`](./PR-05a-assets-workspace-foundation-and-service-state.md)
|
||||
- [`./PR-05c-selected-asset-details-contract-and-preview.md`](./PR-05c-selected-asset-details-contract-and-preview.md)
|
||||
- [`./PR-05d-assets-activity-progress-and-logs-integration.md`](./PR-05d-assets-activity-progress-and-logs-integration.md)
|
||||
|
||||
## Scope
|
||||
|
||||
- implement inline staged review panel inside the `Assets` workspace
|
||||
- support preview-first handling for:
|
||||
- `Adopt`
|
||||
- `Forget`
|
||||
- `Remove`
|
||||
- `Quarantine`
|
||||
- relocational mutations
|
||||
- batch mutations when available
|
||||
- render proposed actions, blockers, warnings, safe fixes, and diff-style effects
|
||||
- disable `Apply` while blockers exist
|
||||
- use modal confirmation only for high-risk final commits
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- no fully generic mutation framework for every Studio workspace
|
||||
- no speculative batch authoring flows that do not yet exist in services
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Define the staged review panel and its state model.
|
||||
2. Integrate preview requests and preview-ready responses from services.
|
||||
3. Render registry impact and workspace impact separately.
|
||||
4. Gate apply on blockers.
|
||||
5. Wire `preview_ready`, `action_applied`, and `action_failed` into activity.
|
||||
6. Add modal confirmation only where the final commit is high-risk.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- sensitive asset mutations do not execute directly from a single click
|
||||
- preview clearly shows what will change in registry and workspace
|
||||
- blockers prevent apply
|
||||
- safe fixes remain visually distinct from destructive actions
|
||||
- preview/apply lifecycle events surface correctly in workspace and activity
|
||||
|
||||
## Validation
|
||||
|
||||
- unit tests for preview state mapping and apply gating
|
||||
- unit tests for registry/workspace impact rendering rules
|
||||
- UI smoke validation for staged mutation flows
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- staged review panel
|
||||
- asset mutation action wiring
|
||||
- preview/apply state models
|
||||
- activity integration for mutation lifecycle
|
||||
- tests for preview and apply behavior
|
||||
@ -38,3 +38,12 @@ A Studio plan should usually include:
|
||||
|
||||
The current Studio execution queue is:
|
||||
|
||||
1. [`PR-05a-assets-workspace-foundation-and-service-state.md`](./PR-05a-assets-workspace-foundation-and-service-state.md)
|
||||
2. [`PR-05b-asset-navigator-search-filters-and-selection.md`](./PR-05b-asset-navigator-search-filters-and-selection.md)
|
||||
3. [`PR-05c-selected-asset-details-contract-and-preview.md`](./PR-05c-selected-asset-details-contract-and-preview.md)
|
||||
4. [`PR-05d-assets-activity-progress-and-logs-integration.md`](./PR-05d-assets-activity-progress-and-logs-integration.md)
|
||||
5. [`PR-05e-assets-staged-mutations-preview-and-apply.md`](./PR-05e-assets-staged-mutations-preview-and-apply.md)
|
||||
|
||||
Recommended execution order:
|
||||
|
||||
`PR-05a -> PR-05b -> PR-05c -> PR-05d -> PR-05e`
|
||||
|
||||
292
docs/studio/specs/4. Assets Workspace Specification.md
Normal file
292
docs/studio/specs/4. Assets Workspace Specification.md
Normal file
@ -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.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user