Files
prometeu-studio/prometeu-studio-ui-javafx-2/README.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

76 lines
6.5 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.
# Studio JavaFX 2 foundation
This frontend provides the Studio presentation foundation, project chooser and
integrated Play view used by the normal `prometeu-app` entry point. It consumes
neutral Studio API services and has no dependency on the previous frontend, Core,
concrete runtime/provider adapters or MCP. The standalone shell/gallery remain
independent developer demonstrations without a project/backend.
Requires Java 25; Gradle selects Java 25 and JavaFX 23.0.2 for the module.
From the Studio repository:
```sh
./gradlew :prometeu-studio-ui-javafx-2:run
./gradlew :prometeu-studio-ui-javafx-2:gallery
```
The standalone shell contains identity, presentation selectors and an empty central
area. The application mounts its chooser/Play view in that shell. The **separate
development gallery** demonstrates components, validation, progress, both fonts and
configurable text scale. Gallery actions operate on sample text only.
```sh
./gradlew :prometeu-studio-ui-javafx-2:test
./gradlew :prometeu-studio-ui-javafx-2:desktopTest
./gradlew :prometeu-studio-ui-javafx-2:installDist
```
`desktopTest` requires a desktop session and opens temporary windows. It exercises actual JavaFX behavior and writes PNG captures with environment metadata under `build/desktop-captures`. Normal unit tests do not require a display. Clipboard testing replaces clipboard content with a test string. Preference tests use an isolated disposable node rather than application preferences.
The generated launcher is `build/install/prometeu-studio-ui-javafx-2/bin/prometeu-studio-ui-javafx-2`; pass `--gallery` to open the gallery. This development distribution uses an available Java installation, unlike the existing product installation's bundled runtime.
## Components and ownership
`AppearanceContext` belongs to one window. Construct it with initial `PresentationSettings`, loaded `Messages` and `FontResources`, and a persistence consumer. Attach it to the window root. Views own their children; the context owns their presentation subscriptions and removes them on `close()`. Do not reuse a closed context. Settings updates and composition run on the FX thread.
| Component | Contract |
| --- | --- |
| `StudioText` | Localized label with wrapping and optional title role in the visual hierarchy. `setLabelFor` associates input labels. |
| `StudioIcon` | Decorative vector pixel mark; put meaningful names on the action or container that uses it. |
| `StudioButton` | Native Button actions, focus/default-button APIs and enabled/armed behavior; optional primary appearance. |
| `StudioToggle` | Native ToggleButton selection and accessibility. |
| `StudioTextField` | Native editing, clipboard and IME path; `setError` controls appearance and must accompany explanatory feedback. |
| `StudioSelect<T>` | Native, non-editable ComboBox with localized cells, context-owned selection connection and themed popup. |
| `StudioPanel` | Resizable content frame with stepped vector geometry and layered bevel colors. |
| `StudioFeedback` | Localized parameterized message/error and optional determinate progress. |
Fields retain their contents when theme, locale, typeface or scale changes. Geometry follows each Region's actual layout size, rather than stretching a low-resolution image. JavaFX native controls and skins retain interaction semantics; there is no all-Canvas widget toolkit.
Semantic theme colors are in `styles/dark.css` and `styles/light.css`. Component geometry/state styles are in `styles/components.css`. `AppearanceContext` sets inherited family and size from the centralized presentation settings. There is no third-party control library in this slice.
## Preferences and localization
`UserSettingsStore` uses the Java Preferences node `p/studio/ui/javafx2` for theme, language, bundled typeface and text scale (75–200%). Startup uses dark, Departure Mono and 100%; a supported system locale chooses pt-BR, otherwise English. Invalid individual values fall back independently with diagnostics.
Load preferences and font/bundle resources before composing views. `SettingsPersistence` debounces writes on its worker, flushes the last choice asynchronously on close, and shuts the worker down. It never writes from the FX thread. No project state or previous frontend preferences are migrated.
All interface messages live in UTF-8 `messages_en.properties` and `messages_pt_BR.properties`. Missing translations diagnose and fall back to English; an absent English key displays `[key]`. Bundle parity is checked by unit tests. Dynamic feedback retains its key/arguments and is reformatted on locale changes; user-authored text retains its value.
## Fonts and licenses
- **Departure Mono 1.500**: default, monospaced pixel design. Source: `rektdeckard/departure-mono`, revision `75152a3f1e6dacdd248a6c397c97dbf27e33eea0`.
- **Roboto Mono Regular**: bundled alternative. Source: `googlefonts/RobotoMono`, revision `7bf0b33178844cc7d0c9915b746ece1be7f46bea`.
Both font files load from local classpath resources. Their full copyright/SIL OFL 1.1 notices are under `src/main/resources/p/studio/ui/javafx2/fonts/*-LICENSE.txt`, inside the application jar and in the installed distribution's `licenses/` directory. No system font installation or network request is required. A failed font load diagnoses and uses Monospaced; JavaFX supplies fallback glyph rendering.
The default 16.5 logical pixel size was checked on a macOS display reporting 2× output scale. Departure's 11 px grid does not guarantee pixel-perfect rendering at every fractional output/text scale. Alternative family/scale are presentation choices rather than fixed assumptions inside views. Future editors may choose their own documented text roles.
## Validation boundaries
Unit tests verify preference codecs/storage, asynchronous final persistence, locale fallback and bundle parity, font/license packaging and semantic contrast pairs. Desktop qualification exercises actual selectors/popups, dynamic feedback, clipboard, Tab traversal, input retention, both themes/locales/fonts, minimum width, repeated appearance changes and reopening with new contexts.
The initial desktop target is macOS. Snapshot PNGs are logical scene captures; metadata records actual output scale, but these captures do not themselves prove physical-pixel sharpness at every scale. Windows/Linux, a screen-reader walkthrough and native multi-step IME input remain environment-specific manual qualification. Preserving JavaFX semantics is not a claim that those checks were completed.
No project navigation, editor host, ACP, domain workspace, asset authoring, build/run/debug or shipping feature is implemented here.