discussion framework migration
This commit is contained in:
@@ -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.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user