@joekytc/dsh-swarm 0.1.2 → 0.2.0

package/skills/llm-wiki-skill/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "llm-wiki",
+  "version": "0.0.0",
+  "private": true,
+  "description": "llm-wiki monorepo: Skill core, workbench, and shared packages.",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "workspaces": [
+    "workbench/server",
+    "workbench/web",
+    "packages/*"
+  ],
+  "scripts": {
+    "dev": "concurrently -n server,web -c blue,magenta --kill-others-on-fail \"npm run dev:server\" \"npm run dev:web\"",
+    "dev:server": "npm run dev --workspace=@llm-wiki-agent/server",
+    "dev:web": "npm run dev --workspace=@llm-wiki-agent/web",
+    "typecheck": "npm run typecheck --workspaces --if-present"
+  },
+  "devDependencies": {
+    "concurrently": "^9.2.1"
+  }
+}

package/skills/llm-wiki-skill/packages/graph-engine/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@llm-wiki/graph-engine",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Shared llm-wiki graph atlas engine for the workbench and offline HTML.",
+  "license": "MIT",
+  "sideEffects": false,
+  "main": "./dist/engine.iife.js",
+  "module": "./dist/engine.esm.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/engine.esm.js",
+      "default": "./dist/engine.esm.js"
+    }
+  },
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.json --emitDeclarationOnly",
+    "test": "node --import tsx --test test/*.test.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "devDependencies": {
+    "@types/d3-force": "^3.0.10",
+    "tsx": "^4.19.0",
+    "typescript": "~6.0.2",
+    "vis-network": "^10.1.0",
+    "vite": "^8.0.12"
+  },
+  "dependencies": {
+    "d3-force": "^3.0.0",
+    "d3-quadtree": "^3.0.1",
+    "graphology": "^0.26.0",
+    "sigma": "^3.0.3"
+  }
+}

package/skills/llm-wiki-skill/packages/graph-engine/src/anim/.gitkeep

@@ -0,0 +1 @@
+

package/skills/llm-wiki-skill/packages/graph-engine/src/anim/index.ts

@@ -0,0 +1,179 @@
+import type { CommunityId, EdgeId, GraphDiff, NodeId } from "../types";
+
+export type DiffQueueVisibility = "visible" | "hidden";
+export type DiffQueueDragState = "idle" | "dragging";
+export type DiffQueueReason = "visible" | "hidden" | "dragging";
+
+export interface DiffQueueSnapshot {
+  pending: GraphDiff | null;
+  isAnimating: boolean;
+  visibility: DiffQueueVisibility;
+  dragState: DiffQueueDragState;
+}
+
+export interface DiffQueueDecision {
+  action: "consume" | "queue";
+  diff: GraphDiff | null;
+  reason: DiffQueueReason;
+  snapshot: DiffQueueSnapshot;
+}
+
+export class GraphDiffQueue {
+  private pending: GraphDiff | null = null;
+  private visibility: DiffQueueVisibility;
+  private dragState: DiffQueueDragState = "idle";
+  private isAnimating = false;
+
+  constructor(options: { visible?: boolean } = {}) {
+    this.visibility = options.visible === false ? "hidden" : "visible";
+  }
+
+  get snapshot(): DiffQueueSnapshot {
+    return {
+      pending: this.pending,
+      isAnimating: this.isAnimating,
+      visibility: this.visibility,
+      dragState: this.dragState
+    };
+  }
+
+  push(diff: GraphDiff | null): DiffQueueDecision {
+    if (!diff || isEmptyDiff(diff)) return this.decision("queue", null, this.blockedReason());
+    if (this.canConsume()) {
+      this.isAnimating = true;
+      return this.decision("consume", diff, "visible");
+    }
+    this.pending = mergeGraphDiffs(this.pending, diff);
+    return this.decision("queue", this.pending, this.blockedReason());
+  }
+
+  setVisible(visible: boolean): DiffQueueDecision {
+    this.visibility = visible ? "visible" : "hidden";
+    return this.flushIfReady(visible ? "visible" : "hidden");
+  }
+
+  setDragging(dragging: boolean): DiffQueueDecision {
+    this.dragState = dragging ? "dragging" : "idle";
+    return this.flushIfReady(dragging ? "dragging" : "visible");
+  }
+
+  finishAnimation(): DiffQueueDecision {
+    this.isAnimating = false;
+    return this.flushIfReady("visible");
+  }
+
+  clear(): void {
+    this.pending = null;
+    this.isAnimating = false;
+  }
+
+  private flushIfReady(fallbackReason: DiffQueueReason): DiffQueueDecision {
+    if (!this.pending || !this.canConsume()) {
+      return this.decision("queue", this.pending, this.blockedReason(fallbackReason));
+    }
+    const diff = this.pending;
+    this.pending = null;
+    this.isAnimating = true;
+    return this.decision("consume", diff, "visible");
+  }
+
+  private canConsume(): boolean {
+    return this.visibility === "visible" && this.dragState === "idle" && !this.isAnimating;
+  }
+
+  private blockedReason(fallback: DiffQueueReason = "visible"): DiffQueueReason {
+    if (this.visibility === "hidden") return "hidden";
+    if (this.dragState === "dragging") return "dragging";
+    return fallback;
+  }
+
+  private decision(action: DiffQueueDecision["action"], diff: GraphDiff | null, reason: DiffQueueReason): DiffQueueDecision {
+    return {
+      action,
+      diff,
+      reason,
+      snapshot: this.snapshot
+    };
+  }
+}
+
+export function mergeGraphDiffs(previous: GraphDiff | null, next: GraphDiff): GraphDiff {
+  if (!previous) return cloneDiff(next);
+
+  const addedNodes = new Set(previous.addedNodes);
+  const removedNodes = new Set(previous.removedNodes);
+  for (const id of next.addedNodes) {
+    if (removedNodes.has(id)) removedNodes.delete(id);
+    else addedNodes.add(id);
+  }
+  for (const id of next.removedNodes) {
+    if (addedNodes.has(id)) addedNodes.delete(id);
+    else removedNodes.add(id);
+  }
+
+  const addedEdges = new Set(previous.addedEdges);
+  const removedEdges = new Set(previous.removedEdges);
+  for (const id of next.addedEdges) {
+    if (removedEdges.has(id)) removedEdges.delete(id);
+    else addedEdges.add(id);
+  }
+  for (const id of next.removedEdges) {
+    if (addedEdges.has(id)) addedEdges.delete(id);
+    else removedEdges.add(id);
+  }
+
+  return {
+    addedNodes: orderedSet(addedNodes),
+    removedNodes: orderedSet(removedNodes),
+    recoloredNodes: mergeRecolors(previous.recoloredNodes, next.recoloredNodes, addedNodes, removedNodes),
+    addedEdges: orderedSet(addedEdges),
+    removedEdges: orderedSet(removedEdges),
+    newCommunities: orderedSet(new Set([...previous.newCommunities, ...next.newCommunities])),
+    stats: next.stats
+  };
+}
+
+export function isEmptyDiff(diff: GraphDiff): boolean {
+  return diff.addedNodes.length === 0
+    && diff.removedNodes.length === 0
+    && diff.recoloredNodes.length === 0
+    && diff.addedEdges.length === 0
+    && diff.removedEdges.length === 0
+    && diff.newCommunities.length === 0;
+}
+
+function mergeRecolors(
+  previous: GraphDiff["recoloredNodes"],
+  next: GraphDiff["recoloredNodes"],
+  addedNodes: Set<NodeId>,
+  removedNodes: Set<NodeId>
+): GraphDiff["recoloredNodes"] {
+  const byId = new Map<NodeId, { id: NodeId; from: CommunityId; to: CommunityId }>();
+  for (const item of previous) byId.set(item.id, { ...item });
+  for (const item of next) {
+    const existing = byId.get(item.id);
+    byId.set(item.id, {
+      id: item.id,
+      from: existing?.from ?? item.from,
+      to: item.to
+    });
+  }
+  for (const id of [...addedNodes, ...removedNodes]) byId.delete(id);
+  return Array.from(byId.values()).filter((item) => item.from !== item.to);
+}
+
+function cloneDiff(diff: GraphDiff): GraphDiff {
+  return {
+    addedNodes: [...diff.addedNodes],
+    removedNodes: [...diff.removedNodes],
+    recoloredNodes: diff.recoloredNodes.map((item) => ({ ...item })),
+    addedEdges: [...diff.addedEdges],
+    removedEdges: [...diff.removedEdges],
+    newCommunities: [...diff.newCommunities],
+    stats: { ...diff.stats }
+  };
+}
+
+function orderedSet<T extends NodeId | EdgeId | CommunityId>(set: Set<T>): T[] {
+  return Array.from(set);
+}

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

@@ -0,0 +1,79 @@
+export type GraphArchitectureLayerId =
+  | "data"
+  | "layout"
+  | "viewport"
+  | "controller"
+  | "renderer"
+  | "gestures"
+  | "facade";
+
+export interface GraphArchitectureLayer {
+  id: GraphArchitectureLayerId;
+  name: string;
+  owns: readonly string[];
+  entrypoints: readonly string[];
+  mustNotOwn: readonly string[];
+}
+
+export const GRAPH_ARCHITECTURE_LAYERS = [
+  {
+    id: "data",
+    name: "GraphData",
+    owns: ["graph schema", "node and edge facts", "selection data inputs"],
+    entrypoints: ["src/types.ts", "src/model/", "src/graph-node.ts", "src/select/"],
+    mustNotOwn: ["DOM", "screen projection", "host callbacks", "pointer or wheel events"]
+  },
+  {
+    id: "layout",
+    name: "GraphLayout",
+    owns: ["world positions", "layout bounds", "community wash geometry", "spatial hit testing"],
+    entrypoints: ["src/layout/", "src/render/model.ts", "src/render/community-wash.ts", "src/sim/"],
+    mustNotOwn: ["host callbacks", "browser default policy", "screen projection"]
+  },
+  {
+    id: "viewport",
+    name: "GraphViewport",
+    owns: ["camera", "world/screen projection", "fit, pan, zoom, minimap projection", "resize anchoring"],
+    entrypoints: ["src/render/viewport.ts", "src/render/geometry.ts"],
+    mustNotOwn: ["graph data mutation", "DOM event classification", "host callbacks"]
+  },
+  {
+    id: "controller",
+    name: "GraphController",
+    owns: ["semantic graph commands", "keyboard routing", "node drag coordination"],
+    entrypoints: ["src/render/controller.ts"],
+    mustNotOwn: ["host callbacks", "graph drawing", "render-model computation"]
+  },
+  {
+    id: "renderer",
+    name: "GraphRenderer",
+    owns: ["DOM/SVG drawing", "node, edge, wash, toolbar, overlay, reader painting", "render-only CSS state"],
+    entrypoints: [
+      "src/render/graph-renderer-root.ts",
+      "src/render/render-pipeline.ts",
+      "src/render/overlays-presenter.ts",
+      "src/render/nodes.ts",
+      "src/render/edges.ts",
+      "src/render/community-washes.ts",
+      "src/render/minimap.ts",
+      "src/render/controls.ts",
+      "src/render/hover-card.ts",
+      "src/render/offline-reader.ts"
+    ],
+    mustNotOwn: ["host callbacks", "selection semantics", "browser default policy"]
+  },
+  {
+    id: "gestures",
+    name: "GraphGestures",
+    owns: ["raw wheel, pointer, and keyboard ownership", "gesture blockers", "graph-owned intent classification"],
+    entrypoints: ["src/render/gestures.ts"],
+    mustNotOwn: ["host callbacks", "graph drawing", "data persistence"]
+  },
+  {
+    id: "facade",
+    name: "GraphFacade",
+    owns: ["public graph engine API", "host capability callbacks", "selection resolution", "renderer lifecycle"],
+    entrypoints: ["src/facade.ts", "src/index.ts"],
+    mustNotOwn: ["raw DOM event policy", "node layout physics", "drawing internals"]
+  }
+] as const satisfies readonly GraphArchitectureLayer[];

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

@@ -0,0 +1,121 @@
+import type { CommunityId, GraphData, GraphDiff, GraphNode, NodeId } from "./types";
+
+const MIN_COMMUNITY_MATCH_JACCARD = 0.5;
+
+interface CommunityGroup {
+	id: CommunityId;
+	members: Set<NodeId>;
+}
+
+export function diffGraphData(previous: GraphData, next: GraphData): GraphDiff {
+	const previousNodeIds = new Set(previous.nodes.map((node) => node.id));
+	const nextNodeIds = new Set(next.nodes.map((node) => node.id));
+	const previousEdgeIds = new Set(previous.edges.map((edge) => edge.id));
+	const nextEdgeIds = new Set(next.edges.map((edge) => edge.id));
+	const alignedCommunities = alignCommunities(previous, next);
+
+	const addedNodes = stableDifference(nextNodeIds, previousNodeIds, next.nodes.map((node) => node.id));
+	const removedNodes = stableDifference(previousNodeIds, nextNodeIds, previous.nodes.map((node) => node.id));
+	const addedEdges = stableDifference(nextEdgeIds, previousEdgeIds, next.edges.map((edge) => edge.id));
+	const removedEdges = stableDifference(previousEdgeIds, nextEdgeIds, previous.edges.map((edge) => edge.id));
+	const recoloredNodes = recoloredExistingNodes(previous, next, alignedCommunities);
+
+	return {
+		addedNodes,
+		removedNodes,
+		recoloredNodes,
+		addedEdges,
+		removedEdges,
+		newCommunities: alignedCommunities.newCommunities,
+		stats: {
+			nodeCount: next.nodes.length,
+			edgeCount: next.edges.length,
+			communityCount: communityGroups(next).length
+		}
+	};
+}
+
+function recoloredExistingNodes(
+	previous: GraphData,
+	next: GraphData,
+	alignment: { nextToPrevious: Map<CommunityId, CommunityId> }
+): GraphDiff["recoloredNodes"] {
+	const previousById = new Map(previous.nodes.map((node) => [node.id, node]));
+	const result: GraphDiff["recoloredNodes"] = [];
+	for (const nextNode of next.nodes) {
+		const previousNode = previousById.get(nextNode.id);
+		if (!previousNode) continue;
+		const previousCommunity = communityForNode(previousNode);
+		const nextCommunity = communityForNode(nextNode);
+		if (!previousCommunity || !nextCommunity) continue;
+		const alignedNextCommunity = alignment.nextToPrevious.get(nextCommunity);
+		if (!alignedNextCommunity) continue;
+		if (previousCommunity === alignedNextCommunity) continue;
+		result.push({ id: nextNode.id, from: previousCommunity, to: nextCommunity });
+	}
+	return result;
+}
+
+function alignCommunities(previous: GraphData, next: GraphData): {
+	nextToPrevious: Map<CommunityId, CommunityId>;
+	newCommunities: CommunityId[];
+} {
+	const previousGroups = communityGroups(previous);
+	const nextGroups = communityGroups(next);
+	const pairs: Array<{ previous: CommunityId; next: CommunityId; score: number }> = [];
+	for (const previousGroup of previousGroups) {
+		for (const nextGroup of nextGroups) {
+			const score = jaccard(previousGroup.members, nextGroup.members);
+			if (score >= MIN_COMMUNITY_MATCH_JACCARD) {
+				pairs.push({ previous: previousGroup.id, next: nextGroup.id, score });
+			}
+		}
+	}
+	pairs.sort((a, b) => b.score - a.score || a.previous.localeCompare(b.previous) || a.next.localeCompare(b.next));
+
+	const usedPrevious = new Set<CommunityId>();
+	const usedNext = new Set<CommunityId>();
+	const nextToPrevious = new Map<CommunityId, CommunityId>();
+	for (const pair of pairs) {
+		if (usedPrevious.has(pair.previous) || usedNext.has(pair.next)) continue;
+		usedPrevious.add(pair.previous);
+		usedNext.add(pair.next);
+		nextToPrevious.set(pair.next, pair.previous);
+	}
+
+	const newCommunities = nextGroups
+		.map((group) => group.id)
+		.filter((id) => !nextToPrevious.has(id));
+	return { nextToPrevious, newCommunities };
+}
+
+function communityGroups(data: GraphData): CommunityGroup[] {
+	const groups = new Map<CommunityId, Set<NodeId>>();
+	for (const node of data.nodes) {
+		const community = communityForNode(node);
+		if (!community) continue;
+		const members = groups.get(community) ?? new Set<NodeId>();
+		members.add(node.id);
+		groups.set(community, members);
+	}
+	return Array.from(groups.entries()).map(([id, members]) => ({ id, members }));
+}
+
+function communityForNode(node: GraphNode): CommunityId | null {
+	if (node.community == null || node.community === "") return null;
+	return String(node.community);
+}
+
+function jaccard(left: Set<NodeId>, right: Set<NodeId>): number {
+	if (left.size === 0 && right.size === 0) return 1;
+	let intersection = 0;
+	for (const id of left) {
+		if (right.has(id)) intersection++;
+	}
+	const union = new Set([...left, ...right]).size;
+	return union === 0 ? 0 : intersection / union;
+}
+
+function stableDifference<T>(left: Set<T>, right: Set<T>, order: T[]): T[] {
+	return order.filter((item) => left.has(item) && !right.has(item));
+}