This commit is contained in:
2026-03-24 13:42:57 +00:00
parent d16a987949
commit 0e5e1669c2
98 changed files with 824 additions and 8449 deletions
+5 -1
View File
@@ -49,4 +49,8 @@ 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)
4. [`assets-workspace-execution-wave.md`](./assets-workspace-execution-wave.md)
5. [`mental-model-asset-mutations.md`](./mental-model-asset-mutations.md)
6. [`bank-composition-editor.md`](./bank-composition-editor.md)
7. [`pack-wizard-shell.md`](./pack-wizard-shell.md)
8. [`project-scoped-state-and-activity.md`](./project-scoped-state-and-activity.md)
@@ -0,0 +1,88 @@
# Assets Workspace Execution Wave
## Original Problem
The first `Assets` workspace wave solved many UI problems in small execution slices:
- workspace foundation;
- asset navigator;
- selected-asset details;
- activity, progress, and logs;
- staged mutations;
- event-driven refactor;
- package and subscription boundaries.
That historical sequence was useful while implementation was in flight, but it became a poor learning surface.
## Consolidated Decision
The stable Studio direction for `Assets` is:
1. the workspace is asset-first, not file-first;
2. the workspace is event-driven, not refresh-heavy;
3. composition, projection, and rendering are separated;
4. details sections update independently instead of forcing whole-panel rebuilds;
5. mutation review is preview-first;
6. the shell reflects operational lifecycle without taking over workspace-local reasoning.
## Final Model
### 1. Workspace Foundation
- `Assets` is a real workspace, not a placeholder;
- workspace state is explicit about loading, empty, error, and ready conditions;
- selection is stable by asset identity rather than by transient row position.
### 2. Navigator and Details Split
- the left side owns navigation and projection;
- the main area teaches the selected asset in a fixed didactic order;
- navigator updates and details updates must not require a workspace-wide redraw by default.
### 3. Event-Driven Ownership
- local UI change flows through typed workspace events;
- component-scoped subscriptions replace root-owned redraw logic;
- structural sync and local projection updates stay distinct.
### 4. Operational Surfaces
- activity belongs to the shell timeline;
- progress belongs both to the current workspace flow and the broader shell context;
- textual logs are supporting drill-down, not the main explanation surface.
### 5. Mutation Review
- preview is the default review surface for sensitive actions;
- blockers, warnings, and safe fixes remain semantically separate;
- modal confirmation is reserved for high-risk commit boundaries.
## Examples
### Example: Why the root should not own every redraw
If one asset row changes because its diagnostics changed, the correct response is a row-scoped update.
Rebuilding navigator, details, and unrelated controls teaches the wrong ownership model and makes the UI harder to reason about.
### Example: Why the shell still needs activity
Mutation review happens inside the workspace.
But lifecycle milestones such as `preview ready`, `action applied`, or `action failed` still matter at shell scope because they are part of the user's project timeline.
## Common Pitfalls and Anti-Patterns
- Treating `Assets` as a filesystem explorer with extra badges.
- Using `refresh()` as the default answer to local UI state changes.
- Letting details sections depend on a monolithic selected-asset redraw.
- Using logs as the primary explanation surface for mutations.
- Publishing shell activity without keeping workspace-local review visible.
## References
- Specs:
- [`../specs/1. Studio Shell and Workspace Layout Specification.md`](../specs/1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md)
- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
- Related learn:
- [`./mental-model-assets-workspace.md`](./mental-model-assets-workspace.md)
- [`./mental-model-asset-mutations.md`](./mental-model-asset-mutations.md)
- [`./mental-model-studio-events-and-components.md`](./mental-model-studio-events-and-components.md)
@@ -0,0 +1,126 @@
# Bank Composition Editor
## Original Problem
`Bank Composition` needed to become a real editor inside `Asset Details` without collapsing into any of these bad outcomes:
- direct binding to raw snapshot or manifest shapes;
- overgeneric UI components before the first section existed;
- family-specific rules hidden inside visual controls;
- direct Studio writes to `asset.json`;
- public bus chatter for every local section interaction.
## Consolidated Decision
The first-wave `Bank Composition` model is:
1. Studio owns a DTO projection boundary for the section;
2. the section shell lands early and follows the existing staged-edit rhythm;
3. dual-list and capacity-meter components stay intentionally dumb;
4. one section-scoped coordinator around `StudioFormSession<BankCompositionDraft>` owns orchestration;
5. public workspace-bus events stay minimal and notification-oriented;
6. `apply` goes through packer and rebinds from refreshed persisted state.
## Final Model
### 1. DTO Boundary
The section never consumes raw packer/runtime structures directly.
It works with Studio-owned DTOs for:
- `available` rows from current runtime/details state;
- `selected` rows from persisted composition state.
Only non-blocking files enter the `available` DTO projection.
### 2. Section Shell
`Bank Composition` is a real `Asset Details` section, not a hidden future placeholder.
The shell follows the existing staged-edit rhythm:
- `change`
- `apply`
- `reset`
- `cancel`
Outside edit mode, it teaches the current persisted state in read-only form.
### 3. Dumb Components
Two named components exist for this area:
- `StudioDualListView<T>`
- `StudioAssetCapacityMeter`
They are intentionally state-driven, not rule-driven.
Family-specific transfer, ordering, and capacity semantics do not live inside these components.
### 4. Section-Scoped Coordinator
The main orchestration lives in one section-scoped coordinator built around `StudioFormSession<BankCompositionDraft>`.
That coordinator owns:
- draft lifecycle;
- transfer and reorder effects;
- capacity state;
- blockers and hints;
- apply success and failure handling.
### 5. WorkspaceBus Boundary
The public bus surface stays intentionally small.
First-wave public notifications are about observable state transitions:
- draft changed;
- capacity changed;
- apply requested;
- apply succeeded;
- apply failed.
Local edit actions remain local to the section coordinator.
### 6. Persistence Boundary
Studio does not write `asset.json` directly for `Bank Composition`.
The write path is:
1. Studio submits ordered selected files to packer;
2. packer validates and persists through `asset.json.artifacts`;
3. packer refreshes the minimum runtime/details state;
4. Studio rebinds from refreshed persisted state.
If apply fails, the draft stays alive and the section remains in editing mode.
## Examples
### Example: Why the meter must stay dumb
Tile banks and sound banks may calculate capacity differently.
That difference belongs in family policies owned by the coordinator, not in `StudioAssetCapacityMeter`.
### Example: Why `apply` is not a public bus command
External observers may care that apply was requested or failed.
They do not need to own the local section command sequence for `moveUp`, `moveDown`, `reset`, or `cancel`.
## Common Pitfalls and Anti-Patterns
- Binding section UI directly to raw snapshot rows or raw manifest shape.
- Hiding bank-family rules inside `StudioDualListView<T>` or the capacity meter.
- Creating a second staged-edit session model parallel to `StudioFormSession`.
- Turning every local section action into a public workspace-bus event.
- Writing `asset.json` directly from Studio instead of routing through packer.
## References
- Specs:
- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
- Cross-domain:
- [`../../packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../../packer/specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
- Related learn:
- [`./assets-workspace-execution-wave.md`](./assets-workspace-execution-wave.md)
+87
View File
@@ -0,0 +1,87 @@
# Pack Wizard Shell
## Original Problem
The `Assets` workspace already had a reserved `Pack` action, but that did not answer the real product question:
How should Studio behave when the developer wants to pack the current build set?
The risk was building a visually plausible modal that quietly reimplemented packer semantics or hid the real operational phases.
## Consolidated Decision
The stable first-wave rule is:
`Pack` is a Studio-owned wizard shell over packer-owned operations.
The wizard is phase-based:
1. `Summary`
2. `Validation`
3. `Packing`
4. `Result`
Studio owns presentation and state binding.
Packer owns summary, validation, execution, progress, and result semantics.
## Final Model
### 1. Workspace-Level Entry Point
- `Pack` is a workspace action, not a selected-asset action;
- the user is operating on the current pack set, not on one asset in isolation.
### 2. Summary
- the wizard asks packer for the current build-set summary;
- Studio does not count navigator rows and pretend that is the build set;
- the canonical runtime artifact is explicitly `assets.pa`.
### 3. Validation
- validation runs only on `registered + included in build`;
- blocking diagnostics stop the flow before execution;
- warnings may be visible, but they do not become blockers unless packer classifies them that way.
### 4. Packing
- execution is operational and non-editable;
- progress comes from packer-owned progress state or events;
- the UI does not simulate progress with timers;
- the first wave is non-cancelable.
### 5. Result
- the primary summary shows final status, packed asset count, elapsed time, and `assets.pa`;
- companion artifacts are supporting detail, not the headline of the result screen;
- the UI must distinguish blocked, failed, and successful outcomes.
## Examples
### Example: Why validation is a separate phase
If the wizard jumps straight from summary into execution, the user loses the explicit gate that explains why packing is blocked.
Validation exists to make the gate understandable before byte emission begins.
### Example: Why Studio must not fake progress
A fake progress bar may look smoother, but it lies about operational ownership.
If the packer is the owner of execution semantics, the UI must reflect packer-owned progress honestly.
## Common Pitfalls and Anti-Patterns
- Treating pack summary as a local Studio recomputation.
- Using one opaque modal state instead of explicit operational phases.
- Letting unrelated assets influence wizard validation.
- Exposing fake cancel behavior that the packer does not actually support.
- Making companion artifacts dominate the main result summary.
## References
- Specs:
- [`../specs/4. Assets Workspace Specification.md`](../specs/4.%20Assets%20Workspace%20Specification.md)
- Cross-domain:
- [`../../packer/learn/pack-wizard-summary-validation-and-pack-execution.md`](../../packer/learn/pack-wizard-summary-validation-and-pack-execution.md)
- [`../../packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../../packer/specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
- Related learn:
- [`./assets-workspace-execution-wave.md`](./assets-workspace-execution-wave.md)
@@ -0,0 +1,57 @@
# Project-Scoped State and Activity
## Original Problem
Some Studio state is global by nature, but some state is clearly tied to one opened project.
If project-local state is stored as if it were application-global, the shell starts mixing unrelated histories and the project root stops being the obvious home of Studio-owned project data.
## Consolidated Decision
The stable direction is:
1. project-local Studio state lives under `.studio/` inside the project root;
2. shell activity is restored and persisted per project;
3. persisted activity history is bounded;
4. `.studio/` is the reserved root for future project-local Studio settings.
## Final Model
### 1. Storage Root
- each project owns `.studio/`;
- new-project scaffolding creates that directory;
- `.workspace/` is not the project-local Studio root for this model.
### 2. Activity Persistence
- shell activity is loaded when the project opens;
- new activity is appended to that project's local history;
- history is trimmed to the latest `500` entries.
### 3. Scope Rule
- project-local shell history belongs to the project;
- launcher-global concerns remain outside this storage path;
- future Studio project configuration can live under the same `.studio/` root.
## Examples
### Example: Why activity cannot stay application-global
If two projects have one shared persisted feed, the shell stops teaching the user what happened in the currently opened project.
That destroys causality instead of preserving it.
## Common Pitfalls and Anti-Patterns
- Treating project activity as if it were launcher-global state.
- Mixing unrelated projects into one persisted activity history.
- Leaving project-local Studio files in ad hoc roots instead of `.studio/`.
- Letting unbounded activity persistence grow without a hard cap.
## References
- Specs:
- [`../specs/1. Studio Shell and Workspace Layout Specification.md`](../specs/1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md)
- Related learn:
- [`./mental-model-studio-shell.md`](./mental-model-studio-shell.md)