# Phase 19 — Plain Background: architecture specification

> **Status:** Approved design; implementation under way. This specification implements the [accepted product brief](../plans/phase_19_plain_background.md) and [UI/UX specification](phase_19_plain_background_ui_ux.md). The color-choices and custom-picker PNGs reflect the current-color chip as the sole custom-picker entry and the simple **Preview** label; the solid fill and exact labels in the UI/UX specification govern implementation.

## Scope and decisions

Plain Background is a scene-wide, opaque backdrop. It is not a Stage object, a wall panel, or Background ground. The initial color is `#F5EFE0`. File → New adds a truly empty Plain Background starter and relabels the existing neutral-Sky starter **Open Sky**. EDIT → Scenery → Backgrounds offers Plain Background beside the four existing Sky cards. A scene remembers its confirmed plain color while a Sky is active.

The approved design uses a small shared view composed of the existing `StageSkyView` and a full-rect solid `ColorRect`. `SandboxStage` owns the confirmed scene values and the short-lived picker draft. No `Resource`, global signal bus, or extra selectable node is needed for three scalar document values. The Stage inspector kit (`StageInspectorPanel`, `StagePanelChoiceGroup`, `StagePanelToggleRow`) remains for selected objects; this is a modal chooser and uses `AssetSelector`, `AssetCard`, the existing color controls, and their theme tokens.

When Sandbox Stage launches as the active scene without a requested scene, `SandboxStage` opens the starter chooser once after startup recovery handling. A restored autosave remains the active scene without a chooser; discarding recovery opens the chooser. CLI scene requests and load errors keep their existing flows. Closing the startup chooser leaves the empty EDIT Stage open and does not reopen the chooser for that session.

## Node hierarchy and rendering

```text
SandboxStage : Node2D
├─ StageBackgroundLayer : CanvasLayer (layer -1)
│  └─ StageBackgroundView : Control (full viewport; ignores mouse)
│     ├─ StageSkyView : Control (camera-bound only on the live Stage)
│     └─ PlainFill : ColorRect (full rect, opaque, ignores mouse)
├─ StageGrid : Node2D (EDIT overlay)
└─ World : Node2D (existing placed objects)

StageStarterCardPreview : SubViewportContainer
└─ PreviewViewport : SubViewport
   ├─ PreviewBackgroundLayer : CanvasLayer (layer -1)
   │  └─ StageBackgroundView (unbound still)
   └─ PreviewWorld : Node2D

AssetSelector scene-wide card
└─ StageBackgroundCardPreview : Control
   └─ StageBackgroundView (unbound still, clipped to card)
```

`StageBackgroundView` toggles its Sky and Plain children exclusively. A Plain view is a single opaque viewport-sized rect, with no gradient, horizon, motif, parallax, or world transform. Its anchors respond to viewport resize. `StageSkyView` continues to own all five existing Sky IDs and camera response; when hidden for Plain it should not spend frames updating Sky motifs. The view and both children ignore mouse input and never enter Stage selection or draw-order lists. The starter preview must use the same background-kind and color interpretation as the live Stage. The gallery card receives the **remembered** plain color even when the active kind is Sky. Card frames and labels are UI overlays outside the fill, not part of its sample.

## Typed contracts and ownership

| Target | Contract and change | Owner responsibility |
| --- | --- | --- |
| `scripts/stage/scenery/stage_background_view.gd`, `class_name StageBackgroundView extends Control` | `func set_background(kind: StringName, sky_id: StringName, plain_color: Color) -> void`; `func bind_camera(camera: Camera2D) -> void`; `func apply_theme(stage_theme: SandboxTheme) -> void` | Only renders a validated Sky or opaque Plain fill. Reuses `StageSkyView`; has no document, history, or picker state. `bind_camera(null)` yields still previews. |
| `scripts/editors/stage/sandbox_stage.gd`, `class_name SandboxStage extends Node2D` | Confirmed `_background_kind: StringName`, `_sky_id: StringName`, `_plain_color: Color`; transient `_plain_color_draft_active: bool`, `_plain_color_draft: Color`. Private typed helpers such as `_commit_background_kind(kind: StringName, sky_id: StringName = &"") -> void`, `_commit_plain_color(color: Color) -> void`, `_preview_plain_color(color: Color) -> void`, `_cancel_plain_color_preview() -> void`, `_refresh_background_view() -> void`. | Sole authority for current scene state, dirty state, save snapshot, recent color history, and draft rollback. Switching to Plain changes the kind immediately and opens choices; switching Sky retains `_plain_color`. |
| `scripts/stage/stage_scene_io.gd`, `class_name StageSceneIO extends RefCounted` | `FILE_VERSION := "1.7"`; typed validation/migration of `background_kind`, `sky_id`, and `plain_color`. | Reject malformed new backdrop fields before applying a document; migrate older versions without changing their visible Sky. |
| `scripts/editors/stage/stage_scene_adapter.gd`, `class_name StageSceneAdapter extends RefCounted` | Pass all three fields through `collect(...) -> Dictionary` and `apply(...) -> Dictionary`. | Keep background data at the top level; no object entry is created. |
| `scripts/editors/stage/stage_asset_browser.gd` and `scripts/shared/ui/asset_selector.gd`, `class_name AssetSelector extends PopupPanel` | Supply four starter cards and five scene-wide background cards; pass `{background_kind, sky_id, plain_color}` for active state and previews. Add typed `signal plain_color_preview_requested(color: Color)`, `signal plain_color_commit_requested(color: Color)`, and `signal plain_color_preview_cancel_requested` through the browser facade. | The chooser owns view navigation, focus, current/selected card display, and picker controls; it emits intents. It never marks the scene dirty or writes scene data. Keep existing `surface_color_confirmed` for wall/Ground setup history; do not route Plain through it and double-record a color. |
| `scripts/shared/stage_ui/stage_surface_color_controls.gd`, `class_name StageSurfaceColorControls extends VBoxContainer`; `scripts/shared/ui/color_swatch_selector.gd`, `class_name ColorSwatchSelector extends FlowContainer` | Retain `color_selected(color: Color)` and `custom_color_requested`; activating the current-color chip is the sole entry to the full picker. Ensure compact swatches are at least 44 × 44 and stack sections when a horizontal row will clip. | Show current, recent, and preset colors with separate selected and focus treatment. The Stage's existing eight-color recent list is shared. |
| `scripts/shared/stage_ui/stage_surface_color_picker_view.gd`, `class_name StageSurfaceColorPickerView extends VBoxContainer` | Extend `configure(...)`, or add a typed background-specific configuration method, so `preview_color_changed(color: Color)` uses an opaque flat sample for Plain. | Native `ColorPicker` supplies controls. The view displays a draft but does not commit it. Surface motif previews keep their current path. |
| `scripts/stage/scenery/stage_starter_card_preview.gd` and `scripts/stage/scenery/stage_background_card_preview.gd` | Use `StageBackgroundView` for starter and background card imagery. | Show a true solid fill for Plain and preserve existing Sky rendering in still previews. |
| `scripts/stage/stage_grid.gd`, `class_name StageGrid extends Node2D`; `scripts/stage/stage_gizmos.gd`, `class_name StageGizmos extends Node2D`; `scripts/stage/sandbox_theme.gd`, `class_name SandboxTheme extends RefCounted`; `sandbox_theme.json` | Add theme-backed light/dark grid colors and two-tone editor outline colors. Add typed setters on drawing nodes if needed to pass the current backdrop treatment. | Adapt editor overlays to the background while leaving authored art, speech, and physics unchanged. |

The signal names above are the desired public interface between chooser, browser, and Stage. Keep the existing `item_selected(entry: Dictionary)` path for Sky and Plain card taps. A Plain card tap commits the active kind before the chooser opens its color-choices view. A Sky card tap commits the new Sky immediately and keeps the chooser open. The current-card indicator uses a stable **Current background** badge and selected border; keyboard focus is separate. The Plain color choices and its custom picker keep the Stage at full brightness while the modal input blocker remains active and transparent. Other chooser views retain the usual visual dimming.

## Saved scene format and migration

Save top-level fields in `.scene` v1.7:

```json
{
  "version": "1.7",
  "background_kind": "plain",
  "sky_id": "sky_neutral",
  "plain_color": "#F5EFE0",
  "camera": {"position": {"x": 0.0, "y": -400.0}, "zoom": 0.5},
  "objects": [],
  "event_rules": []
}
```

`background_kind` is exactly `"sky"` or `"plain"`. `sky_id` remains one of the existing five IDs even while Plain is active, preserving the last selected Sky for a later switch. `plain_color` is an opaque canonical six-digit `#RRGGBB` string. Runtime color values are clamped to opacity before commit; invalid file values are rejected at the JSON boundary. The plain starter is a separate `.scene` file under `content/stages/starters/` with these values and empty `objects`/`event_rules`; the existing `blank.scene` can remain the Open Sky starter, with its UI label changed. Town Street and Living Room remain authored compositions and acquire migrated Sky-kind fields on their next save if their source version is older.

`StageSceneIO._migrate_to_current()` must explicitly handle **1.6** as well as 1.0–1.5. Every pre-1.7 file migrates to `background_kind: "sky"` and `plain_color: "#F5EFE0"`; it preserves its migrated `sky_id` (including `sky_neutral`). In particular, adding 1.6 to the old `version != "1.5"` branch would incorrectly overwrite its Sky choice: keep that earlier version-specific rule intact. Current-version normalization still runs for migrated data. Read and validate the complete document before replacing the live scene. Save and autosave both serialize confirmed fields only; a picker draft is never consulted. `ContentPaths.canonicalize()` continues to handle starter paths.

## Color transaction and navigation

```mermaid
stateDiagram-v2
    [*] --> Backgrounds
    Backgrounds --> ColorChoices: tap Plain / commit kind
    Backgrounds --> Backgrounds: tap Sky / commit sky
    ColorChoices --> ColorChoices: tap swatch / commit color
    ColorChoices --> CustomPicker: activate current-color chip / snapshot confirmed color
    CustomPicker --> ColorChoices: Use color / commit once
    CustomPicker --> ColorChoices: Back or Esc / discard draft
    ColorChoices --> Backgrounds: Back / keep commits
    CustomPicker --> [*]: popup hide, mode switch, scene replacement / discard draft
```

`_plain_color` is the confirmed remembered value; `_plain_color_draft` exists only while the custom picker is open. Every native picker movement calls `_preview_plain_color()` to update the live `StageBackgroundView` and its flat chooser sample, without assigning `_plain_color`, changing recent history, or marking dirty. **Use color** clamps to opaque, commits the chosen color once, clears draft state, calls the existing `_record_recent_surface_color()` once, and returns to color choices. A preset/recent swatch uses the same commit method directly. An intentional selection can reorder recent history; mark the scene dirty only if the confirmed scene value actually changes. Opening choices at the untouched default does not add the default to recents.

Back, Cancel, Esc, popup hide, mode switch, and scene replacement must all clear the draft and restore the confirmed render. A replacement cancels the draft **before** resetting or loading scene state; popup-hide cleanup must be idempotent because a normal close can trigger it after a button callback. Back from color choices returns to Backgrounds without reverting confirmed card/swatches; Close retains confirmed choices. If Save/autosave occurs during a draft, the snapshot reads `_plain_color`, never the displayed draft. Focus returns to the Plain card from color choices and to the custom-picker opener from the picker; the popup keeps its screen anchor while switching views.

## Chooser layout and contrast

Use the existing `AssetSelector` responsive grid and `AssetCard` controls. File → New presents Plain Background, Open Sky, Town Street, Living Room in that order, two columns on a normal desktop and one scrollable column when narrow. Keep fixed heading and reachable Close. Backgrounds presents the five scene-wide cards under **Choose the scene background**; Wall panel and Background ground stay in a separate **More backgrounds** row. The color-choices view has a fixed **Choose background color** heading, flat confirmed preview, a focusable current-color chip with readable hex, up to eight shared recents, and presets. Place **‹ Backgrounds** at the left of the fixed footer and **Close** at the right; stack them as full-width actions on narrow layouts. Activating the current-color chip opens the custom picker; do not add a separate **More colors** button. The custom view has a flat draft preview and fixed Back/Use footer. Reuse `popups.asset_selector`, `popups.dialog`, `stage_surface_colors`, `stage_panels.action`, and `mode_colors.edit` tokens; add only narrowly needed flat-preview/backdrop-overlay tokens. Increase `popups.asset_selector.compact_swatch_size` from 42 to at least 44 in both theme sources, and clamp the actual `ColorSwatchSelector` target size to at least 44 even if a custom theme supplies a smaller number. Card, swatch, and action targets also meet 44 × 44. Scroll the content within viewport-safe bounds; do not horizontally clip compact color sections.

`StageGrid` currently uses translucent white lines. For Plain, choose theme-backed dark minor/major lines on a light fill and light minor/major lines on a dark fill using the displayed color's luminance, including a temporary draft. Minor lines stay subdued; major lines remain legible. On Sky, retain the established grid treatment. `StageGizmos` currently draws white selection and yellow hover outlines, which can disappear against light fills; add a dark backing stroke beneath a bright core for selection, hover, box selection, rotate ring, and scale handles. Keep screen-space widths and hit testing unchanged. This overlay treatment may be applied consistently for Sky and Plain. No authored object, speech bubble, placement material, or pixel color is rewritten. EDIT still owns grid/gizmos, DIRECT keeps its framing cues, and PLAY hides edit-only overlays. Review cursor pills and placement ghosts on light, dark, and saturated fills during rendered verification.

## Observable acceptance and verification route

| User path / repeatable scenario | Observable outcome |
| --- | --- |
| Fresh Sandbox Stage startup without a scene; close the chooser; compare with a CLI scene load and autosave restore/discard | The chooser opens once over an empty EDIT Stage. Close leaves the blank Stage open without reopening the chooser. A CLI-loaded or restored scene suppresses it; discarding autosave recovery opens it only after the recovery dialog closes. |
| Dirty scene → File → New → cancel unsaved gate or cancel starter chooser; then choose Plain and Open Sky in separate runs | Gates preserve the prior scene on cancel. Plain opens an unsaved empty scene with a uniform `#F5EFE0` fill and zero placed objects; Open Sky keeps the former neutral gradient, sun, and clouds. Both card previews match. |
| EDIT → Scenery → Backgrounds → Plain → swatch → Sky → Plain | Plain taps switch immediately, swatches update Stage and recent ordering, Sky remains selectable, and returning to Plain restores its confirmed color. Selected badge and focus are distinct. Wall/Ground remain separate. |
| Plain custom picker → drag RGB/HSV controls → Back; repeat with Esc, Close, mode change, popup dismissal, and scene replacement | Draft appears in Stage/sample while editing; each cancel path restores the prior confirmed fill. Dirty state, recent list, saved file, and autosave content do not change from the draft. Replacement does not carry draft into the next scene. |
| Plain color choices → activate current-color chip → change custom picker controls → Use color → Save → reopen; compare color and recent list before/after | The current-color chip opens the picker without a separate button. One confirmation stores an opaque color, records it once in shared history, and marks the scene dirty once. Reopen restores active kind and remembered color. A Sky-active save/reopen also retains the hidden remembered plain color. |
| Load representative v1.0–v1.6 files, especially a v1.6 `sky_neutral` scene and a v1.6 non-neutral Sky; save/reopen | They remain visually Sky scenes with the same Sky ID and composition; migration adds default remembered Plain color and writes v1.7 without changing objects, camera, or Sky choice. Invalid v1.7 background data fails before live-scene replacement. |
| Plain Stage with no world objects → pan, zoom, viewport resize, EDIT → DIRECT → PLAY → stop; repeat after save/reopen | Every frame stays an opaque edge-free flat fill. No gradient or motifs appear; backdrop never intercepts clicks. Mode transitions retain color; PLAY has no edit-only grid/gizmos. |
| Light `#F5EFE0`, dark, and saturated Plain colors with Ground, artwork, Props, character, speech, selection, and placement ghost | Grid major/minor lines, selection/hover/gizmos, cursor pills, and ghosts remain usable. Foreground pixel colors and object behavior remain unchanged. |
| Narrow viewport → pointer/touch/keyboard through starters, cards, swatches, picker, Back/Use/Close | Content scrolls without horizontal clipping; actions stay reachable; all targets meet 44 × 44; returning from subviews restores opener focus and popup anchor. |

Use the real Stage chooser, stage scene load/save path, and render-capable Stage for the scenarios above. Inspect captured frames at the named colors, camera positions, zoom levels, modes, and viewport sizes; a headless parse or a screenshot command alone does not establish visual correctness. Focused automated checks should cover the v1.7 migration/validation boundary and the commit/cancel state transitions where they meaningfully protect behavior. No new graphical or animation asset is required: thumbnails and previews are rendered from existing Sky drawing and the new solid fill.

## Trade-offs and implementation constraint

Composing a backdrop view adds one small node and typed facade but keeps Sky drawing focused and lets live Stage and previews share the same kind switch. Three scalar file fields are easier to validate and migrate than a custom `Resource`; the saved `sky_id` is deliberate remembered state while Plain is active. Color history remains a user setting shared with surface colors, while the confirmed plain color belongs to each scene. Theme-backed grid color can account for the flat background, but it cannot account for every placed object beneath a particular grid segment; the two-tone gizmo outline protects selection visibility across mixed art.

The existing chooser was designed around four Sky cards and a separate surface row. Its grid-row counting, active-card group, footer placement, and compact swatch width need targeted extension for five scene-wide choices and the new color views. Preserve its popup anchor and focus behavior while changing those branches; do not fork a second gallery or color picker.