fix(components): stop Mermaid diagrams from capturing the wheel

[lodystage]

Related issue

Same-repository branch; no intake Issue. Reported directly: scrolling a
conversation stops when the pointer is over a Mermaid diagram.

Problem / pressure

Streamdown wraps every rendered diagram in a pan/zoom canvas whose non-passive
wheel listener calls preventDefault() on each event. Scrolling the
conversation therefore stopped dead and zoomed the diagram whenever the pointer
happened to rest over one. controls.mermaid.panZoom: false — which this repo
already sets — only hides that canvas's buttons; the listener stays. The same
canvas also sets touch-action: none inline, so a finger landing on a diagram
could not scroll the conversation at all.

Zooming a diagram is still wanted, just not by accident: it belongs to the
full-screen viewer the user deliberately opens.

Summary

• A diagram in a message is a still preview. markdown-renderer.tsx intercepts
  wheel in the capture phase above the canvas and never calls
  preventDefault(), so the browser scrolls normally. Three !important
  overrides return touch-action, the pan transform, and the cursor to the page.
• mermaid-diagram-viewer.tsx becomes the only canvas: a trackpad pinch
  (ctrl/meta-modified wheel) zooms around the pointer, and a held mouse or pen
  button drags. Plain wheel and touch panning stay with the surface's own
  scrolling, so momentum and overscroll containment remain the platform's.
• Mermaid invariants moved to a scoped doc, which also drops
  ai-gui/AGENTS.md from 8123 to 7667 bytes.

Visual explanation

The wheel path over a diagram, before and after:

flowchart TD
    W["wheel over a diagram"] --> Root["markdown root (capture phase)"]

    Root -->|before| Canvas["Streamdown pan/zoom canvas<br/>preventDefault() + zoom state"]
    Canvas --> Dead["page does not scroll"]

    Root -->|after| Take["stopPropagation()<br/>re-dispatch uncancelable copy"]
    Take --> Above["scroll-viewport listeners<br/>stick-to-bottom, outline jump"]
    Take --> Scroll["browser scrolls the conversation"]

Loading

stopPropagation() alone would have hidden the gesture from the listeners above
the message, hence the re-dispatched copy from the markdown root, whose
propagation path excludes the canvas.

Where each gesture is handled now:

MarkdownRenderer (markdown-renderer.tsx)
└── [data-streamdown="mermaid"]        # still preview: click/Enter opens the viewer
    └── Streamdown pan/zoom canvas     # wheel taken back, transform + touch-action pinned

MermaidDiagramViewer (mermaid-diagram-viewer.tsx)
└── scroll surface                     # plain wheel + touch = native pan
    ├── ctrl/meta + wheel              # pinch: zoom anchored at the pointer
    └── mouse/pen drag on the diagram  # pan via scrollLeft/scrollTop

Before / after

Measured in Chromium (Playwright driving the real MermaidStyleReview story,
given a scroll container because the Storybook preview clips its own overflow):

Before	After
300px wheel over the diagram: container scrollTop 0 -> 0	0 -> 300, matching the control wheel over prose beside it
touch-action: none on the diagram	touch-action: auto
Drag left the preview at matrix(0.9, 0, 0, 0.9, 100, 60) — displaced and holding a zoom from the swallowed wheel	Drag leaves transform: none; the release opens the viewer
Viewer: no pinch; ctrl+wheel reached the window	Viewer: ctrl+wheel 121% -> 148%, anchored at the pointer
Viewer: pan by scrollbars or wheel only	Viewer: drag pans (scrollTop 177 -> 297 for a 120px drag), stays open

Test plan

• packages/components: vitest run tests/markdown-mermaid-fullscreen.test.tsx
  — 16 passed, including five new cases. The wheel case asserts
  defaultPrevented === false and that a listener above the message still
  receives one event of the same deltaY; removing the interceptor makes it
  fail, so it guards the reported defect rather than restating the code.
• vitest run tests/markdown — 105 passed. tsgo --noEmit — clean.
  oxlint on the changed files — 0 warnings, 0 errors. prettier --check on
  every changed file — clean. pnpm run docs check — no errors.
• Tailwind CLI over src/tailwind/index.css confirms the three overrides
  compile to !important declarations.
• Chromium verification as tabulated above, including a baseline run with only
  markdown-renderer.tsx reverted, which reproduced the report.
• Skipped: full pnpm check (this worktree needs its submodules initialized to
  install, and the suite reaches far past the changed files). Two full
  packages/components runs each failed one unrelated test, a different one
  each time (markdown-streaming-reparse, then avatar-cache); both pass in
  isolation, so they are load flakes. Touch was not exercised on a device: the
  touch-action fix is a computed-style observation.

Context handoff

Instructions for reviewing agents

• Review focus: the capture-phase wheel interceptor in markdown-renderer.tsx, and whether its re-dispatched copy is a faithful stand-in for the listeners above the message (use-sticky-scroll.ts, view.tsx).
• Decisions to challenge: neutralizing Streamdown's canvas from outside instead of patching the package or replacing the block with a custom renderer; pinning the canvas transform rather than intercepting pointerdown.
• Plausible failures / evidence gaps: two-finger touch pinch is deliberately absent; the zoom-in cursor rule targets [data-streamdown="mermaid"] > div, so a Streamdown structural change would silently drop that affordance, though not the fix.

Authoring context

• User goal / directives: stop a Mermaid diagram from capturing the wheel while the user scrolls the conversation, and support pinch/pan once the user focuses a diagram, as on a MacBook trackpad.
• Constraints / non-goals: no dependency patch, no fork of Streamdown's mermaid block, and no reimplementation of its copy/download controls; the viewer's existing exits, safe-area padding, stacking, and natural-size opening are unchanged.
• Risk-bearing decisions: the interceptor stops the original wheel and re-dispatches an uncancelable copy from the markdown root; if a consumer above the message needed the original target or cancelability, it would now see neither.
• Destructive or irreversible behavior: none — renderer-only, no storage, protocol, or migration surface.
• Deliberately not done or tested: two-finger touch pinch (it requires taking touch-action and reimplementing inertial panning); touch was not exercised on a device; full pnpm check was not run in this worktree.
• Unknowns / confidence: high for desktop, verified in Chromium before and after; medium for touch, where the fix rests on a computed-style observation rather than a device test.

Rationale and rejected alternatives:
.agents/notes/implemented/bug-fix/2026-09-09-mermaid-diagram-gestures.md.
Invariants: packages/components/src/components/ai-gui/mermaid-diagram-rendering.md.

🤖 Generated with Claude Code