From 2ee37d7d13b71ada8bafa016754337041d8758d9 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Wed, 11 Mar 2026 12:11:25 +0000 Subject: [PATCH] update specs studio --- docs/studio/README.md | 8 +- ...Workspace Navigation, and Layout Agenda.md | 154 ------------------ ...g, Events, and Custom Components Agenda.md | 104 ------------ ...ents Module and Admission Policy Agenda.md | 60 ------- docs/studio/agendas/README.md | 8 +- ...orkspace-navigation-and-layout-decision.md | 145 ----------------- docs/studio/decisions/README.md | 7 +- docs/studio/learn/README.md | 7 + ...ntal-model-studio-events-and-components.md | 76 +++++++++ .../studio/learn/mental-model-studio-shell.md | 60 +++++++ ...hell and Workspace Layout Specification.md | 105 ++++++++++++ .../2. Studio UI Foundations Specification.md | 123 ++++++++++++++ ... Studio Components Module Specification.md | 130 +++++++++++++++ docs/studio/specs/README.md | 16 ++ 14 files changed, 532 insertions(+), 471 deletions(-) delete mode 100644 docs/studio/agendas/01.0. Studio Shell, Workspace Navigation, and Layout Agenda.md delete mode 100644 docs/studio/agendas/01.6. Studio UI Foundations - Naming, Events, and Custom Components Agenda.md delete mode 100644 docs/studio/agendas/01.7. Studio Components Module and Admission Policy Agenda.md delete mode 100644 docs/studio/decisions/001-studio-shell-workspace-navigation-and-layout-decision.md create mode 100644 docs/studio/learn/mental-model-studio-events-and-components.md create mode 100644 docs/studio/learn/mental-model-studio-shell.md create mode 100644 docs/studio/specs/1. Studio Shell and Workspace Layout Specification.md create mode 100644 docs/studio/specs/2. Studio UI Foundations Specification.md create mode 100644 docs/studio/specs/3. Studio Components Module Specification.md diff --git a/docs/studio/README.md b/docs/studio/README.md index 10ebf0a7..441b63ba 100644 --- a/docs/studio/README.md +++ b/docs/studio/README.md @@ -45,6 +45,8 @@ Use it to: - decide how Studio consumes services and events, - define what must be visible, staged, or confirmed in the UI. +When a topic is fully propagated into specs and learn, the corresponding agenda should leave the retained set. + ### `decisions/` `decisions/` records closed Studio product and UX decisions before they are fully propagated. @@ -55,6 +57,8 @@ Use it to: - define invariants for UI behavior, - capture what must be implemented in Studio code and service contracts. +Once their content is fully absorbed into specs and learn, they should not be retained just as historical residue. + ### `pull-requests/` `pull-requests/` contains execution plans for Studio changes. @@ -99,9 +103,11 @@ The preferred Studio documentation flow is: ## Practical Rule - `agendas/` stores currently open Studio questions. -- `decisions/` stores decisions that still need propagation. +- `decisions/` stores only decisions that still need propagation. - `pull-requests/` stores execution plans. - `specs/` stores the normative Studio contract. - `learn/` stores teaching-oriented Studio knowledge. +The current Studio core has already been consolidated into [`specs/`](./specs/) and [`learn/`](./learn/). The `agendas/` and `decisions/` directories remain available for future cycles. + If implementation exposes a missing UI or interaction decision, stop and return to `agendas/` or `decisions/`. diff --git a/docs/studio/agendas/01.0. Studio Shell, Workspace Navigation, and Layout Agenda.md b/docs/studio/agendas/01.0. Studio Shell, Workspace Navigation, and Layout Agenda.md deleted file mode 100644 index e9c7607e..00000000 --- a/docs/studio/agendas/01.0. Studio Shell, Workspace Navigation, and Layout Agenda.md +++ /dev/null @@ -1,154 +0,0 @@ -# Studio Shell, Workspace Navigation, and Layout Agenda - -## Status - -Closed - -## Purpose - -Define the baseline Studio shell: - -- main window layout, -- workspace navigation model, -- shell regions and panel hierarchy, -- default landing behavior, -- how future workspaces should fit into the frame. - -## Domain Owner - -`docs/studio` - -## Current Code Context - -Current `prometeu-studio` already provides: - -- `MainView` as the root shell; -- `WorkspaceBar` as left-side workspace navigation; -- `EditorWorkspace` as the most concrete workspace; -- placeholder workspaces for `Assets` and `Device`; -- a `BuilderWorkspace` implementation artifact with logs and toolbar. - -The shell exists, but it is still closer to a scaffold than a documented Studio UX contract. - -This shell may be substantially remodeled in code as long as the resulting Studio preserves: - -- theme support; -- i18n support; -- a clear path for custom Studio components instead of ad hoc UI fragments. - -## Core Questions - -1. What is the long-lived shell structure of the Studio? -2. Is left-side workspace switching the correct baseline navigation model? -3. Which shell regions are global and which belong to each workspace? -4. How should the Assets workspace coexist with Editor, Device, and future shipping flows? -5. What should the default landing workspace be? - -## Options - -### Option A - -Keep the current shell mostly intact and grow workspaces within it. - -### Option B - -Evolve toward a multi-panel shell with global activity and contextual side panels. - -### Option C - -Adopt a dock-heavy IDE-style shell from the start. - -## Tradeoffs - -- Option A is fast and consistent with current code, but may constrain richer workflows later. -- Option B preserves the current shell while creating room for Studio-grade interaction design. -- Option C is powerful, but likely too heavy for the current code and service maturity. - -Specific concern with adopting a fully docked shell too early: - -- it forces panel lifecycle and layout-persistence decisions before the core workspace model is stable; -- it adds implementation weight around focus, restore, drag/drop, and window state without proving that the Studio already needs that flexibility; -- it increases UX complexity while the Assets workspace and background activity model are still being defined; -- it risks stabilizing the wrong shell topology too early. - -## Recommendation - -Prefer Option B. - -Recommended direction: - -- keep workspace switching in the shell, -- formalize a stable frame with top global menus, left workspace selectors, center workspace body, and right global utility panel, -- let each workspace own its internal panels, including logs and detailed operational output, -- avoid a fully dockable IDE model for the first Studio UI wave, -- revisit dockability only after the shell regions and workspace panel responsibilities are proven in use. - -## Open Questions - -1. Which shell regions are baseline and always present: - top global menus, left workspace navigation, right global utility panel, status/progress bar? -2. Which right-side tabs are baseline in v1, and which are future additions? -3. Should the Studio land directly in a workspace, restore the last workspace, or open through a project launcher/home surface first? -4. Does `BuilderWorkspace` remain a first-class shell workspace, or should future shipping/build flows move toward a different Studio surface? -5. Which parts of the shell must be fixed in v1, and which can remain future extension points without immediate docking support? - -## Current Direction - -The preferred direction for question 3 is to introduce a lightweight project launcher or home surface before the main workspace shell. - -Target experience: - -- closer to Unity or the IntelliJ family than to direct last-tab restore; -- show existing projects immediately; -- make `open project` and `create project` first-class actions; -- only enter the workspace shell after a concrete project is selected or created. - -This keeps project entry intentional and gives the Studio a stable place for project lifecycle actions without overloading the main workspace shell. - -The current preferred shell model is: - -- top region with global Studio menus such as `File`, `Edit`, `View`, and similar shell-level actions; -- left-side fixed workspace selector, closer to IntelliJ-style workspace switching than to a free docking system; -- center region fully owned by the selected workspace; -- right-side global utility surface implemented as tabs; -- logs and detailed execution output owned by each workspace instead of a single global bottom console. - -The right-side global utility surface is intended for concerns such as: - -- general activity visibility; -- contextual inspector or summary views; -- global shortcuts and shell-level utility surfaces. - -`Run` should not be modeled as a tab. - -It should remain always visible at the top-right portion of the shell so that running the current project or relevant flow is always easy to reach. - -This keeps run/build controls immediately accessible while allowing the right-side tab system to serve broader global concerns. - -Current baseline answers: - -- the initial right-side tab set contains only `Activity`; -- the right-side panel must remain easy to extend with additional tabs later; -- `BuilderWorkspace` may remain in the shell temporarily because it is still useful for tests, but it should be treated as a low-investment transitional surface on the path toward a future `Shipper`; -- the baseline fixed workspace set is: - - Code Editor - - Asset Management - - Debugger/Profiler - - Shipper, temporarily represented by the current `BuilderWorkspace` - -The shell and workspaces should also evolve with explicit foundations for: - -- clear naming conventions, -- a Studio event system, -- reusable custom components such as directory trees and related structured UI controls. - -## Expected Follow-up - -- a shell decision, -- a Studio shell spec, -- a PR/plan for `MainView`, `WorkspaceBar`, and workspace composition. -- a separate Studio foundations agenda for naming, events, and custom component architecture. - -## Outcome - -Closed in [`001-studio-shell-workspace-navigation-and-layout-decision.md`](../decisions/001-studio-shell-workspace-navigation-and-layout-decision.md). diff --git a/docs/studio/agendas/01.6. Studio UI Foundations - Naming, Events, and Custom Components Agenda.md b/docs/studio/agendas/01.6. Studio UI Foundations - Naming, Events, and Custom Components Agenda.md deleted file mode 100644 index 35452ec6..00000000 --- a/docs/studio/agendas/01.6. Studio UI Foundations - Naming, Events, and Custom Components Agenda.md +++ /dev/null @@ -1,104 +0,0 @@ -# Studio UI Foundations - Naming, Events, and Custom Components Agenda - -## Status - -Open - -## Purpose - -Define the shared UI foundations required before the Studio grows into a larger product surface. - -This agenda exists to keep the Studio from becoming a pile of unrelated JavaFX screens with inconsistent naming, ad hoc event wiring, and one-off controls. - -## Domain Owner - -`docs/studio` - -## Context - -The current `prometeu-studio` shell is still small enough to be remodeled. - -Today there is no real Studio-wide event system. - -Current behavior is still largely based on direct wiring between UI elements, workspace hosts, and service calls. - -That is the right moment to establish explicit foundations for: - -- clear naming conventions; -- a Studio event system; -- reusable custom components; -- long-lived support for i18n and themes. - -The immediate driver is the upcoming Assets workspace, but the same foundations will affect Editor, Debugger/Profiler, and the future Shipper surface. - -## Core Questions - -1. Which naming conventions should apply to Studio shell classes, workspaces, panels, services, and events? -2. What kind of Studio-wide event system should exist between shell, workspaces, and background services? -3. Which custom components should become first-class reusable Studio controls instead of one-off implementations? -4. How should i18n and theme support constrain custom component design from day 1? -5. Where is the boundary between generic infrastructure and domain-specific workspace UI? - -## Initial Areas To Close - -### Naming - -Need clear and stable names for: - -- shell surfaces; -- workspace types; -- right-side utility tabs; -- events and event payloads; -- reusable controls and component packages. - -### Events - -Need a Studio event model that can support: - -- shell-level state changes; -- workspace-local interactions; -- background service notifications; -- progress and activity publication; -- future debugger/profiler integration. - -Current direction: - -- introduce a Studio-owned event system instead of continuing with ad hoc direct coupling; -- keep it small, local, and strongly typed; -- model it as a `StudioEventBus` or equivalent typed publish/subscribe surface; -- avoid stringly-typed event names and avoid overbuilding a large reactive framework too early. - -Illustrative event categories include: - -- project lifecycle events; -- workspace selection events; -- run/build intent events; -- activity publication events; -- diagnostics and asset-selection events. - -### Custom Components - -Likely candidates include: - -- directory tree or project tree controls; -- activity feed views; -- diagnostics list views; -- inspector panels; -- staged action and preview surfaces. - -## Recommendation - -Close this agenda early, right after the shell decision. - -Recommended direction: - -- establish naming before adding many more UI classes; -- define a Studio-owned typed event system before workspaces start integrating services ad hoc; -- invest in reusable components only where the shell or multiple workspaces will truly benefit; -- require i18n and theme compliance for every Studio-specific control. - -## Expected Follow-up - -- one or more Studio foundation decisions, -- a foundational Studio spec, -- a PR/plan for shared UI infrastructure in `prometeu-studio`. diff --git a/docs/studio/agendas/01.7. Studio Components Module and Admission Policy Agenda.md b/docs/studio/agendas/01.7. Studio Components Module and Admission Policy Agenda.md deleted file mode 100644 index 18f9d2ef..00000000 --- a/docs/studio/agendas/01.7. Studio Components Module and Admission Policy Agenda.md +++ /dev/null @@ -1,60 +0,0 @@ -# Studio Components Module and Admission Policy Agenda - -## Status - -Open - -## Purpose - -Define the role of `prometeu-studio-components` and the rules for what should enter that module. - -The module now exists as a base project, but it should not become a dumping ground for wrappers around JavaFX controls or speculative framework work. - -## Domain Owner - -`docs/studio` - -## Context - -The Studio UI is about to be remodeled. - -We want: - -- a consistent Studio UI dialect; -- reusable JavaFX-based Studio components; -- easier customization and stronger engineering around shared controls; -- continued compatibility with i18n and themes. - -At the same time, we explicitly do not want to populate the module prematurely. - -## Current Direction - -`prometeu-studio-components` should remain empty until concrete Studio UI work requires shared controls. - -The baseline policy is: - -- the module exists now so Studio UI work has a clear home for shared components; -- components are admitted only when they are needed by the current Studio UI wave; -- the module should stay focused on real Studio shell and workspace needs, not general JavaFX abstraction for its own sake. - -## Core Questions - -1. Which kinds of components belong in `prometeu-studio-components` from day 1? -2. Which controls should remain local to `prometeu-studio` until a second use appears? -3. What theme and i18n requirements must every admitted component satisfy? -4. How much infrastructure should live in this module versus in Studio application code? -5. How do we prevent the module from turning into a speculative component catalog? - -## Recommendation - -Keep the module intentionally sparse. - -Recommended admission rule: - -- add a component when it is part of the shell or has immediate reuse in the current Studio UI work; -- otherwise keep it local until the need is proven. - -## Expected Follow-up - -- a decision on the admission policy for `prometeu-studio-components`; -- a future spec or learn artifact once the first component wave actually exists. diff --git a/docs/studio/agendas/README.md b/docs/studio/agendas/README.md index 4274b434..587e28bb 100644 --- a/docs/studio/agendas/README.md +++ b/docs/studio/agendas/README.md @@ -11,16 +11,14 @@ The initial Studio UI planning wave is: 3. [`01.3. Asset Details, Diagnostics, and Action Surface Agenda.md`](./01.3.%20Asset%20Details,%20Diagnostics,%20and%20Action%20Surface%20Agenda.md) 4. [`01.4. Background Events, Progress, and Activity Feed Agenda.md`](./01.4.%20Background%20Events,%20Progress,%20and%20Activity%20Feed%20Agenda.md) 5. [`01.5. Preview, Confirm, and Apply Mutation Flows Agenda.md`](./01.5.%20Preview,%20Confirm,%20and%20Apply%20Mutation%20Flows%20Agenda.md) -6. [`01.6. Studio UI Foundations - Naming, Events, and Custom Components Agenda.md`](./01.6.%20Studio%20UI%20Foundations%20-%20Naming,%20Events,%20and%20Custom%20Components%20Agenda.md) -7. [`01.7. Studio Components Module and Admission Policy Agenda.md`](./01.7.%20Studio%20Components%20Module%20and%20Admission%20Policy%20Agenda.md) Recommended discussion order: -`01.6 -> 01.7 -> 01.1 -> 01.2 -> 01.3 -> 01.4 -> 01.5` +`01.1 -> 01.2 -> 01.3 -> 01.4 -> 01.5` -The Studio shell baseline was closed in [`../decisions/001-studio-shell-workspace-navigation-and-layout-decision.md`](../decisions/001-studio-shell-workspace-navigation-and-layout-decision.md). +The shell, UI foundations, and components admission baselines were already consolidated into [`../specs/`](../specs/) and [`../learn/`](../learn/). -The remaining order closes the shared UI foundations, then the components admission policy, then the asset workspace structure, and only after that the detailed interaction flows. +The remaining order closes the asset workspace structure first, and only after that the detailed interaction flows. ## Purpose diff --git a/docs/studio/decisions/001-studio-shell-workspace-navigation-and-layout-decision.md b/docs/studio/decisions/001-studio-shell-workspace-navigation-and-layout-decision.md deleted file mode 100644 index c5b6d649..00000000 --- a/docs/studio/decisions/001-studio-shell-workspace-navigation-and-layout-decision.md +++ /dev/null @@ -1,145 +0,0 @@ -# Studio Shell, Workspace Navigation, and Layout Decision - -## Status - -Accepted - -## Cycle - -Studio UI Wave 01 - -## Context - -`prometeu-studio` already has a shell scaffold, but it was assembled manually and does not yet define a stable Studio UI contract. - -At the same time, the Studio is about to grow in at least these directions: - -- code editing; -- asset management; -- debugger and profiler work; -- future shipping flows; -- shared activity and run controls. - -The shell therefore needs to be stabilized before the Assets workspace and broader UI work expand further. - -This decision applies only to the Studio UI layer at this stage. -It does not reopen unrelated service or domain contracts. - -## Decision - -The Studio adopts a structured shell, not a fully docked IDE shell, for the current UI wave. - -The baseline shell is: - -- top global menu region; -- left fixed workspace selector; -- center workspace host; -- right global utility panel with tabs; -- top-right always-visible run surface. - -The shell must open through a lightweight project launcher or home surface before entering the main workspace frame. - -## Invariants and Constraints - -### Global Shell Regions - -The baseline mandatory shell regions are: - -- top global menus; -- left workspace navigation; -- center workspace host; -- right global utility panel; -- top-right run surface. - -Logs and detailed operational output do not belong to the global shell as a single shared console. -They belong to the active workspace that owns the operation. - -### Workspace Model - -The left-side workspace selector remains fixed for now. - -The baseline workspace set is: - -- Code Editor; -- Asset Management; -- Debugger/Profiler; -- Shipper, temporarily represented by the current `BuilderWorkspace`. - -`BuilderWorkspace` may remain in the shell for now because it is still useful for testing, but it is a transitional surface and should receive minimal new investment until the future `Shipper` is properly defined. - -### Right-Side Utility Panel - -The right-side global utility surface is tab-based. - -Baseline rules: - -- the initial tab set contains only `Activity`; -- the panel must remain easy to extend with additional tabs later; -- `Run` is not a tab. - -The right-side panel is for general Studio awareness and shell-level utility, not for per-workspace log dumping. - -### Project Entry - -The Studio must not land directly into a workspace as the primary entry flow. - -Baseline behavior: - -- first show a lightweight project launcher or home surface; -- 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. - -### UI Remodeling Scope - -The Studio UI may be substantially remodeled in code during this wave. - -That flexibility is limited by these requirements: - -- theme support must be preserved; -- i18n support must be preserved; -- the resulting UI should create a clear path for reusable Studio components rather than ad hoc JavaFX fragments. - -### No Fully Docked Shell Yet - -A fully docked IDE shell is explicitly deferred. - -Reasons: - -- shell topology is still being proven; -- workspace responsibilities are still being defined; -- early docking would force layout and lifecycle decisions too soon; -- the extra complexity is not justified by the current product maturity. - -Dockability may be revisited only after shell regions and workspace panel responsibilities are stable in actual use. - -## Explicit Non-Decisions - -This decision does not yet define: - -- the full set of future right-side tabs beyond `Activity`; -- the detailed content model of the `Activity` surface; -- the Studio event system architecture in detail; -- custom component admission policy; -- the internal panel composition of each workspace. - -Those topics remain delegated to follow-up Studio agendas and decisions. - -## Propagation Targets - -This decision must propagate to: - -- Studio shell specifications under `docs/studio/specs/`; -- Studio foundation work on naming, events, and custom components; -- future PR/plan work for `MainView`, workspace switching, project launcher, and shell composition; -- code implementation in `prometeu-studio` and future shared UI work in `prometeu-studio-components`. - -## Validation Notes - -A conforming first UI wave should make these behaviors visible: - -- the user enters through a project launcher or home surface; -- the shell shows a fixed workspace rail on the left; -- the selected workspace owns its main body and its own logs; -- the right side exposes `Activity` as a global utility surface; -- run controls remain immediately visible without opening a tab. diff --git a/docs/studio/decisions/README.md b/docs/studio/decisions/README.md index 70b38734..d857a03b 100644 --- a/docs/studio/decisions/README.md +++ b/docs/studio/decisions/README.md @@ -2,9 +2,12 @@ This directory contains Studio decision records. -Current retained Studio decisions: +There are currently no retained Studio decision records. -1. [`001-studio-shell-workspace-navigation-and-layout-decision.md`](./001-studio-shell-workspace-navigation-and-layout-decision.md) +The first Studio decision wave was already consolidated into: + +- normative specifications under [`../specs/`](../specs/) +- didactic material under [`../learn/`](../learn/) ## Purpose diff --git a/docs/studio/learn/README.md b/docs/studio/learn/README.md index 6d142c1b..ea37d264 100644 --- a/docs/studio/learn/README.md +++ b/docs/studio/learn/README.md @@ -41,3 +41,10 @@ If content grows, prefer: - overview documents, - explicit learning paths, - consolidation of duplicated explanations. + +## Current Learning Path + +Start here: + +1. [`mental-model-studio-shell.md`](./mental-model-studio-shell.md) +2. [`mental-model-studio-events-and-components.md`](./mental-model-studio-events-and-components.md) diff --git a/docs/studio/learn/mental-model-studio-events-and-components.md b/docs/studio/learn/mental-model-studio-events-and-components.md new file mode 100644 index 00000000..95837a26 --- /dev/null +++ b/docs/studio/learn/mental-model-studio-events-and-components.md @@ -0,0 +1,76 @@ +# Studio Events and Components Mental Model + +Two things are meant to stop the Studio from becoming messy as it grows: + +- a typed event model; +- a single authoritative control layer. + +These two rules solve different problems, but they reinforce each other. + +## Why a Studio-owned event system? + +Without it, the shell, workspaces, and services begin to call each other directly. + +That usually feels fine at first, because the UI is small. Then the application gains: + +- global activity surfaces; +- background operations; +- multiple workspaces; +- status and progress reporting; +- cross-cutting actions such as run or diagnostics. + +At that point, direct references become the path of least resistance and the UI starts coupling itself in ways that are hard to unwind. + +The Studio event system exists to keep event publication explicit and typed. + +## Why both a global bus and workspace buses? + +Because the Studio needs both segregation and shared visibility. + +Workspaces should be able to keep their local activity scoped. +The shell should still be able to observe what is happening globally. + +The chosen rule is therefore: + +- each workspace has its own bus; +- the Studio has a global bus; +- every workspace event is automatically republished to the global bus. + +This means callers do not need to decide when to duplicate publication manually. + +## Why not rely on raw JavaFX controls directly? + +Because raw JavaFX use spreads quickly and creates UI drift. + +When each part of the app consumes JavaFX controls directly, the Studio gradually accumulates: + +- inconsistent naming; +- inconsistent styling hooks; +- repeated local wrappers; +- uneven behavior between screens; +- more work each time theme or locale behavior needs to change. + +That is why the Studio uses `prometeu-studio-components` as its visual control layer. + +## Does that mean reimplementing JavaFX? + +No. + +The goal is not to reproduce every JavaFX API. +The goal is to expose the Studio-facing API the application actually needs. + +That keeps the control layer: + +- opinionated; +- smaller than JavaFX; +- aligned with the Studio's own UI dialect. + +## Practical reading rule + +When adding UI code, ask two questions: + +1. Is this communication really an event? +2. Is this control part of the Studio's visible dialect? + +If the answer to the first question is yes, it should probably publish a typed Studio event. +If the answer to the second question is yes, it should probably come through `prometeu-studio-components`. diff --git a/docs/studio/learn/mental-model-studio-shell.md b/docs/studio/learn/mental-model-studio-shell.md new file mode 100644 index 00000000..785e44b4 --- /dev/null +++ b/docs/studio/learn/mental-model-studio-shell.md @@ -0,0 +1,60 @@ +# Studio Shell Mental Model + +The Studio shell exists to frame workspaces, not to absorb every piece of UI. + +That distinction matters because a lot of early JavaFX applications slowly become a single giant layout where every new concern gets added to the same frame. The shell model chosen here avoids that. + +## What belongs to the shell? + +The shell owns: + +- project entry through a launcher or home surface; +- global menus; +- fixed workspace navigation; +- the workspace host; +- the right-side utility surface; +- the always-visible run surface. + +The shell does not own the full operating detail of every domain workflow. + +## What belongs to a workspace? + +A workspace owns its main body and its domain-specific detail. + +That includes things like: + +- editor-specific structure; +- asset-management views; +- debugger and profiler views; +- workspace-local logs and detailed operational output. + +This is why the Studio does not define a mandatory single global console as the primary logging model. + +## Why avoid a fully docked shell right now? + +Because the Studio is still proving its topology. + +If docking is introduced too early, the codebase starts solving these problems before the product actually needs them: + +- panel restore rules; +- drag-and-drop docking behavior; +- focus and lifecycle complexity; +- layout persistence; +- too many shell-level extension points. + +The structured shell keeps the frame stable without pretending the full IDE model is already known. + +## Why is `Run` always visible? + +Because run is a primary action, not a secondary panel. + +If running the project requires opening a tab first, the shell is hiding one of the most important actions behind navigation friction. The Studio therefore treats `Run` as a persistent shell control. + +## Practical reading rule + +When deciding whether something belongs in the shell or in a workspace, ask: + +> “Is this a Studio-wide framing concern, or is it operational detail of one workspace?” + +If it is framing, it belongs in the shell. +If it is operational detail, it probably belongs in the workspace. diff --git a/docs/studio/specs/1. Studio Shell and Workspace Layout Specification.md b/docs/studio/specs/1. Studio Shell and Workspace Layout Specification.md new file mode 100644 index 00000000..83e3926a --- /dev/null +++ b/docs/studio/specs/1. Studio Shell and Workspace Layout Specification.md @@ -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. diff --git a/docs/studio/specs/2. Studio UI Foundations Specification.md b/docs/studio/specs/2. Studio UI Foundations Specification.md new file mode 100644 index 00000000..a72cd0c4 --- /dev/null +++ b/docs/studio/specs/2. Studio UI Foundations Specification.md @@ -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. diff --git a/docs/studio/specs/3. Studio Components Module Specification.md b/docs/studio/specs/3. Studio Components Module Specification.md new file mode 100644 index 00000000..65da1aef --- /dev/null +++ b/docs/studio/specs/3. Studio Components Module Specification.md @@ -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. diff --git a/docs/studio/specs/README.md b/docs/studio/specs/README.md index be441007..f64bb9f9 100644 --- a/docs/studio/specs/README.md +++ b/docs/studio/specs/README.md @@ -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.