assets workspace agendas
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user