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.
This commit is contained in:
@@ -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
|
||||
|
||||
+1
-1
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user