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:
@@ -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.
|
||||
Reference in New Issue
Block a user