feat(studio): refine Play workspace and project preferences (WRK-001D)
Test / Tests and coverage
Intrepid/Prometeu/Studio/pipeline/head This commit looks good

This commit is contained in:
2026-11-22 15:45:09 +00:00
parent f27cecfe39
commit 2d8f6436e4
42 changed files with 1597 additions and 169 deletions
+42 -2
View File
@@ -177,11 +177,38 @@ shield follows actual opening steps and remains visible for at least one second,
counted in parallel with preparation. Opening a project does not compile or start
the game. Closing its window stops execution and returns to the launcher.
The launcher inherits presentation preferences and has no language, theme,
typeface or scale controls. Closing it exits Studio. `./gradlew run` at the root
The launcher inherits presentation preferences and offers **Prometeu Studio > Preferences**
instead of permanent appearance selectors. This dialog also sets the machine-local
runtime default; **Project > Settings** configures an optional override and save
media. Interactive Play freezes the effective runtime for both asset capacity
qualification and launch, leaving inherited project configuration null. Headless
and MCP configuration remains project-specific.
The global Play/Stop button and Pause/Resume toggle stay on the right above the
Gameplay tab, moving together onto a second right-aligned row when navigation
needs the space. State text
lives in the project header. The equal-height footer follows the selected tab and
shows Gameplay's effective scale. Native tabs use stepped upper corners and a flat,
open base joining the content, without a button's lower bevel. Studio identity
appears once in the launcher's menu. Gameplay automatically fits the native frame
to its surface; the optional manual slider
uses 25–400% scale, with scrolling for oversized images. Window geometry is stored
in `~/.prometeu-studio/window-state.json`; the runtime default is stored separately
in `~/.prometeu-studio/runtime-settings.json`. Neither is portable game metadata.
Closing the launcher exits Studio. `./gradlew run` at the root
launches only the product; the independent shell/gallery require their explicit
module commands and do not run after the product closes.
The active tab's gold outline encloses its content with an opening below the tab
header. The product workspace uses a plain surface and equal top/bottom margins;
there is no additional decorative frame around the tabs. The standalone foundation
shell retains its panel. Gameplay contains a vertical SplitPane: game/local scale controls above,
logs below, initially around 80/20. Drag its horizontal divider to prioritize logs
or game. Automatic fitting follows the resulting render area, including while
paused; manual mode preserves the chosen scale and uses scrolling. The split stays
with the open view and is not stored as a project preference. Header/footer stay
outside the split. The outline decoration does not participate in layout or hit testing.
Qualify these windows without a native runtime using disposable projects and
isolated presentation storage:
@@ -194,6 +221,19 @@ Scene captures and environment metadata are written to
wizard, appearance, geometry, failure feedback and late-session cleanup; the
separate Play gates below exercise the native process and game lifecycle.
Check command position and painting with real Robot mouse events, screen captures
and a repaint reference across themes, locales and text scales:
```bash
./gradlew :prometeu-app:studioControlsDesktopTest
```
Captures and pixel comparisons are written to
`prometeu-app/build/controls-desktop-captures`. The diagnostic fixture retains the
old wrapping layout to measure displacement; the stable-layout gate exercises the
current execution bar. These checks do not replace human confirmation of a reported
artifact that cannot be reproduced on the qualification machine.
Requires a desktop environment and an installed native runtime:
```bash
@@ -16,8 +16,9 @@ own explicit contracts.
## Shell
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
identity, presentation selectors and an empty working area. The product uses its
own menu/toolbar shell and Gameplay tab as specified in specification 14; the
standalone selectors are developer demonstrations. 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.
@@ -15,10 +15,75 @@ Opening MUST hide the launcher and present a separate loading shield; the projec
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.
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.
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
@@ -37,13 +102,19 @@ a selection; Open MUST also work by double click or Enter. Adding a manifest MUS
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
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
@@ -64,7 +135,11 @@ 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
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,
@@ -88,6 +163,32 @@ 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
@@ -169,12 +270,24 @@ 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.
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.
Input MUST invert the image's scene transform and selected logical zoom. Touch
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
@@ -185,7 +298,7 @@ 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
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.