react-state-basis 0.4.1 → 0.4.2

package/dist/index.mjs

@@ -20,6 +20,36 @@ import {
   use as reactUse
 } from "react";
 
+// src/core/math.ts
+var calculateSimilarityCircular = (bufferA, headA, bufferB, headB, offset) => {
+  const L = bufferA.length;
+  let dot = 0;
+  let magA = 0;
+  let magB = 0;
+  const headOffset = headB - headA + offset;
+  for (let i = 0; i < L; i++) {
+    const valA = bufferA[i];
+    let iB = i + headOffset;
+    if (iB < 0) iB += L;
+    else if (iB >= L) iB -= L;
+    const valB = bufferB[iB];
+    dot += valA * valB;
+    magA += valA * valA;
+    magB += valB * valB;
+  }
+  if (magA === 0 || magB === 0) return 0;
+  return dot / (Math.sqrt(magA) * Math.sqrt(magB));
+};
+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));
+};
+
 // src/core/logger.ts
 var isWeb = typeof window !== "undefined" && typeof window.document !== "undefined";
 var LAST_LOG_TIMES = /* @__PURE__ */ new Map();
@@ -32,9 +62,11 @@ var STYLES = {
   headerGreen: "background: #00b894; color: white; font-weight: bold; padding: 4px 8px; border-radius: 4px;",
   label: "background: #dfe6e9; color: #2d3436; padding: 0 4px; border-radius: 3px; font-family: monospace; font-weight: bold; border: 1px solid #b2bec3;",
   location: "color: #0984e3; font-family: monospace; font-weight: bold;",
-  codeBlock: "background: #1e1e1e; color: #9cdcfe; padding: 8px 12px; display: block; margin: 4px 0; border-left: 3px solid #00b894; font-family: monospace; line-height: 1.4; border-radius: 0 3px 3px 0;",
+  impact: "background: #f1f2f6; color: #2f3542; padding: 0 4px; border-radius: 3px; font-weight: bold;",
   subText: "color: #636e72; font-size: 11px;",
-  bold: "font-weight: bold;"
+  bold: "font-weight: bold;",
+  actionMemo: "color: #00b894; font-weight: bold; border: 1px solid #00b894; padding: 0 4px; border-radius: 3px;",
+  actionDelete: "color: #d63031; font-weight: bold; border: 1px solid #d63031; padding: 0 4px; border-radius: 3px;"
 };
 var parseLabel = (label) => {
   const parts = label.split(" -> ");
@@ -68,11 +100,11 @@ var displayRedundancyAlert = (labelA, labelB, sim) => {
   if (!isWeb || !shouldLog(`redundant-${labelA}-${labelB}`)) return;
   const infoA = parseLabel(labelA);
   const infoB = parseLabel(labelB);
-  console.group(`%c \u{1F4D0} BASIS | REDUNDANT PATTERN `, STYLES.headerRed);
+  console.group(`%c \u264A BASIS | TWIN STATE DETECTED `, STYLES.headerRed);
   console.log(`%c\u{1F4CD} Location: %c${infoA.file}`, STYLES.bold, STYLES.location);
   console.log(
-    `%cObservation:%c %c${infoA.name}%c and %c${infoB.name}%c move together.
-%cOne is likely a direct mirror of the other. Confidence: ${(sim * 100).toFixed(0)}%`,
+    `%cThe Rhythm:%c %c${infoA.name}%c and %c${infoB.name}%c are moving in perfect sync.
+%cThis indicates that one is a redundant shadow of the other. Confidence: ${(sim * 100).toFixed(0)}%`,
     STYLES.bold,
     "",
     STYLES.label,
@@ -82,10 +114,12 @@ var displayRedundancyAlert = (labelA, labelB, sim) => {
     STYLES.subText
   );
   console.log(
-    `%cAction:%c Refactor %c${infoB.name}%c to useMemo.`,
-    "color: #00b894; font-weight: bold;",
+    `%cRecommended Fix:%c Derive %c${infoB.name}%c from %c${infoA.name}%c during the render pass.`,
+    STYLES.bold,
+    "",
+    STYLES.actionMemo,
     "",
-    "color: #e84393; font-weight: bold;",
+    STYLES.bold,
     ""
   );
   console.groupEnd();
@@ -96,12 +130,12 @@ var displayCausalHint = (targetLabel, sourceLabel, method = "math") => {
   const target = parseLabel(targetLabel);
   const source = parseLabel(sourceLabel);
   console.groupCollapsed(
-    `%c \u{1F4A1} BASIS | ${method === "math" ? "DETECTED" : "TRACKED"} SYNC LEAK `,
+    `%c \u26A1 BASIS | DOUBLE RENDER CYCLE `,
     STYLES.headerBlue
   );
   console.log(`%c\u{1F4CD} Location: %c${target.file}`, STYLES.bold, STYLES.location);
   console.log(
-    `%cFlow:%c %c${source.name}%c \u2794 Effect \u2794 %c${target.name}%c`,
+    `%cThe Rhythm:%c %c${source.name}%c pulses, then %c${target.name}%c pulses one frame later.`,
     STYLES.bold,
     "",
     STYLES.label,
@@ -110,78 +144,112 @@ var displayCausalHint = (targetLabel, sourceLabel, method = "math") => {
     ""
   );
   console.log(
-    `%cContext:%c ${method === "math" ? "The engine detected a consistent 20ms lag between these updates." : "This was caught during React effect execution."}
-%cResult:%c This creates a %cDouble Render Cycle%c.`,
+    `%cThe Impact:%c You are forcing %c2 render passes%c for a single logical change.`,
     STYLES.bold,
     "",
+    STYLES.impact,
+    ""
+  );
+  console.log(
+    `%cRecommended Fix:%c Remove the useEffect. Calculate %c${target.name}%c as a derived value or projection.`,
     STYLES.bold,
     "",
-    "color: #d63031; font-weight: bold;",
+    STYLES.actionDelete,
     ""
   );
   console.groupEnd();
 };
-var displayInfiniteLoop = (label) => {
+var displayViolentBreaker = (label, count, threshold) => {
   if (!isWeb) return;
-  const info = parseLabel(label);
-  console.group(`%c \u{1F6D1} BASIS CRITICAL | CIRCUIT BREAKER `, STYLES.headerRed);
-  console.error(`Infinite oscillation on: %c${info.name}%c`, "color: white; background: #d63031; padding: 2px 4px;", "");
+  const parts = label.split(" -> ");
+  console.group(
+    `%c \u26A0\uFE0F  CRITICAL SYSTEM ALERT | BASIS ENGINE `,
+    "background: #dc2626; color: white; font-weight: bold; padding: 8px 16px; font-size: 14px;"
+  );
+  console.error(
+    `%c\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501`,
+    "color: #dc2626; font-weight: bold;"
+  );
+  console.error(
+    `%cINFINITE LOOP DETECTED
+
+%cVariable: %c${parts[1] || label}
+%cUpdate Frequency: %c${count} updates/sec
+%cExpected Maximum: %c${threshold} updates
+
+%c\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501`,
+    "color: #dc2626; font-size: 16px; font-weight: bold;",
+    "color: #71717a; font-weight: bold;",
+    `color: white; background: #dc2626; padding: 2px 8px;`,
+    "color: #71717a; font-weight: bold;",
+    `color: #fbbf24; font-weight: bold;`,
+    "color: #71717a; font-weight: bold;",
+    `color: #fbbf24; font-weight: bold;`,
+    "color: #dc2626; font-weight: bold;"
+  );
+  console.log(
+    `%cDIAGNOSTICS:
+1. Check for setState inside the render body.
+2. Verify useEffect dependencies (missing or unstable refs).
+3. Look for circular chains (State A -> B -> A).
+
+%cSYSTEM ACTION: Update BLOCKED. Fix your code to resume monitoring.`,
+    "color: #71717a;",
+    "color: #dc2626; font-weight: bold;"
+  );
   console.groupEnd();
 };
-var displayHealthReport = (history2, similarityFn, threshold) => {
+var displayHealthReport = (history2, threshold) => {
   const entries = Array.from(history2.entries());
   const totalVars = entries.length;
   if (totalVars === 0) return;
   const clusters = [];
   const processed = /* @__PURE__ */ new Set();
   let independentCount = 0;
-  entries.forEach(([labelA, vecA]) => {
+  entries.forEach(([labelA, metaA]) => {
     if (processed.has(labelA)) return;
     const currentCluster = [labelA];
     processed.add(labelA);
-    entries.forEach(([labelB, vecB]) => {
+    entries.forEach(([labelB, metaB]) => {
       if (labelA === labelB || processed.has(labelB)) return;
-      const sim = similarityFn(vecA, vecB);
+      const sim = calculateCosineSimilarity(metaA.buffer, metaB.buffer);
       if (sim > threshold) {
         currentCluster.push(labelB);
         processed.add(labelB);
       }
     });
-    if (currentCluster.length > 1) {
-      clusters.push(currentCluster);
-    } else {
-      independentCount++;
-    }
+    if (currentCluster.length > 1) clusters.push(currentCluster);
+    else independentCount++;
   });
   const systemRank = independentCount + clusters.length;
   const healthScore = systemRank / totalVars * 100;
   if (isWeb) {
     console.group(`%c \u{1F4CA} BASIS | ARCHITECTURAL HEALTH REPORT `, STYLES.headerGreen);
     console.log(
-      `%cArchitectural Health Score: %c${healthScore.toFixed(1)}% %c(State Distribution: ${systemRank}/${totalVars})`,
+      `%cSystem Efficiency: %c${healthScore.toFixed(1)}% %c(Basis Vectors: ${systemRank} / Total Hooks: ${totalVars})`,
       STYLES.bold,
       `color: ${healthScore > 85 ? "#00b894" : "#d63031"}; font-size: 16px; font-weight: bold;`,
       "color: #636e72; font-style: italic;"
     );
     if (clusters.length > 0) {
-      console.log(`%cDetected ${clusters.length} Synchronized Update Clusters:`, "font-weight: bold; color: #e17055; margin-top: 10px;");
+      console.log(`%cDetected ${clusters.length} Entangled Clusters:`, "font-weight: bold; color: #e17055; margin-top: 10px;");
       clusters.forEach((cluster, idx) => {
         const names = cluster.map((l) => parseLabel(l).name).join(" \u27F7 ");
         console.log(` %c${idx + 1}%c ${names}`, "background: #e17055; color: white; border-radius: 50%; padding: 0 5px;", "font-family: monospace;");
       });
-      console.log("%c\u{1F4A1} Action: Variables in a cluster move together. Try refactoring them into a single state object or use useMemo for derived values.", STYLES.subText);
+      console.log("%c\u{1F4A1} Analysis: These variables are mirrored. Storing them separately creates unnecessary work for React.", STYLES.subText);
     } else {
-      console.log("%c\u2728 All state variables have optimal distribution. Your Basis is healthy.", "color: #00b894; font-weight: bold; margin-top: 10px;");
+      console.log("%c\u2728 All state variables are independent. Your architectural Basis is healthy.", "color: #00b894; font-weight: bold; margin-top: 10px;");
     }
-    if (totalVars > 0 && totalVars < 15) {
+    if (totalVars > 0 && totalVars < 20) {
       console.groupCollapsed("%cView Full Correlation Matrix", "color: #636e72; font-size: 11px;");
       const matrix = {};
-      entries.forEach(([labelA]) => {
+      entries.forEach(([labelA, metaA]) => {
         const nameA = parseLabel(labelA).name;
         matrix[nameA] = {};
-        entries.forEach(([labelB]) => {
+        entries.forEach(([labelB, metaB]) => {
           const nameB = parseLabel(labelB).name;
-          const sim = similarityFn(history2.get(labelA), history2.get(labelB));
+          const sim = calculateCosineSimilarity(metaA.buffer, metaB.buffer);
           matrix[nameA][nameB] = sim > threshold ? `\u274C ${(sim * 100).toFixed(0)}%` : `\u2705`;
         });
       });
@@ -189,183 +257,185 @@ var displayHealthReport = (history2, similarityFn, threshold) => {
       console.groupEnd();
     }
     console.groupEnd();
-  } else {
-    console.log(`[BASIS HEALTH] Score: ${healthScore.toFixed(1)}% (State Distribution: ${systemRank}/${totalVars})`);
   }
 };
 
-// src/core/math.ts
-var calculateSimilarityWithOffset = (A, B, offsetA, offsetB, length) => {
-  let dot = 0;
-  let magA = 0;
-  let magB = 0;
-  for (let i = 0; i < length; i++) {
-    const valA = A[i + offsetA];
-    const valB = B[i + offsetB];
-    dot += valA * valB;
-    magA += valA * valA;
-    magB += valB * valB;
-  }
-  if (magA === 0 || magB === 0) return 0;
-  return dot / (Math.sqrt(magA) * Math.sqrt(magB));
-};
-var calculateCosineSimilarity = (A, B) => {
-  return calculateSimilarityWithOffset(A, B, 0, 0, A.length);
-};
-
 // src/core/constants.ts
 var WINDOW_SIZE = 50;
 var SIMILARITY_THRESHOLD = 0.88;
 var LOOP_THRESHOLD = 150;
-var LOOP_WINDOW_MS = 1e3;
 var ANALYSIS_INTERVAL = 5;
 var VOLATILITY_THRESHOLD = 25;
 
 // src/engine.ts
-var GLOBAL_KEY = "__BASIS_ENGINE_INSTANCE__";
+var BASIS_INSTANCE_KEY = /* @__PURE__ */ Symbol.for("__basis_engine_instance__");
 var getGlobalInstance = () => {
-  const g = typeof window !== "undefined" ? window : global;
-  if (!g[GLOBAL_KEY]) {
-    g[GLOBAL_KEY] = {
+  const root = globalThis;
+  if (!root[BASIS_INSTANCE_KEY]) {
+    root[BASIS_INSTANCE_KEY] = {
       config: { debug: false },
       history: /* @__PURE__ */ new Map(),
       currentTickBatch: /* @__PURE__ */ new Set(),
       redundantLabels: /* @__PURE__ */ new Set(),
       booted: false,
-      updateLog: [],
       tick: 0,
       isBatching: false,
-      currentEffectSource: null
+      currentEffectSource: null,
+      pausedVariables: /* @__PURE__ */ new Set(),
+      metrics: { lastAnalysisTimeMs: 0, comparisonCount: 0, lastAnalysisTimestamp: 0 },
+      alertCount: 0,
+      loopCounters: /* @__PURE__ */ new Map(),
+      lastCleanup: Date.now()
     };
   }
-  return g[GLOBAL_KEY];
+  return root[BASIS_INSTANCE_KEY];
 };
 var instance = getGlobalInstance();
-var config = instance.config;
-var history = instance.history;
-var currentTickBatch = instance.currentTickBatch;
-var redundantLabels = instance.redundantLabels;
-var configureBasis = (newConfig) => {
-  Object.assign(instance.config, newConfig);
-  if (instance.config.debug && !instance.booted) {
-    displayBootLog(WINDOW_SIZE);
-    instance.booted = true;
-  }
-};
-var getTemporalSimilarity = (vecA, vecB) => {
-  const L = vecA.length;
-  const sync = calculateSimilarityWithOffset(vecA, vecB, 0, 0, L);
-  const bFollowsA = calculateSimilarityWithOffset(vecA, vecB, 0, 1, L - 1);
-  const aFollowsB = calculateSimilarityWithOffset(vecA, vecB, 1, 0, L - 1);
-  return { sync, bFollowsA, aFollowsB };
-};
-var getPulseDensity = (vec) => {
-  let sum = 0;
-  for (let i = 0; i < vec.length; i++) sum += vec[i];
-  return sum;
-};
+var { config, history, redundantLabels, currentTickBatch } = instance;
+var currentTickRegistry = {};
+var dirtyLabels = /* @__PURE__ */ new Set();
 var analyzeBasis = () => {
   if (!instance.config.debug) {
     instance.redundantLabels.clear();
     return;
   }
-  const entries = Array.from(instance.history.entries()).map(([label, vec]) => ({
-    label,
-    vec,
-    density: getPulseDensity(vec)
-  })).filter((e) => e.density >= 2);
-  if (entries.length < 2) return;
-  const newRedundant = /* @__PURE__ */ new Set();
-  for (let i = 0; i < entries.length; i++) {
-    for (let j = i + 1; j < entries.length; j++) {
-      const entryA = entries[i];
-      const entryB = entries[j];
-      const { sync, bFollowsA, aFollowsB } = getTemporalSimilarity(entryA.vec, entryB.vec);
-      const maxSim = Math.max(sync, bFollowsA, aFollowsB);
-      if (maxSim > SIMILARITY_THRESHOLD) {
-        const isBothVolatile = entryA.density > VOLATILITY_THRESHOLD && entryB.density > VOLATILITY_THRESHOLD;
-        if (sync === maxSim) {
-          if (!isBothVolatile) {
-            newRedundant.add(entryA.label);
-            newRedundant.add(entryB.label);
-            displayRedundancyAlert(entryA.label, entryB.label, sync);
-          }
-        } else if (bFollowsA === maxSim) {
-          displayCausalHint(entryB.label, entryA.label, "math");
-        } else if (aFollowsB === maxSim) {
-          displayCausalHint(entryA.label, entryB.label, "math");
+  const scheduler = globalThis.requestIdleCallback || ((cb) => setTimeout(cb, 1));
+  scheduler(() => {
+    const analysisStart = performance.now();
+    if (dirtyLabels.size === 0) return;
+    const allEntries = [];
+    const dirtyEntries = [];
+    instance.history.forEach((meta, label) => {
+      if (meta.options.suppressAll) return;
+      let density = 0;
+      for (let k = 0; k < meta.buffer.length; k++) density += meta.buffer[k];
+      if (density >= 2) {
+        const entry = { label, meta, density };
+        allEntries.push(entry);
+        if (dirtyLabels.has(label)) dirtyEntries.push(entry);
+      }
+    });
+    if (dirtyEntries.length === 0 || allEntries.length < 2) {
+      dirtyLabels.clear();
+      return;
+    }
+    const nextRedundant = /* @__PURE__ */ new Set();
+    let compCount = 0;
+    instance.redundantLabels.forEach((l) => {
+      if (!dirtyLabels.has(l)) nextRedundant.add(l);
+    });
+    for (const dirtyEntry of dirtyEntries) {
+      for (const otherEntry of allEntries) {
+        if (dirtyEntry.label === otherEntry.label) continue;
+        if (dirtyLabels.has(otherEntry.label) && dirtyEntry.label > otherEntry.label) continue;
+        compCount++;
+        const sync = calculateSimilarityCircular(dirtyEntry.meta.buffer, dirtyEntry.meta.head, otherEntry.meta.buffer, otherEntry.meta.head, 0);
+        const bA = calculateSimilarityCircular(dirtyEntry.meta.buffer, dirtyEntry.meta.head, otherEntry.meta.buffer, otherEntry.meta.head, 1);
+        const aB = calculateSimilarityCircular(dirtyEntry.meta.buffer, dirtyEntry.meta.head, otherEntry.meta.buffer, otherEntry.meta.head, -1);
+        const maxSim = Math.max(sync, bA, aB);
+        if (maxSim > SIMILARITY_THRESHOLD) {
+          const bothVolatile = dirtyEntry.density > VOLATILITY_THRESHOLD && otherEntry.density > VOLATILITY_THRESHOLD;
+          if (sync === maxSim && !bothVolatile) {
+            nextRedundant.add(dirtyEntry.label);
+            nextRedundant.add(otherEntry.label);
+            displayRedundancyAlert(dirtyEntry.label, otherEntry.label, sync);
+          } else if (bA === maxSim) displayCausalHint(otherEntry.label, dirtyEntry.label, "math");
+          else if (aB === maxSim) displayCausalHint(dirtyEntry.label, otherEntry.label, "math");
         }
       }
     }
-  }
-  instance.redundantLabels.clear();
-  newRedundant.forEach((label) => instance.redundantLabels.add(label));
+    dirtyLabels.clear();
+    instance.redundantLabels.clear();
+    nextRedundant.forEach((l) => instance.redundantLabels.add(l));
+    instance.metrics.lastAnalysisTimeMs = performance.now() - analysisStart;
+    instance.metrics.comparisonCount = compCount;
+    instance.metrics.lastAnalysisTimestamp = Date.now();
+  });
+};
+var processHeartbeat = () => {
+  instance.tick++;
+  instance.history.forEach((meta, label) => {
+    meta.buffer[meta.head] = instance.currentTickBatch.has(label) ? 1 : 0;
+    meta.head = (meta.head + 1) % WINDOW_SIZE;
+  });
+  instance.currentTickBatch.clear();
+  currentTickRegistry = {};
+  instance.isBatching = false;
+  if (instance.tick % ANALYSIS_INTERVAL === 0) analyzeBasis();
 };
 var recordUpdate = (label) => {
   if (!instance.config.debug) return true;
+  if (instance.pausedVariables.has(label)) return false;
   const now = Date.now();
-  instance.updateLog.push({ label, ts: now });
-  if (instance.updateLog.length > 200) {
-    instance.updateLog = instance.updateLog.filter((e) => now - e.ts < LOOP_WINDOW_MS);
+  if (now - instance.lastCleanup > 1e3) {
+    instance.loopCounters.clear();
+    instance.lastCleanup = now;
   }
-  const updateCount = instance.updateLog.filter((e) => e.label === label).length;
-  if (updateCount > LOOP_THRESHOLD) {
-    displayInfiniteLoop(label);
+  const count = (instance.loopCounters.get(label) || 0) + 1;
+  instance.loopCounters.set(label, count);
+  if (count > LOOP_THRESHOLD) {
+    displayViolentBreaker(label, count, LOOP_THRESHOLD);
+    instance.pausedVariables.add(label);
     return false;
   }
   if (instance.currentEffectSource && instance.currentEffectSource !== label) {
     displayCausalHint(label, instance.currentEffectSource, "tracking");
   }
+  if (currentTickRegistry[label]) return true;
+  currentTickRegistry[label] = true;
   instance.currentTickBatch.add(label);
+  dirtyLabels.add(label);
   if (!instance.isBatching) {
     instance.isBatching = true;
-    setTimeout(() => {
-      instance.tick++;
-      instance.history.forEach((vec, l) => {
-        vec.shift();
-        vec.push(instance.currentTickBatch.has(l) ? 1 : 0);
-      });
-      instance.currentTickBatch.clear();
-      instance.isBatching = false;
-      if (instance.tick % ANALYSIS_INTERVAL === 0) {
-        analyzeBasis();
-      }
-    }, 20);
+    requestAnimationFrame(processHeartbeat);
   }
   return true;
 };
-var beginEffectTracking = (label) => {
-  if (instance.config.debug) instance.currentEffectSource = label;
-};
-var endEffectTracking = () => {
-  instance.currentEffectSource = null;
+var configureBasis = (c) => {
+  Object.assign(instance.config, c);
+  if (instance.config.debug && !instance.booted) {
+    displayBootLog(WINDOW_SIZE);
+    instance.booted = true;
+  }
 };
-var registerVariable = (label) => {
-  if (!instance.config.debug) return;
-  if (!instance.history.has(label)) {
-    instance.history.set(label, new Array(WINDOW_SIZE).fill(0));
+var registerVariable = (l, o = {}) => {
+  if (!instance.config.debug || o.suppressAll) return;
+  if (!instance.history.has(l)) {
+    instance.history.set(l, { buffer: new Uint8Array(WINDOW_SIZE), head: 0, options: o });
   }
 };
-var unregisterVariable = (label) => {
-  instance.history.delete(label);
+var unregisterVariable = (l) => {
+  instance.history.delete(l);
+};
+var beginEffectTracking = (l) => {
+  if (instance.config.debug) instance.currentEffectSource = l;
+};
+var endEffectTracking = () => {
+  instance.currentEffectSource = null;
 };
 var printBasisHealthReport = (threshold = 0.5) => {
   if (!instance.config.debug) {
     console.warn("[Basis] Cannot generate report. Debug mode is OFF.");
     return;
   }
-  displayHealthReport(instance.history, calculateCosineSimilarity, threshold);
+  displayHealthReport(instance.history, threshold);
 };
+var getBasisMetrics = () => ({
+  engine: "v0.4.2 (Ring Buffer)",
+  hooks: instance.history.size,
+  load: instance.metrics.comparisonCount,
+  analysis_ms: instance.metrics.lastAnalysisTimeMs.toFixed(3)
+});
 if (typeof window !== "undefined") {
   window.printBasisReport = printBasisHealthReport;
+  window.getBasisMetrics = getBasisMetrics;
 }
 var __testEngine__ = {
   instance,
-  config: instance.config,
   history: instance.history,
-  currentTickBatch: instance.currentTickBatch,
   configureBasis,
   registerVariable,
+  unregisterVariable,
   recordUpdate,
   printBasisHealthReport,
   beginEffectTracking,
@@ -380,7 +450,9 @@ function useState(initialState, label) {
   const effectiveLabel = reactUseRef(label || getFallbackLabel("state")).current;
   reactUseEffect(() => {
     registerVariable(effectiveLabel);
-    return () => unregisterVariable(effectiveLabel);
+    return () => {
+      unregisterVariable(effectiveLabel);
+    };
   }, [effectiveLabel]);
   const setter = reactUseCallback((newValue) => {
     if (recordUpdate(effectiveLabel)) {
@@ -403,7 +475,9 @@ function useReducer(reducer, initialArg, init, label) {
   );
   reactUseEffect(() => {
     registerVariable(effectiveLabel);
-    return () => unregisterVariable(effectiveLabel);
+    return () => {
+      unregisterVariable(effectiveLabel);
+    };
   }, [effectiveLabel]);
   const basisDispatch = reactUseCallback((action) => {
     if (recordUpdate(effectiveLabel)) {
@@ -475,7 +549,9 @@ function useOptimistic2(passthrough, reducer, label) {
   const effectiveLabel = label || "anonymous_optimistic";
   reactUseEffect(() => {
     registerVariable(effectiveLabel);
-    return () => unregisterVariable(effectiveLabel);
+    return () => {
+      unregisterVariable(effectiveLabel);
+    };
   }, [effectiveLabel]);
   const [state, reactAddOptimistic] = React.useOptimistic(passthrough, reducer);
   const addOptimistic = reactUseCallback((payload) => {
@@ -496,7 +572,9 @@ function useActionState2(action, initialState, permalink, label) {
   );
   reactUseEffect(() => {
     registerVariable(effectiveLabel);
-    return () => unregisterVariable(effectiveLabel);
+    return () => {
+      unregisterVariable(effectiveLabel);
+    };
   }, [effectiveLabel]);
   const basisDispatch = reactUseCallback((payload) => {
     if (recordUpdate(effectiveLabel)) {
@@ -557,7 +635,9 @@ var BasisHUD = () => {
   useEffect2(() => {
     if (!isExpanded) return;
     let animationFrame;
+    let isMounted = true;
     const draw = () => {
+      if (!isMounted) return;
       const canvas = canvasRef.current;
       if (!canvas) return;
       const ctx = canvas.getContext("2d");
@@ -579,7 +659,10 @@ var BasisHUD = () => {
       animationFrame = requestAnimationFrame(draw);
     };
     draw();
-    return () => cancelAnimationFrame(animationFrame);
+    return () => {
+      isMounted = false;
+      cancelAnimationFrame(animationFrame);
+    };
   }, [isExpanded]);
   return /* @__PURE__ */ jsxs("div", { style: getHUDContainerStyle(isExpanded), onClick: () => setIsExpanded(!isExpanded), children: [
     /* @__PURE__ */ jsx(HUDHeader, { isExpanded }),
@@ -605,63 +688,87 @@ function renderEmptyState(ctx) {
   ctx.fillText("Waiting for state transitions...", HUD_DIMENSIONS.PADDING, 30);
 }
 function renderMatrix(ctx, entries) {
-  entries.forEach(([label, vector], rowIndex) => {
-    const y = rowIndex * HUD_DIMENSIONS.ROW_HEIGHT + HUD_DIMENSIONS.PADDING;
-    const stateName = label.split(" -> ")[1] || label;
-    const density = vector.reduce((acc, bit) => acc + bit, 0);
-    const isVolatile = density > 25;
+  const L = HUD_DIMENSIONS.WINDOW_SIZE;
+  const colW = HUD_DIMENSIONS.COL_WIDTH;
+  const rowH = HUD_DIMENSIONS.ROW_HEIGHT;
+  const pad = HUD_DIMENSIONS.PADDING;
+  const cellW = colW - 1.5;
+  const cellH = rowH - 4;
+  const gridPath = new Path2D();
+  const successPath = new Path2D();
+  const errorPath = new Path2D();
+  ctx.font = "11px Inter, Menlo, monospace";
+  let rowIndex = 0;
+  for (const [label, meta] of entries) {
+    const y = rowIndex * rowH + pad;
     const isRedundant = redundantLabels.has(label);
-    vector.forEach((bit, colIndex) => {
-      const x = colIndex * HUD_DIMENSIONS.COL_WIDTH + HUD_DIMENSIONS.PADDING;
-      ctx.fillStyle = bit === 1 ? isRedundant ? HUD_THEME.error : HUD_THEME.success : HUD_THEME.grid;
-      const w = HUD_DIMENSIONS.COL_WIDTH - 1.5;
-      const h = HUD_DIMENSIONS.ROW_HEIGHT - 4;
-      if (ctx.roundRect) {
-        ctx.beginPath();
-        ctx.roundRect(x, y, w, h, HUD_DIMENSIONS.RADIUS);
-        ctx.fill();
+    const { buffer, head } = meta;
+    let uiPos = 0;
+    const addToPath = (val, xIdx) => {
+      const x = xIdx * colW + pad;
+      if (val === 1) {
+        (isRedundant ? errorPath : successPath).rect(x, y, cellW, cellH);
       } else {
-        ctx.fillRect(x, y, w, h);
+        gridPath.rect(x, y, cellW, cellH);
       }
-    });
-    const textX = HUD_DIMENSIONS.WINDOW_SIZE * HUD_DIMENSIONS.COL_WIDTH + HUD_DIMENSIONS.PADDING + 10;
+    };
+    for (let i = head; i < L; i++) addToPath(buffer[i], uiPos++);
+    for (let i = 0; i < head; i++) addToPath(buffer[i], uiPos++);
+    const stateName = label.split(" -> ")[1] || label;
+    const textX = L * colW + pad + 10;
+    let density = 0;
+    for (let i = 0; i < L; i++) density += buffer[i];
+    const isVolatile = density > 25;
     ctx.fillStyle = isRedundant ? HUD_THEME.error : isVolatile ? HUD_THEME.success : HUD_THEME.text;
-    ctx.font = `${isRedundant || isVolatile ? "600" : "400"} 11px Inter, Menlo, monospace`;
-    let prefix = "";
-    if (isRedundant) prefix = "! ";
-    else if (isVolatile) prefix = "~ ";
-    const cleanName = prefix + stateName;
-    const truncatedName = cleanName.length > 18 ? cleanName.substring(0, 16) + ".." : cleanName;
-    ctx.fillText(truncatedName, textX, y + 9);
-  });
+    ctx.fillText((isRedundant ? "! " : isVolatile ? "~ " : "") + stateName, textX, y + 9);
+    rowIndex++;
+  }
+  ctx.fillStyle = HUD_THEME.grid;
+  ctx.fill(gridPath);
+  ctx.fillStyle = HUD_THEME.success;
+  ctx.fill(successPath);
+  ctx.fillStyle = HUD_THEME.error;
+  ctx.fill(errorPath);
 }
-var HUDHeader = ({ isExpanded }) => /* @__PURE__ */ jsxs("div", { style: {
-  padding: "10px 14px",
-  backgroundColor: isExpanded ? HUD_THEME.header : "transparent",
-  color: isExpanded ? "white" : HUD_THEME.header,
-  fontWeight: 600,
-  fontSize: "11px",
-  letterSpacing: "0.05em",
-  display: "flex",
-  justifyContent: "space-between",
-  alignItems: "center",
-  transition: "background 0.3s"
-}, children: [
-  /* @__PURE__ */ jsx("span", { children: isExpanded ? "STATE BASIS MATRIX" : "\u{1F4D0} BASIS ACTIVE" }),
-  isExpanded && /* @__PURE__ */ jsx("span", { style: { opacity: 0.8, fontSize: "9px" }, children: "R50" })
-] });
-var HUDFooter = () => /* @__PURE__ */ jsxs("div", { style: {
-  marginTop: "12px",
-  paddingTop: "8px",
-  borderTop: `1px solid ${HUD_THEME.grid}`,
-  color: HUD_THEME.textDim,
-  fontSize: "9px",
-  display: "flex",
-  justifyContent: "space-between"
-}, children: [
-  /* @__PURE__ */ jsx("span", { children: "LINEAR DEPENDENCY AUDIT" }),
-  /* @__PURE__ */ jsx("span", { children: "THRESHOLD 0.88" })
-] });
+var HUDHeader = ({ isExpanded }) => /* @__PURE__ */ jsxs(
+  "div",
+  {
+    style: {
+      padding: "10px 14px",
+      backgroundColor: isExpanded ? HUD_THEME.header : "transparent",
+      color: isExpanded ? "white" : HUD_THEME.header,
+      fontWeight: 600,
+      fontSize: "11px",
+      letterSpacing: "0.05em",
+      display: "flex",
+      justifyContent: "space-between",
+      alignItems: "center",
+      transition: "background 0.3s"
+    },
+    children: [
+      /* @__PURE__ */ jsx("span", { children: isExpanded ? "STATE BASIS MATRIX" : "\u{1F4D0} BASIS ACTIVE" }),
+      isExpanded && /* @__PURE__ */ jsx("span", { style: { opacity: 0.8, fontSize: "9px" }, children: "v0.4.2" })
+    ]
+  }
+);
+var HUDFooter = () => /* @__PURE__ */ jsxs(
+  "div",
+  {
+    style: {
+      marginTop: "12px",
+      paddingTop: "8px",
+      borderTop: `1px solid ${HUD_THEME.grid}`,
+      color: HUD_THEME.textDim,
+      fontSize: "9px",
+      display: "flex",
+      justifyContent: "space-between"
+    },
+    children: [
+      /* @__PURE__ */ jsx("span", { children: "RING BUFFER ENGINE" }),
+      /* @__PURE__ */ jsx("span", { children: "ZERO ALLOC" })
+    ]
+  }
+);
 
 // src/context.tsx
 import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
@@ -684,6 +791,7 @@ export {
   BasisProvider,
   basis,
   configureBasis,
+  getBasisMetrics,
   printBasisHealthReport,
   use,
   useActionState2 as useActionState,