@ai-setting/roy-plugin-task-show 2.5.22 → 2.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-setting/roy-plugin-task-show",
-  "version": "2.5.22",
+  "version": "2.6.1",
   "description": "roy-agent plugin: visualize task solving process via tool call flow on a local web service",
   "type": "module",
   "main": "dist/index.js",

package/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "@ai-setting/roy-plugin-task-show",
-  "version": "2.5.22",
+  "version": "2.6.1",
   "type": "tool-plugin",
-  "description": "v2.4.1: Mermaid zoom now supports click-and-drag pan (Task #2785). After zooming in, users can drag the diagram to view the surrounding canvas area. Implementation: per-container panState/dragState WeakMap (no global state leak); applyTransform(translate+scale) single-source-of-truth for the CSS transform; attachPanHandlers on pointerdown/move/up/cancel with setPointerCapture for off-element drags; pointer cursor switches to grab/grabbing with touch-action: none to prevent native scrolling; reset/zoomReset now also resets pan to (0,0). 14/14 new mermaid-pan tests pass, full suite 558/564 with 6 pre-existing failures unrelated to this commit. v2.4.0: Combines v2.3.0 Combines v2.3.0 (worktree-aware file-tree + unbounded Mermaid zoom, Task #2773) with the v2.3.0 mermaid placeholder expansion (Task #2771). Sidebar + endpoint scope git ls-files to session.context.worktree (fallback process.cwd()); Mermaid zoom-in is no longer capped at 3.0\u00d7; .mermaid placeholder is now min-height: 2400px and .mermaid-zoom-stage is min-width: 6400px / min-height: 2400px (5\u00d7 base, via --mermaid-placeholder-multiplier CSS custom property) so dense diagrams get enough canvas to pan/zoom comfortably. v2.3.0: Worktree-aware file tree sidebar + unbounded Mermaid zoom-in. The file-tree sidebar (and /api/task/:id/file-tree endpoint) now scope git ls-files to session.context.worktree when the host (task:before.create / task:after.create payload) supplies a worktree path, so the sidebar shows the files the agent is actually editing instead of the plugin process cwd. New resolveWorktreePath helper in src/file-tree.ts returns session.context.worktree (trimmed, with empty/non-string guard) or falls back to process.cwd() for backward compatibility with pre-v2.3.0 hosts. TypeScript: TaskSession gains an optional context?: { worktree?: string } field. TaskShowServer exposes getCollector() so tests can seed sessions with context.worktree set. The Mermaid zoom toolbar (introduced in v2.0.8) no longer caps zoom-in at 3.0\u00d7 \u2014 the ZOOM_MAX constant is REMOVED and clampZoom only enforces ZOOM_MIN=0.25, so dense diagrams remain readable on high-DPI monitors when the user wants to zoom way in. ZOOM_MIN stays in place so zoom-out still bottoms out before rendering a black screen. New tests: test/file-tree-worktree.test.ts (10 cases \u2014 resolveWorktreePath edges, SSR scope, endpoint scope, fallback), test/mermaid-zoom-unlimited.test.ts (8 cases \u2014 source guard, behaviour at 6\u00d7/10\u00d7/50\u00d7, lower-bound preserved), test/mermaid-placeholder-size.test.ts (7 cases \u2014 min-height/min-width 5\u00d7 checks, transform-origin preserved, --mermaid-placeholder-multiplier hint). v2.3.0: Major visual overhaul of the per-task detail page \u2014 VS Code-style tool-call browser powered by Monaco Editor + LCS-based diff + project file tree with mermaid-driven navigation. The detail page now renders a 2-column layout: a sticky left sidebar with the project's git-tracked file tree (chevron-toggle directories, `is-affected` highlight for files touched by the current task), and a main column with the existing Mermaid + stats + toolcalls table + a new dedicated `<section id=\"tool-call-detail-panel\">` that hosts the LCS diff body + Monaco container for the currently-selected tool call. The legacy inline `<details class=\"diff-panel\">` (naive split-and-filter, prone to mis-tagging context lines) is replaced by `<ol class=\"diff-body\">` with proper added/removed/context markers driven by a real LCS dynamic-programming table (`computeDiff()` in `src/tool-call-detail.ts`). Tool calls with a file path get a Monaco Editor placeholder (`<div class=\"monaco-editor\" data-file-path=\"...\" data-language=\"...\">`) which the client-side `public/tool-call-detail.js` lazy-loads from `cdn.jsdelivr.net/npm/monaco-editor@0.45.0` the first time the user clicks a tool row. The Mermaid `__toolClick(toolId)` callback now drives THREE things: (a) the existing row scroll + highlight (preserved from v1.x), (b) the dedicated detail panel re-renders with the matching call, (c) the file-tree sidebar highlights the corresponding file (when `data-file-path` is present). New `GET /api/task/:id/file-tree` endpoint serves the git-tracked file list (`{ files: string[] }`) with a 30-second in-memory TTL + 8-entry FIFO bound. New modules: `src/file-tree.ts` (pure data layer: `buildFileTree / extractAffectedPaths / findNodeByPath / collectAllPaths / gitLsFiles / parseLsFiles`), `src/tool-call-detail.ts` (SSR + LCS diff + HTML escaping), `public/file-tree.js` (vanilla JS hydrator with chevron toggle + keyboard navigation + scrollIntoView), `public/tool-call-detail.js` (Monaco AMD loader + `__toolClick` wrapper + file-content fetch). New tests: `test/file-tree.test.ts` (21 cases \u2014 empty/single/nested/dedup/sort/depth/parseLsFiles/gitLsFiles), `test/tool-call-detail.test.ts` (22 cases \u2014 LCS diff edges, HTML escape, path aliases, summary stats), `test/tool-call-detail-server-integration.test.ts` (7 cases \u2014 SSR HTML contracts + endpoint), `test/tool-call-detail-jsdom.test.ts` (7 cases \u2014 client-side hydrators). v1.2.0: CSS context & packaged release hotfix. The plugin's public assets (notably `public/style.css`) and runtime adapters now correctly resolve relative to the installed package directory even when consumed via the published npm tarball. The session-scoped `TaskSessionStore` now preserves the full host session context (parent-child task links, plugin-handle id, env scope) across render cycles \u2014 previously the session was collapsed to its `sessionId` on first load and never refreshed, so the home page lost the \u300csession ancestors\u300d chain and external tasks from outside the current session silently disappeared from the tree. Adds `src/task-metadata.ts` as the single source of truth for the public `Task` shape exposed by `/api/tasks` + `/api/tasks/:id`, including the v1.0.0+ `processDescription` field, and re-exports it through the CLI adapters (`cli-tasks-adapter.ts` + `cli-tasks-tree-adapter.ts`) so the home page tree + the per-task page render against the same metadata contract. Bundles 244-line regression test (`test/context-and-packed-release.test.ts`) that boots the plugin from the **npm-pack** directory (not the repo working tree), spawns `roy-agent tasks get <id> --json`, and asserts (a) `public/style.css` is present and \u2265 64 lines, (b) the `/api/events` SSE endpoint survives a reload, and (c) `task.session` survives a render cycle. v1.1.0: Full Server-Sent Events realtime subscription across 3 event classes (task.created / operation.updated / tool.called) on both the home page and the per-task /task/<id> page. The per-task pipeline now subscribes to /api/events and patches the DOM in place on operation.updated \u2014 no more 5s-poll delay before the user sees a new milestone. The 'Task lifecycle pipeline' header badge is replaced by a 5-state SSE-aware badge (stale / connecting / live / reconnecting / error) so the user can tell at a glance whether real-time updates are flowing, the connection dropped, or 3+ consecutive errors triggered the polling fallback. Legacy boolean `stale` cache-TTL pill and `tool.recorded` event name are preserved for back-compat with v0.9.x / v1.0.0 clients. v1.0.0: First stable release. Replaces the v0.9.x fixture-based verify scripts (which built fake TaskOperationsEnvelope and never invoked the real `roy-agent` CLI, masking regressions in the public-schema `processDescription` field) with a real-CLI scenario test + verify (`test/process-description-real-scenario.test.ts` + `scripts/verify-v100-real-scenario.ts`) that spawns `roy-agent tasks get <id> --operations --json` via `defaultRunner` and asserts the API response carries `processDescription` end-to-end. The 0.9.9 processDescription fix is preserved verbatim \u2014 this release only swaps the verify surface. Visualize the tool call chain of a task on a local web service with real-time SSE updates. v0.9.9: Task lifecycle pipeline on /task/<id> now exposes BOTH the milestone badge AND the \u300c\u8fc7\u7a0b\u63cf\u8ff0\u300d column at a glance \u2014 the server-side `/api/tasks/:id/operations` endpoint exposes `processDescription` on every operation (no longer stripped from the public schema), the client-side `renderPipelineHtml` mirrors the server's `.op-desc-block` + `.op-proc-block` block layout so SSR \u2194 CSR stay in sync, and a long-standing CSS right-side text-truncation bug in the pipeline timeline (long CJK titles overflowing the panel edge) is fixed via `min-width: 0` on `.op-row1` + `overflow-wrap: anywhere` on `.op-title`. v0.9.0: Session-scoped home page (only show tasks created after plugin load + their external ancestors), with per-row \u300c\u663e\u793a\u5168\u90e8\u680f\u4f4d\u300d toggle and lazy-loaded operations timeline; per-task Mermaid labels now correctly render CJK / mixed-Latin / emoji text (encoded as \\uXXXX before emission, decoded by the browser); detail page layout reordered to lifecycle \u2192 pipeline \u2192 stats \u2192 toolcalls \u2192 rawjson. v0.5.0+: page refreshes stream over GET /api/events (Server-Sent Events). Subscribes to tool:before.execute, tool:after.execute, task:before.create, task:after.create, task:after.complete (preferred, 2026-07-10+), and task:after.update (legacy fallback). v0.6.11: Mermaid re-rendering is delegated to a self-contained controller (public/mermaid-renderer.js) that prevents the SVG\u2192raw-source regression on async updates and surfaces recoverable .mermaid-error states. v0.6.12: Task lifecycle pipeline (operations timeline) server now emits data-task-id on the pipeline section; client preserves it on swap, so the page actually fetches /api/tasks/<id>/operations and renders the 7-op timeline (previously silently bailed). v0.7.0: Home page redesigned as a hierarchical task tree (driven by `roy-agent tasks tree --json`); new /api/tasks/tree endpoint with status / priority / type / root-id filters, expand/collapse UI, search, and live 30s polling. v0.8.0: per-task page Mermaid area now renders the hierarchical 'Task lifecycle + tools' view \u2014 each operation record owns a subgraph that nests its tool calls, with click callbacks (`window.__toolClick`) that scroll-into-view + highlight + auto-expand the matching row in the tool-call table below. Operation record descriptions (`description` + `processDescription`) are now always rendered inline (no `<details>` collapse) so the user sees the lifecycle state at a glance; a fallback `<details>` kicks in only for descriptions longer than 600 chars. v0.8.1: hotfix for two pre-existing bugs in v0.8.0 (browser smoke test surfaced after merge). (a) Mermaid click directives were emitted as `click t1 __toolClick(1)` (missing `call` keyword) \u2014 Mermaid 10's parser rejects this with `got 'PS'`. Fixed to `click t1 call __toolClick(1)` (the v10 grammar requires `call` to invoke a callback with arguments). (b) `buildMermaidSource` lived inside the `attachTaskPageTimeline` IIFE but was also called from a listener in the `attachToolClickBridge` IIFE \u2014 sibling IIFEs cannot see each other's locals, so the listener threw `ReferenceError: buildMermaidSource is not defined` and the Mermaid diagram silently failed to re-render after `task-show:lifecycle-ops-loaded`. Fixed by hoisting the function (and its three helpers) to script top-level so both IIFEs can see it via the script-wide closure; the function is also exposed on `window.buildMermaidSource` for tests + tooling. v0.8.3: tree-display fix (Task #2426). The home page used to look like a flat list of root tasks because `autoExpandFirstLevels(..., 2)` only opened the first 2 levels \u2014 30/47 roots were leaf nodes and the remaining 17 collapsed to one level so grandchildren were never visible. Default expand depth is now 3 (root + child + grandchild + great-grandchild are visible on first paint), the summary line now shows per-depth count pills (root / child / grandchild / great-grandchild / level-N), each `tree-row` carries a `data-depth` attribute so CSS can paint coloured left rails per level, and the duplicated 'Live tool-call sessions (legacy view)' panel that made the page look like both a flat table AND a tree is now hidden behind `#legacy-sessions[hidden]` (kept for future debug-toggle restoration). v0.8.10: bug-fix release (Task #2537 + Task #2534). (a) Heap-bounded plugin caches: OperationsCache and TasksTreeCache now enforce a hard maxEntries cap (default 256 / 64). Oldest stale entries are evicted before inserting a new one, so long-lived roy-agent sessions (BackgroundTaskManager + MemorySessionStore) no longer leak Map entries through the plugin's per-task caches \u2014 see Task #2537 for the heap-unbounded-state RED\u2192GREEN repro. (b) Mermaid CJK font-family: server.ts renderTaskPage now configures mermaid.initialize({ themeVariables: { fontFamily: '\"PingFang SC\", \"Microsoft YaHei\", \"Noto Sans CJK SC\", \"Source Han Sans CN\", \"WenQuanYi Micro Hei\", sans-serif' } }) so Chinese node labels render correctly in browsers that have at least one of those fonts installed (see Task #2534).",
+  "description": "v2.6.1: Mermaid render-retry self-heal (Task #3129 follow-up). v2.6.0's 3-attempt retry loop replayed the SAME source string on every retry — if the source was half-built at attempt 1 (SSE applyTaskUpdate interleaving with task-operations.js polling), attempts 2-3 hit the same 'Syntax error in text' fallback. v2.6.1 makes `controller.update()` accept an OPTIONAL `getSourceForRetry` thunk and re-invokes it between attempts so each retry sees the freshest (operations, session) snapshot the caller's source-builder can assemble. `scheduleMermaidRender` (public/app.js) now passes the same thunk through, so the SSE/poll race that v2.6.0 fixed now also self-heals within a single render call. RENDER_RETRY_MAX bumped 3→5 with backoff 60ms→120ms to give the second path more time to settle. mount() keeps the original two-arg signature (SSR-stable source, no race). All 7 new retry-thunk tests pass (T1 self-heal, T2 v2.6.0 fallback, T3 first-try bypass, T4 same-source fidelity, T5 non-retryable bail, T6 thunk-throw, T7 mount signature). v2.6.0: Mermaid rendering race-condition fix (Task #3123 — `Syntax error in text` on Task detail pages). Two paths previously raced on the same `<div class=\"mermaid\">`: the SSE `applyTaskUpdate` handler (writes the latest session.toolCalls) and the `task-show:lifecycle-ops-loaded` listener (writes the latest operations from `/api/tasks/:id/operations`). Each path had its OWN `createMermaidController` instance, so two controllers ran concurrent `mermaid.render()` calls and a half-built source string landed mid-transition → 'Syntax error in text'. Fix has three parts: (1) a SINGLE shared `window.__mermaidController` singleton (both paths now `update()` the same instance, so the existing per-container token guard drops late results); (2) a per-container Promise-chain render queue (`window.scheduleMermaidRender(container, taskId, getSource)` where `getSource` is a thunk) so the (operations, session) snapshot is atomic by the time we hand it to the controller; (3) `mermaid-renderer.js#renderInternal` now retries `mermaid.render` up to 3× with jittered backoff (60-180ms+0-40ms) on `Syntax error in text` before giving up, so transient races self-heal without surfacing the error block. Backwards compatible: old bundles that don't include the lock helper fall through to the v2.5.x per-instance controller. Tested: all 135 mermaid/app-js tests pass, build + typecheck clean. v2.4.1: Mermaid zoom now supports click-and-drag pan (Task #2785). After zooming in, users can drag the diagram to view the surrounding canvas area. Implementation: per-container panState/dragState WeakMap (no global state leak); applyTransform(translate+scale) single-source-of-truth for the CSS transform; attachPanHandlers on pointerdown/move/up/cancel with setPointerCapture for off-element drags; pointer cursor switches to grab/grabbing with touch-action: none to prevent native scrolling; reset/zoomReset now also resets pan to (0,0). 14/14 new mermaid-pan tests pass, full suite 558/564 with 6 pre-existing failures unrelated to this commit. v2.4.0: Combines v2.3.0 Combines v2.3.0 (worktree-aware file-tree + unbounded Mermaid zoom, Task #2773) with the v2.3.0 mermaid placeholder expansion (Task #2771). Sidebar + endpoint scope git ls-files to session.context.worktree (fallback process.cwd()); Mermaid zoom-in is no longer capped at 3.0×; .mermaid placeholder is now min-height: 2400px and .mermaid-zoom-stage is min-width: 6400px / min-height: 2400px (5× base, via --mermaid-placeholder-multiplier CSS custom property) so dense diagrams get enough canvas to pan/zoom comfortably. v2.3.0: Worktree-aware file tree sidebar + unbounded Mermaid zoom-in. The file-tree sidebar (and /api/task/:id/file-tree endpoint) now scope git ls-files to session.context.worktree when the host (task:before.create / task:after.create payload) supplies a worktree path, so the sidebar shows the files the agent is actually editing instead of the plugin process cwd. New resolveWorktreePath helper in src/file-tree.ts returns session.context.worktree (trimmed, with empty/non-string guard) or falls back to process.cwd() for backward compatibility with pre-v2.3.0 hosts. TypeScript: TaskSession gains an optional context?: { worktree?: string } field. TaskShowServer exposes getCollector() so tests can seed sessions with context.worktree set. The Mermaid zoom toolbar (introduced in v2.0.8) no longer caps zoom-in at 3.0× — the ZOOM_MAX constant is REMOVED and clampZoom only enforces ZOOM_MIN=0.25, so dense diagrams remain readable on high-DPI monitors when the user wants to zoom way in. ZOOM_MIN stays in place so zoom-out still bottoms out before rendering a black screen. New tests: test/file-tree-worktree.test.ts (10 cases — resolveWorktreePath edges, SSR scope, endpoint scope, fallback), test/mermaid-zoom-unlimited.test.ts (8 cases — source guard, behaviour at 6×/10×/50×, lower-bound preserved), test/mermaid-placeholder-size.test.ts (7 cases — min-height/min-width 5× checks, transform-origin preserved, --mermaid-placeholder-multiplier hint). v2.3.0: Major visual overhaul of the per-task detail page — VS Code-style tool-call browser powered by Monaco Editor + LCS-based diff + project file tree with mermaid-driven navigation. The detail page now renders a 2-column layout: a sticky left sidebar with the project's git-tracked file tree (chevron-toggle directories, `is-affected` highlight for files touched by the current task), and a main column with the existing Mermaid + stats + toolcalls table + a new dedicated `<section id=\"tool-call-detail-panel\">` that hosts the LCS diff body + Monaco container for the currently-selected tool call. The legacy inline `<details class=\"diff-panel\">` (naive split-and-filter, prone to mis-tagging context lines) is replaced by `<ol class=\"diff-body\">` with proper added/removed/context markers driven by a real LCS dynamic-programming table (`computeDiff()` in `src/tool-call-detail.ts`). Tool calls with a file path get a Monaco Editor placeholder (`<div class=\"monaco-editor\" data-file-path=\"...\" data-language=\"...\">`) which the client-side `public/tool-call-detail.js` lazy-loads from `cdn.jsdelivr.net/npm/monaco-editor@0.45.0` the first time the user clicks a tool row. The Mermaid `__toolClick(toolId)` callback now drives THREE things: (a) the existing row scroll + highlight (preserved from v1.x), (b) the dedicated detail panel re-renders with the matching call, (c) the file-tree sidebar highlights the corresponding file (when `data-file-path` is present). New `GET /api/task/:id/file-tree` endpoint serves the git-tracked file list (`{ files: string[] }`) with a 30-second in-memory TTL + 8-entry FIFO bound. New modules: `src/file-tree.ts` (pure data layer: `buildFileTree / extractAffectedPaths / findNodeByPath / collectAllPaths / gitLsFiles / parseLsFiles`), `src/tool-call-detail.ts` (SSR + LCS diff + HTML escaping), `public/file-tree.js` (vanilla JS hydrator with chevron toggle + keyboard navigation + scrollIntoView), `public/tool-call-detail.js` (Monaco AMD loader + `__toolClick` wrapper + file-content fetch). New tests: `test/file-tree.test.ts` (21 cases — empty/single/nested/dedup/sort/depth/parseLsFiles/gitLsFiles), `test/tool-call-detail.test.ts` (22 cases — LCS diff edges, HTML escape, path aliases, summary stats), `test/tool-call-detail-server-integration.test.ts` (7 cases — SSR HTML contracts + endpoint), `test/tool-call-detail-jsdom.test.ts` (7 cases — client-side hydrators). v1.2.0: CSS context & packaged release hotfix. The plugin's public assets (notably `public/style.css`) and runtime adapters now correctly resolve relative to the installed package directory even when consumed via the published npm tarball. The session-scoped `TaskSessionStore` now preserves the full host session context (parent-child task links, plugin-handle id, env scope) across render cycles — previously the session was collapsed to its `sessionId` on first load and never refreshed, so the home page lost the 「session ancestors」 chain and external tasks from outside the current session silently disappeared from the tree. Adds `src/task-metadata.ts` as the single source of truth for the public `Task` shape exposed by `/api/tasks` + `/api/tasks/:id`, including the v1.0.0+ `processDescription` field, and re-exports it through the CLI adapters (`cli-tasks-adapter.ts` + `cli-tasks-tree-adapter.ts`) so the home page tree + the per-task page render against the same metadata contract. Bundles 244-line regression test (`test/context-and-packed-release.test.ts`) that boots the plugin from the **npm-pack** directory (not the repo working tree), spawns `roy-agent tasks get <id> --json`, and asserts (a) `public/style.css` is present and ≥ 64 lines, (b) the `/api/events` SSE endpoint survives a reload, and (c) `task.session` survives a render cycle. v1.1.0: Full Server-Sent Events realtime subscription across 3 event classes (task.created / operation.updated / tool.called) on both the home page and the per-task /task/<id> page. The per-task pipeline now subscribes to /api/events and patches the DOM in place on operation.updated — no more 5s-poll delay before the user sees a new milestone. The 'Task lifecycle pipeline' header badge is replaced by a 5-state SSE-aware badge (stale / connecting / live / reconnecting / error) so the user can tell at a glance whether real-time updates are flowing, the connection dropped, or 3+ consecutive errors triggered the polling fallback. Legacy boolean `stale` cache-TTL pill and `tool.recorded` event name are preserved for back-compat with v0.9.x / v1.0.0 clients. v1.0.0: First stable release. Replaces the v0.9.x fixture-based verify scripts (which built fake TaskOperationsEnvelope and never invoked the real `roy-agent` CLI, masking regressions in the public-schema `processDescription` field) with a real-CLI scenario test + verify (`test/process-description-real-scenario.test.ts` + `scripts/verify-v100-real-scenario.ts`) that spawns `roy-agent tasks get <id> --operations --json` via `defaultRunner` and asserts the API response carries `processDescription` end-to-end. The 0.9.9 processDescription fix is preserved verbatim — this release only swaps the verify surface. Visualize the tool call chain of a task on a local web service with real-time SSE updates. v0.9.9: Task lifecycle pipeline on /task/<id> now exposes BOTH the milestone badge AND the 「过程描述」 column at a glance — the server-side `/api/tasks/:id/operations` endpoint exposes `processDescription` on every operation (no longer stripped from the public schema), the client-side `renderPipelineHtml` mirrors the server's `.op-desc-block` + `.op-proc-block` block layout so SSR ↔ CSR stay in sync, and a long-standing CSS right-side text-truncation bug in the pipeline timeline (long CJK titles overflowing the panel edge) is fixed via `min-width: 0` on `.op-row1` + `overflow-wrap: anywhere` on `.op-title`. v0.9.0: Session-scoped home page (only show tasks created after plugin load + their external ancestors), with per-row 「显示全部栏位」 toggle and lazy-loaded operations timeline; per-task Mermaid labels now correctly render CJK / mixed-Latin / emoji text (encoded as \\uXXXX before emission, decoded by the browser); detail page layout reordered to lifecycle → pipeline → stats → toolcalls → rawjson. v0.5.0+: page refreshes stream over GET /api/events (Server-Sent Events). Subscribes to tool:before.execute, tool:after.execute, task:before.create, task:after.create, task:after.complete (preferred, 2026-07-10+), and task:after.update (legacy fallback). v0.6.11: Mermaid re-rendering is delegated to a self-contained controller (public/mermaid-renderer.js) that prevents the SVG→raw-source regression on async updates and surfaces recoverable .mermaid-error states. v0.6.12: Task lifecycle pipeline (operations timeline) server now emits data-task-id on the pipeline section; client preserves it on swap, so the page actually fetches /api/tasks/<id>/operations and renders the 7-op timeline (previously silently bailed). v0.7.0: Home page redesigned as a hierarchical task tree (driven by `roy-agent tasks tree --json`); new /api/tasks/tree endpoint with status / priority / type / root-id filters, expand/collapse UI, search, and live 30s polling. v0.8.0: per-task page Mermaid area now renders the hierarchical 'Task lifecycle + tools' view — each operation record owns a subgraph that nests its tool calls, with click callbacks (`window.__toolClick`) that scroll-into-view + highlight + auto-expand the matching row in the tool-call table below. Operation record descriptions (`description` + `processDescription`) are now always rendered inline (no `<details>` collapse) so the user sees the lifecycle state at a glance; a fallback `<details>` kicks in only for descriptions longer than 600 chars. v0.8.1: hotfix for two pre-existing bugs in v0.8.0 (browser smoke test surfaced after merge). (a) Mermaid click directives were emitted as `click t1 __toolClick(1)` (missing `call` keyword) — Mermaid 10's parser rejects this with `got 'PS'`. Fixed to `click t1 call __toolClick(1)` (the v10 grammar requires `call` to invoke a callback with arguments). (b) `buildMermaidSource` lived inside the `attachTaskPageTimeline` IIFE but was also called from a listener in the `attachToolClickBridge` IIFE — sibling IIFEs cannot see each other's locals, so the listener threw `ReferenceError: buildMermaidSource is not defined` and the Mermaid diagram silently failed to re-render after `task-show:lifecycle-ops-loaded`. Fixed by hoisting the function (and its three helpers) to script top-level so both IIFEs can see it via the script-wide closure; the function is also exposed on `window.buildMermaidSource` for tests + tooling. v0.8.3: tree-display fix (Task #2426). The home page used to look like a flat list of root tasks because `autoExpandFirstLevels(..., 2)` only opened the first 2 levels — 30/47 roots were leaf nodes and the remaining 17 collapsed to one level so grandchildren were never visible. Default expand depth is now 3 (root + child + grandchild + great-grandchild are visible on first paint), the summary line now shows per-depth count pills (root / child / grandchild / great-grandchild / level-N), each `tree-row` carries a `data-depth` attribute so CSS can paint coloured left rails per level, and the duplicated 'Live tool-call sessions (legacy view)' panel that made the page look like both a flat table AND a tree is now hidden behind `#legacy-sessions[hidden]` (kept for future debug-toggle restoration). v0.8.10: bug-fix release (Task #2537 + Task #2534). (a) Heap-bounded plugin caches: OperationsCache and TasksTreeCache now enforce a hard maxEntries cap (default 256 / 64). Oldest stale entries are evicted before inserting a new one, so long-lived roy-agent sessions (BackgroundTaskManager + MemorySessionStore) no longer leak Map entries through the plugin's per-task caches — see Task #2537 for the heap-unbounded-state RED→GREEN repro. (b) Mermaid CJK font-family: server.ts renderTaskPage now configures mermaid.initialize({ themeVariables: { fontFamily: '\"PingFang SC\", \"Microsoft YaHei\", \"Noto Sans CJK SC\", \"Source Han Sans CN\", \"WenQuanYi Micro Hei\", sans-serif' } }) so Chinese node labels render correctly in browsers that have at least one of those fonts installed (see Task #2534).",
   "main": "dist/index.js",
   "hooks": [
     {
@@ -23,11 +23,11 @@
     },
     {
       "point": "task:after.complete",
-      "purpose": "PREFERRED hook point (roy-agent 2026-07-10+). When a task transitions to a terminal status (completed/failed/cancelled), finalize the session and broadcast a `task.completed` SSE event. terminalStatus field is explicit \u2014 no status filtering required. The handler dedupes against any `task:after.update` that may also fire on the same transition."
+      "purpose": "PREFERRED hook point (roy-agent 2026-07-10+). When a task transitions to a terminal status (completed/failed/cancelled), finalize the session and broadcast a `task.completed` SSE event. terminalStatus field is explicit — no status filtering required. The handler dedupes against any `task:after.update` that may also fire on the same transition."
     },
     {
       "point": "task:after.update",
-      "purpose": "GENERIC status update hook (v0.5.0+). Used for non-terminal transitions (running \u2192 paused \u2192 running) AND as a legacy fallback for hosts predating the AFTER_COMPLETE hook point. Broadcasts `task.updated` for non-terminal status, `task.completed` for terminal status. The internal dedup set guarantees at most one terminal broadcast per task even if both hooks fire."
+      "purpose": "GENERIC status update hook (v0.5.0+). Used for non-terminal transitions (running → paused → running) AND as a legacy fallback for hosts predating the AFTER_COMPLETE hook point. Broadcasts `task.updated` for non-terminal status, `task.completed` for terminal status. The internal dedup set guarantees at most one terminal broadcast per task even if both hooks fire."
     }
   ],
   "commands": [
@@ -64,20 +64,20 @@
     }
   },
   "endpoints": {
-    "index": "GET / \u2014 index of recent task sessions",
-    "taskDetail": "GET /task/:taskId \u2014 detail page (mermaid flow + tables)",
-    "apiSessions": "GET /api/sessions \u2014 JSON list of sessions",
-    "apiSessionDetail": "GET /api/sessions/:taskId \u2014 JSON detail of one session",
-    "apiEvents": "GET /api/events \u2014 Server-Sent Events stream (real-time push)",
-    "static": "GET /static/* \u2014 static frontend assets (CSS/JS)"
+    "index": "GET / — index of recent task sessions",
+    "taskDetail": "GET /task/:taskId — detail page (mermaid flow + tables)",
+    "apiSessions": "GET /api/sessions — JSON list of sessions",
+    "apiSessionDetail": "GET /api/sessions/:taskId — JSON detail of one session",
+    "apiEvents": "GET /api/events — Server-Sent Events stream (real-time push)",
+    "static": "GET /static/* — static frontend assets (CSS/JS)"
   },
   "sse": {
     "events": [
-      "snapshot \u2014 initial state dump on connect",
-      "task.created \u2014 new task session opened",
-      "task.updated \u2014 non-terminal status change",
-      "task.completed \u2014 task transitioned to a terminal status",
-      "tool.recorded \u2014 tool call appended to a session"
+      "snapshot — initial state dump on connect",
+      "task.created — new task session opened",
+      "task.updated — non-terminal status change",
+      "task.completed — task transitioned to a terminal status",
+      "tool.recorded — tool call appended to a session"
     ],
     "heartbeatMs": 15000,
     "snapshotFrame": "event: snapshot\ndata: {type:'snapshot', data:{sessions:[...]}}\n\n"
@@ -89,4 +89,4 @@
   },
   "repository": "github:ai-setting/roy-plugin-task-visualize",
   "bugs": "https://github.com/ai-setting/roy-plugin-task-visualize/issues"
-}
+}

package/public/app.js

@@ -104,6 +104,141 @@
   }
 })();
 
+/* ------------------------------------------------------------------------- */
+/* v2.6.0 (fix/task-show-mermaid-render-lock): shared singleton + queue      */
+/*                                                                            */
+/* Background: two paths call `controller.update(mermaidDiv, source)` for    */
+/* the same DOM node — (1) SSE `applyTaskUpdate` (latest session) and       */
+/* (2) `task-show:lifecycle-ops-loaded` (latest operations). Each path     */
+/* previously created its OWN `createMermaidController` instance, so two    */
+/* controllers raced on the same container and produced inconsistent       */
+/* source strings during the brief window where one path had new toolCalls  */
+/* but the other still served stale operations.                             */
+/*                                                                            */
+/* The fix has three parts:                                                  */
+/*   1. A single shared controller (`window.__mermaidController`) — both   */
+/*      paths call `update()` on the same instance, so the existing `token` */
+/*      mechanism (in `mermaid-renderer.js`) drops the late result.         */
+/*   2. A render queue keyed by container (`window.__mermaidQueue`) —     */
+/*      before `update()` runs we enqueue a Promise that resolves only    */
+/*      after the previous `update()` for that container settled. This   */
+/*      gives a stable (operations, session) snapshot to render: the      */
+/*      second caller will see the freshly-updated `__lifecycleOps` or   */
+/*      `__pipelineController.lastSession` by the time its callback      */
+/*      runs.                                                               */
+/*   3. The controllers' own retry path (`mermaid-renderer.js` v2.6.0)   */
+/*      handles any remaining transient syntax errors.                     */
+/* ------------------------------------------------------------------------- */
+(function attachSharedMermaidLock() {
+  function ensureSharedMermaidController(taskId) {
+    if (!window.MermaidRenderer || !window.MermaidRenderer.createMermaidController) {
+      return null;
+    }
+    if (!window.__mermaidController) {
+      window.__mermaidController = window.MermaidRenderer.createMermaidController({
+        idPrefix: "task-" + (taskId || "lifecycle"),
+      });
+    }
+    return window.__mermaidController;
+  }
+
+  function ensureMermaidQueue() {
+    if (!window.__mermaidQueue) {
+      // Promise chain key — keyed by container DOM node identity so
+      // different diagrams on the same page render independently.
+      window.__mermaidQueue = new WeakMap();
+    }
+    return window.__mermaidQueue;
+  }
+
+  /**
+   * Schedule a render via the SHARED controller + per-container queue.
+   *
+   * `getSource()` is a thunk so it reads the LATEST state right before
+   * its turn in the queue runs — this is what makes the snapshot atomic.
+   * By the time the queue dispatches our thunk, the previous update()'s
+   * `mermaid.render` Promise has either resolved or been superseded, and
+   * any sibling path that fired in the meantime has updated the
+   * authoritative state (window.__lifecycleOps or
+   * window.__pipelineController.lastSession). The thunk reads both and
+   * builds the source string in one synchronous block — no interleaving
+   * possible between "read ops" and "read session".
+   *
+   * Returns a Promise that resolves when THIS render is settled. Note
+   * that if a newer call has already superseded us, the controller's
+   * token guard drops our result and our Promise simply resolves to
+   * "we ran, but nothing changed" — matching the v1.x behavior.
+   */
+  function scheduleMermaidRender(container, taskId, getSource) {
+    const controller = ensureSharedMermaidController(taskId);
+    if (!controller) {
+      // Mermaid not loaded — preserve legacy fallback: write source
+      // as pre-formatted text so the user at least sees something.
+      try {
+        container.textContent = String(getSource());
+      } catch (_) { /* swallow — same as v1.x */ }
+      return Promise.resolve();
+    }
+    const queue = ensureMermaidQueue();
+    const prev = queue.get(container);
+    const next = Promise.resolve(prev).then(() => {
+      // Re-check container still in the DOM; lifecycle-ops-loaded
+      // can fire after the user navigates away (task page replaced
+      // by the index, etc.) — `controller.update` already no-ops on
+      // a destroyed controller, but skipping earlier saves work.
+      if (!container || !container.isConnected) return;
+      let source;
+      try {
+        source = String(getSource());
+      } catch (err) {
+        // eslint-disable-next-line no-console
+        console.warn("[task-show] scheduleMermaidRender: getSource threw:", err);
+        return;
+      }
+      // v2.6.1 (fix/task-show-mermaid-render-thunk-retry): the
+      // v2.6.0 retry path replayed the same `source` string on
+      // every attempt, so a half-built source at attempt 1 was
+      // doomed to fail at attempts 2-3 as well. We now hand the
+      // controller the SAME `getSource` thunk as
+      // `getSourceForRetry` so each retry can read the freshest
+      // (operations, session) snapshot the thunk can assemble.
+      return controller.update(container, source, { getSourceForRetry: getSource });
+    }).catch((err) => {
+      // Defensive: never let an exception in the queue escape the
+      // promise chain. The controller's own onStateChange handler
+      // already surfaces render errors as the visible error block.
+      // eslint-disable-next-line no-console
+      console.warn("[task-show] mermaid queue tick failed:", err && err.message || err);
+    }).finally(() => {
+      // Drop our chain slot once settled so the WeakMap entry stays
+      // accurate — this also prevents a stale chain from blocking
+      // future renders on the same container (a common v1.x bug
+      // where a caught render error left the chain permanently
+      // broken).
+      const cur = queue.get(container);
+      if (cur === next) queue.delete(container);
+    });
+    queue.set(container, next);
+    // v2.5.12 (Task #2951): install the zoom-stage guardian once per
+    // container so Mermaid's late `mermaid.run()` (~T+3s) doesn't
+    // strip the `.mermaid-zoom-stage` wrapper. Guarded by the same
+    // `__mermaidGuardian` flag the legacy code used so multiple
+    // callers don't double-bind.
+    if (window.MermaidZoomGuardian && window.MermaidZoomGuardian.MermaidZoomGuardian && !window.__mermaidGuardian) {
+      try {
+        window.__mermaidGuardian = new window.MermaidZoomGuardian.MermaidZoomGuardian(container);
+        window.__mermaidGuardian.start();
+      } catch (_) { /* ignore — guardian is best-effort */ }
+    }
+    return next;
+  }
+
+  // Expose helpers so other IIFEs (attachTaskPageTimeline,
+  // attachToolClickBridge) share the same controller + queue.
+  window.scheduleMermaidRender = scheduleMermaidRender;
+  window.ensureSharedMermaidController = ensureSharedMermaidController;
+})();
+
 /* ------------------------------------------------------------------------- */
 /* v0.8.1+ Mermaid source builder (top-level — shared by both IIFEs)        */
 /* ------------------------------------------------------------------------- */
@@ -632,14 +767,31 @@ if (typeof window !== "undefined") {
         .then((r) => (r.ok ? r.json() : null))
         .then((s) => {
           if (!s) return;
+          // v2.6.0 (fix/task-show-mermaid-render-lock): route through
+          // the shared singleton + queue. The thunk reads the LATEST
+          // state inside its slot, so by the time the queue dispatches
+          // us we may have a richer session than what was captured
+          // here — that's fine, it just means we render with the most
+          // up-to-date snapshot.
+          if (window.scheduleMermaidRender) {
+            window.scheduleMermaidRender(mermaidDiv, taskId, () => {
+              const liveOps = (window.__lifecycleOps && window.__lifecycleOps.operations) || ops;
+              return buildMermaidSource(s, liveOps);
+            });
+            return;
+          }
           const source = buildMermaidSource(s, ops);
           if (window.MermaidRenderer && window.MermaidRenderer.createMermaidController) {
-            if (!window.__mermaidController) {
-              window.__mermaidController = window.MermaidRenderer.createMermaidController({
-                idPrefix: "lifecycle-" + taskId,
-              });
+            if (window.ensureSharedMermaidController) {
+              window.ensureSharedMermaidController(taskId).update(mermaidDiv, source);
+            } else {
+              if (!window.__mermaidController) {
+                window.__mermaidController = window.MermaidRenderer.createMermaidController({
+                  idPrefix: "lifecycle-" + taskId,
+                });
+              }
+              window.__mermaidController.update(mermaidDiv, source);
             }
-            window.__mermaidController.update(mermaidDiv, source);
             // v2.5.12 (Task #2951): install the zoom-stage guardian.
             if (!window.__mermaidGuardian && window.MermaidZoomGuardian) {
               window.__mermaidGuardian = new window.MermaidZoomGuardian.MermaidZoomGuardian(mermaidDiv);
@@ -654,14 +806,29 @@ if (typeof window !== "undefined") {
         });
       return;
     }
+    // v2.6.0: prefer the shared scheduler so this render serializes
+    // behind any in-flight `applyTaskUpdate` call.
+    if (window.scheduleMermaidRender) {
+      window.scheduleMermaidRender(mermaidDiv, taskId, () => {
+        const liveOps = (window.__lifecycleOps && window.__lifecycleOps.operations) || ops;
+        // Re-read the live session inside the thunk too — SSE may
+        // have updated `__pipelineController.lastSession` while we
+        // waited in the queue.
+        const liveSession = (window.__pipelineController && window.__pipelineController.lastSession) || session;
+        return buildMermaidSource(liveSession, liveOps);
+      });
+      return;
+    }
     const source = buildMermaidSource(session, ops);
     if (window.MermaidRenderer && window.MermaidRenderer.createMermaidController) {
-      if (!window.__mermaidController) {
+      if (window.ensureSharedMermaidController) {
+        window.ensureSharedMermaidController(taskId).update(mermaidDiv, source);
+      } else if (!window.__mermaidController) {
         window.__mermaidController = window.MermaidRenderer.createMermaidController({
           idPrefix: "lifecycle-" + taskId,
         });
+        window.__mermaidController.update(mermaidDiv, source);
       }
-      window.__mermaidController.update(mermaidDiv, source);
       // v2.5.12 (Task #2951): install the zoom-stage guardian.
       if (!window.__mermaidGuardian && window.MermaidZoomGuardian) {
         window.__mermaidGuardian = new window.MermaidZoomGuardian.MermaidZoomGuardian(mermaidDiv);
@@ -781,23 +948,29 @@ if (typeof window !== "undefined") {
     // Re-render mermaid diagram.
     const mermaidDiv = document.querySelector(".mermaid");
     if (mermaidDiv) {
-      // v0.8.0+: prefer the latest operations fetched by
-      // task-operations.js (window.__lifecycleOps) so the Mermaid shows
-      // the hierarchical view. Falls back to the linear chain when no
-      // operations are loaded yet.
-      const ops = (window.__lifecycleOps && window.__lifecycleOps.operations) || null;
-      const source = buildMermaidSource(session, ops);
-      // The controller handles mermaid availability, async race protection,
-      // error fallback, and idempotency. If Mermaid hasn't loaded yet
-      // (window.MermaidRenderer is undefined), we fall back to writing the
-      // source as a <pre> so the user at least sees the diagram text — same
-      // UX as the legacy pre-controller code.
-      if (window.MermaidRenderer && window.MermaidRenderer.createMermaidController) {
+      // v2.6.0 (fix/task-show-mermaid-render-lock): route through the
+      // shared singleton + per-container queue (`window.scheduleMermaidRender`).
+      // Previously `applyTaskUpdate._controller` was a SEPARATE instance from
+      // the one `task-show:lifecycle-ops-loaded` created (`window.__mermaidController`),
+      // so two controllers raced on the same `<div class="mermaid">` and the
+      // SSR or the winning render could land stale. The shared controller +
+      // thunk-based source builder makes the (operations, session) snapshot
+      // atomic.
+      if (window.scheduleMermaidRender) {
+        window.scheduleMermaidRender(mermaidDiv, taskId, () => {
+          const ops = (window.__lifecycleOps && window.__lifecycleOps.operations) || null;
+          return buildMermaidSource(session, ops);
+        });
+      } else if (window.MermaidRenderer && window.MermaidRenderer.createMermaidController) {
+        // Backwards-compatible fallback for older bundles that loaded
+        // app.js without the lock helper. Same behavior as v2.5.x.
         if (!applyTaskUpdate._controller) {
           applyTaskUpdate._controller = window.MermaidRenderer.createMermaidController({
             idPrefix: "task-" + taskId,
           });
         }
+        const ops = (window.__lifecycleOps && window.__lifecycleOps.operations) || null;
+        const source = buildMermaidSource(session, ops);
         applyTaskUpdate._controller.update(mermaidDiv, source);
         // v2.5.12 (Task #2951): install the zoom-stage guardian so
         // Mermaid's late `mermaid.run()` (~T+3s) doesn't strip the

package/public/mermaid-renderer.js

@@ -69,6 +69,57 @@
   const ZOOM_MIN = 0.25;
   const ZOOM_DEFAULT = 1.0;
 
+  // v2.6.0 (fix/task-show-mermaid-render-retry): robustness
+  // against transient syntax errors. The mermaid CLI parser is
+  // strict — a half-built source string from a race between
+  // the SSE `applyTaskUpdate` path (which writes the latest
+  // session.toolCalls) and the `task-operations.js` polling
+  // path (which writes the latest operations) can land in the
+  // controller mid-transition. The controller already drops
+  // *late* results via `getToken`, but it cannot save a *bad*
+  // source that was already inconsistent at construction time.
+  //
+  // v2.6.1 (fix/task-show-mermaid-render-thunk-retry): the
+  // v2.6.0 retry loop kept replaying the *same* source string
+  // on each attempt. If that string was bad (half-built at the
+  // moment we read it), all retries were doomed — every retry
+  // hit the same `Parse error on line N` / `Syntax error in
+  // text` SVG fallback. The fix is to (a) thread an optional
+  // `getSourceForRetry` thunk through `renderInternal()` /
+  // `update()`, and (b) re-invoke that thunk between attempts
+  // so each retry sees the **freshest** `(operations,
+  // session)` snapshot the controller's caller can assemble.
+  // `scheduleMermaidRender` (public/app.js) supplies this thunk
+  // by default so the race that v2.6.0 fixed now also self-
+  // heals within a single render call.
+  //
+  // We also bumped the retry budget + backoff so a second
+  // SSE/poll cycle has time to land before the loop gives up.
+  // The (v) prefixed config keeps the v2.6.0 behaviour available
+  // for callers that still want the literal replay (legacy
+  // direct `controller.update(container, source)` callers).
+  const RENDER_RETRY_MAX = 5;
+  const RENDER_RETRY_BACKOFF_MS = 120;
+  const RENDER_RETRY_BACKOFF_JITTER_MS = 80;
+
+  function isRetryableMermaidError(err) {
+    // Mermaid 10 surfaces parse failures with a thrown Error
+    // whose message contains "Syntax error in text" (lower-
+    // case `i`, capital `S`). Other failure modes (network,
+    // library missing, internal bug) are NOT retryable here —
+    // we let the outer try/catch surface them normally.
+    const msg = (err && err.message) || String(err || "");
+    return msg.indexOf("Syntax error in text") !== -1
+      || msg.indexOf("syntax error in text") !== -1;
+  }
+
+  function backoffDelay(attempt) {
+    // attempt is 1-based: 1 → base, 2 → base + 0..jitter.
+    const base = RENDER_RETRY_BACKOFF_MS * attempt;
+    const jitter = Math.floor(Math.random() * RENDER_RETRY_BACKOFF_JITTER_MS);
+    return base + jitter;
+  }
+
   function escapeHtml(s) {
     return String(s)
       .replace(/&/g, "&")
@@ -667,8 +718,29 @@
      * the container reflects the latest source (either an SVG or an error
      * block). If a newer call supersedes this one before the mermaid.render
      * Promise resolves, the result is dropped (no DOM mutation).
+     *
+     * v2.6.0 (fix/task-show-mermaid-render-retry): on `Syntax error in
+     * text` we retry up to `RENDER_RETRY_MAX` times with jittered
+     * backoff before giving up. The race window between the SSE
+     * `applyTaskUpdate` and the `task-operations.js` poll paths can
+     * deliver a half-built source string to this controller; a brief
+     * wait usually lets the second path complete and the next
+     * `update()` call supersedes us — the dropped retry then costs
+     * nothing. See `isRetryableMermaidError` and `backoffDelay`.
+     *
+     * v2.6.1 (fix/task-show-mermaid-render-thunk-retry): we now
+     * accept an OPTIONAL `opts.getSourceForRetry` thunk. When the
+     * first render raises a retryable error, the loop awaits
+     * `backoffDelay(attempt)` ms (giving the SSE/poll paths time to
+     * settle) and re-invokes the thunk to read the LATEST source —
+     * rather than replaying the stale one. The caller (typically
+     * `scheduleMermaidRender`) bundles the (operations, session)
+     * read inside the thunk so each retry sees an atomic snapshot
+     * produced after the previous attempt's failure surfaced. This
+     * converts a doomed 3-of-3 retry loop into a chance to heal as
+     * soon as the racing path lands the missing piece.
      */
-    async function renderInternal(container, source) {
+    async function renderInternal(container, source, opts) {
       // Idempotency: if the controller was destroyed or the container has
       // already successfully rendered this exact source, skip work entirely.
       if (controllerDestroyed) return;
@@ -687,20 +759,76 @@
         return;
       }
 
+      // v2.6.1: parse the optional thunk ONCE so the value can be
+      // reused across retries without surprising the caller
+      // (the same thunk must return consistent snapshots, i.e. it
+      // is a snapshot-fetcher not a side-effect-emitter).
+      const getSourceForRetry = (opts && typeof opts.getSourceForRetry === "function")
+        ? opts.getSourceForRetry
+        : null;
+
       const myToken = beginRender(container);
       setState(container, "loading");
+      // v2.6.0: same `id` is reused across retries inside one logical
+      // render — no need to bump `seqNum` per attempt since the token
+      // already distinguishes this logical call from any newer one.
       const seqNum = nextSeq(container);
       const id = `${idPrefix}-${seqNum}`;
       let result;
-      try {
-        result = await mermaid.render(id, source);
-      } catch (err) {
-        // Only surface this error if the user hasn't superseded us.
+      let lastErr = null;
+      // v2.6.0 + v2.6.1: retry loop. v2.6.0 replayed the same
+      // `source` string, which could not self-heal. v2.6.1 re-fetches
+      // `source` from the thunk (when provided) between attempts so
+      // each try sees the freshest `(operations, session)` snapshot
+      // the caller's source-builder can assemble. Non-retryable
+      // failures (e.g. library missing, thrown exception) bail
+      // immediately to preserve the original error behavior.
+      outer: for (let attempt = 1; attempt <= RENDER_RETRY_MAX; attempt++) {
+        // Bail out fast if a newer render has superseded us — paying
+        // for retries on a doomed source is wasteful.
+        if (controllerDestroyed || isDestroyed(container) || getToken(container) !== myToken) return;
+        try {
+          result = await mermaid.render(id, source);
+          lastErr = null;
+          break;
+        } catch (err) {
+          lastErr = err;
+          // v2.6.1: re-read the latest source from the thunk
+          // BEFORE the next backoff so the next attempt does not
+          // replay the same stale string. If the thunk is missing
+          // or throws we keep the prior `source` (legacy v2.6.0
+          // behaviour) and let the existing backoff handle the
+          // best-effort sequence.
+          if (getSourceForRetry && isRetryableMermaidError(err) && attempt < RENDER_RETRY_MAX) {
+            try {
+              const fresh = String(getSourceForRetry() ?? "");
+              if (fresh && fresh !== source) {
+                source = fresh;
+              }
+            } catch (_thunkErr) {
+              // Thunk threw — keep the previous source and let
+              // backoff + supersede do the work. We intentionally
+              // do not propagate this to the user; the loop will
+              // surface the underlying mermaid error instead.
+            }
+          }
+          if (!isRetryableMermaidError(err) || attempt === RENDER_RETRY_MAX) break;
+          // v2.6.0: wait, then check whether a newer call has
+          // superseded us. If yes, abort silently — no DOM mutation,
+          // no error block.
+          await new Promise((r) => setTimeout(r, backoffDelay(attempt)));
+          if (controllerDestroyed || isDestroyed(container) || getToken(container) !== myToken) return;
+        }
+      }
+      if (lastErr) {
+        // All retries failed (or the error wasn't retryable). Surface
+        // it just like before — only if this call is still the live
+        // one.
         if (controllerDestroyed || isDestroyed(container) || getToken(container) !== myToken) return;
         renderErrorBlock(
           container,
           source,
-          (err && err.message) || String(err),
+          (lastErr && lastErr.message) || String(lastErr),
         );
         if (onStateChange) onStateChange(container, "error");
         return;
@@ -777,11 +905,25 @@
         // Idempotent: calling mount twice on the same container should not
         // duplicate SVG. We treat mount and update identically from the
         // rendering pipeline's perspective; the contract difference is only
-        // intent (mount for first paint, update for re-renders).
+        // intent (mount for first paint, update for re-renders). mount keeps
+        // the simple two-arg signature — passing a thunk here would be
+        // surprising because the SSR page already commits a stable source.
         return renderInternal(container, source);
       },
-      update(container, source) {
-        return renderInternal(container, source);
+      /**
+       * v2.6.1: `update()` now accepts an optional third arg, a thunk that
+       * re-fetches the LATEST source between retry attempts. When omitted
+       * the controller falls back to v2.6.0's behaviour of replaying the
+       * supplied `source` (useful for callers that already know the
+       * string is final). `scheduleMermaidRender` (public/app.js) supplies
+       * this thunk so the race-fixed source-builder path self-heals.
+       *
+       * @param {HTMLElement} container
+       * @param {string} source
+       * @param {{ getSourceForRetry?: () => string | null }} [opts]
+       */
+      update(container, source, opts) {
+        return renderInternal(container, source, opts || null);
       },
       showError(container, source, error) {
         renderErrorBlock(container, source, error && error.message ? error.message : String(error));