Files
prometeu-studio/docs/specs/studio/13. JavaFX 2 Foundation Specification.md
bquarkz 1e17fc4d67
Test / Tests and coverage
Intrepid/Prometeu/Studio/pipeline/head This commit looks good
feat(studio): add JavaFX 2 foundation and minimal shell
2026-11-18 09:39:42 +00:00

50 lines
5.4 KiB
Markdown
Raw Permalink 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.
# JavaFX 2 Foundation Specification
Status: Implemented foundation. 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.
## 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 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.
## Presentation ownership
An `AppearanceContext` owns presentation state and subscriptions for one window and MUST be closed when that window is hidden. A closed context MUST NOT accept updates. Reopening MUST construct a new context. Components MUST retain normal JavaFX semantics for keyboard, focus, editing and accessibility, while exposing Studio appearance and small APIs.
Reusable families are text/title, decorative pixel icon, button, toggle, text field, non-editable selector, panel and message/progress feedback. Error appearance MUST have explanatory text. Text meaning MUST NOT depend on color alone. Custom geometry MUST NOT replace native interaction with a rasterized whole-window surface.
## Themes and geometry
The dark and light themes MUST provide matching semantic color tokens for background/workspace/surface/field, text/muted text, border, highlight/shadow, accent/on-accent, focus and error. Shared state styles MUST use those tokens. Theme changes MUST update active controls and selector popups in place without losing entered text.
Stepped corners and layered relief are the foundation's visual direction. Region outlines MUST be recomputed at actual layout dimensions so corner steps do not grow with panel width. Main text MUST remain vector-rendered and independently scalable. Palette and geometry refinements MUST preserve legibility, interaction and the agreed identity.
Normal text contrast targets are at least 4.5:1, large text 3:1, and necessary control/focus indicators 3:1. These are design/verification references, not an accessibility certification.
## Fonts and configuration
Departure Mono MUST be the default interior family; Roboto Mono MUST be available locally as an alternative. Both MUST ship with full SIL OFL 1.1 copyright and license notices. Loading MUST NOT require network access or preinstalled fonts. Font failure MUST diagnose and use a readable fallback.
Family and text scale MUST be configurable through presentation settings, not hardcoded in consumers. Supported text scale is 75–200%, default 100%. The developer gallery exposes these choices and comparable editable text. This contract does not require a full preferences window or system-font manager. Native window decoration remains platform-owned.
## Localization and persistence
The UI MUST support pt-BR and English, including runtime labels, accessible names and feedback. English is the fallback bundle. A missing translation MUST diagnose and fall back; an unknown key MUST remain identifiable as `[key]`. Bundles MUST have matching key sets in verification. Formatting MUST use the active locale. Changing locale MUST preserve user-authored text.
First launch MUST select dark, Departure Mono and 100% scale. A supported system locale selects pt-BR; otherwise English. Explicit choices MUST restore without a game project. Invalid individual preference values MUST fall back independently. Persistence MUST remain local presentation state, execute outside the FX thread and flush the latest selection on orderly close. It MUST NOT migrate or mutate the previous frontend's project-local state.
## Verification and non-goals
The foundation MUST have display-free tests of its own locale/preferences/resources/contracts and opt-in real desktop qualification. Desktop checks MUST identify environment/output scale, include normal/minimum sizes and inspect both themes, locales and fonts. Tests MUST exercise active popup appearance, focus/Tab, clipboard, state retention and close/reopen. Performance evidence MUST identify the measured operation; a CSS/layout measurement MUST NOT be presented as total frame latency.
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.