stickman/docs/specs/phase_17c_impact_wobble_ui.md

Phase 17c — Impact wobble: UI/UX specification

Status: UI/UX design selected; architecture and implementation follow. Source: Phase 17 — Props for Storytelling. Scope: The child-facing setting and visual feedback for impact wobble on a placed prop in the Sandbox Stage. This document leaves hit detection, persistence, and animation ownership to the architecture specification.

Child flow

1. In EDIT, the child selects one placed prop. Its existing settings card opens with the prop's name in the fixed header. Under When bumped, the child turns on Wobble when bumped. The selected prop shows one brief sample wobble in place, then settles. Turning the switch off stops a sample that is still playing.
2. The child starts PLAY. A noticeable physical hit makes the enabled prop wobble briefly and settle. It can wobble whether it began PLAY in place or Can fall and move. A moving prop continues its normal physical movement during the visual wobble. Ordinary resting contact does not make it shake repeatedly.
3. Stopping PLAY ends any active wobble and restores the prop's authored appearance and placement. The saved On/Off choice remains on this placed copy of the prop.

EDIT card layout and states

Existing StageInspectorPanel
├─ Fixed header: prop icon / selected prop name / ✕ Close
└─ ScrollContainer / VBoxContainer
   ├─ Existing depth, starting motion, and collision controls
   ├─ Existing After letting go section, when applicable
   ├─ When bumped: section heading
   │  └─ Wobble when bumped: StagePanelToggleRow
   │     ├─ Short helper line
   │     └─ Fixed-position switch + ON/OFF text
   └─ Existing Use spots section

• Add the heading and one full-width StagePanelToggleRow to the existing StagePropSettingsView body. Keep StageInspectorPanel's selected-name header, fixed ✕ Close, scrolling body, safe-area fit, selection dismissal, and compact Settings reopen button. The switch belongs to one selected placed prop; it does not edit the reusable .prop asset or every prop of the same type.
• The row is available for Stays in place and Can fall and move props, including a prop currently configured to let stickmen or other props pass through it. A pass-through prop may have no qualifying hit in its current setup, but the child may change its behavior later or release it with different collision settings. Keep the choice and its preview available without a disabled state or an extra prerequisite control.
• The switch starts OFF for a placement with no authored wobble choice. Its ON/OFF text, knob position, selected surface, and border show the state without relying on color. Keep the caption stable when toggled. The row stays at least 44 logical pixels high and follows the larger applicable stage_panels.toggle.minimum_height value. All of the row is one pointer/touch target; keyboard focus is visible and Space/Enter activates it once.
• Show the same short helper in both states: A hard bump makes this prop wobble once in PLAY. It sets an expectation for the effect without exposing impact strength or a force slider. Help wraps within the row; the switch and ON/OFF label remain anchored at the top when the card width or font size changes. On a short stage, only the body scrolls, so the header and Close remain reachable.
• Pressing the switch applies the choice immediately and marks the scene as changed. Closing the card keeps the choice. Reopening the card displays its current state without replaying the sample. Selecting another prop displays that prop's own choice. Multiple selection continues to show the existing Select one prop to change its settings. notice.

On-stage preview and PLAY feedback

• Turning ON in EDIT plays one short, controlled sample on the selected prop and its selection outline, then returns both to their authored appearance. The sample is visual only: it does not move the prop's authored position, rotate its collision shape, start physics, or change the saved scene. It also works on a pass-through prop, since it demonstrates the selected setting rather than claiming a collision has occurred.
• A sample remains attached to its prop while the stage view pans or zooms. Preserve the prop's behind/in-front draw tier; do not temporarily move it in front of other artwork. If another object partly covers it, the selected outline makes the sample easier to spot. Use a modest amplitude and a quick settle so the prop still looks stable. Do not add an instructional cursor, ghost path, or capture bar: this is a direct switch, with no stage click to complete.
• Turning OFF, changing selection, leaving EDIT, or starting PLAY cancels an EDIT sample cleanly. Switching ON again plays one new sample. The switch's state remains the durable feedback even when the selected artwork is covered.
• In PLAY, each qualifying hit yields one readable wobble that settles. A prop using Can fall and move must wobble while it is falling, sliding, or otherwise moving; the wobble rides along with that movement instead of freezing, snapping, or replacing it. Wobble is a visual response and does not imply toppling, breaking, a change of collision behavior, or a rule firing. Existing collision rules remain the way to author more elaborate consequences.
• Resting contact and ongoing contact must not produce a constant shake. A later separate meaningful hit can produce another wobble. The visible result should be similar for a stationary prop hit by a moving stickman and a moving prop that strikes another object; the architecture spec will define the hit-strength rule.
• PLAY uses the normal clean green stage presentation. No persistent wobble icon, instruction pill, or effect label covers the movie. Stopping PLAY removes any active wobble before EDIT returns and restores the authored prop appearance and placement. If the project later offers reduced animation, use a brief static emphasis as the equivalent hit cue.

Shared controls, theme, and accessibility

• Reuse StageInspectorPanel, StagePanelToggleRow, and its StagePanelSwitchVisual from scripts/shared/stage_ui/. The existing StagePanelChoiceGroup still handles depth and starting motion; wobble is one independent switch. Extend StagePropSettingsView rather than building a second inspector or a floating settings widget.
• Use SandboxTheme's stage_panels.shell, .type, .toggle, and .action tokens for layout, fonts, row surfaces, borders, hover, selected, disabled, and focus states. The EDIT accent comes from mode_colors.edit; PLAY presentation follows the existing mode_colors.play. If the visual sample or wobble needs configurable duration, angle, or offset, add named effect tokens to both sandbox_theme.json and SandboxTheme defaults during implementation. Do not hardcode UI colors or font sizes.
• The card must remain usable at narrow widths and enlarged fonts. The helper wraps without clipping or moving the switch out of reach. Focus remains visible over the ON state. The control can be used with pointer, touch, or keyboard, and its ON/OFF text communicates state without color.
• The existing ✕ Close and Settings controls remain at least 44 × 44 logical pixels. The switch does not enter a capture workflow, so it needs no separate Cancel button. EDIT selection and the existing Objects here chooser continue to make covered props reachable.

Exact child-facing copy

Context	Copy
Card heading	When bumped
Switch caption	Wobble when bumped
Switch state	ON / OFF
Helper, both states	A hard bump makes this prop wobble once in PLAY.
Existing card actions	✕ Close / Settings

There is no child-facing force, impact threshold, frequency, or strength control.

UI review criteria

1. Selecting one placed prop shows the new switch in the existing card. Its state is readable without color, and it remains reachable on a short or narrow stage with enlarged fonts.
2. Switching ON previews one brief wobble on that selected prop, including when it is set to pass through others. Switching OFF or leaving EDIT cancels the sample and leaves the authored placement unchanged.
3. Two placed copies of the same prop can show different ON/OFF choices. Closing and reopening the card, saving and reloading the scene, and entering and stopping PLAY display the correct choice for each copy.
4. A qualifying hit produces one short visible wobble on both stationary and currently moving physics props. Normal movement continues, resting contact does not shake repeatedly, and stopping PLAY clears the visual effect.
5. Pointer, touch, and keyboard activation each change the switch once. The focus state remains visible, and the helper and switch do not clip or jump when the card reflows.