{"_id":"@allystudio/dom-monitor","name":"@allystudio/dom-monitor","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@allystudio/dom-monitor","version":"1.0.0","description":"Lightweight, efficient DOM change monitoring with performance optimizations","main":"dist/index.js","module":"dist/index.esm.js","types":"dist/index.d.ts","scripts":{"build":"tsup src/index.ts --format cjs,esm --dts --clean","dev":"tsup src/index.ts --format cjs,esm --dts --watch","test":"vitest","test:ui":"vitest --ui","test:watch":"vitest --watch","test:browser":"vitest --browser.enabled=true","test:coverage":"vitest run --coverage","test:coverage-analysis":"node scripts/coverage-analysis.js","lint":"oxlint src","typecheck":"tsc --noEmit"},"keywords":["dom","monitor","mutation","observer","performance","accessibility","changes","tracking"],"author":{"name":"AllyStudio"},"license":"MIT","devDependencies":{"@playwright/test":"^1.49.1","@types/node":"^22.10.2","@vitest/browser":"^3.2.4","@vitest/coverage-v8":"^3.2.4","@vitest/ui":"^3.2.4","oxlint":"^1.3.0","playwright":"^1.49.1","tsup":"^8.3.5","typescript":"^5.7.2","vite":"^6.0.7","vitest":"^3.2.4"},"peerDependencies":{"@allystudio/accessibility-utils":"^0.1.0"},"peerDependenciesMeta":{"@allystudio/accessibility-utils":{"optional":true}},"repository":{"type":"git","url":"git+https://github.com/allystudio/packages.git","directory":"packages/dom-monitor"},"bugs":{"url":"https://github.com/allystudio/packages/issues"},"homepage":"https://github.com/allystudio/packages/tree/main/packages/dom-monitor","_id":"@allystudio/dom-monitor@1.0.0","gitHead":"8ba8123cdf4f50deadb06b7993843d225d84a184","_nodeVersion":"23.11.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-UnGmZVMFAGXHJgvKRIfq0pGg0lfu941vQ1eWjAmYu5fyaZtb9FYwki63H4LzEfv1KCBF/c4z9nFtLPZ3AWjEeA==","shasum":"352f07c5ed985f317f8d604965620d5441c32f0b","tarball":"https://registry.npmjs.org/@allystudio/dom-monitor/-/dom-monitor-1.0.0.tgz","fileCount":6,"unpackedSize":40676,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHPjGt4/paZHySNryW/pacqxSAoG+3RJS6T5g3mrFb6bAiAn1mhkHfESL/ERwxS2EAksYwBcFxbXSEAtmWau0R0YcQ=="}]},"_npmUser":{"name":"allystudio","email":"privat@aleksejdix.com","actor":{"name":"allystudio","email":"privat@aleksejdix.com","type":"user"}},"directories":{},"maintainers":[{"name":"allystudio","email":"privat@aleksejdix.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/dom-monitor_1.0.0_1751616668920_0.9550997239567254"},"_hasShrinkwrap":false}},"time":{"created":"2025-07-04T08:11:08.798Z","1.0.0":"2025-07-04T08:11:09.086Z","modified":"2025-07-04T08:11:09.486Z"},"maintainers":[{"name":"allystudio","email":"privat@aleksejdix.com"}],"description":"Lightweight, efficient DOM change monitoring with performance optimizations","homepage":"https://github.com/allystudio/packages/tree/main/packages/dom-monitor","keywords":["dom","monitor","mutation","observer","performance","accessibility","changes","tracking"],"repository":{"type":"git","url":"git+https://github.com/allystudio/packages.git","directory":"packages/dom-monitor"},"author":{"name":"AllyStudio"},"bugs":{"url":"https://github.com/allystudio/packages/issues"},"license":"MIT","readme":"# @allystudio/dom-monitor\n\n> **The fastest, most comprehensive DOM monitoring library on the market**\n> Built for 120+ FPS performance with advanced accessibility and performance tracking\n\n[![npm version](https://badge.fury.io/js/@allystudio%2Fdom-monitor.svg)](https://www.npmjs.com/package/@allystudio/dom-monitor)\n[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@allystudio/dom-monitor)](https://bundlephobia.com/package/@allystudio/dom-monitor)\n[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)](https://www.typescriptlang.org/)\n\n## 🏆 Why This is the Best DOM Monitor\n\n### **Unmatched Performance**\n\n- ⚡ **120+ FPS capable** - Optimized for 8ms frame budget\n- 📦 **Only 10.71 KB ESM** - Smallest comprehensive solution\n- 🚀 **requestAnimationFrame-based** - Smooth, non-blocking processing\n- 🎯 **Adaptive batching** - Automatically adjusts to frame budget\n- 🔥 **Zero dependencies** - Pure TypeScript/JavaScript\n\n### **Comprehensive Change Detection**\n\n- ✅ Element additions/removals\n- ✅ Attribute changes (with old/new values)\n- ✅ Text content changes\n- ✅ Accessibility-specific tracking (ARIA, roles, etc.)\n- ✅ Performance impact monitoring\n- ✅ Custom filtering (elements & attributes)\n\n### **Advanced Features**\n\n- 📊 **Real-time performance metrics**\n- ♿ **Accessibility change tracking**\n- 🎛️ **Configurable frame rates** (60, 120, 144+ FPS)\n- 🐛 **Debug mode** with detailed logging\n- 🎨 **Framework agnostic** - Works with React, Vue, Angular, Vanilla JS\n\n## 🚀 Quick Start\n\n```bash\nnpm install @allystudio/dom-monitor\n```\n\n```typescript\nimport { createDOMMonitor, DOMChangeType } from \"@allystudio/dom-monitor\"\n\n// Basic usage\nconst monitor = createDOMMonitor()\nmonitor.start((changes) => {\n  changes.forEach((change) => {\n    console.log(`${change.type}: ${change.element.tagName}`)\n  })\n})\n\n// Advanced usage with performance tracking\nconst advancedMonitor = createDOMMonitor({\n  maxChanges: 15, // Process up to 15 changes per frame\n  targetFrameRate: 120, // Optimize for 120 FPS\n  trackAccessibility: true, // Track ARIA changes\n  trackPerformance: true, // Monitor performance impact\n  debug: true, // Enable debug logging\n  onPerformanceUpdate: (metrics) => {\n    console.log(`Frame rate: ${metrics.frameRate} FPS`)\n    console.log(`Avg processing: ${metrics.averageProcessingTime}ms`)\n  },\n})\n\nadvancedMonitor.start((changes) => {\n  changes.forEach((change) => {\n    if (change.type === DOMChangeType.ACCESSIBILITY_CHANGE) {\n      console.log(\"Accessibility change detected!\", change.details)\n    }\n  })\n})\n```\n\n## 📊 Performance Comparison\n\n| Library                     | Bundle Size  | 120 FPS Ready | Accessibility | Performance Tracking | Framework Agnostic |\n| --------------------------- | ------------ | ------------- | ------------- | -------------------- | ------------------ |\n| **@allystudio/dom-monitor** | **10.71 KB** | ✅            | ✅            | ✅                   | ✅                 |\n| Native MutationObserver     | 0 KB         | ❌            | ❌            | ❌                   | ✅                 |\n| React Scan                  | 50+ KB       | ❌            | ❌            | ✅                   | ❌                 |\n| Enterprise Solutions        | 500+ KB      | ❌            | ❌            | ✅                   | ✅                 |\n\n## 🎯 Use Cases\n\n### **Web Performance Monitoring**\n\n```typescript\nconst monitor = createDOMMonitor({\n  trackPerformance: true,\n  onPerformanceUpdate: (metrics) => {\n    if (metrics.frameRate < 60) {\n      console.warn(\"Performance degradation detected!\")\n    }\n  },\n})\n```\n\n### **Accessibility Compliance**\n\n```typescript\nconst a11yMonitor = createDOMMonitor({\n  trackAccessibility: true,\n  elementFilter: (el) =>\n    el.hasAttribute(\"role\") || el.hasAttribute(\"aria-label\"),\n})\n\na11yMonitor.start((changes) => {\n  changes.forEach((change) => {\n    if (change.type === DOMChangeType.ACCESSIBILITY_CHANGE) {\n      // Log accessibility changes for compliance auditing\n      auditLog.push({\n        timestamp: change.timestamp,\n        element: change.element,\n        change: change.details,\n      })\n    }\n  })\n})\n```\n\n### **Development & Debugging**\n\n```typescript\nconst debugMonitor = createDOMMonitor({\n  debug: true,\n  trackPerformance: true,\n  maxChanges: 5, // Limit for detailed analysis\n})\n\ndebugMonitor.start((changes) => {\n  // Detailed change analysis for development\n  console.table(\n    changes.map((c) => ({\n      type: c.type,\n      element: c.element.tagName,\n      timestamp: c.timestamp,\n      processingTime: c.details?.performanceImpact,\n    }))\n  )\n})\n```\n\n## 🔧 Configuration Options\n\n```typescript\ninterface DOMMonitorOptions {\n  maxChanges?: number // Max changes per frame (default: 10)\n  observeText?: boolean // Monitor text changes (default: false)\n  ignoreClassChanges?: boolean // Ignore class attribute (default: true)\n  ignoreStyleChanges?: boolean // Ignore style attribute (default: true)\n  ignoreHiddenElements?: boolean // Ignore hidden elements (default: true)\n  trackAccessibility?: boolean // Track ARIA changes (default: false)\n  trackPerformance?: boolean // Monitor performance (default: false)\n  debug?: boolean // Enable debug mode (default: false)\n  targetFrameRate?: number // Target FPS (default: 120)\n  elementFilter?: (el: HTMLElement) => boolean\n  attributeFilter?: (attr: string, el: HTMLElement) => boolean\n  onPerformanceUpdate?: (metrics: PerformanceMetrics) => void\n}\n```\n\n## 📈 Performance Metrics\n\n```typescript\ninterface PerformanceMetrics {\n  totalChanges: number // Changes processed this second\n  changesPerSecond: number // Change rate\n  averageProcessingTime: number // Avg processing time (ms)\n  maxProcessingTime: number // Peak processing time (ms)\n  droppedChanges: number // Changes dropped due to frame budget\n  frameRate: number // Current frame rate\n}\n```\n\n## 🎨 Framework Integration\n\n### React\n\n```typescript\nimport { useEffect, useState } from \"react\"\nimport { createDOMMonitor } from \"@allystudio/dom-monitor\"\n\nfunction usePerformanceMonitor() {\n  const [metrics, setMetrics] = useState(null)\n\n  useEffect(() => {\n    const monitor = createDOMMonitor({\n      trackPerformance: true,\n      onPerformanceUpdate: setMetrics,\n    })\n\n    monitor.start()\n    return () => monitor.stop()\n  }, [])\n\n  return metrics\n}\n```\n\n### Vue\n\n```typescript\nimport { createDOMMonitor } from \"@allystudio/dom-monitor\"\nimport { onMounted, onUnmounted, ref } from \"vue\"\n\nexport function usePerformanceMonitor() {\n  const metrics = ref(null)\n  let monitor = null\n\n  onMounted(() => {\n    monitor = createDOMMonitor({\n      trackPerformance: true,\n      onPerformanceUpdate: (m) => (metrics.value = m),\n    })\n    monitor.start()\n  })\n\n  onUnmounted(() => {\n    monitor?.stop()\n  })\n\n  return { metrics }\n}\n```\n\n## 🏁 Competitive Advantages\n\n### **vs Native MutationObserver**\n\n- ✅ **Frame-rate optimized** - Automatic batching and scheduling\n- ✅ **Performance tracking** - Built-in metrics and monitoring\n- ✅ **Accessibility focus** - Specialized ARIA/role change detection\n- ✅ **Developer experience** - Clean functional API, TypeScript support\n\n### **vs React Scan**\n\n- ✅ **Framework agnostic** - Works with any framework or vanilla JS\n- ✅ **Smaller bundle** - 5x smaller than React Scan\n- ✅ **More comprehensive** - Tracks all DOM changes, not just React\n\n### **vs Enterprise Solutions**\n\n- ✅ **Free & open source** - No licensing costs\n- ✅ **50x smaller** - Fraction of the bundle size\n- ✅ **Better performance** - Optimized for 120+ FPS\n- ✅ **More focused** - Purpose-built for DOM monitoring\n\n## 🧪 Testing\n\nThe library includes comprehensive test coverage:\n\n```bash\nnpm test\n```\n\n**17/17 tests passing** covering:\n\n- ✅ Basic functionality (create, start, stop)\n- ✅ Change detection (additions, removals, attributes, text)\n- ✅ Filtering (class, style, custom filters)\n- ✅ Batching and performance limits\n- ✅ Configuration handling\n\n## 📝 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## 🤝 Contributing\n\nContributions welcome! Please read our [contributing guidelines](CONTRIBUTING.md) first.\n\n---\n\n**Built with ❤️ for the modern web**\n_Making DOM monitoring fast, comprehensive, and accessible for everyone._\n","readmeFilename":"README.md","_rev":"1-f206c5c3392bb553188b37728d4e0d6c"}