stickman/docs/specs/speech_bubble_layout_presets.md

Speech Bubble Layout Presets

Status: Implemented; awaiting user verification (2026-10-01).

Interaction

Provide three pictorial, one-tap actions to the whole-speech stage panel under Bubble layout:

• Stack keeps Bubble 1 at its current center, then arranges each later bubble above the previous one. Use measured frame heights and the existing stack gap so large text does not overlap. Alternate a small horizontal offset to make the group read like comic panels.
• Same spot places every bubble at Bubble 1's current center, so the speech can take turns from a shared location. These are placement actions, not toggle choices. Their buttons do not keep a selected state. Each action updates bubble placements immediately; children can then drag any bubble independently. Comic chain is a separate persistent Show bubbles presentation choice; details are in Comic Chain Speech Mode.

Data and ownership

SpeechBubble computes the requested centers from its current measured editor-preview frames, in rig-local coordinates. SandboxStage routes the selected preset to SpeechComposer, which writes each center into that bubble's existing placement: {mode: "manual", center: Vector2} field. Stack and Same spot only change positions. Comic chain is saved as arrangement: "comic_chain" and controls cumulative playback and connected tails.

Order badges remain fixed-size editor controls across camera zoom. When two or more badge positions are close, group the badges into one ascending-number row above the bubbles. If that row does not fit in the stage or overlaps a visible Speech Show or Speech Style toolbar, use an ascending vertical rail beside the group; use a row below only when the stage edges and toolbars leave no room above or beside it. Keep the group together, outside visible toolbar bounds, and make the layout used for drawing the same layout used for badge hit testing. The selected bubble's badge has a yellow fill and dark number; other badges keep a dark fill, yellow outline, and light number. A badge click selects that bubble and raises its frame and text above overlapping siblings for editing; it does not change speech order or saved placement.

Bubble 1 is the anchor for both actions. Stack computes the first later bubble at previous_center.y - previous_height/2 - STACK_GAP - current_height/2, with alternating ±22 px horizontal offsets from Bubble 1. Same spot copies Bubble 1's center exactly to every bubble.

Acceptance

1. The Show Speech panel displays Stack and Same spot placement actions, while Comic chain appears as a persistent choice under Show bubbles.
2. Stack leaves Bubble 1's saved center intact and moves later bubbles upward with no frame overlap, including bubbles with different font sizes.
3. Same spot gives every bubble the exact same saved center as Bubble 1.
4. Dragging one bubble after either action changes only that bubble. Reapplying a preset lays out the full sequence again.
5. Layout positions survive speech save and scene save/load. Choosing Stack or Same spot does not change the selected Show bubbles mode.
6. When two or more badge positions are close, their badges form a sorted horizontal row above the bubble group, or a sorted vertical rail beside it when the row cannot fit. The selected bubble's badge is visibly filled yellow. Every badge remains readable and clickable; clicking one brings that bubble's frame and text to the front for editing.
7. No order badge is drawn underneath the visible speech toolbar.