# 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 a separate compact project launcher with known projects and actions to add an existing `prometeu.json`, open, forget and create a project. Opening MUST hide the launcher and present a separate loading shield; the project window MUST appear only after preparation and the minimum shield duration. A project MUST be closed before another can open. Closing returns to the launcher after execution and session cleanup. Startup MUST NOT automatically restore the previous project. Project-window geometry MUST be restored per project through the neutral window-state port. 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. 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. ## Project selection, creation and loading The launcher MUST reuse the persisted known-project catalogue, ordered by name, and display name, version, language, stdlib and path. Open and Forget MUST require a selection; Open MUST also work by double click or Enter. Adding a manifest MUST validate, remember and select it without automatically opening. Forget MUST remove only the catalogue reference, never files. Cancelled file selection MUST leave the catalogue unchanged. Empty and failed states MUST provide visible feedback. The launcher MUST contain project selection/management and identity only, without global language, theme, typeface or scale controls. It MUST inherit the existing presentation settings; those controls belong to the project window. Closing the launcher MUST exit Studio without presenting an empty project/foundation shell. The internal project frame MUST grow and shrink with the available launcher width and height, allocating additional height to the project list. Smaller viewports or larger text scales MUST retain scrolling so project commands remain accessible. The creation wizard MUST use UI2 components and preserve five steps: name, language/stdlib/source root, indentation/runtime details, parent location and confirmation. Options MUST come from `ProjectLanguageCatalog`, with Game as the target. Back MUST preserve input. Cancel MUST return to selection; creation and persistence MUST execute off the FX thread. Successful creation MUST remember and open the project through the common loading flow. A failed opening after creation MUST explain that the project exists and can be opened again. Partial creation MUST retain diagnostics and identify its location without deleting files as an automatic rollback. The catalogue's existing machine-local MCP configuration preparation remains available; it does not start an AI client or LSP. The opening coordinator MUST expose real steps for catalogue validation, `openForPlay()` session acquisition, known-project persistence and FX view composition. The sequence MUST accommodate future steps without enabling them in this slice. It MUST NOT initialize the previous workspace initializer merely to provide the loading mechanism. Unmeasurable work MUST use indeterminate progress; time-driven percentages MUST NOT stand in for actual progress. The shield MUST identify Studio, its version, the project and current phase. It MUST remain visible for at least one second, measured with a monotonic clock from presentation, in parallel with preparation. The project is ready when validation, session acquisition, required persistence and view composition succeed. If ready before the minimum, show completion while awaiting the remainder; if slower, there MUST be no additional full-second delay. This is independent of native runtime READY and first-frame delivery, which belong to Play. Each opening attempt MUST own its pending session, timer and callbacks until handoff or cleanup. Failures at every step, including executor admission and FX composition, MUST release acquired resources before enabling another opening and return to selection with a visible error after the minimum. Cleanup failure MUST retain recovery feedback and block new openings until explicitly retried cleanup succeeds. There MUST be no automatic opening retry. Application exit MUST cancel the cosmetic delay, prevent late presentation and still release late-arriving sessions; cancelling a future is not proof of resource release. IO, session teardown and operation waits MUST stay off the FX thread. Window transitions MUST NOT accidentally exit JavaFX while all stages are hidden. Launcher, wizard, shield and project MUST share UI2 theme, locale, typeface and scale, with scrolling as needed to keep commands accessible. The launcher MUST request application exit when closed; closing the project window MUST request project closure and return to selection under the existing Stop/save rules. Timers, views and appearance subscriptions MUST be disposed with their owners. ## 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 640×360 game occupies 640×360 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. The only native machine output is 640×360 RGBA8888 at 60 Hz. The new JavaFX 2 viewport obtains dimensions from complete runtime publications; it MUST NOT keep an independent fallback resolution. Leaving the image cancels an active contact; dragging back while still held MUST NOT recapture without a new press inside. Zoom and scroll continue to operate in JavaFX logical coordinates, with scene transforms accounting for host display scaling. These frontend changes apply to the new UI only; the old UI is outside the current graphics migration scope. ## 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. `studioProjectsDesktopTest` qualifies real launcher/wizard/shield/project window transitions with isolated projects/preferences and filesystem catalogue services. It does not require or qualify native execution. Its snapshots include environment metadata under `prometeu-app/build/projects-desktop-captures`. Unit tests with a controlled clock cover fast/slow loading, failure, cleanup retry and late results. 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 [development guide](../../development.md#native-runtime-installation-and-qualification). 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.