# 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)