@joekytc/dsh-swarm 0.1.2 → 0.3.0

package/skills/llm-wiki-skill/packages/graph-engine/src/render/community-cloud-geometry.ts

@@ -0,0 +1,178 @@
+import type { GraphRendererAdapterData } from "./adapter";
+import type { GraphScreenPoint } from "./geometry";
+import { sigmaWorldPointToScreenPoint } from "./sigma-coordinates";
+import type { SigmaGlobalRendererCreateOptions, SigmaGlobalSigmaLike } from "./sigma-global-renderer";
+
+export interface SigmaCommunityCloud {
+  box: { left: number; top: number; width: number; height: number };
+  localPoints: Array<{ x: number; y: number }> | null;
+}
+
+export interface SigmaCommunityCloudBasis {
+  hullPoints: Array<{ x: number; y: number }>;
+  signature: string;
+}
+
+export function sigmaCommunityCloudBasisById(adapterData: GraphRendererAdapterData): Map<string, SigmaCommunityCloudBasis> {
+  const washByCommunityId = new Map(adapterData.renderable.communities.map((community) => [community.id, community.wash]));
+  const pointsByCommunityId = new Map<string, Array<{ x: number; y: number }>>();
+  for (const node of adapterData.nodes) {
+    if (!node.communityId) continue;
+    const wash = washByCommunityId.get(node.communityId);
+    if (!wash) continue;
+    const list = pointsByCommunityId.get(node.communityId);
+    const point = clampPointToWorldEllipse(node.point, wash);
+    if (list) list.push(point);
+    else pointsByCommunityId.set(node.communityId, [point]);
+  }
+  const output = new Map<string, SigmaCommunityCloudBasis>();
+  for (const [communityId, points] of pointsByCommunityId) {
+    output.set(communityId, { hullPoints: convexHull2d(points), signature: sigmaCommunityCloudSignature(points, washByCommunityId.get(communityId)) });
+  }
+  return output;
+}
+
+export function sigmaCommunityCloudBasisByIdWithReuse(
+  previous: Map<string, SigmaCommunityCloudBasis>,
+  adapterData: GraphRendererAdapterData
+): Map<string, SigmaCommunityCloudBasis> {
+  const washByCommunityId = new Map(adapterData.renderable.communities.map((community) => [community.id, community.wash]));
+  const pointsByCommunityId = new Map<string, Array<{ x: number; y: number }>>();
+  for (const node of adapterData.nodes) {
+    if (!node.communityId) continue;
+    const wash = washByCommunityId.get(node.communityId);
+    if (!wash) continue;
+    const list = pointsByCommunityId.get(node.communityId);
+    const point = clampPointToWorldEllipse(node.point, wash);
+    if (list) list.push(point);
+    else pointsByCommunityId.set(node.communityId, [point]);
+  }
+  const output = new Map<string, SigmaCommunityCloudBasis>();
+  for (const [communityId, points] of pointsByCommunityId) {
+    const signature = sigmaCommunityCloudSignature(points, washByCommunityId.get(communityId));
+    const cached = previous.get(communityId);
+    output.set(communityId, cached?.signature === signature ? cached : { hullPoints: convexHull2d(points), signature });
+  }
+  return output;
+}
+
+export function sigmaCommunityCloudBasisByIdWithNodePoint(
+  previous: Map<string, SigmaCommunityCloudBasis>,
+  adapterData: GraphRendererAdapterData,
+  nodeId: string
+): Map<string, SigmaCommunityCloudBasis> {
+  const changedNode = adapterData.nodes.find((node) => node.id === nodeId);
+  if (!changedNode?.communityId) return previous;
+  const community = adapterData.renderable.communities.find((item) => item.id === changedNode.communityId);
+  if (!community?.wash) return previous;
+  const wash = community.wash;
+  const points = adapterData.nodes
+    .filter((node) => node.communityId === changedNode.communityId)
+    .map((node) => clampPointToWorldEllipse(node.point, wash));
+  const signature = sigmaCommunityCloudSignature(points, wash);
+  const cached = previous.get(changedNode.communityId);
+  if (cached?.signature === signature) return previous;
+  const next = new Map(previous);
+  next.set(changedNode.communityId, { hullPoints: convexHull2d(points), signature });
+  return next;
+}
+
+export function sigmaCommunityCloudSignature(
+  points: readonly { x: number; y: number }[],
+  wash: { cx: number; cy: number; rx: number; ry: number } | null | undefined
+): string {
+  const parts = wash ? [wash.cx, wash.cy, wash.rx, wash.ry] : [];
+  for (const point of points) parts.push(point.x, point.y);
+  return parts.map((value) => String(Math.round(value * 1000) / 1000)).join(",");
+}
+
+export function sigmaProjectedCloudHullPoints(
+  basis: SigmaCommunityCloudBasis | undefined,
+  sigma: SigmaGlobalSigmaLike,
+  options: Pick<SigmaGlobalRendererCreateOptions, "viewport" | "viewportSize" | "adapterData">
+): GraphScreenPoint[] {
+  return basis?.hullPoints.map((point) => sigmaWorldPointToScreenPoint(sigma, point, options)) ?? [];
+}
+
+export function clampPointToWorldEllipse(
+  point: { x: number; y: number },
+  ellipse: { cx: number; cy: number; rx: number; ry: number }
+): { x: number; y: number } {
+  const rx = Math.max(1, ellipse.rx);
+  const ry = Math.max(1, ellipse.ry);
+  const dx = point.x - ellipse.cx;
+  const dy = point.y - ellipse.cy;
+  const distance = Math.hypot(dx / rx, dy / ry);
+  if (distance <= 1) return { x: point.x, y: point.y };
+  return {
+    x: ellipse.cx + dx / distance,
+    y: ellipse.cy + dy / distance
+  };
+}
+
+export function sigmaCommunityCloud(
+  screenHullPoints: GraphScreenPoint[],
+  fallbackBox: { left: number; top: number; width: number; height: number }
+): SigmaCommunityCloud {
+  const hull = screenHullPoints;
+  if (hull.length >= 3) {
+    const cx = hull.reduce((sum, p) => sum + p.x, 0) / hull.length;
+    const cy = hull.reduce((sum, p) => sum + p.y, 0) / hull.length;
+    const expanded = hull.map((p) => clampPointToScreenEllipse({
+      x: p.x + (p.x - cx) * 0.4,
+      y: p.y + (p.y - cy) * 0.4
+    }, fallbackBox));
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    for (const p of expanded) {
+      minX = Math.min(minX, p.x);
+      minY = Math.min(minY, p.y);
+      maxX = Math.max(maxX, p.x);
+      maxY = Math.max(maxY, p.y);
+    }
+    const box = { left: minX, top: minY, width: Math.max(8, maxX - minX), height: Math.max(8, maxY - minY) };
+    return { box, localPoints: expanded.map((p) => ({ x: p.x - box.left, y: p.y - box.top })) };
+  }
+  return { box: fallbackBox, localPoints: null };
+}
+
+export function clampPointToScreenEllipse(
+  point: GraphScreenPoint,
+  box: { left: number; top: number; width: number; height: number }
+): GraphScreenPoint {
+  const cx = box.left + box.width / 2;
+  const cy = box.top + box.height / 2;
+  const rx = Math.max(1, box.width / 2);
+  const ry = Math.max(1, box.height / 2);
+  const dx = point.x - cx;
+  const dy = point.y - cy;
+  const distance = Math.hypot(dx / rx, dy / ry);
+  if (distance <= 1) return point;
+  return {
+    x: cx + dx / distance,
+    y: cy + dy / distance
+  };
+}
+
+export function convexHull2d(points: GraphScreenPoint[]): GraphScreenPoint[] {
+  if (points.length < 3) return points.slice();
+  const pts = points.slice().sort((a, b) => a.x - b.x || a.y - b.y);
+  const cross = (o: GraphScreenPoint, a: GraphScreenPoint, b: GraphScreenPoint): number =>
+    (a.x - o.x) * (b.y - o.y) - (a.y - o.y) * (b.x - o.x);
+  const lower: GraphScreenPoint[] = [];
+  for (const p of pts) {
+    while (lower.length >= 2 && cross(lower[lower.length - 2], lower[lower.length - 1], p) <= 0) lower.pop();
+    lower.push(p);
+  }
+  const upper: GraphScreenPoint[] = [];
+  for (let i = pts.length - 1; i >= 0; i -= 1) {
+    const p = pts[i];
+    while (upper.length >= 2 && cross(upper[upper.length - 2], upper[upper.length - 1], p) <= 0) upper.pop();
+    upper.push(p);
+  }
+  lower.pop();
+  upper.pop();
+  return lower.concat(upper);
+}

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

@@ -0,0 +1,238 @@
+import { GRAPH_WORLD_SIZE } from "./geometry";
+
+export interface CommunityWashPoint {
+  x: number;
+  y: number;
+}
+
+export interface CommunityWashNodeLike {
+  point: CommunityWashPoint;
+}
+
+export interface CommunityWash {
+  cx: number;
+  cy: number;
+  rx: number;
+  ry: number;
+  opacity: number;
+}
+
+export interface CommunityWashOptions {
+  minRadiusX?: number;
+  minRadiusY?: number;
+  paddingX?: number;
+  paddingY?: number;
+  maxRadiusX?: number;
+  maxRadiusY?: number;
+}
+
+interface CommunityWashBounds {
+  minX: number;
+  maxX: number;
+  minY: number;
+  maxY: number;
+}
+
+interface CommunityWashCore {
+  core: CommunityWashPoint[];
+  outliers: CommunityWashPoint[];
+}
+
+const DEFAULT_MIN_RADIUS_X = 54;
+const DEFAULT_MIN_RADIUS_Y = 36;
+const DEFAULT_PADDING_X = 46;
+const DEFAULT_PADDING_Y = 34;
+const COMMUNITY_WASH_CORE_EXACT_LIMIT = 240;
+export const DEFAULT_COMMUNITY_WASH_MAX_RADIUS_X = GRAPH_WORLD_SIZE.width * 0.19;
+export const DEFAULT_COMMUNITY_WASH_MAX_RADIUS_Y = round(GRAPH_WORLD_SIZE.height * 0.21);
+
+export function computeCommunityWash(nodes: CommunityWashNodeLike[], options: CommunityWashOptions = {}): CommunityWash | null {
+  if (!nodes.length) return null;
+  const points = nodes.map((node) => normalizePoint(node.point));
+  const policy = normalizeCommunityWashOptions(options);
+  const { core, outliers } = communityWashCore(points);
+  const base = cappedBounds(
+    paddedBounds(core, policy),
+    policy.maxRadiusX * 2,
+    policy.maxRadiusY * 2
+  );
+  const finalBounds = outliers.length
+    ? expandBoundsTowardOutliers(base, paddedBounds([...core, ...outliers], policy), policy)
+    : base;
+
+  return {
+    cx: round((finalBounds.minX + finalBounds.maxX) / 2),
+    cy: round((finalBounds.minY + finalBounds.maxY) / 2),
+    rx: round((finalBounds.maxX - finalBounds.minX) / 2),
+    ry: round((finalBounds.maxY - finalBounds.minY) / 2),
+    opacity: nodes.length > 1 ? 0.11 : 0.06
+  };
+}
+
+function normalizeCommunityWashOptions(options: CommunityWashOptions): Required<CommunityWashOptions> {
+  return {
+    minRadiusX: finitePositiveNumber(options.minRadiusX, DEFAULT_MIN_RADIUS_X),
+    minRadiusY: finitePositiveNumber(options.minRadiusY, DEFAULT_MIN_RADIUS_Y),
+    paddingX: finitePositiveNumber(options.paddingX, DEFAULT_PADDING_X),
+    paddingY: finitePositiveNumber(options.paddingY, DEFAULT_PADDING_Y),
+    maxRadiusX: finitePositiveNumber(options.maxRadiusX, DEFAULT_COMMUNITY_WASH_MAX_RADIUS_X),
+    maxRadiusY: finitePositiveNumber(options.maxRadiusY, DEFAULT_COMMUNITY_WASH_MAX_RADIUS_Y)
+  };
+}
+
+function communityWashCore(points: CommunityWashPoint[]): CommunityWashCore {
+  if (points.length <= 3) return { core: points, outliers: [] };
+  const scoredPoints = points.length > COMMUNITY_WASH_CORE_EXACT_LIMIT
+    ? representativeWashPoints(points, COMMUNITY_WASH_CORE_EXACT_LIMIT)
+    : points;
+  const scored = scoredPoints
+    .map((point) => ({
+      point,
+      neighborScore: nearestNeighborScore(point, scoredPoints)
+    }))
+    .sort((left, right) => left.neighborScore - right.neighborScore);
+  const coreCount = Math.max(2, Math.ceil(scored.length * 0.75));
+  const core = scored.slice(0, coreCount);
+  const outliers = scored.slice(coreCount);
+  const coreMax = Math.max(...core.map((item) => item.neighborScore));
+  const outlierMin = Math.min(...outliers.map((item) => item.neighborScore));
+  if (!Number.isFinite(outlierMin) || outlierMin <= Math.max(180, coreMax * 2.5)) {
+    return { core: points, outliers: [] };
+  }
+  return {
+    core: core.map((item) => item.point),
+    outliers: outliers.map((item) => item.point)
+  };
+}
+
+function representativeWashPoints(points: CommunityWashPoint[], limit: number): CommunityWashPoint[] {
+  if (points.length <= limit) return points;
+  const lastIndex = points.length - 1;
+  const representatives: CommunityWashPoint[] = [];
+  const seen = new Set<number>();
+  for (let index = 0; index < limit; index += 1) {
+    const sourceIndex = Math.round(index * lastIndex / Math.max(1, limit - 1));
+    if (seen.has(sourceIndex)) continue;
+    seen.add(sourceIndex);
+    representatives.push(points[sourceIndex]);
+  }
+  return representatives;
+}
+
+function paddedBounds(points: CommunityWashPoint[], options: Required<CommunityWashOptions>): CommunityWashBounds {
+  const minX = Math.min(...points.map((point) => point.x));
+  const maxX = Math.max(...points.map((point) => point.x));
+  const minY = Math.min(...points.map((point) => point.y));
+  const maxY = Math.max(...points.map((point) => point.y));
+  const cx = (minX + maxX) / 2;
+  const cy = (minY + maxY) / 2;
+  const rx = Math.max(options.minRadiusX, (maxX - minX) / 2 + options.paddingX);
+  const ry = Math.max(options.minRadiusY, (maxY - minY) / 2 + options.paddingY);
+  return {
+    minX: cx - rx,
+    maxX: cx + rx,
+    minY: cy - ry,
+    maxY: cy + ry
+  };
+}
+
+function expandBoundsTowardOutliers(
+  base: CommunityWashBounds,
+  desired: CommunityWashBounds,
+  options: Required<CommunityWashOptions>
+): CommunityWashBounds {
+  const horizontal = expandAxis(base.minX, base.maxX, desired.minX, desired.maxX, options.maxRadiusX * 2);
+  const vertical = expandAxis(base.minY, base.maxY, desired.minY, desired.maxY, options.maxRadiusY * 2);
+  return {
+    minX: horizontal.min,
+    maxX: horizontal.max,
+    minY: vertical.min,
+    maxY: vertical.max
+  };
+}
+
+function expandAxis(
+  baseMin: number,
+  baseMax: number,
+  desiredMin: number,
+  desiredMax: number,
+  maxSize: number
+): { min: number; max: number } {
+  const base = cappedAxis(baseMin, baseMax, maxSize);
+  const leftExtra = Math.max(0, base.min - desiredMin);
+  const rightExtra = Math.max(0, desiredMax - base.max);
+  const available = Math.max(0, maxSize - (base.max - base.min));
+  const totalExtra = leftExtra + rightExtra;
+  if (totalExtra <= 0 || available <= 0) return base;
+  const used = Math.min(available, totalExtra);
+  return {
+    min: base.min - used * (leftExtra / totalExtra),
+    max: base.max + used * (rightExtra / totalExtra)
+  };
+}
+
+function cappedBounds(bounds: CommunityWashBounds, maxWidth: number, maxHeight: number): CommunityWashBounds {
+  const horizontal = cappedAxis(bounds.minX, bounds.maxX, maxWidth);
+  const vertical = cappedAxis(bounds.minY, bounds.maxY, maxHeight);
+  return {
+    minX: horizontal.min,
+    maxX: horizontal.max,
+    minY: vertical.min,
+    maxY: vertical.max
+  };
+}
+
+function cappedAxis(min: number, max: number, maxSize: number): { min: number; max: number } {
+  const size = max - min;
+  if (size <= maxSize) return { min, max };
+  const center = (min + max) / 2;
+  const radius = maxSize / 2;
+  return {
+    min: center - radius,
+    max: center + radius
+  };
+}
+
+function nearestNeighborScore(point: CommunityWashPoint, points: CommunityWashPoint[]): number {
+  let nearest = Number.POSITIVE_INFINITY;
+  let secondNearest = Number.POSITIVE_INFINITY;
+  let neighborCount = 0;
+  for (const candidate of points) {
+    if (candidate === point) continue;
+    neighborCount += 1;
+    const candidateDistance = distance(point, candidate);
+    if (candidateDistance < nearest) {
+      secondNearest = nearest;
+      nearest = candidateDistance;
+    } else if (candidateDistance < secondNearest) {
+      secondNearest = candidateDistance;
+    }
+  }
+  if (neighborCount === 0) return 0;
+  if (neighborCount === 1) return nearest;
+  return (nearest + secondNearest) / 2;
+}
+
+function distance(left: CommunityWashPoint, right: CommunityWashPoint): number {
+  return Math.hypot(right.x - left.x, right.y - left.y);
+}
+
+function normalizePoint(point: CommunityWashPoint): CommunityWashPoint {
+  return {
+    x: finiteNumber(point.x, 0),
+    y: finiteNumber(point.y, 0)
+  };
+}
+
+function finitePositiveNumber(value: unknown, fallback: number): number {
+  const numeric = finiteNumber(value, fallback);
+  return numeric > 0 ? numeric : fallback;
+}
+
+function finiteNumber(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+function round(value: number): number {
+  return Math.round(value * 1000) / 1000;
+}

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

@@ -0,0 +1,19 @@
+import type { RenderableCommunity } from "./model";
+
+const SVG_NS = "http://www.w3.org/2000/svg";
+
+export function createCommunityWashElement(ownerDocument: Document, community: RenderableCommunity): SVGEllipseElement | null {
+  if (!community.wash) return null;
+  const ellipse = ownerDocument.createElementNS(SVG_NS, "ellipse");
+  ellipse.setAttribute("class", "community-wash");
+  ellipse.setAttribute("cx", String(community.wash.cx));
+  ellipse.setAttribute("cy", String(community.wash.cy));
+  ellipse.setAttribute("rx", String(community.wash.rx));
+  ellipse.setAttribute("ry", String(community.wash.ry));
+  ellipse.setAttribute("fill", community.color);
+  ellipse.setAttribute("opacity", String(community.wash.opacity));
+  ellipse.dataset.communityId = community.id;
+  ellipse.dataset.boundaryCertainty = community.boundaryCertainty;
+  ellipse.style.cursor = "pointer";
+  return ellipse;
+}

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

@@ -0,0 +1,14 @@
+import type {
+  GraphRenderer,
+  GraphRendererOptions,
+  StaticGraphRenderer,
+  StaticRendererOptions
+} from "./index";
+
+type AssertAssignable<T extends true> = T;
+type SameType<Left, Right> = (<T>() => T extends Left ? 1 : 2) extends (<T>() => T extends Right ? 1 : 2)
+  ? true
+  : false;
+
+type _StaticRendererAlias = AssertAssignable<SameType<StaticGraphRenderer, GraphRenderer>>;
+type _StaticRendererOptionsAlias = AssertAssignable<SameType<StaticRendererOptions, GraphRendererOptions>>;