@joekytc/dsh-swarm 0.1.2 → 0.2.0

package/skills/llm-wiki-skill/docs/design/oriental-atlas/reviews/result-review.md

@@ -0,0 +1,68 @@
+# 结果评审
+
+## 来源包
+
+- Brief：`.briefpilot/graph-html-redesign/design-brief.json`
+- DESIGN.md：`.briefpilot/graph-html-redesign/DESIGN.md`
+- 已选策略：东方编辑部 × 数字山水
+- 目标工具：generic
+
+## 评审证据
+
+- 证据类型：local_file + screenshot_reference
+- 证据路径：`.briefpilot/graph-html-redesign/oriental-editorial-atlas.html`
+- 视觉证据：`/tmp/oriental-atlas-desktop.png`、`/tmp/oriental-atlas-tablet.png`、`/tmp/oriental-atlas-mobile.png`、`/tmp/oriental-atlas-mobile-lower.png`
+- 摘要：本地 HTML 页面已打开并截图检查。桌面宽度 1440、平板宽度 768、手机宽度 375 均无控制台错误、无横向溢出。页面整体采用米白纸面、墨色文字、朱砂强调、青绿/夜青辅助，包含左侧文献索引、中间图谱、右侧札记详情、搜索、筛选、置信度、状态切换和响应式降级。
+
+## 保留点
+
+- 视觉方向基本命中：首屏明显比 demo 更像成熟产品，东方编辑部气质来自文献索引、纸面、朱砂线、札记详情，而不是廉价纹样。
+- 信息结构完整：左侧导航、中间图谱、右侧详情三栏清楚，搜索、社区、学习队列、推荐起点、图例、洞察、相邻节点都有入口。
+- 设计 token 大体遵循 DESIGN.md：米白、墨色、朱砂、青绿、夜青、旧地图线和细边框体系一致。
+- 落地性较好：单文件 HTML，无外部网络资源；图谱、状态面板和交互用 vanilla HTML/CSS/JS 实现。
+- 技术检查通过：桌面、平板、手机截图无横向溢出；控制台无错误。
+
+## 问题
+
+| 严重程度 | Brief 依据 | 问题 | 证据 | 建议修改 |
+|---|---|---|---|---|
+| medium | `review-checklist.md`：触控目标至少 44px；`DESIGN.md` Responsive Behavior | 移动端部分按钮高度只有 36px，低于 44px 触控目标。 | 浏览器检查显示 `.segmented button` 和 `.state-button` 在 375px 下高 36px，`空` 按钮宽 34px。 | 将所有移动端交互按钮 `min-height` 调整到 44px；状态按钮在窄屏下用 2x2 或单行横向滚动，不要缩成 34x36。 |
+| medium | `design-brief.json`：首屏要看出“东方编辑部 × 数字山水”；移动端可降级但不能丢主信息 | 手机首屏只看到标题和文献索引，中央图谱和数字山水舞台要下滑很久才出现，移动端第一眼缺少“数字山水”。 | `/tmp/oriental-atlas-mobile.png` 首屏只显示 topbar、搜索、社区和学习队列，未露出图谱。 | 移动端在文献索引上方或标题下方加入一张紧凑“图谱预览卡”，或把主内容顺序改为标题 → 图谱预览 → 文献索引 → 详情。 |
+| low | `DESIGN.md` Components：Node 有 disabled/unavailable、error 状态；Buttons 有 pressed、disabled、error 状态 | 状态覆盖主要集中在 loading/empty/error，按钮和节点的 disabled/unavailable 展示不够明确。 | 源码有 loading/empty/error 和 selected/focus/hover，但未看到清楚的 disabled/unavailable 示例。 | 增加一个不可用节点或不可用来源示例，并补 `.is-disabled` / `[disabled]` 的视觉规则。 |
+| low | `review-checklist.md`：截图/GIF 有记忆点，适合 README | 桌面首屏很稳，但“数字山水”的视觉记忆点仍偏背景层，整体更像东方编辑部而不是混合方向。 | `/tmp/oriental-atlas-desktop.png` 中图谱背景线条克制，山水/星图层次存在但不强。 | 可以适度强化中图的地貌层：增加 1-2 层更有识别度的等高线/星点路径，但保持低对比，不遮挡节点。 |
+
+## 视觉评审
+
+- 状态：available_model_image
+- 来源：本地 HTML 截图 `/tmp/oriental-atlas-desktop.png`、`/tmp/oriental-atlas-tablet.png`、`/tmp/oriental-atlas-mobile.png`、`/tmp/oriental-atlas-mobile-lower.png`
+- 说明：已使用截图进行视觉检查。桌面版符合度高；移动端无横向溢出，但首屏策略弱化了图谱主角，部分按钮小于 44px。
+
+## 决定
+
+- 决定：tweak
+- 策略是否保留：true
+- 策略变化原因：无需改变策略，问题是局部响应式和状态覆盖不完整。
+- 提示意图：targeted_modification
+
+## 下一轮提示摘要
+
+保留：
+
+- 保留米白纸面、墨色文字、朱砂强调、青绿/夜青辅助的视觉系统。
+- 保留左侧文献索引、中间知识舆图、右侧札记详情的桌面三栏结构。
+- 保留状态面板、置信度图例、社区导航、学习队列和推荐起点。
+- 保留无外部依赖、单文件 HTML、vanilla CSS/JS 的落地方式。
+
+修改：
+
+- 修正移动端触控目标，所有按钮和可点卡片至少 44px 高，窄按钮至少 44px 宽。
+- 调整移动端内容顺序或增加图谱预览卡，让 375px 首屏能看到“数字山水图谱”的存在。
+- 增加 disabled/unavailable 节点、来源或按钮状态示例。
+- 稍微强化中央图谱的山水/星图视觉记忆点，但不要遮挡节点和边。
+
+验收检查：
+
+- 375px 截图首屏能看到标题、关键状态和图谱预览，不只看到文献索引。
+- 所有 `button/input/a` 在移动端可点击区域不小于 44px。
+- 1440、768、375 三档无横向滚动，无控制台错误。
+- loading、empty、error、selected、focus、disabled/unavailable 状态都能被看见或触发。

package/skills/llm-wiki-skill/docs/graph/2026-06-16-interaction-risk-audit.md

@@ -0,0 +1,88 @@
+# Graph Interaction Risk Audit
+
+日期：2026-06-16
+
+适用计划：`docs/plans/2026-06-16-graph-six-layer-architecture-phased-plan.md`
+
+## 审计目标
+
+这份审计把本轮图谱重构要覆盖的交互风险集中记录下来。它不是普通 bug list，而是后续每个阶段的验收清单：每个风险都要明确期望行为、owner layer、验证方法和目标阶段。
+
+核心原则：
+
+- 图谱拥有自己的交互空间。节点、边、社区色块、空白画布上的滚轮、拖拽、hover、点击、键盘取消都先进入图谱交互链路。
+- 浏览器默认行为只在明确允许的文本、输入、阅读区域发生。
+- 命中、坐标、状态、渲染不能各算各的。
+- 工作台和离线 HTML 是同等目标，不能只修其中一个。
+
+## Owner Layer 约定
+
+| Owner layer | 负责范围 |
+|---|---|
+| GraphGestures | 原始 pointer、wheel、keyboard、touch 事件；点击/拖拽/缩放意图；阻止浏览器默认行为 |
+| SpatialIndex / GraphLayout | 节点、边、社区色块、空白图谱区域命中；布局边界；社区色块软边界 |
+| GraphViewport | 世界坐标、屏幕坐标、小地图坐标转换；相机缩放、平移、fit、resize anchor |
+| GraphState | hover、selection、active drag、pins、positions、viewport 等图谱运行状态 |
+| GraphRenderer | 节点、边、社区色块、小地图、hover 卡片、工具栏、离线 reader 的绘制 |
+| GraphFacade | workbench/offline 公开 API、宿主回调、持久化 pin、抽屉/选择语义协调 |
+
+## 风险矩阵
+
+| 风险 | 期望行为 | Owner layer | 验证方法 | 目标阶段 |
+|---|---|---|---|---|
+| Trackpad wheel 在图谱内被页面滚动或页面缩放抢走 | 鼠标或触控板停在节点、边、社区色块、空白画布上时，wheel 都只改变图谱相机；页面尺寸、页面滚动位置和浏览器缩放不变 | GraphGestures + GraphViewport | Node test 覆盖 wheel target policy；workbench/offline browser 脚本记录 transform 变化、root scroll、页面 viewport 指标 | Phase 2 |
+| `ctrl/meta + wheel` 触发浏览器页面缩放 | 图谱拥有的 surface 内，pinch-like wheel 被图谱接管；输入框、阅读正文等 blocker 内不接管 | GraphGestures | Browser 脚本 dispatch cancelable wheel，记录 `visualViewport.scale`、`devicePixelRatio`、clientWidth 和 graph transform | Phase 2 |
+| 鼠标在节点上滚轮不能缩放 | 节点命中优先，但节点上的 wheel 仍走 graph zoom，不因为节点可点击/可拖拽而阻断缩放 | GraphGestures + SpatialIndex | `gestures.test.ts` 覆盖 node target wheel；workbench/offline 真实节点上滚轮验证 transform 改变 | Phase 2 |
+| 鼠标在社区色块上滚轮不能缩放 | 社区色块可点击选择整个社区，但 wheel 仍走 graph zoom；点击和滚轮互不抢语义 | GraphGestures + SpatialIndex | `gestures.test.ts` 覆盖 community target wheel；community wash browser regression | Phase 2 |
+| 空白拖动画布时选中工具栏或页面文字 | active pan/drag 期间禁止 native selection；结束或取消后清理锁定状态 | GraphGestures + GraphRenderer | Browser 脚本拖动画布后断言 `window.getSelection().toString()` 为空、toolbar/search 文本未被选中、root dataset 无 stuck active | Phase 2 |
+| 原生 drag selection 或页面 scroll 泄漏进图谱 | 图谱 owned surface 在 active gesture 期间阻止默认拖选、滚动和 scroll chaining；root scroll 被复位 | GraphGestures | Browser 脚本拖拽空白、拖节点、拖社区色块，检查 root scroll、document selection、body scroll | Phase 2 |
+| 快速松开节点后节点回到原位 | drag end intent 必须带最终 pointer 坐标；即使最后一帧 move 没来得及提交，release 坐标也会提交成 pin | GraphGestures + GraphViewport + GraphState + GraphFacade | State machine test 覆盖 final screen point；browser 脚本快速 mouse down/move/up，检查节点位置和 pinned 状态 | Phase 2 |
+| 节点拖拽不跟手或跳到别处 | 拖拽以 grabbed offset 为基准，屏幕点经 GraphViewport 反投影；节点中心不突然吸到鼠标中心，也不使用旧坐标公式 | GraphViewport + GraphState + GraphFacade | `simulation-bridge.test.ts` 覆盖 offset；browser 脚本记录 pointer 与节点中心距离上限 | Phase 3 |
+| 节点被社区色块或固定世界尺寸锁住 | 社区色块是软视觉区域；节点可拖出色块；世界 bounds 由布局和 pin/outlier 推导，不用 `1000x680` 当硬笼子 | GraphLayout + GraphViewport | render model/community wash tests；community wash browser regression 拖出初始 wash 并检查 pin | Phase 3 / Phase 6 |
+| 社区色块无限追随远处离群节点 | 色块可受拖出节点影响，但有上限；不会变成覆盖全屏的巨大色块；社区成员关系不因拖拽改变 | GraphLayout + GraphRenderer | `community-wash.test.ts` 覆盖 outlier cap；browser 脚本检查 wash 大小上限和成员稳定 | Phase 6 |
+| 点击社区和拖动社区阈值冲突 | 小位移点击选中社区并打开选区语义；超过阈值不触发社区点击，也不误启动节点拖拽 | GraphGestures + SpatialIndex | `gestures.test.ts` 覆盖 community move cancel；browser 脚本 move past threshold 后 visible nodes 不变 | Phase 2 / Phase 6 |
+| DOM stacking order 改变后命中不同 | 节点命中优先于边和社区；社区优先于空白；命中来源是 SpatialIndex，不是 `elementFromPoint` 或 DOM 层级 | SpatialIndex / GraphLayout + GraphGestures | 新增 `spatial-index.test.ts`，构造重叠节点/边/社区并打乱 DOM 顺序；renderer boundary test 禁止旧 DOM hit owner | Phase 1 / Phase 7 |
+| Hover 简介位置漂移 | hover anchor 来自节点/边的世界坐标，经 GraphViewport 投影；zoom、pan、drag、resize、drawer open 后重新计算 | GraphViewport + GraphState + GraphRenderer | `overlays.test.ts` 扩展投影；workbench/offline browser 测 preview 和 anchor gap、viewport 内不溢出 | Phase 3 |
+| Hover 卡片与节点不同步 | hover 状态存于 GraphState，Renderer 只绘制；节点位置更新后卡片 anchor 跟随同一状态快照 | GraphState + GraphRenderer | Browser 脚本在拖拽后 hover，记录卡片相对节点距离；state test 覆盖 hover snapshot | Phase 3 |
+| Search 输入框边界误接管 | search 内 wheel、pointer、keyboard 不触发图谱 zoom/pan/shortcut；离开 search 后恢复图谱控制 | GraphGestures + GraphFacade | `gestures.test.ts` blocker 覆盖 search；browser 脚本打开 search 后滚轮不改变图谱 transform | Phase 2 |
+| Toolbar/legend 边界误接管 | 工具栏和图例作为图谱控件：点击按控件语义走；wheel/pointer 不误触发画布 pan；空白点击可关闭 popover | GraphGestures + GraphRenderer | toolbar state tests；browser 脚本覆盖 toolbar panel、legend row、blank close | Phase 2 |
+| Minimap 边界误接管 | minimap 有自己的点击/导航语义；不被 blank pan 或 graph wheel 错认；minimap 投影只走 GraphViewport | GraphGestures + GraphViewport + GraphRenderer | viewport minimap tests；browser 脚本 wheel over minimap 不 zoom graph，minimap click/viewport rect 稳定 | Phase 3 |
+| Drawer/reader 边界误接管 | workbench drawer 和 offline reader 内允许文本阅读/滚动/按钮；不触发 graph drag/zoom；图谱 anchor 不因 drawer resize 漂移 | GraphGestures + GraphFacade + GraphViewport | Browser 脚本 drawer wheel 不 zoom graph，drawer resize 后选中节点保持可见且 hover 不溢出 | Phase 2 / Phase 3 |
+| 数据刷新时正在拖拽 | active drag 期间 diff queue 暂存或合并；释放后以最终 pin/position 重建 layout 和 SpatialIndex，不用旧 snapshot 覆盖用户拖拽 | GraphState + GraphFacade + GraphLayout | GraphDiffQueue tests 已有基础，扩展 active drag release 后 replay；browser 可用 mock refresh 验证无回弹 | Phase 3 |
+| Pointer cancel / lost pointer capture 后状态卡住 | 取消事件只清理 active gesture，不误提交 click/pin；root dataset、cursor、selection lock 都恢复 | GraphGestures + GraphState | `gestures.test.ts` 已覆盖基础，扩展 DOM cleanup；browser 脚本 dispatch pointercancel/lostpointercapture 后继续可操作 | Phase 2 |
+| Escape 行为混乱 | active drag/pan 优先取消当前手势；无 active gesture 时清理 hover/selection/drawer/search，具体语义由 GraphFacade 统一 | GraphGestures + GraphFacade + GraphState | State machine test；workbench/offline browser 脚本覆盖 drawer、selection、search、active drag | Phase 2 / Phase 4 |
+| 键盘快捷键抢输入框 | search、drawer、text-control 内的 Tab/Enter/Space/Arrow/plus/minus/zero 不触发图谱快捷键；图谱 focus 内才响应 | GraphGestures + GraphFacade | gestures blocker tests；browser 脚本聚焦 search/drawer 按键验证不改变 graph transform/selection | Phase 2 |
+| Graph focus 不明确 | 点击/Tab 进入图谱后键盘归图谱；离开图谱或进入文本控件后键盘归宿主/浏览器 | GraphGestures + GraphFacade | Browser 脚本检查 focus ring、keyboard commands only under graph focus | Phase 4 |
+| Touch 一指拖动画布和拖节点不稳定 | 支持 pointer events 的触摸：一指空白 pan、一指节点 drag；pointercancel 清理；没有复杂多指编辑时提供按钮 fallback | GraphGestures + GraphViewport | Browser 脚本模拟 pointerType touch；Node state machine test 覆盖 touch-like pointer sequence | Phase 2 |
+| 双击或连续点击语义散落 | 双击 fit/reset 或其他图谱命令必须由 GraphGestures 发 intent，Renderer 不直接绑定 root dblclick | GraphGestures + GraphFacade | Final cleanup `rg` 检查 static-renderer 不再绑定 root dblclick；browser 脚本覆盖 reset/fit | Phase 5 / Phase 7 |
+| 旧 renderer 继续偷偷拥有交互 | `static-renderer.ts` 终态只能是 composition/compat shell；不能保留 root wheel/pointer/dblclick/keydown/hit-test/coordinate owner | GraphFacade + GraphRenderer | Final cleanup `rg` 检查；renderer-boundary test 用 runtime contract 防止换文件名复发 | Phase 5 / Phase 7 |
+| Workbench 与离线 HTML 行为分叉 | graph-engine 内的行为同源；workbench 只负责宿主抽屉和能力，offline 只负责离线 reader；核心交互测试两端都跑 | GraphFacade | `tests/graph-workbench-interactions.regression-1.sh` 和 `tests/graph-offline-phase-6.regression-1.sh` 同时通过 | Phase 7 |
+
+## 当前覆盖与缺口
+
+已有覆盖：
+
+- `packages/graph-engine/test/gestures.test.ts` 已覆盖基础 target 分类、节点拖拽、社区点击取消、空白 pan、pointer cancel、Escape。
+- `packages/graph-engine/test/viewport.test.ts` 已覆盖 zoom/pan/fit/minimap/resize anchor。
+- `packages/graph-engine/test/simulation-bridge.test.ts` 已覆盖 dragged point under pointer 和 off-world drag 不被投影层 clamp。
+- `packages/graph-engine/test/community-wash.test.ts` 与 `render-model.test.ts` 已覆盖社区色块 outlier cap、拖出后成员稳定。
+- `tests/browser/graph-workbench-interactions.mjs`、`graph-offline-phase-6.mjs`、`graph-community-wash-interactions.mjs` 已有真实浏览器检查基础。
+
+必须补齐：
+
+- SpatialIndex 作为真实命中来源，而不是 DOM target 的接口包装。
+- 图谱内 `ctrl/meta + wheel` 和 trackpad pinch-like wheel 不改变浏览器页面 zoom 的浏览器证据。
+- 空白 pan、节点 drag 后无 native text selection 的浏览器证据。
+- 快速 release 用最终 pointer 坐标提交 pin 的浏览器证据。
+- hover preview 在 drag、zoom、pan、drawer resize 后仍锚定节点/边的浏览器证据。
+- renderer boundary 检查，防止旧 `static-renderer.ts` 或新 renderer 文件重新接管交互。
+
+## 阶段入口条件
+
+Phase 1 之前必须满足：
+
+- 本审计文档已提交。
+- 进度账本记录 Phase 0 task 0.2 的验证和提交号。
+- 不开始行为改动，直到 task 0.3 把现有测试与缺口映射到目标阶段。
+
+后续每阶段完成时，progress 文件必须把本审计中的相关风险标成已有验证证据，不能只写“实现完成”。

package/skills/llm-wiki-skill/docs/graph/2026-06-16-interaction-test-coverage-map.md

@@ -0,0 +1,212 @@
+# Graph Interaction Test Coverage Map
+
+日期：2026-06-16
+
+适用计划：`docs/plans/2026-06-16-graph-six-layer-architecture-phased-plan.md`
+
+前置审计：`docs/graph/2026-06-16-interaction-risk-audit.md`
+
+## 目标
+
+这份文档把交互风险映射到现有测试、缺口测试和后续阶段。它用于防止后续重构只移动代码、不建立保护网。
+
+判定规则：
+
+- `Covered`：已有单元测试或浏览器脚本能直接防住该风险。
+- `Partial`：已有测试覆盖了核心数学或状态，但没有覆盖真实浏览器行为或最终架构边界。
+- `Missing`：当前没有明确测试，必须在目标阶段新增。
+
+## 覆盖总览
+
+| 风险组 | 当前状态 | 已有保护 | 必补保护 | 目标阶段 |
+|---|---|---|---|---|
+| 节点/边/社区/空白 wheel zoom | Partial | `gestures.test.ts` target policy；`graph-workbench-interactions.mjs` 和 `graph-offline-phase-6.mjs` 覆盖部分 wheel target | trackpad-like wheel、`ctrl/meta + wheel` 不触发页面 zoom 的浏览器证据 | Phase 2 |
+| 浏览器默认行为隔离 | Missing | root scroll reset 有部分浏览器检查 | native selection、body scroll、root scroll、browser zoom 指标统一记录 | Phase 2 |
+| 点击/拖拽状态机 | Partial | `gestures.test.ts` 覆盖阈值、cancel、Escape；`simulation-bridge.test.ts` 覆盖 grabbed offset | 快速 release 用 final pointer 坐标提交 pin 的浏览器证据 | Phase 2 |
+| SpatialIndex 命中 | Missing | 现有 target classifier 不依赖 DOM mock，但仍不是真实空间命中 | 新增 `spatial-index.test.ts`，覆盖节点、边、社区、空白、重叠优先级、旧世界外命中 | Phase 1 |
+| 坐标和相机 | Partial | `geometry.test.ts`、`viewport.test.ts`、`simulation-bridge.test.ts`、`overlays.test.ts` | layout-driven world bounds、drawer resize 后 hover/selection anchor 的浏览器证据 | Phase 3 |
+| 图谱运行状态 | Partial | `runtime-state.test.ts`、`queue.test.ts` 覆盖基础状态和 diff queue | 数据刷新期间 active drag 的最终 pin 不被 stale snapshot 覆盖 | Phase 3 |
+| 社区色块软边界 | Partial | `community-wash.test.ts`、`render-model.test.ts`、`graph-community-wash-interactions.mjs` | SpatialIndex priority 接管社区命中；expanded bounds 下 cap 不无限放大 | Phase 6 |
+| 工具栏/search/legend/minimap/drawer 边界 | Partial | `gestures.test.ts` blocker policy；toolbar tests；workbench/offline browser 覆盖部分 UI | keyboard focus、wheel blocker、pointer blocker、drawer resize anchor 的一组统一回归 | Phase 2 / Phase 3 |
+| hover preview anchor | Partial | `overlays.test.ts` 和 browser hover checks | zoom、pan、drag、drawer resize、community focus 后统一 anchor gap 证据 | Phase 3 |
+| keyboard/touch | Missing | Escape 基础 state machine 覆盖 | graph focus 内快捷键、text-control blocker、touch-like pointer sequence | Phase 2 / Phase 4 |
+| renderer 旧责任清理 | Missing | 计划内 `rg` 命令尚未转成阶段测试 | renderer boundary test + final cleanup `rg`，禁止 root interaction 和 coordinate owner 回到 renderer | Phase 5 / Phase 7 |
+| workbench/offline parity | Partial | `graph-workbench-interactions.mjs`、`graph-offline-phase-6.mjs`、`graph-community-wash-interactions.mjs` | 每个核心交互在两端都留下证据 artifact | Phase 7 |
+
+## 现有测试归位
+
+### GraphGestures
+
+已有：
+
+- `packages/graph-engine/test/gestures.test.ts`
+  - graph target 分类：blank、node、community wash、edge、minimap、toolbar、search、legend、drawer、text-control。
+  - wheel target policy：blank/node/community/edge 可 zoom；controls/drawer/minimap/text-control 阻断。
+  - pointerdown target policy：node drag、community click、blank pan、controls blocker。
+  - gesture state machine：node click、node drag、community click cancel、blank pan、pointercancel、lostpointercapture、Escape。
+
+缺口：
+
+- 当前 `ctrl/meta + wheel` 在单元测试里是 blocked，但本轮设计要求 graph-owned surface 内必须阻止浏览器页面 zoom 并转为图谱意图；Phase 2 必须重做该策略并补浏览器证据。
+- 缺 touch-like pointer sequence。
+- 缺 keyboard focus 和 text-control blocker 的真实浏览器证据。
+- 缺 active gesture 期间 native selection 清理证据。
+
+### GraphViewport / Geometry
+
+已有：
+
+- `packages/graph-engine/test/geometry.test.ts`
+  - world/screen round trip。
+  - drawer-style resize 后 layer point round trip。
+  - minimap projection。
+  - 不在投影 helper 内静默 clamp。
+- `packages/graph-engine/test/viewport.test.ts`
+  - wheel zoom around pointer。
+  - pan、fit、center、resize anchor、minimap rect、frame commit coalescing。
+- `packages/graph-engine/test/simulation-bridge.test.ts`
+  - grabbed point stays under pointer。
+  - drag start 不跳到 pointer center。
+  - off-world drag 不在 projection/bridge 层 clamp。
+- `packages/graph-engine/test/overlays.test.ts`
+  - node/edge hover anchor 使用投影点。
+  - preview card stay inside viewport。
+
+缺口：
+
+- GraphViewport 还需要接入 layout-driven world bounds，不再让固定世界尺寸决定拖拽范围。
+- Browser 需要证明 zoom、pan、drag、drawer resize 后 hover preview 仍与节点/边锚定。
+- Minimap 点击和当前 viewport rect 需要在新 world bounds 下验证。
+
+### GraphState / Diff Queue
+
+已有：
+
+- `packages/graph-engine/test/runtime-state.test.ts`
+  - viewport、hover、selection、focus、pins、positions、active gesture 一处更新。
+  - simulation proposal 不直接变成 committed positions。
+  - snapshot clone 防止外部改 hidden state。
+- `packages/graph-engine/test/queue.test.ts`
+  - graph hidden 时 diff queue 合并。
+  - drag 期间 hold diff，释放后 consume。
+
+缺口：
+
+- active drag release 同时遇到 data refresh 时，最终 release position 必须优先于 stale replay。
+- GraphState 与 GraphFacade 之间需要一个明确的 commit path 测试，证明 fast release 不回弹。
+
+### GraphLayout / Community Wash
+
+已有：
+
+- `packages/graph-engine/test/community-wash.test.ts`
+  - small communities remain selectable。
+  - dragged outlier influences wash but does not chase it without cap。
+  - multi-direction outlier cap。
+- `packages/graph-engine/test/render-model.test.ts`
+  - pinned member outside wash cap 时 community membership 稳定。
+  - member dragged beyond cap 后 community focus 稳定。
+- `tests/browser/graph-community-wash-interactions.mjs`
+  - community wash 上 wheel zoom。
+  - 点击 community wash 进入社区。
+  - 超过阈值移动取消 community click。
+  - 节点可以拖出初始 wash 并提交 pin。
+
+缺口：
+
+- SpatialIndex 接管后，community hit 不能再依赖 DOM stacking。
+- expanded layout bounds 下，wash cap 仍然不能无限扩张。
+- 节点拖出 wash 后，wash soft-boundary 更新要和 membership 稳定同时验证。
+
+### GraphRenderer / Boundary
+
+已有：
+
+- `packages/graph-engine/test/render-model.test.ts`
+  - renderable graph、selected state、density、community focus、pinned positions。
+- `packages/graph-engine/test/toolbar.test.ts`
+  - toolbar panel state 和 blank click close。
+- `packages/graph-engine/test/search-and-legend.test.ts`
+  - search helpers 和 legend selection。
+- `tests/browser/graph-stage-4-5.mjs`
+  - 旧阶段的 wheel、selection、drawer、hover、edge preview、responsive checks。
+
+缺口：
+
+- 缺 renderer boundary test：Renderer 不能直接拥有 root wheel/pointer/dblclick/keydown。
+- 缺 final `rg` 检查转成可重复的测试证据。
+- 缺 DOM order 改变但 SpatialIndex 命中不变的测试。
+
+### Workbench / Offline
+
+已有：
+
+- `tests/browser/graph-workbench-interactions.mjs`
+  - workbench desktop/narrow、wheel targets、blocker targets、hover、drawer resize、community drag、pan/minimap reset。
+- `tests/browser/graph-offline-phase-6.mjs`
+  - offline hover、drag under pointer、selection panel、reader boundary、root scroll 等。
+- `tests/browser/graph-community-wash-interactions.mjs`
+  - offline community wash 专项。
+
+缺口：
+
+- 两端都需要记录页面 zoom 没有变化。
+- 两端都需要记录 native selection 没有泄漏。
+- 两端都需要记录快速 release 后 pin 位置稳定。
+- 两端都需要记录 pointercancel/lostpointercapture 后不留下 stuck state。
+
+## 必须新增或扩展的测试
+
+| 测试文件 | 类型 | 覆盖内容 | 目标阶段 |
+|---|---|---|---|
+| `packages/graph-engine/test/spatial-index.test.ts` | Node unit | node/edge/community/blank hit；overlap priority；out-of-old-world hit；DOM order independent fixtures | Phase 1 |
+| `packages/graph-engine/test/gestures.test.ts` | Node unit | graph-owned `ctrl/meta + wheel` policy；touch-like pointer sequence；keyboard focus blocker contract | Phase 2 |
+| `tests/browser/graph-workbench-interactions.mjs` | Browser | graph-owned wheel does not zoom page；native selection stays empty；fast release pin persists；pointercancel cleanup | Phase 2 |
+| `tests/browser/graph-offline-phase-6.mjs` | Browser | same as workbench for offline HTML | Phase 2 / Phase 7 |
+| `packages/graph-engine/test/runtime-state.test.ts` | Node unit | data refresh while dragging keeps final release position | Phase 3 |
+| `packages/graph-engine/test/viewport.test.ts` | Node unit | layout-driven world bounds; minimap and fit under expanded bounds | Phase 3 |
+| `packages/graph-engine/test/overlays.test.ts` | Node unit | hover anchor after viewport resize, zoom, pan, and dragged node update | Phase 3 |
+| `packages/graph-engine/test/facade.test.ts` | Node unit | facade is the only host callback owner; workbench/offline capability contract remains compatible | Phase 4 |
+| `packages/graph-engine/test/renderer-boundary.test.ts` | Node unit / static check | renderer modules do not bind root graph events or perform graph hit testing | Phase 5 / Phase 7 |
+| `tests/browser/graph-community-wash-interactions.mjs` | Browser | SpatialIndex node > community > blank priority; wash cap under expanded bounds | Phase 6 |
+
+## Phase Gate Mapping
+
+Phase 1 can pass only when:
+
+- SpatialIndex exists as a real hit-testing source.
+- `spatial-index.test.ts` covers nodes, edges, communities, blank, overlap priority, old-world outliers.
+
+Phase 2 can pass only when:
+
+- Node tests cover graph-owned wheel/pointer/key policy.
+- Workbench and offline browser tests prove graph-owned wheel does not change page zoom.
+- Workbench and offline browser tests prove native selection does not leak during graph gestures.
+- Fast release drag persists the final position.
+
+Phase 3 can pass only when:
+
+- GraphViewport owns all coordinate conversion under drag, hover, resize, minimap, fit.
+- Layout-driven bounds replace fixed world-size drag cage.
+- Data refresh while dragging cannot overwrite final user intent.
+
+Phase 4 can pass only when:
+
+- GraphFacade owns host coordination.
+- Workbench and offline use the same graph-engine capability contract.
+
+Phase 5 can pass only when:
+
+- Renderer modules draw from snapshots and do not decide interaction meaning.
+- `static-renderer.ts` is reduced to compatibility/composition responsibilities.
+
+Phase 6 can pass only when:
+
+- Community wash remains soft, capped, and non-blocking.
+- SpatialIndex priority drives node/community/blank behavior.
+
+Phase 7 can pass only when:
+
+- Full command set passes.
+- Browser artifacts exist for workbench, narrow, and offline paths.
+- Static cleanup checks show old renderer-owned interaction paths are gone.

package/skills/llm-wiki-skill/docs/graph/performance/2026-06-18-phase-0-2-baseline.md

@@ -0,0 +1,86 @@
+# Phase 0.2 Existing Graph Baseline
+
+Date: 2026-06-18
+Branch: `codex/large-graph-performance-experience`
+Task: `0.2`
+
+## Scope
+
+This report captures the current graph behavior and performance baseline before changing graph behavior for the large-graph performance plan.
+
+## Verification
+
+| Check | Result | Evidence |
+|---|---:|---|
+| Graph engine test | Pass | `npm run test --workspace=@llm-wiki/graph-engine`: 274 tests, 58 suites, 0 failures |
+| Graph engine typecheck | Pass | `npm run typecheck --workspace=@llm-wiki/graph-engine` |
+| Graph engine build | Pass | `npm run build --workspace=@llm-wiki/graph-engine` |
+| Workbench web test | Pass | `npm run test --workspace=@llm-wiki-agent/web`: 29 tests, 12 suites, 0 failures |
+| Workbench web typecheck | Pass | `npm run typecheck --workspace=@llm-wiki-agent/web` |
+| Stage 4.5 offline browser regression | Pass | `GRAPH_STAGE_4_5_CHROME_EXECUTABLE=<Playwright Chromium> bash tests/graph-browser-stage-4-5.regression-1.sh --target offline` |
+
+## Browser Artifact
+
+Dense wheel artifact:
+
+- JSON: `docs/graph/performance/artifacts/2026-06-18-phase-0-2/stage-4.5-offline-dense-wheel.json`
+- Screenshot: `docs/graph/performance/artifacts/2026-06-18-phase-0-2/stage-4.5-offline-dense-wheel.png`
+- Navigation screenshot: `docs/graph/performance/artifacts/2026-06-18-phase-0-2/stage-4.5-offline-navigation.png`
+
+Recorded sample:
+
+| Viewport | Duration | Frames | Idle FPS | Wheel FPS | Minimum FPS | Transform changed |
+|---|---:|---:|---:|---:|---:|---|
+| 1440x960 | 3004 ms | 157 | 13.6 | 52.3 | 12.0 | true |
+
+Important limitation: the current dense fixture has 200 nodes and 231 edges. This is useful as a regression baseline, but it does not prove 1000, 5000, or 10000 node smoothness.
+
+## Current Rendering Behavior
+
+- The current graph renderer is DOM/SVG.
+- Nodes are DOM `button` elements in a node layer.
+- Edges are SVG `path` elements in an edge layer.
+- Community washes are SVG ellipses.
+- Pan and zoom are applied through one content-layer transform.
+- Motion frames update node positions, edge paths, community wash geometry, and minimap points.
+- Search, type filters, community hover, node selection, reader state, and selection panels are all currently coupled to the same DOM/SVG renderer path.
+
+## Current Interaction Semantics
+
+The current behavior remains the pre-new-design behavior:
+
+- Plain node click opens the reader-style node detail state.
+- Shift-click builds a multi-node selection.
+- Community legend click selects/focuses community nodes.
+- Blank double-click fits the graph.
+- Escape closes reader/selection state and clears graph highlights.
+- Offline graph uses an in-graph reader panel; workbench graph opens the right drawer.
+
+This is intentionally recorded as baseline behavior, not as the desired final interaction model.
+
+## Baseline Bottleneck Class
+
+The obvious large-graph risk is DOM/SVG update volume.
+
+Reasons:
+
+- Every visible node is a live DOM element.
+- Every visible edge is a live SVG path.
+- Rebuild/paint replaces the graph root and remounts controls.
+- Motion frames recompute renderable graph state and update many DOM/SVG attributes.
+- Hover, search, filter, community emphasis, and selection use DOM state/class updates across visible graph elements.
+
+For small and medium scoped views, this is still appropriate. For 5000+ or 10000+ global views, the likely bottleneck is not one single function; it is the total cost of DOM node count, SVG path count, repeated attribute/class writes, and full repaint/remount paths.
+
+## Test Harness Note
+
+The first run of `tests/graph-browser-stage-4-5.regression-1.sh --target offline` exposed two harness issues:
+
+- Playwright's normal click waited indefinitely for the offline theme button to become stable even though the button was visible, stationary, and not covered.
+- The script's default system Chrome path failed in this environment during launch/cleanup. Installing Playwright Chromium and setting `GRAPH_STAGE_4_5_CHROME_EXECUTABLE` to the Playwright browser path produced a passing run.
+
+The theme-button step was adjusted in the test harness to use forced click for this specific control. Product behavior was not changed.
+
+## Next Baseline Gap
+
+Phase 1 must add deterministic 1000, 5000, 10000, oversized-community, many-small-communities, many-search-hits, and many-Pin fixtures. Until those measurements exist, this report should be treated as the current small/dense-fixture baseline only.

package/skills/llm-wiki-skill/docs/graph/performance/2026-06-18-phase-1-3-dom-svg-large-baseline.md

@@ -0,0 +1,85 @@
+# Phase 1.3 DOM/SVG Large Graph Baseline
+
+Date: 2026-06-18
+Branch: `codex/large-graph-performance-experience`
+Task: `1.3`
+Renderer: current DOM/SVG
+
+## Scope
+
+This report summarizes the current DOM/SVG renderer against the generated large-graph performance fixtures. It does not choose the final renderer route. It turns the raw runner output into provisional thresholds for the next phases.
+
+## Commands
+
+- `git log --oneline -15`
+- `npm run test --workspace=@llm-wiki/graph-engine`
+- `GRAPH_LARGE_PERF_ARTIFACT_DIR=/tmp/llm-wiki-graph-large-perf-task-1-3 bash tests/graph-browser-large-performance.regression-1.sh`
+
+## Artifact
+
+Machine-readable result:
+
+- `/tmp/llm-wiki-graph-large-perf-task-1-3/large-graph-performance-results.json`
+
+The artifact contains 47 fixed-schema records across 5 graph shapes.
+
+## Result Table
+
+| Shape | Nodes | Edges | DOM nodes | Initial | Wheel | Pan | Hover | Search | Click | Drawer | Community | Return | Cycle |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| nodes-1000-sparse | 1000 | 1400 | 7249 | pass (900.4 ms) | pass (1016.8 ms, 60 FPS) | pass (130.5 ms) | pass (65.1 ms) | pass (189.2 ms) | pass (452.8 ms) | pass (857.1 ms) | pass (3122.9 ms) | pass (1389.1 ms) |
+| nodes-1000-dense | 1000 | 12000 | 7249 | pass (1008.4 ms) | pass (1007.2 ms, 59.6 FPS) | pass (129.2 ms) | pass (57.2 ms) | pass (205.2 ms) | pass (519.8 ms) | pass (867.9 ms) | pass (3279.1 ms) | pass (1432 ms) |
+| nodes-5000-sparse | 5000 | 6500 | 27399 | pass (4615.6 ms) | pass (1013.5 ms, 51.3 FPS) | pass (142.5 ms) | pass (145 ms) | pass (942.2 ms) | pass (2488.8 ms) | pass (5229.1 ms) | pass (4022.2 ms) | not run |
+| nodes-10000-aggregation | 10000 | 14000 | 52649 | pass (8836 ms) | pass (1004.9 ms, 36.8 FPS) | fail:timeout (-) | pass (3784.6 ms) | fail:timeout (-) | pass (4390.7 ms) | pass (13895.1 ms) | pass (4387 ms) | not run |
+| oversized-community | 3000 | 7000 | 17224 | pass (15788.6 ms) | pass (1005 ms, 12.9 FPS) | pass (247 ms) | pass (131.5 ms) | pass (3342.5 ms) | pass (8498.3 ms) | pass (27055.3 ms) | pass (9611.6 ms) | not run |
+
+
+## Recorded Failures
+
+- nodes-10000-aggregation / pan: timeout
+- nodes-10000-aggregation / node_click: timeout
+
+## Bottleneck Class
+
+The primary bottleneck class is DOM/SVG update volume. The evidence is structural and measured:
+
+- 1000-node global view creates about 7,249 DOM nodes and remains mostly responsive.
+- 5000-node global view creates about 27,399 DOM nodes; it still completes the key actions, but initial render and community entry move into multi-second territory.
+- 10000-node global view creates about 52,649 DOM nodes. In this run, pan and node click timed out, while drawer open and community entry were already multi-second actions in the prior 1.2 run.
+- Oversized community keeps 3000 nodes present and creates about 17,224 DOM nodes; community entry exposes 1800 nodes, which is too large for a card-heavy reading surface.
+
+Secondary bottlenecks are interaction-state churn and community focus expansion. Search itself is still comparatively cheap, but click-to-reader, drawer open, enter-community, and return-global become slow because they update many DOM/SVG elements and remount or restyle large visible sets.
+
+## Provisional Thresholds
+
+These thresholds are intentionally provisional. They are gates for Phase 4/6 comparison, not final product promises.
+
+| Metric | Provisional pass threshold | Notes |
+|---|---:|---|
+| Initial render, 1000 nodes | <= 1500 ms | Current 1000 sparse/dense passed. |
+| Initial render, 5000 nodes | <= 5000 ms | Current 5000 sparse passed but is close enough to watch. |
+| Initial render, 10000 nodes | <= 8000 ms | Current 10000 exceeded this; global path needs degradation or another renderer. |
+| Wheel zoom | >= 30 FPS and p95 <= 35 ms | 1000 and 5000 passed; low FPS is a failure class. |
+| Pan | <= 300 ms or explicit failure class | 10000 timed out in this run. |
+| Hover | <= 500 ms | All measured shapes passed here. |
+| Search highlight | <= 500 ms | Current search is not the first bottleneck. |
+| Node click | <= 800 ms for 1000, <= 1500 ms for 5000, <= 2000 ms for 10000 | 10000 timed out in this run. |
+| Drawer open | <= 1000 ms for 1000, <= 2500 ms for 5000, <= 3000 ms for 10000 | Prior 1.2 result showed 10000 drawer open can reach 7600 ms. |
+| Enter community | <= 1500 ms for normal community, <= 3000 ms for large/oversized community | 10000 and oversized community exceed the target. |
+| Return global | <= 3500 ms for 1000, <= 5000 ms for 5000, <= 5000 ms for 10000 | Current 1000 is already near the limit. |
+| Repeated cycle memory growth | <= 10 MB for 1000-node cycle | Current 1000 cycle showed no growth in available memory field. |
+
+## Interpretation
+
+The current renderer is acceptable for small graph and community reading, but it is not a proven 10000+ global renderer. The next implementation phases should keep DOM/SVG for community/detail views while treating 5000/10000 global browsing as requiring budget enforcement, aggregation, or a different global rendering route.
+
+## Phase 4.1 Render Budgets
+
+These budgets are the first shared graph-layer caps derived from the DOM/SVG bottleneck class above. They are not the final large-graph renderer decision; they prevent the current renderer from producing card-heavy or edge-heavy global output while Phase 6 evaluates the global route.
+
+| View | Max visible nodes | Max visible edges | Max labels | Max full cards | Max interaction-time updates |
+|---|---:|---:|---:|---:|---:|
+| Global | 10000 | 1000 | 40 | 0 | 1200 |
+| Community focus | 2500 | 1500 | 120 | 60 | 1800 |
+
+Overflow is reported by the shared render model for nodes, edges, labels, cards, and interaction updates so drawer/list states can expose omitted detail without forcing it onto the canvas. Selection, search results, and Pin hints may promote priority, but they do not raise these caps.