@ai-setting/roy-plugin-task-show 2.4.0 → 2.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-setting/roy-plugin-task-show",
-  "version": "2.4.0",
+  "version": "2.4.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.4.0",
+  "version": "2.4.1",
   "type": "tool-plugin",
-  "description": "v2.4.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).",
+  "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×; .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": [
     {
@@ -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/mermaid-renderer.js

@@ -162,6 +162,16 @@
     // not reset the user's zoom level.
     const zoomState = new WeakMap(); // container -> number (>=0.25, no upper cap in v2.3.0+)
 
+    // v2.4.1 (feat/task-show-v241-mermaid-pan): per-container pan
+    // state, independent of zoom. Keyed by the same container
+    // reference so the user's drag offset survives re-renders.
+    const panState = new WeakMap(); // container -> { tx: number, ty: number }
+    // v2.4.1: per-container drag-in-progress state. Holds the
+    // pointer down coordinates so `pointermove` can compute the
+    // delta. We do NOT store the live tx/ty here — those live in
+    // `panState` so they survive pointer-cancel.
+    const dragState = new WeakMap(); // container -> { startX, startY, startTx, startTy, pointerId }
+
     function nextSeq(container) {
       const cur = seq.get(container) || 0;
       const next = cur + 1;
@@ -229,12 +239,79 @@
       return v == null ? ZOOM_DEFAULT : v;
     }
 
+    // -----------------------------------------------------------------
+    // v2.4.1 (feat/task-show-v241-mermaid-pan): pan state + helpers
+    // -----------------------------------------------------------------
+
+    // Default pan offsets: no offset. panState defaults to
+    // { tx: 0, ty: 0 } if the container has no entry yet.
+    function getPan(container) {
+      if (!container) return { tx: 0, ty: 0 };
+      const v = panState.get(container);
+      return v == null ? { tx: 0, ty: 0 } : { tx: v.tx, ty: v.ty };
+    }
+
+    function setPan(container, tx, ty) {
+      // Sanitize: NaN -> 0 (defensive; tests assert finite).
+      const nextTx = Number.isFinite(tx) ? tx : 0;
+      const nextTy = Number.isFinite(ty) ? ty : 0;
+      panState.set(container, { tx: nextTx, ty: nextTy });
+      return { tx: nextTx, ty: nextTy };
+    }
+
+    function resetPan(container) {
+      return setPan(container, 0, 0);
+    }
+
+    // Clamp pan offsets so the diagram cannot be dragged beyond
+    // its visible bounds. The lower bound is `-diagramSize + containerSize`
+    // (so the right/bottom edge stays visible), the upper bound
+    // is 0 (so the top/left edge stays visible). When the
+    // diagram is smaller than the container in either axis, that
+    // axis is pinned to 0.
+    //
+    // When the stage has no measured size yet (pre-mount, jsdom
+    // test, or a freshly-created wrapper), the bounds collapse
+    // to (0, 0) — i.e. we still return the requested values
+    // (within NaN sanitization) without clamping, because we have
+    // no information to clamp against.
+    function clampPan(container, tx, ty) {
+      const safeTx = Number.isFinite(tx) ? tx : 0;
+      const safeTy = Number.isFinite(ty) ? ty : 0;
+      if (!container || !container.querySelector) {
+        return { tx: safeTx, ty: safeTy };
+      }
+      const stage = container.querySelector(".mermaid-zoom-stage");
+      if (!stage) return { tx: safeTx, ty: safeTy };
+      const cw = container.clientWidth || 0;
+      const ch = container.clientHeight || 0;
+      const sw = stage.scrollWidth || 0;
+      const sh = stage.scrollHeight || 0;
+      // No dimensions known yet — don't clamp, the caller may
+      // be setting an explicit value (e.g. tests, programmatic
+      // panning before the SVG is measured).
+      if (cw === 0 && ch === 0 && sw === 0 && sh === 0) {
+        return { tx: safeTx, ty: safeTy };
+      }
+      const minTx = sw > cw ? -(sw - cw) : 0;
+      const minTy = sh > ch ? -(sh - ch) : 0;
+      const nextTx = Math.max(minTx, Math.min(0, safeTx));
+      const nextTy = Math.max(minTy, Math.min(0, safeTy));
+      return { tx: nextTx, ty: nextTy };
+    }
+
     function ensureZoomStage(container) {
       // Lazy-create the wrapper if the user calls zoom before a
       // successful mount (the regression test exercises this path).
       if (!container || !container.querySelector) return null;
       let stage = container.querySelector(".mermaid-zoom-stage");
-      if (stage) return stage;
+      if (stage) {
+        // v2.4.1: ensure pan handlers are wired even when the
+        // stage was created by a previous version of the
+        // controller (covers the upgrade path).
+        attachPanHandlers(container);
+        return stage;
+      }
       stage = container.ownerDocument.createElement("div");
       stage.className = "mermaid-zoom-stage";
       // Re-parent any existing children (e.g. an already-rendered
@@ -252,6 +329,9 @@
         stage.appendChild(fragment);
       }
       container.appendChild(stage);
+      // v2.4.1: wire pointer-event handlers on the freshly
+      // created stage so the user can click-drag to pan.
+      attachPanHandlers(container);
       return stage;
     }
 
@@ -302,16 +382,33 @@
       applyZoom(container, getZoom(container));
     }
 
-    function applyZoom(container, zoom) {
+    function applyZoom(container, _zoom) {
+      // v2.4.1: applyZoom now writes the COMPOSED transform
+      // (`translate(tx, ty) scale(z)`) so pan and zoom share a
+      // single CSS property. This keeps the order stable (CSS
+      // applies right-to-left: scale first, then translate) and
+      // avoids the brief flicker a separate `transform-origin`
+      // change would cause. The legacy `_zoom` argument is
+      // ignored — `applyTransform` reads both pan + zoom from
+      // their WeakMaps so the caller's value stays authoritative.
+      applyTransform(container);
+    }
+
+    // v2.4.1: single source of truth for the stage's transform.
+    // Reads current pan + zoom from their WeakMaps and writes
+    // `translate(tx, ty) scale(z)` to the inline style.
+    function applyTransform(container) {
       const stage = ensureZoomStage(container);
       if (!stage) return;
+      const z = getZoom(container);
+      const p = getPan(container);
       // Use the inline `style` so the transform survives any
       // user-provided stylesheet overrides. We also set
       // `transform-origin: top left` so the diagram does not
       // recenter on every zoom step (Mermaid SVGs have their own
       // viewBox, but the surrounding page would jump otherwise).
       stage.style.transformOrigin = "top left";
-      stage.style.transform = `scale(${zoom})`;
+      stage.style.transform = `translate(${p.tx}px, ${p.ty}px) scale(${z})`;
     }
 
     function setZoom(container, nextZoom) {
@@ -352,7 +449,143 @@
     }
 
     function resetZoom(container) {
-      return setZoom(container, ZOOM_DEFAULT);
+      // v2.4.1: resetZoom now also resets the pan offset, so
+      // "100%" returns the user to the top-left corner of the
+      // diagram regardless of where they had dragged it. We
+      // always re-apply the transform even if the zoom value
+      // didn't change — `setZoom` short-circuits when from ===
+      // to (e.g. the user was already at 100%), which would
+      // otherwise leave a stale `translate(tx, ty)` on the
+      // stage even after pan was reset.
+      resetPan(container);
+      const z = setZoom(container, ZOOM_DEFAULT);
+      applyTransform(container);
+      return z;
+    }
+
+    // v2.4.1: pan API. Mutates the per-container panState and
+    // re-applies the composed transform. Pan is clamped so the
+    // diagram cannot be dragged past the viewport (see clampPan).
+    function panTo(container, tx, ty) {
+      if (!container) return { tx: 0, ty: 0 };
+      // Lazy-create the stage so callers can pan before mount
+      // (matches the behaviour of `setZoom` / `applyZoom`).
+      ensureZoomStage(container);
+      const clamped = clampPan(container, Number(tx) || 0, Number(ty) || 0);
+      setPan(container, clamped.tx, clamped.ty);
+      applyTransform(container);
+      return { tx: clamped.tx, ty: clamped.ty };
+    }
+
+    // v2.4.1: pointer-driven drag handlers. We wire them on the
+    // stage (not the container) so they don't interfere with
+    // text selection inside the toolbar.
+    function attachPanHandlers(container) {
+      if (!container || !container.ownerDocument) return;
+      // Already wired — don't double-bind.
+      if (container.__panHandlersAttached) return;
+      const stage = container.querySelector(".mermaid-zoom-stage");
+      if (!stage) return;
+      const doc = container.ownerDocument;
+
+      // pointerdown: capture the starting client coordinates and
+      // the current pan offsets so subsequent pointermove events
+      // can compute the delta.
+      function onPointerDown(ev) {
+        // Only respond to the primary pointer button (left click
+        // or primary touch). Ignore right-click and middle-click.
+        if (ev && typeof ev.button === "number" && ev.button !== 0) return;
+        // Allow the user to drag using touch / pen too.
+        const pid = ev && typeof ev.pointerId === "number" ? ev.pointerId : 1;
+        const cur = getPan(container);
+        dragState.set(container, {
+          startX: ev.clientX,
+          startY: ev.clientY,
+          startTx: cur.tx,
+          startTy: cur.ty,
+          pointerId: pid,
+        });
+        stage.classList.add("is-dragging");
+        try {
+          stage.setPointerCapture && stage.setPointerCapture(pid);
+        } catch (_) {
+          // ignore — setPointerCapture can throw in jsdom
+        }
+        if (ev && typeof ev.preventDefault === "function") {
+          try { ev.preventDefault(); } catch (_) { /* ignore */ }
+        }
+      }
+
+      function onPointerMove(ev) {
+        const drag = dragState.get(container);
+        if (!drag) return;
+        // Filter to the captured pointer only — touchscreens may
+        // send moves for secondary fingers.
+        if (ev && typeof ev.pointerId === "number" && drag.pointerId !== undefined && ev.pointerId !== drag.pointerId) {
+          return;
+        }
+        const dx = ev.clientX - drag.startX;
+        const dy = ev.clientY - drag.startY;
+        panTo(container, drag.startTx + dx, drag.startTy + dy);
+      }
+
+      function endDrag(ev) {
+        const drag = dragState.get(container);
+        if (!drag) return;
+        if (ev && typeof ev.pointerId === "number" && drag.pointerId !== undefined && ev.pointerId !== drag.pointerId) {
+          return;
+        }
+        dragState.delete(container);
+        stage.classList.remove("is-dragging");
+        try {
+          stage.releasePointerCapture && stage.releasePointerCapture(drag.pointerId);
+        } catch (_) {
+          // ignore — release can throw if capture was lost
+        }
+      }
+
+      // pointermove + pointerup + pointercancel all attach to the
+      // stage itself so the drag survives the pointer leaving
+      // the stage element. setPointerCapture keeps the events
+      // routed to the stage even if the cursor drifts off the
+      // diagram. Attaching to the stage (rather than window)
+      // also keeps the implementation deterministic in test
+      // environments where `window` and `doc.defaultView` can
+      // be distinct objects.
+      stage.addEventListener("pointerdown", onPointerDown);
+      stage.addEventListener("pointermove", onPointerMove);
+      stage.addEventListener("pointerup", endDrag);
+      stage.addEventListener("pointercancel", endDrag);
+      // Also attach to document/window as a safety net — some
+      // browsers route pointercancel through the document even
+      // when capture is set. We swallow duplicates in endDrag.
+      if (doc && doc.addEventListener) {
+        doc.addEventListener("pointerup", endDrag);
+        doc.addEventListener("pointercancel", endDrag);
+      }
+      // We need a way to remove these listeners on destroy();
+      // stash a teardown closure on the container.
+      container.__panHandlers = { onPointerDown, onPointerMove, endDrag, doc, stage };
+      container.__panHandlersAttached = true;
+    }
+
+    function detachPanHandlers(container) {
+      if (!container || !container.__panHandlers) return;
+      const h = container.__panHandlers;
+      try {
+        h.stage && h.stage.removeEventListener && h.stage.removeEventListener("pointerdown", h.onPointerDown);
+        h.stage && h.stage.removeEventListener && h.stage.removeEventListener("pointermove", h.onPointerMove);
+        h.stage && h.stage.removeEventListener && h.stage.removeEventListener("pointerup", h.endDrag);
+        h.stage && h.stage.removeEventListener && h.stage.removeEventListener("pointercancel", h.endDrag);
+        if (h.doc && h.doc.removeEventListener) {
+          h.doc.removeEventListener("pointerup", h.endDrag);
+          h.doc.removeEventListener("pointercancel", h.endDrag);
+        }
+      } catch (_) {
+        // ignore
+      }
+      container.__panHandlers = null;
+      container.__panHandlersAttached = false;
     }
 
     /**
@@ -490,18 +723,31 @@
       zoomIn,
       zoomOut,
       resetZoom,
+      // v2.4.1 (feat/task-show-v241-mermaid-pan): pan controls.
+      // The pan offset is tracked per-container in `panState`
+      // and composes with zoom via the same CSS transform
+      // (`translate(tx, ty) scale(z)`). Pointer-driven drag is
+      // wired automatically when the stage is created.
+      getPan,
+      panTo,
       destroy() {
         controllerDestroyed = true;
         // Mark every known container as destroyed so any in-flight render
         // for them is dropped. We can't iterate WeakMaps, but we *can*
         // iterate the Set we maintain.
         const list = Array.from(containers);
-        for (const c of list) markDestroyed(c);
+        for (const c of list) {
+          markDestroyed(c);
+          // v2.4.1: also tear down the pan event listeners so
+          // detached controllers don't leak handlers.
+          detachPanHandlers(c);
+        }
         containers.clear();
       },
       /** Destroy state for a single container. */
       destroyContainer(container) {
         markDestroyed(container);
+        detachPanHandlers(container);
         containers.delete(container);
       },
     };

package/public/style.css

@@ -447,7 +447,7 @@ table.toolcalls tr.tool-row.highlight:hover {
   /* The wrapper that carries the transform. `transform-origin:
      top left` ensures the diagram grows down-right rather than
      re-centering (which would look jumpy). The transform itself
-     is set inline by `MermaidRenderer.applyZoom` so the JS
+     is set inline by `MermaidRenderer.applyTransform` so the JS
      state is the single source of truth. */
   display: inline-block;
   transform-origin: top left;
@@ -466,6 +466,29 @@ table.toolcalls tr.tool-row.highlight:hover {
   min-height: calc(
     var(--mermaid-base-height) * var(--mermaid-placeholder-multiplier)
   );
+  /* v2.4.1 (feat/task-show-v241-mermaid-pan): the stage is
+     grabbable so the user can drag to pan around a zoomed-in
+     diagram. `cursor: grab` is the canonical CSS hint for
+     "this thing is draggable" — combined with `cursor:
+     grabbing` set while a drag is in flight (see
+     `.mermaid-zoom-stage.is-dragging`). `touch-action: none`
+     disables the browser's default pan/zoom gestures on
+     touchscreens so our pointer handlers stay in charge. */
+  cursor: grab;
+  touch-action: none;
+  user-select: none;
+  -webkit-user-select: none;
+}
+
+/* v2.4.1 (feat/task-show-v241-mermaid-pan): the dragging
+   variant is set on the stage while a pointer drag is in
+   flight. `cursor: grabbing` is the conventional "currently
+   dragging" cursor, and we drop the transition so the
+   transform tracks the pointer 1:1 (otherwise the diagram
+   lags behind the cursor). */
+.mermaid-zoom-stage.is-dragging {
+  cursor: grabbing;
+  transition: none;
 }
 
 .hint {