@joekytc/dsh-swarm 0.1.2 → 0.2.0

package/skills/llm-wiki-skill/packages/graph-engine/src/render/node-drag-lifecycle.ts

@@ -0,0 +1,94 @@
+import type { LiveGraphSimulation, PinState } from "../sim";
+import type { NodeId, PinMap, PinPosition } from "../types";
+import type { RenderPositionMap } from "./model";
+
+export interface GraphNodeDragSession {
+  pointerId: number;
+  nodeId: NodeId;
+  startWorldPoint: PinPosition;
+  wasPinned: boolean;
+}
+
+export interface CommitGraphNodeDragInput {
+  nodeId: NodeId;
+  simulation: LiveGraphSimulation;
+  pinState: PinState;
+  finalWorldPoint?: PinPosition | null;
+}
+
+export interface CancelGraphNodeDragInput {
+  session: GraphNodeDragSession;
+  simulation: LiveGraphSimulation;
+  pinState: PinState;
+}
+
+export interface CommittedGraphNodeDrag {
+  kind: "committed";
+  nodeId: NodeId;
+  pinPosition: PinPosition;
+  positions: RenderPositionMap;
+  pins: PinMap;
+  pinnedNodeIds: NodeId[];
+}
+
+export interface CancelledGraphNodeDrag {
+  kind: "cancelled";
+  nodeId: NodeId;
+  restoredPosition: PinPosition;
+  restoredFixed: boolean;
+  positions: RenderPositionMap;
+  pins: PinMap;
+  pinnedNodeIds: NodeId[];
+}
+
+export function commitGraphNodeDrag(input: CommitGraphNodeDragInput): CommittedGraphNodeDrag {
+  if (input.finalWorldPoint) input.simulation.dragTo(input.nodeId, normalizePosition(input.finalWorldPoint));
+  const snapshot = input.simulation.endDrag({ keepFixed: true });
+  const pinPosition = requirePosition(snapshot.positions, input.nodeId);
+  const pinSnapshot = input.pinState.pin(input.nodeId, pinPosition);
+  return {
+    kind: "committed",
+    nodeId: input.nodeId,
+    pinPosition,
+    positions: snapshot.positions,
+    pins: pinSnapshot.pins,
+    pinnedNodeIds: pinSnapshot.pinnedNodeIds
+  };
+}
+
+export function cancelGraphNodeDrag(input: CancelGraphNodeDragInput): CancelledGraphNodeDrag {
+  const restoredPosition = normalizePosition(input.session.startWorldPoint);
+  const snapshot = input.simulation.endDrag({
+    restore: {
+      position: restoredPosition,
+      fixed: input.session.wasPinned
+    }
+  });
+  const pinSnapshot = input.pinState.snapshot();
+  return {
+    kind: "cancelled",
+    nodeId: input.session.nodeId,
+    restoredPosition,
+    restoredFixed: input.session.wasPinned,
+    positions: snapshot.positions,
+    pins: pinSnapshot.pins,
+    pinnedNodeIds: pinSnapshot.pinnedNodeIds
+  };
+}
+
+function requirePosition(positions: RenderPositionMap, nodeId: NodeId): PinPosition {
+  const position = positions[nodeId];
+  if (!position) throw new Error(`Cannot finish drag for unknown graph node: ${nodeId}`);
+  return normalizePosition(position);
+}
+
+function normalizePosition(position: PinPosition): PinPosition {
+  return {
+    x: finiteNumber(position.x, 0),
+    y: finiteNumber(position.y, 0)
+  };
+}
+
+function finiteNumber(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}

package/skills/llm-wiki-skill/packages/graph-engine/src/render/nodes.ts

@@ -0,0 +1,103 @@
+import type { NodeId } from "../types";
+import type { NodeDisplayMode, RenderableNode } from "./model";
+
+export interface GraphNodeElementHandlers {
+  onNodeClick: (id: NodeId, additive: boolean) => void;
+  onNodeDoubleClick: (id: NodeId) => boolean;
+  onNodePreviewEnter: (id: NodeId) => void;
+  onNodePreviewLeave: () => void;
+}
+
+export interface GraphNodeElementOptions {
+  communityMap?: boolean;
+}
+
+export function createGraphNodeElement(
+  ownerDocument: Document,
+  node: RenderableNode,
+  handlers: GraphNodeElementHandlers,
+  options: GraphNodeElementOptions = {}
+): HTMLButtonElement {
+  const button = ownerDocument.createElement("button");
+  button.className = "node";
+  if (node.unavailable) button.classList.add("is-disabled");
+  applyGraphNodeDisplayMode(button, node.displayMode);
+  if (node.previewStart) button.classList.add("is-preview-start");
+  if (!node.labelVisible) button.classList.add("is-label-hidden");
+  button.type = "button";
+  button.dataset.id = node.id;
+  button.dataset.type = node.type;
+  button.dataset.community = node.community;
+  button.dataset.visualRole = node.visualRole;
+  button.dataset.startNode = node.startNode ? "true" : "false";
+  button.dataset.previewStart = node.previewStart ? "true" : "false";
+  button.dataset.coreAnchor = node.coreAnchor ? "true" : "false";
+  button.dataset.temporaryBoost = node.temporaryBoost > 0 ? "true" : "false";
+  button.dataset.interactionLabelVisible = node.interactionLabelVisible ? "true" : "false";
+  button.dataset.traceable = node.selected || node.coreAnchor || node.interactionLabelVisible ? "true" : "false";
+  button.dataset.worldX = String(node.point.x);
+  button.dataset.worldY = String(node.point.y);
+  button.style.left = `${node.x}%`;
+  button.style.top = `${node.y}%`;
+  button.title = node.label;
+  button.setAttribute("aria-pressed", node.selected ? "true" : "false");
+  button.addEventListener("dblclick", (event) => {
+    event.stopPropagation();
+    handlers.onNodeDoubleClick(node.id);
+  });
+  button.addEventListener("pointerenter", () => handlers.onNodePreviewEnter(node.id));
+  button.addEventListener("pointerleave", () => handlers.onNodePreviewLeave());
+  button.addEventListener("focus", () => handlers.onNodePreviewEnter(node.id));
+  button.addEventListener("blur", () => handlers.onNodePreviewLeave());
+  bindNodeActivationHandlers(button, node.id, handlers);
+
+  if (options.communityMap) {
+    button.dataset.labelSide = node.communityMapLabelSide;
+    button.dataset.relationLabel = node.communityMapRelationLabel ? "true" : "false";
+    button.style.setProperty("--node-size", `${node.communityMapDotSize}px`);
+
+    const pin = ownerDocument.createElement("span");
+    pin.className = "node-pin";
+    pin.setAttribute("aria-hidden", "true");
+
+    const dot = ownerDocument.createElement("span");
+    dot.className = "dot-core";
+    pin.appendChild(dot);
+    button.appendChild(pin);
+  }
+
+  const kind = ownerDocument.createElement("span");
+  kind.className = "node-kind";
+  kind.textContent = node.kind;
+  button.appendChild(kind);
+
+  const name = ownerDocument.createElement("span");
+  name.className = "node-name";
+  name.textContent = node.label;
+  button.appendChild(name);
+
+  const meta = ownerDocument.createElement("span");
+  meta.className = "node-meta";
+  const spark = ownerDocument.createElement("i");
+  spark.className = "spark";
+  meta.appendChild(spark);
+  meta.append(node.unavailable ? "来源暂不可用" : String(Math.round(node.priority || node.weight || 0)));
+  button.appendChild(meta);
+
+  return button;
+}
+
+export function applyGraphNodeDisplayMode(button: HTMLButtonElement, displayMode: NodeDisplayMode): void {
+  button.classList.toggle("is-compact", displayMode === "compact-card");
+  button.classList.toggle("is-point", displayMode === "point");
+  button.classList.toggle("is-overview", displayMode === "overview");
+  button.dataset.densityMode = displayMode;
+}
+
+function bindNodeActivationHandlers(button: HTMLButtonElement, nodeId: string, handlers: GraphNodeElementHandlers): void {
+  button.addEventListener("click", (event) => {
+    if (event.detail !== 0) return;
+    event.stopPropagation();
+    handlers.onNodeClick(nodeId, event.shiftKey);
+  });
+}

package/skills/llm-wiki-skill/packages/graph-engine/src/render/offline-reader.ts

@@ -0,0 +1,209 @@
+import type { GraphNode, SelectionInput } from "../types";
+import { graphNodeTypeLabel, wikiPathForGraphNode } from "../graph-node";
+
+export interface OfflineReaderNode {
+  id: string;
+  label: string;
+  type: string;
+  content?: string;
+  summary?: string;
+}
+
+interface GraphReaderNodeMeta {
+  type: string;
+  typeLabel: string;
+  sourcePath: string;
+  date: string | null;
+  source: string | null;
+}
+
+export interface OfflineSelectionPanelInput {
+  selection: SelectionInput | null;
+  selectedNodes: GraphNode[];
+  facts: {
+    pageCount: number;
+    internalLinkCount: number;
+    communityCount: number;
+    isolatedCount: number;
+  } | null;
+}
+
+export function renderOfflineReader(
+  ownerDocument: Document,
+  reader: HTMLElement,
+  input: {
+    selected: OfflineReaderNode | null;
+    rawNode: GraphNode | null;
+    onClose: () => void;
+  }
+): void {
+  const { selected, rawNode } = input;
+  reader.dataset.state = selected ? "open" : "closed";
+  reader.replaceChildren();
+  if (!selected || !rawNode) {
+    const empty = ownerDocument.createElement("p");
+    empty.className = "graph-reader-empty";
+    empty.textContent = "选择一个节点查看内容";
+    reader.appendChild(empty);
+    return;
+  }
+
+  const header = ownerDocument.createElement("div");
+  header.className = "graph-reader-header";
+  const title = ownerDocument.createElement("div");
+  title.className = "graph-reader-title";
+  title.textContent = selected.label;
+  const readerNode = graphReaderNode(rawNode);
+  const meta = ownerDocument.createElement("div");
+  meta.className = "graph-reader-meta";
+  for (const item of graphReaderMetaItems(readerNode)) {
+    const tag = ownerDocument.createElement("span");
+    tag.textContent = item;
+    meta.appendChild(tag);
+  }
+  const close = ownerDocument.createElement("button");
+  close.type = "button";
+  close.className = "graph-reader-close";
+  close.setAttribute("aria-label", "关闭阅读面板");
+  close.textContent = "×";
+  close.addEventListener("click", input.onClose);
+  header.append(title, meta, close);
+
+  const body = ownerDocument.createElement("div");
+  body.className = "graph-reader-body";
+  if (readerNode.type === "source" && readerNode.sourcePath) {
+    const sourceLink = ownerDocument.createElement("a");
+    sourceLink.className = "graph-reader-source";
+    sourceLink.href = readerNode.sourcePath;
+    sourceLink.textContent = readerNode.sourcePath;
+    body.appendChild(sourceLink);
+  }
+  const content = String(rawNode.content || rawNode.summary || selected.label);
+  const rendered = renderMarkdown(content);
+  if (rendered) {
+    const article = ownerDocument.createElement("article");
+    article.className = "graph-reader-markdown";
+    article.innerHTML = rendered;
+    body.appendChild(article);
+  } else {
+    const pre = ownerDocument.createElement("pre");
+    pre.textContent = content;
+    body.appendChild(pre);
+  }
+  reader.append(header, body);
+}
+
+export function renderOfflineSelectionPanel(
+  ownerDocument: Document,
+  panel: HTMLElement,
+  input: OfflineSelectionPanelInput & { onClose: () => void }
+): void {
+  panel.replaceChildren();
+  panel.dataset.state = input.selection ? "open" : "closed";
+  if (!input.selection || !input.facts) {
+    const empty = ownerDocument.createElement("p");
+    empty.className = "graph-selection-empty";
+    empty.textContent = "Shift+点击 可选择多个节点";
+    panel.appendChild(empty);
+    return;
+  }
+
+  const header = ownerDocument.createElement("div");
+  header.className = "graph-selection-header";
+  const title = ownerDocument.createElement("div");
+  title.className = "graph-selection-title";
+  title.textContent = offlineSelectionTitle(input.selection, input.selectedNodes.length);
+  const close = ownerDocument.createElement("button");
+  close.type = "button";
+  close.className = "graph-selection-close";
+  close.setAttribute("aria-label", "关闭选区面板");
+  close.textContent = "×";
+  close.addEventListener("click", input.onClose);
+  header.append(title, close);
+
+  const hint = ownerDocument.createElement("div");
+  hint.className = "graph-selection-hint";
+  hint.textContent = "Shift+点击 增删节点";
+
+  const facts = ownerDocument.createElement("div");
+  facts.className = "graph-selection-facts";
+  facts.append(
+    createSelectionFact(ownerDocument, "页面", input.facts.pageCount),
+    createSelectionFact(ownerDocument, "内部关联", input.facts.internalLinkCount),
+    createSelectionFact(ownerDocument, "社区", input.facts.communityCount),
+    createSelectionFact(ownerDocument, "孤立页", input.facts.isolatedCount)
+  );
+
+  const list = ownerDocument.createElement("ol");
+  list.className = "graph-selection-pages";
+  for (const node of input.selectedNodes) {
+    const item = ownerDocument.createElement("li");
+    item.className = "graph-selection-page";
+    const name = ownerDocument.createElement("span");
+    name.className = "graph-selection-page-title";
+    name.textContent = node.label || node.id;
+    const path = ownerDocument.createElement("span");
+    path.className = "graph-selection-page-path";
+    path.textContent = wikiPathForGraphNode(node);
+    item.append(name, path);
+    list.appendChild(item);
+  }
+
+  panel.append(header, hint, facts, list);
+}
+
+function createSelectionFact(ownerDocument: Document, label: string, value: number): HTMLElement {
+  const item = ownerDocument.createElement("div");
+  item.className = "graph-selection-fact";
+  const number = ownerDocument.createElement("strong");
+  number.textContent = String(value);
+  const text = ownerDocument.createElement("span");
+  text.textContent = label;
+  item.append(number, text);
+  return item;
+}
+
+function offlineSelectionTitle(selection: SelectionInput, count: number): string {
+  if (selection.kind === "community") return `社区选区 · ${count} 页`;
+  if (selection.kind === "neighbors") return `相邻节点 · ${count} 页`;
+  if (selection.kind === "node") return "选中页面";
+  return `手动选区 · ${count} 页`;
+}
+
+function graphReaderNode(node: GraphNode): GraphReaderNodeMeta {
+  const sourcePath = wikiPathForGraphNode(node);
+  return {
+    type: node.type,
+    typeLabel: graphNodeTypeLabel(node.type),
+    sourcePath,
+    date: dateForNode(node),
+    source: sourceForNode(node)
+  };
+}
+
+function dateForNode(node: GraphNode): string | null {
+  const value = node.date || node.updated_at || node.updatedAt || node.created_at || node.createdAt;
+  return value == null || value === "" ? null : String(value);
+}
+
+function sourceForNode(node: GraphNode): string | null {
+  const value = node.source_title || node.source_url || node.url || node.author || node.source_name;
+  return value == null || value === "" ? null : String(value);
+}
+
+function graphReaderMetaItems(node: GraphReaderNodeMeta): string[] {
+  const items = [node.typeLabel];
+  if (node.date) items.push(node.date);
+  if (node.source) items.push(node.source);
+  return items;
+}
+
+function renderMarkdown(markdown: string): string | null {
+  const runtime = globalThis as unknown as {
+    marked?: { parse?: (input: string, options?: Record<string, unknown>) => string };
+    DOMPurify?: { sanitize?: (input: string, options?: Record<string, unknown>) => string };
+  };
+  if (typeof runtime.marked?.parse !== "function" || typeof runtime.DOMPurify?.sanitize !== "function") return null;
+  const html = runtime.marked.parse(markdown, { breaks: false, gfm: true });
+  return runtime.DOMPurify.sanitize(html, { ADD_ATTR: ["target", "data-target", "tabindex"] });
+}

package/skills/llm-wiki-skill/packages/graph-engine/src/render/overlays-presenter.ts

@@ -0,0 +1,192 @@
+import type { GraphNode, NodeId, SelectionInput } from "../types";
+import { resolveSelectionForCapabilities } from "../select";
+import type { RenderableGraph, RenderableNode } from "./model";
+import { buildHoverPreview } from "./preview";
+import { createEdgeHoverPreviewContent, createHoverPreviewContent } from "./hover-card";
+import { renderOfflineReader, renderOfflineSelectionPanel } from "./offline-reader";
+import { graphEdgeHoverAnchor, graphNodeHoverAnchor, resolveGraphHoverPreviewPosition } from "./overlays";
+import type { GraphRuntimeStateSnapshot } from "./state";
+import type { GraphRenderContext } from "./render-context";
+
+export interface GraphOverlaysPresenter {
+  scheduleHoverPreview(id: NodeId): void;
+  showEdgeHoverPreview(id: string): void;
+  clearHoverPreview(): void;
+  cancelHoverPreviewOnly(): void;
+  setGraphHover(hover: GraphRuntimeStateSnapshot["hover"]): GraphRuntimeStateSnapshot;
+  renderHoverPreview(): void;
+  renderReader(): void;
+  renderSelectionPanel(): void;
+  destroy(): void;
+}
+
+export interface GraphOverlaysPresenterOptions {
+  viewportSize(): { width: number; height: number };
+  clearInteractionState(): void;
+}
+
+export function createGraphOverlaysPresenter(
+  context: GraphRenderContext,
+  options: GraphOverlaysPresenterOptions
+): GraphOverlaysPresenter {
+  function panelSelection(snapshot: GraphRuntimeStateSnapshot = context.runtimeState.snapshot()): SelectionInput | null {
+    return snapshot.selectionSurface === "selection-panel" ? snapshot.selection : null;
+  }
+
+  function renderReader(): void {
+    const reader = context.dom.readerElement;
+    if (!reader) return;
+    const selected = context.graph.selectedNodeId ? context.graph.nodes.find((node) => node.id === context.graph.selectedNodeId) : null;
+    const rawNode = selected ? context.data.nodes.find((node) => node.id === selected.id) : null;
+    renderOfflineReader(context.ownerDocument, reader, {
+      selected: selected
+        ? {
+            id: selected.id,
+            label: selected.label,
+            type: selected.type,
+            content: rawNode?.content ? String(rawNode.content) : undefined,
+            summary: rawNode?.summary ? String(rawNode.summary) : undefined
+          }
+        : null,
+      rawNode: rawNode || null,
+      onClose: () => options.clearInteractionState()
+    });
+  }
+
+  function renderSelectionPanel(): void {
+    const panel = context.dom.selectionElement;
+    if (!panel) return;
+    const selection = panelSelection();
+    const resolved = selection ? resolveSelectionForCapabilities(context.data, selection, { canAsk: false }) : null;
+    const selectedNodes = resolved
+      ? resolved.nodeIds
+        .map((id) => context.data.nodes.find((node) => node.id === id))
+        .filter((node): node is GraphNode => Boolean(node))
+      : [];
+    renderOfflineSelectionPanel(context.ownerDocument, panel, {
+      selection,
+      selectedNodes,
+      facts: resolved?.facts || null,
+      onClose: () => options.clearInteractionState()
+    });
+  }
+
+  function scheduleHoverPreview(id: NodeId): void {
+    if (context.graph.focus?.kind === "community") return;
+    if (context.previewTimer) clearTimeout(context.previewTimer);
+    context.previewTimer = setTimeout(() => {
+      context.previewTimer = null;
+      const hover = context.runtimeState.snapshot().hover;
+      if (hover?.kind !== "node" || hover.id !== id) return;
+      renderHoverPreview();
+    }, 300);
+  }
+
+  function showEdgeHoverPreview(id: string): void {
+    if (context.previewTimer) {
+      clearTimeout(context.previewTimer);
+      context.previewTimer = null;
+    }
+    setGraphHover({ kind: "edge", id });
+    renderHoverPreview();
+  }
+
+  function clearHoverPreview(): void {
+    if (context.previewTimer) {
+      clearTimeout(context.previewTimer);
+      context.previewTimer = null;
+    }
+    const hover = context.runtimeState.snapshot().hover;
+    if (hover?.kind !== "node" && hover?.kind !== "edge") return;
+    setGraphHover(null);
+    renderHoverPreview();
+  }
+
+  function cancelHoverPreviewOnly(): void {
+    if (context.previewTimer) {
+      clearTimeout(context.previewTimer);
+      context.previewTimer = null;
+    }
+    if (context.dom.previewElement?.dataset.kind === "node") {
+      context.dom.previewElement.dataset.state = "closed";
+      context.dom.previewElement.replaceChildren();
+    }
+  }
+
+  function setGraphHover(hover: GraphRuntimeStateSnapshot["hover"]): GraphRuntimeStateSnapshot {
+    return context.runtimeState.setHover(hover);
+  }
+
+  function renderHoverPreview(): void {
+    const preview = context.dom.previewElement;
+    if (!preview) return;
+    const hover = context.runtimeState.snapshot().hover;
+    const edge = hover?.kind === "edge" ? context.graph.edges.find((item) => item.id === hover.id) : null;
+    const rawNode = hover?.kind === "node" ? context.data.nodes.find((node) => node.id === hover.id) : null;
+    const renderedNode = hover?.kind === "node" ? context.graph.nodes.find((node) => node.id === hover.id) : null;
+    preview.replaceChildren();
+    preview.dataset.kind = edge ? "edge" : "node";
+    if (edge) {
+      preview.dataset.state = "open";
+      preview.append(createEdgeHoverPreviewContent(context.ownerDocument, edge.relationType, edge.confidence));
+      positionEdgeHoverPreview(preview, edge);
+      return;
+    }
+    if (hover?.kind === "node" && context.graph.focus?.kind === "community") {
+      preview.dataset.state = "closed";
+      return;
+    }
+    preview.dataset.state = rawNode && renderedNode ? "open" : "closed";
+    if (!rawNode || !renderedNode) return;
+    const content = buildHoverPreview(rawNode);
+    preview.append(createHoverPreviewContent(context.ownerDocument, content));
+    positionHoverPreview(preview, renderedNode);
+  }
+
+  function positionHoverPreview(preview: HTMLElement, node: RenderableNode): void {
+    const previewRect = preview.getBoundingClientRect();
+    const size = options.viewportSize();
+    const position = resolveGraphHoverPreviewPosition({
+      anchorScreenPoint: graphNodeHoverAnchor(node, context.runtimeState.snapshot().viewport, size, context.graph.worldBounds),
+      previewSize: { width: previewRect.width, height: previewRect.height },
+      viewportSize: size,
+      offset: { x: 18, y: -previewRect.height - 24 },
+      margin: 12
+    });
+    preview.style.left = `${position.x}px`;
+    preview.style.top = `${position.y}px`;
+  }
+
+  function positionEdgeHoverPreview(preview: HTMLElement, edge: RenderableGraph["edges"][number]): void {
+    const previewRect = preview.getBoundingClientRect();
+    const source = context.graph.nodes.find((node) => node.id === edge.source);
+    const target = context.graph.nodes.find((node) => node.id === edge.target);
+    const size = options.viewportSize();
+    const position = resolveGraphHoverPreviewPosition({
+      anchorScreenPoint: graphEdgeHoverAnchor({ source, target }, context.runtimeState.snapshot().viewport, size, context.graph.worldBounds),
+      previewSize: { width: previewRect.width, height: previewRect.height },
+      viewportSize: size,
+      offset: { x: 16, y: -previewRect.height - 16 },
+      margin: 12
+    });
+    preview.style.left = `${position.x}px`;
+    preview.style.top = `${position.y}px`;
+  }
+
+  function destroy(): void {
+    if (context.previewTimer) clearTimeout(context.previewTimer);
+    context.previewTimer = null;
+  }
+
+  return {
+    scheduleHoverPreview,
+    showEdgeHoverPreview,
+    clearHoverPreview,
+    cancelHoverPreviewOnly,
+    setGraphHover,
+    renderHoverPreview,
+    renderReader,
+    renderSelectionPanel,
+    destroy
+  };
+}

package/skills/llm-wiki-skill/packages/graph-engine/src/render/overlays.ts

@@ -0,0 +1,73 @@
+import { worldPointToScreenPoint, type GraphScreenPoint, type GraphWorldBounds, type GraphWorldPoint } from "./geometry";
+import type { RendererViewport, RendererViewportSize } from "./viewport";
+
+export interface GraphOverlayNodeLike {
+  point: GraphWorldPoint;
+}
+
+export interface GraphOverlayEdgeLike {
+  source?: GraphOverlayNodeLike | null;
+  target?: GraphOverlayNodeLike | null;
+}
+
+export interface GraphPreviewSize {
+  width: number;
+  height: number;
+}
+
+export interface GraphPreviewPositionInput {
+  anchorScreenPoint: GraphScreenPoint;
+  previewSize: GraphPreviewSize;
+  viewportSize: RendererViewportSize;
+  offset: { x: number; y: number };
+  margin?: number;
+}
+
+export function graphNodeHoverAnchor(
+  node: GraphOverlayNodeLike,
+  viewport: RendererViewport,
+  viewportSize: RendererViewportSize,
+  worldBounds?: GraphWorldBounds
+): GraphScreenPoint {
+  return worldPointToScreenPoint(node.point, viewport, viewportSize, worldBounds);
+}
+
+export function graphEdgeHoverAnchor(
+  edge: GraphOverlayEdgeLike,
+  viewport: RendererViewport,
+  viewportSize: RendererViewportSize,
+  worldBounds?: GraphWorldBounds
+): GraphScreenPoint {
+  if (!edge.source || !edge.target) {
+    return {
+      x: viewportSize.width / 2,
+      y: viewportSize.height / 2
+    };
+  }
+  const source = worldPointToScreenPoint(edge.source.point, viewport, viewportSize, worldBounds);
+  const target = worldPointToScreenPoint(edge.target.point, viewport, viewportSize, worldBounds);
+  return {
+    x: (source.x + target.x) / 2,
+    y: (source.y + target.y) / 2
+  };
+}
+
+export function resolveGraphHoverPreviewPosition(input: GraphPreviewPositionInput): GraphScreenPoint {
+  const margin = finiteNumber(input.margin, 12);
+  const preferredLeft = input.anchorScreenPoint.x + finiteNumber(input.offset.x, 0);
+  const preferredTop = input.anchorScreenPoint.y + finiteNumber(input.offset.y, 0);
+  const maxLeft = Math.max(margin, input.viewportSize.width - finiteNumber(input.previewSize.width, 0) - margin);
+  const maxTop = Math.max(margin, input.viewportSize.height - finiteNumber(input.previewSize.height, 0) - margin);
+  return {
+    x: clamp(preferredLeft, margin, maxLeft),
+    y: clamp(preferredTop, margin, maxTop)
+  };
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
+function finiteNumber(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}