stickman/docs/specs/phase_7_ui_polish.md

# Phase 7 UI Polish — Architecture Specification

Status: **proposed; awaiting user approval**  
Source plan: `docs/archive/plans/PHASE_7_UI_POLISH.md`  
Target: Godot 4.7.1 Sandbox Stage only. The configured Stickman Editor main scene is not changed.

## 1. Scope and current-state audit

Phase 7 is an incremental polish pass, not a rewrite of `SandboxStage`. The stage scene remains deliberately small and the runtime UI remains owned by `SandboxStage._build_ui()`. Existing tests also access several stage fields directly, so moving the full UI into a new scene would add migration risk without improving the requested behavior.

### Already implemented; preserve and restyle

| Plan item | Existing implementation |
|---|---|
| Three mode controls | `_mode_buttons` in `scripts/editors/stage/sandbox_stage.gd` |
| Mode badge, status text, live world coordinates | `_mode_badge`, `_status_label`, `_status_cursor_coords` |
| Mode cursor and target reticle | `_apply_cursor()`, `_build_action_cursor()` |
| Cursor tooltip and direct-action trajectory | `_tooltip`, `StagePlacementOverlay.set_action_trajectory()` |
| Terrain AABB stride, Bresenham painting, Shift lock | `_terrain_stride()`, `_bresenham_cells()`, `_update_terrain_drag()` |
| Three-state terrain ghosts | `_classify_cell()`, `_refresh_terrain_ghosts()` |
| Asset selector with thumbnail cards and dimmer | `asset_selector.tscn`, `asset_selector.gd`, `_selector_dim` |
| Sequential off-screen thumbnail rendering and disk cache | stage `_thumbnail_queue`; `scripts/shared/thumbnails/*` |
| Popup and editor font overrides | `_apply_popup_theme()` and widget `apply_font()` methods |

These behaviors are integration points, not new Phase 7 systems. Their public behavior and existing headless tests must continue to pass.

### In Phase 7

1. Replace the stage-local JSON parsing and scattered style constants with a validated, cached `SandboxTheme` service and schema version 2.
2. Give the existing mode switcher, viewport frame, badge, status bar, tooltips, popups, dialogs, selector, and overlays a coherent theme-driven appearance.
3. Replace the top-row spawn text buttons with a scrollable graphical card palette. Clicking keeps the existing persistent placement behavior; dragging a card performs one placement.
4. Harden the existing thumbnail cache with a memory tier and stale-request protection. Rendering remains serialized on the main thread.
5. Add reusable color, size, font-preset, and emoji controls, with stable typed APIs, ready for later parameter dialogs.

### Explicitly deferred

- Speech bubble geometry/styles, custom speech rendering, and changes to persisted `speak` actions. Section 10 defines the future contract, but Phase 7 does not emit or consume it.
- Embedding the four new reusable widgets into the Speak dialog. That is the first consumer in the future speech-customization phase.
- True background-thread thumbnail rendering. Godot scene/viewport rendering remains main-thread work; Phase 7 limits generation to one job at a time and avoids duplicate/stale work.
- Dragging cards out of the modal `AssetSelector`. Direct drag uses the currently selected Prop or Stickman card in the persistent palette; the modal remains click-to-select.
- New bitmap icon art. Phase 7 uses registry-provided emoji glyphs plus existing generated thumbnails. Art assets can replace them later without changing card APIs.
- A full `.tscn` conversion of the code-built Sandbox UI.

## 2. Files

### Add

- `scripts/stage/sandbox_theme.gd` — `class_name SandboxTheme`, schema validation, legacy aliases, typed accessors, font/style/theme caches.
- `scripts/shared/ui/asset_card.gd` — `class_name AssetCard`, reusable palette/selector card and pointer-drag threshold handling.
- `scripts/shared/ui/color_swatch_selector.gd` — `class_name ColorSwatchSelector`.
- `scripts/shared/ui/preset_size_toggle.gd` — `class_name PresetSizeToggle`.
- `scripts/shared/ui/font_preset_picker.gd` — `class_name FontPresetPicker`.
- `scripts/shared/ui/emoji_quick_grid.gd` — `class_name EmojiQuickGrid`.
- `tests/test_phase7_theme.gd` — schema, fallback, alias, and resource/cache behavior.
- `tests/test_phase7_widgets.gd` — widget data contracts and signals.
- `tests/test_phase7_palette.gd` — card activation/drag state, mode visibility, and placement behavior.

The reusable controls are script-built `Control` subclasses, not new scenes. They have no project-specific node paths and can be instantiated in any popup.

### Change

- `sandbox_theme.json` — migrate the committed theme to schema `2.0`.
- `scripts/editors/stage/sandbox_stage.gd` — own `SandboxTheme`; build/stylize the chrome and palette; route card drag input; use theme accessors; apply theme to popups/dialogs; add thumbnail request generation tokens.
- `scripts/stage/stage_spawner.gd` — expose registry-backed palette descriptors without exposing `_registry`.
- `scripts/shared/ui/asset_selector.gd` — build cells with `AssetCard`; accept a `SandboxTheme`; keep current signals and pagination.
- `scenes/stage/asset_selector.tscn` — name layout containers used for theme spacing/margins and remove hard-coded visual values now owned by the theme. Node unique names and popup behavior remain compatible.
- `scripts/shared/thumbnails/thumbnail_cache.gd` — add an in-memory texture tier and versioned cache API while preserving current path helpers.
- `scripts/stage/stage_placement_overlay.gd` — accept resolved overlay colors/metrics through one style method; drawing/input behavior is unchanged.
- `scripts/stage/stage_director_visuals.gd` — consume a resolved style dictionary rather than reading raw schema internals; preserve `set_style(Dictionary)` as a compatibility wrapper.
- `scripts/editors/stage/action_editor.gd`, `scripts/editors/stage/rule_editor.gd`, `scripts/editors/stage/queue_panel.gd`, `scripts/editors/stage/rule_panel.gd` — add `apply_theme(theme: SandboxTheme)` wrappers and retain current `apply_font(...)` methods for existing tests/callers.
- Existing Phase 3b/3c/4b tests only where assertions must reflect the always-visible mode frame or v2 key names; behavioral coverage is not removed.

### Not changed in Phase 7

- `scenes/stage/sandbox_stage.tscn`
- `scripts/stage/action_registry.gd`
- `scripts/stage/stage_scene_io.gd`
- `scripts/characters/stickman/stickman_rig.gd`
- `scripts/speech/stickman_speech_bubble.gd`

## 3. `sandbox_theme.json` schema 2.0

The JSON remains hand-editable. Colors are HTML strings (`#RRGGBB` or `#RRGGBBAA`), resource paths are strings, dimensions are logical screen pixels, and preset IDs are stable lowercase strings.

```json
{
  "version": "2.0",
  "global": {
    "font_preset": "ui",
    "font_size": 18,
    "text_color": "#F5F7FA",
    "muted_text_color": "#AAB2C0",
    "bg_color": "#171B24F2",
    "surface_color": "#252B38FA",
    "border_color": "#FFFFFF33",
    "border_width": 1,
    "corner_radius": 10,
    "padding": 8,
    "spacing": 8
  },
  "fonts": {
    "ui_font": "",
    "emoji_font": "",
    "ui_font_bold": "",
    "ui_font_italic": "",
    "presets": {
      "ui": { "label": "Standard", "path": "" },
      "comic": { "label": "Comic", "path": "" },
      "pixel": { "label": "Pixel", "path": "" },
      "scary": { "label": "Scary", "path": "" }
    },
    "sizes": {
      "action_popup": 24,
      "action_popup_emoji": 22,
      "assignment_badge": 20,
      "rule_label": 16,
      "status_pill": 16,
      "tooltip": 18,
      "queue_panel": 18,
      "rule_panel": 18,
      "action_editor": 18,
      "rule_editor": 18,
      "panel_row": 16,
      "panel_title": 18,
      "asset_label": 14,
      "asset_badge": 12
    },
    "flags": {
      "panel_title_bold": true,
      "rule_label_bold": false,
      "badge_bold": true,
      "action_popup_bold": false,
      "action_popup_italic": false
    }
  },
  "mode_colors": {
    "edit": "#22C6FF",
    "direct": "#FFB300",
    "play": "#33DD77",
    "guide": "#22C6FF"
  },
  "grid": { "snap_size": 15.0 },
  "chrome": {
    "style_defaults": { "bg_color": "#171B24F2", "corner_radius": 10 },
    "top_bar": { "height": 48 },
    "status_bar": { "height": 32 },
    "mode_switcher": { "segment_min_width": 104 },
    "mode_frame": { "border_width": 3 },
    "mode_badge": { "corner_radius": 12, "padding": 10 },
    "tooltip": { "bg_color": "#101010E6", "border_width": 1 }
  },
  "popups": {
    "style_defaults": { "bg_color": "#202633FA", "border_color": "#FFFFFF33", "corner_radius": 12, "padding": 12 },
    "action_menu": { "font_size": 24 },
    "dialog": {},
    "asset_selector": { "backdrop_alpha": 0.55 }
  },
  "palette": {
    "style_defaults": { "bg_color": "#252B38FA", "corner_radius": 10, "padding": 6 },
    "dock_width": 116,
    "card_size": [96, 94],
    "icon_size": 30,
    "drag_threshold": 8,
    "selected_border_width": 3
  },
  "overlays": {
    "style_defaults": { "line_width": 2, "dash_length": 8, "dash_gap": 5 },
    "terrain_guide": { "color": "#22C6FF" },
    "valid": { "color": "#4DE66680" },
    "same_type": { "color": "#FFFFFF26" },
    "invalid": { "color": "#FF4D4D80" }
  },
  "widgets": {
    "swatches": ["#FFFFFF", "#111111", "#22C6FF", "#FFB300", "#33DD77", "#FF4D4D"],
    "size_presets": [
      { "id": "small", "label": "Small", "value": 20 },
      { "id": "medium", "label": "Medium", "value": 28 },
      { "id": "huge", "label": "HUGE", "value": 40 }
    ],
    "emoji": ["😀", "😂", "😍", "😮", "😢", "😡", "👍", "❤️"]
  },
  "speech_bubbles": {
    "style_defaults": {
      "font_preset": "ui",
      "size_preset": "medium",
      "color": "#FFFFFFFF",
      "text_color": "#111111FF",
      "border_color": "#00000099",
      "border_width": 2,
      "corner_radius": 8,
      "padding": 14
    },
    "styles": {
      "standard": { "label": "Standard", "geometry": "rounded" },
      "yell": { "label": "Yell", "geometry": "burst" },
      "thought": { "label": "Thought", "geometry": "cloud" },
      "whisper": { "label": "Whisper", "geometry": "dashed" }
    }
  }
}
```

Array values such as `card_size` must contain exactly two finite numbers. Unsupported or malformed values fall back independently; one bad field does not discard the rest of the file.

### Resolution order

For a component such as `popups.action_menu`, the service deep-merges, from lowest to highest priority:

1. Hard-coded `SandboxTheme.DEFAULT_CONFIG` value.
2. Loaded `global` value.
3. Loaded subsystem `popups.style_defaults` value.
4. Loaded component `popups.action_menu` value.

Font resolution is: component `font_preset`/explicit path → subsystem default → `global.font_preset` → `fonts.ui_font` → `ThemeDB.fallback_font`. An unavailable named preset falls back to `ui`. Emoji font resolution is `fonts.emoji_font` → resolved UI font → `ThemeDB.fallback_font`.

### Validation, warnings, and caching

- Missing, unreadable, malformed, or non-dictionary JSON produces one non-blocking `push_warning` and a complete default config.
- A wrong type, non-finite number, bad color, or missing/non-Font resource warns once per key and falls back only that key.
- Unknown keys are retained in `raw_config()` for forward compatibility but are ignored by typed accessors.
- Fonts are loaded once per normalized non-empty resource path in `_font_cache`.
- Resolved `StyleBoxFlat` templates are cached by the canonical resolved style dictionary. `stylebox()` returns a duplicate so mode-specific color mutation cannot leak into another control.
- The generated Godot `Theme` is cached. Call `invalidate_caches()` only after an explicit reload; Phase 7 does not add live file watching.
- No theme resource failure may prevent Sandbox startup.

## 4. `SandboxTheme` public contract

```gdscript
class_name SandboxTheme
extends RefCounted

const SCHEMA_VERSION: String = "2.0"
const DEFAULT_PATH: String = "res://sandbox_theme.json"

func load_from(path: String = DEFAULT_PATH) -> bool
func raw_config() -> Dictionary
func value(path: String, fallback: Variant = null) -> Variant
func color(path: String, fallback: Color) -> Color
func number(path: String, fallback: float, minimum: float = -INF, maximum: float = INF) -> float
func integer(path: String, fallback: int, minimum: int = -2147483648, maximum: int = 2147483647) -> int
func font(component_path: String = "", preset_id: String = "ui") -> Font
func emoji_font() -> Font
func style(component_path: String) -> Dictionary
func stylebox(component_path: String) -> StyleBoxFlat
func control_theme() -> Theme
func swatches() -> Array[Color]
func size_presets() -> Array[Dictionary]
func font_presets() -> Array[Dictionary]
func emoji_items() -> Array[String]
func invalidate_caches() -> void
```

`raw_config()` returns a deep duplicate. The preset array entries returned by `size_presets()` are `{id: String, label: String, value: int}`; font preset entries are `{id: String, label: String, font: Font}`. Invalid entries are omitted, while a built-in medium size and UI font are always available.

No reload signal is needed in Phase 7 because the theme loads once before UI construction. A later live-theme editor may add `theme_reloaded()` without changing the accessor API.

## 5. Palette descriptors and controls

### `StageSpawner` API

Add:

```gdscript
func get_palette_entries() -> Array[Dictionary]
```

Each returned deep-duplicated entry has this shape:

```gdscript
{
    "placement_id": String, # existing id accepted by set_placement_mode()
    "kind": String,         # "terrain" | "prop" | "stickman" | "area"
    "label": String,
    "icon": String,         # emoji fallback, not a resource path
    "category": String,     # visible badge/group label
    "opens_selector": bool
}
```

Registry defaults are Ground/🧱/Terrain, Ramp/📐/Terrain, Step/🪜/Terrain, Prop/📦/Props, Stickman/🧍/Cast, and Area/🎯/Events. `get_spawnable_ids()` and `get_label()` remain unchanged.

### `AssetCard`

```gdscript
class_name AssetCard
extends Button

signal activated(payload: Dictionary)
signal drag_started(payload: Dictionary)

func configure(payload: Dictionary, icon_texture: Texture2D = null, theme: SandboxTheme = null) -> void
func set_thumbnail(texture: Texture2D) -> void
func set_selected(selected: bool) -> void
func payload() -> Dictionary
```

The payload is deep-copied on input and signal emission. The card owns icon/thumbnail, label, and optional category badge children. It emits `activated` on a release that stayed below `palette.drag_threshold`; after the threshold it emits `drag_started` once and suppresses activation. It does not mutate stage or spawner state directly.

### Reusable widget APIs

```gdscript
# ColorSwatchSelector
signal color_selected(color: Color)
func configure(colors: Array[Color], selected: Color, theme: SandboxTheme = null) -> void
func set_selected(color: Color, emit_signal: bool = false) -> void
func get_selected() -> Color

# PresetSizeToggle
signal preset_selected(id: String, value: int)
func configure(presets: Array[Dictionary], selected_id: String, theme: SandboxTheme = null) -> void
func set_selected(id: String, emit_signal: bool = false) -> void
func get_selected_id() -> String
func get_selected_value() -> int

# FontPresetPicker
signal preset_selected(id: String)
func configure(presets: Array[Dictionary], selected_id: String, theme: SandboxTheme = null) -> void
func set_selected(id: String, emit_signal: bool = false) -> void
func get_selected_id() -> String

# EmojiQuickGrid
signal emoji_selected(text: String)
func configure(items: Array[String], columns: int = 8, theme: SandboxTheme = null) -> void
```

All configure methods replace prior children, tolerate empty inputs, use a `ButtonGroup` for exclusive preset selection, expose keyboard focus, and meet a minimum 44×44 logical-pixel pointer target.

## 6. Node ownership and layout

`SandboxStage` continues to create one `CanvasLayer` named `UI`. Its runtime ownership becomes:

```text
SandboxStage (Node2D; state and orchestration)
├── GridLayer / World / GhostHolder / PlacementOverlay / DirectorVisuals (world space)
└── UI (CanvasLayer)
    ├── ModeFrame (Panel; full rect; mouse ignore)
    ├── TopBar (PanelContainer)
    │   └── FileMenu + ModeSwitcher + edit/direct utility controls
    ├── PaletteDock (PanelContainer; left, below TopBar and above StatusBar)
    │   └── ScrollContainer/PaletteCards (VBoxContainer of AssetCard)
    ├── ModeBadge (PanelContainer; mouse ignore)
    ├── ActionTooltip (Label; mouse ignore)
    ├── BottomStatusBar (PanelContainer)
    ├── SelectorDim (ColorRect; visible only with selector)
    └── Popups/dialogs/selectors/editors
```

`PaletteDock` is visible only in EDIT. Existing grid/snap/size controls remain in `TopBar`; spawn buttons leave the top row. `_palette_buttons` is retained and maps placement IDs to `AssetCard` (a `Button` subclass), preserving callers that inspect `button_pressed`/`visible`.

The mode segments share a `ButtonGroup`, have adjacent rounded styles, and retain `_on_mode_segment_toggled`. `_mode_frame` is visible in all three modes and uses the active accent; it remains behind all chrome and ignores mouse input. The badge remains below the top bar and displays the existing text.

The stage assigns `theme.control_theme()` to the UI root and explicitly to Window-derived popups/dialogs that do not reliably inherit across a native/embedded window boundary. Component styleboxes are then applied only where a named component override is needed.

## 7. Input and signal flow

### Click placement

1. `AssetCard.activated(payload)` reaches `SandboxStage._on_palette_card_activated(payload)`.
2. Terrain/Area calls existing `set_placement_mode(placement_id)`.
3. Prop/Stickman opens the existing selector; selecting an entry updates the spawner and arms the existing `prop`/`stickman` placement ID.
4. LMB remains repeated placement and RMB/Escape cancels, matching existing behavior.

### Direct card drag

Godot Control drag-and-drop is not used because the drop surface is a `Node2D` world and a full-screen `Control` would compete with existing `_unhandled_input` selection/gizmo routing.

1. `AssetCard.drag_started(payload)` calls `_begin_palette_drag(payload)`.
2. The stage stores `_palette_drag_payload`, snapshots the prior placement ID, resolves current Prop/Stickman selection, and creates the normal collision-disabled placement ghost.
3. While a palette drag is active, `SandboxStage._input` handles mouse motion and LMB release before pan/zoom routing. Tooltip/modal/rule input is not entered.
4. A release is valid only inside the stage viewport and outside visible interactive chrome (`gui_get_hovered_control() == null` or a mouse-ignore overlay). Valid release places exactly one object at `_viewport_to_world(event.position)`, using existing snap/spawn/finalize/signals/dirty-state code.
5. Release over UI, RMB, Escape, mode change, selector open, or focus loss cancels and frees the drag ghost.
6. A card drag is one-shot and restores the previous persistent placement selection. It never starts terrain line-painting; terrain drag-painting still starts from a stage press after click-arming the tool.

Add private state and helpers in `sandbox_stage.gd`:

```gdscript
var _palette_drag_payload: Dictionary = {}
var _palette_drag_previous_id: String = ""

func _on_palette_card_activated(payload: Dictionary) -> void
func _begin_palette_drag(payload: Dictionary) -> void
func _update_palette_drag(viewport_pos: Vector2) -> void
func _finish_palette_drag(viewport_pos: Vector2) -> void
func _cancel_palette_drag() -> void
func _is_stage_drop_position(viewport_pos: Vector2) -> bool
```

Priority while active is palette drag → modal suppression → pan/zoom → existing world tools. Existing rule/capture/terrain/gizmo priorities remain unchanged when no palette drag is active.

## 8. Thumbnail pipeline

The existing renderer nodes and queue remain stage-owned. Do not introduce threads.

Extend `ThumbnailCache` with:

```gdscript
func get_texture(cache_path: String) -> Texture2D
func store_texture(cache_path: String, texture: Texture2D) -> Error
func forget_memory(cache_path: String) -> void
func clear_memory() -> void
```

`get_texture()` checks an in-memory dictionary, then PNG, and memoizes success. `store_texture()` memoizes and persists. Existing `load_png()`/`save_png()` remain as compatibility wrappers.

The stage increments `_thumbnail_generation: int` whenever selector entries change or the selector closes. Each queued job carries `{generation, kind, entry, cache_path}`. After each `await`, results update the selector only when the generation still matches, the selector is open, and the entry is still present. Cache writes may complete for a stale UI generation because they remain useful. Queue keys prevent duplicate work in the same generation. One job at a time preserves frame stability and the existing renderer assumptions.

## 9. Overlay, popup, and dialog integration

- `StagePlacementOverlay.apply_style(style: Dictionary)` receives resolved guide/valid/invalid metrics. Existing public setters and screen-constant line math remain intact.
- The three terrain ghost modulates come from `overlays.valid`, `overlays.same_type`, and `overlays.invalid`; classification values and commit rules do not change.
- `StageDirectorVisuals.apply_style(style: Dictionary, fonts: Dictionary)` receives already-resolved sizes/colors/fonts. Keep `set_style(Dictionary)` as a legacy wrapper through Phase 7 tests.
- All PopupMenus use `popups.action_menu`; Accept/Confirmation/File dialogs use `popups.dialog`; `AssetSelector` uses `popups.asset_selector`.
- `_apply_popup_theme()` remains temporarily as a wrapper around `SandboxTheme` so existing direct tests do not break.
- Tooltip positioning continues clamping to the visible viewport. Palette dock bounds are also treated as UI, so a tooltip never becomes a valid world drop region.

## 10. Future speech customization contract (blueprint only)

When implemented in a later phase, a flat queue action will optionally carry one nested visual object:

```gdscript
{
    "type": "speak",
    "text": String,
    "duration": float,
    "stop_current": bool, # optional, existing
    "visual": {           # optional; absent means theme defaults
        "font_preset": String,
        "size_preset": String,
        "color": String,       # HTML RGBA
        "bubble_style": String # standard/yell/thought/whisper
    }
}
```

Rule actions will store the same `visual` dictionary under their existing `params`. `ActionRegistry.to_rule_action()`/`from_rule_action()` will copy it unchanged, `StageSceneIO` will validate known scalar fields while preserving absence, and `SpeechBubble.show_text()` will eventually accept a style dictionary. Unknown preset/style IDs must resolve to theme defaults rather than invalidating the action.

Phase 7 only reserves the theme IDs and supplies the reusable controls. It deliberately does not modify save files or runtime speech behavior.

## 11. Compatibility and migration

- Theme schema `1.0`, missing version, and `2.0` are accepted. Unsupported future major versions warn and use recognized keys plus defaults.
- Legacy aliases are applied before validation:
  - `mode_colors.edit_accent/direct_accent/play_accent/guide_line` → `mode_colors.edit/direct/play/guide`.
  - Existing flat `fonts.*_font_size` keys → matching `fonts.sizes.*` keys.
  - `fonts.action_popup.{size,bold,italic}` → `fonts.sizes.action_popup` and `fonts.flags.action_popup_*`.
  - Existing bold flags and `assignment_badge_radius` retain their current meaning.
- A v2 key wins when both v2 and its legacy alias exist.
- No automatic write-back of user theme files occurs.
- Existing `user://sandbox_settings.json` values win over theme defaults. If a settings key is absent, the loaded theme value—not the old hard-coded constant—is used.
- `.scene` serialization remains byte-contract compatible because Phase 7 changes no scene payload fields.
- Existing public stage signals (`mode_changed`, `object_placed`, selection/deletion signals), `AssetSelector` signals, placement IDs, and action dictionaries remain unchanged.
- Existing private test-visible fields remain present. `_palette_buttons` values remain `Button`-compatible.
- Missing emoji/custom fonts degrade to `ThemeDB.fallback_font`; labels stay usable even if a glyph renders as a fallback box.

## 12. Delivery phases and acceptance criteria

### 7.1 Theme service and schema

- `SandboxTheme` loads the committed v2 file and produces complete resolved values.
- Missing/malformed files, invalid individual keys, and missing font paths never abort startup.
- v1 aliases reproduce current sizes/colors.
- Font/style/theme caches reuse resources; caller mutation of one returned stylebox does not affect another.
- Existing grid setting precedence is preserved with the corrected theme fallback for missing settings keys.

### 7.2 Chrome and mode polish

- Mode segments are one exclusive group with clear active accent and keyboard focus.
- Frame, badge, and status bar update immediately in EDIT/DIRECT/PLAY; the frame uses each mode color in every mode.
- Existing cursor, tooltip, target trajectory, status coordinate, and Escape behavior pass unchanged.
- At 1280×720, top/bottom chrome and the palette do not cover each other; at smaller windows, the palette scrolls instead of overflowing.

### 7.3 Reusable widgets

- All four controls configure from the theme contract, rebuild safely, emit exactly once per user choice, and expose their selected value.
- Empty/malformed preset arrays fall back safely.
- Every interactive item has keyboard focus and a minimum 44×44 target.

### 7.4 Palette, selector, and thumbnail cache

- Six registry-driven graphical cards appear only in EDIT and preserve `_palette_buttons` state semantics.
- Click-arming, modal Prop/Stickman selection, repeated placement, RMB/Escape cancellation, and mode transitions behave as before.
- Dragging a palette card over the stage places exactly one item; release over UI/cancel places none and leaves no ghost.
- The selector retains pagination, dimming, Browse/Refresh, generated previews, and click selection.
- Cached textures are reused from memory/disk, duplicate jobs are suppressed, and stale async completion never updates a closed or repopulated selector.

### 7.5 Popup/overlay consistency and regression

- Popup menus, dialogs, panels, selector cards, tooltip, terrain guides, ghosts, and action trajectories use the resolved theme.
- Terrain painting still uses template AABB stride, Bresenham cells, three classifications, Shift axis lock, and skip-on-conflict commits.
- Queue/rule/action editor behavior and font APIs remain compatible.
- No changes occur to speech rendering or saved action schemas.

## 13. Validation strategy

### Headless tests

Run the new suites plus the regression suites most directly touched:

```powershell
& "C:\Godot4\Godot_v4.7.1-stable_win64_console.exe" --headless --path "C:\Godot4\stickman" --script res://tests/test_phase7_theme.gd
& "C:\Godot4\Godot_v4.7.1-stable_win64_console.exe" --headless --path "C:\Godot4\stickman" --script res://tests/test_phase7_widgets.gd
& "C:\Godot4\Godot_v4.7.1-stable_win64_console.exe" --headless --path "C:\Godot4\stickman" --script res://tests/test_phase7_palette.gd
& "C:\Godot4\Godot_v4.7.1-stable_win64_console.exe" --headless --path "C:\Godot4\stickman" --script res://tests/test_phase4b_stage.gd
& "C:\Godot4\Godot_v4.7.1-stable_win64_console.exe" --headless --path "C:\Godot4\stickman" --script res://tests/test_phase4b_logic.gd
& "C:\Godot4\Godot_v4.7.1-stable_win64_console.exe" --headless --path "C:\Godot4\stickman" --script res://tests/test_phase4b_terrain.gd
& "C:\Godot4\Godot_v4.7.1-stable_win64_console.exe" --headless --path "C:\Godot4\stickman" --script res://tests/test_phase4b1_fixes.gd
& "C:\Godot4\Godot_v4.7.1-stable_win64_console.exe" --headless --path "C:\Godot4\stickman" --script res://tests/test_phase3b_library.gd
& "C:\Godot4\Godot_v4.7.1-stable_win64_console.exe" --headless --path "C:\Godot4\stickman" --script res://tests/test_phase3b_ui_fixes.gd
& "C:\Godot4\Godot_v4.7.1-stable_win64_console.exe" --headless --path "C:\Godot4\stickman" --script res://tests/test_phase3c_bugfix.gd
```

Run `--check-only` on every added/changed `.gd` script before those suites. Tests should exercise public methods/signals where possible; source-text assertions are only a last resort for engine behavior that cannot be driven headlessly.

### User verification in Godot (spec-pipeline hand-off)

After implementation and green headless tests, stop and ask the user to verify:

1. Resize the Sandbox Stage from 1280×720 down to a small window and confirm chrome/palette remain usable.
2. Switch all modes and confirm frame, badge, segment, status, cursor, and visibility changes.
3. Click-arm and drag-drop each card type; cancel by UI release, RMB, Escape, and a mode change.
4. Open Prop and Stickman selectors twice to confirm thumbnail reuse and no visible stale updates.
5. Exercise Direct-mode Walk To and rule targets to verify tooltip/trajectory/reticle layering.
6. Terrain-paint empty, same-type, and conflicting cells with and without Shift.
7. Open Speak/Wait/Rename, queue/rule editors, and context menus to judge font size, contrast, and emoji fallback.

Do not update README/project documentation until the user explicitly confirms the feature works.

## 14. Design decisions and trade-offs requiring approval

1. **Keep the Sandbox UI code-built.** This minimizes churn in a 4,000-line controller and preserves existing test-visible fields. Replacing it with a complete UI scene is deferred.
2. **Use a dedicated theme service, not raw dictionary reads or a JSON-to-Theme singleton.** The stage owns one instance, making tests deterministic and avoiding global state; a cached Godot `Theme` still supplies normal Control inheritance.
3. **Use custom card pointer capture for world drops.** A full-screen Control drop target risks intercepting the existing Node2D world input stack. Drag placement is intentionally one-shot; click placement remains persistent.
4. **Show the mode frame in all modes.** The plan says it reflects the active mode; the current implementation shows it only in DIRECT. Phase 7 changes that behavior.
5. **Reserve but do not implement speech customization.** Theme presets and reusable controls land now, while action persistence/runtime rendering stay unchanged until a dedicated speech phase.
6. **Serialized, cached thumbnail work is preferred over threading.** It is safer with Godot viewports and already matches the working architecture; memory caching and generation tokens address the actual stutter/stale-update risks.