@ltm-blueverse/alpha-semantic-hub 0.7.0

package/explorer/src/workspaces/GraphWorkspace/plugins/neighborhoodPanelPlugin.tsx

@@ -0,0 +1,231 @@
+import type { CSSProperties } from "react";
+
+import type { GraphPlugin } from "./types";
+
+const NEIGHBORHOOD_PANEL_ID = "neighborhood-panel";
+const MAX_NEIGHBORS = 10;
+
+function maxWeightBetween(graphRef: any, sourceId: string, targetId: string): number {
+  let weight = 0;
+  graphRef.forEachDirectedEdge(sourceId, targetId, (_edgeId: string, attrs: { weight?: number }) => {
+    weight = Math.max(weight, Number(attrs.weight ?? 0));
+  });
+  return weight;
+}
+
+function formatNeighborMeta(neighbor: { nodeType: string; degree: number; weight: number }) {
+  const parts = [neighbor.nodeType, `degree ${neighbor.degree}`];
+  if (neighbor.weight > 0) {
+    parts.push(`weight ${neighbor.weight.toFixed(2)}`);
+  }
+  return parts.join(" · ");
+}
+
+export const neighborhoodPanelPlugin: GraphPlugin = {
+  id: "neighborhood-panel",
+  mount: () => {},
+  unmount: () => {},
+  onStateChange: () => {},
+  toolbarItems: (context) => [
+    {
+      id: "neighborhood-toggle",
+      label: "Neighbors",
+      title: "Toggle neighborhood panel",
+      active: context.isPanelOpen(NEIGHBORHOOD_PANEL_ID),
+      order: 30,
+      onClick: () => context.dispatchAction({ type: "togglePanel", panelId: NEIGHBORHOOD_PANEL_ID }),
+    },
+  ],
+  renderPanel: (context) => {
+    if (!context.isPanelOpen(NEIGHBORHOOD_PANEL_ID)) {
+      return null;
+    }
+
+    const selected = context.getSelectedNodeState();
+    const displayState = context.getDisplayState();
+    if (!selected) {
+      return {
+        id: NEIGHBORHOOD_PANEL_ID,
+        title: "Neighborhood",
+        placement: "bottom",
+        order: 20,
+        defaultOpen: false,
+        preferredWidth: 360,
+        preferredHeight: 260,
+        content: <div style={emptyTextStyle}>Select a node to inspect its local neighborhood.</div>,
+      };
+    }
+
+    const neighbors = context.graph
+      .neighbors(selected.id)
+      .map((neighborId) => {
+        const attrs = context.graph.getNodeAttributes(neighborId);
+        const weight = Math.max(
+          maxWeightBetween(context.graph, selected.id, neighborId),
+          maxWeightBetween(context.graph, neighborId, selected.id),
+        );
+        return {
+          id: neighborId,
+          label: String(attrs.label || neighborId),
+          nodeType: String(attrs.nodeType || "Entity"),
+          color: String(attrs.baseColor || attrs.color || context.theme.palette.semantic[0]),
+          weight,
+          degree: context.graph.degree(neighborId),
+        };
+      })
+      .sort((left, right) => {
+        if (right.weight !== left.weight) {
+          return right.weight - left.weight;
+        }
+        if (right.degree !== left.degree) {
+          return right.degree - left.degree;
+        }
+        return left.label.localeCompare(right.label);
+      })
+      .slice(0, MAX_NEIGHBORS);
+    const hiddenNeighborCount = displayState.selectedCollapsedNeighborIds.length;
+    const aggregatedEdgeCount = context.displayGraph
+      .edges()
+      .map((edgeId) => context.displayGraph.getEdgeAttributes(edgeId) as { isAggregated?: boolean })
+      .filter((attrs) => attrs.isAggregated).length;
+
+    return {
+      id: NEIGHBORHOOD_PANEL_ID,
+      title: "Neighborhood",
+      placement: "bottom",
+      order: 20,
+      defaultOpen: false,
+      preferredWidth: 360,
+      preferredHeight: 260,
+      content: (
+        <div style={panelBodyStyle}>
+          <div style={panelEyebrowStyle}>{selected.label}</div>
+          <div style={summaryStyle}>
+            {selected.neighborCount.toLocaleString()} direct neighbors in the full graph
+          </div>
+          <div style={{ display: "flex", gap: 8, flexWrap: "wrap" }}>
+            <button
+              type="button"
+              onClick={() => context.dispatchAction({ type: "collapseNeighborhood" })}
+              disabled={!selected.canCollapseNeighborhood || selected.isNeighborhoodCollapsed}
+              style={controlButtonStyle}
+            >
+              Collapse Neighborhood
+            </button>
+            <button
+              type="button"
+              onClick={() => context.dispatchAction({ type: "expandNeighborhood" })}
+              disabled={!selected.isNeighborhoodCollapsed}
+              style={controlButtonStyle}
+            >
+              Expand Neighborhood
+            </button>
+          </div>
+          {hiddenNeighborCount > 0 ? (
+            <div style={summaryStyle}>
+              {hiddenNeighborCount.toLocaleString()} lower-priority neighbors are collapsed in the current view.
+            </div>
+          ) : null}
+          {aggregatedEdgeCount > 0 ? (
+            <div style={summaryStyle}>
+              {aggregatedEdgeCount.toLocaleString()} aggregated structural bundle{aggregatedEdgeCount === 1 ? "" : "s"} visible.
+            </div>
+          ) : null}
+          {neighbors.length ? (
+            <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
+              {neighbors.map((neighbor) => (
+                <button
+                  key={neighbor.id}
+                  type="button"
+                  onClick={() => context.dispatchAction({ type: "selectNode", nodeId: neighbor.id })}
+                  style={neighborButtonStyle}
+                >
+                  <span
+                    style={{
+                      ...swatchStyle,
+                      background: neighbor.color,
+                      boxShadow: `0 0 16px ${neighbor.color}40`,
+                    }}
+                  />
+                  <div style={{ minWidth: 0, flex: 1, textAlign: "left" }}>
+                    <div style={rowTitleStyle}>{neighbor.label}</div>
+                    <div style={rowMetaStyle}>{formatNeighborMeta(neighbor)}</div>
+                  </div>
+                </button>
+              ))}
+            </div>
+          ) : (
+            <div style={emptyTextStyle}>No direct neighbors are available for this node.</div>
+          )}
+        </div>
+      ),
+    };
+  },
+};
+
+const panelBodyStyle: CSSProperties = {
+  display: "flex",
+  flexDirection: "column",
+  gap: 12,
+};
+
+const panelEyebrowStyle: CSSProperties = {
+  color: "#fff1f3",
+  fontSize: 14,
+  fontWeight: 700,
+};
+
+const summaryStyle: CSSProperties = {
+  color: "#c99aa3",
+  fontSize: 12,
+  lineHeight: 1.5,
+};
+
+const neighborButtonStyle: CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  gap: 10,
+  width: "100%",
+  padding: "8px 10px",
+  background: "rgba(255,255,255,0.025)",
+  border: "1px solid rgba(255,255,255,0.06)",
+  borderRadius: 12,
+  cursor: "pointer",
+};
+
+const controlButtonStyle: CSSProperties = {
+  padding: "7px 10px",
+  background: "rgba(255,255,255,0.03)",
+  border: "1px solid rgba(255,255,255,0.08)",
+  borderRadius: 10,
+  color: "#dce7f4",
+  cursor: "pointer",
+  fontSize: 12,
+};
+
+const swatchStyle: CSSProperties = {
+  width: 10,
+  height: 10,
+  borderRadius: 999,
+  flexShrink: 0,
+};
+
+const rowTitleStyle: CSSProperties = {
+  color: "#fff1f3",
+  fontSize: 13,
+  fontWeight: 600,
+  overflow: "hidden",
+  textOverflow: "ellipsis",
+  whiteSpace: "nowrap",
+};
+
+const rowMetaStyle: CSSProperties = {
+  color: "#c99aa3",
+  fontSize: 12,
+};
+
+const emptyTextStyle: CSSProperties = {
+  color: "#c99aa3",
+  fontSize: 12,
+  lineHeight: 1.5,
+};

package/explorer/src/workspaces/GraphWorkspace/plugins/temporalOverlayPlugin.tsx

@@ -0,0 +1,142 @@
+import type { CSSProperties } from "react";
+
+import type { GraphPlugin } from "./types";
+
+const TEMPORAL_PANEL_ID = "temporal-panel";
+
+function formatTemporalLabel(value: Date | null) {
+  if (!value) {
+    return "No time selected";
+  }
+  return `${value.getFullYear()}/${String(value.getMonth() + 1).padStart(2, "0")}`;
+}
+
+export const temporalOverlayPlugin: GraphPlugin = {
+  id: "temporal-overlay",
+  mount: () => {},
+  unmount: () => {},
+  onStateChange: () => {},
+  toolbarItems: (context) => [
+    {
+      id: "temporal-toggle",
+      label: "Temporal",
+      title: "Toggle temporal context panel",
+      active: context.isPanelOpen(TEMPORAL_PANEL_ID),
+      order: 40,
+      onClick: () => context.dispatchAction({ type: "togglePanel", panelId: TEMPORAL_PANEL_ID }),
+    },
+  ],
+  renderOverlay: (context) => {
+    const temporal = context.getTemporalState();
+    if (!temporal?.currentTime) {
+      return null;
+    }
+
+    const label = formatTemporalLabel(temporal.currentTime);
+    return {
+      id: "temporal-overlay-chip",
+      layer: 1,
+      order: 10,
+      element: (
+        <div
+          style={{
+            position: "absolute",
+            left: 140,
+            bottom: 26,
+            display: "inline-flex",
+            alignItems: "center",
+            gap: 10,
+            padding: "8px 12px",
+            borderRadius: 999,
+            border: "1px solid rgba(255, 107, 129, 0.18)",
+            background: "linear-gradient(135deg, rgba(6, 15, 27, 0.88), rgba(11, 22, 39, 0.76))",
+            boxShadow: "0 12px 30px rgba(0, 0, 0, 0.28)",
+            color: "#ffdfe4",
+            fontSize: 11,
+            letterSpacing: "0.05em",
+            textTransform: "uppercase",
+            pointerEvents: "none",
+          }}
+        >
+          <span style={{ color: "#7fc6ff", fontWeight: 700 }}>Temporal</span>
+          <span>{label}</span>
+          {typeof temporal.activeNodeCount === "number" ? (
+            <span style={{ color: "#c99aa3" }}>{temporal.activeNodeCount.toLocaleString()} active</span>
+          ) : null}
+        </div>
+      ),
+    };
+  },
+  renderPanel: (context) => {
+    if (!context.isPanelOpen(TEMPORAL_PANEL_ID)) {
+      return null;
+    }
+
+    const temporal = context.getTemporalState();
+    return {
+      id: TEMPORAL_PANEL_ID,
+      title: "Temporal Context",
+      placement: "bottom",
+      order: 30,
+      defaultOpen: false,
+      preferredWidth: 320,
+      preferredHeight: 220,
+      content: (
+        <div style={panelBodyStyle}>
+          <div style={panelEyebrowStyle}>Current scrubber state</div>
+          <div style={detailRowStyle}>
+            <span style={detailLabelStyle}>Current</span>
+            <span style={detailValueStyle}>{formatTemporalLabel(temporal?.currentTime ?? null)}</span>
+          </div>
+          <div style={detailRowStyle}>
+            <span style={detailLabelStyle}>Bounds</span>
+            <span style={detailValueStyle}>
+              {(temporal?.minDate ?? "1970")} → {(temporal?.maxDate ?? "now")}
+            </span>
+          </div>
+          <div style={detailRowStyle}>
+            <span style={detailLabelStyle}>Active nodes</span>
+            <span style={detailValueStyle}>
+              {typeof temporal?.activeNodeCount === "number" ? temporal.activeNodeCount.toLocaleString() : "All"}
+            </span>
+          </div>
+        </div>
+      ),
+    };
+  },
+};
+
+const panelBodyStyle: CSSProperties = {
+  display: "flex",
+  flexDirection: "column",
+  gap: 10,
+};
+
+const panelEyebrowStyle: CSSProperties = {
+  color: "#c99aa3",
+  fontSize: 11,
+  fontWeight: 700,
+  letterSpacing: "0.08em",
+  textTransform: "uppercase",
+};
+
+const detailRowStyle: CSSProperties = {
+  display: "flex",
+  justifyContent: "space-between",
+  gap: 16,
+  padding: "8px 10px",
+  borderRadius: 12,
+  border: "1px solid rgba(255,255,255,0.06)",
+  background: "rgba(255,255,255,0.025)",
+};
+
+const detailLabelStyle: CSSProperties = {
+  color: "#c99aa3",
+  fontSize: 12,
+};
+
+const detailValueStyle: CSSProperties = {
+  color: "#fff1f3",
+  fontSize: 12,
+  fontWeight: 600,
+};

package/explorer/src/workspaces/GraphWorkspace/plugins/types.ts

@@ -0,0 +1,106 @@
+import type { ReactNode } from "react";
+import type Graph from "graphology";
+
+import { graph, type EdgeAttributes, type NodeAttributes } from "../../../store/graphStore";
+import type { GraphTheme } from "../graphTheme";
+import type { GraphSceneRuntime } from "../scene";
+import type {
+  GraphAnalyticsSnapshot,
+  GraphDisplayStateSnapshot,
+  GraphDiagnosticsSnapshot,
+  GraphEffectsState,
+  GraphEffectToggle,
+  GraphInteractionState,
+  GraphLoadSummary,
+  GraphSelectedNodeState,
+  GraphTemporalState,
+  GraphLayoutViewMode,
+} from "../types";
+
+export type { GraphTemporalState } from "../types";
+
+export type GraphPluginId = string;
+export type GraphPluginPanelPlacement = "side" | "bottom";
+
+export interface GraphInspectorState {
+  selectedNodeId: string | null;
+  ownsSelectionDetails: boolean;
+}
+
+export type GraphPluginActionRequest =
+  | { type: "fitView" }
+  | { type: "focusNode"; nodeId: string }
+  | { type: "selectNode"; nodeId: string }
+  | { type: "setViewMode"; viewMode: GraphLayoutViewMode }
+  | { type: "enterLocalGraph"; nodeId: string }
+  | { type: "collapseNeighborhood" }
+  | { type: "expandNeighborhood" }
+  | { type: "toggleEffect"; effect: GraphEffectToggle }
+  | { type: "setEffect"; effect: GraphEffectToggle; enabled: boolean }
+  | { type: "togglePanel"; panelId: string }
+  | { type: "openPanel"; panelId: string }
+  | { type: "closePanel"; panelId: string };
+
+export interface GraphPluginToolbarItem {
+  id: string;
+  label: string;
+  title?: string;
+  active?: boolean;
+  order?: number;
+  onClick: () => void;
+}
+
+export interface GraphPluginPanelDescriptor {
+  id: string;
+  title: string;
+  placement: GraphPluginPanelPlacement;
+  order?: number;
+  defaultOpen?: boolean;
+  preferredHeight?: number;
+  preferredWidth?: number;
+  content: ReactNode;
+}
+
+export interface GraphPluginOverlayDescriptor {
+  id: string;
+  layer?: number;
+  order?: number;
+  element: ReactNode;
+}
+
+export interface GraphPluginContext {
+  readonly scene: GraphSceneRuntime | null;
+  readonly graph: typeof graph | Graph<NodeAttributes, EdgeAttributes>;
+  readonly displayGraph: typeof graph | Graph<NodeAttributes, EdgeAttributes>;
+  readonly theme: GraphTheme;
+  getInteractionState: () => GraphInteractionState;
+  getSelectedNodeState: () => GraphSelectedNodeState | null;
+  getInspectorState: () => GraphInspectorState;
+  getGraphSummary: () => GraphLoadSummary | null;
+  getTemporalState: () => GraphTemporalState | null;
+  getEffectsState: () => GraphEffectsState;
+  getDiagnosticsSnapshot: () => GraphDiagnosticsSnapshot | null;
+  getAnalyticsSnapshot: () => GraphAnalyticsSnapshot | null;
+  getDisplayState: () => GraphDisplayStateSnapshot;
+  isPanelOpen: (panelId: string) => boolean;
+  dispatchAction: (action: GraphPluginActionRequest) => void;
+}
+
+export interface GraphPlugin {
+  id: GraphPluginId;
+  mount: (context: GraphPluginContext) => void;
+  unmount: (context: GraphPluginContext) => void;
+  onStateChange: (context: GraphPluginContext, interactionState: GraphInteractionState) => void;
+  renderOverlay?: (
+    context: GraphPluginContext,
+  ) => GraphPluginOverlayDescriptor | GraphPluginOverlayDescriptor[] | null;
+  renderPanel?: (
+    context: GraphPluginContext,
+  ) => GraphPluginPanelDescriptor | GraphPluginPanelDescriptor[] | null;
+  toolbarItems?: (context: GraphPluginContext) => GraphPluginToolbarItem[];
+}
+
+export interface GraphPluginRegistryEntry {
+  plugin: GraphPlugin;
+  enabled?: boolean;
+}

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

@@ -0,0 +1,50 @@
+import type { EdgeAttributes } from "../../store/graphStore";
+import { curveGroupForPair } from "../../store/edgePairKeys.js";
+import { GRAPH_THEME } from "./graphTheme";
+
+export type RealtimeEdgePayload = {
+  id: string;
+  familyId?: string;
+  source_id: string;
+  target_id: string;
+  type?: string;
+  weight?: number;
+  properties?: Record<string, unknown>;
+};
+
+export function buildRealtimeEdgeAttributes(
+  payload: RealtimeEdgePayload,
+  options: { isBidirectional: boolean; isSmallGraph: boolean },
+): EdgeAttributes {
+  const properties = payload.properties || {};
+  const isInferred = Boolean(properties.inferred);
+  const baseColor = isInferred ? GRAPH_THEME.palette.accent.path : GRAPH_THEME.palette.muted.edgeStructure;
+
+  return {
+    edgeId: payload.id,
+    familyId: payload.familyId || payload.id,
+    sourceId: payload.source_id,
+    targetId: payload.target_id,
+    weight: Number(payload.weight ?? 1),
+    edgeType: payload.type || "related_to",
+    properties,
+    size: 1,
+    baseSize: 1,
+    color: baseColor,
+    baseColor,
+    mutedColor: GRAPH_THEME.palette.muted.edgeOverview,
+    visualPriority: isInferred ? 0.95 : 0.5,
+    isBidirectional: options.isBidirectional,
+    edgeFamily: isInferred ? "path" : options.isBidirectional ? "bidirectional" : "line",
+    curveGroup: options.isBidirectional ? curveGroupForPair(payload.source_id, payload.target_id) : null,
+    type: "line",
+    edgeVariant: isInferred ? "pathSignal" : options.isBidirectional ? "bidirectionalCurve" : "directional",
+    arrowVisibilityPolicy: isInferred ? "always" : "contextual",
+    relationshipStrength: isInferred ? 0.95 : 0.52,
+    isParallelPair: false,
+    parallelIndex: 0,
+    parallelCount: 1,
+    familySize: 1,
+    isSmallGraph: options.isSmallGraph,
+  };
+}

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

@@ -0,0 +1,79 @@
+import type { ForwardRefExoticComponent, ReactNode, RefAttributes } from "react";
+import type Graph from "graphology";
+
+import { graph, type EdgeAttributes, type NodeAttributes } from "../../store/graphStore";
+import type {
+  GraphAnalyticsSnapshot,
+  GraphCameraState,
+  GraphDistanceVisualState,
+  GraphDisplayMeta,
+  GraphDisplayStateSnapshot,
+  GraphEffectsState,
+  GraphInteractionState,
+  GraphLayoutSource,
+  GraphLayoutStatus,
+  GraphRuntimeDiagnosticsSnapshot,
+  GraphTemporalState,
+  GraphViewMode,
+} from "./types";
+
+export type GraphSceneGraph = typeof graph | Graph<NodeAttributes, EdgeAttributes>;
+export type GraphSceneRenderer = "sigma";
+
+export interface GraphSceneRuntime {
+  renderer: GraphSceneRenderer;
+  scene: unknown;
+  graph: GraphSceneGraph;
+  displayGraph: GraphSceneGraph;
+  graphVersion: number;
+  layoutMode?: GraphDisplayMeta["layoutMode"];
+  requestRender: () => void;
+  getCameraState: () => GraphCameraState | null;
+}
+
+export interface GraphSceneEventMap {
+  onNodeSelect?: (nodeId: string) => void;
+  onEdgeSelect?: (edgeId: string) => void;
+  onInteractionStateChange?: (interactionState: GraphInteractionState) => void;
+  onCameraStateChange?: (cameraState: GraphCameraState) => void;
+  onDiagnosticsChange?: (diagnostics: GraphRuntimeDiagnosticsSnapshot) => void;
+  onAnalyticsChange?: (analytics: GraphAnalyticsSnapshot | null) => void;
+  onRuntimeChange?: (runtime: GraphSceneRuntime | null) => void;
+}
+
+export interface GraphSceneProps extends GraphSceneEventMap {
+  graphVersion: number;
+  graphReady: boolean;
+  displayGraph: GraphSceneGraph;
+  displayMeta: GraphDisplayMeta;
+  displayState?: GraphDisplayStateSnapshot;
+  selectedNodeId: string;
+  focusedNodeId: string;
+  selectedEdgeId: string;
+  activePath?: string[];
+  activePathEdgeIds?: string[];
+  distanceVisualState?: GraphDistanceVisualState;
+  effectsState: GraphEffectsState;
+  temporalState?: GraphTemporalState | null;
+  isLayoutRunning: boolean;
+  onLayoutRunningChange?: (running: boolean) => void;
+  layoutSource?: GraphLayoutSource;
+  onLayoutStatusChange?: (status: GraphLayoutStatus) => void;
+  viewMode: GraphViewMode;
+  className?: string;
+  showFitViewButton?: boolean;
+  pluginOverlays?: ReactNode[];
+}
+
+export interface GraphSceneHandle {
+  fitView: () => void;
+  focusNode: (nodeId: string) => void;
+  zoomIn: () => void;
+  zoomOut: () => void;
+  getRuntime: () => GraphSceneRuntime | null;
+  setLayoutRunning?: (running: boolean) => void;
+}
+
+export type GraphSceneAdapter = ForwardRefExoticComponent<
+  GraphSceneProps & RefAttributes<GraphSceneHandle>
+>;