react-state-basis 0.6.4 → 0.6.6

package/dist/index.js

@@ -34,7 +34,9 @@ __export(index_exports, {
   basis: () => basis,
   configureBasis: () => configureBasis,
   createContext: () => createContext,
+  getBasisGraph: () => getBasisGraph,
   getBasisMetrics: () => getBasisMetrics,
+  printBasisGraph: () => printBasisGraph,
   printBasisHealthReport: () => printBasisHealthReport,
   use: () => use,
   useActionState: () => useActionState,
@@ -62,33 +64,92 @@ module.exports = __toCommonJS(index_exports);
 var React = __toESM(require("react"));
 var import_react = require("react");
 
+// src/core/constants.ts
+var WINDOW_SIZE = 50;
+var PAIR_RARITY_TARGET = 0.01;
+var RELATIVE_OVERLAP_FLOOR = 0.65;
+var LOOP_THRESHOLD = 150;
+var VOLATILITY_THRESHOLD = 25;
+var INSTANCE_SEP = "##";
+
 // src/core/math.ts
-var calculateSimilarityCircular = (bufferA, headA, bufferB, headB, offset) => {
+var choose = (n, k) => {
+  if (k < 0 || k > n) return 0;
+  k = Math.min(k, n - k);
+  let result = 1;
+  for (let i = 0; i < k; i++) {
+    result = result * (n - i) / (i + 1);
+  }
+  return result;
+};
+var hypergeomPMF = (k, n1, m1, N) => {
+  const total = choose(N, n1);
+  if (total === 0) return 0;
+  return choose(m1, k) * choose(N - m1, n1 - k) / total;
+};
+var hypergeomUpperTailP = (kStart, n1, m1, N) => {
+  const kMax = Math.min(n1, m1);
+  let p = 0;
+  for (let k = Math.max(0, kStart); k <= kMax; k++) {
+    p += hypergeomPMF(k, n1, m1, N);
+  }
+  return p;
+};
+var minOverlapForRarity = (n1, m1, N, targetP) => {
+  const kMax = Math.min(n1, m1);
+  for (let k = 0; k <= kMax; k++) {
+    if (hypergeomUpperTailP(k, n1, m1, N) <= targetP) return k;
+  }
+  return kMax + 1;
+};
+var overlapThresholdCache = /* @__PURE__ */ new Map();
+var getMinOverlap = (densityA, densityB, windowSize) => {
+  const lo = Math.min(densityA, densityB) | 0;
+  const hi = Math.max(densityA, densityB) | 0;
+  const key = `${lo}_${hi}_${windowSize}`;
+  let cached = overlapThresholdCache.get(key);
+  if (cached === void 0) {
+    const rare = minOverlapForRarity(lo, hi, windowSize, PAIR_RARITY_TARGET);
+    const floor = Math.ceil(RELATIVE_OVERLAP_FLOOR * lo);
+    cached = Math.max(rare, floor);
+    overlapThresholdCache.set(key, cached);
+  }
+  return cached;
+};
+var isSignificantOverlap = (overlap, densityA, densityB, windowSize) => {
+  if (densityA < 2 || densityB < 2) return false;
+  return overlap >= getMinOverlap(densityA, densityB, windowSize);
+};
+var countOverlapsCircular = (bufferA, headA, bufferB, headB) => {
   const L = bufferA.length;
-  let dot = 0, magA = 0, magB = 0;
-  const baseOffset = ((headB - headA + offset) % L + L) % L;
+  const offSync = ((headB - headA) % L + L) % L;
+  const offALeadsB = ((headB - headA + 1) % L + L) % L;
+  const offBLeadsA = ((headB - headA - 1) % L + L) % L;
+  let kSync = 0;
+  let kALeadsB = 0;
+  let kBLeadsA = 0;
+  let densityA = 0;
+  let densityB = 0;
   for (let i = 0; i < L; i++) {
-    const valA = bufferA[i];
-    let iB = i + baseOffset;
-    if (iB >= L) {
-      iB -= L;
-    }
-    const valB = bufferB[iB];
-    dot += valA * valB;
-    magA += valA * valA;
-    magB += valB * valB;
+    const a = bufferA[i] ? 1 : 0;
+    const b = bufferB[i] ? 1 : 0;
+    densityA += a;
+    densityB += b;
+    let iSync = i + offSync;
+    if (iSync >= L) iSync -= L;
+    let iALeadsB = i + offALeadsB;
+    if (iALeadsB >= L) iALeadsB -= L;
+    let iBLeadsA = i + offBLeadsA;
+    if (iBLeadsA >= L) iBLeadsA -= L;
+    if (a && bufferB[iSync]) kSync++;
+    if (a && bufferB[iALeadsB]) kALeadsB++;
+    if (a && bufferB[iBLeadsA]) kBLeadsA++;
   }
-  if (magA === 0 || magB === 0) return 0;
-  return dot / (Math.sqrt(magA) * Math.sqrt(magB));
+  return { kSync, kALeadsB, kBLeadsA, densityA, densityB };
 };
-var calculateCosineSimilarity = (A, B) => {
-  let dot = 0, magA = 0, magB = 0;
-  for (let i = 0; i < A.length; i++) {
-    dot += A[i] * B[i];
-    magA += A[i] * A[i];
-    magB += B[i] * B[i];
-  }
-  return magA === 0 || magB === 0 ? 0 : dot / (Math.sqrt(magA) * Math.sqrt(magB));
+var cosineFromOverlap = (overlap, densityA, densityB) => {
+  if (densityA <= 0 || densityB <= 0) return 0;
+  return overlap / Math.sqrt(densityA * densityB);
 };
 
 // src/core/graph.ts
@@ -125,13 +186,27 @@ var calculateSpectralInfluence = (graph, maxIterations = 20, tolerance = 1e-3) =
   }
   return scores;
 };
-
-// src/core/constants.ts
-var WINDOW_SIZE = 50;
-var SIMILARITY_THRESHOLD = 0.88;
-var LOOP_THRESHOLD = 150;
-var VOLATILITY_THRESHOLD = 25;
-var INSTANCE_SEP = "##";
+var groupEventSources = (nodes, edges) => {
+  const outgoing = /* @__PURE__ */ new Map();
+  edges.forEach((e) => {
+    if (!outgoing.has(e.source)) outgoing.set(e.source, []);
+    outgoing.get(e.source).push(e);
+  });
+  const eventSourceIds = nodes.filter((n) => n.role === "event").map((n) => n.id);
+  const signatureOf = (sourceEdges) => sourceEdges.map((e) => `${e.target}@${e.weight}`).sort().join("|");
+  const buckets = /* @__PURE__ */ new Map();
+  eventSourceIds.forEach((id) => {
+    const sig = signatureOf(outgoing.get(id) || []);
+    if (!buckets.has(sig)) buckets.set(sig, []);
+    buckets.get(sig).push(id);
+  });
+  const groups = Array.from(buckets.values()).map((sourceIds) => ({
+    sourceIds,
+    occurrences: sourceIds.length,
+    edges: (outgoing.get(sourceIds[0]) || []).slice()
+  }));
+  return groups.sort((a, b) => b.edges.length - a.edges.length || b.occurrences - a.occurrences);
+};
 
 // src/core/label.ts
 var stripInstance = (label) => {
@@ -144,6 +219,7 @@ var parseLabel = (label) => {
   return { file: parts[0] || "Unknown", name: parts[1] || base };
 };
 var isSameField = (labelA, labelB) => stripInstance(labelA) === stripInstance(labelB);
+var isEffectLabel = (name) => /^effect_L\d+(:\d+)?$/.test(name) || name === "anonymous_effect" || name === "anonymous_layout_effect";
 
 // src/core/ranker.ts
 var identifyTopIssues = (graph, history2, redundantLabels2, violationMap) => {
@@ -245,32 +321,22 @@ var LAST_LOG_TIMES = /* @__PURE__ */ new Map();
 var LOG_COOLDOWN = 3e3;
 var THEME = {
   identity: "#6C5CE7",
-  // Purple (Brand)
   problem: "#D63031",
-  // Red (Bugs)
   solution: "#FBC531",
-  // Yellow (Fixes)
   context: "#0984E3",
-  // Blue (Locations)
   muted: "#9AA0A6",
-  // Gray (Metadata)
   border: "#2E2E35",
   success: "#00b894"
-  // Green (Good Score)
 };
 var STYLES = {
-  // Structure
   basis: `background: ${THEME.identity}; color: white; font-weight: bold; padding: 2px 6px; border-radius: 3px;`,
   headerIdentity: `background: ${THEME.identity}; color: white; font-weight: bold; padding: 4px 8px; border-radius: 4px;`,
   headerProblem: `background: ${THEME.problem}; color: white; font-weight: bold; padding: 4px 8px; border-radius: 4px;`,
   version: `background: #a29bfe; color: #2d3436; padding: 2px 6px; border-radius: 3px; margin-left: -4px;`,
-  // Actions
   actionLabel: `color: ${THEME.solution}; font-weight: bold;`,
   actionPill: `color: ${THEME.solution}; font-weight: bold; border: 1px solid ${THEME.solution}; padding: 0 4px; border-radius: 3px;`,
-  // Context
   impactLabel: `color: ${THEME.context}; font-weight: bold;`,
   location: `color: ${THEME.context}; font-family: monospace; font-weight: bold;`,
-  // Text
   subText: `color: ${THEME.muted}; font-size: 11px;`,
   bold: "font-weight: bold;",
   label: "background: #dfe6e9; color: #2d3436; padding: 0 4px; border-radius: 3px; font-family: monospace; font-weight: bold; border: 1px solid #b2bec3;"
@@ -285,6 +351,15 @@ var shouldLog = (key) => {
   return false;
 };
 var isBooleanLike = (name) => /^(is|has|can|should|did|will|show|hide)(?=[A-Z_])/.test(name);
+var areSyncSignificant = (metaA, metaB) => {
+  const { kSync, densityA, densityB } = countOverlapsCircular(
+    metaA.buffer,
+    metaA.head,
+    metaB.buffer,
+    metaB.head
+  );
+  return isSignificantOverlap(kSync, densityA, densityB, metaA.buffer.length);
+};
 var getSuggestedFix = (issue, info) => {
   if (issue.label.includes("Global Event")) {
     return `These variables update together but live in different hooks/files. Consolidate them into a single %cuseReducer%c or atomic store update.`;
@@ -314,7 +389,7 @@ var getSuggestedFix = (issue, info) => {
   }
   return `Check the dependency chain of ${info.name}.`;
 };
-var displayHealthReport = (history2, threshold, violationMap) => {
+var displayHealthReport = (history2, violationMap) => {
   if (!isWeb) return;
   const entries = Array.from(history2.entries());
   if (entries.length === 0) return;
@@ -390,11 +465,10 @@ var displayHealthReport = (history2, threshold, violationMap) => {
     processed.add(labelA);
     entries.forEach(([labelB, metaB]) => {
       if (labelA === labelB || processed.has(labelB)) return;
-      if (calculateCosineSimilarity(metaA.buffer, metaB.buffer) > threshold) {
-        if (metaA.role === "context" /* CONTEXT */ && metaB.role === "context" /* CONTEXT */) return;
-        currentCluster.push(labelB);
-        processed.add(labelB);
-      }
+      if (!areSyncSignificant(metaA, metaB)) return;
+      if (metaA.role === "context" /* CONTEXT */ && metaB.role === "context" /* CONTEXT */) return;
+      currentCluster.push(labelB);
+      processed.add(labelB);
     });
     if (currentCluster.length > 1) clusters.push(currentCluster);
     else independentCount++;
@@ -470,7 +544,7 @@ var displayRedundancyAlert = (labelA, metaA, labelB, metaB, sim) => {
   const alertType = isContextMirror ? "CONTEXT MIRRORING" : isStoreMirror ? "STORE MIRRORING" : "DUPLICATE STATE";
   console.group(`%c \u264A BASIS | ${alertType} `, STYLES.headerProblem);
   console.log(`%c\u{1F4CD} Location: %c${infoA.file}`, STYLES.bold, STYLES.location);
-  console.log(`%cIssue:%c ${infoA.name} and ${infoB.name} are synchronized (${(sim * 100).toFixed(0)}%).`, STYLES.bold, "");
+  console.log(`%cIssue:%c ${infoA.name} and ${infoB.name} overlapped on ${(sim * 100).toFixed(0)}% of aligned updates.`, STYLES.bold, "");
   if (isContextMirror || isStoreMirror) {
     const sourceType = isStoreMirror ? "External Store" : "Global Context";
     console.log(
@@ -539,6 +613,99 @@ var displayCausalHint = (targetLabel, targetMeta, sourceLabel, sourceMeta) => {
   }
   console.groupEnd();
 };
+var splitHookLine = (raw) => {
+  const m = raw.match(/^(.*):(\d+)$/);
+  if (!m) return { hook: raw };
+  return { hook: m[1], line: Number(m[2]) };
+};
+var formatHook = (raw) => {
+  const { hook } = splitHookLine(raw);
+  if (!isEffectLabel(hook)) return hook;
+  const lineMatch = hook.match(/L(\d+)$/);
+  return lineMatch ? `effect @ L${lineMatch[1]}` : "effect (anonymous)";
+};
+var formatNode = (node, fallbackId = "?") => {
+  if (!node) return fallbackId;
+  if (node.role === "event") return "Event";
+  const hook = formatHook(node.name || node.id);
+  if (node.file && hook) return `${node.file} \u2192 ${hook}`;
+  return hook || node.id;
+};
+var displayGraphReport = (graph) => {
+  if (!isWeb) return;
+  if (graph.nodes.length === 0) {
+    console.log(
+      `%c \u{1F4CA} BASIS | CAUSAL GRAPH %c(no data yet)`,
+      STYLES.headerIdentity,
+      `color: ${THEME.muted}; font-style: italic;`
+    );
+    return;
+  }
+  const nodeById = new Map(graph.nodes.map((n) => [n.id, n]));
+  const outgoing = /* @__PURE__ */ new Map();
+  graph.edges.forEach((e) => {
+    if (!outgoing.has(e.source)) outgoing.set(e.source, []);
+    outgoing.get(e.source).push(e);
+  });
+  const eventGroups = graph.eventGroups.map((g) => ({
+    sourceIds: g.sourceIds,
+    sourceNode: nodeById.get(g.sourceIds[0]),
+    edges: g.edges,
+    occurrences: g.occurrences
+  }));
+  const groupedSourceIds = new Set(graph.eventGroups.flatMap((g) => g.sourceIds));
+  const nonEventGroups = Array.from(outgoing.keys()).filter((id) => !groupedSourceIds.has(id)).map((id) => ({ sourceIds: [id], sourceNode: nodeById.get(id), edges: outgoing.get(id), occurrences: 1 }));
+  const groups = [...eventGroups, ...nonEventGroups].sort(
+    (a, b) => b.edges.length - a.edges.length || b.occurrences - a.occurrences
+  );
+  console.group(
+    `%c \u{1F4CA} BASIS | CAUSAL GRAPH %c${graph.nodes.length} nodes \xB7 ${graph.edges.length} edges \xB7 ${groups.length} sources \xB7 buffer window ${graph.bufferWindowSize}`,
+    STYLES.headerIdentity,
+    `color: ${THEME.muted}; font-weight: normal; font-style: italic;`
+  );
+  console.log(
+    `%cparent \u2192 child = observed cause \u2192 update. (\xD7N) = times in this window. Event groups with the same fan-out are collapsed.`,
+    STYLES.subText
+  );
+  groups.forEach((group) => {
+    const isEvent = group.sourceNode?.role === "event";
+    const isCtx = group.sourceNode?.role === "context" /* CONTEXT */;
+    const isFx = group.sourceNode?.role === "effect";
+    const isUnknown = group.sourceNode?.role === "unknown";
+    const icon = isEvent ? "\u26A1" : isCtx ? "\u03A9" : isFx ? "\u21AF" : isUnknown ? "?" : "\u25CF";
+    const color = isEvent ? THEME.solution : isCtx ? THEME.context : THEME.identity;
+    const fanout = group.edges.length;
+    const hits = group.occurrences;
+    const hitLabel = hits > 1 ? ` \xB7 \xD7${hits}` : "";
+    const title = isEvent ? `Event \xB7 ${fanout} target${fanout === 1 ? "" : "s"}${hitLabel}` : formatNode(group.sourceNode, group.sourceIds[0]);
+    console.groupCollapsed(
+      `%c${icon} %c${title}`,
+      `color: ${color};`,
+      "font-family: monospace; font-weight: 600;"
+    );
+    group.edges.slice().sort((a, b) => b.weight - a.weight).forEach((edge) => {
+      const target = nodeById.get(edge.target);
+      const label = formatNode(target, edge.target);
+      const weight = edge.weight > 1 ? ` (\xD7${edge.weight})` : "";
+      if (target?.redundant) {
+        console.log(
+          `%c  ${label}%c${weight} %credundant`,
+          `color: ${THEME.muted}; font-family: monospace;`,
+          `color: ${THEME.muted}; font-style: italic;`,
+          `color: ${THEME.problem}; font-weight: bold;`
+        );
+      } else {
+        console.log(
+          `%c  ${label}%c${weight}`,
+          `color: ${THEME.muted}; font-family: monospace;`,
+          `color: ${THEME.muted}; font-style: italic;`
+        );
+      }
+    });
+    console.groupEnd();
+  });
+  console.groupEnd();
+};
 var displayViolentBreaker = (label, count, threshold) => {
   if (!isWeb) return;
   const { name } = parseLabel(label);
@@ -555,7 +722,6 @@ var displayBootLog = (windowSize) => {
 };
 
 // src/core/analysis.ts
-var CAUSAL_MARGIN = 0.05;
 var isEventDriven = (label, graph) => {
   for (const [parent, targets] of graph.entries()) {
     if (parent.startsWith("Event_Tick_") && targets.has(label)) {
@@ -565,28 +731,33 @@ var isEventDriven = (label, graph) => {
   return false;
 };
 var calculateAllSimilarities = (entryA, entryB) => {
-  const sync = calculateSimilarityCircular(
-    entryA.meta.buffer,
-    entryA.meta.head,
-    entryB.meta.buffer,
-    entryB.meta.head,
-    0
-  );
-  const bA = calculateSimilarityCircular(
-    entryA.meta.buffer,
-    entryA.meta.head,
-    entryB.meta.buffer,
-    entryB.meta.head,
-    1
-  );
-  const aB = calculateSimilarityCircular(
+  const { kSync, kALeadsB, kBLeadsA, densityA, densityB } = countOverlapsCircular(
     entryA.meta.buffer,
     entryA.meta.head,
     entryB.meta.buffer,
-    entryB.meta.head,
-    -1
+    entryB.meta.head
   );
-  return { sync, bA, aB, max: Math.max(sync, bA, aB) };
+  const sync = cosineFromOverlap(kSync, densityA, densityB);
+  const bA = cosineFromOverlap(kALeadsB, densityA, densityB);
+  const aB = cosineFromOverlap(kBLeadsA, densityA, densityB);
+  const max = Math.max(sync, bA, aB);
+  const windowSize = entryA.meta.buffer.length;
+  const significantSync = isSignificantOverlap(kSync, densityA, densityB, windowSize);
+  const kLead = Math.max(kALeadsB, kBLeadsA);
+  const significantLead = isSignificantOverlap(kLead, densityA, densityB, windowSize) && kLead >= kSync + 1;
+  return {
+    sync,
+    bA,
+    aB,
+    max,
+    kSync,
+    kALeadsB,
+    kBLeadsA,
+    densityA,
+    densityB,
+    significantSync,
+    significantLead
+  };
 };
 var shouldSkipComparison = (entryA, entryB, dirtyLabels2) => {
   if (entryA.label === entryB.label) return true;
@@ -611,52 +782,51 @@ var detectRedundancy = (entryA, entryB, similarities, redundantSet, violationMap
   const roleA = entryA.meta.role;
   const roleB = entryB.meta.role;
   if (isGlobalSource(roleA) && isGlobalSource(roleB)) return;
-  if (entryA.meta.density < 2 || entryB.meta.density < 2) return;
+  if (similarities.densityA < 2 || similarities.densityB < 2) return;
+  const score = similarities.sync;
   if (roleA === "local" /* LOCAL */ && isGlobalSource(roleB)) {
     redundantSet.add(entryA.label);
-    pushViolation(violationMap, entryB.label, { type: "context_mirror", target: entryA.label, similarity: similarities.max });
-    displayRedundancyAlert(entryA.label, entryA.meta, entryB.label, entryB.meta, similarities.max);
+    pushViolation(violationMap, entryB.label, { type: "context_mirror", target: entryA.label, similarity: score });
+    displayRedundancyAlert(entryA.label, entryA.meta, entryB.label, entryB.meta, score);
   } else if (isGlobalSource(roleA) && roleB === "local" /* LOCAL */) {
     redundantSet.add(entryB.label);
-    pushViolation(violationMap, entryA.label, { type: "context_mirror", target: entryB.label, similarity: similarities.max });
-    displayRedundancyAlert(entryB.label, entryB.meta, entryA.label, entryA.meta, similarities.max);
+    pushViolation(violationMap, entryA.label, { type: "context_mirror", target: entryB.label, similarity: score });
+    displayRedundancyAlert(entryB.label, entryB.meta, entryA.label, entryA.meta, score);
   } else if (roleA === "local" /* LOCAL */ && roleB === "local" /* LOCAL */) {
     redundantSet.add(entryA.label);
     redundantSet.add(entryB.label);
-    pushViolation(violationMap, entryA.label, { type: "duplicate_state", target: entryB.label, similarity: similarities.max });
-    pushViolation(violationMap, entryB.label, { type: "duplicate_state", target: entryA.label, similarity: similarities.max });
-    displayRedundancyAlert(entryA.label, entryA.meta, entryB.label, entryB.meta, similarities.max);
+    pushViolation(violationMap, entryA.label, { type: "duplicate_state", target: entryB.label, similarity: score });
+    pushViolation(violationMap, entryB.label, { type: "duplicate_state", target: entryA.label, similarity: score });
+    displayRedundancyAlert(entryA.label, entryA.meta, entryB.label, entryB.meta, score);
   }
 };
 var detectCausalLeak = (entryA, entryB, similarities, violationMap, graph) => {
   if (entryA.isVolatile || entryB.isVolatile) return;
-  if (similarities.max - similarities.sync < CAUSAL_MARGIN) return;
   const addLeak = (source, target) => {
     if (isEventDriven(target, graph)) return;
-    if (!violationMap.has(source)) {
-      violationMap.set(source, []);
-    }
-    violationMap.get(source).push({ type: "causal_leak", target });
+    pushViolation(violationMap, source, { type: "causal_leak", target });
     const sourceEntry = source === entryA.label ? entryA : entryB;
     const targetEntry = source === entryA.label ? entryB : entryA;
     displayCausalHint(target, targetEntry.meta, source, sourceEntry.meta);
   };
-  if (similarities.bA === similarities.max) {
+  if (similarities.kALeadsB >= similarities.kBLeadsA) {
     addLeak(entryA.label, entryB.label);
-  } else if (similarities.aB === similarities.max) {
+  } else {
     addLeak(entryB.label, entryA.label);
   }
 };
 var detectSubspaceOverlap = (dirtyEntries, allEntries, redundantSet, dirtyLabels2, graph) => {
-  let compCount = 0;
   const violationMap = /* @__PURE__ */ new Map();
+  let compCount = 0;
   for (const entryA of dirtyEntries) {
     for (const entryB of allEntries) {
       if (shouldSkipComparison(entryA, entryB, dirtyLabels2)) continue;
       compCount++;
       const similarities = calculateAllSimilarities(entryA, entryB);
-      if (similarities.max > SIMILARITY_THRESHOLD) {
+      if (similarities.significantSync) {
         detectRedundancy(entryA, entryB, similarities, redundantSet, violationMap);
+      }
+      if (similarities.significantLead) {
         detectCausalLeak(entryA, entryB, similarities, violationMap, graph);
       }
     }
@@ -915,9 +1085,9 @@ var beginEffectTracking = (l) => {
 var endEffectTracking = () => {
   instance.currentEffectSource = null;
 };
-var printBasisHealthReport = (threshold = 0.5) => {
+var printBasisHealthReport = () => {
   if (!instance.config.debug) return;
-  displayHealthReport(instance.history, threshold, instance.violationMap);
+  displayHealthReport(instance.history, instance.violationMap);
 };
 var getBasisMetrics = () => ({
   engine: "v0.6.x",
@@ -925,9 +1095,53 @@ var getBasisMetrics = () => ({
   analysis_ms: instance.metrics.lastAnalysisTimeMs.toFixed(3),
   entropy: instance.metrics.systemEntropy.toFixed(3)
 });
+var getBasisGraph = () => {
+  const nodeIds = /* @__PURE__ */ new Set();
+  const edges = [];
+  instance.graph.forEach((targets, source) => {
+    nodeIds.add(source);
+    targets.forEach((weight, target) => {
+      nodeIds.add(target);
+      edges.push({ source, target, weight });
+    });
+  });
+  const nodes = Array.from(nodeIds).map((id) => {
+    if (id.startsWith("Event_Tick_")) {
+      return { id, name: "Event", file: "(shared trigger)", role: "event", density: null, redundant: false };
+    }
+    const meta = instance.history.get(id);
+    const { file, name } = parseLabel(id);
+    if (!meta) {
+      const role = isEffectLabel(name) ? "effect" : "unknown";
+      return { id, name, file, role, density: null, redundant: false };
+    }
+    return {
+      id,
+      name,
+      file,
+      role: meta.role,
+      density: meta.density,
+      redundant: instance.redundantLabels.has(id)
+    };
+  });
+  return {
+    generatedAt: Date.now(),
+    bufferWindowSize: WINDOW_SIZE,
+    eventTtlMs: EVENT_TTL,
+    nodes,
+    edges,
+    eventGroups: groupEventSources(nodes, edges)
+  };
+};
+var printBasisGraph = () => {
+  if (!instance.config.debug) return;
+  displayGraphReport(getBasisGraph());
+};
 if (typeof window !== "undefined") {
   window.printBasisReport = printBasisHealthReport;
   window.getBasisMetrics = getBasisMetrics;
+  window.getBasisGraph = getBasisGraph;
+  window.printBasisGraph = printBasisGraph;
 }
 
 // src/hooks.ts
@@ -1330,7 +1544,9 @@ function basis() {
   basis,
   configureBasis,
   createContext,
+  getBasisGraph,
   getBasisMetrics,
+  printBasisGraph,
   printBasisHealthReport,
   use,
   useActionState,