clean up
This commit is contained in:
@@ -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)
|
||||
@@ -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)
|
||||
Reference in New Issue
Block a user