Add initial draft for Phase 7 UI Polish plan

AGENTS.md

@@ -1,11 +1,13 @@
-# AGENTS.md — stickman (Godot 4.4)
+# AGENTS.md — stickman (Godot 4.7.1)
 
 ## Project type
-- **Godot 4.4** 2D/GUI project (Forward Plus renderer)
+
+- **Godot 4.7.1** 2D/GUI project (Forward Plus renderer)
 - Headless tests + command-line scene playback exist (see "Command-line testing & debug playback" below); the GUI editor runs via `run/main_scene`.
 - **Main scene:** `res://scenes/stickman_editor.tscn` (set as `run/main_scene` in `project.godot`)
 
 ## Command-line testing & debug playback
+
 - **Godot binary (4.7.1) — resolve per platform.** Commands below use `<godot>` as shorthand:
   - macOS: `/Applications/Godot.app/Contents/MacOS/Godot`
   - Windows (PowerShell): `& "C:\Godot4\Godot_v4.7.1-stable_win64_console.exe"`
@@ -21,17 +23,28 @@
 - **Richer debug logs:** append `--verbose` to the scene-playback (or headless) command to surface engine warnings/errors alongside your own `print()` lines.
 
 ## Project overview
-Stickman Studio is an editor tool for drawing and assembling stick figures. It is a
+
-`Control`-based GUI (not physics/animation) in its current phase. Body-part vector shapes
+Stickman Studio is a kid-friendly 2D scene-building and directing project—not only a
-are authored per-panel (each panel supports **multiple shapes** with Z-ordering) and
+stick-figure editor. Its broader product direction is an approachable moviemaker where
-assembled in a "Whole Stickman" preview that supports translation, rotation, and scale.
+children can create and customize stickmen, build sets with floors/terrain and props,
+arrange characters and objects, direct behavior with queued actions and event-triggered
+rules, and play the resulting scenes.
+
+The codebase currently has two primary workflows. The main `Control`-based stickman editor
+authors body-part vector shapes and assembles them in the "Whole Stickman" preview. The
+Sandbox Stage provides the wider scene workflow through EDIT/DIRECT/PLAY modes, terrain,
+props, live stickman rigs, action queues, and events. The editor remains the configured
+`run/main_scene`; the Sandbox Stage and its runtime systems are separate scenes and tools
+that form the foundation of the broader moviemaking experience.
 
 ## Required addon
+
 - **Scalable Vector Shapes 2D** (v2.27.7) at `addons/curved_lines_2d/`
   - Declared dependency for the project. The current editor UI does not instantiate it directly,
     but keep it present — it is required for the legacy `stick.tscn` rig.
 
 ## Architecture
+
 - `scripts/stickman_editor.gd` — `extends Control`; the main controller. Owns the menu bar,
   save/load/clear flow, JSON (de)serialization, and populates the 10 body-part panels.
   Writes `FILE_VERSION "1.5"`; auto-migrates `"1.0"`–`"1.4"` files on load. Coordinates cross-panel
@@ -329,16 +342,14 @@ assembled in a "Whole Stickman" preview that supports translation, rotation, and
     reads `_ragdoll_bodies["torso"]`: when its linear/angular velocity drops below
     `REST_LINEAR_THRESHOLD`/`REST_ANGULAR_THRESHOLD` (or it is sleeping) it accumulates
     `_rest_timer`; after `rest_timeout` (and a `STABILIZATION_DELAY` hold) with `auto_recover`
-    on it calls `_start_recovery()`.
+    on it calls `_start_recovery()`. - **Pre-ragdoll capture:** `_enter_ragdoll()` first calls `_capture_pre_ragdoll_state()`,
-    - **Pre-ragdoll capture:** `_enter_ragdoll()` first calls `_capture_pre_ragdoll_state()`,
     which snapshots, into `_pre_ragdoll_state`, the 6 IK marker values, the 8 limb bone
     rotations, the head bone rotation, the facing profile, the 4 live bend flags, the head
     LookAt enabled state, per-leg knee side + flag (`leg_sides`), and the chain-space entry
     offsets `torso_chain_offset` / `head_chain_offset` — captured at entry so the snap needs
     **no authored geometry constants** and the LEFT mirror's ambiguous `global_rotation`
     decomposition (±π) cancels out. This snapshot is the recovery **END target** (possibly a
-      mid-walk pose; the animation is not resumed).
+    mid-walk pose; the animation is not resumed). - **Recovery capture + landing:** `_start_recovery()` (also `request_recovery()`, no-op
-    - **Recovery capture + landing:** `_start_recovery()` (also `request_recovery()`, no-op
     unless in RAGDOLL) calls `_capture_ragdoll_pose()` — records the 10 bodies' rig-local
     `{pos, rot, half}` (`half` = each capsule's half-length from build-time metadata) and
     probes the terrain for the ground surface under the fallen figure via `_probe_ground_y()`
@@ -350,8 +361,7 @@ assembled in a "Whole Stickman" preview that supports translation, rotation, and
     landing X — `feet = (_captured_landing_center.x, _captured_ground_y)`, `new_root = feet +
 FOOT_OFFSET` — and re-bases the captured rig-local positions with a **mirror-aware local
     shift** `local_shift = to_local(shift) − to_local(Vector2.ZERO)`, so the re-base survives
-      the LEFT X-mirror), sets `state = RECOVERING` + emits.
+    the LEFT X-mirror), sets `state = RECOVERING` + emits. - **Snap:** `_snap_skeleton_to_pose()` writes the captured pose: the torso marker via
-    - **Snap:** `_snap_skeleton_to_pose()` writes the captured pose: the torso marker via
     `to_local(center_world − spine_dir·half)` with rotation `chain(spine) − torso_chain_offset`;
     the limb bones `rot_u = chain(u) − θ_t − bone_angle_u` and
     `rot_l = chain(l) − chain(u) + bone_angle_u − bone_angle_l`; the head via
@@ -365,8 +375,7 @@ assembled in a "Whole Stickman" preview that supports translation, rotation, and
     `Skeleton2D.set_process_internal(true)`, and re-asserts the Torso marker's
     `RemoteTransform2D` update flags), then **disables** the 4 arm TwoBoneIK mods + the head
     LookAt and **enables** the 2 leg mods (bend side matched to the captured fall pose's knee
-      side vs the entry side recorded in `leg_sides`, or forced via `RECOVERY_LEG_SIDE_FORCE`).
+    side vs the entry side recorded in `leg_sides`, or forced via `RECOVERY_LEG_SIDE_FORCE`). - **Stand-up:** `_play_stand_up()` starts a 2.0 s sine-in-out tween (`STAND_UP_DURATION`)
-    - **Stand-up:** `_play_stand_up()` starts a 2.0 s sine-in-out tween (`STAND_UP_DURATION`)
     of the 6 markers → their **pre-ragdoll** values and of the arm + head bones to the
     `_recovery_bones` targets — upper arm bones take the shortest path, lower arm bones use
     `_natural_joint_target(current, target, offset)` (offset = `bone_angle_lower −
@@ -374,13 +383,11 @@ assembled in a "Whole Stickman" preview that supports translation, rotation, and
     and a `"shortest"` entry in `RECOVERY_JOINT_PATH` bypasses it). The **legs are IK-driven**
     toward their tweening, ground-clamped ankle markers. The arm mods + head LookAt stay
     disabled during the tween. The baked `"stand_up"` animation is **not** played (a fixed
-      first keyframe can never match an arbitrary ragdoll rest pose).
+    first keyframe can never match an arbitrary ragdoll rest pose). - **Finish:** `_on_stand_up_finished()` restores the pre-ragdoll facing profile + per-joint
-    - **Finish:** `_on_stand_up_finished()` restores the pre-ragdoll facing profile + per-joint
     bend flags + head LookAt state (`_restore_head_lookat_state()`), re-enables the arm mods,
     re-shows `Body/*`, sets `state = ANIMATED`, and emits. The resumed IK solve reproduces the
     pre-ragdoll pose exactly (the end pose matches the pre-ragdoll frame, including mid-walk
-      poses).
+    poses). - `_pin_mirrored_head_rotation()` pins the head only while `ANIMATED`. Interruptible:
-    - `_pin_mirrored_head_rotation()` pins the head only while `ANIMATED`. Interruptible:
     `set_ragdoll(true)` during `RECOVERING` kills the stand-up tween and rebuilds the ragdoll;
     `set_ragdoll(false)` during `RAGDOLL` routes through `_start_recovery()`; repeated
     `set_ragdoll` calls are idempotent. `is_in_ragdoll()` stays
@@ -439,7 +446,7 @@ assembled in a "Whole Stickman" preview that supports translation, rotation, and
     (any queue mutation), `speech_finished`. Exports `walk_speed` (300.0). Public API: `walk_to(
 target, speed = -1.0)` (feet/ground destination; no-op unless `state == ANIMATED`), `is_walking()`,
     `speak(text, duration)` (lazily creates a `SpeechBubble` child at `SPEECH_BUBBLE_OFFSET`, auto-hides
-    + emits `speech_finished`), the queue API `queue_action` / `clear_queue` / `get_queue` /
+    - emits `speech_finished`), the queue API `queue_action` / `clear_queue` / `get_queue` /
       `remove_action` / `insert_action` / `queue_size` (all mutations emit `queue_changed`), and the
       runner API `start_queue` / `stop_queue` / `is_queue_running`. `_ready()` builds a
       `NavigationAgent2D` child at `NAV_AGENT_LOCAL_POS` (feet, on the ground-level nav mesh;
@@ -1014,7 +1021,7 @@ assembled in a "Whole Stickman" preview that supports translation, rotation, and
   disables in PLAY. Also draws the box-select marquee via `set_box_rect(rect)`.
 - `scripts/stage_grid.gd` — `class_name StageGrid`, `extends Node2D`; the optional world-space
   grid overlay (Phase 2). Pure `_draw()`: grid lines pan/zoom with the camera (`camera.get_screen_center_position()`
-  + viewport extent / zoom), with a heavier **major line every 5 cells**; `grid_size` / `enabled`
+  - viewport extent / zoom), with a heavier **major line every 5 cells**; `grid_size` / `enabled`
     are set by `SandboxStage`. Added as the first child of the stage root so it renders behind
     `World`; no hit-testing.
 - Scenes:
@@ -1061,6 +1068,7 @@ assembled in a "Whole Stickman" preview that supports translation, rotation, and
     palette-button selector grids.
 
 ### Body-part data model
+
 - 10 internal part keys (ordered): `head`, `torso`, `left_upper_arm`, `left_lower_arm`,
   `right_upper_arm`, `right_lower_arm`, `left_upper_leg`, `left_lower_leg`,
   `right_upper_leg`, `right_lower_leg`.
@@ -1086,6 +1094,7 @@ assembled in a "Whole Stickman" preview that supports translation, rotation, and
   `"1.0"`–`"1.4"` files auto-migrate on load).
 
 ### settings.json (Phase 6)
+
 - Persisted editor preferences written to `settings.json` via `_save_settings()` and
   loaded in `_load_settings()`.
 - Keys: `version`, `grid_size`, `snap_to_grid`, `recent_colors`, `show_pose_guide`.
@@ -1096,12 +1105,14 @@ assembled in a "Whole Stickman" preview that supports translation, rotation, and
   via `_broadcast_settings()`.
 
 ### Legacy scene (do not delete)
+
 - `stick.tscn` — the original rigged/animated figure using `Skeleton2D` + IK targets +
   `RemoteTransform2D` + `Line2D` limbs, plus an embedded `@tool` script drawing the head
   circle. Animations: "walk", "walk_to", "RESET". **Not** the current main scene; kept for
   future animation/rigging phases.
 
 ## Editor conventions
+
 - `.godot/` is gitignored; never edit it manually.
 - Scene files (`*.tscn`) and `.import` files are text-based; use Godot's editor for complex changes.
 - UID references (Godot 4 native) exist in scenes; do not change them by hand.

plans/PHASE_7_UI_POLISH.md

@@ -0,0 +1,134 @@
+# High-Level Architectural Plan: Graphical UI & Palette Polish Phase
+
+## Objective
+
+To overhaul the `SandboxStage` user interface into a polished, kid-friendly graphical experience, while establishing a flexible, schema-driven theme system that seamlessly supports present UI elements and future feature additions (such as dynamic speech bubble styling, sound customization, and extended rule editors).
+
+---
+
+## 1. Centralized Theme & Resource Infrastructure
+
+### 1.1 JSON Theme Schema Expansion (`sandbox_theme.json`)
+
+- **Unified Theme Specification**: Expand the `sandbox_theme.json` contract to serve as the single source of truth for typography, spatial grids, mode accent colors, and component-specific visual presets.
+
+- **Subsystem Category Blocks**: Structure the schema into modular sub-dictionaries (e.g., `fonts`, `mode_colors`, `grid`, `popups`, `speech_bubbles`).
+
+- **Graceful Fallback Pipeline**:
+
+1. Specific component override value.
+
+2. Subsystem block default (e.g., `speech_bubbles.style_defaults`).
+
+3. Global theme default (`fonts.ui_font`).
+
+4. System fallback (`ThemeDB.fallback_font`).
+
+- **Resource Preloading & Validation**: Ensure the theme loader validates paths, gracefully handles missing assets with non-blocking warnings, and caches loaded `Font` and `StyleBox` objects.
+
+---
+
+## 2. Graphical Stage Chrome & Mode Navigation
+
+### 2.1 Mode Switcher & Viewport Frame
+
+- **3-Segment Graphical Switcher**: Replace standard text toggles with a stylized 3-segment mode control (`[✏️ Edit | 🎬 Direct | ▶️ Play]`).
+
+- **Viewport Frame Accent**: Render a screen-constant border frame (`_mode_frame`) around the viewport that dynamically tints according to the active mode accent color.
+
+- **Mode Badge Pill**: Maintain a rounded, high-contrast status badge in the viewport corner displaying the active state with mode-specific icons and accent backgrounds.
+
+### 2.2 Status Bar & Dynamic Cursor System
+
+- **Status & Coordinate Bar**: Polish the bottom bar for scannability, hosting contextual operational hints and live spatial coordinates.
+
+- **Contextual Cursors & Floating Tooltips**:
+- Swap between arrow/crosshair, placement cursors, and custom action reticles depending on mode and pending operations.
+
+- Attach floating, high-contrast tooltip pills offset from the cursor during target selection workflows (e.g., direct mode commands or trigger mapping).
+
+---
+
+## 3. Icon-Based Palette & Thumbnail Engine
+
+### 3.1 Draggable / Clickable Card Palette
+
+- **Visual Asset Cards**: Transition spawner controls from text buttons to visual card tiles displaying item icons, labels, and category badges.
+
+- **Placement Integration**: Support both click-to-select active placement and direct drag-and-drop actions onto the stage.
+
+### 3.2 Modal Asset Selector & Thumbnail Pipeline
+
+- **Asset Selector Modal**: Refine the modal popup and its dimming background backdrop for browsing extended stickmen and prop libraries.
+
+- **Asynchronous Thumbnail Cache**:
+- Streamline off-screen thumbnail generation for custom props and stickmen.
+
+- Cache generated preview textures to prevent UI stuttering during library scans.
+
+---
+
+## 4. Visual Overlay & Placement Feedback Engine
+
+### 4.1 Terrain Drag-Painting & Ghosting Feedback
+
+- **Block-Unit Stride Alignment**: Align placement ghosts and Bresenham line painting to the active terrain template's AABB extent.
+
+- **3-State Ghost Tinting**:
+- **Green**: Valid, empty space ready for placement.
+
+- **Faint / Neutral**: Same-type block (skipped to avoid double-stamping).
+
+- **Red**: Conflicting entity or invalid geometry.
+
+### 4.2 Guidance & Target Trajectories
+
+- **Axis-Aligned Guides**: Render high-contrast dashed lines along cardinal axes during Shift-locked terrain drags.
+
+- **Rubber-Band Trajectories**: Draw contextual connection lines and target reticles from character origins to mouse targets during Direct mode actions.
+
+---
+
+## 5. Reusable Control Widgets & Forward-Compatible Systems
+
+### 5.1 Standardized Kid-Friendly UI Components
+
+Develop a suite of reusable, theme-aware control widgets that can be embedded across dialogs, action popups, and future parameter editors:
+
+- **Color Swatch Selector**: Clickable circle palettes populated from theme swatch arrays or editor history.
+
+- **Preset Size Toggles**: Segmented buttons for coarse adjustments (e.g., **Small**, **Medium**, **HUGE**) mapping to backend integer/scale metrics.
+
+- **Preset Style / Font Pickers**: Visual icon or text buttons allowing selection between preset fonts (e.g., Standard, Comic, Pixel, Scary).
+
+- **Emoji Quick Grid**: A dedicated grid widget for inserting expressive graphics directly into text fields.
+
+### 5.2 Context Menus & Action Popups
+
+- **Uniform Popup Styling**: Apply standardized theme rules, font sizes, and emoji scaling across action context menus, trigger submenus, and dialogs.
+
+- **Clean Action Dialogs**: Align text input (Speak), duration (Wait), and rename popups with dark-mode sandbox styling.
+
+### 5.3 Extension Blueprint: Speech Bubble Customization System
+
+Architect the theme and component pipeline so that future speech bubble upgrades plug directly into the visual foundation without refactoring:
+
+- **Data Contract**: Ensure the `speak` action payload accepts visual parameters (`font_preset`, `size_preset`, `color`, `bubble_style`) alongside text.
+
+- **Style Engine Integration**: Speech bubble nodes consume geometry styles (Standard, Yell, Thought, Whisper) and theme font presets directly from `sandbox_theme.json`.
+
+- **UI Reusability**: The standard Color Swatch, Size Toggle, Font Picker, and Emoji Grid widgets drop directly into the Direct mode `Speak` parameter dialog.
+
+---
+
+## Recommended Execution Sequence
+
+1. **Phase 1: Theme Engine & Core Schema**: Extend `sandbox_theme.json` schema, build centralized theme loading/fallback pipeline, and integrate theme application hooks across stage UI.
+
+2. **Phase 2: Chrome & Mode Navigation Polish**: Implement the 3-segment mode control, viewport frame accents, status badges, and cursor/tooltip overlay controllers.
+
+3. **Phase 3: Reusable UI Component Library**: Build the Color Swatch, Size Toggle, Font Picker, and Emoji Grid widgets.
+
+4. **Phase 4: Graphical Palette & Modal Overhaul**: Implement icon-based asset cards, refine the `AssetSelector` modal, and optimize asynchronous thumbnail caching.
+
+5. **Phase 5: Context Menus & Overlay Polish**: Update action popups with uniform theme sizing and polish drag-painting ghost/guide overlays.