@ltm-blueverse/alpha-semantic-hub 0.7.0

package/explorer/src/workspaces/GraphWorkspace/graphColorLegend.ts

@@ -0,0 +1,36 @@
+import type Graph from "graphology";
+
+import type { NodeAttributes } from "../../store/graphStore";
+import { GRAPH_THEME, type GraphTheme } from "./graphTheme";
+
+export type GraphColorLegendItem = {
+  id: string;
+  group: string;
+  color: string;
+  count: number;
+};
+
+/** Normal semantic color, before selection, distance, or zoom styling. */
+export function getSemanticNodeColor(
+  attrs: Pick<NodeAttributes, "baseColor" | "color">,
+  theme: GraphTheme = GRAPH_THEME,
+) {
+  return String(attrs.baseColor || attrs.color || theme.palette.semantic[0]);
+}
+
+/** Use the displayed graph so synthetic groups and filtered views keep their colors. */
+export function buildGraphColorLegend(graph: Graph, theme: GraphTheme = GRAPH_THEME): GraphColorLegendItem[] {
+  const entries = new Map<string, GraphColorLegendItem>();
+  graph.forEachNode((_id, attrs) => {
+    if (attrs.hidden) return;
+    const group = String(attrs.semanticGroup || attrs.nodeType || "entity");
+    // Focused clones bake interaction colors into baseColor; keep those out of the semantic key.
+    const color = String(attrs.semanticBaseColor || getSemanticNodeColor(attrs as NodeAttributes, theme));
+    // A synthetic display node can share a semantic label with a different color.
+    const id = JSON.stringify([group, color]);
+    const current = entries.get(id);
+    if (current) current.count += 1;
+    else entries.set(id, { id, group, color, count: 1 });
+  });
+  return [...entries.values()].sort((a, b) => a.group.localeCompare(b.group) || a.color.localeCompare(b.color));
+}

package/explorer/src/workspaces/GraphWorkspace/graphConfig.ts

@@ -0,0 +1,102 @@
+export const GRAPH_THEME = {
+  background: {
+    canvas: "#050816",
+    shell: "#0A1021",
+    panel: "#10182C",
+    grid: "rgba(93, 124, 168, 0.08)",
+    vignette: "rgba(2, 4, 10, 0.88)",
+  },
+  nodes: {
+    palette: [
+      "#3CE7FF",
+      "#23D7C8",
+      "#5DA9FF",
+      "#9B6BFF",
+      "#FF4FD8",
+      "#FF9A3C",
+      "#B9FF3B",
+    ],
+    selected: "#FFC857",
+    selectedGlow: "rgba(255, 200, 87, 0.36)",
+    hoverGlow: "rgba(60, 231, 255, 0.32)",
+    border: "#07111C",
+    subduedAlpha: 0.1,
+  },
+  edges: {
+    baseColor: "rgba(126, 162, 214, 0.08)",
+    subduedColor: "rgba(126, 162, 214, 0.03)",
+    hoverColor: "rgba(94, 198, 255, 0.9)",
+    pathColor: "rgba(255, 192, 92, 0.95)",
+    focusColor: "rgba(175, 191, 255, 0.26)",
+  },
+  motion: {
+    hoverMs: 160,
+    cameraMs: 480,
+  },
+  thresholds: {
+    interactiveLayoutMaxNodes: 8000,
+    stagedLayoutMaxNodes: 25000,
+    focusNeighborCap: 18,
+    focusPrimaryLabels: 8,
+    particleEdgeCap: 32,
+  },
+} as const;
+
+export const FORCE_ATLAS_SETTINGS = {
+  getEdgeWeight: "weight",
+  settings: {
+    barnesHutOptimize: true,
+    barnesHutTheta: 0.6,
+    linLogMode: true,
+    outboundAttractionDistribution: true,
+    strongGravityMode: false,
+    gravity: 0.14,
+    scalingRatio: 4.8,
+    slowDown: 6,
+    edgeWeightInfluence: 1,
+    adjustSizes: true,
+  },
+} as const;
+
+export function clamp(min: number, value: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
+export function hashString(value: string): number {
+  let hash = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    hash = (hash << 5) - hash + value.charCodeAt(index);
+    hash |= 0;
+  }
+  return Math.abs(hash);
+}
+
+export function withAlpha(color: string | undefined, alpha: number): string {
+  if (!color) {
+    return `rgba(130, 145, 165, ${alpha})`;
+  }
+
+  if (color.startsWith("#")) {
+    const hex = color.slice(1);
+    const normalized = hex.length === 3
+      ? hex.split("").map((char) => `${char}${char}`).join("")
+      : hex;
+
+    if (normalized.length === 6) {
+      const red = Number.parseInt(normalized.slice(0, 2), 16);
+      const green = Number.parseInt(normalized.slice(2, 4), 16);
+      const blue = Number.parseInt(normalized.slice(4, 6), 16);
+      return `rgba(${red}, ${green}, ${blue}, ${alpha})`;
+    }
+  }
+
+  if (color.startsWith("rgba(")) {
+    return color.replace(/rgba\(([^)]+),\s*[\d.]+\)/, `rgba($1, ${alpha})`);
+  }
+
+  if (color.startsWith("rgb(")) {
+    return color.replace("rgb(", "rgba(").replace(")", `, ${alpha})`);
+  }
+
+  return `rgba(130, 145, 165, ${alpha})`;
+}

package/explorer/src/workspaces/GraphWorkspace/graphEntityShape.ts

@@ -0,0 +1,34 @@
+import type { GraphEntityShapeVariant } from "./graphTheme";
+
+export const ENTITY_SHAPE_ALIASES: Array<[GraphEntityShapeVariant, RegExp]> = [
+  ["biomolecule", /\b(gene|protein|enzyme|receptor|target|transcript|rna|dna|mirna|biomolecule|peptide)\b/i],
+  ["condition", /\b(disease|condition|phenotype|symptom|disorder|syndrome|diagnosis|pathology|trait)\b/i],
+  ["compound", /\b(drug|chemical|compound|metabolite|molecule|small[_\s-]?molecule|ligand|therapeutic|medication|substance)\b/i],
+  ["process", /\b(pathway|process|mechanism|function|ontology|biological[_\s-]?process|cellular[_\s-]?process|program|module)\b/i],
+];
+
+export function classifyEntityShape(
+  nodeType?: string,
+  semanticGroup?: string,
+  content?: string,
+  properties?: Record<string, unknown>,
+): GraphEntityShapeVariant {
+  const values = [
+    nodeType,
+    semanticGroup,
+    content,
+    String(properties?.type ?? ""),
+    String(properties?.category ?? ""),
+    String(properties?.label ?? ""),
+  ]
+    .filter((value) => typeof value === "string" && value.trim().length > 0)
+    .join(" ");
+
+  for (const [shape, pattern] of ENTITY_SHAPE_ALIASES) {
+    if (pattern.test(values)) {
+      return shape;
+    }
+  }
+
+  return "entity";
+}

package/explorer/src/workspaces/GraphWorkspace/graphLoading.ts

@@ -0,0 +1,84 @@
+import type { GraphLoadPhase, GraphLoadProgress, GraphLoadProgressKind, GraphLayoutSource, GraphLayoutState } from "./types";
+
+export const GRAPH_LOAD_STAGE_SEQUENCE: Exclude<GraphLoadPhase, "ready">[] = [
+  "bootstrapping",
+  "fetching_nodes",
+  "fetching_edges",
+  "computing_styling",
+  "hydrating_scene",
+  "stabilizing_layout",
+];
+
+export function getGraphLoadTitle(phase: GraphLoadPhase): string {
+  switch (phase) {
+    case "bootstrapping":
+      return "Preparing graph session";
+    case "fetching_nodes":
+      return "Loading nodes";
+    case "fetching_edges":
+      return "Loading relationships";
+    case "computing_styling":
+      return "Computing node styling";
+    case "hydrating_scene":
+      return "Hydrating graph scene";
+    case "stabilizing_layout":
+      return "Stabilizing layout";
+    case "ready":
+    default:
+      return "Graph ready";
+  }
+}
+
+export function getGraphLoadStageLabel(phase: Exclude<GraphLoadPhase, "ready">): string {
+  switch (phase) {
+    case "bootstrapping":
+      return "Prepare";
+    case "fetching_nodes":
+      return "Nodes";
+    case "fetching_edges":
+      return "Relations";
+    case "computing_styling":
+      return "Styling";
+    case "hydrating_scene":
+      return "Scene";
+    case "stabilizing_layout":
+      return "Layout";
+    default:
+      return "Stage";
+  }
+}
+
+export function createGraphLoadProgress(input: {
+  phase: GraphLoadPhase;
+  message: string;
+  progressKind: GraphLoadProgressKind;
+  loaded?: number | null;
+  total?: number | null;
+  nodesLoaded?: number;
+  nodesTotal?: number | null;
+  edgesLoaded?: number;
+  edgesTotal?: number | null;
+  showGraphBehind?: boolean;
+  layoutSource?: GraphLayoutSource;
+  layoutState?: GraphLayoutState;
+}): GraphLoadProgress {
+  const phaseIndex = GRAPH_LOAD_STAGE_SEQUENCE.indexOf(input.phase as Exclude<GraphLoadPhase, "ready">);
+
+  return {
+    phase: input.phase,
+    title: getGraphLoadTitle(input.phase),
+    message: input.message,
+    progressKind: input.progressKind,
+    loaded: input.loaded ?? null,
+    total: input.total ?? null,
+    nodesLoaded: input.nodesLoaded ?? 0,
+    nodesTotal: input.nodesTotal ?? null,
+    edgesLoaded: input.edgesLoaded ?? 0,
+    edgesTotal: input.edgesTotal ?? null,
+    showGraphBehind: input.showGraphBehind ?? false,
+    stageIndex: phaseIndex >= 0 ? phaseIndex + 1 : GRAPH_LOAD_STAGE_SEQUENCE.length,
+    stageCount: GRAPH_LOAD_STAGE_SEQUENCE.length,
+    layoutSource: input.layoutSource,
+    layoutState: input.layoutState,
+  };
+}