@joekytc/dsh-swarm 0.1.2 → 0.2.0

package/skills/llm-wiki-skill/packages/graph-engine/test/route-continuity.test.ts

@@ -0,0 +1,284 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import type {
+  GraphData,
+  GraphTypeFilters,
+  PinMap,
+  SelectionInput,
+  ThemeId
+} from "../src";
+import {
+  createGraphFacadeFromRenderer,
+  createGraphFacadeRouteManager,
+  type GraphFacadeRenderer,
+  type GraphFacadeRouteRendererFactoryInput,
+  type GraphFacadeState
+} from "../src/facade";
+
+const DATA: GraphData = {
+  meta: {
+    build_date: "2026-06-16",
+    wiki_title: "Route continuity test graph",
+    total_nodes: 2,
+    total_edges: 1
+  },
+  nodes: [
+    {
+      id: "a",
+      label: "Alpha",
+      type: "topic",
+      community: "c1",
+      source_path: "wiki/a.md",
+      content: "Alpha content"
+    },
+    {
+      id: "b",
+      label: "Beta",
+      type: "source",
+      community: "c1",
+      source_path: "wiki/b.md",
+      content: "Beta content"
+    }
+  ],
+  edges: [
+    {
+      id: "a->b",
+      from: "a",
+      to: "b",
+      type: "EXTRACTED",
+      confidence: "EXTRACTED",
+      relation_type: "实现",
+      weight: 1
+    }
+  ]
+};
+
+describe("graph route state continuity", () => {
+  it("preserves selected, searched, pinned, and community state across a data refresh when objects still exist", () => {
+    const container = { dataset: {} as Record<string, string | undefined> };
+    const state: GraphFacadeState = {
+      data: DATA,
+      pins: { "wiki/a.md": { x: 10, y: 20, coordinateSpace: "world" } },
+      theme: "shan-shui",
+      focus: null,
+      typeFilters: { topic: true, source: false },
+      aggregationMarkers: [],
+      selection: null,
+      searchQuery: "",
+      searchResultIds: [],
+      temporaryObject: null
+    };
+    const sigmaInputs: GraphFacadeRouteRendererFactoryInput[] = [];
+    const communityInputs: GraphFacadeRouteRendererFactoryInput[] = [];
+    const communityRenderers: Array<GraphFacadeRenderer & { calls: unknown[][] }> = [];
+    const manager = createGraphFacadeRouteManager(container as unknown as HTMLElement, {
+      state,
+      factories: {
+        createSigmaGlobal: (input) => {
+          sigmaInputs.push(input);
+          return createFakeRenderer();
+        },
+        createDomSvgCommunity: (input) => {
+          communityInputs.push(input);
+          return trackRenderer(communityRenderers, "dom-community");
+        },
+        createDomSvgSmallFallback: () => createFakeRenderer(),
+        createOverLimitNotice: () => createFakeRenderer()
+      }
+    });
+
+    sigmaInputs[0].options.callbacks.onVisibilityStateChange?.({
+      searchQuery: "Alpha",
+      searchResultIds: ["a"],
+      typeFilters: { topic: true, source: false },
+      temporaryObject: { kind: "node", nodeId: "b" }
+    });
+    manager.select({ kind: "node", id: "a" });
+    manager.focusCommunity("c1");
+
+    const refreshedData: GraphData = {
+      ...DATA,
+      meta: { ...DATA.meta, wiki_title: "Refreshed graph" },
+      nodes: DATA.nodes.map((node) => node.id === "a" ? { ...node, label: "Alpha refreshed" } : node)
+    };
+    manager.setData(refreshedData);
+
+    assert.equal(manager.routeId, "dom-svg-community");
+    assert.equal(state.data, refreshedData);
+    assert.deepEqual(state.focus, { kind: "community", id: "c1" });
+    assert.deepEqual(state.selection, { kind: "node", id: "a" });
+    assert.equal(state.searchQuery, "Alpha");
+    assert.deepEqual(state.searchResultIds, ["a"]);
+    assert.deepEqual(state.typeFilters, { topic: true, source: false });
+    assert.deepEqual(state.temporaryObject, { kind: "node", nodeId: "b" });
+    assert.deepEqual(state.pins, { "wiki/a.md": { x: 10, y: 20, coordinateSpace: "world" } });
+    assert.deepEqual(communityInputs[0].options.selection, { kind: "node", id: "a" });
+    assert.deepEqual(communityInputs[0].options.searchResultIds, ["a"]);
+    assert.deepEqual(communityRenderers[0].calls.at(-1), ["setData", refreshedData, undefined]);
+  });
+
+  it("makes a disappeared selected object explicitly unavailable after data refresh", () => {
+    const container = { dataset: {} as Record<string, string | undefined> };
+    const renderer = createFakeRenderer();
+    const engine = createGraphFacadeFromRenderer(container, renderer, {
+      data: DATA,
+      theme: "shan-shui",
+      pins: { "wiki/a.md": { x: 10, y: 20, coordinateSpace: "world" } }
+    });
+
+    engine.select({ kind: "node", id: "a" });
+    const refreshedData: GraphData = {
+      ...DATA,
+      nodes: DATA.nodes.filter((node) => node.id !== "a"),
+      edges: []
+    };
+    engine.setData(refreshedData);
+    const unavailable = engine.summarizeUnavailableObject({ kind: "node", nodeId: "a" }, "missing-node");
+
+    assert.equal(unavailable.kind, "unavailable-object");
+    assert.equal(unavailable.reason, "missing-node");
+    assert.deepEqual(unavailable.object, { kind: "node", nodeId: "a" });
+    assert.deepEqual(unavailable.selection.input, { kind: "node", id: "a" });
+    assert.deepEqual(unavailable.selection.selectedNodeIds, []);
+    assert.equal(unavailable.selection.containsCurrentObject, false);
+    assert.deepEqual(unavailable.pinHints, []);
+  });
+
+  it("passes shared interaction state into DOM/SVG small fallback and keeps return-global rules consistent", () => {
+    const container = { dataset: {} as Record<string, string | undefined> };
+    const state: GraphFacadeState = {
+      data: DATA,
+      pins: { "wiki/a.md": { x: 10, y: 20, coordinateSpace: "world" } },
+      theme: "shan-shui",
+      focus: null,
+      typeFilters: { topic: true, source: true },
+      aggregationMarkers: [],
+      selection: { kind: "node", id: "a" },
+      searchQuery: "Alpha",
+      searchResultIds: ["a"],
+      temporaryObject: null
+    };
+    const fallbackInputs: GraphFacadeRouteRendererFactoryInput[] = [];
+    const communityInputs: GraphFacadeRouteRendererFactoryInput[] = [];
+    const fallbackRenderers: Array<GraphFacadeRenderer & { calls: unknown[][] }> = [];
+    const manager = createGraphFacadeRouteManager(container as unknown as HTMLElement, {
+      state,
+      factories: {
+        createSigmaGlobal: () => {
+          throw new Error("WebGL unavailable");
+        },
+        createDomSvgCommunity: (input) => {
+          communityInputs.push(input);
+          return createFakeRenderer();
+        },
+        createDomSvgSmallFallback: (input) => {
+          fallbackInputs.push(input);
+          return trackRenderer(fallbackRenderers, "small-fallback");
+        },
+        createOverLimitNotice: () => createFakeRenderer()
+      }
+    });
+
+    assert.equal(manager.routeId, "dom-svg-small-fallback");
+    assert.deepEqual(fallbackInputs[0].options.selection, { kind: "node", id: "a" });
+    assert.equal(fallbackInputs[0].options.searchQuery, "Alpha");
+    assert.deepEqual(fallbackInputs[0].options.searchResultIds, ["a"]);
+    assert.deepEqual(Object.keys(fallbackInputs[0].options.pins), ["wiki/a.md"]);
+
+    fallbackInputs[0].options.callbacks.onSelectionInput?.({ kind: "community", id: "c1" });
+    assert.deepEqual(state.selection, { kind: "community", id: "c1" });
+    assert.equal(manager.routeId, "dom-svg-small-fallback");
+
+    manager.focusCommunity("c1");
+    assert.equal(manager.routeId, "dom-svg-community");
+    assert.deepEqual(communityInputs[0].options.selection, { kind: "community", id: "c1" });
+
+    communityInputs[0].options.callbacks.onGlobalResetRequested?.();
+
+    assert.equal(manager.routeId, "dom-svg-small-fallback");
+    assert.equal(manager.sigmaKnownUnavailable, true);
+    assert.equal(state.selection, null);
+    assert.deepEqual(fallbackInputs.at(-1)?.options.selection, null);
+    assert.equal(fallbackInputs.at(-1)?.options.searchQuery, "Alpha");
+    assert.deepEqual(fallbackInputs.at(-1)?.options.searchResultIds, ["a"]);
+    assert.deepEqual(Object.keys(fallbackInputs.at(-1)?.options.pins || {}), ["wiki/a.md"]);
+    assert.deepEqual(fallbackRenderers.at(-1)?.calls.filter((call) => call[0] === "resetView"), [["resetView"]]);
+  });
+});
+
+function createFakeRenderer(): GraphFacadeRenderer & { calls: unknown[][] } {
+  const calls: unknown[][] = [];
+  return {
+    calls,
+    async applyDiff(diff, options) {
+      calls.push(["applyDiff", diff, options]);
+    },
+    isDragging() {
+      calls.push(["isDragging"]);
+      return false;
+    },
+    setData(data: GraphData, pins?: PinMap) {
+      calls.push(["setData", data, pins]);
+    },
+    setAggregationMarkers(markers) {
+      calls.push(["setAggregationMarkers", markers]);
+    },
+    focusNode(path: string) {
+      calls.push(["focusNode", path]);
+    },
+    focusCommunity(id: string) {
+      calls.push(["focusCommunity", id]);
+    },
+    previewNode(id: string | null) {
+      calls.push(["previewNode", id]);
+    },
+    setTypeFilters(filters: GraphTypeFilters) {
+      calls.push(["setTypeFilters", filters]);
+    },
+    showTemporaryObject(object) {
+      calls.push(["showTemporaryObject", object]);
+    },
+    clearTemporaryObjectDisplay() {
+      calls.push(["clearTemporaryObjectDisplay"]);
+    },
+    resetView() {
+      calls.push(["resetView"]);
+    },
+    select(selection: SelectionInput) {
+      calls.push(["select", selection]);
+    },
+    clearSelection() {
+      calls.push(["clearSelection"]);
+    },
+    clearInteraction() {
+      calls.push(["clearInteraction"]);
+    },
+    setNodeFixed(id: string, mode: "fix" | "unfix") {
+      calls.push(["setNodeFixed", id, mode]);
+      return true;
+    },
+    setTheme(theme: ThemeId) {
+      calls.push(["setTheme", theme]);
+    },
+    setPins(pins: PinMap) {
+      calls.push(["setPins", pins]);
+    },
+    resetLayout() {
+      calls.push(["resetLayout"]);
+    },
+    destroy() {
+      calls.push(["destroy"]);
+    }
+  };
+}
+
+function trackRenderer(
+  renderers: Array<GraphFacadeRenderer & { calls: unknown[][] }>,
+  route: string
+): GraphFacadeRenderer & { calls: unknown[][] } {
+  const renderer = createFakeRenderer();
+  renderer.calls.push(["create", route]);
+  renderers.push(renderer);
+  return renderer;
+}

package/skills/llm-wiki-skill/packages/graph-engine/test/runtime-state.test.ts

@@ -0,0 +1,281 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import {
+  resolveVisibleSnapshot,
+  buildAtlasModel,
+  deriveAtlasLayout,
+  resolveAtlasVisibleSnapshot,
+  resolveAtlasSelectedNodeId,
+  getAtlasDensityMode,
+  atlasNodePoint,
+  getAtlasModelBounds,
+  fitAtlasViewport,
+  centerAtlasViewportOnPoint,
+  zoomAtlasViewport,
+  atlasViewportRect,
+  atlasPointToMinimap,
+  minimapPointToAtlasPoint,
+  atlasViewportToMinimapRect
+} from "../src/model";
+
+describe("resolveVisibleSnapshot", () => {
+  const nodes = [
+    { id: "n1", label: "机器学习基础", content: "监督学习与数据预处理", degree: 2 },
+    { id: "n2", label: "深度学习", content: "神经网络与 Transformer", degree: 3 },
+    { id: "n3", label: "Transformer", content: "语言模型核心架构", degree: 2 },
+    { id: "n4", label: "数据清洗", content: "数据预处理的一部分", degree: 1 }
+  ];
+
+  const links = [
+    { id: "e1", source: "n1", target: "n2", type: "EXTRACTED", weight: 0.95 },
+    { id: "e2", source: "n2", target: "n3", type: "EXTRACTED", weight: 0.91 },
+    { id: "e3", source: "n1", target: "n4", type: "INFERRED", weight: 0.55 }
+  ];
+
+  it("combines edge filtering, focus mode, and search query", () => {
+    const snapshot = resolveVisibleSnapshot({
+      nodes,
+      links,
+      baseNodeIds: ["n1", "n2", "n3", "n4"],
+      filters: { EXTRACTED: true, INFERRED: false, AMBIGUOUS: false },
+      focusMode: "high_confidence",
+      searchQuery: "transformer",
+      anchorNodeId: "n2",
+      highConfidenceThreshold: 0.9
+    });
+
+    assert.deepEqual(snapshot.node_ids, ["n2", "n3"]);
+    assert.deepEqual(snapshot.nodes.map((node) => node.id), ["n2", "n3"]);
+    assert.deepEqual(snapshot.links.map((link) => link.id), ["e2"]);
+    assert.deepEqual(snapshot.searchIndex.map((entry) => entry.node.id), ["n1", "n2", "n3"]);
+  });
+
+  it("keeps one-hop scope around the selected anchor", () => {
+    const snapshot = resolveVisibleSnapshot({
+      nodes,
+      links,
+      baseNodeIds: ["n1", "n2", "n3"],
+      filters: { EXTRACTED: true, INFERRED: true, AMBIGUOUS: false },
+      focusMode: "one_hop",
+      searchQuery: "",
+      anchorNodeId: "n2"
+    });
+
+    assert.deepEqual(snapshot.node_ids, ["n1", "n2", "n3"]);
+    assert.deepEqual(snapshot.links.map((link) => link.id), ["e1", "e2"]);
+  });
+
+  it("returns empty visible nodes when search has no matches", () => {
+    const snapshot = resolveVisibleSnapshot({
+      nodes,
+      links,
+      baseNodeIds: ["n1", "n2", "n3"],
+      filters: { EXTRACTED: true, INFERRED: true, AMBIGUOUS: false },
+      focusMode: "all",
+      searchQuery: "不存在",
+      anchorNodeId: "n2"
+    });
+
+    assert.deepEqual(snapshot.node_ids, []);
+    assert.deepEqual(snapshot.nodes, []);
+    assert.deepEqual(snapshot.links, []);
+    assert.equal(snapshot.searchIndex.length, 3);
+  });
+
+  it("keeps an explicitly empty current range empty", () => {
+    const snapshot = resolveVisibleSnapshot({
+      nodes,
+      links,
+      baseNodeIds: [],
+      filters: { EXTRACTED: true, INFERRED: true, AMBIGUOUS: false },
+      focusMode: "all",
+      searchQuery: "机器"
+    });
+
+    assert.deepEqual(snapshot.node_ids, []);
+    assert.deepEqual(snapshot.nodes, []);
+    assert.deepEqual(snapshot.links, []);
+    assert.deepEqual(snapshot.searchIndex, []);
+  });
+});
+
+describe("atlas state contract", () => {
+  const rawGraph = {
+    meta: { wiki_title: "测试知识库", build_date: "2026-04-27" },
+    nodes: [
+      { id: "a", label: "知识编译", type: "topic", community: "method", confidence: "EXTRACTED", content: "# 知识编译\n\n整理一次，持续维护。" },
+      { id: "b", label: "素材消化", type: "topic", community: "method", confidence: "INFERRED", source_path: "wiki/topics/b.md" },
+      { id: "c", label: "网页文章", type: "source", community: "source", confidence: "AMBIGUOUS" }
+    ],
+    edges: [
+      { id: "ab", from: "a", to: "b", type: "EXTRACTED", weight: 0.9 },
+      { id: "ac", from: "a", to: "c", type: "INFERRED", weight: 0.6 }
+    ],
+    learning: {
+      entry: { recommended_start_node_id: "a" },
+      communities: [
+        { id: "method", label: "方法论", node_count: 2, is_primary: true, recommended_start_node_id: "a" },
+        { id: "source", label: "素材来源", node_count: 1, recommended_start_node_id: "c" }
+      ]
+    }
+  };
+
+  it("normalizes raw graph into one atlas model", () => {
+    const model = buildAtlasModel(rawGraph);
+
+    assert.equal(model.meta.wiki_title, "测试知识库");
+    assert.equal(model.nodes.length, 3);
+    assert.equal(model.edges.length, 2);
+    assert.equal(model.byId.a.degree, 2);
+    assert.equal(model.byId.a.summary, "整理一次，持续维护。");
+    assert.deepEqual(model.communities.map((community) => community.label), ["方法论", "素材来源"]);
+    assert.equal(model.starts[0].node.id, "a");
+  });
+
+  it("treats null atlas coordinates as missing layout input", () => {
+    const model = buildAtlasModel({
+      nodes: [
+        { id: "nullish", label: "Nullish", x: null, y: null },
+        { id: "origin", label: "Origin", x: 0, y: 0 }
+      ],
+      edges: []
+    });
+    deriveAtlasLayout(model);
+
+    assert.notDeepEqual(
+      { x: model.byId.nullish.x, y: model.byId.nullish.y },
+      { x: 5, y: 8 }
+    );
+    assert.deepEqual(
+      { x: model.byId.origin.x, y: model.byId.origin.y },
+      { x: 5, y: 8 }
+    );
+  });
+
+  it("uses one visible snapshot for filters, search, density, and starts", () => {
+    const model = buildAtlasModel(rawGraph);
+    const layout = deriveAtlasLayout(model);
+    const snapshot = resolveAtlasVisibleSnapshot(model, layout, {
+      activeCommunityId: "method",
+      focusMode: "all",
+      query: "素材",
+      selectedNodeId: "a",
+      filters: { EXTRACTED: true, INFERRED: true }
+    });
+
+    assert.deepEqual(snapshot.node_ids, ["b"]);
+    assert.deepEqual(snapshot.nodes.map((node) => node.id), ["b"]);
+    assert.deepEqual(snapshot.edges, []);
+    assert.equal(snapshot.densityMode, "card");
+    assert.equal(snapshot.starts[0].node.id, "b");
+    assert.equal(snapshot.importantNodeIds.b, true);
+    assert.equal(snapshot.counts.total_nodes, 3);
+  });
+
+  it("keeps recommended starts and high-priority nodes readable as atlas index slips", () => {
+    const model = buildAtlasModel(rawGraph);
+    const layout = deriveAtlasLayout(model);
+    const snapshot = resolveAtlasVisibleSnapshot(model, layout, {
+      activeCommunityId: "all",
+      focusMode: "all",
+      query: "",
+      selectedNodeId: null,
+      filters: { EXTRACTED: true, INFERRED: true, AMBIGUOUS: true, UNVERIFIED: true }
+    });
+
+    assert.equal(snapshot.starts[0].node.id, "a");
+    assert.equal(snapshot.startNodeIds.a, true);
+    assert.equal(snapshot.importantNodeIds.a, true);
+    assert.equal(snapshot.labelNodeIds.a, true);
+  });
+
+  it("preserves only explicit selections inside the current visible atlas range", () => {
+    const model = buildAtlasModel(rawGraph);
+    const layout = deriveAtlasLayout(model);
+    const methodSnapshot = resolveAtlasVisibleSnapshot(model, layout, {
+      activeCommunityId: "source",
+      focusMode: "all",
+      query: "",
+      selectedNodeId: "a",
+      filters: { EXTRACTED: true, INFERRED: true, AMBIGUOUS: true, UNVERIFIED: true }
+    });
+    const emptySnapshot = resolveAtlasVisibleSnapshot(model, layout, {
+      activeCommunityId: "source",
+      focusMode: "all",
+      query: "没有结果",
+      selectedNodeId: "c",
+      filters: { EXTRACTED: true, INFERRED: true, AMBIGUOUS: true, UNVERIFIED: true }
+    });
+
+    assert.equal(resolveAtlasSelectedNodeId(model, methodSnapshot, "a"), null);
+    assert.equal(resolveAtlasSelectedNodeId(model, methodSnapshot, "c"), "c");
+    assert.equal(resolveAtlasSelectedNodeId(model, emptySnapshot, "c"), null);
+  });
+
+  it("does not auto-select a recommended start on first open", () => {
+    const model = buildAtlasModel(rawGraph);
+    const layout = deriveAtlasLayout(model);
+    const snapshot = resolveAtlasVisibleSnapshot(model, layout, {
+      activeCommunityId: "all",
+      focusMode: "all",
+      query: "",
+      selectedNodeId: null,
+      filters: { EXTRACTED: true, INFERRED: true, AMBIGUOUS: true, UNVERIFIED: true }
+    });
+
+    assert.equal(snapshot.starts[0].node.id, "a");
+    assert.equal(resolveAtlasSelectedNodeId(model, snapshot, null), null);
+  });
+
+  it("selects density mode by visible node budget", () => {
+    assert.equal(getAtlasDensityMode(50), "card");
+    assert.equal(getAtlasDensityMode(120), "compact-card");
+    assert.equal(getAtlasDensityMode(300), "point-plus-focus");
+    assert.equal(getAtlasDensityMode(800), "overview");
+  });
+
+  it("derives one model coordinate space for nodes and bounds", () => {
+    const model = buildAtlasModel(rawGraph);
+    deriveAtlasLayout(model);
+    const point = atlasNodePoint(model.byId.a);
+    const bounds = getAtlasModelBounds(model.nodes, 0);
+
+    assert.equal(point.x, model.byId.a.x * 10);
+    assert.equal(point.y, model.byId.a.y * 6.8);
+    assert.ok(bounds.width > 0);
+    assert.ok(bounds.height > 0);
+    assert.ok(bounds.minX <= point.x && point.x <= bounds.maxX);
+    assert.ok(bounds.minY <= point.y && point.y <= bounds.maxY);
+  });
+
+  it("fits, zooms, and reports the current viewport rectangle", () => {
+    const viewportSize = { width: 1000, height: 680 };
+    const bounds = { minX: 250, minY: 180, maxX: 750, maxY: 500, width: 500, height: 320 };
+    const fitted = fitAtlasViewport(bounds, viewportSize, { padding: 0.8 });
+    const zoomed = zoomAtlasViewport(fitted, 1.5, { x: 500, y: 340 }, viewportSize);
+    const rect = atlasViewportRect(zoomed, viewportSize);
+
+    assert.ok(fitted.scale > 1);
+    assert.ok(zoomed.scale > fitted.scale);
+    assert.ok(rect.width < 1000);
+    assert.ok(rect.height < 680);
+    assert.ok(rect.minX >= 0 && rect.maxX <= 1000);
+    assert.ok(rect.minY >= 0 && rect.maxY <= 680);
+  });
+
+  it("centers viewport on model points and maps minimap clicks back to atlas coordinates", () => {
+    const viewportSize = { width: 800, height: 500 };
+    const point = { x: 250, y: 170 };
+    const centered = centerAtlasViewportOnPoint(point, viewportSize, 1.4);
+    const rect = atlasViewportRect(centered, viewportSize);
+    const miniPoint = atlasPointToMinimap(point);
+    const restored = minimapPointToAtlasPoint(miniPoint);
+    const miniRect = atlasViewportToMinimapRect(centered, viewportSize);
+
+    assert.ok(rect.minX <= point.x && point.x <= rect.maxX);
+    assert.ok(rect.minY <= point.y && point.y <= rect.maxY);
+    assert.deepEqual(restored, point);
+    assert.ok(miniRect.width > 0);
+    assert.ok(miniRect.height > 0);
+  });
+});

package/skills/llm-wiki-skill/packages/graph-engine/test/search-and-legend.test.ts

@@ -0,0 +1,124 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import {
+  buildCommunityLegend,
+  buildRenderableGraph,
+  resolveGraphSearchState,
+  resolveNextGraphSearchFocus,
+  resolvePreviousGraphSearchFocus
+} from "../src/render";
+import type { GraphNode } from "../src/types";
+
+describe("graph scoped search", () => {
+  it("matches nodes through the shared search helpers and marks non-matches faded", () => {
+    const nodes = searchNodes();
+    const state = resolveGraphSearchState(nodes, "attention");
+
+    assert.equal(state.query, "attention");
+    assert.deepEqual(state.matchIds, ["A"]);
+    assert.deepEqual(
+      state.nodes.map((node) => [node.id, node.searchState]),
+      [["A", "match"], ["B", "faded"], ["C", "faded"]]
+    );
+  });
+
+  it("treats an empty query as no matches and reuses a cached index", () => {
+    const nodes = searchNodes();
+    const first = resolveGraphSearchState(nodes, "source");
+    const second = resolveGraphSearchState(nodes, "", first.searchIndex);
+
+    assert.equal(second.searchIndex, first.searchIndex);
+    assert.deepEqual(second.matchIds, []);
+    assert.deepEqual(second.nodes.map((node) => node.searchState), ["none", "none", "none"]);
+  });
+
+  it("cycles focus through search matches and handles empty results", () => {
+    assert.deepEqual(resolveNextGraphSearchFocus(["A", "B", "C"], null), { id: "A", index: 0 });
+    assert.deepEqual(resolveNextGraphSearchFocus(["A", "B", "C"], "A"), { id: "B", index: 1 });
+    assert.deepEqual(resolveNextGraphSearchFocus(["A", "B", "C"], "C"), { id: "A", index: 0 });
+    assert.deepEqual(resolveNextGraphSearchFocus([], "A"), { id: null, index: -1 });
+  });
+
+  it("cycles search focus backward for keyboard result navigation", () => {
+    assert.deepEqual(resolvePreviousGraphSearchFocus(["A", "B", "C"], null), { id: "C", index: 2 });
+    assert.deepEqual(resolvePreviousGraphSearchFocus(["A", "B", "C"], "C"), { id: "B", index: 1 });
+    assert.deepEqual(resolvePreviousGraphSearchFocus(["A", "B", "C"], "A"), { id: "C", index: 2 });
+    assert.deepEqual(resolvePreviousGraphSearchFocus([], "A"), { id: null, index: -1 });
+  });
+});
+
+describe("community legend", () => {
+  it("builds visible legend rows with color, label, page count, and node ids", () => {
+    const rows = buildCommunityLegend([
+      {
+        id: "c1",
+        label: "核心主题",
+        color: "#c33",
+        nodeCount: 3,
+        wash: { cx: 100, cy: 120, rx: 60, ry: 40, opacity: 0.11 }
+      },
+      {
+        id: "empty",
+        label: "空社区",
+        color: "#999",
+        nodeCount: 0,
+        wash: null
+      },
+      {
+        id: "hidden",
+        label: "隐藏社区",
+        color: "#555",
+        nodeCount: 2,
+        wash: null
+      }
+    ], [
+      { id: "A", community: "c1" },
+      { id: "B", community: "c1" },
+      { id: "C", community: "c2" }
+    ]);
+
+    assert.deepEqual(rows, [{
+      id: "c1",
+      label: "核心主题",
+      color: "#c33",
+      pageCount: 3,
+      nodeIds: ["A", "B"]
+    }, {
+      id: "hidden",
+      label: "隐藏社区",
+      color: "#555",
+      pageCount: 2,
+      nodeIds: []
+    }]);
+  });
+
+  it("community selection highlights all nodes in that community", () => {
+    const graph = buildRenderableGraph({
+      meta: {
+        build_date: "2026-06-13T00:00:00.000Z",
+        wiki_title: "Legend",
+        total_nodes: 3,
+        total_edges: 1
+      },
+      nodes: [
+        { id: "A", label: "A", type: "entity", community: "c1" },
+        { id: "B", label: "B", type: "entity", community: "c1" },
+        { id: "C", label: "C", type: "entity", community: "c2" }
+      ],
+      edges: [{ id: "AB", from: "A", to: "B", type: "EXTRACTED" }]
+    }, { selection: { kind: "community", id: "c1" } });
+
+    assert.deepEqual(
+      graph.nodes.map((node) => [node.id, node.selected]),
+      [["A", true], ["B", true], ["C", false]]
+    );
+  });
+});
+
+function searchNodes(): GraphNode[] {
+  return [
+    { id: "A", label: "Attention", type: "topic", content: "Transformer attention notes." },
+    { id: "B", label: "Embeddings", type: "entity", content: "Vector source material." },
+    { id: "C", label: "Retrieval", type: "source", content: "Indexing and recall." }
+  ];
+}