complete Studio core and JavaFX boundary migration
Intrepid/Prometeu/Studio/pipeline/pr-master Build started...
JaCoCo Coverage #### Project Overview No changes detected, that affect the code coverage. * Line Coverage: 64.01% (20482/31999) * Branch Coverage: 54.22% (8240/15196) * Lines of Code: 31999 * Cyclomatic Complexity: 13164 #### Quality Gates Summary Output truncated.
Test / Build skipped: 15, passed: 715
Intrepid/Prometeu/Studio/pipeline/head This commit looks good

This commit is contained in:
2026-09-25 11:28:18 +01:00
parent 10f1b3f87c
commit a0a5050d5e
461 changed files with 9319 additions and 7205 deletions
@@ -1,169 +1,66 @@
# Studio Components Module Specification
# Studio JavaFX Components Boundary Specification
Status: Draft
Scope: `prometeu-studio-components` role, admission policy, and JavaFX wrapping boundary
Purpose: Define the authoritative visual control layer for the Studio.
## Status
Active
## Applies To
- `prometeu-studio-ui-javafx`
- shared Studio controls and workspace-framework primitives
- JavaFX controls actively used by the Studio
## Purpose
Define the visual component boundary inside the JavaFX adapter without creating a second application or domain layer.
## 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
This specification is subordinate to [`9. Studio Core and Adapter Architecture Specification.md`](9.%20Studio%20Core%20and%20Adapter%20Architecture%20Specification.md).
## 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.
6. Reusable event-driven workspace controls should be admitted when they are part of the active Studio workspace framework.
1. Reusable Studio visual controls belong to `prometeu-studio-ui-javafx`.
2. The JavaFX adapter may organize reusable controls by shell, forms, banks, lifecycle, navigation, feedback, and inspection roles.
3. A control is admitted when it has an immediate Studio consumer; speculative mirroring of JavaFX is forbidden.
4. Shared controls must preserve theme, localization, and explicit visual-state behavior.
5. Controls that observe UI events must expose predictable attach/detach or subscribe/unsubscribe lifecycle behavior.
6. Visual controls must depend on neutral Studio API contracts, not core or provider implementations.
7. Domain rules, application orchestration, filesystem workflows, compiler/Packer/LSP/runtime calls, and Spring composition do not belong in the visual component layer.
## Module Role
## JavaFX Wrapping Boundary
`prometeu-studio-components` is:
The Studio may use raw JavaFX for trivial local composition. A reusable control should expose the Studio-facing API actually needed instead of cloning the complete upstream JavaFX surface.
- the authoritative Studio control layer;
- the home of the Studio visual dialect;
- 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.
Shared controls may include:
`prometeu-studio-components` is not:
- shell and action controls;
- workspace rails and hosts;
- form sections and action bars;
- list, tree, inspector, and dual-list surfaces;
- activity, progress, badges, headers, and feedback controls;
- lifecycle-managed visual primitives.
- a speculative generic framework;
- a full reimplementation of JavaFX;
- a dumping ground for unrelated non-visual infrastructure.
## Construction and Lifecycle
## Admission Policy
Controls, rows, dialogs, and views MUST NOT be Spring singletons by default. A Spring-managed JavaFX composition factory may create them with explicit constructor dependencies.
A control is admissible when it is needed by the current Studio UI work.
Controls that attach event subscriptions MUST release them when detached. UI-local events may coordinate selection, navigation, editing scope, attach/detach, and presentation refresh. Request/response application behavior MUST use injected Studio API services directly.
Rules:
## State Boundary
- 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.
Presentation-only view models, form drafts, selection state, and formatting helpers may live beside JavaFX controls when they do not determine domain outcomes.
## 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.
## Control Lifecycle Hooks
Studio controls may need to observe event buses or other external state.
Rules:
- the control layer must provide explicit subscribe and unsubscribe lifecycle methods that can be overridden when needed;
- the control layer should also provide `onAttached()` and `onDetached()` lifecycle hooks;
- `onAttached()` should call `subscribe()`;
- `onDetached()` should call `unsubscribe()`;
- controls that attach subscriptions must also define how those subscriptions are released;
- event-driven controls must not hide subscription lifecycle completely inside ad hoc local wiring.
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:
- 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-visual policies and workflows that determine asset validity, capacity, metadata, build, runtime, project, or semantic results MUST live behind `prometeu-studio-api` and be implemented by `prometeu-studio-core` or an explicit infrastructure adapter.
## Non-Goals
- 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
- creating a standalone `prometeu-studio-components` Gradle module;
- wrapping the full JavaFX API;
- storing workspace business logic in controls;
- using Spring as a registry for each visual object;
- defining components for a future web UI.
## Exit Criteria
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.
This specification is satisfied when reusable JavaFX controls have clear visual ownership, explicit lifecycle behavior, neutral injected dependencies, and no application or provider implementation responsibilities.