event bus start: code, PRs e specs

This commit is contained in:
2026-03-24 13:42:43 +00:00
parent a16d63cfb5
commit e7670b5474
16 changed files with 731 additions and 42 deletions
@@ -23,6 +23,8 @@ This specification consolidates the accepted Studio shell decision into normativ
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
@@ -48,6 +50,20 @@ The baseline workspace set includes:
`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.
@@ -95,6 +111,7 @@ Rules:
- 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
@@ -102,4 +119,5 @@ 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.
@@ -23,6 +23,9 @@ This specification consolidates the accepted Studio UI foundations decision into
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
@@ -118,6 +121,7 @@ Shared Studio foundations include:
- shell-level UI conventions;
- event publication and observation infrastructure;
- reusable workspace framework primitives;
- reusable Studio control conventions.
## Subscription Lifecycle
@@ -135,6 +139,27 @@ This exists to make event wiring visible, testable, and safe under UI lifecycle
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;
@@ -146,6 +171,7 @@ Shared Studio foundations do not include:
- 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
@@ -153,4 +179,5 @@ 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.
@@ -21,6 +21,7 @@ This specification consolidates the accepted Studio components module decision i
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
@@ -28,7 +29,8 @@ This specification consolidates the accepted Studio components module decision i
- the authoritative Studio control layer;
- the home of the Studio visual dialect;
- the place where Studio-facing controls are shaped for Studio use.
- 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:
@@ -45,6 +47,7 @@ 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
@@ -81,6 +84,25 @@ Rules:
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:
@@ -135,6 +157,7 @@ The module must remain:
- 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
@@ -142,4 +165,5 @@ 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.
@@ -68,6 +68,14 @@ The workspace must help the user understand:
- what the asset declares toward the runtime-facing contract;
- which operations are safe, staged, blocked, or destructive.
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:
@@ -80,6 +88,18 @@ The baseline workspace layout is:
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
@@ -133,6 +153,17 @@ Filesystem structure may be visible and actionable as supporting context, but 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.
@@ -158,6 +189,14 @@ The selected asset view must use this stable composition:
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.
@@ -253,6 +292,14 @@ Inline staged panels are allowed for non-destructive blocked or inspect-only flo
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`
@@ -295,7 +342,6 @@ 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;
- cross-workspace reuse beyond the `Assets` workspace;
- future multi-select or bulk-edit UX beyond the currently defined staged batch summary rules.
## Exit Criteria
@@ -307,4 +353,5 @@ This specification is satisfied when the Studio `Assets` workspace:
- 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.