stickman/docs/specs/speech_comic_chain_layout.md

Comic Chain Speech Mode

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

Intent

Comic chain is a speech presentation mode. Bubble 1 appears first. Each next bubble appears above and connects to its predecessor, while all earlier bubbles remain visible. Bubble 1's character-facing tail identifies the speaker.

Show Speech UI

Place Comic chain beside the other choices in Show bubbles:

💬 Show bubbles
[Show all] [One at a time] [💬 Comic chain]

🗨 Bubble layout
[Stack] [Same spot]

• The three Show bubbles choices use the existing selected-choice styling. Comic chain is a persistent presentation choice, not a one-shot placement action.
• Choosing Show all or One at a time exits Comic chain. The selected mode should be clear from its highlighted button.
• Stack and Same spot remain one-tap placement actions. They do not enable or disable Comic chain.
• Entering Comic chain arranges the bubbles using the measured Stack placement. Children may drag bubbles afterward; connectors follow their positions.
• Disable Comic chain when a speech has fewer than two bubbles. Keep the existing placement-action availability rules.
• No explanatory blurb or extra dialog.

Playback behavior

Comic chain is cumulative: bubble 1 appears, then bubble 2 is added while bubble 1 stays visible, then bubble 3 is added while bubbles 1 and 2 stay visible, and so on. Previous bubbles finish their entrance and text reveal before they become static. Each new bubble follows the existing per-bubble timing and reveal settings.

The stage editor's static preview shows the complete chain at once. Preview speech and runtime playback build the chain progressively. Standard Show all and One at a time behavior stays unchanged.

Layout and connector appearance

• On entry to Comic chain, keep Bubble 1's current center and arrange each later bubble above its predecessor, using measured frame heights, the existing stack gap, and alternating horizontal offsets.
• Bubble 1 connects to the character using its frame style: Talk/Whisper use a smooth tail, Shout uses an angular tail, Think uses descending dots, and SFX has no connector.
• For each later bubble, connect it to the preceding bubble's nearest frame edge. Use the current bubble's frame style. Talk/Whisper use a broad, blunt-ended bridge, and Shout uses an angular bridge. The attachment joins the previous bubble's outline; it does not narrow into a pointed tip.
• Draw connector bridges behind bubble frames and text so the frame outlines cover the seam and the connector does not obscure previous text. Think bubbles use descending thought dots that end at the previous bubble. SFX has no connector.
• Recompute connectors after bubble movement, camera changes, or actor movement. Preserve readable order badges above all bubble art.

Saved data and compatibility

Use arrangement: "comic_chain" as the canonical saved mode, alongside the existing together and take_turns values. Existing scenes with bubble_layout: "comic_chain" migrate to arrangement: "comic_chain" when normalized. New saves omit the obsolete bubble_layout key. Missing or invalid mode values default to together.

Preserve the mode through speech drafts, queue and rule actions, .scene save/load, and runtime playback. There is no scene file-version change.

Ownership and acceptance

• SpeechShowToolbar shows the three persistent Show bubbles choices and keeps Stack/Same spot as placement actions.
• SandboxStage applies measured Stack centers when Comic chain is selected.
• SpeechComposer commits arrangement and bubble centers together as one draft update.
• SpeechPayload validates the new arrangement and migrates the previous bubble_layout field.
• StageSceneIO and ActionRegistry preserve the canonical arrangement across queues and rules.
• SpeechBubble reveals the chain cumulatively and renders blunt joined bridges behind the predecessor frame.

Acceptance: selecting Comic chain highlights it, stacks bubbles, and previews a cumulative chain; bubble 1 points to the character; later bubbles join their predecessor with a blunt attachment; Think uses dots and SFX stays unconnected; dragging keeps connectors aligned; Show all and One at a time remain unchanged; old Comic chain saves migrate; Stack and Same spot only alter positions.