feat: incremental tile streaming — per-tool dispatch + streaming-state events

[romer8]

Summary

Phase 1 of docs/plans/2026-05-28-002-feat-chatbox-core-incremental-tile-streaming-plan.md (origin: docs/brainstorms/2026-05-28-incremental-tile-streaming-requirements.md).

Adds incremental per-tool dispatch to chatbox-core so tiles appear on the dashboard as each MCP tool returns, instead of all at once at end-of-turn. On local Ollama at ~10s per round, a 5-tool turn goes from "blank dashboard for 50s, then 5 tiles" to "first tile at ~10s, last at ~50s" — same total wall-clock, dramatically different perceived latency. Also lays the lifecycle groundwork for tethysdash (Phase 2) to gate per-tile edit/delete affordances during streaming.

What's in this PR (Phase 1)

Unit 1 — engine onToolEnvelope callback (engine/index.js)

• New optional callback parameter on processToolCalls and runChatSession options bags.
• Fires once per visualization / layer_update / patch_update push with the per-call delta of dispatchedUuids (NOT cumulative).
• Wrapped in fireToolEnvelope helper mirroring the fireStatus pattern: try/catch + console.warn, never aborts the engine loop.
• Threads signal into the processToolCalls options bag too (previously only forwarded to executeTool).
• 10 new tests in engine/onToolEnvelope.test.js — happy paths per envelope kind, multi-shape single result, multi-tool ordering + per-call delta isolation, host throw containment, signal.aborted gate, undefined no-op backward compat.

Unit 2 — Chatbox.jsx per-tool dispatch + end-of-turn no-op sentinel (merged from Units 2+4 per scope-guardian review)

• Chatbox.jsx supplies the engine callback; translates each invocation into the existing window.dispatchEvent shapes:
  • visualization → tethysdash:add-visualization {batch:true, panels:[panel]} (per-panel construction inlined from end-of-turn block at lines 928-955, including resolveVisualizationUrl + client_custom_remote + inlineData branches).
  • layer_update → tethysdash:update-visualization flat shape {uuid: map_uuid, operation: 'append_layers', layers: [layer]} matching the existing handler. NOT batched (handler does not look at detail.updates).
  • patch_update → tethysdash:update-visualization {batch:true, operation:'apply_patch', patches:[entry]}.
• Defense-in-depth gates: signal.aborted check + capturedTurnId freshness check. No requestAnimationFrame per the raf-timing-race solution doc.
• streamedDispatchFiredRef sentinel: reset at turn start, set on first callback invocation; the three end-of-turn dispatch sites (lines ~928, ~983, ~1072) check it and skip dispatch when streaming already fired (R10). Backward-compat: legacy hosts (no onToolEnvelope) see sentinel stay false and the existing end-of-turn dispatch runs unchanged.

Unit 3 — tethysdash:turn-start / tethysdash:turn-end window events

• turn-start fires immediately AFTER abortRef.current = controller is assigned. Inline INVARIANT comment names the sequencing so a future refactor doesn't reorder.
• turn-end fires from the shared finally block. Single site covers success / thrown error / user-initiated abort / /clear uniformly.
• Events carry no payload; listeners (added in Phase 2 on tethysdash) toggle a boolean.

Unit 5 — Stop UX contract documentation

• The existing result.aborted ? (accumulatedContent || "(Stopped)") : (result.assistantText ...) shape already implements R8a because the engine returns {aborted: true} rather than throwing on abort, so the stop path routes through setMessages not ChatErrorPanel. Added comment block naming the contract so the behavior survives future refactors.

API surface delta

Surface	Before	After
<Chatbox> component props	unchanged	unchanged
runChatSession options	(existing)	+ onToolEnvelope (optional, default null)
processToolCalls options	(existing)	+ onToolEnvelope, + signal
Window events emitted from chatbox-core	tethysdash:add-visualization, tethysdash:update-visualization, tethysdash:patch-rejected	+ tethysdash:turn-start, + tethysdash:turn-end

Additive only. Passive consumers see no behavior change.

Phase 2 (deferred to a follow-up PR on tethysapp-tethys_dash)

Lands after this beta is published. Adds a StreamingContext to Contexts.js, has DashboardLoader.js listen for the new window events and provide an isStreaming flag, and gates DashboardItem's edit/delete/reorder affordances on it with aria-disabled="true" + opacity + tooltip.

Test plan

• npx vitest run → 679/679 + 10 new = 689/689 pass
• npm run build → dist rebuilt clean
• After publish to beta dist-tag, smoke against tethysdash dev (Phase 2 PR will exercise the events end-to-end)
• Plan deferred questions: planning needs to verify /clear interleaving with turn-end timing under real conditions

Release notes

CHANGELOG updated under ## [0.16.0-beta.0] — 2026-05-28. package.json bumped from 0.15.3 → 0.16.0-beta.0. Adjust before publishing if a different version is preferred.

Plan: docs/plans/2026-05-28-002-feat-chatbox-core-incremental-tile-streaming-plan.md
Origin: docs/brainstorms/2026-05-28-incremental-tile-streaming-requirements.md