discussion framework migration

This commit is contained in:
2026-03-26 18:45:46 +00:00
parent e78b72f61a
commit 38d8c25bba
90 changed files with 1150 additions and 2585 deletions
@@ -0,0 +1,123 @@
# Studio Shell and Workspace Layout Specification
Status: Draft
Scope: Studio shell, project entry, and workspace frame
Purpose: Define the normative shell structure of the Studio UI.
## Authority and Precedence
This specification consolidates the accepted Studio shell decision into normative form.
## Normative Inputs
- the Studio application shell
- project entry or launcher flow
- shell-level workspace navigation
- shell-level utility and run surfaces
## Core Rules
1. The Studio must open through a project launcher or home surface before entering the main workspace shell.
2. The main shell must expose a top global menu region.
3. The main shell must expose a left fixed workspace selector.
4. The main shell must expose a center workspace host.
5. The main shell must expose a right global utility panel.
6. The main shell must expose an always-visible run surface in the top-right area.
7. Workspaces mounted in the shell must follow the Studio event-driven workspace framework.
8. The shell must preserve a clear path for reusable workspace framework primitives shared across workspaces.
## Project Entry
The Studio must not land directly into a workspace as its primary entry behavior.
Baseline project entry behavior is:
- show a lightweight launcher or home surface first;
- show existing or recent projects;
- expose `Open Project` and `Create Project` as first-class actions;
- enter the main workspace shell only after a concrete project is selected or created.
## Workspace Model
The left workspace selector remains fixed in the baseline Studio shell.
The baseline workspace set includes:
- Code Editor;
- Asset Management;
- Debugger/Profiler;
- Shipper, temporarily represented by the current `BuilderWorkspace`.
`BuilderWorkspace` is transitional and must not be treated as a long-term architectural reference for the final shipping surface.
## Workspace Architecture Model
The shell-level workspace host exists to mount independently authored workspaces under one Studio contract.
Baseline workspace architecture rules are:
- each workspace should have a composition root that mounts the workspace into the shell;
- a workspace composition root should coordinate workspace services, state orchestration, and structural sync, but it should not own every local render path directly;
- event-observing workspace controls must be lifecycle-managed;
- workspace-local updates should flow through the Studio event system rather than ad hoc imperative redraw chains;
- future workspaces should consume shared Studio workspace framework primitives where those primitives already cover the needed behavior.
The shell must not encourage a workspace model where every interaction falls back to whole-workspace refresh.
## Right Utility Panel
The right-side global utility surface is tab-based.
Baseline rules:
- the initial tab set contains only `Activity`;
- the panel must be extendable with additional tabs later;
- `Run` is not a tab.
The right utility panel exists for shell-level visibility and utility, not for general per-workspace log dumping.
## Logs and Operational Detail
Detailed execution output belongs to the active workspace that owns the operation.
Rules:
- the shell must not define a single mandatory global console as the baseline logging model;
- each workspace may expose its own logs, console, or detailed operational output;
- shell-level utility surfaces may summarize shared activity, but they do not replace workspace-owned detail.
## UI Remodeling Scope
The Studio UI may be remodeled substantially during this wave.
That flexibility is constrained by:
- theme support must remain preserved;
- i18n support must remain preserved;
- the resulting shell must keep a clear path for reusable Studio controls.
## Deferred Docking
A fully docked IDE shell is not baseline behavior.
Rules:
- docking is explicitly deferred;
- shell topology and workspace responsibilities must be proven first;
- future dockability may be revisited only after the baseline shell is stable in actual use.
## Non-Goals
- defining the full internal layout of every workspace
- defining the final future tab set of the right utility panel
- defining the detailed activity rendering model
- defining every reusable workspace primitive in this document
## Exit Criteria
This specification is complete enough when:
- project entry and shell regions are unambiguous;
- workspace and shell responsibilities are clearly separated;
- the shell-level expectations for workspace architecture are explicit;
- the baseline Studio frame is stable enough for implementation planning.
@@ -0,0 +1,191 @@
# Studio UI Foundations Specification
Status: Draft
Scope: Naming, event publication model, and Studio UI foundations
Purpose: Define the shared infrastructure rules that all Studio UI work must follow.
## Authority and Precedence
This specification consolidates the accepted Studio UI foundations decision into normative form.
## Normative Inputs
- Studio shell structures
- workspace UI structures
- Studio-owned services
- shell and workspace event publication needs
- reusable Studio control infrastructure
## Core Rules
1. Studio UI naming must be explicit by role.
2. The Studio must define its own typed event system.
3. The Studio event system must include one global bus and one bus per workspace.
4. Every event published on a workspace bus must also be published on the global bus automatically.
5. Studio UI must preserve theme and i18n compatibility by construction.
6. Lifecycle-managed event subscription is the canonical way Studio controls observe external state.
7. The Studio must provide a reusable workspace framework for event-driven workspace composition.
8. Studio workspaces must consume that framework rather than invent refresh-heavy workspace-local patterns.
## Naming by Role
Studio naming must follow role-oriented conventions.
Baseline naming guidance:
- `StudioShell*` for shell-level structures;
- `*Workspace` for workspaces;
- `*Panel` for composed regions or panels;
- `*View` for focused visual views;
- `*Item` or `*Row` for list and cell-like elements;
- `StudioEvent*` for event types;
- `*Service` for operational services;
- `*Control` for reusable low-level visual controls.
Names must communicate responsibility directly.
Vague naming that hides shell, panel, workspace, or control roles is non-conforming.
## Studio Event System
The Studio must not rely on stringly-typed event routing as its primary contract.
Baseline event rules:
- event publication is local to the process;
- event publication is strongly typed;
- event payloads are DTOs and should be immutable where practical;
- event publication and subscription management must be thread-safe;
- the baseline model should remain intentionally small;
- a large reactive framework is not baseline behavior.
Thread safety is required because background work such as asset recognition, scanning, diagnostics refresh, or other asynchronous Studio activity may publish events that eventually affect visible UI state.
## Global and Workspace Buses
The baseline event topology includes:
- one global `StudioEventBus`;
- one workspace-local event bus per workspace.
Propagation rules:
- every event published on a workspace bus is automatically republished on the global bus;
- propagation is workspace to global;
- global-to-workspace rebroadcast is not baseline behavior.
The global Studio bus is backed by a typed event bus reference owned by the Studio application container.
Container rules:
- the Studio `Container` owns the global typed event bus reference used by `StudioEventBus`;
- host-integrated services that need shared Studio operational visibility should receive that container-owned typed event bus reference during bootstrap instead of allocating disconnected local buses;
- the `Container` must be initialized during Studio boot before packer-backed integration services, workspaces, or adapters begin use.
This topology exists so callers do not need to duplicate publication decisions manually.
## Event Categories
The exact event catalog may evolve incrementally.
Illustrative baseline categories include:
- project lifecycle events;
- project loading lifecycle events;
- workspace selection events;
- run and build intent events;
- activity publication events;
- progress update events;
- diagnostics update events;
- asset selection events.
For project bootstrap and splash/loading integration, the Studio event catalog should reserve typed events for:
- project loading started;
- project loading progress;
- project loading completed;
- project loading failed.
Project loading progress events should carry at least:
- the project identity,
- a typed loading phase,
- a user-facing status message,
- and either determinate progress or an explicit indeterminate marker.
## Theme and i18n Compatibility
Shared Studio UI foundations must preserve:
- CSS-based theming;
- locale-safe user-facing text behavior;
- safe runtime locale updates where text changes dynamically;
- no hardcoded user-facing text in reusable Studio controls.
Theme and i18n compatibility are admission requirements for shared UI infrastructure.
## Foundation Boundary
Shared Studio foundations include:
- shell-level UI conventions;
- event publication and observation infrastructure;
- reusable workspace framework primitives;
- reusable Studio control conventions.
## Subscription Lifecycle
Reusable Studio controls must have an explicit subscription lifecycle when they observe events or external state.
Baseline rule:
- Studio controls that need event observation should expose subscribe and unsubscribe lifecycle hooks that can be overridden when needed.
- Studio controls should also expose attach and detach lifecycle hooks for integration with the UI tree.
- `onAttached()` should trigger subscription setup.
- `onDetached()` should trigger subscription teardown.
This exists to make event wiring visible, testable, and safe under UI lifecycle changes.
The exact base class or interface shape is an implementation concern, but the lifecycle itself is normative.
## Canonical Workspace Framework
The Studio workspace model is not just a collection of unrelated screens.
Baseline workspace-framework rules are:
- a workspace should be built as a composition root plus lifecycle-managed child controls;
- child controls should subscribe only to the workspace events or external state they actually consume;
- local UI changes should be propagated through typed events and targeted patches where identity is preserved;
- structural synchronization should be explicit and separate from local patch propagation;
- whole-workspace refresh is a structural recovery path, not the default routine interaction path.
The baseline reusable workspace framework should cover at least:
- composition-root conventions;
- lifecycle-managed event-subscriber controls;
- projection-host patterns for list/tree/detail surfaces;
- local-patch versus structural-sync orchestration rules.
The first concrete proving ground for this framework may be a single workspace, but the resulting framework is normative for future Studio workspace implementation.
Shared Studio foundations do not include:
- domain-specific workspace business logic;
- speculative control catalogs;
- unrelated non-visual infrastructure that does not directly serve Studio UI.
## Non-Goals
- defining the full event catalog in advance
- defining every future workspace interaction
- defining the first concrete control implementation wave in detail
- allowing each workspace to define its own incompatible event/lifecycle model
## Exit Criteria
This specification is complete enough when:
- naming rules are stable enough to guide new Studio code;
- the event topology is explicit;
- the lifecycle and workspace-framework rules are explicit;
- theme and i18n constraints are unambiguous for shared Studio UI work.
@@ -0,0 +1,169 @@
# Studio Components Module Specification
Status: Draft
Scope: `prometeu-studio-components` role, admission policy, and JavaFX wrapping boundary
Purpose: Define the authoritative visual control layer for the Studio.
## Authority and Precedence
This specification consolidates the accepted Studio components module decision into normative form.
## Normative Inputs
- `prometeu-studio-components`
- Studio shell and workspace UI needs
- JavaFX controls actively used by the Studio
## Core Rules
1. `prometeu-studio-components` is the official visual control module for Studio UI.
2. Studio UI should normally consume visual controls from `prometeu-studio-components`, not directly from raw JavaFX.
3. A control enters the module when it is needed by the current Studio UI wave.
4. Controls in the module wrap and shape the JavaFX controls the Studio actively uses, but do not clone the full JavaFX API.
5. Every admitted control must preserve theme and i18n compatibility.
6. Reusable event-driven workspace controls should be admitted when they are part of the active Studio workspace framework.
## Module Role
`prometeu-studio-components` is:
- the authoritative Studio control layer;
- the home of the Studio visual dialect;
- the place where Studio-facing controls are shaped for Studio use;
- the preferred home for reusable lifecycle-aware workspace controls when those controls are part of the visible Studio UI dialect.
`prometeu-studio-components` is not:
- a speculative generic framework;
- a full reimplementation of JavaFX;
- a dumping ground for unrelated non-visual infrastructure.
## Admission Policy
A control is admissible when it is needed by the current Studio UI work.
Rules:
- immediate current Studio use is sufficient justification;
- a second use is not required when the control is clearly part of the shell or the current workspace surface;
- no control should be added without an immediate Studio consumer.
- a control needed first by one workspace may still be admitted when it is clearly intended as a reusable Studio workspace primitive.
## Studio Usage Rule
The baseline Studio UI should not rely on raw JavaFX controls as its normal visual surface.
Rules:
- a visual control used by Studio should normally come from `prometeu-studio-components`;
- extremely trivial local composition may stay in `prometeu-studio`;
- local exceptions must remain exceptional rather than becoming the default path.
## Wrapping Boundary
Controls in `prometeu-studio-components` must wrap the JavaFX controls the Studio actively uses.
Rules:
- the Studio-layer control should expose the Studio-facing API actually needed;
- exhaustive mirroring of upstream JavaFX APIs is not required;
- the goal is consistency and clarity, not a perfect one-to-one mirror of every JavaFX type.
## Control Lifecycle Hooks
Studio controls may need to observe event buses or other external state.
Rules:
- the control layer must provide explicit subscribe and unsubscribe lifecycle methods that can be overridden when needed;
- the control layer should also provide `onAttached()` and `onDetached()` lifecycle hooks;
- `onAttached()` should call `subscribe()`;
- `onDetached()` should call `unsubscribe()`;
- controls that attach subscriptions must also define how those subscriptions are released;
- event-driven controls must not hide subscription lifecycle completely inside ad hoc local wiring.
These hooks exist so event-driven controls remain predictable and safe to embed in shell and workspace UI.
## Reusable Workspace Primitives
Some reusable controls are not shell-only and are not domain-specific either.
They may still belong in `prometeu-studio-components` when they are part of the visible Studio workspace framework.
Illustrative admissible examples include:
- projection hosts for list/tree/detail surfaces;
- lifecycle-managed row or item controls;
- reusable section or inspector surfaces;
- visible controls that encode local-patch versus structural-sync interaction patterns.
What does not belong here:
- workspace-specific orchestration logic;
- domain-specific service calls;
- hidden coordination code with no visible control responsibility.
## Typical Control Scope
Typical controls that belong in the module include:
- shell controls;
- action controls and buttons;
- tab systems;
- tree and list controls;
- inspector and panel surfaces;
- activity and feedback surfaces;
- badges, headers, and related Studio primitives.
What stays outside the module:
- workspace-specific composition logic;
- non-visual domain behavior;
- speculative controls with no immediate Studio consumer.
## Theme and i18n
Every admitted control must support:
- CSS-based theming;
- safe locale-aware text behavior when text is exposed;
- no hardcoded user-facing text;
- explicit visual states where state matters.
## Organization Guidance
The module should be organized by Studio role rather than vague technical buckets.
Illustrative areas include:
- shell;
- actions;
- navigation;
- feedback;
- inspection;
- trees.
## Anti-Bloat Rule
The module must remain:
- intentional;
- Studio-driven;
- small enough to reason about;
- broad enough to prevent UI entropy in the application.
## Non-Goals
- defining the first concrete component set in full detail
- defining final package layout exhaustively
- mirroring the entire JavaFX control hierarchy
- storing domain-specific workspace orchestration code in the components module
## Exit Criteria
This specification is complete enough when:
- the module role is unambiguous;
- admission rules are stable enough to guide implementation;
- reusable workspace-control admission is clear enough to prevent local reimplementation drift;
- the JavaFX wrapping boundary is clear enough to prevent drift.
@@ -0,0 +1,364 @@
# Assets Workspace Specification
## Status
Active
## Applies To
- `prometeu-studio`
- the Studio `Assets` workspace
- packer-facing Studio service integration for asset browsing, inspection, diagnostics, and staged mutations
## Purpose
Define the normative Studio contract for the `Assets` workspace.
This specification stabilizes:
- the information architecture of the workspace,
- the navigation and selection model,
- the selected-asset details structure,
- the relationship between activity, progress, and logs,
- and the preview/confirm/apply flow for sensitive mutations.
## Authority and Precedence
This specification extends:
- [`1. Studio Shell and Workspace Layout Specification.md`](1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md)
- [`2. Studio UI Foundations Specification.md`](2.%20Studio%20UI%20Foundations%20Specification.md)
- [`3. Studio Components Module Specification.md`](3.%20Studio%20Components%20Module%20Specification.md)
For packer-facing semantics, this specification must align with:
- [`../../packer/specs/1. Domain and Artifact Boundary Specification.md`](../../packer/specs/1.%20Domain%20and%20Artifact%20Boundary%20Specification.md)
- [`../../packer/specs/2. Workspace, Registry, and Asset Identity Specification.md`](../../packer/specs/2.%20Workspace,%20Registry,%20and%20Asset%20Identity%20Specification.md)
- [`../../packer/specs/3. Asset Declaration and Virtual Asset Contract Specification.md`](../../packer/specs/3.%20Asset%20Declaration%20and%20Virtual%20Asset%20Contract%20Specification.md)
- [`../../packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../../packer/specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.md)
If this document conflicts with the global Studio shell specifications, the shell specifications control shell-wide behavior and this document controls workspace-local behavior.
## Normative Inputs
The `Assets` workspace is a Studio view over packer services.
The workspace must assume:
- registered and unregistered assets may coexist inside `assets/`;
- unregistered assets remain visible but excluded from builds;
- assets may aggregate many internal inputs;
- runtime-facing output contract data exists for each asset;
- diagnostics, activity, progress, and staged mutation responses are available from Studio-facing services;
- packer-facing operational freshness may surface states such as `healthy`, `stale`, `diverged`, `reconciling`, or `failed`.
Packer-backed operational events consumed by this workspace are expected to enter Studio through the container-owned typed event bus path rather than through workspace-local ad hoc bus creation.
## Workspace Model
The `Assets` workspace is:
- `asset-first`,
- `path-aware`,
- didactic toward the packer model,
- and explicitly not a raw filesystem explorer clone.
The workspace must help the user understand:
- what the asset registration and build status are;
- where the asset root lives;
- which internal inputs belong to that asset;
- what the asset declares toward the runtime-facing contract;
- which operations are safe, staged, blocked, or destructive;
- whether the current view reflects healthy, stale, diverged, or reconciling packer state.
The `Assets` workspace is also the first concrete consumer of the Studio event-driven workspace framework.
That means:
- `Assets` must prove the canonical Studio workspace architecture in real use;
- reusable lifecycle and projection patterns extracted here should be consumable by future Studio workspaces;
- `Assets` must not rely on a monolithic workspace root that redraws most of the UI after local interactions.
## Baseline Layout
The baseline workspace layout is:
- a custom `Asset Tree` / `Asset Navigator` on the left;
- a selected-asset details area in the main panel;
- inline diagnostics and action surfaces attached to the selected asset;
- global `Activity` in the shell right-side utility area;
- logs in the lower workspace region.
Filesystem structure may be visible and actionable as supporting context, but it is not the primary identity model of the workspace.
## Component Ownership Rules
The `Assets` workspace must be implemented as a composition root plus lifecycle-managed child controls.
Rules:
- the workspace root should coordinate service calls, workspace state, and structural synchronization;
- the workspace root should not own the render and update path of every navigator row, details section, and form control directly;
- the navigator host, asset rows, selected-asset details host, and details-internal sections/forms should subscribe only to the events and state they consume;
- event-consuming controls must subscribe only while mounted in the UI tree;
- reusable framework primitives should be consumed where the Studio already provides them instead of duplicating local refresh-oriented mechanisms.
## Asset Navigator Rules
### Primary Navigation Unit
- The primary navigation unit is the asset, not the raw file.
- The navigator must not degrade into a generic file tree.
- Grouping may reflect path or parent-folder structure, but asset nodes remain the primary navigable and selectable unit.
### Visual Rules
- The left navigation surface must be a custom `Asset Tree` / `Asset Navigator`.
- Asset nodes must expose strong visual semantics through icons, badges, and state styling.
- Asset nodes must surface:
- registration status,
- build participation,
- diagnostics presence,
- preload intent,
- and broad asset family or type where available.
- Path context may appear as secondary information.
### Filters and Search
- The baseline filters are:
- `Registered`
- `Unregistered`
- `Diagnostics`
- `Preload`
- The navigator must support textual search.
- Baseline search must cover at least:
- `asset_name`
- asset root path
- path context
### Workspace Actions
- Workspace-scoped actions must appear above the main asset workspace split, not inside the navigator list region.
- Workspace-scoped actions must not be mixed into the selected-asset details surface.
- Workspace actions should remain visible without requiring a selected asset.
- Global asset-manager actions such as `Add Asset`, `Doctor`, and `Pack` belong to this workspace-level action area.
### Navigator Actions
- Navigator-local controls may include search and filters that are specifically about asset discovery and navigation.
### Selection Rules
- The baseline navigator is single-select.
- Registered asset selection must be preserved by `asset_id`.
- Unregistered selection must be preserved by asset root path until the asset becomes registered.
- If an asset changes state while preserving identity, selection must remain attached to it.
- If the selected asset is removed from the navigator, selection must clear explicitly.
- Selection must never silently drift to another asset due to refresh ordering.
### Local Rendering Rules
- The workspace must use event-directed local redraws for routine interactions.
- The navigator host must react to projection-level events rather than whole-workspace rerender requests.
- Asset row items should react to row-scoped patch and selection events when identity is preserved.
- Selecting an asset must update navigator selection styling and the selected-asset details surface without rebuilding the entire workspace shell.
- Search and filter changes must redraw the navigator projection only.
- Details-local interactions such as preview input selection, preview zoom, or runtime-contract edits must redraw the selected-asset details surface only.
- Structural operations such as asset creation, removal, relocation, or full workspace reload may rebuild both navigator and details projections.
- Workspace-scoped progress and logging updates must not force navigator or selected-asset details redraw unless the underlying projection actually changed.
### State Rules
- The navigator must define explicit `loading assets` state.
- The navigator must define explicit `no assets` state.
- The navigator must define explicit `no results` state.
- The navigator must define explicit `workspace error` state.
- The workspace must define explicit operational freshness states when packer runtime divergence is surfaced.
- Unregistered assets must appear in the same navigator flow as registered assets.
- Unregistered styling must communicate `present but not yet registered`, not `broken`.
### Inputs Expansion
- Internal inputs may appear only as optional expansion or inspection surfaces.
- Inputs must not replace asset nodes as the default navigation unit.
## Selected Asset Details Rules
The selected asset view must use this stable composition:
1. top row with `Summary` and `Actions` side by side
2. `Runtime Contract`
3. `Inputs / Preview`
4. `Diagnostics`
This composition is stable across asset families.
The selected-asset details area must follow component-local ownership.
Rules:
- the details host should react to details lifecycle events such as loading, ready, and error;
- details sections should update independently when only one section's projection changed;
- forms and preview-local controls should publish and consume narrow typed events rather than trigger full details rebuild by default.
### Summary
- `Summary` must always be present for a selected asset.
- `Summary` must show:
- `asset_name`
- registration status
- build participation
- `asset_id` when available
- family/type
- asset root path
### Runtime Contract
- `Runtime Contract` must present runtime-facing asset output data in short, didactic form.
- `Runtime Contract` must surface:
- `output.format`
- `codec`
- `preload`
- Runtime-facing output information must not require raw JSON inspection.
### Inputs / Preview
- `Inputs / Preview` must expose internal inputs as part of the selected asset.
- Inputs should be structured by role where that information is available.
- Preview should be available for previewable materials such as:
- images
- palettes
- audio
- text
- similar lightweight input artifacts
- Preview of derived output may exist, but input preview has baseline priority.
### Diagnostics
- Diagnostics for the selected asset must appear inline in the selected asset view.
- Blockers, warnings, and hints must be distinguishable.
- Inline diagnostics must not be replaced by raw logs.
### Actions
- Actions must be explicit.
- Actions that target the selected asset must appear beside `Summary`, not in the navigator area.
- Safe and routine actions must be visually separated from sensitive mutations.
- Hidden or automatic repair behavior is not allowed in the selected-asset view.
- If packer surfaces stale/diverged/reconciling state, the selected-asset view may expose explicit refresh or reconcile-oriented actions, but it must not invent repair semantics locally.
## Action Rules
- Registered assets excluded from builds must expose an explicit `Include In Build` action.
- Primary actions for unregistered assets include `Register`.
- `Register` is a direct action in Studio UX. If registration is valid, clicking it must register immediately without an extra acknowledgement step.
- If registration is blocked, Studio may surface the blocking preview inline so the user can inspect why registration cannot proceed.
- Sensitive actions such as `Exclude From Build`, `Remove`, and `Relocate` must be visually separated from routine actions.
- Sensitive actions must not look interchangeable with routine actions.
- `Relocate` must collect an explicit user-chosen destination root before the staged preview is generated.
- Automatic relocation targets are not sufficient Studio UX for `Relocate`.
- `Exclude From Build` and `Remove` must confirm in a modal review surface rather than an inline staged panel.
## Activity, Progress, and Logs Rules
### Activity
- `Activity` belongs to the global right-side shell panel.
- `Activity` is the structured operational timeline of the Studio.
- Activity entries must be user-oriented rather than service-trace-oriented.
- Repetitive background events must be aggregated or summarized.
- Significant lifecycle milestones should remain visible in the feed.
### Progress
- Progress must be visible globally in the shell.
- Progress may also appear inline when the current asset or action clearly owns that progress.
- Progress tick events must update progress state rather than create feed spam.
### Logs
- Logs belong to the lower workspace region as detailed textual output.
- Logs are secondary drill-down, not the primary explanation surface.
- The user must not need raw logs to understand ordinary operational state.
### Failure Retention
- Recent actionable failures must remain visible until acknowledged.
- Failures tied to the selected asset should also surface inline in the selected asset view.
- Critical failures must not disappear merely because low-value events continue to arrive.
## Staged Mutation Rules
Sensitive asset mutations are `preview-first`.
The review surface depends on the mutation class.
Inline staged panels are allowed for non-destructive blocked or inspect-only flows.
Modal review and confirmation is required for `Exclude From Build`, `Remove`, and relocation commits.
Routine state patches such as `preload`, `Include In Build`, and `Exclude From Build` must patch the affected asset projection locally when identity is preserved. Full workspace refresh is reserved for operations that change workspace structure or identity resolution.
Operation orchestration must follow this rule:
- local patch when stable identity and local projection are preserved;
- explicit structural sync when collection shape, identity, or projection membership changes;
- no routine mutation path should fall back to whole-workspace refresh merely for implementation convenience.
### Mutations Requiring Preview
- `Exclude From Build`
- `Remove`
- relocational changes such as move or rename of asset roots
- batch operations
Navigator-level `Doctor` and `Pack`, plus asset-level `Include In Build` and successful `Register`, remain outside this sensitive mutation staging flow.
### Preview Content
- Preview must show affected assets.
- Relocation preview must show the planned target root chosen by the user.
- Preview must show proposed actions.
- Preview must distinguish registry impact from workspace impact.
- Preview must show blockers, warnings, and safe fixes as separate visual sections.
- Preview must show diff-style effects such as:
- create
- move
- delete
- registry update
### Apply Rules
- `Apply` must remain disabled while blockers exist.
- Batch operations must present an aggregate summary first.
- Batch operations may expose drill-down detail after the aggregate summary.
- Destructive or relocational actions must not bypass preview.
### Activity Integration
- `preview_ready` should surface in global `Activity`.
- `action_applied` should surface in global `Activity`.
- `action_failed` should surface in global `Activity`.
- reconcile or divergence state transitions should remain visible when they affect current workspace truth.
- The preview itself remains a workspace-local review surface.
## Non-Goals
This specification does not define:
- the exact JavaFX component tree or control class structure of the `Assets` workspace;
- final reusable component boundaries for all preview surfaces;
- future multi-select or bulk-edit UX beyond the currently defined staged batch summary rules.
## Exit Criteria
This specification is satisfied when the Studio `Assets` workspace:
- navigates by assets rather than raw files;
- preserves path awareness without collapsing into a file explorer;
- explains the selected asset through summary, contract, inputs, diagnostics, and actions;
- keeps activity, progress, and logs clearly separated;
- stages sensitive mutations through preview-first flows;
- proves the Studio event-driven workspace framework through lifecycle-managed local ownership;
- and behaves as a didactic helper for the packer model.
+65
View File
@@ -0,0 +1,65 @@
# Studio Specs
This directory contains the normative Studio specification set.
## Purpose
Specs define the official Studio contract.
They exist to stabilize:
- the application shell,
- workspace responsibilities,
- interaction flows,
- service and event integration expectations,
- UX behavior that implementation should preserve.
## Expected Format
The exact structure may vary by document, but a Studio spec should usually contain:
1. Title
2. Status
3. Scope or Applies To
4. Purpose
5. Authority and Precedence
6. Normative Inputs
7. Core Rules
8. Non-Goals
9. Exit Criteria
## Writing Rules
- Write in normative language.
- Integrate only decisions that have already been closed.
- Keep design exploration and option analysis out of the spec body.
- Preserve clear boundaries between shell, workspace, and integration specs.
## Upstream Rule
Specs should normally be fed by:
1. agendas that frame the open Studio topic,
2. decisions that close the product or interaction choice,
3. pull-request plans that define propagation,
4. then spec integration.
If a spec edit would require guessing unresolved UI behavior, stop and surface the missing decision first.
## Current Corpus
The current Studio core corpus is:
1. [`1. Studio Shell and Workspace Layout Specification.md`](1.%20Studio%20Shell%20and%20Workspace%20Layout%20Specification.md)
2. [`2. Studio UI Foundations Specification.md`](2.%20Studio%20UI%20Foundations%20Specification.md)
3. [`3. Studio Components Module Specification.md`](3.%20Studio%20Components%20Module%20Specification.md)
4. [`4. Assets Workspace Specification.md`](4.%20Assets%20Workspace%20Specification.md)
## Reading Order
Recommended order:
1. shell and workspace layout;
2. shared UI foundations;
3. components module policy;
4. assets workspace behavior.