react-state-basis 0.6.3 → 0.6.5

package/README.md

@@ -5,9 +5,10 @@
 <div align="center">
 
 # react-state-basis
-### Runtime Architectural Auditor for React
 
-**Basis tracks when state updates (never what) to catch architectural debt that standard tools miss, while keeping your data private.**
+### Runtime diagnostics for React state
+
+**Basis observes when state updates happen and uses those patterns to highlight state-management issues that can be difficult to spot in a code review or profiler. It does not inspect state values.**
 
 [![npm version](https://img.shields.io/npm/v/react-state-basis.svg?style=flat-square)](https://www.npmjs.com/package/react-state-basis)
 [![GitHub stars](https://img.shields.io/github/stars/liovic/react-state-basis.svg?style=flat-square)](https://github.com/liovic/react-state-basis/stargazers)
@@ -20,12 +21,16 @@
 ## Quick Start
 
 ### 1. Install
+
 ```bash
 npm i react-state-basis
 ```
 
-### 2. Setup (Vite)
-Add the plugin to your `vite.config.ts`. The Babel plugin auto-labels your hooks - you continue importing from `react` as normal.
+### 2. Setup with Vite
+
+Add the plugin to your `vite.config.ts`.
+
+The Babel plugin labels React hooks automatically, so you can continue importing from `react` as usual.
 
 ```ts
 import { defineConfig } from 'vite';
@@ -34,43 +39,55 @@ import { basis } from 'react-state-basis/vite';
 
 export default defineConfig({
   plugins: [
-    react({ 
-      babel: { plugins: [['react-state-basis/plugin']] } 
+    react({
+      babel: {
+        plugins: [['react-state-basis/plugin']],
+      },
     }),
-    basis()
-  ]
+    basis(),
+  ],
 });
 ```
+This is the supported setup today. Next.js / SWC is not instrumented yet.
 
 ### 3. Initialize
+
 ```tsx
 import { BasisProvider } from 'react-state-basis';
 
 root.render(
-  <BasisProvider 
+  <BasisProvider
     debug={true}
-    showHUD={true} // Set to false for console-only forensics
+    showHUD={true}
   >
     <App />
   </BasisProvider>
 );
 ```
 
-### 4. Verify the Signal
-Drop this pattern into any component. For this pattern, Basis typically flags the rhythm of the debt within ~100ms; detection latency can vary for other patterns.
+Set `showHUD={false}` to keep the diagnostics in the console without showing the overlay.
+
+### 4. Try it
+
+For example:
 
 ```tsx
 const [a, setA] = useState(0);
 const [b, setB] = useState(0);
 
 useEffect(() => {
-  setB(a + 1); // ⚡ BASIS: "Double Render Detected"
+  setB(a + 1);
 }, [a]);
 
-return <button onClick={() => setA(a + 1)}>Pulse Basis</button>;
+return (
+  <button onClick={() => setA(a + 1)}>
+    Update
+  </button>
+);
 ```
 
-Click the button. You should see this in your console:
+When the button is clicked, Basis can identify the effect-driven update pattern and report where it originated. You should see in your console:
+
 ```
 ⚡ BASIS | DOUBLE RENDER
 📍 Location: YourComponent.tsx
@@ -78,64 +95,199 @@ Issue: effect_L5 triggers b in a separate frame.
 Fix: Derive b during the render phase (remove effect) or wrap in useMemo.
 ```
 
----
-
-### 5. Control & Scope
-*   **Ghost Mode:** Disable the visual overlay while keeping console-based forensics active by setting `showHUD={false}` on the provider.
-*   **Selective Auditing:** Add `// @basis-ignore` at the top of any file to disable instrumentation. Recommended for:
-    *   High-frequency animation logic (>60fps)
-    *   Third-party library wrappers
-    *   Intentional synchronization (e.g., local mirrors of external caches)
+Detection happens at runtime and timing varies by pattern.
 
 ---
 
 ## HUD
 
-The optional overlay shows your component's state updates in real time. Purple pulses mark updates coming from Context; red pulses mark state that looks like a redundant copy of something else.
+The optional HUD shows state updates as they happen.
 
 <p align="center">
-  <img src="./assets/050Basis.gif" width="800" alt="Basis Demo" />
+  <img src="./assets/050Basis.gif" width="800" alt="Basis Demo">
 </p>
 
-> **Note:** The HUD shows updates as they happen. The **Architectural Health Report** (Console) looks at the whole update graph together, so it can catch patterns a single glance at the HUD would miss.
+The HUD is useful for seeing individual updates. The console report looks at the observed update graph over time, which can reveal patterns that are harder to see from a single interaction.
 
 ---
 
-## What Basis Detects
+## What Basis Looks For
+
+Basis does not try to determine whether your state is "correct." Instead, it looks for update patterns that are often worth investigating.
+
+### Effect-driven updates
+
+A `useEffect` causes another state update immediately after rendering.
+
+This can be a sign that some state could be derived during render instead.
+
+### Correlated state
+
+Two pieces of state repeatedly update within the same time window.
+
+For example:
+
+```tsx
+const [isLoading, setIsLoading] = useState(false);
+const [isSuccess, setIsSuccess] = useState(false);
+```
+
+If these values consistently change together, it may be worth checking whether they could be represented by a single state value.
+
+Basis reports the correlation; it does not assume that the states should be merged.
+
+### Fragmented updates
 
-Basis watches *when* your state updates and looks for timing patterns that usually mean architectural debt - two states always changing together, an effect immediately re-triggering a render, a click that fans out into updates across unrelated files. Every flag below is a signal to investigate, not a verified defect:
+A single interaction causes updates across multiple components, files, contexts, or stores.
 
-- **⚡ Double Renders (Sync Leaks)** - A `useEffect` triggers a state update immediately after a render, forcing the browser to paint twice.
-- **⚡ Prime Movers (Likely Root Causes)** - Skips downstream symptoms and points you to the hook or event most likely to have started the chain reaction. When multiple updates fire in the same tick, Basis ranks candidates by their position in the update graph rather than asserting a single definitive cause.
-- **⚡ Fragmented Updates** - A single click forces updates in multiple different files or contexts at once (tearing risk).
-- **Context Mirroring** - You're redundantly copying Global Context data into local state, creating two sources of truth.
-- **Duplicate State** - Two variables always update at the exact same time and should probably be merged (e.g. `isLoading` + `isSuccess`).
-- **🛑 Infinite Loops** - A safety circuit-breaker that kills the auditor before a recursive update freezes your browser.
+Sometimes this is intentional. In other cases, it can indicate that state ownership is spread across several places.
 
-Under the hood this is timing correlation over an update graph - ideas borrowed loosely from graph theory and signal processing, not a formal proof. [**See examples & fixes →**](https://github.com/liovic/react-state-basis/wiki/The-Forensic-Catalog)
+### Context mirroring
+
+Local state is repeatedly updated from Context state.
+
+This can create two representations of the same information and is worth reviewing when the local copy does not have an independent purpose.
+
+### Update origins
+
+When several updates occur together, Basis can use the observed update graph to identify which updates appear upstream of others.
+
+This is intended to help investigate a chain of updates rather than simply reporting every downstream symptom.
+
+### Infinite update protection
+
+Basis includes safeguards to stop its own instrumentation from continuing indefinitely when an application enters a recursive update loop.
 
 ---
 
-## Reports & Telemetry
+### Important: these are signals, not proofs
+
+Basis uses runtime timing and correlation heuristics.
 
-### Architectural Health Report
-Check your entire app's state architecture by running `window.printBasisReport()` in the console.
+A detected pattern is **not automatically a bug**, and Basis does not know the intent behind your application architecture.
 
-*   **Refactor Priorities:** Ranks issues by blast radius on the update graph, so you can see which hook or event has the widest fan-out across the rest of your app.
-*   **Efficiency Score:** A rough ratio of independent update sources vs effect-driven follow-up updates. Diagnostic, not a grade.
-*   **Sync Issues:** Groups variables that tend to update together into clusters (e.g., boolean pairs that are really one piece of state).
+Use the results as prompts for investigation rather than as rules for how React code should be written.
 
-### Hardware Telemetry
-Verify engine efficiency and heap stability in real-time via `window.getBasisMetrics()`.
+[See examples and possible fixes →](https://github.com/liovic/react-state-basis/wiki/The-Forensic-Catalog)
 
 ---
 
-## Real-World Evidence
+## Reports
+
+Run:
+
+```js
+window.printBasisReport()
+```
+
+to print a summary of the observed update graph.
 
-Basis has been tested against industry-standard codebases:
+The report can include:
 
-*   **Excalidraw (114k⭐)** - Proposed a theme-sync fix [**PR #10637**](https://github.com/excalidraw/excalidraw/pull/10637) (not merged)
-*   **shadcn-admin (10k⭐)** - Detected redundant state pattern in viewport detection hooks. [**PR #274**](https://github.com/satnaing/shadcn-admin/pull/274) (merged)
+* **Update sources** - where observed update chains appear to originate.
+* **Fan-out** - which updates are followed by the largest number of downstream updates.
+* **Correlated state** - state variables that repeatedly update together.
+* **Effect-driven updates** - updates that occur as a consequence of effects.
+* **Engine metrics** - runtime measurements collected by the Basis engine.
+
+These metrics are diagnostic rather than a score for the quality of your application.
+
+### Causal graph
+
+`printBasisReport()` gives a diagnosis. If you want to see the evidence that report is based on, Basis also exposes the observed update graph directly.
+
+`printBasisGraph()` does nothing unless `debug` is on (same as `printBasisReport()`). `getBasisGraph()` always returns the current snapshot, regardless of `debug`, since it's just serializing the graph, not printing anything.
+
+```js
+window.printBasisGraph()
+```
+
+prints it to the console, grouped by source:
+
+```
+📊 BASIS | CAUSAL GRAPH  7 nodes · 7 edges · 2 sources · buffer window 50
+parent → child = observed cause → update. (×N) = times in this window.
+⚡ Event · 3 targets · ×2
+    BooleanEntanglement.tsx → isLoading redundant
+    BooleanEntanglement.tsx → isSuccess redundant
+    BooleanEntanglement.tsx → hasData redundant
+↯ WeatherLab.tsx → effect @ L7
+    WeatherLab.tsx → fahrenheit (×2)
+```
+
+For the raw data, either from the console:
+
+```js
+window.getBasisGraph()
+```
+
+or imported directly, if you're building your own tooling on top of it rather than reading it from the console:
+
+```ts
+import { getBasisGraph } from 'react-state-basis';
+import type { BasisGraphJSON } from 'react-state-basis';
+```
+
+Either way it returns:
+
+```ts
+{
+  generatedAt: number;
+  bufferWindowSize: number;
+  eventTtlMs: number;
+  nodes: { id, name, file, role, density, redundant }[];
+  edges: { source, target, weight }[];
+  eventGroups: { sourceIds, occurrences, edges }[];
+}
+```
+
+A few things worth knowing about the shape:
+
+* `role` distinguishes real state (`local` / `context` / `store` / `proj`) from `effect` sources, virtual `event` triggers, and `unknown` (a graph edge with no recognized shape - e.g. a custom integration recording edges directly). `effect`, `event`, and `unknown` all have `density: null` - none of them has a real update history of its own.
+* `bufferWindowSize` and `eventTtlMs` are two different clocks: state nodes' `density` is measured over the last `bufferWindowSize` ticks, while virtual `event` nodes are pruned after `eventTtlMs` of inactivity. They're unrelated, so don't read one as describing the other.
+* User interactions are recorded as virtual, per-frame `event` triggers. Repeated interactions that produce the exact same fan-out (same targets, same weights) are collapsed into one entry in `eventGroups`, so clicking the same button 20 times doesn't produce 20 near-identical entries. `nodes` and `edges` remain the full, ungrouped data if you need it - the node/edge counts in the header above are always raw counts, not the number of lines shown after grouping.
+* Only nodes that appear on at least one edge are included - a registered variable that has never caused or received an update won't show up.
+
+This is meant for inspecting what Basis actually observed, building your own tooling on top of it, or attaching to a bug report - not as a second diagnostic layer alongside `printBasisReport()`.
+
+### Runtime metrics
+
+You can inspect engine metrics with:
+
+```js
+window.getBasisMetrics()
+```
+
+---
+
+## Controlling the Instrumentation
+
+### Console-only mode
+
+Disable the HUD while keeping diagnostics enabled:
+
+```tsx
+<BasisProvider showHUD={false}>
+  <App />
+</BasisProvider>
+```
+
+### Ignoring files
+
+Add:
+
+```ts
+// @basis-ignore
+```
+
+to a file to disable Basis instrumentation for that file.
+
+This can be useful for:
+
+* high-frequency animation code
+* third-party library wrappers
+* intentionally synchronized state
+* code where instrumentation is not useful
 
 ---
 
@@ -143,62 +295,89 @@ Basis has been tested against industry-standard codebases:
 
 ### Zustand
 
-Wrap your store with `basisLogger` to give Basis visibility into external
-store updates. Store signals appear in the HUD and health report alongside your React state.
+Basis can observe Zustand store updates alongside React state.
 
 ```typescript
 import { create } from 'zustand';
 import { basisLogger } from 'react-state-basis/zustand';
 
 export const useStore = create(
-  basisLogger((set) => ({
-    theme: 'light',
-    toggleTheme: () => set((state) => ({ 
-      theme: state.theme === 'light' ? 'dark' : 'light' 
-    })),
-  }), 'MyStore')
+  basisLogger(
+    (set) => ({
+      theme: 'light',
+
+      toggleTheme: () =>
+        set((state) => ({
+          theme: state.theme === 'light' ? 'dark' : 'light',
+        })),
+    }),
+    'MyStore'
+  )
 );
 ```
 
-This enables detection of **Store Mirroring**, **Store Sync Leaks**, and
-**Global Event Fragmentation** across React and Zustand state simultaneously.
+This allows React and Zustand updates to appear in the same runtime graph.
 
-[See full Zustand example →](./examples/basis-zustand/)
+[See the Zustand example →](./examples/basis-zustand/)
 
-### More integrations coming
+### Planned integrations
 
-Planned: XState, React Query, Redux Toolkit. Community PRs welcome.
+XState, React Query, and Redux Toolkit are planned.
+
+Community contributions are welcome.
 
 ---
 
 ## Performance & Privacy
 
-**Development:** <1ms overhead per update cycle, zero heap growth  
-**Production:** ~0.01ms per hook (monitoring disabled, ~2-3KB bundle)  
-**Privacy:** Only tracks update timing, never state values
+Basis is designed primarily as a development-time diagnostic tool.
+
+* **Development:** instrumentation overhead is designed to remain small; current benchmarks show less than 1ms per update cycle in tested scenarios.
+* **Production:** monitoring is disabled, with a small production footprint.
+* **Privacy:** Basis records update timing and relationships, not application state values.
+
+Actual overhead depends on the application and instrumentation configuration.
 
-[**See benchmarks →**](https://github.com/liovic/react-state-basis/wiki/Performance-Forensics)
+[See benchmarks →](https://github.com/liovic/react-state-basis/wiki/Performance-Forensics)
 
 ---
 
-## Documentation & Theory
+## Real-World Examples
 
-The engine uses graph and timing heuristics to infer likely architectural issues from *when* state changes, not *what* it changes to. [**The wiki**](https://github.com/liovic/react-state-basis/wiki) explains the full mental model, the math it borrows from, and the engine internals. It is a heuristic, not a proof.
+Basis has also been tested against existing open-source applications.
+
+* **Excalidraw** - Basis identified a theme synchronization pattern and a possible simplification. [PR #10637](https://github.com/excalidraw/excalidraw/pull/10637) was proposed but not merged.
+* **shadcn-admin** - Basis identified a redundant state pattern in viewport detection hooks. [PR #274](https://github.com/satnaing/shadcn-admin/pull/274) was merged.
+
+These examples are intended as demonstrations of the tool's output, not as claims that every detected pattern represents a defect.
 
 ---
 
-## Roadmap
+## How It Works
+
+Basis observes the timing and relationships between state updates while your application runs.
+
+It builds an in-memory representation of those updates and applies heuristics to identify recurring patterns.
+
+It does **not** need to inspect the values stored in your state to perform these checks.
 
-Each version answers a different architectural question:
+The analysis is intentionally heuristic. Runtime behavior can show that two things consistently happen together, but it cannot by itself prove why they happen together or whether the relationship is intentional.
 
-✓ **v0.4.x** - Detect states that always move together *(The Correlation Era)*  
-✓ **v0.5.x** - Detect local copies of Context *(The Decomposition Era)*  
-→ **v0.6.x** - Rank which update fans out widest *(The Graph Era)*  
-**v0.7.x** - Detect derivative vs. independent state *(The Information Era)*  
-**v0.8.x** - Estimate how much local state a component actually needs *(The Manifold Era)*
+For a deeper look at the implementation and underlying model:
+
+[Read the documentation and theory →](https://github.com/liovic/react-state-basis/wiki)
+
+---
+
+## Roadmap
 
+* ✓ **v0.4.x** - Identify state that repeatedly updates together
+* ✓ **v0.5.x** - Identify local state synchronized from Context
+* → **v0.6.x** - Analyze update fan-out and likely upstream sources
+* **v0.7.x** - Improve detection of derived vs. independent state
+* **v0.8.x** - Explore how much local state components actually use
 
-[**More info**](https://github.com/liovic/react-state-basis/wiki/Roadmap)
+[See the full roadmap →](https://github.com/liovic/react-state-basis/wiki/Roadmap)
 
 ---
 

package/dist/{chunk-E3D6YEKB.mjs → chunk-EJXGN76H.mjs}

@@ -61,6 +61,27 @@ var calculateSpectralInfluence = (graph, maxIterations = 20, tolerance = 1e-3) =
   }
   return scores;
 };
+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/constants.ts
 var WINDOW_SIZE = 50;
@@ -80,6 +101,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) => {
@@ -475,6 +497,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);
@@ -837,6 +952,13 @@ var unregisterVariable = (l) => {
   instance.loopCounters.delete(l);
   instance.pausedVariables.delete(l);
   instance.redundantLabels.delete(l);
+  instance.graph.delete(l);
+  instance.graph.forEach((targets) => targets.delete(l));
+  instance.violationMap.delete(l);
+  instance.violationMap.forEach((list) => {
+    const idx = list.findIndex((v) => v.target === l);
+    if (idx !== -1) list.splice(idx, 1);
+  });
 };
 var beginEffectTracking = (l) => {
   if (instance.config.debug) instance.currentEffectSource = l;
@@ -854,9 +976,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;
 }
 
 export {
@@ -872,6 +1038,8 @@ export {
   beginEffectTracking,
   endEffectTracking,
   printBasisHealthReport,
-  getBasisMetrics
+  getBasisMetrics,
+  getBasisGraph,
+  printBasisGraph
 };
-//# sourceMappingURL=chunk-E3D6YEKB.mjs.map
+//# sourceMappingURL=chunk-EJXGN76H.mjs.map