Skip to content

Speech bubbles: dialogue over the sprite, and a thinking ellipsis while a turn is in flight #119

Closed

Description

@omesser

Related: #17 (chat surface), #6 (the verbs that address the buddy), #84 (Do Not Disturb), #12 (hide rules and z-order).

This issue takes the bubble out of #17. The SPEC parked it there (docs/SPEC.md:385: "a reply that is not a declared Behavior is spoken (say:)… #17 will put that in a bubble"), and two code comments repeat the promise (director.rs:162, the as_speech doc; #17's own comment). #17 keeps the chat window; the bubble is the sprite's own mouth and deserves its own ticket. When this lands, repoint those three references.

Why

Two SPEC stories, both currently unmet:

  • Story 63: answers arrive through the character. The pipeline exists end to end — speak (Expression tool), say: classification (ModelDirector::as_speech), Frame.dialogue emitted for one tick (engine.rs:491) — and then the text goes nowhere but an AI_BUDDY_TRACE_MODEL eprintln. The buddy already talks; nobody can hear it.
  • Story 61: visibly react while the Harness works, so that I can tell something is happening. ADR-0004 keeps the model out of the frame loop precisely so the buddy stays alive while thinking; a thinking bubble is that liveness made legible. The signal already exists — model::InFlight::ready() is false exactly while a call is out — and reaches no pixel.

Scope

The speech bubble

  • A bubble above the sprite showing Frame.dialogue, tail pointing at the head. Frame.dialogue is emitted for one tick ("a line is said once, not held" — engine.rs:1631), so the shell latches it and owns display duration: 900ms + 55ms per character, clamped to 2–8 s. A new line replaces the old one.
  • Text wraps at a max width (~260 logical px default) and truncates with an ellipsis past ~6 lines — a reply long enough to truncate belongs in Chat surface #17's chat surface, and the bubble is not a document viewer.
  • Legible on any wallpaper: opaque background, border, shadow, system font. Per-Character bubble styling is v2; the Character Manifest does not grow a key for this.

The thinking bubble

  • The same bubble chrome with three animated dots (CSS keyframes, no JS timer), shown while a reactive session wake is in flight — the wakes where someone addressed the buddy (Poke, Summon, Throw, a chat turn once Chat surface #17 lands). Ambient wakes stay invisible: the Director wakes on a pace whenever the user pauses typing, and a buddy that visibly ponders every few minutes reads as stuck, not alive. This narrows "whenever a prompt is sent" deliberately; the addressed flag the frame loop already computes is exactly the split.
  • Appears only after a ~250 ms grace (an instant reply never flashes it) and, once shown, holds ≥600 ms (no flicker). When the reply arrives it becomes the speech bubble in place if there is dialogue, or fades if the reply was a silent Behavior, a Wake::Failed, or the static-Director fallback.
  • It can never get stuck: it is a pure function of InFlight state each tick, not an event that must be cancelled.

Where it renders

In the existing overlay webviews — a sibling element of #sprite in src/index.html, never a child: the sprite mirrors with scaleX(facing) and a child bubble would mirror its text. A second Tauri window would re-buy all of build_overlay, Spaces membership, capture exclusion, and display reconciliation for nothing.

Three concrete gaps to close:

  1. Placement (main.rs:102) carries no text — add dialogue: Option<String> (set on the tick the line is said) and thinking: bool (level).
  2. The webview has one <img> and no text node — add the bubble element and its placement/wrap/duration logic in main.js.
  3. Geometry: position from the same shared-point-space rect on every overlay, so a bubble on a display seam stays whole like the sprite does. Clamp to display bounds — flip below the sprite when the head is near the ceiling (CEILING_CLEARANCE is 128 px and a bubble can be taller), slide horizontally at edges so the tail keeps pointing at the sprite.

Rules the bubble inherits, not invents

  • Do Not Disturb: Frame.dialogue is already None under DND (engine.rs:491), so no speech bubble can appear. The thinking bubble is also suppressed — quiet means quiet — which today falls out of DND refusing proposals, but the bubble layer must not assume a wake cannot fire (session_due does not consult DND).
  • Hide rules: the bubble fades with the sprite (Change { visible, fade_ms } is already on every frame event) and vanishes instantly on the hide hotkey.
  • Click-through: the bubble is not interactive in v1. The hit region stays the sprite's alpha mask; bubble pixels stay click-through. (The union alternative buys nothing until the bubble has affordances.)

One Engine decision

A pure-speech reply (BehaviorProposal { behavior: "", dialogue }) currently starts no animation — the empty name is refused by chain, so the buddy would speak without moving its mouth. Decide here: play Primitive::Talk when a proposal carries dialogue and no playable Behavior. Note the durations are independent — talk holds PRIMITIVE_MS (600 ms) while the bubble holds reading time; the bubble must not borrow the animation clock.

Out of scope

  • Streaming text (the Completer returns a whole String; revisit with Harness attachment and the Action Log #16's real Harness).
  • Bubble input, buttons, or links — Chat surface #17's chat surface owns interaction.
  • Per-Character bubble art or fonts.
  • Per-Instance bubbles (the shell runs one Engine today; the Roster wiring is its own ticket).

CONTEXT.md gains Speech bubble as a term when this lands.

Acceptance criteria

  • A say: reply and a speak tool call each produce a bubble over the sprite with the line, held for reading time, then gone.
  • Poking the buddy with a Director configured shows the ellipsis (after the grace), then the reply — as a bubble, a Behavior, or both.
  • Ambient wakes never show the ellipsis.
  • A failed or silent turn fades the ellipsis without a bubble; it can never persist past its turn.
  • The bubble follows a walking sprite, mirrors correctly, stays whole across a display seam, and stays inside display bounds at edges and ceiling.
  • Under DND nothing appears; the hide hotkey removes bubble and sprite together, instantly.
  • Dialogue with no playable Behavior plays talk.

Tests

  • Engine: dialogue-with-empty-behavior plays talk (extends the pinned dialogue tests in engine.rs).
  • Renderer logic (wrap, duration, clamp/flip placement) as plain functions under node --test tests/.
  • Manual, against a fake Completer with an artificially slow turn (same rig Chat surface #17 plans): confirm grace, no flicker, no stuck ellipsis, and that the buddy keeps moving throughout — ADR-0004's whole point.

Spec: docs/SPEC.md stories 21, 27, 61, 63 · ADR-0004 · ADR-0008

Activity

  1. added a commit that references this issue on Aug 31, 2026
  2. omesser commented on Aug 31, 2026

    @omesser
    OwnerAuthor

    Implemented and on main in #127 (160db5e, plus 862c301 closing the review gaps). Verified against every acceptance criterion:

    • Placement carries dialogue and thinking (src-tauri/src/main.rs:129,133), populated at :857.
    • #bubble and #thinking-bubble are siblings of #sprite, not children (src/index.html:9-19).
    • Reading time 900ms + 55ms/char clamped 2–8s, wrap at 260px, ellipsis past six lines — all in src/bubble.js, latched in src/main.js:146-195.
    • Ellipsis: CSS keyframes (src/main.css:79-103), reactive wakes only and suppressed under DND (src-tauri/src/main.rs:692), 250ms grace and 600ms minimum hold (src/main.js:50,198,223).
    • Dialogue with an empty behavior plays talk (crates/core/src/engine.rs:450), with three engine tests at :4288.
    • Geometry clamps to display bounds, flips below at the ceiling, slides at edges (src/bubble.js:53-73).
    • node --test tests/ — 14 pass; cargo test green.
    • CONTEXT.md carries Speech bubble and Thinking ellipsis (:179-188), and the three forward references in docs/SPEC.md:385 and director.rs:162 are repointed from Chat surface #17 to Speech bubbles: dialogue over the sprite, and a thinking ellipsis while a turn is in flight #119.

    One loose end, tracked separately rather than here: origin/fix-thinking-bubble-lingers (a67c89b, "The thinking indicator yields to a reply, and a one-tick line is never lost") is not an ancestor of main. It refines shipped behavior — worth merging or reopening as its own issue.

  3. omesser commented on Aug 31, 2026

    @omesser
    OwnerAuthor

    Correction on that loose end: it is already open as #137, waiting on your review — nothing to reopen here.

  4. added this to the V1 milestone on Sep 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions