update specs studio

This commit is contained in:
2026-03-24 13:42:39 +00:00
parent 9ed16301ab
commit 2ee37d7d13
14 changed files with 532 additions and 471 deletions
@@ -0,0 +1,105 @@
# 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.
## 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.
## 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
## Exit Criteria
This specification is complete enough when:
- project entry and shell regions are unambiguous;
- workspace and shell responsibilities are clearly separated;
- the baseline Studio frame is stable enough for implementation planning.
@@ -0,0 +1,123 @@
# 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.
## 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;
- the baseline model should remain intentionally small;
- a large reactive framework is not baseline behavior.
## 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.
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;
- workspace selection events;
- run and build intent events;
- activity publication events;
- progress update events;
- diagnostics update events;
- asset selection events.
## 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 Studio control conventions.
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
## Exit Criteria
This specification is complete enough when:
- naming rules are stable enough to guide new Studio code;
- the event topology is explicit;
- theme and i18n constraints are unambiguous for shared Studio UI work.
@@ -0,0 +1,130 @@
# 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.
## 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.
`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.
## 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.
## 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
## Exit Criteria
This specification is complete enough when:
- the module role is unambiguous;
- admission rules are stable enough to guide implementation;
- the JavaFX wrapping boundary is clear enough to prevent drift.
+16
View File
@@ -45,3 +45,19 @@ Specs should normally be fed by:
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)
## Reading Order
Recommended order:
1. shell and workspace layout;
2. shared UI foundations;
3. components module policy.