react-state-basis 0.5.0 → 0.6.0

package/dist/index.mjs

@@ -48,24 +48,176 @@ var calculateCosineSimilarity = (A, B) => {
   return magA === 0 || magB === 0 ? 0 : dot / (Math.sqrt(magA) * Math.sqrt(magB));
 };
 
+// src/core/graph.ts
+var calculateSpectralInfluence = (graph, maxIterations = 20, tolerance = 1e-3) => {
+  const nodes = Array.from(/* @__PURE__ */ new Set([...graph.keys(), ...Array.from(graph.values()).flatMap((m) => [...m.keys()])]));
+  if (nodes.length === 0) return /* @__PURE__ */ new Map();
+  let scores = /* @__PURE__ */ new Map();
+  nodes.forEach((n) => scores.set(n, 1 / nodes.length));
+  for (let i = 0; i < maxIterations; i++) {
+    const nextScores = /* @__PURE__ */ new Map();
+    let totalWeight = 0;
+    nodes.forEach((source) => {
+      let influence = 0;
+      const outgoing = graph.get(source);
+      if (outgoing) {
+        outgoing.forEach((weight, target) => {
+          if (source !== target) {
+            influence += (scores.get(target) || 0) * weight;
+          }
+        });
+      }
+      nextScores.set(source, influence + 0.01);
+      totalWeight += influence + 0.01;
+    });
+    let delta = 0;
+    nextScores.forEach((val, key) => {
+      const normalized = val / totalWeight;
+      const diff = normalized - (scores.get(key) || 0);
+      delta += diff * diff;
+      nextScores.set(key, normalized);
+    });
+    scores = nextScores;
+    if (Math.sqrt(delta) < tolerance) break;
+  }
+  return scores;
+};
+
+// src/core/ranker.ts
+var parseLabel = (label) => {
+  const parts = label.split(" -> ");
+  return { file: parts[0] || "Unknown", name: parts[1] || label };
+};
+var identifyTopIssues = (graph, history2, redundantLabels2, violationMap) => {
+  const results = [];
+  const influence = calculateSpectralInfluence(graph);
+  const isEffect = (label) => label.includes("effect_L") || label.includes("useLayoutEffect") || label.includes("useInsertionEffect");
+  const isEvent = (label) => label.startsWith("Event_Tick_");
+  const eventSignatures = /* @__PURE__ */ new Map();
+  const drivers = Array.from(graph.entries()).filter(([label, targets]) => {
+    if (targets.size === 0) return false;
+    if (isEvent(label)) {
+      const validTargets = Array.from(targets.keys()).filter((t) => {
+        const meta2 = history2.get(t);
+        return meta2 && meta2.role !== "context" /* CONTEXT */;
+      });
+      if (validTargets.length > 1) {
+        const signature = validTargets.sort().join("|");
+        const existing = eventSignatures.get(signature);
+        if (existing) {
+          existing.count++;
+          existing.score = Math.max(existing.score, influence.get(label) || 0);
+        } else {
+          eventSignatures.set(signature, {
+            count: 1,
+            score: influence.get(label) || 0,
+            targets: validTargets
+          });
+        }
+      }
+      return false;
+    }
+    const meta = history2.get(label);
+    if (meta?.role === "context" /* CONTEXT */) return false;
+    if (meta?.role === "proj" /* PROJECTION */) return false;
+    const score = influence.get(label) || 0;
+    if (isEffect(label) && targets.size > 0) return true;
+    if (targets.size < 2 && score < 0.05) return false;
+    return true;
+  }).sort((a, b) => {
+    const scoreA = influence.get(a[0]) || 0;
+    const scoreB = influence.get(b[0]) || 0;
+    return scoreB - scoreA;
+  });
+  const sortedEvents = Array.from(eventSignatures.entries()).sort((a, b) => b[1].targets.length - a[1].targets.length);
+  sortedEvents.slice(0, 2).forEach(([sig, data]) => {
+    const primaryVictim = parseLabel(data.targets[0]);
+    const smartLabel = `${primaryVictim.file} -> Global Event (${primaryVictim.name})`;
+    results.push({
+      label: smartLabel,
+      metric: "influence",
+      score: 1,
+      reason: `Global Sync Event: An external trigger is updating ${data.targets.length} roots simultaneously. Occurred ${data.count} times.`,
+      violations: data.targets.map((t) => ({
+        type: "causal_leak",
+        target: t
+      }))
+    });
+  });
+  drivers.slice(0, 3 - results.length).forEach(([label, targets]) => {
+    const targetNames = Array.from(targets.keys());
+    if (isEffect(label)) {
+      results.push({
+        label,
+        metric: "influence",
+        score: influence.get(label) || 0,
+        reason: `Side-Effect Driver: Hook writes to state during render.`,
+        violations: targetNames.map((t) => ({ type: "causal_leak", target: t }))
+      });
+      return;
+    }
+    results.push({
+      label,
+      metric: "influence",
+      score: influence.get(label) || targets.size,
+      reason: `Sync Driver: Acts as a "Prime Mover" for ${targets.size} downstream signals.`,
+      violations: targetNames.map((t) => ({ type: "causal_leak", target: t }))
+    });
+  });
+  if (results.length === 0) {
+    const sortedDensity = Array.from(history2.entries()).filter(
+      ([label, meta]) => meta.role === "local" /* LOCAL */ && !redundantLabels2.has(label) && meta.density > 25
+    ).sort((a, b) => b[1].density - a[1].density);
+    sortedDensity.slice(0, 3).forEach(([label, meta]) => {
+      results.push({
+        label,
+        metric: "density",
+        score: meta.density,
+        reason: `High Frequency: potential main-thread saturation.`,
+        violations: []
+      });
+    });
+  }
+  return results;
+};
+
 // src/core/logger.ts
 var isWeb = typeof window !== "undefined" && typeof window.document !== "undefined";
 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 = {
-  basis: "background: #6c5ce7; color: white; font-weight: bold; padding: 2px 6px; border-radius: 3px;",
-  version: "background: #a29bfe; color: #2d3436; padding: 2px 6px; border-radius: 3px; margin-left: -4px;",
-  headerRed: "background: #d63031; color: white; font-weight: bold; padding: 4px 8px; border-radius: 4px;",
-  headerBlue: "background: #0984e3; color: white; font-weight: bold; padding: 4px 8px; border-radius: 4px;",
-  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;",
-  subText: "color: #636e72; font-size: 11px;",
+  // 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;",
-  action: "color: #00b894; font-weight: bold; border: 1px solid #00b894; padding: 0 4px; border-radius: 3px;",
-  warning: "color: #d63031; font-weight: bold; border: 1px solid #d63031; padding: 0 4px; border-radius: 3px;"
+  label: "background: #dfe6e9; color: #2d3436; padding: 0 4px; border-radius: 3px; font-family: monospace; font-weight: bold; border: 1px solid #b2bec3;"
 };
-var parseLabel = (label) => {
+var parseLabel2 = (label) => {
   const parts = label.split(" -> ");
   return { file: parts[0] || "Unknown", name: parts[1] || label };
 };
@@ -78,57 +230,103 @@ var shouldLog = (key) => {
   }
   return false;
 };
-var displayRedundancyAlert = (labelA, metaA, labelB, metaB, sim) => {
-  if (!isWeb || !shouldLog(`redundant-${labelA}-${labelB}`)) return;
-  const infoA = parseLabel(labelA);
-  const infoB = parseLabel(labelB);
-  const isContextMirror = metaA.role === "local" && metaB.role === "context" || metaB.role === "local" && metaA.role === "context";
-  const local = metaA.role === "local" ? infoA : infoB;
-  const context = metaA.role === "context" ? infoA : infoB;
-  console.group(`%c \u264A BASIS | ${isContextMirror ? "CONTEXT MIRRORING" : "DUPLICATE STATE"} `, STYLES.headerRed);
-  console.log(`%c\u{1F4CD} Location: %c${infoA.file}`, STYLES.bold, STYLES.location);
-  if (isContextMirror) {
-    console.log(
-      `%cIssue:%c Local variable %c${local.name}%c is just a copy of Global Context %c${context.name}%c.
-%cConfidence: ${(sim * 100).toFixed(0)}%`,
-      STYLES.bold,
-      "",
-      STYLES.label,
-      "",
-      STYLES.label,
-      "",
-      STYLES.subText
-    );
-    console.log(`%cFix:%c Use the context value directly to avoid state drift.`, STYLES.bold, STYLES.warning);
-  } else {
-    console.log(
-      `%cIssue:%c %c${infoA.name}%c and %c${infoB.name}%c are synchronized (${(sim * 100).toFixed(0)}% correlation).`,
-      STYLES.bold,
-      "",
-      STYLES.label,
-      "",
-      STYLES.label,
-      ""
-    );
-    console.log(
-      `%cFix:%c Merge states or calculate %c${infoB.name}%c from %c${infoA.name}%c via %cuseMemo%c.`,
-      STYLES.bold,
-      "",
-      STYLES.label,
-      "",
-      STYLES.label,
-      "",
-      STYLES.action,
-      ""
-    );
+var isBooleanLike = (name) => /^(is|has|can|should|did|will|show|hide)(?=[A-Z_])/.test(name);
+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.`;
   }
-  console.groupEnd();
+  const violations = issue.violations || [];
+  const leaks = violations.filter((v) => v.type === "causal_leak");
+  const mirrors = violations.filter((v) => v.type === "context_mirror");
+  const duplicates = violations.filter((v) => v.type === "duplicate_state");
+  if (mirrors.length > 0) {
+    return `Local state is 'shadowing' Global Context. This creates two sources of truth. Delete the local state and consume the %cContext%c value directly.`;
+  }
+  if (leaks.length > 0) {
+    const targetName = parseLabel2(leaks[0].target).name;
+    if (issue.label.includes("effect")) {
+      return `This Effect triggers a synchronous re-render of ${targetName}. Calculate ${targetName} during the render phase (Derived State) or wrap in %cuseMemo%c if expensive.`;
+    }
+    return `State cascading detected. ${info.name} triggers ${targetName} in a separate frame. Merge them into one object to update simultaneously.`;
+  }
+  if (duplicates.length > 0) {
+    if (isBooleanLike(info.name)) {
+      return `Boolean Explosion detected. Multiple flags are toggling in sync. Replace impossible states with a single %cstatus%c string ('idle' | 'loading' | 'success').`;
+    }
+    return `Redundant State detected. This variable carries no unique information. Derive it from the source variable during render, or use %cuseMemo%c to cache the result.`;
+  }
+  if (issue.metric === "density") {
+    return `High-Frequency Update. This variable updates faster than the frame rate. Apply %cdebounce%c or move to a Ref to unblock the main thread.`;
+  }
+  return `Check the dependency chain of ${info.name}.`;
 };
-var displayHealthReport = (history2, threshold) => {
+var displayHealthReport = (history2, threshold, violationMap) => {
   if (!isWeb) return;
   const entries = Array.from(history2.entries());
-  const totalVars = entries.length;
-  if (totalVars === 0) return;
+  if (entries.length === 0) return;
+  const topIssues = identifyTopIssues(instance.graph, history2, instance.redundantLabels, violationMap);
+  console.group(`%c \u{1F4CA} BASIS | ARCHITECTURAL HEALTH REPORT `, STYLES.headerIdentity);
+  if (topIssues.length > 0) {
+    console.log(
+      `%c\u{1F3AF} REFACTOR PRIORITIES %c(PRIME MOVERS)`,
+      `font-weight: bold; color: ${THEME.identity}; margin-top: 10px;`,
+      `font-weight: normal; color: ${THEME.muted}; font-style: italic;`
+    );
+    topIssues.forEach((issue, idx) => {
+      const info = parseLabel2(issue.label);
+      const icon = issue.metric === "influence" ? "\u26A1" : "\u{1F4C8}";
+      const pColor = idx === 0 ? THEME.problem : idx === 1 ? THEME.solution : THEME.identity;
+      let displayName = info.name;
+      let displayFile = info.file;
+      if (issue.label.includes("Global Event")) {
+        displayName = info.name;
+        displayFile = info.file;
+      }
+      console.group(
+        ` %c${idx + 1}%c ${icon} ${displayName} %c(${displayFile})`,
+        `background: ${pColor}; color: ${idx === 1 ? "black" : "white"}; border-radius: 50%; padding: 0 5px;`,
+        "font-family: monospace; font-weight: 700;",
+        `color: ${THEME.muted}; font-size: 10px; font-weight: normal; font-style: italic;`
+      );
+      console.log(`%c${issue.reason}`, `color: ${THEME.muted}; font-style: italic;`);
+      if (issue.violations.length > 0) {
+        const byFile = /* @__PURE__ */ new Map();
+        issue.violations.forEach((v) => {
+          if (issue.label.includes("Global Event") && v.type === "context_mirror") return;
+          const { file, name } = parseLabel2(v.target);
+          if (!byFile.has(file)) byFile.set(file, []);
+          byFile.get(file).push(name);
+        });
+        const impactParts = [];
+        byFile.forEach((vars, file) => {
+          const varList = vars.join(", ");
+          impactParts.push(`${file} (${varList})`);
+        });
+        if (impactParts.length > 0) {
+          console.log(`%cImpacts: %c${impactParts.join(" + ")}`, STYLES.impactLabel, "");
+        }
+      }
+      const fix = getSuggestedFix(issue, info);
+      const fixParts = fix.split("%c");
+      if (fixParts.length === 3) {
+        console.log(
+          `%cSolution: %c${fixParts[0]}%c${fixParts[1]}%c${fixParts[2]}`,
+          STYLES.actionLabel,
+          "",
+          STYLES.actionPill,
+          ""
+        );
+      } else {
+        console.log(
+          `%cSolution: %c${fix}`,
+          STYLES.actionLabel,
+          ""
+        );
+      }
+      console.groupEnd();
+    });
+    console.log("\n");
+  }
   const clusters = [];
   const processed = /* @__PURE__ */ new Set();
   let independentCount = 0;
@@ -138,9 +336,8 @@ var displayHealthReport = (history2, threshold) => {
     processed.add(labelA);
     entries.forEach(([labelB, metaB]) => {
       if (labelA === labelB || processed.has(labelB)) return;
-      const sim = calculateCosineSimilarity(metaA.buffer, metaB.buffer);
-      if (sim > threshold) {
-        if (metaA.role === "context" && metaB.role === "context") return;
+      if (calculateCosineSimilarity(metaA.buffer, metaB.buffer) > threshold) {
+        if (metaA.role === "context" /* CONTEXT */ && metaB.role === "context" /* CONTEXT */) return;
         currentCluster.push(labelB);
         processed.add(labelB);
       }
@@ -148,73 +345,149 @@ var displayHealthReport = (history2, threshold) => {
     if (currentCluster.length > 1) clusters.push(currentCluster);
     else independentCount++;
   });
-  const systemRank = independentCount + clusters.length;
-  const healthScore = systemRank / totalVars * 100;
-  console.group(`%c \u{1F4CA} BASIS | ARCHITECTURAL HEALTH REPORT `, STYLES.headerGreen);
+  const totalVars = entries.length;
+  const redundancyScore = (independentCount + clusters.length) / totalVars * 100;
+  let internalEdges = 0;
+  instance.graph.forEach((targets, source) => {
+    if (source.startsWith("Event_Tick_")) return;
+    internalEdges += targets.size;
+  });
+  const causalPenalty = internalEdges / totalVars * 100;
+  let healthScore = redundancyScore - causalPenalty;
+  if (healthScore < 0) healthScore = 0;
+  const scoreColor = healthScore > 85 ? THEME.success : THEME.problem;
   console.log(
-    `%cEfficiency: %c${healthScore.toFixed(1)}% %c(${systemRank}/${totalVars} Sources of Truth)`,
+    `%cSystem Efficiency: %c${healthScore.toFixed(1)}%`,
     STYLES.bold,
-    `color: ${healthScore > 85 ? "#00b894" : "#d63031"}; font-weight: bold;`,
-    STYLES.subText
+    `color: ${scoreColor}; font-weight: bold;`
   );
+  console.log(`%cSources of Truth: ${independentCount + clusters.length}/${totalVars} | Causal Leaks: ${internalEdges}`, STYLES.subText);
   if (clusters.length > 0) {
-    console.log(`%cDetected ${clusters.length} Sync Issues:`, "font-weight: bold; color: #e17055; margin-top: 10px;");
+    console.log(`%cDetected ${clusters.length} Sync Issues:`, `font-weight: bold; color: ${THEME.problem}; margin-top: 10px;`);
     clusters.forEach((cluster, idx) => {
-      const clusterMetas = cluster.map((l) => ({ label: l, meta: history2.get(l), info: parseLabel(l) }));
-      const contexts = clusterMetas.filter((c) => c.meta.role === "context");
-      const locals = clusterMetas.filter((c) => c.meta.role === "local");
-      const names = clusterMetas.map((c) => `${c.meta.role === "context" ? "\u03A9 " : ""}${c.info.name}`).join(" \u27F7 ");
-      console.group(` %c${idx + 1}%c ${names}`, "background: #e17055; color: white; border-radius: 50%; padding: 0 5px;", "font-family: monospace; font-weight: bold;");
-      if (contexts.length > 0) {
-        const ctxNames = contexts.map((c) => c.info.name).join(", ");
-        console.log(`%cDiagnosis:%c Context Mirroring. Variables are copying from %c${ctxNames}%c.`, STYLES.bold, "", STYLES.label, "");
-        console.log(`%cSolution:%c Use the context directly to avoid state drift.`, STYLES.bold, STYLES.action);
+      const clusterMetas = cluster.map((l) => ({
+        label: l,
+        meta: history2.get(l),
+        name: parseLabel2(l).name
+      }));
+      const hasCtx = clusterMetas.some((c) => c.meta.role === "context" /* CONTEXT */);
+      const names = clusterMetas.map((c) => `${c.meta.role === "context" /* CONTEXT */ ? "\u03A9 " : ""}${c.name}`).join(" \u27F7 ");
+      console.group(` %c${idx + 1}%c ${names}`, `background: ${THEME.problem}; color: white; border-radius: 50%; padding: 0 5px;`, "font-family: monospace; font-weight: bold;");
+      if (hasCtx) {
+        console.log(`%cDiagnosis: Context Mirroring. Local state is shadowing global context.`, `color: ${THEME.problem};`);
+        console.log(`%cSolution: Use context directly to avoid state drift.`, STYLES.actionLabel);
       } else {
-        const isExplosion = locals.length > 2;
-        if (isExplosion) {
-          console.log(`%cDiagnosis:%c Boolean Explosion. Multiple states updating in sync.`, STYLES.bold, "");
-          console.log(`%cSolution:%c Combine into a single %cstatus%c string or a %creducer%c.`, STYLES.bold, "", STYLES.label, "", STYLES.label, "");
+        const boolKeywords = ["is", "has", "can", "should", "loading", "success", "error", "active", "enabled", "open", "visible"];
+        const boolCount = clusterMetas.filter(
+          (c) => boolKeywords.some((kw) => c.name.toLowerCase().startsWith(kw))
+        ).length;
+        const isBoolExplosion = cluster.length > 2 && boolCount / cluster.length > 0.5;
+        if (isBoolExplosion) {
+          console.log(`%cDiagnosis:%c Boolean Explosion. Multiple booleans updating in sync.`, STYLES.bold, "");
+          console.log(`%cSolution:%c Combine into a single %cstatus%c string or a %creducer%c.`, STYLES.actionLabel, "", STYLES.actionPill, "", STYLES.actionPill, "");
+        } else if (cluster.length > 2) {
+          console.log(`%cDiagnosis:%c Sibling Updates. These states respond to the same event.`, STYLES.bold, "");
+          console.log(`%cSolution:%c This may be intentional. If not, consolidate into a %creducer%c.`, STYLES.actionLabel, "", STYLES.actionPill, "");
         } else {
           console.log(`%cDiagnosis:%c Redundant State. Variables always change together.`, STYLES.bold, "");
-          console.log(`%cSolution:%c Derive one from the other via %cuseMemo%c.`, STYLES.bold, "", STYLES.label, "");
+          console.log(`%cSolution:%c Derive one from the other via %cuseMemo%c.`, STYLES.actionLabel, "", STYLES.actionPill, "");
         }
       }
       console.groupEnd();
     });
   } else {
-    console.log("%c\u2728 Your architecture is clean. No redundant state detected.", "color: #00b894; font-weight: bold;");
+    console.log("%c\u2728 Your architecture is clean. No redundant state detected.", `color: ${THEME.success}; font-weight: bold;`);
+  }
+  console.groupEnd();
+};
+var displayRedundancyAlert = (labelA, metaA, labelB, metaB, sim) => {
+  if (!isWeb || !shouldLog(`redundant-${labelA}-${labelB}`)) return;
+  const infoA = parseLabel2(labelA);
+  const infoB = parseLabel2(labelB);
+  const isContextMirror = metaA.role === "local" /* LOCAL */ && metaB.role === "context" /* CONTEXT */ || metaB.role === "local" /* LOCAL */ && metaA.role === "context" /* CONTEXT */;
+  console.group(`%c \u264A BASIS | ${isContextMirror ? "CONTEXT MIRRORING" : "DUPLICATE STATE"} `, 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, "");
+  if (isContextMirror) {
+    console.log(
+      `%cFix:%c Local state is 'shadowing' Global Context. Delete the local state and consume the %cContext%c value directly.`,
+      STYLES.bold,
+      "",
+      STYLES.actionPill,
+      ""
+    );
+  } else {
+    if (isBooleanLike(infoA.name) || isBooleanLike(infoB.name)) {
+      console.log(
+        `%cFix:%c Boolean Explosion detected. Merge flags into a single %cstatus%c string or %cuseReducer%c.`,
+        STYLES.bold,
+        "",
+        STYLES.actionPill,
+        "",
+        STYLES.actionPill,
+        ""
+      );
+    } else {
+      console.log(
+        `%cFix:%c Redundant State detected. Derive %c${infoB.name}%c from %c${infoA.name}%c during render, or use %cuseMemo%c.`,
+        STYLES.bold,
+        "",
+        STYLES.label,
+        "",
+        STYLES.label,
+        "",
+        STYLES.actionPill,
+        ""
+      );
+    }
   }
   console.groupEnd();
 };
 var displayCausalHint = (targetLabel, targetMeta, sourceLabel, sourceMeta) => {
   if (!isWeb || !shouldLog(`causal-${sourceLabel}-${targetLabel}`)) return;
-  const target = parseLabel(targetLabel);
-  const source = parseLabel(sourceLabel);
-  const isContextTrigger = sourceMeta.role === "context";
-  console.groupCollapsed(`%c \u26A1 BASIS | ${isContextTrigger ? "CONTEXT SYNC LEAK" : "DOUBLE RENDER"} `, STYLES.headerBlue);
+  const target = parseLabel2(targetLabel);
+  const source = parseLabel2(sourceLabel);
+  const isCtx = sourceMeta.role === "context" /* CONTEXT */;
+  const isEffect = sourceLabel.includes("effect") || sourceLabel.includes("useLayoutEffect");
+  console.groupCollapsed(`%c \u26A1 BASIS | ${isCtx ? "CONTEXT SYNC LEAK" : "DOUBLE RENDER"} `, STYLES.headerProblem);
   console.log(`%c\u{1F4CD} Location: %c${target.file}`, STYLES.bold, STYLES.location);
-  if (isContextTrigger) {
-    console.log(`%cIssue:%c Context %c${source.name}%c updated, then local %c${target.name}%c followed 1 frame later.`, STYLES.bold, "", STYLES.label, "", STYLES.label, "");
-    console.log(`%cImpact: This forces React to render the component twice for every change.`, STYLES.subText);
+  console.log(`%cIssue:%c ${source.name} triggers ${target.name} in separate frames.`, STYLES.bold, "");
+  if (isEffect) {
+    console.log(
+      `%cFix:%c Derive %c${target.name}%c during the render phase (remove effect) or wrap in %cuseMemo%c.`,
+      STYLES.bold,
+      "",
+      STYLES.label,
+      "",
+      STYLES.actionPill,
+      ""
+    );
   } else {
-    console.log(`%cIssue:%c %c${source.name}%c triggers %c${target.name}%c in a separate frame.`, STYLES.bold, "", STYLES.label, "", STYLES.label, "");
+    console.log(
+      `%cFix:%c Merge %c${target.name}%c with %c${source.name}%c into a single state update.`,
+      STYLES.bold,
+      "",
+      STYLES.label,
+      "",
+      STYLES.label,
+      ""
+    );
   }
-  console.log(`%cFix:%c Derive %c${target.name}%c during the first render.`, STYLES.bold, STYLES.action, STYLES.label, "");
   console.groupEnd();
 };
 var displayViolentBreaker = (label, count, threshold) => {
   if (!isWeb) return;
   const parts = label.split(" -> ");
-  console.group(`%c \u{1F6D1} BASIS CRITICAL | CIRCUIT BREAKER `, "background: #dc2626; color: white; font-weight: bold; padding: 8px 16px;");
+  console.group(`%c \u{1F6D1} BASIS CRITICAL | CIRCUIT BREAKER `, STYLES.headerProblem);
   console.error(`INFINITE LOOP DETECTED
 Variable: ${parts[1] || label}
 Frequency: ${count} updates/sec`);
-  console.log(`%cACTION: Update BLOCKED to prevent browser freeze.`, "color: #dc2626; font-weight: bold;");
+  console.log(`%cACTION: Update BLOCKED to prevent browser freeze.`, `color: ${THEME.problem}; font-weight: bold;`);
   console.groupEnd();
 };
 var displayBootLog = (windowSize) => {
   if (!isWeb) return;
-  console.log(`%cBasis%cAuditor%c | v0.5.x Architectural Forensics Active (Window: ${windowSize})`, STYLES.basis, STYLES.version, "color: #636e72; font-style: italic; margin-left: 8px;");
+  console.log(`%cBasis%cAuditor%c "Graph Era" (Window: ${windowSize})`, STYLES.basis, STYLES.version, `color: ${THEME.muted}; font-style: italic; margin-left: 8px;`);
 };
 
 // src/core/constants.ts
@@ -224,10 +497,37 @@ var LOOP_THRESHOLD = 150;
 var VOLATILITY_THRESHOLD = 25;
 
 // 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)) {
+      return true;
+    }
+  }
+  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(entryA.meta.buffer, entryA.meta.head, entryB.meta.buffer, entryB.meta.head, -1);
+  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(
+    entryA.meta.buffer,
+    entryA.meta.head,
+    entryB.meta.buffer,
+    entryB.meta.head,
+    -1
+  );
   return { sync, bA, aB, max: Math.max(sync, bA, aB) };
 };
 var shouldSkipComparison = (entryA, entryB, dirtyLabels2) => {
@@ -235,49 +535,78 @@ var shouldSkipComparison = (entryA, entryB, dirtyLabels2) => {
   if (dirtyLabels2.has(entryB.label) && entryA.label > entryB.label) return true;
   return false;
 };
-var detectRedundancy = (entryA, entryB, similarities, redundantSet) => {
+var pushViolation = (map, source, detail) => {
+  if (!map.has(source)) {
+    map.set(source, []);
+  }
+  const list = map.get(source);
+  const exists = list.some(
+    (v) => v.type === detail.type && v.target === detail.target
+  );
+  if (!exists) {
+    list.push(detail);
+  }
+};
+var detectRedundancy = (entryA, entryB, similarities, redundantSet, violationMap) => {
   const roleA = entryA.meta.role;
   const roleB = entryB.meta.role;
   if (roleA === "context" /* CONTEXT */ && roleB === "context" /* CONTEXT */) return;
   if (entryA.meta.density < 2 || entryB.meta.density < 2) return;
   if (roleA === "local" /* LOCAL */ && roleB === "context" /* CONTEXT */) {
     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);
   } else if (roleA === "context" /* CONTEXT */ && 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);
   } 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);
   }
 };
-var detectCausalLeak = (entryA, entryB, similarities) => {
+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 });
+    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) {
-    displayCausalHint(entryB.label, entryB.meta, entryA.label, entryA.meta);
+    addLeak(entryA.label, entryB.label);
   } else if (similarities.aB === similarities.max) {
-    displayCausalHint(entryA.label, entryA.meta, entryB.label, entryB.meta);
+    addLeak(entryB.label, entryA.label);
   }
 };
-var detectSubspaceOverlap = (dirtyEntries, allEntries, redundantSet, dirtyLabels2) => {
+var detectSubspaceOverlap = (dirtyEntries, allEntries, redundantSet, dirtyLabels2, graph) => {
   let compCount = 0;
+  const violationMap = /* @__PURE__ */ new Map();
   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) {
-        detectRedundancy(entryA, entryB, similarities, redundantSet);
-        detectCausalLeak(entryA, entryB, similarities);
+        detectRedundancy(entryA, entryB, similarities, redundantSet, violationMap);
+        detectCausalLeak(entryA, entryB, similarities, violationMap, graph);
       }
     }
   }
-  return compCount;
+  return { compCount, violationMap };
 };
 
 // src/engine.ts
 var BASIS_INSTANCE_KEY = /* @__PURE__ */ Symbol.for("__basis_engine_instance__");
+var EVENT_TTL = 1e4;
 var NULL_SIGNAL = {
   role: "proj" /* PROJECTION */,
   buffer: new Uint8Array(0),
@@ -285,6 +614,30 @@ var NULL_SIGNAL = {
   density: 0,
   options: {}
 };
+var activeEventId = null;
+var activeEventTimer = null;
+var pruneGraph = () => {
+  const now = Date.now();
+  for (const source of instance.graph.keys()) {
+    if (source.startsWith("Event_Tick_")) {
+      const parts = source.split("_");
+      const timestamp = parseInt(parts[2], 10);
+      if (now - timestamp > EVENT_TTL) {
+        instance.graph.delete(source);
+      }
+    }
+  }
+};
+var getEventId = () => {
+  if (!activeEventId) {
+    activeEventId = `Event_Tick_${Date.now()}_${Math.random().toString(36).substr(2, 5)}`;
+    if (activeEventTimer) clearTimeout(activeEventTimer);
+    activeEventTimer = setTimeout(() => {
+      activeEventId = null;
+    }, 0);
+  }
+  return activeEventId;
+};
 var getGlobalInstance = () => {
   const root = globalThis;
   if (!root[BASIS_INSTANCE_KEY]) {
@@ -297,7 +650,10 @@ var getGlobalInstance = () => {
       tick: 0,
       isBatching: false,
       currentEffectSource: null,
+      lastStateUpdate: null,
       pausedVariables: /* @__PURE__ */ new Set(),
+      graph: /* @__PURE__ */ new Map(),
+      violationMap: /* @__PURE__ */ new Map(),
       metrics: {
         lastAnalysisTimeMs: 0,
         comparisonCount: 0,
@@ -327,6 +683,14 @@ var calculateTickEntropy = (tickIdx) => {
   });
   return 1 - activeCount / total;
 };
+var recordEdge = (source, target) => {
+  if (!source || !target || source === target) return;
+  if (!instance.graph.has(source)) {
+    instance.graph.set(source, /* @__PURE__ */ new Map());
+  }
+  const targets = instance.graph.get(source);
+  targets.set(target, (targets.get(target) || 0) + 1);
+};
 var analyzeBasis = () => {
   if (!instance.config.debug || dirtyLabels.size === 0) {
     return;
@@ -357,16 +721,33 @@ var analyzeBasis = () => {
         nextRedundant.add(l);
       }
     });
-    const compCount = detectSubspaceOverlap(
+    const { compCount, violationMap } = detectSubspaceOverlap(
       dirtyEntries,
       allEntries,
       nextRedundant,
-      snapshot
+      snapshot,
+      instance.graph
     );
     instance.redundantLabels.clear();
     nextRedundant.forEach((l) => {
       instance.redundantLabels.add(l);
     });
+    violationMap.forEach((newList, label) => {
+      const existing = instance.violationMap.get(label) || [];
+      newList.forEach((detail) => {
+        const alreadyExists = existing.some(
+          (v) => v.type === detail.type && v.target === detail.target
+        );
+        if (!alreadyExists) {
+          existing.push(detail);
+        }
+      });
+      instance.violationMap.set(label, existing);
+    });
+    if (instance.violationMap.size > 500) {
+      const keys = Array.from(instance.violationMap.keys()).slice(0, 200);
+      keys.forEach((k) => instance.violationMap.delete(k));
+    }
     instance.metrics.lastAnalysisTimeMs = performance.now() - analysisStart;
     instance.metrics.comparisonCount = compCount;
     instance.metrics.lastAnalysisTimestamp = Date.now();
@@ -388,6 +769,7 @@ var processHeartbeat = () => {
   instance.currentTickBatch.clear();
   currentTickRegistry = {};
   instance.isBatching = false;
+  instance.lastStateUpdate = null;
   if (dirtyLabels.size > 0) {
     analyzeBasis();
   }
@@ -399,6 +781,7 @@ var recordUpdate = (label) => {
   if (now - instance.lastCleanup > 1e3) {
     instance.loopCounters.clear();
     instance.lastCleanup = now;
+    pruneGraph();
   }
   const count = (instance.loopCounters.get(label) || 0) + 1;
   instance.loopCounters.set(label, count);
@@ -407,17 +790,25 @@ var recordUpdate = (label) => {
     instance.pausedVariables.add(label);
     return false;
   }
-  if (instance.currentEffectSource && instance.currentEffectSource !== label) {
-    const targetMeta = instance.history.get(label);
-    const sourceMeta = instance.history.get(instance.currentEffectSource);
-    if (targetMeta) {
-      const sourceDensity = sourceMeta?.density || 0;
-      const isVolatile = targetMeta.density > VOLATILITY_THRESHOLD || sourceDensity > VOLATILITY_THRESHOLD;
-      if (!isVolatile) {
-        displayCausalHint(label, targetMeta, instance.currentEffectSource, sourceMeta || NULL_SIGNAL);
+  const meta = instance.history.get(label);
+  let edgeSource = null;
+  if (instance.currentEffectSource) {
+    edgeSource = instance.currentEffectSource;
+  } else {
+    edgeSource = getEventId();
+  }
+  if (edgeSource && edgeSource !== label) {
+    recordEdge(edgeSource, label);
+    if (instance.currentEffectSource && instance.currentEffectSource !== label) {
+      const sourceMeta = instance.history.get(instance.currentEffectSource) || NULL_SIGNAL;
+      if (meta && sourceMeta && meta.density < VOLATILITY_THRESHOLD && sourceMeta.density < VOLATILITY_THRESHOLD) {
+        displayCausalHint(label, meta, instance.currentEffectSource, sourceMeta);
       }
     }
   }
+  if (meta && meta.role === "local" /* LOCAL */ && !instance.currentEffectSource) {
+    instance.lastStateUpdate = label;
+  }
   if (currentTickRegistry[label]) return true;
   currentTickRegistry[label] = true;
   instance.currentTickBatch.add(label);
@@ -461,10 +852,10 @@ var endEffectTracking = () => {
 };
 var printBasisHealthReport = (threshold = 0.5) => {
   if (!instance.config.debug) return;
-  displayHealthReport(instance.history, threshold);
+  displayHealthReport(instance.history, threshold, instance.violationMap);
 };
 var getBasisMetrics = () => ({
-  engine: "v0.5.x",
+  engine: "v0.6.x",
   hooks: instance.history.size,
   analysis_ms: instance.metrics.lastAnalysisTimeMs.toFixed(3),
   entropy: instance.metrics.systemEntropy.toFixed(3)
@@ -791,7 +1182,11 @@ var HUDHeader = ({ isExpanded }) => /* @__PURE__ */ jsxs(
 import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
 var BasisContext = createContext2({ debug: false });
 var isWeb2 = typeof window !== "undefined" && typeof window.document !== "undefined";
-var BasisProvider = ({ children, debug = true }) => {
+var BasisProvider = ({
+  children,
+  debug = true,
+  showHUD = true
+}) => {
   useLayoutEffect2(() => {
     configureBasis({ debug });
     if (isWeb2) {
@@ -800,7 +1195,7 @@ var BasisProvider = ({ children, debug = true }) => {
   }, [debug]);
   return /* @__PURE__ */ jsxs2(BasisContext.Provider, { value: { debug }, children: [
     children,
-    debug && isWeb2 && /* @__PURE__ */ jsx2(BasisHUD, {})
+    debug && showHUD && isWeb2 && /* @__PURE__ */ jsx2(BasisHUD, {})
   ] });
 };
 var useBasisConfig = () => useContext2(BasisContext);