88 lines
3.2 KiB
Markdown
88 lines
3.2 KiB
Markdown
# 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)
|