stickman/docs/specs/phase_19_scenery_backgrounds_ui_ux.md

Phase 19 — Scenery, backgrounds, and surface finishes: UI/UX specification

Status: Approved and implemented, including the Stage-relative asset-sizing addition (2026-10-16). Based on the accepted product brief. Full Phase 19 user/editor verification remains pending.

Decision: Use a responsive Scenery chooser followed by canvas tools. Placement stays active for repeated copies. Right-click exits placement. Scenery artwork keeps live .prop references, with a visible, repairable placeholder if a referenced file cannot be found. The Phase 19 addition standardizes new artwork around a standing-stickman size guide and adds single-placement Scenery resizing; direct single-piece transforms commit on release, while the existing group preview keeps its Keep/Cancel boundary. Phase 19 does not add Undo; Stage Undo is deferred to its own future phase and should be recorded in tech debt during architecture planning.

Reuse gate for every new dialog or control: Before building it, inspect the existing shared UI, Stage panel kit, Stage modal/capture controls, and SandboxTheme tokens. Use a matching component directly; extend or extract shared behavior when Phase 19 uses it in more than one place. Keep only content and interaction that are genuinely unique to this feature local. Do not add a parallel card grid, overlap popup, capture bar, dialog skin, swatch style, or selected-object inspector. The later architecture specification must name any justified exception before implementation.

Child promise and visual language

The Stage teaches three roles through entry points and short, visible words: Scenery stays put, Props can be part of the action, and Ground is where stickmen walk. An identical drawing can be placed through Scenery or Props without implying the copies behave alike. Sky is chosen through its card, never by selecting an enormous rectangle in the Stage.

Keep the existing mode language: EDIT uses cyan/blue and a visible grid, DIRECT uses amber/gold and its camera frame, and PLAY uses green with clean artwork. Each active tool also has an icon and words; color alone never identifies it. All buttons, cards, chips, handles' pointer hit regions, and dialog actions have at least a 44 × 44 logical-pixel target. Control heights come from SandboxTheme tokens rather than local constants.

Flow at a glance

flowchart LR
    New[File → New] --> Gate[Protect unsaved scene]
    Gate --> Starter[Choose Blank, Town Street, or Living Room]
    Starter --> Edit[EDIT Stage]
    Edit --> Scenery[Scenery chooser]
    Scenery --> Sky[Choose Sky: changes immediately]
    Scenery --> Wall[Choose wall look → draw panels]
    Scenery --> Art[Filter artwork → choose drawing → place copies]
    Scenery --> Dress[Edit Scenery → select and change pieces]
    Dress --> Several[Select several → move or resize scenery together]
    Several --> Review[Keep changes or Cancel preview]
    Review --> Dress
    Edit --> Ground[Ground → choose look → paint walkable pieces]
    Wall --> Edit
    Art --> Edit
    Dress --> Edit
    Ground --> Edit

The chooser is for discovery and choice. Once an artwork or wall tool is chosen, it closes so the Stage is visible. A small capture bar below the top toolbar and mode pill carries the current task, Done, and ✕ Cancel. The cursor pill and ghost carry the immediate instruction at the pointer.

Concrete screen examples

Desktop, while placing a Tree:

┌ File ─────────────── ✏️ Edit | 🎬 Direct | ▶️ Play ─── Grid Snap ┐
│ [Ground]                                                       │
│ [Ramp]      ✏️ EDIT                                            │
│ [Step]       ┌──────────────────────────────────────────────┐   │
│ [Props]      │ 🌳 Tree stays put  [Far] [● Near] [Floor]    │   │
│ [People]     │ Place another tree  [Done]  [✕ Cancel]       │   │
│ [Scenery]    └──────────────────────────────────────────────┘   │
│ [Areas]                                                        │
│                        (translucent Tree ghost)                │
│                         🌳  Tree · Near                         │
│                       ─── ground / existing set ───            │
└────────────────────────────────────────────────────────────────┘

The Scenery chooser, opened from the left palette:

┌ Scenery: stays put ─────────────────────────────── [✕ Close] ┐
│ [Backgrounds]  [● Artwork]    [Edit placed scenery]          │
│ [All artwork] [Nature] [Buildings] [Walls]                   │
│ [Roads & paths] [Objects] [Unsorted, when needed]            │
│                                                              │
│   [ Tree preview      ]  [ Storefront preview ]             │
│   [ Tree              ]  [ Storefront         ]             │
│   [ Skyline preview   ]  [ Rug preview        ]             │
│   [ Skyline           ]  [ Rug                ]             │
│                                                              │
│ [Make artwork…]                                               │
└──────────────────────────────────────────────────────────────┘

Edit Scenery, with several pieces selected and a group resize preview:

┌ File ─────────────── ✏️ Edit | 🎬 Direct | ▶️ Play ─── Grid Snap ┐
│ [Scenery]   ✏️ EDIT     [Edit Scenery · 4 pieces] [Done editing] │
│              ┌──────────────────────────────────────────┐       │
│              │  ◇ fixed corner        old dashed bounds │       │
│              │  [wall] [window] [clock] [rug]            │       │
│              │                 new bright group outline  ◉      │
│              └──────────────────────────────────────────┘       │
│       ┌────────────────────────────────────────────────────┐     │
│       │ Resize 4 scenery pieces · Ground and Props stay put │     │
│       │ [Smaller] [Bigger] [Keep changes] [✕ Cancel]         │     │
│       └────────────────────────────────────────────────────┘     │
└──────────────────────────────────────────────────────────────────┘

These are relationship examples, not fixed pixel geometry. On a narrow viewport the chooser becomes a bounded, scrollable sheet with one card column if needed; filter chips wrap. It never opens wider or taller than the unobstructed screen. The top mode pill remains visible, and the chooser always has a reachable Close button. The capture bar wraps its text and stacks actions only when needed; it never hides the mode pill or the Stage point being placed.

Control layout and navigation

Stage palette and Scenery chooser

• Add one illustrated Scenery card to the existing vertically scrollable left palette. Keep Props and Ground as separate cards, with a short helper line in their chooser/tool: “Stays put”, “Can be part of the action”, or “Stickmen walk here.” The palette card opens the Scenery chooser rather than directly arming a tool.
• The chooser has a fixed title/Close row; Backgrounds and Artwork tabs; a scrollable body; and a fixed lower Make artwork… action when relevant. It is a chooser workflow, not a selected-object inspector. It receives SandboxTheme.control_theme() and its own popup tokens, while borrowing the Stage panel system's font, surface, selected, hover, focus, and target-size rules.
• Backgrounds shows two large category choices, Sky and Wall panel. Artwork shows a single-select filter row with All artwork, Nature, Buildings, Walls, Roads & paths, Objects, and conditional Unsorted. One drawing may carry several tags, so it appears under every matching filter. All artwork includes old, untagged drawings. Filters describe appearance, not behavior. Apply the same filters in the Props browser while keeping its title and placement role distinct.
• Use a FlowContainer for wrapping filter buttons and an adaptive card grid for previews. Each card has a large illustration, a readable name, and a visible keyboard focus ring. No card depends on hover to reveal its action. Changing tabs or tags preserves the chooser and moves focus to the first relevant control; closing returns focus to the Scenery palette card.
• A chooser Close or Esc dismisses only the chooser. Clicking outside may dismiss it when safe, but never chooses an asset or changes a Sky. A blank result shows “No artwork here yet” and offers All artwork and Make artwork… rather than an empty panel.

File → New starter chooser

• Run the existing unsaved-work Save/Discard/Cancel gate before offering a starter. Do not replace the open scene until a starter card is chosen. If the starter chooser is canceled, the current scene remains open; its dirty state reflects whether the child saved it at the gate.
• The themed modal uses three large illustrated cards: Blank Scene, Town Street, and Living Room, plus ✕ Cancel. Each card pairs a preview with one plain sentence: “Start from scratch”, “Shops, trees, sidewalk, and road”, or “A room with a window, rug, and furniture.” The cards wrap to fewer columns on narrower screens and remain scrollable. No tiny menu inside a card.
• Choosing a card creates a new unsaved scene with its suggested name in an editable name field. The name may be changed there or through the existing Rename Scene command. A small, dismissible on-Stage cue can say “Try Scenery to change this place” after Town Street or Living Room opens. It must not cover the Stage or block input.
• Blank starts with the existing neutral view and no Ground; the other two show editable ordinary pieces described in the accepted brief. Their cards must not promise a functional door, sitting, or automatic window cutting.

Backgrounds and placement

Sky

• Backgrounds → Sky opens four designed thumbnail cards: Clear Day, Cloudy Day, Sunset, Starry Night. The currently selected card has a strong border, filled selected state, and the text “Current Sky”; keyboard focus remains a separate outline.
• One tap or Enter/Space changes the Sky immediately; the chooser stays open so another card can be tried. Close means “stop choosing”, not “revert”. With no Undo in Phase 19, the child can restore the previous look by choosing its card again. Changing Sky never recolors or tints other pieces. Sky has no Stage selection handles or overlap entry.
• The thumbnail shows enough clouds, sun/moon, and color variation to predict the Stage result. A chosen Sky is static during PLAY and stable through camera movement.

Wall panel

• Backgrounds → Wall panel offers picture choices Paint, Brick, and Wood, plus a large preview of only the selected finish (Paint is a flat color; Brick and Wood show their texture). The selected-color tile replaces the chooser content and footer with the themed custom color view; Back to wall panel discards its draft and returns to setup, while Use color applies it and returns. The chooser's Recently used row is the only recent-color list. In the expanded setup chooser, Cancel exits and Draw wall panel starts placement; there is no separate Back or close-X action in that state.
• Choosing a look updates its preview. Pressing Draw wall panel closes the chooser and arms placement. The capture bar says “Drag across the space for a wall panel”, with Done and ✕ Cancel. The pointer has a corner reticle and a nearby pill “Drag to draw wall”. A press sets the first corner; dragging draws a world-anchored translucent patterned rectangle; release commits one finite panel. The pattern preview remains at sensible scale rather than stretching with the draft.
• Snap, when enabled, visibly aligns the draft to nearby grid lines. An unusably small draft shows a red outline and “Make the wall bigger”; release leaves no panel. A valid draft uses the EDIT accent plus a neutral outline and dimension cue. This is appearance only: a helper in the chooser says “Looks like a wall. Stickmen can pass through.”
• Touch can drag or tap the first and second corners. The first tap leaves a visible anchored corner and continuous rectangle preview; the second tap commits. The same visible Cancel and Done remain available. Right-click cancels a draft and exits the wall tool under the exit rules below.

Artwork and depth

• Choosing an artwork card closes the chooser, starts a translucent ghost under the pointer, and shows a capture bar with the drawing's name, Far, Near, On the floor, Done, and ✕ Cancel. Near is the default for a newly chosen drawing. Each depth choice has a simple layer illustration plus text; selected, hover, and focus states differ without relying on color. Changing depth updates the ghost's visible placement layer before commit.
• The cursor pill says “Click to place [name]”; on touch it becomes a small anchored Stage hint after the asset is chosen. Tap/click commits one copy. The ghost remains ready for another; after a commit the bar says “Place another [name]” and shows the count of copies placed in this tool session. Copies already committed remain when the tool closes. A repeat placement starts as another distinct piece.
• The selected artwork's source card may carry tag badges in the chooser, but tag words never suggest collision or interaction. The Stage preview says “Stays put”. Its depth affects appearance only; it does not grant blocking, pickup, support, Use, or event behavior.

Opening a wall panel for a window or doorway

• Wall-area erasing is easy to discover from either entry point: a selected wall panel's shared Scenery inspector includes a touch-sized Erase wall area action, and the Edit Scenery capture bar shows Erase wall area whenever nothing is selected. Either starts a dedicated tool with a translucent red, crossed rectangle preview and a visible capture bar: “Drag over the wall · release to erase”, Done, and ✕ Cancel. Snap-to-grid, when enabled, applies to both drag corners.
• Dragging a rectangle through one or more wall panels removes only the covered area. Each intersected panel is split into up to four remaining rectangles that retain its look and color. Brick/wood motifs keep a shared anchor, so the surrounding pattern does not restart at every cut edge. Existing artwork and other scenery are untouched; this is a visual opening, not a collision or doorway mechanic.
• Each valid release applies that opening immediately. Done, ✕ Cancel, right-click, or Esc exits the tool; canceling an in-progress drag discards only that draft, while previously completed openings remain. Phase 19 has no Undo, so keep the capture copy clear about this commit-on-release behavior.

Placement exit, cancel, and mode changes

State	Done	✕ Cancel	Right-click / Esc
Chooser open, no tool	Close chooser	Close chooser	Close chooser
Tool armed, only passive artwork ghost or wall corner cursor, no placement yet	Exit without placing	Exit without placing	Exit without placing
Active uncommitted wall draw or resize	Discard the draft, then exit the tool	Discard the draft, then exit the tool	Discard the draft, then exit the tool
One or more pieces committed, no active gesture	Keep pieces and exit	Keep pieces; discard only the next passive ghost and exit	Done: keep pieces and exit
One or more pieces committed, another gesture active	Keep prior pieces; discard current draft and exit	Keep prior pieces; discard current draft and exit	Cancel current draft, keep prior pieces, then exit

A passive artwork ghost does not count as an active gesture; a pressed wall corner, two-tap first corner, or resize drag does. Releasing a mouse button after cancellation cannot commit the old draft. The capture bar keeps a short line “Placed pieces stay” once any copy has committed, so Cancel does not falsely imply that all prior placements are erased. Right-click is an optional pointer shortcut; Done and Cancel stay visible for touch and keyboard users. Switching to DIRECT/PLAY or opening another Stage tool discards an active draft, preserves completed pieces, and removes all ghosts, handles, and capture prompts. No new Undo control or shortcut is introduced here.

Edit Scenery and selected-object cards

• The Scenery chooser has a large Edit placed scenery action. It closes the chooser and enters a clearly labeled “Edit Scenery” state inside EDIT, with an on-Stage pill and prominent Done editing button. The global mode remains EDIT and its mode pill remains visible. Done editing, Esc when no edit gesture is active, or switching modes returns to ordinary selection. Esc during a resize or move first cancels that draft and leaves Edit Scenery active. The child can reopen Scenery to place more pieces.
• Ordinary EDIT click/box selection favors characters, Props, Ground, and existing interactive objects; broad wall panels, Far/Near artwork, and floor art do not enter those results. In Edit Scenery, only wall panels and Scenery artwork enter click/box selection. The selected piece gets a bright outline backed by a dark halo, a text name/depth label, and large move/resize handles with at least 44 × 44 logical-pixel hit regions at common zoom. A single-piece drag previews live and commits immediately on release; uniform resize keeps the opposite corner visibly pinned, and the transform affects only that placement. It has no extra Keep confirmation. While the pointer/finger is held, a compact capture bar offers ✕ Cancel for touch users; Escape, right-click, or leaving Edit Scenery also cancels the active gesture and restores the pre-drag position/size. Releasing the gesture commits without waiting for another choice. A later Stage Undo action is deferred to its own phase and tracked in technical debt. The selected-artwork card also offers large Smaller and Bigger actions for users who prefer buttons; each applies one immediate, proportion-preserving size step to that placement only. Existing placement sizes are not automatically changed when this feature is added.
• When pieces overlap, a small cutout under the pointer takes priority over a broad panel. Clicking a panel's exposed area or edge selects it. If several pieces still match, show a themed “Pieces here” chooser with one large labeled row per candidate and a visible Close. A selected panel also remains reachable through that chooser when its visible area is covered. Box selection in Edit Scenery includes only Scenery pieces; ordinary box selection does not gather broad scenery.
• A selected Scenery artwork card uses StageInspectorPanel and StagePanelChoiceGroup. The header has the drawing name, icon, and Close. The body offers an illustrated Where it appears group with Far, Near, and On the floor, large Smaller / Bigger size steps, and Erase scenery. A selected wall card uses the same shell, with Wall panel header, Look, Color, and Erase wall panel. Each change applies only to that selected piece. These cards have a fixed Close, scrollable body, and the established compact Settings reopen button while the same piece remains selected. Closing the card does not exit Edit Scenery.
• An Erase action for a wall or artwork asks “Erase this piece?” with Keep it and Erase buttons before removing it, because Phase 19 has no Undo. The Delete key follows the same safeguard for selected Scenery.
• Sky is never listed in Pieces here, never box selected, and never shown in the selected-piece card. Its only edit path is Backgrounds → Sky.

Artwork file missing after reopen

• A missing live .prop reference leaves a real, saved Scenery placement at its authored position and Far/Near/On the floor depth. On the Stage, draw a soft neutral translucent footprint with a dashed light-and-dark outline when the saved extent is known; otherwise draw a compact world-anchored marker at the saved point. A constant-screen-size picture/question icon and label say “Artwork not found”, followed by a short remembered drawing name or file name when available. Do not use a large red error block, expose a full file path on the canvas, or show an empty gap that looks like the child erased the art. Keep the marker legible on all four Skies and on common Ground/wall looks. In DIRECT and PLAY, the placement remains a subdued neutral marker at the same layer, without edit handles or repair controls, so the missing set piece is still evident without covering the action.
• On scene open, reuse the existing missing-assets summary dialog with calmer copy: “Some artwork could not be found. Your scenery spots are still here.” List the friendly names and offer “Show scenery” and “Later”. Show scenery enters Edit Scenery and focuses the first missing placement; Later closes the dialog and leaves every marker visible. This summary appears once for the load, not on every frame or selection. It does not replace the existing stickman/Prop warning semantics; the missing-Scenery wording is scoped to Scenery.
• In ordinary EDIT, the footprint and label are visible but the missing placement's broad bounds do not enter normal click or box selection. Its small, explicit Find artwork badge has at least a 44 × 44 hit target and can switch to Edit Scenery with that placement selected; the badge alone takes input, so a child can still select a character, Ground, or Prop in front of the marker. The Stage palette's Edit placed scenery path and a Needs artwork section in the Scenery piece list provide alternatives when the badge is covered or offscreen.
• In Edit Scenery, the missing placement participates in Scenery selection and Pieces here with a distinct picture/question icon and “Artwork not found · [name]” row. Selecting it shows the normal StageInspectorPanel shell headed “Artwork not found”, with the remembered name, its saved depth, and large actions Find artwork…, Choose another artwork, Keep for now, and Erase scenery. An optional File details disclosure may show the saved path for a helping adult; the path is not the primary instruction. The neutral marker remains visible when the card is closed, and the compact Settings reopen control works as for other Scenery. If the original size is unavailable, do not show misleading resize handles; explain “Find artwork to change its size.” Moving the marker and changing its depth remain possible without making it solid or interactive. It can join Select several for group moves; if any selected member lacks a known footprint, disable Resize together with the same plain-language reason until that artwork is repaired.
• Find artwork… opens the established themed .prop file chooser so the child can point to a moved file. Choose another artwork opens the same responsive Artwork gallery used for placement, explicitly labeled as a replacement choice. After either choice, show a ghost of the candidate at the saved position, size/scale, orientation, and depth where those saved values exist, and ask “Use this artwork here?” with Use artwork and ✕ Cancel. The replacement can be adjusted afterward; do not silently alter Ground, Props, or other Scenery. Canceling the chooser, file dialog, or preview leaves the missing marker and saved reference untouched. An unsuccessful file load returns to the same marker/card with a plain “Could not open that artwork. Try another file.” message. Erase uses the shared “Erase this piece?” confirmation; only confirmed Erase removes the placement. If several places reference the same missing file, default to repairing the selected place only; an explicit Use for all matching places choice may be offered, with the affected count shown before confirmation.
• The placeholder, badge, piece-list row, preview actions, and dialog work by touch and keyboard: focus is visible and distinct from the missing state; Tab reaches the badge/list, actions are at least 44 × 44, Enter/Space activates them, Esc closes a chooser or cancels an uncommitted preview, and focus returns to the selected placeholder/card. On a narrow viewport, the label truncates gracefully to the remembered name, the inspector body scrolls below a fixed header/Close, and its actions wrap or stack without hiding the mode pill. A missing marker is identified by icon and words as well as outline, never by color alone.

Move or resize several Scenery pieces

• Select several is a large, explicit action within Edit Scenery. While it is active, tapping pieces adds/removes them without beginning a move. A touch-friendly, scrollable piece list offers each piece's thumbnail/name/depth and a large selection row; it provides Select all scenery and Clear selection. Box selection may add Scenery pieces under the same filter. Select all scenery means every wall panel plus every Far, Near, and On the floor Scenery artwork placement in the open scene. Sky, Ground, characters, and interactive Props are never included. There is no automatic starter-wide group or persistent lock between pieces.
• With two or more pieces selected, show a halo-backed union outline, a separate outline on each member, and the text “N scenery pieces selected”. The selected-object card uses the shared StageInspectorPanel shell with Move together, Resize together, Clear selection, and a short explanation “Ground and Props stay put.” It does not show a single shared depth, finish, or color control, because mixed members may have different settings. The group outline and count appear on the canvas, not only in the card. Closing the card follows the normal compact Settings reopen behavior and leaves the selection visible.
• Move together starts a live preview. Dragging the group or using large on-screen arrow buttons applies the same world-space offset to every selected Scenery piece, preserving their relative spacing and Far/Near/On the floor choices. The original outlines remain faint/dashed while the candidate positions have bright outlines. Snap, if enabled, moves the selection as a unit from its anchor without rounding members independently. A cursor pill says “Move N scenery pieces”.
• Resize together starts a live uniform-size preview. Drag a group corner inward/outward; the opposite corner shows a fixed pin and does not move. Every selected artwork piece changes size and position by the same positive scale around that anchor, retaining its proportions and relative layout. Wall panel rectangles change size and position with the group, while Brick/Wood motifs retain their world-scale size and alignment instead of stretching. Far/Near/On the floor choices remain unchanged. Clamp or reject a preview that would collapse or flip any piece; show “Too small” with a blocked outline. The cursor pill says “Resize N scenery pieces” and identifies the fixed corner with a visible pin.
• During either group preview, the on-canvas capture bar shows Keep changes and ✕ Cancel, the selection count, and “Ground and Props stay put.” Releasing a pointer leaves the preview pending; it does not save a change or newly mark the scene dirty. Keep changes commits the whole preview as one edit and marks the scene dirty once. Cancel, right-click, or Esc restores the exact pre-preview positions and sizes and returns to the same multi-selection in Edit Scenery. A later mouse/touch release cannot commit a canceled preview. Done editing or switching modes while a preview is pending first cancels it, then exits Edit Scenery. A Save request while a preview is pending asks the child to Keep changes or Cancel before saving; it never silently saves the draft.
• The group tools are operable without precise dragging: touch targets and corner hit areas are at least 44 × 44 logical pixels; large move arrows and Smaller/Bigger buttons give touch and keyboard users repeatable steps. Pointer users may drag any corner and see its opposite fixed pin; the button path starts with the top-left corner fixed and labels that choice. Every control is focusable, has a visible focus ring and text label, and responds to Enter/Space. On a narrow viewport, the multi-selection card scrolls beneath its fixed Close, the capture bar stacks its actions, and arrow/size buttons remain reachable even when a group corner lies offscreen. The mode pill and Stage preview remain unobstructed.
• A committed group transform saves each member's new position and size through the normal scene save; depth, finish, physics, and interaction roles do not change. The temporary multi-selection, preview, and group outline do not persist on reopen. A whole-set transform that also moves/scales Sky, Ground, characters, or interactive Props is outside Phase 19 and belongs to a separately designed future feature.

Single-artwork direct resizing and multi-piece group resizing intentionally have different commit gestures: one artwork placement commits on handle release, while a group retains the existing snapshot preview with Keep changes / ✕ Cancel. Do not add a single-piece confirmation bar as a substitute for deferred Stage Undo.

Stage-relative authoring size in Prop Editor

• In Arrange, replace the fixed-target Normalize Size action with Size for Stage. It opens a reversible sizing view with Small, Room, and Big starting sizes and fine Make smaller / Make bigger adjustments. The presets are rough visual starting points relative to the standard standing stickman, not rigid limits; preserve the asset's proportions and let the child inspect the actual comparison before keeping it. Exact preset ratios are an architecture/implementation detail, not new UI copy.
• Frame the complete artwork and guide together when the sizing view opens. Show a standing stickman at the standard 1:1 reference scale in front of the artwork, plus a clear floor/contact line near ankle level. Use a dark halo with a light core so the guide remains visible over any fill. The guide is editor-only and never becomes part of the saved artwork. The guide is visible whenever Show Stickman Guide is on and is forced on while Size for Stage is active.
• Keep size applies the preview to the authored shapes and returns to Arrange; ✕ Cancel restores the exact pre-preview shape geometry. Existing whole-prop Transform behavior remains the way to move/rotate/resize all shapes and editable anchors together. Keep this sizing action within the established Prop Editor Arrange toolbar and PropTheme; do not reuse the Stage inspector card for a distinct editor workflow.
• Artist-created and newly authored vector artwork should already be drawn at its intended Stage size, so first placement is normally scale 1 relative to the authored artwork. The standard figure is about 940 world units tall. Prop names should guide an ordinary-object size estimate; the asset review records approximate intended bounds relative to the stickman (height, and width when useful) and includes a scale-check preview. The sizing view is a correction/authoring aid, not a required step for every asset.
• Loading existing .prop files and scenes performs no automatic normalization and retains saved placement transforms. Keep size deliberately changes the authored geometry; saving over the same .prop uses the existing live-reference behavior, so scenes using that drawing show its revised artwork on reopen. Keep the current Save and Save As workflow; this addition introduces no extra copy/version prompt or overwrite confirmation.

Ground finish workflow

• The existing Ground palette entry gains a New Ground look chooser with large picture swatches: Paint, Brick, Wood, Grass, Dirt, Sidewalk, Asphalt. Paint, Brick, and Wood use the same names and comparable preview motif as wall finishes. A chosen swatch becomes the active look for future Ground only. The chooser states “New Ground will look like this” and never silently repaints existing pieces.
• Returning to the Stage shows a patterned Ground ghost for one tap or the existing drag-paint run. A small cursor pill says “Click or drag to add Ground” and the capture bar provides Done and Cancel under the exit rules above. Valid/blocked stroke previews use outline, symbols, and short words as well as color. Adjacent ghost pieces show a continuous-looking pattern. Ramp and Step keep their existing appearance and palette behavior.
• Selecting an existing Ground piece in ordinary EDIT opens a Ground StageInspectorPanel card with This Ground's look, the same finish swatches in a StagePanelChoiceGroup, and any existing Ground controls. Selecting a finish here changes only the selected piece. The different headings New Ground look and This Ground's look make scope visible before a tap.
• In PLAY, Ground keeps its walkable behavior and chosen look. Wall panels, road markings, and rugs never look like a selectable walking surface in the UI.

Prop Editor route for Scenery artwork

• Make artwork… in the Scenery chooser uses the existing vector .prop authoring tool; there is no separate Scenery Editor or file type. When entered from Scenery, its first screen is framed as “Make artwork for your scene” and foregrounds vector drawing, color, shape arrangement, naming, and Save. Hide prop-only material, mass, bounce, collision, Use/attachment, and other action controls from this entry route. Do not require a pretend solid shape to save visual-only artwork.
• The Props entry route retains prop-relevant controls and its distinct “Make a Prop” framing. If a drawing is valid for both roles, the child may find it in both browsers; the Stage placement entry point decides what the copy does. After a successful artwork save, offer “Place it as Scenery” and return to the Artwork chooser focused on the saved drawing. Cancel/exit returns without changing the open Stage.
• Tag editing uses the same large multi-select choices Nature, Buildings, Walls, Roads & paths, and Objects in artwork authoring. The words are descriptive, optional, and never gate the All artwork view. An untagged saved asset remains discoverable under All artwork and conditional Unsorted.

The Size for Stage workflow above applies to both Scenery artwork and Props because they share the same .prop authoring canvas. It does not change the Stage role distinction: a Scenery placement remains inert and non-colliding, while a Prop retains its existing interaction and physics settings.

Theme, components, and accessibility contract

• For selected wall, artwork, and Ground cards, reuse StageInspectorPanel for the fixed header, safe rect, body scroll, Close, focus, and reopened Settings button pattern. Reuse StagePanelChoiceGroup for exclusive depth/finish choices with stable labels and decorative preview cues. StagePanelToggleRow and StagePanelSwitchVisual remain available for true on/off settings but are not forced into this feature's depth or finish choices.
• The multi-selection card also reuses StageInspectorPanel and stage_panels.action for its large Move/Resize/Clear actions; its member list and preview controls add tokens under stage_panels rather than hardcoded colors or sizes. The group capture bar extends the same transient Stage capture pattern used for placement, keeping its instruction and Cancel together below the mode pill.
• Extend the stage_panels SandboxTheme tokens only where these cards need new preview-cue size, card spacing, or scenery-specific accent/selection outlines. Continue using stage_panels.shell, .type, .choice, and .action for geometry and typography, and mode_colors.edit for the EDIT accent. The Scenery chooser, starter modal, color dialog, and Ground chooser use popup/theme tokens and SandboxTheme.control_theme(); their layout is distinct from an in-stage inspector. Generalize the existing Stage capture-bar look for wall/artwork/Ground placement instead of copying fixed styling.
• On narrow or short viewports, chooser contents scroll, filter chips wrap, card columns collapse, the inspector header/Close remain fixed, and the capture bar wraps/stacks within safe margins. Never let a panel cover the EDIT/DIRECT/PLAY mode pill. Decorative thumbnails and cue drawings ignore pointer input; each actual choice is one native focusable Button with Space/Enter activation. Focus moves into an opened chooser/card and returns to the opener on Close when possible.
• Pointer, touch, and keyboard all reveal the selected state, hover where applicable, focus, disabled reasons, and confirmation. No instructional step exists only in a top header, bottom status bar, hover tooltip, or shortcut. Cursor pills remain near the pointer without covering it; they flip to stay in view. Touch users get the same instruction anchored near the draft plus always-visible Done/Cancel.

Reuse and standardization audit

This matrix identifies current UI that already exists. “Extend/share” is a design requirement to converge repeated controls; it does not prescribe a class, signal, or file contract for the architect.

Phase 19 surface	Existing source to use	Reuse decision and boundary
File → New and unsaved-work gate	StageChrome File menu; StageModalViews unsaved ConfirmationDialog; Stage document flow	Direct reuse. Preserve Save/Discard/Cancel, focus, and the current scene until a starter is chosen. Do not make a second unsaved-work dialog.
Illustrated starter chooser	AssetCard, AssetSelector scene/shell, StageModalViews dialog theming and Rename Scene name entry	Extend/share the card-gallery presentation. The three starter cards need a responsive grid, scroll, Close/Cancel, and selected focus behavior also needed by Scenery/Sky/finishes. The editable suggested name follows existing name-entry styling/validation; starter composition remains feature-local. This is a modal choice, not StageInspectorPanel.
Scenery chooser and Artwork cards	AssetSelector, AssetCard, StageAssetBrowser, thumbnail cache/renderers, scenes/stage/asset_selector.tscn	Extend/share the gallery shell and card behavior, reuse browsing/thumbnail work. The current selector is a fixed four-column paged popup and sets card focus to FOCUS_NONE; these must be corrected for responsive layout and keyboard use in the common path rather than copied into a Scenery-only popup. Backgrounds/Artwork tabs use native button choice states and shared popup styling; placement-role text stays feature-local.
Sky and wall/Ground finish cards	AssetCard and the responsive gallery behavior above; SandboxTheme popup/card tokens	Share the same preview-card and focus/selected-state rules. Sky and finishes supply their own preview imagery and one-tap selection meaning; card dragging is disabled for these choices. They do not pretend to be .prop assets or reuse StageAssetBrowser asset scanning. Wall and Ground share names/preview motifs for Paint, Brick, and Wood.
Artwork tags, Props filters, authoring tags	No existing reusable tag-chip control; StagePanelChoiceGroup is a vertical exclusive inspector control; Stage speech UI demonstrates HFlowContainer wrapping	Extract one shared wrapping filter/choice treatment. Use native focusable buttons and one theme contract across Scenery browsing, Props browsing, and optional multi-tag authoring. Single-choice browser filters and multi-choice authoring use the same visual states but different selection rules. Do not clone local chip styling or force the vertical inspector group into a wrapping browser row.
Wall Color and custom color view	ColorSwatchSelector; native ColorPicker in the themed Stage view	Extend/share the color-swatch treatment so it wraps on narrow screens, has visible chosen/focus states, and uses Stage tokens. Open custom color selection from the selected-color tile, keep one recent-color row in the chooser, and provide Back to wall panel / Use color actions. The Prop Editor's PropTheme styling is not a Stage style source; wall/color values remain feature-local.
Scenery overlap Pieces here	StageModalViews.show_objects_here() and its themed, viewport-clamped, scrollable PopupPanel	Generalize the existing overlap chooser. Supply Scenery-only candidates and child-facing piece names/depth, while retaining the same placement, 44 px rows, dismiss, and focus behavior. Do not create a second overlapping-items popup.
Missing Scenery artwork	Existing MissingPropPlaceholder/MissingStickmanPlaceholder preserve missing placements; StageModalViews missing-assets dialog; StageInspectorPanel; StageAssetBrowser gallery/file chooser	Reuse and generalize the recovery path. Keep saved placement continuity and one themed load summary, but give Scenery its neutral labeled marker, selection-card repair actions, and the existing artwork/file choosers. Do not copy the older red marker styling or create a second asset gallery or dialog skin.
Erase this piece?	StageModalViews confirmation/dialog theming; existing Erase Use spot ConfirmationDialog and safe/danger treatment in SandboxStage	Reuse the confirmation pattern. Share the button sizing, themed window, and danger/safe styles instead of copying the spot-erase styling into another private function. The affected piece and wording are local.
Placement and group-preview bar	StageUseTargetCaptureBar and the transient capture-bar contract in stage_panel_ui_system.md	Generalize/extract the capture-bar shell for EDIT prompts, mode accent, Done/Keep changes/Cancel, responsive stacking, and a safe position below the mode pill. Keep Use-target-specific wording/actions in its caller; do not build a second bar with copied colors/geometry.
Cursor pill and Stage ghosts	StageChrome action tooltip/cursor, current placement ghost/terrain overlay, SandboxTheme.overlays	Extend/share presentation and safe cursor positioning while the wall/artwork/Ground draft visuals remain feature-local. Keep one visual language for valid/blocked, mouse/touch feedback, and cancellation; do not copy the current tooltip's hardcoded colors into Phase 19.
Selected artwork, wall, Ground, and multi-selection card	StageInspectorPanel, StagePanelChoiceGroup, StagePropSettingsView dismissal/reopen behavior, stage_panels tokens	Direct reuse of inspector shell and exclusive choice group; extend shared action styling only as needed. These are in-stage selected-object cards. Their data, headings, member list, and commands stay feature-local. StagePanelToggleRow/switch are reserved for real on/off values and are not substitutes for depth or finish choices.
Erase wall area tool	Selected wall's StageInspectorPanel or the no-selection Edit Scenery StageUseTargetCaptureBar; wall ghost/placement logic in StageSceneryController	Reuse the selected-object action styling and existing transient capture bar. Only the cutout rectangle preview and rectangle subtraction are feature-specific; do not add another toolbar or dialog.
Select-several member list	StageInspectorPanel body/action styling; StageModalViews large selectable-row precedent	Reuse row sizing, focus, selected, and scroll rules. Membership logic and piece labels remain local to Edit Scenery; do not invent another inspector shell or tiny checkbox list.
Make artwork… and return	Existing Prop Editor scene/controller and .prop authoring; StageAssetBrowser refresh/thumbnail path	Reuse the existing editor and asset browser. The Scenery entry changes the visible authoring framing and hides prop-only controls; it does not create another editor, file picker, art card system, or .scenery format. The return-to-Stage handoff is feature-local.
Stage-relative size in Prop Editor	Existing Prop Editor Arrange toolbar, whole-prop transform, Normalize Size path, stickman guide, and PropTheme	Extend the existing authoring workflow. Replace the fixed 96-unit normalization target with the reversible Size for Stage preview and front-drawn guide; keep the authoring figure/editor chrome local to Prop Editor. Do not adopt StageInspectorPanel for this editor-only interaction or change existing saved assets automatically.

For every row, new dialogs/popups explicitly receive SandboxTheme.control_theme() and the established Stage dialog style, with their visual values read from SandboxTheme/sandbox_theme.json (popups, palette, stage_panels, chrome.dialogs, mode_colors, and overlays as appropriate). The existing StageModalViews.apply_dialog_theme() handles font/child overrides but is not, by itself, a substitute for assigning the control theme to a new window. Reuse local stylebox instances rather than mutating the cached shared Theme. Keep popup gallery behavior separate from the in-stage inspector layout while making their type, spacing, focus, and selected states consistent.

The existing QueuePanel, RulePanel, ActionEditor, and speech popups in scenes/editors/stage/ solve different editing tasks. They can inform theme and responsive-container choices, but are not replacement shells for a starter or art gallery. Any new Stage popup should pass the same theme, sizing, focus, and dismissal checks as those existing workflows.

Exact child-facing copy map

Context	Text
Palette entry	Scenery; helper Stays put
Props distinction	Props; helper Can be part of the action
Ground distinction	Ground; helper Stickmen walk here
Scenery tabs	Backgrounds, Artwork
Edit action/state	Edit placed scenery, Edit Scenery, Done editing
Multi-selection	Select several, Select all scenery, Clear selection, N scenery pieces selected
Group action/preview	Move together, Resize together, Ground and Props stay put, Keep changes, ✕ Cancel
Group adjustment	Smaller, Bigger, Too small
Wall category/helper	Wall panel; Looks like a wall. Stickmen can pass through.
Wall cursor/draft	Drag to draw wall; Make the wall bigger
Artwork cursor	Click to place [name]; after first copy Place another [name]; during direct resize Resize [name]
Placement actions	Done, ✕ Cancel; after a commit Placed pieces stay
Ground palette/inspector	New Ground look, This Ground's look
Overlap chooser	Pieces here
Missing artwork	Artwork not found, Find artwork, Needs artwork, Show scenery, Later
Missing artwork repair	Find artwork…, Choose another artwork, Keep for now, Use this artwork here?, Use artwork, File details
Repair failure	Could not open that artwork. Try another file.
Erase safeguard	Erase this piece?, Keep it, Erase
Starter cards	Blank Scene, Town Street, Living Room
Stage-relative size	Size for Stage, Small, Room, Big, Make smaller, Make bigger, Keep size, ✕ Cancel, Show Stickman Guide
Single Scenery resize	Smaller, Bigger; a handle drag commits on release
Wall opening tool	Erase wall area, Drag over the wall · release to erase; Erase another area · earlier openings stay

Do not expose “entity”, “collision hull”, “z-index”, “physics layer”, “finish ID”, or “depth tier” as child-facing copy.

Observable UI review scenarios

1. Create Town Street from File → New, cancel at the starter chooser once, then choose it. The old scene persists on cancel; the starter appears as an editable unsaved scene with its sky, Ground, and separate set pieces.
2. Choose Tree under Scenery → Artwork → Nature, change Far/Near/On the floor, place two copies, and right-click. Both copies remain, the passive ghost disappears, and ordinary EDIT selection returns. Repeat with an unfinished wall drag: right-click discards only that draft.
3. In ordinary EDIT, click and box-select a character and Prop in front of a room wall without selecting the wall. Enter Edit Scenery, select a window cutout, then choose the broad wall through its exposed area or Pieces here. Start a direct resize and cancel the still-active gesture before release; its old bounds return. Release a second resize and verify it commits immediately, with no Keep prompt.
4. Change Sky through all four cards while the Living Room window remains visible. The room colors stay unchanged; Close leaves the last chosen Sky, and keyboard focus returns to Scenery.
5. Select Wood for New Ground, paint a run, then select one existing Ground piece and change only that piece to Brick through This Ground's look. A selected wall panel's own Finish/Color changes only that panel.
6. At a narrow viewport and with touch/keyboard input, reach every chooser card, depth choice, Cancel, Done, inspector Close, and overlapping-piece choice without clipping or relying on hover. Enter PLAY and confirm all ghosts, handles, and edit-only bars disappear.
7. In Living Room, use Select several to choose two wall panels, the window frame, and rug. Preview a shared move, cancel with right-click, and verify all four return exactly to their original locations while Wood Ground and furniture remain still. Preview a uniform corner resize, check the opposite anchor stays fixed and wall motifs do not stretch, then Keep changes; save and reopen. The four pieces retain their new positions/sizes and original depth/finish, while the temporary group selection is gone. Repeat the preview with touch or keyboard controls in a narrow viewport, using Esc to cancel.
8. Save a scene with two copies of one live .prop Scenery drawing, then make the file unavailable and reopen the scene. The friendly missing-art summary appears once; both labeled markers remain at their saved positions/depths through EDIT and PLAY. In ordinary EDIT, select a character in front of a marker without selecting Scenery. Use a marker's Find artwork badge or the Edit Scenery Needs artwork list to open its card. Cancel a file choice and verify both markers remain. Choose a replacement for one copy, preview then cancel once, then confirm it; only that copy changes. Confirm the second still has a marker after save/reopen until it too is repaired or deliberately erased. Repeat the repair path with keyboard and on a narrow touch viewport.
9. In Prop Editor, open Size for Stage on representative tall, wide, and small artwork. Confirm the standard stickman is drawn in front, the floor/contact guide is visible over every fill, the preview frames both together, presets and fine adjustments preserve proportions, Keep size applies, and ✕ Cancel restores the exact prior geometry. Confirm new placement uses the authored size and loading an existing file performs no automatic normalization. Deliberately save revised geometry over a referenced asset and confirm the usual Save flow and live-reference update on reopen, with scene placement transforms retained. In Edit Scenery, resize one placement and confirm it commits on release and saves/reopens; cancel a still-active drag with Escape/right-click and with the touch capture bar; verify other scenery and Props stay unchanged. Compare this with the separate group Keep/Cancel flow. Repeat sizing-guide visibility and Stage handle/button access with keyboard/touch and at a narrow viewport.