@research-copilot/plugin 1.1.16 → 1.1.18

package/dist/skills/llm-wiki/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/dist/skills/llm-wiki/packages/graph-engine/test/search-and-legend.test.ts

@@ -0,0 +1,111 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { buildCommunityLegend, buildRenderableGraph, resolveGraphSearchState, resolveNextGraphSearchFocus } 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("restores all nodes for an empty query 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, ["A", "B", "C"]);
+    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 });
+  });
+});
+
+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." }
+  ];
+}

package/dist/skills/llm-wiki/packages/graph-engine/test/select.test.ts

@@ -0,0 +1,168 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import { resolveSelection, resolveSelectionForCapabilities } from "../src/select";
+import type { GraphData, SelectionActionId } from "../src/types";
+
+describe("structured graph selection", () => {
+  it("maps a linked single page to page actions", () => {
+    const selection = resolveSelection(multicommGraph(), { kind: "node", id: "a1" });
+
+    assert.deepEqual(selection.nodeIds, ["a1"]);
+    assert.deepEqual(selection.communityIds, ["alpha"]);
+    assert.deepEqual(selection.facts, {
+      pageCount: 1,
+      internalLinkCount: 0,
+      communityCount: 1,
+      isolatedCount: 0
+    });
+    assert.deepEqual(actionIds(selection), ["summarize_page", "find_related_pages", "quote_page"]);
+    assert.equal(actionIds(selection).includes("explore_potential_links"), false);
+  });
+
+  it("maps an isolated single page to page actions plus the link action", () => {
+    const selection = resolveSelection(multicommGraph(), { kind: "node", id: "island" });
+
+    assert.deepEqual(selection.nodeIds, ["island"]);
+    assert.deepEqual(selection.communityIds, ["solo"]);
+    assert.deepEqual(selection.facts, {
+      pageCount: 1,
+      internalLinkCount: 0,
+      communityCount: 1,
+      isolatedCount: 1
+    });
+    assert.deepEqual(actionIds(selection), ["summarize_page", "find_related_pages", "quote_page", "link_island"]);
+    assert.equal(actionIds(selection).includes("explore_potential_links"), false);
+  });
+
+  it("selects a community and offers single-community actions", () => {
+    const selection = resolveSelection(multicommGraph(), { kind: "community", id: "alpha" });
+
+    assert.deepEqual(selection.nodeIds, ["a1", "a2", "a3"]);
+    assert.deepEqual(selection.communityIds, ["alpha"]);
+    assert.deepEqual(selection.facts, {
+      pageCount: 3,
+      internalLinkCount: 2,
+      communityCount: 1,
+      isolatedCount: 0
+    });
+    assert.deepEqual(actionIds(selection), ["summarize_cluster", "find_knowledge_gaps", "create_topic_page"]);
+  });
+
+  it("selects one-hop neighbors and offers two-community bridge actions", () => {
+    const selection = resolveSelection(multicommGraph(), { kind: "neighbors", id: "bridge" });
+
+    assert.deepEqual(selection.nodeIds, ["a3", "bridge", "b1"]);
+    assert.deepEqual(selection.communityIds, ["alpha", "beta"]);
+    assert.deepEqual(selection.facts, {
+      pageCount: 3,
+      internalLinkCount: 2,
+      communityCount: 2,
+      isolatedCount: 0
+    });
+    assert.deepEqual(actionIds(selection), ["why_no_connection", "find_potential_bridges", "compare_communities"]);
+  });
+
+  it("selects shift-style manual nodes and avoids cluster summary for unlinked multi-select", () => {
+    const selection = resolveSelection(multicommGraph(), { kind: "nodes", ids: ["a1", "b2"] });
+
+    assert.deepEqual(selection.nodeIds, ["a1", "b2"]);
+    assert.deepEqual(selection.communityIds, ["alpha", "beta"]);
+    assert.deepEqual(selection.facts, {
+      pageCount: 2,
+      internalLinkCount: 0,
+      communityCount: 2,
+      isolatedCount: 0
+    });
+    assert.deepEqual(actionIds(selection), ["why_no_connection", "find_potential_bridges", "compare_communities"]);
+    assert.equal(actionIds(selection).includes("summarize_cluster"), false);
+  });
+
+  it("maps linked manual multi-select to group actions", () => {
+    const selection = resolveSelection(multicommGraph(), { kind: "nodes", ids: ["a1", "a2"] });
+
+    assert.deepEqual(selection.nodeIds, ["a1", "a2"]);
+    assert.deepEqual(selection.facts, {
+      pageCount: 2,
+      internalLinkCount: 1,
+      communityCount: 1,
+      isolatedCount: 0
+    });
+    assert.deepEqual(actionIds(selection), ["summarize_group", "explore_group_relationships"]);
+    assert.equal(actionIds(selection).includes("summarize_cluster"), false);
+  });
+
+  it("maps unlinked multi-community selections beyond two communities to exploration actions", () => {
+    const selection = resolveSelection(multicommGraph(), { kind: "nodes", ids: ["a1", "b2", "g1"] });
+
+    assert.deepEqual(selection.nodeIds, ["a1", "b2", "g1"]);
+    assert.deepEqual(selection.facts, {
+      pageCount: 3,
+      internalLinkCount: 0,
+      communityCount: 3,
+      isolatedCount: 0
+    });
+    assert.deepEqual(actionIds(selection), ["explore_potential_links", "compare_differences"]);
+    assert.equal(actionIds(selection).includes("summarize_cluster"), false);
+  });
+
+  it("omits ask actions when onAsk capability is absent", () => {
+    const selection = resolveSelectionForCapabilities(multicommGraph(), { kind: "community", id: "alpha" }, { canAsk: false });
+
+    assert.deepEqual(selection.facts, {
+      pageCount: 3,
+      internalLinkCount: 2,
+      communityCount: 1,
+      isolatedCount: 0
+    });
+    assert.deepEqual(actionIds(selection), []);
+  });
+});
+
+function actionIds(selection: { actions?: Array<{ id: SelectionActionId }> }): SelectionActionId[] {
+  return (selection.actions ?? []).map((action) => action.id);
+}
+
+function multicommGraph(): GraphData {
+  return {
+    meta: {
+      build_date: "2026-06-12T00:00:00.000Z",
+      wiki_title: "Multicomm Fixture",
+      total_nodes: 8,
+      total_edges: 6
+    },
+    nodes: [
+      { id: "a1", label: "Alpha 1", type: "topic", community: "alpha", source_path: "wiki/topics/a1.md" },
+      { id: "a2", label: "Alpha 2", type: "entity", community: "alpha", source_path: "wiki/entities/a2.md" },
+      { id: "a3", label: "Alpha 3", type: "entity", community: "alpha", source_path: "wiki/entities/a3.md" },
+      { id: "bridge", label: "Bridge", type: "topic", community: "beta", source_path: "wiki/topics/bridge.md" },
+      { id: "b1", label: "Beta 1", type: "entity", community: "beta", source_path: "wiki/entities/b1.md" },
+      { id: "b2", label: "Beta 2", type: "entity", community: "beta", source_path: "wiki/entities/b2.md" },
+      { id: "g1", label: "Gamma 1", type: "entity", community: "gamma", source_path: "wiki/entities/g1.md" },
+      { id: "island", label: "Island", type: "source", community: "solo", source_path: "wiki/sources/island.md" }
+    ],
+    edges: [
+      { id: "a1-a2", from: "a1", to: "a2", type: "EXTRACTED", weight: 1 },
+      { id: "a2-a3", from: "a2", to: "a3", type: "EXTRACTED", weight: 1 },
+      { id: "a3-bridge", from: "a3", to: "bridge", type: "INFERRED", weight: 0.7 },
+      { id: "bridge-b1", from: "bridge", to: "b1", type: "EXTRACTED", weight: 1 },
+      { id: "b1-b2", from: "b1", to: "b2", type: "EXTRACTED", weight: 1 },
+      { id: "g1-a2", from: "g1", to: "a2", type: "AMBIGUOUS", weight: 0.4 }
+    ],
+    learning: {
+      version: 1,
+      entry: { recommended_start_node_id: "a1", recommended_start_reason: "community_hub", default_mode: "global" },
+      views: {
+        path: { enabled: false, start_node_id: null, node_ids: [], degraded: true },
+        community: { enabled: false, community_id: null, label: null, node_ids: [], is_weak: false, degraded: true },
+        global: { enabled: true, node_ids: ["a1", "a2", "a3", "bridge", "b1", "b2", "g1", "island"], degraded: false }
+      },
+      communities: [
+        { id: "alpha", label: "Alpha", node_count: 3, color_index: 0 },
+        { id: "beta", label: "Beta", node_count: 3, color_index: 1 },
+        { id: "gamma", label: "Gamma", node_count: 1, color_index: 2 },
+        { id: "solo", label: "Solo", node_count: 1, color_index: 3 }
+      ]
+    }
+  };
+}

package/dist/skills/llm-wiki/packages/graph-engine/test/sim.test.ts

@@ -0,0 +1,123 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import { buildRenderableGraph } from "../src/render";
+import { createLiveGraphSimulation, pinsToPositions, PinState } from "../src/sim";
+import type { GraphData } from "../src/types";
+
+describe("LiveGraphSimulation", () => {
+  it("starts from cold-start graph coordinates and pinned positions", () => {
+    const graph = buildRenderableGraph(sampleGraph(), {
+      theme: "shan-shui",
+      pins: {
+        "wiki/near.md": { x: 800, y: 340 }
+      }
+    });
+    const simulation = createLiveGraphSimulation(graph);
+    const snapshot = simulation.snapshot();
+
+    assert.deepEqual(snapshot.positions.drag, { x: 200, y: 340 });
+    assert.deepEqual(snapshot.positions.near, { x: 800, y: 340 });
+    assert.deepEqual(snapshot.positions.far, { x: 850, y: 340 });
+    simulation.destroy();
+  });
+
+  it("settles to alpha zero instead of moving forever", () => {
+    const graph = buildRenderableGraph(sampleGraph(), { theme: "shan-shui" });
+    const simulation = createLiveGraphSimulation(graph, { coldStartAlpha: 0.09, alphaMin: 0.004 });
+    const settled = simulation.settle();
+
+    assert.equal(settled.alpha, 0);
+    assert.equal(simulation.alpha, 0);
+    simulation.destroy();
+  });
+
+  it("moves direct neighbors during low-heat drag while keeping far nodes fixed", () => {
+    const graph = buildRenderableGraph(sampleGraph(), { theme: "shan-shui" });
+    const simulation = createLiveGraphSimulation(graph, { lowHeatAlphaTarget: 0.15 });
+    simulation.settle();
+    const before = simulation.snapshot();
+
+    simulation.beginDrag("drag");
+    simulation.dragTo("drag", { x: 460, y: 340 });
+    const during = simulation.tick(36);
+
+    assert.ok(during.positions.near.x > before.positions.near.x + 4, "direct neighbor should slide toward the dragged node");
+    assert.deepEqual(during.positions.far, before.positions.far, "far node should remain fixed during the drag");
+    assert.equal(during.positions.drag.x, 460);
+
+    simulation.endDrag();
+    const settled = simulation.settle();
+    assert.equal(settled.alpha, 0);
+    simulation.destroy();
+  });
+});
+
+describe("PinState", () => {
+  it("pins, unpins, and resets by wiki-relative node path", () => {
+    const graph = buildRenderableGraph(sampleGraph(), { theme: "shan-shui" });
+    const pins = new PinState(graph);
+
+    const pinned = pins.pin("drag", { x: 412.5, y: -88.2 });
+    assert.equal(pins.isPinned("drag"), true);
+    assert.deepEqual(pinned.pins, {
+      "wiki/drag.md": { x: 412.5, y: -88.2 }
+    });
+    assert.deepEqual(pinned.pinnedNodeIds, ["drag"]);
+
+    const unpinned = pins.unpin("drag");
+    assert.equal(pins.isPinned("drag"), false);
+    assert.deepEqual(unpinned.pins, {});
+
+    pins.pin("near", { x: 130, y: 245.7 });
+    assert.deepEqual(pins.reset().pins, {});
+  });
+
+  it("normalizes initial pins and exposes render positions for known graph nodes only", () => {
+    const graph = buildRenderableGraph(sampleGraph(), { theme: "shan-shui" });
+    const pins = {
+      "wiki/near.md": { x: 130, y: 245.7 },
+      "wiki/missing.md": { x: 999, y: 999 }
+    };
+    const state = new PinState(graph, pins).snapshot();
+
+    assert.deepEqual(state.pins, {
+      "wiki/near.md": { x: 130, y: 245.7 }
+    });
+    assert.deepEqual(pinsToPositions(graph, state.pins), {
+      near: { x: 130, y: 245.7 }
+    });
+  });
+});
+
+function sampleGraph(): GraphData {
+  return {
+    meta: {
+      build_date: "2026-06-12T00:00:00.000Z",
+      wiki_title: "Simulation Fixture",
+      total_nodes: 3,
+      total_edges: 1
+    },
+    nodes: [
+      { id: "drag", label: "Drag", type: "topic", community: "c1", source_path: "wiki/drag.md", weight: 80, x: 20, y: 50 },
+      { id: "near", label: "Near", type: "entity", community: "c1", source_path: "wiki/near.md", weight: 50, x: 32, y: 50 },
+      { id: "far", label: "Far", type: "entity", community: "c2", source_path: "wiki/far.md", weight: 20, x: 85, y: 50 }
+    ],
+    edges: [
+      { id: "drag-near", from: "drag", to: "near", type: "EXTRACTED", weight: 1 }
+    ],
+    learning: {
+      version: 1,
+      entry: { recommended_start_node_id: "drag", recommended_start_reason: "community_hub", default_mode: "global" },
+      views: {
+        path: { enabled: false, start_node_id: null, node_ids: [], degraded: true },
+        community: { enabled: false, community_id: null, label: null, node_ids: [], is_weak: false, degraded: true },
+        global: { enabled: true, node_ids: ["drag", "near", "far"], degraded: false }
+      },
+      communities: [
+        { id: "c1", label: "Core", node_count: 2, color_index: 0, recommended_start_node_id: "drag" },
+        { id: "c2", label: "Edge", node_count: 1, color_index: 1 }
+      ]
+    }
+  };
+}