@joekytc/dsh-swarm 0.1.2 → 0.2.0

package/skills/llm-wiki-skill/packages/graph-engine/test/sigma-trial-adapter.test.ts

@@ -0,0 +1,82 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import { buildCommunityAggregationMarkers } from "../src";
+import type { GraphData, PinMap } from "../src/types";
+import { buildSigmaGraphologyTrialModel } from "./sigma-trial-adapter";
+
+describe("Sigma/Graphology trial adapter", () => {
+  it("preserves graph semantics for the isolated WebGL candidate route", () => {
+    const data = graphFixture();
+    const pins: PinMap = {
+      "wiki/a.md": { x: 10, y: 20, coordinateSpace: "world" }
+    };
+    const aggregationMarkers = buildCommunityAggregationMarkers(data, {
+      pins,
+      searchResultIds: ["b"],
+      selectedNodeIds: ["a"],
+      minCommunitySize: 2
+    });
+
+    const model = buildSigmaGraphologyTrialModel(data, {
+      pins,
+      searchResultIds: ["b"],
+      selection: { kind: "node", id: "a" },
+      aggregationMarkers
+    });
+
+    assert.equal(model.nodes.length, 3);
+    assert.equal(model.edges.length, 2);
+    assert.deepEqual(model.nodes.map((node) => node.id), ["a", "b", "c"]);
+    assert.equal(model.nodes.find((node) => node.id === "a")?.selected, true);
+    assert.equal(model.nodes.find((node) => node.id === "a")?.pinned, true);
+    assert.equal(model.nodes.find((node) => node.id === "b")?.searchHit, true);
+    assert.equal(model.nodes.find((node) => node.id === "b")?.communityId, "alpha");
+    assert.deepEqual(model.communities.map((community) => community.id), ["alpha", "beta"]);
+    assert.deepEqual(model.communities.find((community) => community.id === "alpha")?.searchResultIds, ["b"]);
+    assert.equal(model.aggregations.length, 1);
+    assert.deepEqual(model.aggregations[0]?.selectedNodeIds, ["a"]);
+    assert.deepEqual(model.aggregations[0]?.searchResultIds, ["b"]);
+    assert.deepEqual(model.aggregations[0]?.pinnedNodeIds, ["a"]);
+
+    assert.equal(model.behavior.route, "candidate-global");
+    assert.deepEqual(model.behavior.searchHighlight.map((item) => item.nodeId), ["b"]);
+    assert.deepEqual(model.behavior.pinInsideAggregation[0]?.pinnedNodeIds, ["a"]);
+    assert.deepEqual(model.behavior.selectedObjectInsideAggregation[0]?.selectedNodeIds, ["a"]);
+    assert.ok(model.behavior.containerSelect.some((item) => item.containerId === "alpha"));
+    assert.ok(model.behavior.enterCommunity.some((item) => item.communityId === "alpha"));
+  });
+});
+
+function graphFixture(): GraphData {
+  return {
+    meta: {
+      build_date: "2026-06-19T00:00:00.000Z",
+      wiki_title: "Sigma trial adapter",
+      total_nodes: 3,
+      total_edges: 2
+    },
+    nodes: [
+      { id: "a", label: "Alpha", type: "topic", community: "alpha", source_path: "wiki/a.md", x: 0, y: 0 },
+      { id: "b", label: "Beta needle", type: "entity", community: "alpha", source_path: "wiki/b.md", x: 10, y: 0 },
+      { id: "c", label: "Gamma", type: "source", community: "beta", source_path: "wiki/c.md", x: 20, y: 0 }
+    ],
+    edges: [
+      { id: "a-b", from: "a", to: "b", type: "EXTRACTED", weight: 1 },
+      { id: "b-c", from: "b", to: "c", type: "INFERRED", weight: 0.7 }
+    ],
+    learning: {
+      version: 1,
+      entry: { recommended_start_node_id: "a", recommended_start_reason: "fixture", default_mode: "global" },
+      views: {
+        path: { enabled: false, start_node_id: null, node_ids: [], degraded: false },
+        community: { enabled: false, community_id: null, label: null, node_ids: [], is_weak: false, degraded: false },
+        global: { enabled: true, node_ids: ["a", "b", "c"], degraded: false }
+      },
+      communities: [
+        { id: "alpha", label: "Alpha", node_count: 2 },
+        { id: "beta", label: "Beta", node_count: 1 }
+      ]
+    }
+  };
+}

package/skills/llm-wiki-skill/packages/graph-engine/test/sigma-trial-adapter.ts

@@ -0,0 +1,271 @@
+import {
+  buildGraphRendererAdapterData,
+  buildGraphRendererBehaviorContract,
+  type GraphRendererBehaviorContract
+} from "../src/render";
+import type {
+  GraphAggregationMarker,
+  GraphData,
+  GraphFocusInput,
+  GraphPinHint,
+  GraphTypeFilters,
+  NodeId,
+  PinMap,
+  SelectionInput
+} from "../src/types";
+
+export interface SigmaTrialOptions {
+  pins?: PinMap;
+  selection?: SelectionInput | null;
+  searchResultIds?: NodeId[];
+  aggregationMarkers?: GraphAggregationMarker[];
+  focus?: GraphFocusInput;
+  typeFilters?: GraphTypeFilters;
+}
+
+export interface SigmaTrialDrawerItem {
+  id: string;
+  label: string;
+  meta: string;
+}
+
+export interface SigmaTrialDrawerPayload {
+  kind: "node" | "community" | "global";
+  title: string;
+  kicker: string;
+  // Representative workbench-like drawer facts (counts the React drawer shows).
+  facts: { label: string; value: string }[];
+  // Representative list rows (core nodes / pinned nodes / search hits), capped.
+  items: SigmaTrialDrawerItem[];
+}
+
+export interface SigmaTrialModel {
+  nodes: SigmaTrialNode[];
+  edges: SigmaTrialEdge[];
+  communities: SigmaTrialCommunity[];
+  aggregations: SigmaTrialAggregation[];
+  // Pre-computed drawer payloads so the trial HTML renders a workbench-weight
+  // summary card instead of a single text node.
+  drawer: {
+    global: SigmaTrialDrawerPayload;
+    nodes: Record<string, SigmaTrialDrawerPayload>;
+    communities: Record<string, SigmaTrialDrawerPayload>;
+  };
+  behavior: GraphRendererBehaviorContract;
+}
+
+export interface SigmaTrialNode {
+  id: string;
+  label: string;
+  x: number;
+  y: number;
+  size: number;
+  color: string;
+  communityId: string | null;
+  sourcePath: string;
+  selected: boolean;
+  searchHit: boolean;
+  pinned: boolean;
+  pinHint: GraphPinHint;
+  aggregationIds: string[];
+}
+
+export interface SigmaTrialEdge {
+  id: string;
+  source: string;
+  target: string;
+  color: string;
+  size: number;
+  relationType: string | null;
+}
+
+export interface SigmaTrialCommunity {
+  id: string;
+  label: string;
+  nodeIds: string[];
+  selected: boolean;
+  searchResultIds: string[];
+  pinnedNodeIds: string[];
+}
+
+export interface SigmaTrialAggregation {
+  id: string;
+  communityId: string | null;
+  nodeIds: string[];
+  selectedNodeIds: string[];
+  searchResultIds: string[];
+  pinnedNodeIds: string[];
+  totalCount: number;
+}
+
+const COMMUNITY_COLORS = [
+  "#2563eb",
+  "#059669",
+  "#d97706",
+  "#7c3aed",
+  "#dc2626",
+  "#0891b2",
+  "#4f46e5",
+  "#65a30d"
+];
+
+export function buildSigmaGraphologyTrialModel(data: GraphData, options: SigmaTrialOptions = {}): SigmaTrialModel {
+  // The trial model must consume adapter-controlled render data only. Node and
+  // edge budgets (which objects exist, their positions, sizes, colors, label
+  // visibility, selection/search/pin/aggregation state) all come from the
+  // adapter output; the raw GraphData is no longer traversed to decide what to
+  // draw. 'data' is still threaded to the adapter for graph semantics.
+  const adapter = buildGraphRendererAdapterData(data, options);
+
+  const nodes = adapter.nodes.map((node): SigmaTrialNode => {
+    const communityId = node.communityId == null ? null : String(node.communityId);
+    return {
+      id: node.id,
+      label: node.label,
+      x: finiteNumber(node.point.x, 0),
+      y: finiteNumber(node.point.y, 0),
+      size: trialNodeSize(node),
+      color: trialNodeColor(node, communityId),
+      communityId,
+      sourcePath: node.sourcePath,
+      selected: node.selected,
+      searchHit: node.searchHit,
+      pinned: node.pinHint.pinned,
+      pinHint: node.pinHint,
+      aggregationIds: node.aggregationIds
+    };
+  });
+
+  const edges = adapter.edges.map((edge): SigmaTrialEdge => ({
+    id: edge.id,
+    source: edge.sourceNodeId,
+    target: edge.targetNodeId,
+    color: "#9ca3af",
+    size: finiteNumber(edge.render.strokeWidth, 1),
+    relationType: edge.relationType == null ? null : String(edge.relationType)
+  }));
+
+  const communities = adapter.communities.map((community): SigmaTrialCommunity => ({
+    id: community.id,
+    label: community.label,
+    nodeIds: community.nodeIds,
+    selected: community.selected,
+    searchResultIds: community.searchResultIds,
+    pinnedNodeIds: community.pinHints.map((hint) => hint.nodeId)
+  }));
+
+  const aggregations = adapter.aggregations.map((aggregation): SigmaTrialAggregation => ({
+    id: aggregation.id,
+    communityId: aggregation.communityId == null ? null : String(aggregation.communityId),
+    nodeIds: aggregation.nodeIds,
+    selectedNodeIds: aggregation.selectedNodeIds,
+    searchResultIds: aggregation.searchResultIds,
+    pinnedNodeIds: aggregation.pinnedNodeIds,
+    totalCount: aggregation.totalCount
+  }));
+
+  const drawer = buildTrialDrawer(adapter);
+
+  return {
+    nodes,
+    edges,
+    communities,
+    aggregations,
+    drawer,
+    behavior: buildGraphRendererBehaviorContract(adapter, "candidate-global")
+  };
+}
+
+// Representative workbench-weight drawer payloads derived only from adapter
+// render data. The trial HTML renders these as a real summary card + list so the
+// drawer/overlay DOM cost is comparable to the production GraphSummaryDrawer.
+function buildTrialDrawer(adapter: ReturnType<typeof buildGraphRendererAdapterData>): SigmaTrialModel["drawer"] {
+  const adjacency = new Map<string, number>();
+  for (const edge of adapter.edges) {
+    adjacency.set(edge.sourceNodeId, (adjacency.get(edge.sourceNodeId) ?? 0) + 1);
+    adjacency.set(edge.targetNodeId, (adjacency.get(edge.targetNodeId) ?? 0) + 1);
+  }
+  const trim = (values: string[]): string[] => values.slice(0, 8);
+
+  const nodePayloads: Record<string, SigmaTrialDrawerPayload> = {};
+  for (const node of adapter.nodes) {
+    const meta = node.type ? String(node.type) : "node";
+    nodePayloads[node.id] = {
+      kind: "node",
+      kicker: "节点",
+      title: node.label || node.id,
+      facts: [
+        { label: "类型", value: meta },
+        { label: "连接", value: String(adjacency.get(node.id) ?? 0) },
+        { label: "社区", value: node.communityId == null ? "—" : String(node.communityId) }
+      ],
+      items: trim(node.aggregationIds).map((id) => ({ id, label: id, meta: "aggregation" }))
+    };
+  }
+
+  const communityPayloads: Record<string, SigmaTrialDrawerPayload> = {};
+  for (const community of adapter.communities) {
+    const labelById = new Map(adapter.nodes.map((node) => [node.id, node.label || node.id]));
+    const coreNodes = community.nodeIds
+      .map((id) => ({ id, label: labelById.get(id) ?? id, degree: adjacency.get(id) ?? 0 }))
+      .sort((a, b) => b.degree - a.degree);
+    communityPayloads[community.id] = {
+      kind: "community",
+      kicker: "社区",
+      title: community.label || community.id,
+      facts: [
+        { label: "节点数", value: String(community.nodeCount) },
+        { label: "命中", value: String(community.searchResultIds.length) },
+        { label: "置顶", value: String(community.pinHints.length) }
+      ],
+      items: trim(coreNodes.map((node) => ({ id: node.id, label: node.label, meta: "core" })))
+    };
+  }
+
+  const globalPayload: SigmaTrialDrawerPayload = {
+    kind: "global",
+    kicker: "全局",
+    title: "全局图谱概览",
+    facts: [
+      { label: "节点", value: String(adapter.counts.nodes) },
+      { label: "边", value: String(adapter.counts.edges) },
+      { label: "社区", value: String(adapter.communities.length) }
+    ],
+    items: trim(adapter.communities.map((community) => ({ id: community.id, label: community.label || community.id, meta: "community" })))
+  };
+
+  return { global: globalPayload, nodes: nodePayloads, communities: communityPayloads };
+}
+
+// Visual budget for a trial node, derived only from adapter render state.
+function trialNodeSize(node: { pinHint: GraphPinHint; selected: boolean; searchHit: boolean; render: { priority: number } }): number {
+  if (node.pinHint.pinned) return 5;
+  if (node.selected) return 5;
+  if (node.searchHit) return 4;
+  return 2;
+}
+
+// Color budget for a trial node, derived only from adapter render state.
+function trialNodeColor(node: { selected: boolean; searchHit: boolean }, communityId: string | null): string {
+  if (node.selected) return "#ef4444";
+  if (node.searchHit) return "#f59e0b";
+  return colorForCommunity(communityId);
+}
+
+function colorForCommunity(communityId: string | null): string {
+  if (!communityId) return "#64748b";
+  const index = Math.abs(hashString(communityId)) % COMMUNITY_COLORS.length;
+  return COMMUNITY_COLORS[index];
+}
+
+function hashString(value: string): number {
+  let hash = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    hash = ((hash << 5) - hash + value.charCodeAt(index)) | 0;
+  }
+  return hash;
+}
+
+function finiteNumber(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}

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

@@ -0,0 +1,207 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import { buildRenderableGraph, screenPointToWorldPoint, worldPointToScreenPoint } from "../src/render";
+import {
+  constrainDragTargetToLayoutBounds,
+  createLiveGraphSimulation,
+  pinsToPositions,
+  PinState
+} from "../src/sim";
+import type { GraphData, PinMap } 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, coordinateSpace: "world" }
+      }
+    });
+    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();
+  });
+
+  it("keeps drag bounds as an explicit layout constraint outside projection helpers", () => {
+    assert.deepEqual(
+      constrainDragTargetToLayoutBounds({ x: -120, y: 940 }, { fallback: { x: 200, y: 340 } }),
+      { x: 0, y: 680 }
+    );
+
+    const graph = buildRenderableGraph(sampleGraph(), { theme: "shan-shui" });
+    const simulation = createLiveGraphSimulation(graph);
+    simulation.beginDrag("drag");
+    const dragged = simulation.dragTo("drag", { x: 1200, y: -250 });
+
+    assert.equal(dragged.fx, 1200);
+    assert.equal(dragged.fy, -250);
+    simulation.destroy();
+
+    const boundedSimulation = createLiveGraphSimulation(graph, {
+      dragBounds: { minX: 0, minY: 0, maxX: 1000, maxY: 680 }
+    });
+    boundedSimulation.beginDrag("drag");
+    const boundedDrag = boundedSimulation.dragTo("drag", { x: 1200, y: -250 });
+
+    assert.equal(boundedDrag.fx, 1000);
+    assert.equal(boundedDrag.fy, 0);
+    boundedSimulation.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, coordinateSpace: "world" }
+    });
+    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, coordinateSpace: "world" as const },
+      "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, coordinateSpace: "world" }
+    });
+    assert.deepEqual(pinsToPositions(graph, state.pins), {
+      near: { x: 130, y: 245.7 }
+    });
+  });
+
+  it("keeps wiki-relative pin format readable and separate from projection math", () => {
+    const graph = buildRenderableGraph(sampleGraph(), { theme: "shan-shui" });
+    const pins: PinMap = {
+      "wiki/drag.md": { x: -42.5, y: 812.75, coordinateSpace: "world" },
+      "wiki/near.md": { x: Number.NaN, y: 245.7 }
+    };
+    const beforeProjection = structuredClone(pins);
+
+    const projected = worldPointToScreenPoint(pins["wiki/drag.md"], { x: -180, y: 64, scale: 1.25 }, { width: 1170, height: 856 });
+    const roundTrip = screenPointToWorldPoint(projected, { x: -180, y: 64, scale: 1.25 }, { width: 1170, height: 856 });
+    const state = new PinState(graph, pins).snapshot();
+
+    assert.deepEqual(pins, beforeProjection, "projection helpers must not rewrite the host pin map");
+    assert.ok(roundTrip.x < 0, "projection round trip should preserve an out-of-world finite pin x");
+    assert.ok(roundTrip.y > 680, "projection round trip should preserve an out-of-world finite pin y");
+    assert.deepEqual(state.pins, {
+      "wiki/drag.md": { x: -42.5, y: 812.75, coordinateSpace: "world" },
+      "wiki/near.md": { x: 0, y: 245.7 }
+    });
+    assert.deepEqual(pinsToPositions(graph, state.pins), {
+      drag: { x: -42.5, y: 812.75 },
+      near: { x: 0, y: 245.7 }
+    });
+  });
+
+  it("separates old percent pins from new world pins", () => {
+    const graph = buildRenderableGraph(sampleGraph(), { theme: "shan-shui" });
+    const pins = new PinState(graph, {
+      "wiki/drag.md": { x: 8, y: 12, coordinateSpace: "world" },
+      "wiki/near.md": { x: 13, y: 50, coordinateSpace: "legacy-percent" }
+    }).snapshot();
+
+    assert.deepEqual(pins.pins, {
+      "wiki/drag.md": { x: 8, y: 12, coordinateSpace: "world" },
+      "wiki/near.md": { x: 13, y: 50, coordinateSpace: "legacy-percent" }
+    });
+    assert.deepEqual(pinsToPositions(graph, pins.pins), {
+      drag: { x: 8, y: 12 },
+      near: { x: 130, y: 340 }
+    });
+  });
+
+  it("treats unmarked small pin values as world coordinates instead of guessing percent", () => {
+    const graph = buildRenderableGraph(sampleGraph(), { theme: "shan-shui" });
+    const pins = new PinState(graph, {
+      "wiki/drag.md": { x: 8, y: 12 }
+    }).snapshot();
+
+    assert.deepEqual(pinsToPositions(graph, pins.pins), {
+      drag: { x: 8, y: 12 }
+    });
+  });
+});
+
+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 }
+      ]
+    }
+  };
+}

package/skills/llm-wiki-skill/packages/graph-engine/test/simulation-bridge.test.ts

@@ -0,0 +1,96 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  beginGraphNodeDrag,
+  resolveGraphNodeDragTarget,
+  screenPointToWorldPoint,
+  worldPointToScreenPoint
+} from "../src/render";
+import type { GraphScreenPoint, GraphWorldPoint, RendererViewport, RendererViewportSize } from "../src/render";
+
+const VIEWPORT_SIZE: RendererViewportSize = { width: 1000, height: 680 };
+
+function assertNear(actual: number, expected: number, message?: string): void {
+  assert.ok(Math.abs(actual - expected) < 0.01, `${message ?? "number"}: expected ${expected}, got ${actual}`);
+}
+
+function assertPointNear(actual: { x: number; y: number }, expected: { x: number; y: number }): void {
+  assertNear(actual.x, expected.x, "x");
+  assertNear(actual.y, expected.y, "y");
+}
+
+describe("graph node drag simulation bridge", () => {
+  it("keeps the grabbed point under the pointer when the viewport is panned and zoomed", () => {
+    const viewport: RendererViewport = { x: -180, y: 72, scale: 2.4 };
+    const nodeWorldPoint: GraphWorldPoint = { x: 360, y: 240 };
+    const nodeScreenPoint = worldPointToScreenPoint(nodeWorldPoint, viewport, VIEWPORT_SIZE);
+    const pointerScreenPoint: GraphScreenPoint = {
+      x: nodeScreenPoint.x + 30,
+      y: nodeScreenPoint.y - 18
+    };
+
+    const drag = beginGraphNodeDrag({
+      nodeWorldPoint,
+      pointerScreenPoint,
+      viewport,
+      viewportSize: VIEWPORT_SIZE
+    });
+    const movedPointer: GraphScreenPoint = {
+      x: pointerScreenPoint.x + 144,
+      y: pointerScreenPoint.y + 96
+    };
+    const target = resolveGraphNodeDragTarget({
+      pointerScreenPoint: movedPointer,
+      viewport,
+      viewportSize: VIEWPORT_SIZE,
+      grabOffset: drag.grabOffset
+    });
+
+    const grabbedWorldPoint = {
+      x: target.x + drag.grabOffset.x,
+      y: target.y + drag.grabOffset.y
+    };
+    assertPointNear(worldPointToScreenPoint(grabbedWorldPoint, viewport, VIEWPORT_SIZE), movedPointer);
+  });
+
+  it("starts a drag at the current node point instead of jumping to the pointer center", () => {
+    const viewport: RendererViewport = { x: -320, y: -140, scale: 1.75 };
+    const nodeWorldPoint: GraphWorldPoint = { x: 700, y: 410 };
+    const pointerScreenPoint: GraphScreenPoint = {
+      x: worldPointToScreenPoint(nodeWorldPoint, viewport, VIEWPORT_SIZE).x - 48,
+      y: worldPointToScreenPoint(nodeWorldPoint, viewport, VIEWPORT_SIZE).y + 22
+    };
+
+    const drag = beginGraphNodeDrag({
+      nodeWorldPoint,
+      pointerScreenPoint,
+      viewport,
+      viewportSize: VIEWPORT_SIZE
+    });
+
+    assertPointNear(drag.targetWorldPoint, nodeWorldPoint);
+    assertPointNear(drag.pointerWorldPoint, screenPointToWorldPoint(pointerScreenPoint, viewport, VIEWPORT_SIZE));
+  });
+
+  it("does not clamp off-world drag targets inside projection or bridge helpers", () => {
+    const viewport: RendererViewport = { x: -120, y: -80, scale: 1.2 };
+    const nodeWorldPoint: GraphWorldPoint = { x: 980, y: 650 };
+    const drag = beginGraphNodeDrag({
+      nodeWorldPoint,
+      pointerScreenPoint: worldPointToScreenPoint(nodeWorldPoint, viewport, VIEWPORT_SIZE),
+      viewport,
+      viewportSize: VIEWPORT_SIZE
+    });
+
+    const target = resolveGraphNodeDragTarget({
+      pointerScreenPoint: { x: 1380, y: 930 },
+      viewport,
+      viewportSize: VIEWPORT_SIZE,
+      grabOffset: drag.grabOffset
+    });
+
+    assert.ok(target.x > 1000, `x should remain outside layout bounds before simulation constraints, got ${target.x}`);
+    assert.ok(target.y > 680, `y should remain outside layout bounds before simulation constraints, got ${target.y}`);
+  });
+});