Skip to content

fix(shell): Stop the thinking ellipsis painting over speech, and make it a thought bubble - #146

Merged
omesser merged 1 commit into
mainfrom
fix/thinking-bubble-overlap
Aug 31, 2026
Merged

omesser merged 1 commit into
mainfrom
fix/thinking-bubble-overlap

Conversation

@omesser

@omesser omesser commented Aug 31, 2026 •

Copy link
Copy Markdown
Owner

Why

Two defects, reported together: the Thinking ellipsis painted on top of the
Speech bubble, and the ellipsis itself read as speech rather than as thought.

The overlap did not come from the decision layer. createBubbleMachine() in
src/bubble.js already refuses to have both up at once. It came from the DOM:
#bubble and #thinking-bubble were two elements anchored to the same head,
and each latched visibility: hidden behind a setTimeout keyed on
latest.fade_ms. That is the Character's presence fade from
crates/core/src/visibility.rs — set only when presence changes, but returned
on every tick, so once any fullscreen application has come and gone it stays at
500ms for the rest of the session. A dismissed Speech bubble then stayed
painted for half a second; the grace before the indicator arrives is 250ms.
250ms of overlap.

The second element caused the look too. .bubble::after was unqualified, so
the thinking bubble wore the Speech bubble's pointed tail, and its dots
animated scale(0) → scale(1) — a dot that leaves reads as art failing to
load, not as waiting.

What changed

#thinking-bubble is gone. One #bubble in one of two modes, named by
data-mode, so the overlap is unrepresentable in the DOM rather than merely
ruled out by the machine upstream of it. A hand-off is a content swap, not a
race between two fades. positionBubble, the --tail-offset and .flipped
all now act on the one element, and both modes carry their own tail geometry.

The fade_ms-keyed visibility: hidden latch went with it — nothing but
opacity gates the bubble now, and hide() is one line. hideAllNow(), the
hide hotkey's path, runs through that same hide().

The ellipsis got the thought idiom: round silhouette, a trail of two shrinking
circles where speech has a pointed tail, and dots that dip 0.35 ↔ 1 with a
3px lift rather than vanishing. Opacity and transform only, so it composites
without repainting — the overlay sits over whatever the user is doing.

Deliberately not done: main.js still writes bubble.style.transition from
latest.fade_ms every frame, so the bubble's own show/hide fade is still
timed by the presence fade. See Notes.

How to verify

Reviewer-runnable, both green on 8c68129 in a clean checkout:

$ node --test tests/*.test.js
# tests 23
# pass 23
# fail 0

$ cargo test --workspace
test result: ok. 35 passed; 0 failed; 2 ignored   (src-tauri)
test result: ok. 306 passed; 0 failed; 0 ignored  (ai_buddy_core)

The machine tests were remodelled around the single surface, and the new test
(the bubble's one surface is never taken back off the wrong one) walks a
turn that starts while a reply is still being read.

Mutation check on the harness, run during review — deleting the
hideThinkingNow() that precedes io.showSpeech() in src/bubble.js fails 2
of the 23 tests. The harness bites.

By hand, for the parts no test reaches: run the app, Poke to raise the
ellipsis, let a reply land, and Poke again during the reading window. Then open
a fullscreen application and close it — that is what latches fade_ms at
500ms and what used to produce the overlap.

Notes

No failing test came first. The bug is in the DOM layer and the repository
has no jsdom seam, so there was no honest red step: nothing in node --test
can observe two elements painted at once. The machine was already correct and
its tests already passed. What the tests do now is pin the model the fix
assumes — one surface — not the pixels. The CSS was verified by eye only;
there is no regression test for the silhouette, the trail, or the dot
animation, and there is no cheap way to add one without pulling in a headless
browser.

fade_ms still reaches the bubble. Every frame, src/main.js sets the
bubble's inline transition to opacity <fade_ms>ms linear, and that inline
rule overrides .bubble { transition: opacity 300ms ease } in main.css. So the authored 300ms show/hide fade never runs: in a
session with no fullscreen application fade_ms is 0 and every bubble snaps
in and out, and after one fullscreen cycle it becomes a 500ms linear fade. The
overlap this PR fixes is gone either way — one element cannot overlap itself —
but the coupling the description calls out as the root cause is only half
removed. Untangling it needs two independent opacity gates on one element
(presence versus bubble), which is a design decision, not a cleanup, so it is
left here rather than taken silently.

The show() comment reads as though fade_ms were gone. Given the line
above, it is worth a sentence pointing at it.

The new test overlaps an existing one. a new turn waits behind a displayed reply, indicator only after it hides already covers the same sequence via
calls; the new test differs mainly in asserting surface state. The harness
also dropped its old exclusive() invariant, which asserted mutual exclusion
on every show across every scenario for free. Restoring it in single-surface
form was tried during review and reverted: the exhaustive deepEqual(calls, …) assertions already catch every mutation it caught, so it was redundant.

Vocabulary. CONTEXT.md calls it the Thinking ellipsis; the code and
comments call it "the indicator". That predates this branch (bubble.js
already used it), so it was not churned here, but the two should converge.
CONTEXT.md's entry describes it as "three animated dots in a bubble", which
is still true of the new art — no doc change was required.

Related, closes neither. #119 introduced both the Speech bubble and the
Thinking ellipsis; #137 was prior work on the indicator. There is no issue for
this one — it was reported directly.

Behind main by one commit. Branched at c17d4c6; main is now
deed195, which touches no file this PR touches, so the squash is clean.

One #bubble in one of two modes. As two elements anchored to the same head
they crossfaded over each other: a bubble's exit was keyed on `fade_ms`, the
Character's presence fade, which rides every frame long after the rule that
set it and outlasts the grace before the indicator arrives.

The indicator is now a thought bubble — round, a trail of dots for a tail,
and dots that dip rather than vanish — so it no longer reads as speech.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@omesser

omesser commented Aug 31, 2026

Copy link
Copy Markdown
Owner Author

Review notes

Reviewed git diff c17d4c6...8c68129 on standards and on the reported defects.
Both defects are genuinely fixed, and the root-cause account holds up: I traced
fade_ms through crates/core/src/visibility.rs and confirmed it is written
only when presence flips visibility but handed back on every tick via
presence(), so it does stick at FADE_MS for the rest of a session after one
fullscreen cycle. .bubble::after being unqualified is likewise the whole
reason the ellipsis wore a speech tail. Nothing anywhere still references
#thinking-bubble, .thinking-bubble or the deleted .hidden.

Nothing was changed on top of 8c68129. One fix was tried and reverted —
see the redundant-invariant note in the description. Everything below is left
for the author.

Carried in the description's Notes, and the substance of the review:

  1. main.js still keys the bubble's opacity transition on fade_ms, so the
    300ms ease in main.css is dead in every session. Not a regression — the
    line predates the branch — but it is the same coupling the fix is about, and
    it is the one thing I would want resolved before this is called finished.
  2. The show() comment reads as though fade_ms no longer touches the bubble.
  3. The new test largely duplicates a new turn waits behind a displayed reply.

Smaller things not worth a Notes entry:

  1. .bubble carries box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15); the two
    trail-dot pseudo-elements do not, so on a light desktop the trail loses the
    lift the bubble has. Contrast is fine either way — white fill, #333
    border — so this is polish, not legibility.
  2. data-mode is never cleared on hide(). Harmless today (.visible is what
    gates opacity, and show() always sets the mode before measuring), but it
    means a bubble dismissed mid-fade morphs shape rather than fading out and
    back in when the next mode arrives within the 500ms window.
  3. The dots animate forever with no prefers-reduced-motion escape. No CSS in
    src/ uses media queries at all, so this is a repo-wide gap rather than
    something this PR introduced.
  4. show() carries ten lines of comment over three lines of code. It clears
    the bar in docs/agents/comments.md — it is the "stops the next reader
    putting the bug back" exception, not history for its own sake — but it is at
    the ceiling of what that exception buys.

Verified by hand: hideAllNow() still reaches the one hide(); .flipped and
--tail-offset are handled for both modes; positionBubble measures after the
mode is set, so offsetWidth reflects the round box. Not verified: anything
visual. No screenshots were taken and no browser was run.

@omesser
omesser merged commit 6e6469c into main Aug 31, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant