Files
prometeu-studio/docs/specs/studio/14. Integrated Play Specification.md
T
bquarkz 2d8f6436e4
Test / Tests and coverage
Intrepid/Prometeu/Studio/pipeline/head This commit looks good
feat(studio): refine Play workspace and project preferences (WRK-001D)
2026-11-22 15:45:09 +00:00

341 lines
21 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.
# 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. Launcher geometry and project-window geometry MUST
be stored independently through the neutral window-state port. Project keys are
normalized absolute project paths. Geometry MUST preserve normal position/size
separately from maximization, survive orderly application restart and leave the
title bar reachable when monitors change. Available secondary displays, including
negative coordinates, MUST be considered instead of clamping every window to the
primary display. Writes MUST be serialized, atomic and off the FX thread; orderly
close MUST flush pending snapshots. Transient native show/maximization events MUST
NOT overwrite the saved normal geometry. Legacy geometry remains readable.
This slice exposes a global Play/Stop button, a separate Pause/Resume toggle, a
Gameplay tab with the game viewport, and bounded logs. Execution belongs to the
project session, independently of tab selection or lifetime. The global toolbar
MUST remain above the tabs. Starting Play selects Gameplay. Pause selection,
accessible names and command availability MUST follow observed execution state,
including automatic pauses and failures. Stop MUST remain Stop until execution
ownership is actually relinquished, including when paused. Transitioning commands
MUST NOT be submitted repeatedly.
The top row MUST place the golden-square Studio mark and **Prometeu Studio** menu
on the left, followed by project navigation. The Play/Stop and Pause/Resume pair
MUST be anchored at the right padding, leaving the intervening space available
for navigation independently of status text. When navigation and the pair would
overlap, the pair MUST occupy a second row, also aligned right. Each command MUST
reserve enough width for all its
translated labels at the active typeface and text scale. State changes MUST NOT
move the pair or resize its slots. The pause toggle MUST visibly read **Resume**
when paused and **Pause** otherwise, consistently with its accessible name and
tooltip. Keyboard focus MUST remain visible within the control's drawing envelope.
A compact project-information header MUST sit below the top area. It contains
project identity and execution status, including transient/disposable status,
separate from command layout. A footer MUST remain at the bottom of the window,
with the same height as the header at the current text scale. It MUST display
information supplied by the selected tab; unregistered tabs MUST show no inherited
status. Gameplay supplies the effective scale or a waiting-for-image status.
Overflowing information MUST ellipsize without displacing commands. At small window
sizes or large text scales, content MUST remain scrollable while both information
strips remain outside the scrolling content.
The product workspace between header and footer MUST use a plain surface without
an additional decorative frame around the tabs. Its top and bottom margins MUST
be equal, initially 18 logical pixels, while retaining the horizontal inset and
filling the remaining space. This MUST preserve scrolling for constrained windows
and MUST NOT remove the active tab's gold outline around its own content. The
standalone foundation shell/gallery retains its decorative panel.
Tabs MUST retain native selection, focus and keyboard behavior and the inherited
Studio typeface. Tabs MUST use stepped upper corners and a flat base without the
lower bevel or bottom outline of a button. The selected tab MUST join the content
surface, with a gold accent on its top and sides. Semantic theme colors MUST retain
distinct selected, hovered, disabled and focused states. This slice MUST NOT add
placeholder editors or extra tabs.
The gold outline MUST continue from the active tab header around its entire content
area, joining the header's sides without drawing a line across the opening below
it. The outline MUST follow selection and layout, disappear for empty content and
remain outside hit testing and layout measurement. It MUST NOT obscure keyboard
focus or leave the previous tab's outline after selection/removal.
Gameplay MUST contain both the game surface/local scale controls and bounded logs,
with an adjustable horizontal divider between game above and logs below. The
initial division SHOULD prioritize the game at approximately 80/20. Both regions
MUST retain usable minimum sizes and scrolling when needed. The divider MUST follow
the Studio theme and indicate drag affordance. Header/footer and global execution
controls MUST remain outside that split. Adjusting it MUST NOT change execution
state or restart the runtime. The split is retained for the open view; it does not
introduce persisted project settings or a restoration contract across reopening.
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, identity and access to
Studio preferences, without permanently exposed language, theme, typeface or scale
selectors. It MUST inherit the existing presentation settings. Closing the
launcher MUST exit Studio without presenting an empty project/foundation shell.
Studio identity MUST appear in the Prometeu Studio menu with its icon; the project
chooser MUST NOT repeat that identity in a separate block below the menu. The
project-section title, catalogue and commands MUST remain visible.
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 chooser MUST use equal 18px outer margins and one 18px panel inset, with 18px
between title/list/actions and 12px between actions. Empty feedback MUST NOT reserve
space; visible feedback MUST align with the outer margins without doubled gaps.
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 use equal 18px outer margins, one 18px panel inset and 18px between content
groups. Content MUST be centered vertically when space permits, with scrolling for
constrained space or larger text. These refinements MUST preserve window sizing,
positioning and opening behavior. 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.
## Preferences and project configuration
Prometeu Studio > Preferences MUST open a separate dialog for theme, language, typeface,
UI text scale and the machine-local default runtime installation. Project >
Settings MUST open a separate dialog for the optional runtime override and save
media configuration. Project > Close project retains coordinated teardown.
Runtime and save fields MUST NOT be mounted permanently in Gameplay. Apply MUST
validate and publish settings off the FX thread; Cancel MUST leave stored choices
unchanged. Appearance forms use draft state until Apply. Execution configuration
MUST remain unavailable while execution ownership is held; appearance preferences
remain usable. Missing configuration MUST provide an action to open its settings.
Interactive Play MUST resolve the project override when present, otherwise the
Studio default. Inheritance MUST remain null in the persisted project setup; the
effective installation MUST be frozen in memory for both build capacity admission
and runtime launch. New global selections affect subsequent starts. An invalid
explicit override MUST fail visibly rather than silently select another runtime.
Existing project overrides MUST remain intact. The global installation is stored
locally, separately from frontend appearance. This rule MUST NOT change the
existing project-specific headless/MCP configuration contracts.
Save media paths remain machine-local project settings. Disposable save MUST be
an explicit temporary choice for the open project, reset on reopening, and MUST
be identified in execution status. Missing save media MUST NOT implicitly select
disposable mode. Existing write exclusion and save protection remain mandatory.
## 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.
Gameplay MUST default to uniform automatic scaling to the largest image that
fits the available surface. Window or Gameplay divider resize MUST recompute the scale, preserve aspect ratio
and center the image with margins when needed, without scrollbars in automatic
mode. The Gameplay footer's percentage and multiplier MUST describe the effective scale
relative to native frame dimensions. UI text scale is independent of game scale.
A Manual scale checkbox MUST enable a continuous slider from 25% to 400% of
native dimensions, initially using the current fitted scale clamped to that range.
Manual images larger than the surface MUST remain accessible by scrolling.
Disabling manual mode returns to automatic fit; reopening a project resets manual
mode. Presentation retains nearest-neighbor sampling, including fractional scale.
Divider movement MUST preserve the chosen manual scale and update the visible
scroll area. Automatic fitting MUST also respond while paused, without requiring
a new runtime frame; disabling manual mode fits the current render area.
This replaces the former discrete x1/x2/x4 and mandatory 1:1 presentation contract.
Input MUST invert the image's actual scene transform and displayed dimensions,
including fractional scale, centering margins and manual scroll. 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.
Scale and scroll 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.