update specs studio
This commit is contained in:
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user