# JavaFX 2 foundation — implementation and qualification

Date: 2026-11-17. Owner: Studio. Decision: DEC-0001, explicitly accepted by Nilton. Plan: PLN-0001.

## Delivered scope

Implemented `studio/prometeu-studio-ui-javafx-2`, with its own launcher, presentation context, native-control components, responsive shell toolbar and scalable stepped/beveled vector outlines. The default product shell contains identity, theme/language selectors and an empty central frame. The developer gallery is a separate launch and supplies font/scale choices, validation/progress states and editable text compared in Departure Mono and Roboto Mono.

Dark/light, pt-BR/English, inherited typography, localized feedback and already-open selector popups update in place. Small user preferences preserve appearance choices through an off-FX-thread writer. Local font binaries and complete SIL OFL notices are bundled in the jar and installed distribution. No game project, backend or agent is required.

Only module inclusion, the new module and its docs/spec index were changed in Studio. Existing frontend implementation/launcher and backend are untouched. Runtime status was checked clean. No commits were created. The root AIE Studio edit flag was enabled under the explicit implementation authorization; runtime remains read-only.

## Actual commands and outcomes

Run from `studio`:

```sh
./gradlew :prometeu-studio-ui-javafx-2:test :prometeu-studio-ui-javafx-2:desktopTest :prometeu-studio-ui-javafx-2:installDist :prometeu-studio-ui-javafx:compileJava --console=plain
./gradlew :prometeu-studio-ui-javafx-2:run --console=plain
```

- Integrated gate: BUILD SUCCESSFUL. Full final output: ART-0010 and `wrk0013-final-checks.log`.
- Actual independent application launch: BUILD SUCCESSFUL after the native window run; `wrk0013-shell-launch.log`. No project/runtime startup was requested or wired.
- Display-free unit tests: 8 passed, 0 failed/error (6 presentation/preference cases, 2 resource/contrast cases).
- Real JavaFX desktop scenario: 1 passed, 0 failed/error. It traverses 8 theme × language × font combinations, localization of an already-open popup, Tab from theme to language, native clipboard edit/paste, validation and retained input, repeated CSS/layout updates, resizing and 3 independent reopenings.
- Installed `licenses/`: both complete font notices confirmed.
- `git diff --check` passed. This is not a full backend/compiler/runtime regression run; no such implementation changed.

## Environment and measurements

macOS 27.2; test JVM Java 21.0.4; JavaFX 23.0.2; reported output scale 2×2. The actual environment and presentation settings accompany every PNG in a `.txt` file.

Normal scene: 1200×800. Minimum outer window: 680×480, with 680×452 scene content in this native-decorated environment. Captures wait for JavaFX pulses after resizing, then record image dimensions and metadata together. Assertions check image/scene dimensions, minimum-width gallery overflow and remaining central space in the minimum product shell.

Final measured average for 20 in-place appearance changes followed by CSS/layout: **19.21 ms**, below the plan's 250 ms average budget. This measures that operation, not total input latency or an FPS guarantee.

Snapshots are logical scene captures, not OS screenshots of physical pixels. Running on a real 2× display verifies that environment, but does not prove pixel-perfect rendering at all fractional scales. Both default and changed typography/scale paths were exercised.

## Visual inspection and corrections

Inspected actual PNGs for the dark/default shell, minimum shell/gallery, dark Departure, light Departure/Roboto and the font comparison area. Corrected horizontal overflow in the narrow toolbar, then used a responsive toolbar to preserve a compact single row at usual widths. Captures now match the resized scene dimensions. Corrected low-contrast golden headings on light surfaces to a theme-specific violet role; selector arrows use text color. Progress has a visible localized percentage and a contrasting theme-specific fill. Default empty shell and gallery are kept distinct.

Unit verification compares semantic theme key sets and required text/background, heading, focus/border, error, accent and progress contrast pairs. Disabled controls retain deliberate disabled appearance. These checks do not constitute accessibility certification or exhaustive pixel-level auditing.

## DEC acceptance coverage

| Criterion | Evidence |
| --- | --- |
| Independent module, old frontend preserved | Final compilation/install gate, standalone run, module build file and source manifest. |
| Component families and empty product shell | `shell-dark-default.png`, `shell-minimum-680x480.png`, gallery matrix, public component source/API guide. |
| Theme/locale switching, fallback, preferences | Presentation tests; real state retention, dynamic feedback and open-popup checks. |
| Departure default, Roboto alternative, configuration/licenses | Resource tests, font gallery, installed license directory, font samples and runtime font-family assertions. |
| Native behavior, focus, accessible semantics/contrast | Clipboard, Tab/focus, native control paths, localized labels/error text and contrast tests; manual qualification limits below. |
| Actual macOS visual qualification | PNGs with matching metadata and dimension assertions in ART-0011. |
| Lifecycle/responsiveness | Context close/reopen assertions, independent persistence worker test, 20-update measurement. |
| No domain/backend/runtime expansion | Source SHA-256 manifest and checked Studio/runtime diff scope. |

## Remaining environment-specific qualification

Windows/Linux, a screen-reader walkthrough and multi-step native IME composition were not exercised. Controls preserve the native JavaFX semantics/path; that is not evidence of completed platform/assistive/IME qualification. No guarantee is made for fractional HiDPI pixel sharpness, arbitrary system fonts, full docking or future editor/ACP lifecycle.

The build emitted the existing buildSrc JDK 25/Kotlin JVM target advisory; the new module uses Java 21. The desktop harness emitted JavaFX's unnamed-module warning; tests and window launch succeeded. Neither warning was represented as a functional failure or silently suppressed.

## Durable integration

- `studio/prometeu-studio-ui-javafx-2/README.md`: commands, API/ownership, settings/i18n, licenses and qualification boundaries.
- `studio/docs/specs/studio/13. JavaFX 2 Foundation Specification.md`: implemented foundation contract.
- `studio/docs/specs/studio/README.md`: explicit coexistence with the existing frontend corpus.
- ART-0011: immutable ZIP of final PNGs, metadata, JUnit XML, build/launch logs and source hashes. The source manifest excludes build products and captures the final source files used by the final gate.

No ACP, Assets, code/scene editor, entity model, pixel/audio editor, execution/debug or Shipper feature was implemented.
