fix(agent-workspace): complete hosted focus and path interactions

Author: Jacobinwwey

README.md

@@ -27,7 +27,7 @@ Unlike traditional "network" views that show a messy web of links, NoteConnectio
 
 ---
 
-## Current Mainline Architecture Status (2026-06-20)
+## Current Mainline Architecture Status (2026-06-24)
 
 ### English
 
@@ -36,6 +36,8 @@ Unlike traditional "network" views that show a messy web of links, NoteConnectio
 - Matched-file discoverability is now intentionally compact: users get a question-mark help affordance for "left-click opens source and highlights the basis" instead of permanent instructional text in the workspace.
 - The matched-file/source-focus path is now right-pane-first: source clicks resolve candidate paths, render Markdown, highlight matched evidence, and expose close controls for the affected right-pane surfaces.
 - `Related Focus` is implemented as a side-pane Focus-mode host backed by the main graph projection contract and the shared double-click decision contract; it switches anchors and opens Markdown inside the pane without moving the main graph DOM or calling the global reader, and the hosted view intentionally omits the main toolbar frame, visible edge layer, and dense background context dots. `Learning Path` hosts the Godot Future Path `diffusion/core/treeLayout` contract, inherits matching Path-mode expansion/collapse/completion state when the live target matches, and routes DOM input through TreeRenderer-style spine-only signals, including right-click prerequisite collapse for the selected node.
+- The hosted `Related Focus` viewport now has pane-local wheel zoom, icon reset, and icon focus-history controls; these controls are intentionally scoped to the right-side Knowledge Focus pane and do not mutate the Tauri main graph runtime.
+- The hosted `Learning Path` Future Path surface now routes node double-click to the same pane-local Markdown reader used by Knowledge Focus, so opening concrete node text stays inside the Guided Learning pane instead of delegating to the global reader.
 - The current implementation uses resolved graph labels such as `water glass`, not internal atom IDs, for the knowledge graph preview surface. This behavior is pinned by strict browser verification.
 - Current code-vs-plan details are tracked in [Agent Knowledge Workspace Graph Preview and Review Closure (2026-06-20)](docs/solutions/agent-knowledge-workspace-graph-preview-and-review-closure-2026-06-20.md) and the [Development Progress Dashboard](docs/diataxis/en/explanation/development-progress-dashboard.md).
 
@@ -46,6 +48,8 @@ Unlike traditional "network" views that show a messy web of links, NoteConnectio
 - 命中文件可发现性现在刻意保持克制：用户通过问号帮助入口了解“左键打开源文档并高亮依据”，而不是在 workspace 中常驻说明文案。
 - 命中文件 / source-focus 路径现在以右侧 pane 为权威阅读面：单击后解析候选路径、渲染 Markdown、高亮命中依据，并在受影响的右侧 pane surface 上提供关闭控件。
 - `关联聚焦` 已实现为右侧 pane 内托管的 Focus-mode：复用主图投影契约与共享双击决策契约，在 pane 内切换 anchor 或打开 Markdown，不移动主图 DOM，也不调用全局 reader；托管视图刻意不显示主界面的工具框、可见边线与密集灰色背景 context 点。`学习路径` 托管 Godot Future Path 的 `diffusion/core/treeLayout` 契约；当主 Path mode 当前 target 匹配时，会继承其 expansion/collapse/completion 状态包，并将 DOM 输入路由为 TreeRenderer 风格的 spine-only 信号，包括对选中主干节点的右键 prerequisite 收起。
+- 托管 `关联聚焦` viewport 现在具备 pane-local 滚轮缩放、图标式 reset 与图标式 focus history 控件；这些控制只作用于右侧知识聚焦 pane，不会修改 Tauri 主图运行时。
+- 托管 `学习路径` Future Path surface 现在把节点双击路由到与知识聚焦相同的 pane-local Markdown reader，因此打开具体节点文本会留在引导式学习 pane 内，而不是委托给全局 reader。
 - 当前实现使用 `water glass` 这类解析后的图标签，而不是内部 atom ID，作为知识图预览展示名称；该行为已由 strict browser verification 固定。
 - 当前代码 / 方案对齐详情见 [Agent 知识工作区图预览与回答审核收口（2026-06-20）](docs/solutions/agent-knowledge-workspace-graph-preview-and-review-closure-2026-06-20.md) 与 [开发进度看板](docs/diataxis/zh/explanation/development-progress-dashboard.md)。
 

docs/diataxis/en/explanation/development-progress-dashboard.md

@@ -3,6 +3,38 @@
 This page is the implementation-facing dashboard for the Knowledge Mastery evolution plan.
 It tracks what is already implemented, where the hard gaps remain, and how to verify progress from code and runtime behavior.
 
+## 2026-06-24 Knowledge Workspace Hosted Interaction Parity
+
+This increment closes two remaining pane-hosting gaps without changing the ownership model established on 2026-06-22.
+The Knowledge Workspace still reuses Focus/Future Path behavior contracts locally; it does not reparent the Tauri main graph DOM and does not open or embed the native Godot window by default.
+
+What is now true in code:
+
+- `src/frontend/workspace_panes.js` wraps the hosted Focus projection in a pane-local viewport with wheel zoom, pointer panning, icon reset, and icon focus-history controls.
+- Hosted Focus history is scoped to the Knowledge Focus pane, bounded to the most recent anchors, and switches anchors through the same hosted `switchHostedFocusNode()` path instead of mutating the main graph runtime.
+- Hosted Focus still hides the dense gray context-dot background, visible edge layer, and main toolbar frame by default, while preserving Focus semantic labels and active node density.
+- `src/frontend/godot_tree_interactions.js` now lets callers provide `nodeReaderRequested`; hosted Future Path uses that callback so double-click opens concrete node Markdown in the Guided Learning pane, while callers without the callback keep the previous prerequisite expand/collapse fallback.
+- `src/frontend/workspace_panes.js` now uses a shared pane-local reader path for both Knowledge Focus and Guided Learning, so node content opens inside the pane that owns the interaction and global `reader.open` remains untouched.
+- `src/frontend/locales/en.json` and `src/frontend/locales/zh.json` now include the new Focus viewport control labels, keeping locale contracts intact.
+- `scripts/verify-agent-workspace-browser.js` now asserts the real browser regression path: Future Path double-click emits `node_reader_requested`, reads `Knowledge_Base/waterglass/water glass.md`, renders Markdown inside the learning-path pane, keeps global reader calls at zero, zooms the hosted Focus viewport by wheel, resets to `1/0/0`, opens focus history, and switches history back to `water glass`.
+- `src/agent_workspace.frontend.test.ts` now pins the same contracts at jsdom level for fast regression feedback.
+
+Code-vs-plan reconciliation:
+
+| Requirement | Current implementation evidence | Progress call |
+|---|---|---|
+| Knowledge Focus should behave like Focus mode in a small right-side pane | Hosted Focus uses the existing projection/double-click contract plus pane-local wheel zoom, reset, and history controls. | Implemented |
+| Knowledge Focus controls must not take over the Tauri main graph | The hosted viewport stores transform state on pane-local DOM attributes and calls hosted anchor switching only. | Implemented |
+| Learning Path double-click should open concrete node content in-place | Hosted Future Path passes `nodeReaderRequested` into the TreeRenderer adapter and opens the shared pane-local Markdown reader. | Implemented |
+| Reuse must remain compatible | The TreeRenderer adapter falls back to the prior expansion behavior when no reader callback is supplied. | Implemented |
+| Regression coverage must be executable | Strict browser verification now checks `water glass` Focus/Future Path interactions, source read path, Markdown render, zoom/reset/history, and global reader non-use. | Implemented |
+
+Tradeoff:
+
+This still deliberately avoids native Godot window docking.
+That is the correct boundary for now: embedding native windows would require platform-specific ownership of window parenting, input focus, teardown, and reader routing.
+The shipped path reuses the stable graph/path contracts and renderer semantics inside the web workspace, which is lower risk and keeps the main Tauri surface isolated.
+
 ## 2026-06-22 Knowledge Workspace Hosted Focus/Future Path Closure
 
 The latest closure is not a new framework direction.

docs/diataxis/zh/explanation/development-progress-dashboard.md

@@ -3,6 +3,38 @@
 本页是“知识彻底掌握演进方案”的实现侧进度看板。
 它用于回答三件事：哪些能力已落地、哪些关键缺口仍在、如何用代码与运行时证据验证推进结果。
 
+## 2026-06-24 知识工作区托管交互对齐
+
+本次增量收口两个剩余的 pane 托管缺口，但不改变 2026-06-22 已确定的 owner 边界。
+Knowledge Workspace 继续在本地复用 Focus/Future Path 的行为契约；它不重挂 Tauri 主图 DOM，也不默认打开或嵌入 Godot 原生窗口。
+
+当前代码已经成立的事实：
+
+- `src/frontend/workspace_panes.js` 为托管 Focus projection 增加了 pane-local viewport，支持滚轮缩放、指针拖拽平移、图标式 reset 与图标式 focus history 控件。
+- 托管 Focus history 只作用于知识聚焦 pane，限制最近 anchor 数量，并通过同一条托管 `switchHostedFocusNode()` 路径切换 anchor，而不是修改主图运行时。
+- 托管 Focus 继续默认隐藏密集灰色 context-dot 背景、可见边线与主界面工具框，同时保留 Focus 语义标签和主节点信息密度。
+- `src/frontend/godot_tree_interactions.js` 现在允许调用方提供 `nodeReaderRequested`；托管 Future Path 使用该回调让双击节点在引导式学习 pane 内打开具体 Markdown，而未提供该回调的调用方仍回退到原有 prerequisite 展开 / 收起行为。
+- `src/frontend/workspace_panes.js` 现在让知识聚焦与引导式学习共用 pane-local reader 路径，因此节点内容会在发起交互的 pane 内打开，全局 `reader.open` 不会被调用。
+- `src/frontend/locales/en.json` 与 `src/frontend/locales/zh.json` 已补齐新的 Focus viewport 控件文案，locale contract 继续成立。
+- `scripts/verify-agent-workspace-browser.js` 现在断言真实浏览器回归路径：Future Path 双击发出 `node_reader_requested`，读取 `Knowledge_Base/waterglass/water glass.md`，在 learning-path pane 内渲染 Markdown，全局 reader 调用保持为零，托管 Focus viewport 可滚轮缩放、reset 回到 `1/0/0`、打开 focus history，并可通过 history 回跳到 `water glass`。
+- `src/agent_workspace.frontend.test.ts` 在 jsdom 层固定同一组契约，提供更快的回归反馈。
+
+代码 / 方案对齐：
+
+| 要求 | 当前实现证据 | 进度判断 |
+|---|---|---|
+| 知识聚焦应在较小右侧 pane 中具备 Focus mode 级交互 | 托管 Focus 复用现有 projection / double-click 契约，并补齐 pane-local 滚轮缩放、reset、history 控件。 | 已实现 |
+| 知识聚焦控件不得接管 Tauri 主图 | 托管 viewport 的 transform 状态只写入 pane-local DOM 属性，anchor 切换也只走 hosted path。 | 已实现 |
+| 学习路径双击节点应在本 pane 内打开具体内容 | 托管 Future Path 将 `nodeReaderRequested` 传入 TreeRenderer 适配层，并打开共享 pane-local Markdown reader。 | 已实现 |
+| 复用必须保持兼容 | TreeRenderer 适配层在未提供 reader callback 时继续回退到旧的展开 / 收起行为。 | 已实现 |
+| 回归覆盖必须可执行 | strict browser verification 已检查 `water glass` Focus/Future Path 交互、源文档读取、Markdown 渲染、缩放 / reset / history，以及全局 reader 不被调用。 | 已实现 |
+
+关键取舍：
+
+这里仍然刻意不做 Godot 原生窗口 docking。
+这个边界是正确的：嵌入原生窗口需要平台级 owner 处理 window parenting、输入焦点、teardown 与 reader 路由。
+当前落地路径是在 web workspace 内复用稳定的 graph/path 契约与 renderer 语义，风险更低，也能保持 Tauri 主界面隔离。
+
 ## 2026-06-22 知识工作区托管 Focus/Future Path 收口
 
 最新收口不是新的框架方向。