From 9ed16301ab607c0a30338c521444e9016330e38a Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Wed, 11 Mar 2026 11:23:50 +0000 Subject: [PATCH] update agenda studio --- ...Workspace Navigation, and Layout Agenda.md | 86 ++++++++++- ...nts, Progress, and Activity Feed Agenda.md | 28 +++- ...g, Events, and Custom Components Agenda.md | 104 +++++++++++++ ...ents Module and Admission Policy Agenda.md | 60 ++++++++ docs/studio/agendas/README.md | 19 ++- ...orkspace-navigation-and-layout-decision.md | 145 ++++++++++++++++++ docs/studio/decisions/README.md | 4 +- 7 files changed, 432 insertions(+), 14 deletions(-) create mode 100644 docs/studio/agendas/01.6. Studio UI Foundations - Naming, Events, and Custom Components Agenda.md create mode 100644 docs/studio/agendas/01.7. Studio Components Module and Admission Policy Agenda.md create mode 100644 docs/studio/decisions/001-studio-shell-workspace-navigation-and-layout-decision.md 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 index 365c366d..e9c7607e 100644 --- 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 @@ -2,7 +2,7 @@ ## Status -Open +Closed ## Purpose @@ -30,6 +30,12 @@ Current `prometeu-studio` already provides: 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? @@ -58,6 +64,13 @@ Adopt a dock-heavy IDE-style shell from the start. - 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. @@ -65,12 +78,77 @@ Prefer Option B. Recommended direction: - keep workspace switching in the shell, -- formalize a stable frame with navigation, workspace body, and activity/progress region, -- let each workspace own its internal panels, -- avoid a fully dockable IDE model for the first Studio UI wave. +- 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.4. Background Events, Progress, and Activity Feed Agenda.md b/docs/studio/agendas/01.4. Background Events, Progress, and Activity Feed Agenda.md index 291c21d0..81af62e5 100644 --- a/docs/studio/agendas/01.4. Background Events, Progress, and Activity Feed Agenda.md +++ b/docs/studio/agendas/01.4. Background Events, Progress, and Activity Feed Agenda.md @@ -46,7 +46,33 @@ Baseline direction: - structured event rendering rather than raw log dumping, - progress visible both inline and in the activity surface, - recent actionable failures retained until acknowledged, -- normal background noise summarized rather than streamed endlessly. +- normal background noise summarized rather than streamed endlessly, +- use the right-side panel for structured activity and progress, +- reserve the bottom region for logs and detailed textual output, +- support a tabbed right-side panel so activity can coexist with other contextual surfaces such as diagnostics or inspector views. + +## Distinction Between Activity and Logs + +Baseline distinction: + +- `activity` is the structured operational timeline of the Studio; +- `logs` are detailed textual outputs from compiler, packer, and other services. + +Examples of `activity`: + +- project opened; +- asset scan started; +- diagnostics updated; +- build started or finished; +- preview ready; +- action applied or failed. + +Examples of `logs`: + +- compiler output; +- packer trace output; +- stack traces; +- detailed technical diagnostics and execution text. ## Expected Follow-up 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 new file mode 100644 index 00000000..35452ec6 --- /dev/null +++ b/docs/studio/agendas/01.6. Studio UI Foundations - Naming, Events, and Custom Components Agenda.md @@ -0,0 +1,104 @@ +# 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 new file mode 100644 index 00000000..18f9d2ef --- /dev/null +++ b/docs/studio/agendas/01.7. Studio Components Module and Admission Policy Agenda.md @@ -0,0 +1,60 @@ +# 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 bae0c220..4274b434 100644 --- a/docs/studio/agendas/README.md +++ b/docs/studio/agendas/README.md @@ -6,18 +6,21 @@ This directory contains active Studio discussion agendas. The initial Studio UI planning wave is: -1. [`01.0. Studio Shell, Workspace Navigation, and Layout Agenda.md`](./01.0.%20Studio%20Shell,%20Workspace%20Navigation,%20and%20Layout%20Agenda.md) -2. [`01.1. Asset Workspace Information Architecture Agenda.md`](./01.1.%20Asset%20Workspace%20Information%20Architecture%20Agenda.md) -3. [`01.2. Asset List, Filters, and Selection Model Agenda.md`](./01.2.%20Asset%20List,%20Filters,%20and%20Selection%20Model%20Agenda.md) -4. [`01.3. Asset Details, Diagnostics, and Action Surface Agenda.md`](./01.3.%20Asset%20Details,%20Diagnostics,%20and%20Action%20Surface%20Agenda.md) -5. [`01.4. Background Events, Progress, and Activity Feed Agenda.md`](./01.4.%20Background%20Events,%20Progress,%20and%20Activity%20Feed%20Agenda.md) -6. [`01.5. Preview, Confirm, and Apply Mutation Flows Agenda.md`](./01.5.%20Preview,%20Confirm,%20and%20Apply%20Mutation%20Flows%20Agenda.md) +1. [`01.1. Asset Workspace Information Architecture Agenda.md`](./01.1.%20Asset%20Workspace%20Information%20Architecture%20Agenda.md) +2. [`01.2. Asset List, Filters, and Selection Model Agenda.md`](./01.2.%20Asset%20List,%20Filters,%20and%20Selection%20Model%20Agenda.md) +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.0 -> 01.1 -> 01.2 -> 01.3 -> 01.4 -> 01.5` +`01.6 -> 01.7 -> 01.1 -> 01.2 -> 01.3 -> 01.4 -> 01.5` -That order closes the Studio shell first, then the asset workspace structure, then interaction details and mutation flows. +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 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. ## 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 new file mode 100644 index 00000000..c5b6d649 --- /dev/null +++ b/docs/studio/decisions/001-studio-shell-workspace-navigation-and-layout-decision.md @@ -0,0 +1,145 @@ +# 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 ef21c963..70b38734 100644 --- a/docs/studio/decisions/README.md +++ b/docs/studio/decisions/README.md @@ -2,7 +2,9 @@ This directory contains Studio decision records. -There are currently no retained Studio decision records. +Current retained Studio decisions: + +1. [`001-studio-shell-workspace-navigation-and-layout-decision.md`](./001-studio-shell-workspace-navigation-and-layout-decision.md) ## Purpose