48 lines
2.3 KiB
Markdown
48 lines
2.3 KiB
Markdown
---
|
|
id: LSN-0003
|
|
ticket: studio-docs-import
|
|
title: Asset mutations legacy lesson
|
|
created: 2026-03-26
|
|
tags:
|
|
- studio
|
|
- legacy-import
|
|
- asset-mutations
|
|
- preview-first
|
|
---
|
|
|
|
## Context
|
|
|
|
Legacy import from `docs/studio/learn/mental-model-asset-mutations.md`.
|
|
|
|
This lesson preserves the didactic rule for how Studio must present asset mutations in the `Assets` workspace, aligned with `docs/studio/specs/4. Assets Workspace Specification.md` and packer integration boundaries.
|
|
|
|
## Key Decisions
|
|
|
|
### Sensitive asset mutations must be preview-first
|
|
|
|
**What:** Studio should treat destructive or relocational asset mutations as preview-first workflows, keep registry impact and workspace impact distinct, and reserve modal confirmation for high-risk final commits rather than using modals as a substitute for review.
|
|
**Why:** Users lose trust quickly when the UI hides whether a mutation affects only registry state or also the physical workspace. Inline staged review keeps the user anchored in the selected asset and its consequences.
|
|
**Trade-offs:** Inline review takes more UI structure than a modal-only flow, but it produces a clearer and safer operational model for both single-asset and batch mutations.
|
|
|
|
## Patterns and Algorithms
|
|
|
|
- Show affected assets, scope of impact, creations/moves/deletions, blockers, warnings, and safe fixes before apply.
|
|
- Use an inline staged panel as the default review surface.
|
|
- Keep `blockers`, `warnings`, and `safe fixes` visually and semantically distinct.
|
|
- For batch operations, show an aggregate summary first and drill-down detail second.
|
|
- Reflect lifecycle milestones such as `preview ready`, `action applied`, and `action failed` at shell scope while keeping review inside the workspace.
|
|
|
|
## Pitfalls
|
|
|
|
- Destructive apply without preview.
|
|
- Using raw logs as the main explanation surface.
|
|
- Mixing safe fixes with deletes as if they were the same class of action.
|
|
- Showing technical diff data without user-facing interpretation.
|
|
- Forcing modal-only review for ordinary mutation flows.
|
|
|
|
## Takeaways
|
|
|
|
- Preview is the review; modal confirmation is only the final safety gate for high-risk commits.
|
|
- Registry impact and workspace impact must never blur in Studio mutation UX.
|
|
- Legacy source attribution: `docs/studio/learn/mental-model-asset-mutations.md`.
|