Files
prometeu-studio/docs/specs/studio/13. JavaFX 2 Foundation Specification.md
T
bquarkz 71fb80efc3
Test / Tests and coverage occurred while executing withChecks step.
Intrepid/Prometeu/Studio/pipeline/head There was a failure building this commit
feat(studio): ship JavaFX 2 Play and delegate integration tooling
Launch the JavaFX 2 project shell on Java 25 with an interactive viewport,
managed Play lifecycle and project mutation guards. Preserve headless/MCP and
save compatibility, and qualify exact runtime executable bundles.
Separate unit JaCoCo gates from opt-in integration suites and use the internal
Pong fixture for the headless visual pilot.
Move maintenance and native conformance tools into tooling; retain the VS Code
extension and update current navigation links.

Validation: tooling make verify passed, including 1064 Studio unit tests,
JaCoCo thresholds and 22 headless integration tests.
2026-11-19 17:32:03 +00:00

66 lines
5.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# JavaFX 2 Foundation Specification
Status: Implemented foundation and default product frontend. Owner: `studio`.
## Scope and precedence
This document governs `prometeu-studio-ui-javafx-2`, an independent replacement frontend foundation. It defines the minimal shell, presentation components, themes, localization and typography. It does not redefine Studio API/Core, MCP, asset banks or runtime contracts.
The normal application now uses this frontend, with project/Play integration owned
by the [Integrated Play Specification](14.%20Integrated%20Play%20Specification.md).
The previous module is retained for consultation and adapter qualification.
Specifications 1–4 describe its shell/components/workspaces; they are not a visual
template for JavaFX 2. Later capabilities must extend the foundation through their
own explicit contracts.
## Shell
The standalone foundation launch MUST show a native-decorated window with Studio
identity, presentation selectors and an empty working area. The product mounts its
chooser/Play view there. Minimum outer size is 680×480; the foundation initial scene
is 1200×800, and the integrated product starts at 1200×850. Toolbar content MUST
wrap/reflow instead of requiring horizontal scrolling at the minimum width.
The shell component and standalone demonstrations MUST NOT initialize a project,
backend graph, runtime or agent. Product services are injected into a separate
coordinator by the app. There MUST be no fictitious editor tabs or domain panels.
The component gallery is a separate developer launch, not a product workspace.
## Presentation ownership
An `AppearanceContext` owns presentation state and subscriptions for one window and MUST be closed when that window is hidden. A closed context MUST NOT accept updates. Reopening MUST construct a new context. Components MUST retain normal JavaFX semantics for keyboard, focus, editing and accessibility, while exposing Studio appearance and small APIs.
Reusable families are text/title, decorative pixel icon, button, toggle, text field, non-editable selector, panel and message/progress feedback. Error appearance MUST have explanatory text. Text meaning MUST NOT depend on color alone. Custom geometry MUST NOT replace native interaction with a rasterized whole-window surface.
## Themes and geometry
The dark and light themes MUST provide matching semantic color tokens for background/workspace/surface/field, text/muted text, border, highlight/shadow, accent/on-accent, focus and error. Shared state styles MUST use those tokens. Theme changes MUST update active controls and selector popups in place without losing entered text.
Stepped corners and layered relief are the foundation's visual direction. Region outlines MUST be recomputed at actual layout dimensions so corner steps do not grow with panel width. Main text MUST remain vector-rendered and independently scalable. Palette and geometry refinements MUST preserve legibility, interaction and the agreed identity.
Normal text contrast targets are at least 4.5:1, large text 3:1, and necessary control/focus indicators 3:1. These are design/verification references, not an accessibility certification.
## Fonts and configuration
Departure Mono MUST be the default interior family; Roboto Mono MUST be available locally as an alternative. Both MUST ship with full SIL OFL 1.1 copyright and license notices. Loading MUST NOT require network access or preinstalled fonts. Font failure MUST diagnose and use a readable fallback.
Family and text scale MUST be configurable through presentation settings, not hardcoded in consumers. Supported text scale is 75–200%, default 100%. The developer gallery exposes these choices and comparable editable text. This contract does not require a full preferences window or system-font manager. Native window decoration remains platform-owned.
## Localization and persistence
The UI MUST support pt-BR and English, including runtime labels, accessible names and feedback. English is the fallback bundle. A missing translation MUST diagnose and fall back; an unknown key MUST remain identifiable as `[key]`. Bundles MUST have matching key sets in verification. Formatting MUST use the active locale. Changing locale MUST preserve user-authored text.
First launch MUST select dark, Departure Mono and 100% scale. A supported system locale selects pt-BR; otherwise English. Explicit choices MUST restore without a game project. Invalid individual preference values MUST fall back independently. Persistence MUST remain local presentation state, execute outside the FX thread and flush the latest selection on orderly close. It MUST NOT migrate or mutate the previous frontend's project-local state.
## Verification and non-goals
The foundation MUST have display-free tests of its own locale/preferences/resources/contracts and opt-in real desktop qualification. Desktop checks MUST identify environment/output scale, include normal/minimum sizes and inspect both themes, locales and fonts. Tests MUST exercise active popup appearance, focus/Tab, clipboard, state retention and close/reopen. Performance evidence MUST identify the measured operation; a CSS/layout measurement MUST NOT be presented as total frame latency.
Initial qualification is on available macOS. Windows/Linux, assistive-technology walkthroughs and native IME composition require their own evidence. Logical scene snapshots MUST NOT be presented as proof of physical pixel alignment at every HiDPI scale.
Project navigation and integrated Play are specified separately by specification
14. Document host, free docking, ACP, asset workflows, code/LSP editor, scene/entity
authoring, pixels/audio editing and shipping remain outside this foundation
contract. Backend integrations MUST use existing application services; domain logic
MUST NOT be duplicated here.