@ltm-blueverse/alpha-semantic-hub 0.7.0

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

@@ -0,0 +1,522 @@
+import type { CSSProperties } from "react";
+
+import { buildGraphColorLegend } from "../graphColorLegend";
+import type {
+  GraphAnalyticsSnapshot,
+  GraphDiagnosticsSnapshot,
+  GraphEffectAvailability,
+  GraphEffectToggle,
+} from "../types";
+import type { GraphPlugin } from "./types";
+
+const EFFECTS_PANEL_ID = "effects-panel";
+
+type EffectRowConfig = {
+  key: GraphEffectToggle;
+  label: string;
+  description: string;
+};
+
+const SCENE_EFFECT_ROWS: EffectRowConfig[] = [
+  {
+    key: "pathPulseEnabled",
+    label: "Path Pulse",
+    description: "Animated pulse on the active selected path.",
+  },
+  {
+    key: "pathFlowEnabled",
+    label: "Path Flow",
+    description: "Directional flow accents along the active selected path.",
+  },
+  {
+    key: "lensEnabled",
+    label: "Neighborhood Lens",
+    description: "Local emphasis around the hovered or selected node.",
+  },
+  {
+    key: "temporalEmphasisEnabled",
+    label: "Temporal Emphasis",
+    description: "Subtle glow around temporally relevant nodes in the active time window.",
+  },
+  {
+    key: "semanticRegionsEnabled",
+    label: "Semantic Regions",
+    description: "Quiet semantic hulls around the strongest visible topic clusters.",
+  },
+  {
+    key: "contoursEnabled",
+    label: "Contours",
+    description: "Low-contrast density halos around the strongest visible anchors.",
+  },
+  {
+    key: "edgeLabelsEnabled",
+    label: "Edge Labels",
+    description: "Draw the relationship type on graph edges. Off restores label-free edges on dense graphs.",
+  },
+  {
+    key: "legendEnabled",
+    label: "Regions Summary",
+    description: "Keep the regions and signals summary visible in the Effects panel.",
+  },
+];
+
+const INTELLIGENCE_EFFECT_ROWS: EffectRowConfig[] = [
+  {
+    key: "pathfindingEnabled",
+    label: "Directed Pathfinding",
+    description: "Compare the traced path against a strict local directed shortest path.",
+  },
+  {
+    key: "communitiesEnabled",
+    label: "Community Regions",
+    description: "Detect stable Louvain communities for orientation and scene grouping.",
+  },
+  {
+    key: "centralityEnabled",
+    label: "Centrality Ranking",
+    description: "Rank the strongest graph anchors for labels, regions, and navigation.",
+  },
+];
+
+const AVAILABILITY_KEYS: Record<GraphEffectToggle, keyof GraphDiagnosticsSnapshot["effectAvailability"]> = {
+  pathPulseEnabled: "pathPulse",
+  pathFlowEnabled: "pathFlow",
+  lensEnabled: "lens",
+  temporalEmphasisEnabled: "temporalEmphasis",
+  semanticRegionsEnabled: "semanticRegions",
+  contoursEnabled: "contours",
+  pathfindingEnabled: "pathfinding",
+  communitiesEnabled: "communities",
+  centralityEnabled: "centrality",
+  legendEnabled: "legend",
+  edgeLabelsEnabled: "edgeLabels",
+  diagnosticsEnabled: "diagnostics",
+};
+
+function renderAvailabilityText(availability: GraphEffectAvailability) {
+  if (availability.available) {
+    if (typeof availability.visibleSegments === "number" && typeof availability.segmentCap === "number") {
+      return `${availability.reason} - ${availability.visibleSegments}/${availability.segmentCap} segments`;
+    }
+    return availability.reason;
+  }
+
+  return availability.detail ? `${availability.reason} - ${availability.detail}` : availability.reason;
+}
+
+function collectFallbackLegendItems(context: Parameters<NonNullable<GraphPlugin["renderPanel"]>>[0]) {
+  return buildGraphColorLegend(context.graph, context.theme)
+    .sort((left, right) => right.count - left.count)
+    .slice(0, context.theme.effects.legend.maxGroups);
+}
+
+function resolveAvailability(
+  availabilityMap: GraphDiagnosticsSnapshot["effectAvailability"] | undefined,
+  key: GraphEffectToggle,
+  enabled: boolean,
+): GraphEffectAvailability {
+  return availabilityMap?.[AVAILABILITY_KEYS[key]] ?? {
+    enabled,
+    available: false,
+    reason: "Waiting for graph runtime",
+  };
+}
+
+function EffectToggleRow({
+  label,
+  description,
+  checked,
+  availability,
+  onToggle,
+}: {
+  label: string;
+  description: string;
+  checked: boolean;
+  availability: GraphEffectAvailability;
+  onToggle: () => void;
+}) {
+  return (
+    <div style={toggleRowStyle}>
+      <div style={{ minWidth: 0, flex: 1 }}>
+        <div style={rowTitleStyle}>{label}</div>
+        <div style={rowDescriptionStyle}>{description}</div>
+        <div style={rowMetaStyle}>{renderAvailabilityText(availability)}</div>
+      </div>
+      <button type="button" onClick={onToggle} style={checked ? toggleButtonActiveStyle : toggleButtonStyle}>
+        {checked ? "On" : "Off"}
+      </button>
+    </div>
+  );
+}
+
+function renderRegionsAndSignals(
+  context: Parameters<NonNullable<GraphPlugin["renderPanel"]>>[0],
+  analytics: GraphAnalyticsSnapshot | null,
+) {
+  const fallbackLegendItems = collectFallbackLegendItems(context);
+  const semanticRegions = analytics?.semanticRegions.summaries ?? [];
+  const communities = analytics?.communities.summaries ?? [];
+  const centrality = analytics?.centrality.topNodes ?? [];
+  const directedPath = analytics?.directedPath ?? null;
+
+  if (!semanticRegions.length && !communities.length && !centrality.length && !fallbackLegendItems.length && !directedPath) {
+    return <div style={emptyTextStyle}>Regions and intelligence summaries will populate when graph analytics are ready.</div>;
+  }
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: 10 }}>
+      {semanticRegions.length ? (
+        <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
+          <div style={subsectionTitleStyle}>Semantic regions</div>
+          {semanticRegions.map((region) => (
+            <div key={region.semanticGroup} style={legendRowStyle}>
+              <span
+                style={{
+                  ...legendSwatchStyle,
+                  background: region.color,
+                  boxShadow: `0 0 0 1px rgba(255,255,255,0.06), 0 0 14px ${region.color}40`,
+                }}
+              />
+              <div style={{ minWidth: 0, flex: 1 }}>
+                <div style={rowTitleStyle}>{region.semanticGroup}</div>
+                <div style={rowMetaStyle}>
+                  {region.visibleNodeCount.toLocaleString()} visible / {region.nodeCount.toLocaleString()} total
+                </div>
+              </div>
+              <div style={signalBadgeStyle}>{region.anchorLabel}</div>
+            </div>
+          ))}
+        </div>
+      ) : null}
+
+      {communities.length ? (
+        <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
+          <div style={subsectionTitleStyle}>Community anchors</div>
+          {communities.slice(0, 3).map((community) => (
+            <div key={community.communityId} style={signalRowStyle}>
+              <div style={{ minWidth: 0, flex: 1 }}>
+                <div style={rowTitleStyle}>{community.anchorLabel}</div>
+                <div style={rowMetaStyle}>
+                  Community {community.communityId} - {community.visibleNodeCount} visible / {community.nodeCount} total
+                </div>
+              </div>
+              <div style={signalBadgeStyle}>{community.dominantSemanticGroup}</div>
+            </div>
+          ))}
+        </div>
+      ) : null}
+
+      {centrality.length ? (
+        <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
+          <div style={subsectionTitleStyle}>Centrality leaders</div>
+          {centrality.slice(0, 3).map((node) => (
+            <div key={node.id} style={signalRowStyle}>
+              <div style={{ minWidth: 0, flex: 1 }}>
+                <div style={rowTitleStyle}>{node.label}</div>
+                <div style={rowMetaStyle}>
+                  {node.semanticGroup} - score {node.score.toFixed(3)}
+                </div>
+              </div>
+              <div style={signalBadgeStyle}>deg {node.degree.toFixed(3)}</div>
+            </div>
+          ))}
+        </div>
+      ) : null}
+
+      {directedPath ? (
+        <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
+          <div style={subsectionTitleStyle}>Directed pathfinding</div>
+          <div style={signalRowStyle}>
+            <div style={{ minWidth: 0, flex: 1 }}>
+              <div style={rowTitleStyle}>{directedPath.ready ? "Local directed path ready" : "Waiting for path context"}</div>
+              <div style={rowMetaStyle}>{directedPath.reason}</div>
+            </div>
+            {directedPath.ready ? (
+              <div style={signalBadgeStyle}>
+                {directedPath.length} hops{directedPath.verifiedAgainstActivePath ? " - match" : ""}
+              </div>
+            ) : null}
+          </div>
+        </div>
+      ) : null}
+
+      {!semanticRegions.length && !communities.length && !centrality.length && fallbackLegendItems.length ? (
+        <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
+          <div style={subsectionTitleStyle}>Fallback semantic legend</div>
+          {fallbackLegendItems.map((item) => (
+            <div key={item.id} style={legendRowStyle}>
+              <span
+                style={{
+                  ...legendSwatchStyle,
+                  background: item.color,
+                  boxShadow: `0 0 0 1px rgba(255,255,255,0.06), 0 0 14px ${item.color}40`,
+                }}
+              />
+              <div style={{ minWidth: 0, flex: 1 }}>
+                <div style={rowTitleStyle}>{item.group}</div>
+                <div style={rowMetaStyle}>{item.count.toLocaleString()} nodes</div>
+              </div>
+            </div>
+          ))}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+export const explorationEffectsPluginPhaseC: GraphPlugin = {
+  id: "exploration-effects",
+  mount: () => {},
+  unmount: () => {},
+  onStateChange: () => {},
+  toolbarItems: (context) => [
+    {
+      id: "effects-toggle",
+      label: "Effects",
+      title: "Open exploration effects controls",
+      active: context.isPanelOpen(EFFECTS_PANEL_ID),
+      order: 18,
+      onClick: () => context.dispatchAction({ type: "togglePanel", panelId: EFFECTS_PANEL_ID }),
+    },
+  ],
+  renderPanel: (context) => {
+    if (!context.isPanelOpen(EFFECTS_PANEL_ID)) {
+      return null;
+    }
+
+    const effectsState = context.getEffectsState();
+    const diagnosticsSnapshot = context.getDiagnosticsSnapshot();
+    const analyticsSnapshot = context.getAnalyticsSnapshot();
+    const availability = diagnosticsSnapshot?.effectAvailability;
+    const showSignalsSection =
+      effectsState.legendEnabled
+      || effectsState.semanticRegionsEnabled
+      || effectsState.communitiesEnabled
+      || effectsState.centralityEnabled
+      || effectsState.pathfindingEnabled;
+
+    return {
+      id: EFFECTS_PANEL_ID,
+      title: "Effects",
+      placement: "bottom",
+      order: 8,
+      defaultOpen: false,
+      preferredWidth: 460,
+      preferredHeight: 360,
+      content: (
+        <div style={panelBodyStyle}>
+          <div style={panelEyebrowStyle}>Exploration effects</div>
+
+          <div style={sectionStyle}>
+            <div style={sectionTitleStyle}>Scene effects</div>
+            {SCENE_EFFECT_ROWS.map((row) => (
+              <EffectToggleRow
+                key={row.key}
+                label={row.label}
+                description={row.description}
+                checked={effectsState[row.key]}
+                availability={resolveAvailability(availability, row.key, effectsState[row.key])}
+                onToggle={() => context.dispatchAction({ type: "toggleEffect", effect: row.key })}
+              />
+            ))}
+          </div>
+
+          <div style={sectionStyle}>
+            <div style={sectionTitleStyle}>Graph intelligence</div>
+            {INTELLIGENCE_EFFECT_ROWS.map((row) => (
+              <EffectToggleRow
+                key={row.key}
+                label={row.label}
+                description={row.description}
+                checked={effectsState[row.key]}
+                availability={resolveAvailability(availability, row.key, effectsState[row.key])}
+                onToggle={() => context.dispatchAction({ type: "toggleEffect", effect: row.key })}
+              />
+            ))}
+          </div>
+
+          {showSignalsSection ? (
+            <div style={sectionStyle}>
+              <div style={sectionTitleStyle}>Regions and signals</div>
+              {renderRegionsAndSignals(context, analyticsSnapshot)}
+            </div>
+          ) : null}
+
+          {import.meta.env.DEV ? (
+            <div style={sectionStyle}>
+              <div style={sectionTitleStyle}>Diagnostics</div>
+              <EffectToggleRow
+                label="Dev Diagnostics"
+                description="Inspect plugin, interaction, and effect gating state."
+                checked={effectsState.diagnosticsEnabled}
+                availability={resolveAvailability(availability, "diagnosticsEnabled", effectsState.diagnosticsEnabled)}
+                onToggle={() => context.dispatchAction({ type: "toggleEffect", effect: "diagnosticsEnabled" })}
+              />
+              {effectsState.diagnosticsEnabled && diagnosticsSnapshot ? (
+                <details style={detailsStyle}>
+                  <summary style={summaryStyle}>Runtime snapshot</summary>
+                  <pre style={diagnosticsPreStyle}>
+                    {JSON.stringify({ diagnostics: diagnosticsSnapshot, analytics: analyticsSnapshot }, null, 2)}
+                  </pre>
+                </details>
+              ) : null}
+            </div>
+          ) : null}
+        </div>
+      ),
+    };
+  },
+};
+
+const panelBodyStyle: CSSProperties = {
+  display: "flex",
+  flexDirection: "column",
+  gap: 12,
+};
+
+const panelEyebrowStyle: CSSProperties = {
+  color: "#c99aa3",
+  fontSize: 11,
+  fontWeight: 700,
+  letterSpacing: "0.08em",
+  textTransform: "uppercase",
+};
+
+const sectionStyle: CSSProperties = {
+  display: "flex",
+  flexDirection: "column",
+  gap: 8,
+  padding: "10px 12px",
+  borderRadius: 14,
+  border: "1px solid rgba(255,255,255,0.06)",
+  background: "rgba(255,255,255,0.025)",
+};
+
+const sectionTitleStyle: CSSProperties = {
+  color: "#ffdfe4",
+  fontSize: 12,
+  fontWeight: 700,
+};
+
+const subsectionTitleStyle: CSSProperties = {
+  color: "#9cc4ec",
+  fontSize: 11,
+  fontWeight: 700,
+  letterSpacing: "0.05em",
+  textTransform: "uppercase",
+};
+
+const toggleRowStyle: CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  gap: 12,
+  padding: "8px 0",
+};
+
+const rowTitleStyle: CSSProperties = {
+  color: "#fff1f3",
+  fontSize: 13,
+  fontWeight: 600,
+};
+
+const rowDescriptionStyle: CSSProperties = {
+  color: "#a1b7cf",
+  fontSize: 12,
+  lineHeight: 1.45,
+};
+
+const rowMetaStyle: CSSProperties = {
+  color: "#7fc6ff",
+  fontSize: 11,
+  lineHeight: 1.45,
+};
+
+const toggleButtonStyle: CSSProperties = {
+  minWidth: 52,
+  padding: "8px 10px",
+  borderRadius: 999,
+  border: "1px solid rgba(255,255,255,0.08)",
+  background: "rgba(255,255,255,0.03)",
+  color: "#cfe0f4",
+  fontSize: 12,
+  fontWeight: 700,
+  cursor: "pointer",
+};
+
+const toggleButtonActiveStyle: CSSProperties = {
+  ...toggleButtonStyle,
+  background: "rgba(31, 111, 235, 0.24)",
+  border: "1px solid rgba(255, 107, 129, 0.28)",
+  color: "#eef6ff",
+};
+
+const legendRowStyle: CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  gap: 10,
+  padding: "8px 10px",
+  borderRadius: 12,
+  border: "1px solid rgba(255,255,255,0.06)",
+  background: "rgba(255,255,255,0.025)",
+};
+
+const legendSwatchStyle: CSSProperties = {
+  width: 10,
+  height: 10,
+  borderRadius: 999,
+  flexShrink: 0,
+};
+
+const signalRowStyle: CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  gap: 10,
+  padding: "8px 10px",
+  borderRadius: 12,
+  border: "1px solid rgba(255,255,255,0.05)",
+  background: "rgba(255,255,255,0.02)",
+};
+
+const signalBadgeStyle: CSSProperties = {
+  padding: "5px 8px",
+  borderRadius: 999,
+  background: "rgba(31, 111, 235, 0.16)",
+  border: "1px solid rgba(255, 107, 129, 0.16)",
+  color: "#ffdfe4",
+  fontSize: 11,
+  fontWeight: 700,
+  whiteSpace: "nowrap",
+};
+
+const detailsStyle: CSSProperties = {
+  borderRadius: 12,
+  border: "1px solid rgba(255,255,255,0.05)",
+  background: "rgba(0,0,0,0.14)",
+  overflow: "hidden",
+};
+
+const summaryStyle: CSSProperties = {
+  cursor: "pointer",
+  padding: "10px 12px",
+  color: "#f0cdd3",
+  fontSize: 12,
+  fontWeight: 700,
+  letterSpacing: "0.04em",
+  textTransform: "uppercase",
+};
+
+const diagnosticsPreStyle: CSSProperties = {
+  margin: 0,
+  padding: "0 12px 12px",
+  color: "#ffdfe4",
+  fontSize: 11,
+  lineHeight: 1.55,
+  whiteSpace: "pre-wrap",
+  wordBreak: "break-word",
+};
+
+const emptyTextStyle: CSSProperties = {
+  color: "#c99aa3",
+  fontSize: 12,
+  lineHeight: 1.5,
+};

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

@@ -0,0 +1,16 @@
+export { explorationEffectsPluginPhaseC as explorationEffectsPlugin } from "./explorationEffectsPluginPhaseC";
+export { legendPlugin } from "./legendPlugin";
+export { neighborhoodPanelPlugin } from "./neighborhoodPanelPlugin";
+export { temporalOverlayPlugin } from "./temporalOverlayPlugin";
+export type {
+  GraphPlugin,
+  GraphPluginActionRequest,
+  GraphPluginContext,
+  GraphInspectorState,
+  GraphPluginId,
+  GraphPluginOverlayDescriptor,
+  GraphPluginPanelDescriptor,
+  GraphPluginRegistryEntry,
+  GraphPluginToolbarItem,
+  GraphTemporalState,
+} from "./types";

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

@@ -0,0 +1,120 @@
+import type { CSSProperties } from "react";
+
+import { buildGraphColorLegend } from "../graphColorLegend";
+import type { GraphPlugin } from "./types";
+
+const LEGEND_PANEL_ID = "legend-panel";
+const MAX_GROUPS = 8;
+
+export const legendPlugin: GraphPlugin = {
+  id: "legend",
+  mount: () => {},
+  unmount: () => {},
+  onStateChange: () => {},
+  toolbarItems: (context) => [
+    {
+      id: "legend-toggle",
+      label: "Legend",
+      title: "Toggle semantic legend",
+      active: context.isPanelOpen(LEGEND_PANEL_ID),
+      order: 20,
+      onClick: () => context.dispatchAction({ type: "togglePanel", panelId: LEGEND_PANEL_ID }),
+    },
+  ],
+  renderPanel: (context) => {
+    if (!context.isPanelOpen(LEGEND_PANEL_ID)) {
+      return null;
+    }
+
+    const items = buildGraphColorLegend(context.graph, context.theme)
+      .sort((left, right) => right.count - left.count)
+      .slice(0, MAX_GROUPS);
+
+    return {
+      id: LEGEND_PANEL_ID,
+      title: "Legend",
+      placement: "bottom",
+      order: 10,
+      defaultOpen: false,
+      preferredWidth: 320,
+      preferredHeight: 220,
+      content: (
+        <div style={panelBodyStyle}>
+          <div style={panelEyebrowStyle}>Semantic groups</div>
+          {items.length ? (
+            <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
+              {items.map((item) => (
+                <div key={item.id} style={legendRowStyle}>
+                  <span
+                    style={{
+                      ...swatchStyle,
+                      background: item.color,
+                      boxShadow: `0 0 0 1px rgba(255,255,255,0.06), 0 0 18px ${item.color}44`,
+                    }}
+                  />
+                  <div style={{ minWidth: 0, flex: 1 }}>
+                    <div style={rowTitleStyle}>{item.group}</div>
+                    <div style={rowMetaStyle}>{item.count.toLocaleString()} nodes</div>
+                  </div>
+                </div>
+              ))}
+            </div>
+          ) : (
+            <div style={emptyTextStyle}>Legend will populate when the graph metadata is available.</div>
+          )}
+        </div>
+      ),
+    };
+  },
+};
+
+const panelBodyStyle: CSSProperties = {
+  display: "flex",
+  flexDirection: "column",
+  gap: 12,
+};
+
+const panelEyebrowStyle: CSSProperties = {
+  color: "#c99aa3",
+  fontSize: 11,
+  fontWeight: 700,
+  letterSpacing: "0.08em",
+  textTransform: "uppercase",
+};
+
+const legendRowStyle: CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  gap: 10,
+  padding: "8px 10px",
+  borderRadius: 12,
+  border: "1px solid rgba(255,255,255,0.06)",
+  background: "rgba(255,255,255,0.025)",
+};
+
+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,
+};