feat(studio): ship JavaFX 2 Play and delegate integration tooling
Test / Tests and coverage occurred while executing withChecks step.
Intrepid/Prometeu/Studio/pipeline/head There was a failure building this commit

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.
This commit is contained in:
2026-11-19 17:32:03 +00:00
parent 1e17fc4d67
commit 71fb80efc3
163 changed files with 5929 additions and 4950 deletions
+2 -1
View File
@@ -29,7 +29,8 @@ See [repository instructions](../../AGENTS.md).
## Navigation verification
Run `python3 tools/documentation/verify.py` from the repository root to check local
Run `../tooling/.venv/bin/python ../tooling/scripts/documentation/verify.py --root .`
from the Studio repository root to check local
links and anchors. Pass `--runtime ../runtime` to also check provider references
against an available read-only runtime checkout. The byte-exact architecture/ISA
mirrors retain the link context of their runtime originals; the checker resolves
@@ -126,4 +126,4 @@ remain separately pending; local results and cross-compilation do not qualify th
- [Common runtime catalog support](../../compiler/24.%20Runtime%20Catalog%20Support%20Specification.md)
- [Runtime numeric contract](../../../../../runtime/docs/specs/runtime/02d-gameplay-math-and-numeric-semantics.md)
- [Production conformance harness](../../../../tools/pbx-conformance/README.md)
- [Production conformance harness](../../../../../tooling/scripts/pbx-conformance/README.md)
@@ -903,4 +903,4 @@ Sibling-file callable/global/service surfaces MUST use declaration/signature-lev
Nominal receiver/method binding MUST retain the originating declaration and lexical scope, including aliases and synthesized receiver types. A private homonym introduced through a dependency cannot replace a local declaration or create an ambiguous executable target merely by sharing spelling. Transient IDs and PBX byte equality across builds are not nominal-identity requirements.
Conformance: PbsProductionLoweringRegressionTest and PbsNominalOwnerRegressionTest cover the frozen 28-case corpus, contextual overloads, privacy by signature, shared storage/singletons and order-sensitive effects. The maintained source-to-guest matrix is tools/pbs-production-corpus/run.py.
Conformance: PbsProductionLoweringRegressionTest and PbsNominalOwnerRegressionTest cover the frozen 28-case corpus, contextual overloads, privacy by signature, shared storage/singletons and order-sensitive effects. The maintained source-to-guest matrix is ../tooling/scripts/pbs-production-corpus/run.py.
@@ -187,8 +187,8 @@ frontend syntax and lowering remain consumer-owned.
| Stable declarations, nominal identity, structural deduplication and cycles | LinkedRegistryTest; IRBackendExecutableContractTest | pass | Common API and linking |
| Complete typed signatures, captures, roles and implementations | PbxRegistryConformanceTest; TypedCommonPipelineTest | pass | Common IR through emission |
| Exact PBX mandatory tables and multi-slot signatures | Independent 194-byte oracle; fixed vec2 function bytes | pass | Wire format, not a self round-trip |
| Runtime final admission and execution | tools/pbx-conformance/run.py | pass | Closure, trait, array, Dynamic, intrinsic, roles, joins, native binding; vec2 load-only |
| Invalid structures, references, code and resource refusal | tools/pbx-conformance/main.rs mutation corpus | pass | Production loader, default/lowered limits |
| Runtime final admission and execution | ../tooling/scripts/pbx-conformance/run.py | pass | Closure, trait, array, Dynamic, intrinsic, roles, joins, native binding; vec2 load-only |
| Invalid structures, references, code and resource refusal | ../tooling/scripts/pbx-conformance/main.rs mutation corpus | pass | Production loader, default/lowered limits |
| Structured initialization and binding diagnostics | HeadlessProcessSessionTest; observed runtime JSON fixtures | pass | Preserves full payload through MCP, including null outer PC |
| Published schema covers current runtime reasons | Actual LifecycleRole/NonFiniteValue payloads against runtime schema | partial | Runtime enum/schema mismatch recorded in AGD75; no payload rewriting |
| PBS migration and integrated delivery | AGD75 and consumer tickets | partial | Existing PBS suite passing is not complete executable lowering evidence |
@@ -196,7 +196,7 @@ Run the focused common tests, then the production harness:
```sh
./gradlew :prometeu-compiler:prometeu-build-pipeline:test --tests '*LinkedRegistryTest' --tests '*PbxRegistryConformanceTest' --tests '*TypedCommonPipelineTest'
python3 tools/pbx-conformance/run.py --runtime ../runtime
../tooling/.venv/bin/python ../tooling/scripts/pbx-conformance/run.py --studio . --runtime ../runtime
```
The Java tests write `build/registry-conformance` inside the build-pipeline
@@ -6,6 +6,11 @@ Purpose: Define the normative shell structure of the Studio UI.
## Authority and Precedence
This document describes the retained previous frontend. The normal application's
replacement shell/project flow is governed by specifications
[13](13.%20JavaFX%202%20Foundation%20Specification.md) and
[14](14.%20Integrated%20Play%20Specification.md), which take precedence for UI2.
This specification consolidates the accepted Studio shell decision into normative form. DEC-0060 adds DEV and project-scoped automation authority; its detailed behavior is owned by the [DEV and Automation Specification](10.%20DEV%20and%20Automation%20Specification.md).
## Normative Inputs
@@ -1,18 +1,30 @@
# JavaFX 2 Foundation Specification
Status: Implemented foundation. Owner: `studio`.
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 existing frontend and its launcher remain available. Specifications 1–4 continue to describe that frontend's current shell/components/workspaces; they are not a visual or architectural template for JavaFX 2. Later capabilities must extend the new foundation through their own explicit 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 default launch MUST show a native-decorated window with Studio identity, theme/language selectors and an empty central working area. Minimum outer window size is 680×480; the initial scene is 1200×800. Toolbar content MUST wrap/reflow instead of requiring horizontal scrolling at the supported minimum width.
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 MUST NOT initialize a game project, backend service graph, runtime or agent. It MUST NOT contain fictitious editor tabs, operations or domain panels. The component gallery is a separate developer launch, not a product workspace.
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
@@ -46,4 +58,8 @@ The foundation MUST have display-free tests of its own locale/preferences/resour
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, document host, free docking, ACP, asset workflows, code/LSP editor, scene/entity authoring, pixels/audio editing and Shipper are outside this foundation contract. Backend integrations MUST use existing application services when those features are introduced; domain logic MUST NOT be duplicated here.
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.
@@ -0,0 +1,149 @@
# Integrated Play Specification
Status: Implemented first interactive slice. Owner: `studio`.
## Product and scope
The normal `prometeu-app` launcher and managed installation MUST use
`prometeu-studio-ui-javafx-2`. The standalone foundation shell and gallery remain
development entry points. The previous frontend is retained for existing adapter
qualification; its workspaces are not mounted in the new product.
Startup MUST show known projects and an action to open an existing project
directory. A project MUST be closed before another can open. Closing returns to
the chooser. Startup MUST NOT automatically restore the previous project.
This slice exposes Play, Pause, Resume, Stop, a game viewport, and bounded logs.
It MUST NOT initialize an AI client or editor/LSP infrastructure when opening for
Play. Existing headless, MCP, evidence, tests and agent contracts remain available
through their existing entry points and services. Their preservation takes
precedence over interactive convenience.
Project creation UI, editors, workspaces, AI prompts, tuning during Play,
breakpoints, hot reload, PMC builds and distribution/export are outside this
slice. Future packaging belongs in Studio as a separate action; Play MUST NOT
implicitly package a PMC or a distributable runtime.
## Preparation, process and authority
Play MUST reuse the compiler/Packer/Shipper preparation pipeline to produce the
cartridge directory. Managed asset capacity, input revision and artifact identity
guards MUST remain enforced against the selected runtime installation. A changed
runtime requires a newly qualified capacity profile; the consumer MUST NOT infer
equivalence from its version string or bypass the guard.
Core owns execution orchestration and an exclusive project lease. The lease MUST
cover preparation, connection, running, paused and stopping phases until actual
preparation termination and native process/worker cleanup. Other project writes
MUST be rejected at service admission, including writes initiated outside the UI.
Preparation by the execution owner has a scoped admission path; it MUST NOT grant
an arbitrary caller permission to edit. The frontend MUST disable configuration
through the same ownership interval. A state label alone MUST NOT release ownership.
The application adapter MUST start a direct, owned `prometeu-runtime` child in
interactive `--studio` mode, without a native game window. This does not compile
Rust for the JVM or load native VM code into Java. Wire and process mechanics
belong to `prometeu-app`, behind neutral API/Core ports. UI2 MUST depend only on
Studio API and its presentation toolkit, never Core, concrete providers or the
previous frontend.
Process/control/video/log workers MUST use a per-connection executor independent
of the bounded operation pool. FX code MUST NOT wait for compilation, sockets,
native process exit or worker joins. Native process completion and worker cleanup
are prerequisites for returning project authority. Failed/stale attempts MUST NOT
change a replacement execution's lifecycle.
## Lifecycle and focus
Play prepares, connects, waits for READY, and issues START. Pause freezes logical
game advancement and audio without replacing the machine. Resume continues that
same session. Pause requested during preparation/connection MUST arm a paused
startup; START alone MUST NOT undo it. Stop cancels/waits for preparation or asks
the native host to stop and confirms teardown.
Minimizing or switching focus to another application MUST pause. Returning focus
or restoring the window MUST NOT automatically resume. Windows/popups owned by
Studio MUST be treated as part of Studio. A focus loss during an asynchronous
Resume MUST still result in pause once the runtime becomes running.
Closing a project or Studio MUST stop its game before closing the project session.
A normal Stop or close that is refused by save protection MUST retain the paused
session and its lease, explain the refusal in logs, and allow manual Resume.
Required IPC failure MUST close channels, terminate the owned native process,
retain bounded diagnostics and restore controls after cleanup. There MUST be no
automatic reconnect/restart, process-name-based termination or loss of headless
capabilities as a recovery mechanism. A new Play requires a new explicit action.
## Save media
For a game declaring save slots, the human MUST select an existing development
save image or explicitly select a disposable session. The frontend MUST NOT
silently create, overwrite or discard persistent media. The disposable choice is
per Play and MUST NOT be silently restored as a persistent project preference.
Existing agent/indentation setup fields MUST be preserved when runtime/save paths
are saved.
Normal Stop MUST wait for pending IO or refuse if it cannot finish safely, and
MUST refuse uncommitted persistent data. Disposable Stop may discard only because
that session was explicitly selected. IPC failure is the bounded forced-teardown
exception; it MUST be reported rather than represented as a successful save.
## Presentation and input
The binary [Studio Play protocol](../../../../runtime/docs/specs/runtime/11b-studio-play-protocol.md)
uses independent control/input and video channels, bounded messages, session and
epoch correlation, and one video credit returned after full reception. The native
tick MUST NOT wait for FX or socket writes. Unsent presentation frames may be
replaced by the latest complete publication; partial wire messages MUST finish or
fail. Control messages MUST NOT be dropped as a presentation optimization.
Java reception converts RGBA8 to premultiplied BGRA on an IO worker. Three CPU
buffers have explicit free, receiving, pending and presentation ownership, with
at most one presentation lease. A leased image MUST remain stable until close.
FX polls the latest complete frame on a pulse, copies it to an FX-owned
`WritableImage`, and releases the lease. Reception MUST NOT enqueue one FX task
per frame. Logs and frontend projections MUST remain bounded.
Zoom choices MUST be x1, x2 and x4 with nearest-neighbor presentation. At x1 a
480×270 game occupies 480×270 logical pixels, respecting OS scale; it does not mean
one physical display pixel. Oversized images MUST retain zoom and scroll. The UI
MUST NOT silently fit the image or change zoom.
Input MUST invert the image's scene transform and selected logical zoom. Touch
outside the image MUST release/reject touch rather than clamp to an edge. Keyboard
input belongs to the focused viewport, with modifiers reserved for application
shortcuts. Pad keys are arrows, A/D/W/S for A/B/X/Y, Q/E for L/R, Z for Start and
Shift for Select. Focus loss and lifecycle changes MUST neutralize held input;
native epochs reject input from older execution phases.
## Verification and limits
The product baseline is Java 25, retaining JavaFX 23.0.2. The bundled image uses an
explicit JDK `jmods` module path for jlink. Build logic may target Java 21 bytecode;
that is not the Studio application baseline.
Qualification MUST cover actual installed startup, existing-game image/input,
pause/resume and focus, project close, dirty-save refusal and cross-mode readback,
broken channels, slow presentation/receiver, bounded buffers, repeated sessions,
and preserved headless/MCP/evidence/tests. Codec fixtures alone are insufficient.
`studioPlayDesktopTest` is an opt-in desktop gate. `-PstudioPlayStress=true` adds a
30-second idle-host measurement, deliberate FX suspension and twenty cycles.
Receive-to-copy latency uses `System.nanoTime` in the same JVM; it MUST NOT be
called end-to-end input latency or physical scanout latency. CPU/heap observations
and hardware/OS/build flavor MUST accompany performance claims. A heap-used sample
does not prove retained-memory bounds; ownership and resource tests do.
Executed functional qualification includes macOS ARM64 with Java 25 and the release
umbrella distribution produced by `runtime/scripts/local-dist.sh`, including real
Pong Play and the deterministic headless process. Capacity qualification identifies
the dispatcher and both native backends as one exact bundle; multiple releases may
share an unchanged dispatcher. The explicit qualification command is documented in
the [Studio README](../../../README.md).
Earlier presentation performance measurements used debug native binaries.
Windows/Linux, release performance, physical HiDPI pixel alignment, and human
listening/IME/accessibility walkthroughs require separate evidence. Diagnostic runs
and failures remain in Work evidence; a later passing run does not establish their
unobserved cause.
@@ -20,6 +20,13 @@ Define the normative contract for Studio project-local persistence under `.studi
## Authority and Precedence
The new Play frontend preserves stored workspace state but does not mount or
restore previous workspaces and never automatically opens the last project.
Runtime/save path updates preserve indentation and agent intent. Presentation
preferences remain separate from `.studio/state.json`; disposable save selection
is an explicit per-Play choice. See specification
[14](14.%20Integrated%20Play%20Specification.md).
This specification implements the accepted decision for project-local Studio state under `.studio/`.
It extends:
@@ -9,6 +9,7 @@ Active
- `prometeu-studio-api`
- `prometeu-studio-core`
- `prometeu-studio-ui-javafx`
- `prometeu-studio-ui-javafx-2`
- `prometeu-app`
- integrations with compiler, Packer, LSP, and the runtime
@@ -47,6 +48,15 @@ JavaFX is the human adapter; DEV is its authorization and observation workspace.
Gradle is the physical classpath boundary. Spring Modulith verifies the functional modules rooted exclusively at `p.studio.core`; it does not replace the Gradle modules.
The normal app composes UI2 through neutral API services; the previous adapter
remains for compatibility qualification. Interactive execution adds neutral
pause/resume, input, stable frame leases and ownership queries. Core owns exclusive
admission through preparation and confirmed teardown. Binary TCP framing, native
process ownership and IO workers belong to the app adapter, independently of the
deterministic headless gateway. `openForPlay` defers editor/agent infrastructure;
the existing session path and automation contracts remain. See specification
[14](14.%20Integrated%20Play%20Specification.md).
The legacy mixed `prometeu-studio` module and the static `p.studio.Container` service locator MUST NOT exist in the final architecture.
## API Neutrality
+7 -4
View File
@@ -4,15 +4,18 @@ Owner: `studio`. Canonical source: `docs/specs/studio`.
This directory contains the normative Studio specification set.
## JavaFX 2 foundation
## Default JavaFX 2 frontend
[`13. JavaFX 2 Foundation Specification.md`](13.%20JavaFX%202%20Foundation%20Specification.md)
defines the independent `prometeu-studio-ui-javafx-2` foundation and minimal shell.
defines the `prometeu-studio-ui-javafx-2` foundation and reusable shell.
Its [module guide](../../../prometeu-studio-ui-javafx-2/README.md) documents execution,
component ownership, themes, locales, bundled fonts and verification. The previous
frontend remains available; specifications 1–4 describe its existing behavior and
frontend is retained for adapter qualification; specifications 1–4 describe its behavior and
do not impose its visual structure on the new implementation. Backend contracts
remain shared and unchanged.
remain shared. The normal/installed app uses the new chooser and Play frontend;
[`14. Integrated Play Specification.md`](14.%20Integrated%20Play%20Specification.md)
owns project flow, execution authority, transport/presentation, input, saves and
qualification boundaries.
## Purpose
+1 -1
View File
@@ -43,7 +43,7 @@ architecture mirrors are synchronized or that all PBS facades are implemented.
Run the explicit source/exporter verification from the Studio root:
```sh
python3 tools/runtime-catalog/verify.py --runtime ../runtime
../tooling/.venv/bin/python ../tooling/scripts/runtime-catalog/verify.py --studio . --runtime ../runtime
```
This command requires a clean checkout of the recorded provider revision, compares