# 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.