assets workspace agendas

This commit is contained in:
2026-03-24 13:42:40 +00:00
parent fcfe732eac
commit 3c5f949910
20 changed files with 919 additions and 444 deletions
+2
View File
@@ -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)
@@ -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)
@@ -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.