pulse-js-framework 1.7.9 → 1.7.10

package/runtime/devtools.js

@@ -7,460 +7,81 @@
  * - Time-travel debugging with state snapshots
  * - Performance monitoring
  * - Effect tracking
- */
-
-import { pulse, effect, batch, context } from './pulse.js';
-
-// =============================================================================
-// DEV TOOLS STATE
-// =============================================================================
-
-/**
- * Dev tools configuration
- */
-const config = {
-  enabled: false,
-  maxSnapshots: 50,
-  logUpdates: false,
-  logEffects: false,
-  warnOnSlowEffects: true,
-  slowEffectThreshold: 16 // ms (one frame at 60fps)
-};
-
-/**
- * Registry of all tracked pulses
- * @type {Map<string, {pulse: Pulse, name: string, createdAt: number}>}
- */
-const pulseRegistry = new Map();
-
-/**
- * Registry of all tracked effects
- * @type {Map<string, {effect: Object, name: string, createdAt: number, runCount: number, totalTime: number}>}
- */
-const effectRegistry = new Map();
-
-/**
- * Time-travel state history
- * @type {Array<{timestamp: number, state: Object, action: string}>}
- */
-const stateHistory = [];
-
-/**
- * Current position in history (for time-travel)
- */
-let historyIndex = -1;
-
-/**
- * Flag to prevent recording during time-travel
- */
-let isTimeTraveling = false;
-
-// =============================================================================
-// DIAGNOSTICS API
-// =============================================================================
-
-/**
- * @typedef {Object} DiagnosticsStats
- * @property {number} pulseCount - Total number of active pulses
- * @property {number} effectCount - Total number of active effects
- * @property {number} totalEffectRuns - Total effect executions
- * @property {number} avgEffectTime - Average effect execution time (ms)
- * @property {number} pendingEffects - Effects waiting to run
- * @property {number} batchDepth - Current batch nesting depth
- * @property {number} snapshotCount - Number of stored snapshots
- * @property {Object} memoryEstimate - Estimated memory usage
- */
-
-/**
- * Get current diagnostics statistics
- * @returns {DiagnosticsStats}
+ * - Accessibility auditing
  *
- * @example
- * const stats = getDiagnostics();
- * console.log(`Active pulses: ${stats.pulseCount}`);
- * console.log(`Effect runs: ${stats.totalEffectRuns}`);
- */
-export function getDiagnostics() {
-  let totalRuns = 0;
-  let totalTime = 0;
-
-  for (const entry of effectRegistry.values()) {
-    totalRuns += entry.runCount;
-    totalTime += entry.totalTime;
-  }
-
-  return {
-    pulseCount: pulseRegistry.size,
-    effectCount: effectRegistry.size,
-    totalEffectRuns: totalRuns,
-    avgEffectTime: totalRuns > 0 ? totalTime / totalRuns : 0,
-    pendingEffects: context.pendingEffects.size,
-    batchDepth: context.batchDepth,
-    snapshotCount: stateHistory.length,
-    memoryEstimate: {
-      pulses: pulseRegistry.size * 100, // rough estimate in bytes
-      effects: effectRegistry.size * 200,
-      history: stateHistory.length * 500
-    }
-  };
-}
-
-/**
- * Get detailed effect statistics
- * @returns {Array<{id: string, name: string, runCount: number, avgTime: number, lastRun: number}>}
+ * Architecture:
+ * This module re-exports from specialized sub-modules:
+ * - devtools/diagnostics.js: Graph inspection, tracking, profiling
+ * - devtools/time-travel.js: State snapshots and history navigation
+ * - devtools/a11y-audit.js: Accessibility validation and reporting
  */
-export function getEffectStats() {
-  return [...effectRegistry.entries()].map(([id, entry]) => ({
-    id,
-    name: entry.name,
-    runCount: entry.runCount,
-    avgTime: entry.runCount > 0 ? entry.totalTime / entry.runCount : 0,
-    totalTime: entry.totalTime,
-    createdAt: entry.createdAt
-  }));
-}
 
-/**
- * Get list of all tracked pulses
- * @returns {Array<{id: string, name: string, value: any, subscriberCount: number}>}
- */
-export function getPulseList() {
-  return [...pulseRegistry.entries()].map(([id, entry]) => ({
-    id,
-    name: entry.name,
-    value: entry.pulse.peek(),
-    subscriberCount: entry.pulse._subscribers?.size || 0,
-    createdAt: entry.createdAt
-  }));
-}
-
-// =============================================================================
-// REACTIVE GRAPH INSPECTION
-// =============================================================================
+import { createLogger } from './logger.js';
 
-/**
- * @typedef {Object} DependencyNode
- * @property {string} id - Node identifier
- * @property {string} type - 'pulse' | 'effect' | 'computed'
- * @property {string} name - Display name
- * @property {any} value - Current value (for pulses)
- * @property {string[]} dependencies - IDs of nodes this depends on
- * @property {string[]} dependents - IDs of nodes that depend on this
- */
-
-/**
- * Build the reactive dependency graph
- * @returns {{nodes: DependencyNode[], edges: Array<{from: string, to: string}>}}
- *
- * @example
- * const graph = getDependencyGraph();
- * console.log('Nodes:', graph.nodes.length);
- * console.log('Edges:', graph.edges.length);
- * // Visualize with D3.js or similar
- */
-export function getDependencyGraph() {
-  const nodes = [];
-  const edges = [];
-  const nodeMap = new Map();
-
-  // Add pulse nodes
-  for (const [id, entry] of pulseRegistry) {
-    const node = {
-      id,
-      type: 'pulse',
-      name: entry.name,
-      value: entry.pulse.peek(),
-      dependencies: [],
-      dependents: []
-    };
-    nodes.push(node);
-    nodeMap.set(id, node);
-  }
-
-  // Add effect nodes and build edges
-  for (const [id, entry] of effectRegistry) {
-    const node = {
-      id,
-      type: 'effect',
-      name: entry.name,
-      value: null,
-      dependencies: [],
-      dependents: []
-    };
-    nodes.push(node);
-    nodeMap.set(id, node);
-
-    // Get effect's dependencies
-    if (entry.effect?.dependencies) {
-      for (const dep of entry.effect.dependencies) {
-        const depId = findPulseId(dep);
-        if (depId) {
-          node.dependencies.push(depId);
-          edges.push({ from: depId, to: id });
-
-          const depNode = nodeMap.get(depId);
-          if (depNode) {
-            depNode.dependents.push(id);
-          }
-        }
-      }
-    }
-  }
-
-  return { nodes, edges };
-}
-
-/**
- * Find pulse ID from pulse instance
- */
-function findPulseId(pulseInstance) {
-  for (const [id, entry] of pulseRegistry) {
-    if (entry.pulse === pulseInstance) {
-      return id;
-    }
-  }
-  return null;
-}
-
-/**
- * Export graph in DOT format for Graphviz visualization
- * @returns {string} DOT format graph
- */
-export function exportGraphAsDot() {
-  const { nodes, edges } = getDependencyGraph();
-
-  let dot = 'digraph ReactiveGraph {\n';
-  dot += '  rankdir=LR;\n';
-  dot += '  node [shape=box];\n\n';
-
-  // Add nodes with styling
-  for (const node of nodes) {
-    const color = node.type === 'pulse' ? 'lightblue' : 'lightgreen';
-    const label = `${node.name}\\n${node.type}`;
-    dot += `  "${node.id}" [label="${label}" fillcolor="${color}" style="filled"];\n`;
-  }
-
-  dot += '\n';
-
-  // Add edges
-  for (const edge of edges) {
-    dot += `  "${edge.from}" -> "${edge.to}";\n`;
-  }
-
-  dot += '}\n';
-  return dot;
-}
-
-// =============================================================================
-// TIME-TRAVEL DEBUGGING
-// =============================================================================
-
-/**
- * @typedef {Object} StateSnapshot
- * @property {number} timestamp - When snapshot was taken
- * @property {Object} state - Serialized state
- * @property {string} action - Description of what caused the snapshot
- * @property {number} index - Position in history
- */
-
-/**
- * Take a snapshot of current state
- * @param {string} [action='manual'] - Description of the action
- * @returns {StateSnapshot}
- */
-export function takeSnapshot(action = 'manual') {
-  if (isTimeTraveling) return null;
-
-  const state = {};
-  for (const [id, entry] of pulseRegistry) {
-    try {
-      // Deep clone to prevent mutation
-      state[id] = JSON.parse(JSON.stringify(entry.pulse.peek()));
-    } catch {
-      // Non-serializable value
-      state[id] = '[Non-serializable]';
-    }
-  }
-
-  const snapshot = {
-    timestamp: Date.now(),
-    state,
-    action,
-    index: stateHistory.length
-  };
-
-  // Trim history if too long
-  if (stateHistory.length >= config.maxSnapshots) {
-    stateHistory.shift();
-  }
-
-  stateHistory.push(snapshot);
-  historyIndex = stateHistory.length - 1;
-
-  return snapshot;
-}
-
-/**
- * Get state history
- * @returns {StateSnapshot[]}
- */
-export function getHistory() {
-  return [...stateHistory];
-}
-
-/**
- * Get current history position
- * @returns {number}
- */
-export function getHistoryIndex() {
-  return historyIndex;
-}
-
-/**
- * Travel to a specific point in history
- * @param {number} index - History index to travel to
- * @returns {boolean} Success
- */
-export function travelTo(index) {
-  if (index < 0 || index >= stateHistory.length) {
-    return false;
-  }
-
-  const snapshot = stateHistory[index];
-  isTimeTraveling = true;
-
-  batch(() => {
-    for (const [id, value] of Object.entries(snapshot.state)) {
-      const entry = pulseRegistry.get(id);
-      if (entry && value !== '[Non-serializable]') {
-        entry.pulse.set(value);
-      }
-    }
-  });
-
-  historyIndex = index;
-  isTimeTraveling = false;
-
-  return true;
-}
-
-/**
- * Go back one step in history
- * @returns {boolean} Success
- */
-export function back() {
-  return travelTo(historyIndex - 1);
-}
-
-/**
- * Go forward one step in history
- * @returns {boolean} Success
- */
-export function forward() {
-  return travelTo(historyIndex + 1);
-}
-
-/**
- * Clear all history
- */
-export function clearHistory() {
-  stateHistory.length = 0;
-  historyIndex = -1;
-}
+// Import from sub-modules
+import {
+  config,
+  getDiagnostics,
+  getEffectStats,
+  getPulseList,
+  getDependencyGraph,
+  exportGraphAsDot,
+  trackedPulse as basedTrackedPulse,
+  trackedEffect,
+  profile,
+  mark,
+  resetDiagnostics,
+  _setSnapshotCountFn
+} from './devtools/diagnostics.js';
+
+import {
+  timeTravelConfig,
+  getIsTimeTraveling,
+  takeSnapshot,
+  getHistory,
+  getHistoryIndex,
+  getSnapshotCount,
+  travelTo,
+  back,
+  forward,
+  clearHistory
+} from './devtools/time-travel.js';
+
+// Wire up snapshot count for diagnostics
+_setSnapshotCountFn(getSnapshotCount);
+
+import {
+  a11yAuditConfig,
+  runA11yAudit,
+  getA11yIssues,
+  getA11yStats,
+  enableA11yAudit,
+  disableA11yAudit,
+  toggleA11yHighlights,
+  exportA11yReport,
+  resetA11yAudit
+} from './devtools/a11y-audit.js';
+
+const log = createLogger('DevTools');
 
 // =============================================================================
-// PULSE & EFFECT TRACKING
+// TRACKED PULSE WITH SNAPSHOT INTEGRATION
 // =============================================================================
 
-let pulseIdCounter = 0;
-let trackedEffectIdCounter = 0;
-
 /**
- * Create a tracked pulse (for dev tools)
+ * Create a tracked pulse with automatic snapshot on change
  * @param {any} initialValue - Initial value
  * @param {string} [name] - Display name for debugging
  * @returns {Pulse} Tracked pulse
  */
 export function trackedPulse(initialValue, name) {
-  const p = pulse(initialValue);
-  const id = `pulse_${++pulseIdCounter}`;
-
-  pulseRegistry.set(id, {
-    pulse: p,
-    name: name || id,
-    createdAt: Date.now()
-  });
-
-  // Wrap set to record snapshots
-  const originalSet = p.set.bind(p);
-  p.set = (value) => {
-    const result = originalSet(value);
-    if (config.enabled && config.logUpdates) {
-      console.log(`[Pulse] ${name || id} updated:`, value);
-    }
-    if (config.enabled && !isTimeTraveling) {
-      takeSnapshot(`${name || id} = ${JSON.stringify(value)}`);
-    }
-    return result;
-  };
-
-  // Add dispose method
-  p.dispose = () => {
-    pulseRegistry.delete(id);
-  };
-
-  return p;
-}
-
-/**
- * Create a tracked effect (for dev tools)
- * @param {function} fn - Effect function
- * @param {string} [name] - Display name for debugging
- * @returns {function} Dispose function
- */
-export function trackedEffect(fn, name) {
-  const id = `effect_${++trackedEffectIdCounter}`;
-  const startTime = Date.now();
-
-  const entry = {
-    effect: null,
-    name: name || id,
-    createdAt: startTime,
-    runCount: 0,
-    totalTime: 0
-  };
-
-  effectRegistry.set(id, entry);
-
-  const wrappedFn = () => {
-    const runStart = performance.now();
-
-    if (config.enabled && config.logEffects) {
-      console.log(`[Effect] ${name || id} running...`);
-    }
-
-    const result = fn();
-
-    const runTime = performance.now() - runStart;
-    entry.runCount++;
-    entry.totalTime += runTime;
-
-    if (config.enabled && config.warnOnSlowEffects && runTime > config.slowEffectThreshold) {
-      console.warn(`[Effect] ${name || id} took ${runTime.toFixed(2)}ms (slow)`);
+  return basedTrackedPulse(initialValue, name, {
+    onSnapshot: (action) => {
+      if (!getIsTimeTraveling()) {
+        takeSnapshot(action);
+      }
     }
-
-    return result;
-  };
-
-  const dispose = effect(wrappedFn, { id });
-
-  // Store reference to effect for graph building
-  entry.effect = context.currentEffect;
-
-  return () => {
-    dispose();
-    effectRegistry.delete(id);
-  };
+  });
 }
 
 // =============================================================================
@@ -474,24 +95,47 @@ export function trackedEffect(fn, name) {
 export function enableDevTools(options = {}) {
   Object.assign(config, options, { enabled: true });
 
+  if (options.maxSnapshots) {
+    timeTravelConfig.maxSnapshots = options.maxSnapshots;
+  }
+
   if (typeof window !== 'undefined') {
     // Expose to window for browser dev tools
     window.__PULSE_DEVTOOLS__ = {
+      // Diagnostics
       getDiagnostics,
       getEffectStats,
       getPulseList,
       getDependencyGraph,
       exportGraphAsDot,
+      profile,
+      mark,
+
+      // Time-travel
       takeSnapshot,
       getHistory,
       travelTo,
       back,
       forward,
       clearHistory,
-      config
+
+      // A11y Audit
+      runA11yAudit,
+      getA11yIssues,
+      getA11yStats,
+      enableA11yAudit,
+      disableA11yAudit,
+      toggleA11yHighlights,
+      exportA11yReport,
+      resetA11yAudit,
+
+      // Config
+      config,
+      timeTravelConfig,
+      a11yAuditConfig
     };
 
-    console.log('[Pulse DevTools] Enabled. Access via window.__PULSE_DEVTOOLS__');
+    log.info('Enabled. Access via window.__PULSE_DEVTOOLS__');
   }
 }
 
@@ -504,6 +148,8 @@ export function disableDevTools() {
   if (typeof window !== 'undefined') {
     delete window.__PULSE_DEVTOOLS__;
   }
+
+  log.info('Disabled');
 }
 
 /**
@@ -520,67 +166,58 @@ export function isDevToolsEnabled() {
  */
 export function configureDevTools(options) {
   Object.assign(config, options);
+
+  if (options.maxSnapshots) {
+    timeTravelConfig.maxSnapshots = options.maxSnapshots;
+  }
 }
 
 /**
  * Clear all dev tools data
  */
 export function resetDevTools() {
-  pulseRegistry.clear();
-  effectRegistry.clear();
-  stateHistory.length = 0;
-  historyIndex = -1;
-  pulseIdCounter = 0;
-  trackedEffectIdCounter = 0;
+  resetDiagnostics();
+  clearHistory();
+  resetA11yAudit();
 }
 
 // =============================================================================
-// PERFORMANCE PROFILING
+// RE-EXPORTS
 // =============================================================================
 
-/**
- * Profile a section of code
- * @param {string} name - Profile name
- * @param {function} fn - Function to profile
- * @returns {any} Result of fn
- *
- * @example
- * const result = profile('data-processing', () => {
- *   return processLargeDataset();
- * });
- */
-export function profile(name, fn) {
-  const start = performance.now();
-
-  try {
-    return fn();
-  } finally {
-    const duration = performance.now() - start;
-    console.log(`[Profile] ${name}: ${duration.toFixed(2)}ms`);
-  }
-}
+export {
+  // Diagnostics
+  getDiagnostics,
+  getEffectStats,
+  getPulseList,
+  getDependencyGraph,
+  exportGraphAsDot,
+  trackedEffect,
+  profile,
+  mark,
 
-/**
- * Create a performance marker
- * @param {string} name - Marker name
- * @returns {{end: function(): number}} Marker with end method
- */
-export function mark(name) {
-  const start = performance.now();
-
-  return {
-    end() {
-      const duration = performance.now() - start;
-      if (config.enabled) {
-        console.log(`[Mark] ${name}: ${duration.toFixed(2)}ms`);
-      }
-      return duration;
-    }
-  };
-}
+  // Time-travel
+  takeSnapshot,
+  getHistory,
+  getHistoryIndex,
+  travelTo,
+  back,
+  forward,
+  clearHistory,
+
+  // A11y Audit
+  runA11yAudit,
+  getA11yIssues,
+  getA11yStats,
+  enableA11yAudit,
+  disableA11yAudit,
+  toggleA11yHighlights,
+  exportA11yReport,
+  resetA11yAudit
+};
 
 // =============================================================================
-// EXPORTS
+// DEFAULT EXPORT
 // =============================================================================
 
 export default {
@@ -588,10 +225,12 @@ export default {
   getDiagnostics,
   getEffectStats,
   getPulseList,
-
-  // Graph
   getDependencyGraph,
   exportGraphAsDot,
+  trackedPulse,
+  trackedEffect,
+  profile,
+  mark,
 
   // Time-travel
   takeSnapshot,
@@ -602,10 +241,6 @@ export default {
   forward,
   clearHistory,
 
-  // Tracking
-  trackedPulse,
-  trackedEffect,
-
   // Configuration
   enableDevTools,
   disableDevTools,
@@ -613,7 +248,13 @@ export default {
   configureDevTools,
   resetDevTools,
 
-  // Profiling
-  profile,
-  mark
+  // Accessibility Audit
+  runA11yAudit,
+  getA11yIssues,
+  getA11yStats,
+  enableA11yAudit,
+  disableA11yAudit,
+  toggleA11yHighlights,
+  exportA11yReport,
+  resetA11yAudit
 };