{"_id":"@aporialab/overdraw-audit","_rev":"3-76090c36480c3fc5a3ae8aad76fb1171","name":"@aporialab/overdraw-audit","dist-tags":{"latest":"2.0.2"},"versions":{"2.0.0":{"name":"@aporialab/overdraw-audit","version":"2.0.0","keywords":["overdraw","backdrop-filter","glassmorphism","blur","css-performance","gpu","lighthouse","audit","cli","performance","devtools","vite-plugin","webpack-plugin","puppeteer","heatmap","stacking-context","css-audit","web-performance","aporia-labs","aporia"],"author":{"name":"Aporia Labs","email":"hello@aporialabs.dev"},"license":"MIT","_id":"@aporialab/overdraw-audit@2.0.0","maintainers":[{"name":"aporialab","email":"aporia_lab@proton.me"}],"homepage":"https://overdraw.v2app.ru","bugs":{"url":"https://github.com/YOUR_USERNAME/overdraw-audit/issues"},"bin":{"overdraw-audit":"bin/overdraw-audit.js"},"dist":{"shasum":"b21fd972b84d630f599756762b96f761d65a4cb3","tarball":"https://registry.npmjs.org/@aporialab/overdraw-audit/-/overdraw-audit-2.0.0.tgz","fileCount":14,"integrity":"sha512-2+zHqq38285hcbUnWbqJggziKq1ikd8uokU23c9fPv8uQBGgpYY2scAQZRofuhNwGws7b2w6Qwb2JCS+WBVUYw==","signatures":[{"sig":"MEUCIGVT7ZyeUcEuf9wWITximW490Ash/lG4GO6OqAS9IqXBAiEA54TbawmlX5PDsxajRovyQnaDj+nZKz7kSTmzRD6xa2M=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":136281},"type":"module","engines":{"node":">=18.0.0"},"exports":{".":"./lib/scorer.js","./vite":"./plugins/vite-plugin.js","./browser":"./lib/puppeteer-fetcher.js","./heatmap":"./lib/heatmap.js","./webpack":"./plugins/webpack-plugin.js","./site-awareness":"./lib/site-awareness.js"},"gitHead":"12ab1b63f2ec889b076677d284b4c6b3051fa266","scripts":{"demo":"node bin/overdraw-audit.js https://linear.app --html --browser","test":"node --experimental-vm-modules node_modules/.bin/jest test/cli-v2.test.js --no-coverage 2>/dev/null || node --test test/cli-v2.test.js","audit":"node bin/overdraw-audit.js","test:watch":"node --test --watch test/cli-v2.test.js","audit:browser":"node bin/overdraw-audit.js --browser"},"_npmUser":{"name":"aporialab","email":"aporia_lab@proton.me"},"repository":{"url":"git+https://github.com/aporia-labs/overdraw-audit.git","type":"git"},"_npmVersion":"10.8.2","description":"CSS glass-effect overdraw auditor — real browser analysis, heatmap, Vite/Webpack plugin, site awareness","directories":{},"_nodeVersion":"20.20.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"optionalDependencies":{"puppeteer":"^21.11.0"},"_npmOperationalInternal":{"tmp":"tmp/overdraw-audit_2.0.0_1771872460631_0.1352218106327534","host":"s3://npm-registry-packages-npm-production"}},"2.0.1":{"name":"@aporialab/overdraw-audit","version":"2.0.1","keywords":["overdraw","backdrop-filter","glassmorphism","blur","css-performance","gpu","lighthouse","audit","cli","performance","devtools","vite-plugin","webpack-plugin","puppeteer","heatmap","stacking-context","css-audit","web-performance","aporia-labs","aporia"],"author":{"name":"Aporia Labs","email":"hello@aporialabs.dev"},"license":"MIT","_id":"@aporialab/overdraw-audit@2.0.1","maintainers":[{"name":"aporialab","email":"aporia_lab@proton.me"}],"homepage":"https://overdraw.v2app.ru","bugs":{"url":"https://github.com/YOUR_USERNAME/overdraw-audit/issues"},"bin":{"overdraw-audit":"bin/overdraw-audit.js"},"dist":{"shasum":"e3084a816d2d02aaa691dd8acaa7ee9c06d09017","tarball":"https://registry.npmjs.org/@aporialab/overdraw-audit/-/overdraw-audit-2.0.1.tgz","fileCount":14,"integrity":"sha512-6iaGtn/oHtSyGsxzfW6DnQ4L9rucTrolnC9KDU/AIi8CYFwGgbUtBZWmXq6YBR5NlhXuxBlsDOjC2aqJdnQW/A==","signatures":[{"sig":"MEUCIBrFhBAtHukPho5rG1h5I7+HHCzbA3ga1pBOJKj5mXZQAiEA5mXkzRlmEaX49nJc3p2tvrbqFJjDZeiSgdTmodSidW0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":140339},"type":"module","engines":{"node":">=18.0.0"},"exports":{".":"./lib/scorer.js","./vite":"./plugins/vite-plugin.js","./browser":"./lib/puppeteer-fetcher.js","./heatmap":"./lib/heatmap.js","./webpack":"./plugins/webpack-plugin.js","./site-awareness":"./lib/site-awareness.js"},"gitHead":"0461294448df4b69cb766b46374a41a8fe22f603","scripts":{"demo":"node bin/overdraw-audit.js https://linear.app --html --browser","test":"node --experimental-vm-modules node_modules/.bin/jest test/cli-v2.test.js --no-coverage 2>/dev/null || node --test test/cli-v2.test.js","audit":"node bin/overdraw-audit.js","test:watch":"node --test --watch test/cli-v2.test.js","audit:browser":"node bin/overdraw-audit.js --browser"},"_npmUser":{"name":"aporialab","email":"aporia_lab@proton.me"},"repository":{"url":"git+https://github.com/aporia-labs/overdraw-audit.git","type":"git"},"_npmVersion":"10.8.2","description":"CSS glass-effect overdraw auditor — real browser analysis, heatmap, Vite/Webpack plugin, site awareness","directories":{},"_nodeVersion":"20.20.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"optionalDependencies":{"puppeteer":"^21.11.0"},"_npmOperationalInternal":{"tmp":"tmp/overdraw-audit_2.0.1_1771872816308_0.9971750925452099","host":"s3://npm-registry-packages-npm-production"}},"2.0.2":{"name":"@aporialab/overdraw-audit","version":"2.0.2","description":"CSS glass-effect overdraw auditor — real browser analysis, heatmap, Vite/Webpack plugin, site awareness","author":{"name":"Aporia Labs","email":"hello@aporialabs.dev"},"keywords":["overdraw","backdrop-filter","glassmorphism","blur","css-performance","gpu","lighthouse","audit","cli","performance","devtools","vite-plugin","webpack-plugin","puppeteer","heatmap","stacking-context","css-audit","web-performance","aporia-labs","aporia"],"homepage":"https://overdraw.v2app.ru","repository":{"type":"git","url":"git+https://github.com/aporia-labs/overdraw-audit.git"},"bugs":{"url":"https://github.com/YOUR_USERNAME/overdraw-audit/issues"},"license":"MIT","type":"module","bin":{"overdraw-audit":"bin/overdraw-audit.js"},"exports":{".":"./lib/scorer.js","./vite":"./plugins/vite-plugin.js","./webpack":"./plugins/webpack-plugin.js","./heatmap":"./lib/heatmap.js","./site-awareness":"./lib/site-awareness.js","./browser":"./lib/puppeteer-fetcher.js"},"engines":{"node":">=18.0.0"},"scripts":{"test":"node --experimental-vm-modules node_modules/.bin/jest test/cli-v2.test.js --no-coverage 2>/dev/null || node --test test/cli-v2.test.js","test:watch":"node --test --watch test/cli-v2.test.js","audit":"node bin/overdraw-audit.js","audit:browser":"node bin/overdraw-audit.js --browser","demo":"node bin/overdraw-audit.js https://linear.app --html --browser"},"optionalDependencies":{"puppeteer":"^21.11.0"},"publishConfig":{"access":"public"},"_id":"@aporialab/overdraw-audit@2.0.2","gitHead":"19b60f76caa73f17c6c7218c9c48f589ac34f25b","_nodeVersion":"20.20.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-9WvvibWdGuQ2yzw8ut3SAGRdPloUh1sQy+olTyQV3C3M3WWOSzvbCsCVOaZE0vs1kRmX1miBinthyGb3pM8Hqg==","shasum":"ad103968d54e943b6cb5bc9260f39c1ce4aea00a","tarball":"https://registry.npmjs.org/@aporialab/overdraw-audit/-/overdraw-audit-2.0.2.tgz","fileCount":14,"unpackedSize":140339,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIEyzB9dI1T2JcMsX+K9SkL/btvZFu9NecSNLk3KWuWO+AiBkDRtX0zLsAQ9H8PnzI0KHAdkVsrYZtbgzPPTcFS7EkA=="}]},"_npmUser":{"name":"aporialab","email":"aporia_lab@proton.me"},"directories":{},"maintainers":[{"name":"aporialab","email":"aporia_lab@proton.me"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/overdraw-audit_2.0.2_1771874192434_0.5267709563391629"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-23T18:47:40.539Z","modified":"2026-02-23T19:16:32.710Z","2.0.0":"2026-02-23T18:47:40.796Z","2.0.1":"2026-02-23T18:53:36.449Z","2.0.2":"2026-02-23T19:16:32.581Z"},"bugs":{"url":"https://github.com/YOUR_USERNAME/overdraw-audit/issues"},"author":{"name":"Aporia Labs","email":"hello@aporialabs.dev"},"license":"MIT","homepage":"https://overdraw.v2app.ru","keywords":["overdraw","backdrop-filter","glassmorphism","blur","css-performance","gpu","lighthouse","audit","cli","performance","devtools","vite-plugin","webpack-plugin","puppeteer","heatmap","stacking-context","css-audit","web-performance","aporia-labs","aporia"],"repository":{"type":"git","url":"git+https://github.com/aporia-labs/overdraw-audit.git"},"description":"CSS glass-effect overdraw auditor — real browser analysis, heatmap, Vite/Webpack plugin, site awareness","maintainers":[{"name":"aporialab","email":"aporia_lab@proton.me"}],"readme":"\n\n# @aporialab/overdraw-audit\n\n[](https://github.com/AporiaLab)\n[](https://www.npmjs.com/package/@aporialab/overdraw-audit)\n[](LICENSE)\n[](https://github.com/AporiaLab/overdraw-audit/actions)\n[](https://github.com/AporiaLab/overdraw-audit#lighthouse-plugin)\n\n**CSS glass-effect overdraw auditor — find exactly which elements are killing your GPU performance.**\n\n[Features](#features) · [Installation](#installation) · [CLI](#cli-usage) · [API](#api-usage) · [Scoring](#score-interpretation) · [Lighthouse Plugin](#lighthouse-plugin)\n\n
\n\n---\n\n## The Problem\n\nModern glassmorphism UIs look stunning. They also silently destroy GPU performance on mid-range devices.\n\n`backdrop-filter: blur()`, layered `box-shadow`, semi-transparent `background`, and stacked `filter` properties cause the browser to composite multiple layers per pixel — **overdraw**. On a complex page, a single modal can trigger 4–8x overdraw across its bounding rect. Multiply that by a full dashboard and you have jank, heat, and battery drain.\n\nMost tools tell you *that* you have a performance problem. `overdraw-audit` tells you *which elements* are causing it, how bad each one is, and what to do about it.\n\n---\n\n## Features\n\n- **Real browser analysis via Puppeteer** — no guessing from source code; the page is actually rendered and composited layers are inspected\n- **GPU overdraw heatmap** — visual HTML/PNG output showing overdraw intensity per region\n- **35 automated tests** covering blur, backdrop-filter, box-shadow, opacity stacking, mix-blend-mode, and filter combinations\n- **DealScore-style composite scoring** — single 0–100 score summarising overdraw severity, normalized by viewport and element count\n- **Lighthouse plugin** — drop-in integration for CI pipelines via `lighthouse-plugin-overdraw`\n- **Per-element breakdown** — overdraw factor, CSS properties responsible, suggested fixes, and estimated GPU savings\n- **JSON, HTML, and stdout** report formats\n\n---\n\n## Installation\n\n```bash\nnpm install @aporialab/overdraw-audit\n```\n\n```bash\nyarn add @aporialab/overdraw-audit\n```\n\n```bash\npnpm add @aporialab/overdraw-audit\n```\n\nFor global CLI access:\n\n```bash\nnpm install -g @aporialab/overdraw-audit\n```\n\n**Requirements:** Node.js >= 18.0.0, Chromium (installed automatically by Puppeteer)\n\n---\n\n## CLI Usage\n\n### Audit a URL\n\n```bash\nnpx overdraw-audit https://example.com\n```\n\n### Audit a local file\n\n```bash\nnpx overdraw-audit ./dist/index.html\n```\n\n### Generate an HTML heatmap report\n\n```bash\nnpx overdraw-audit https://example.com --report heatmap.html\n```\n\n### Output raw JSON\n\n```bash\nnpx overdraw-audit https://example.com --format json --output audit.json\n```\n\n### Set viewport\n\n```bash\nnpx overdraw-audit https://example.com --width 1440 --height 900\n```\n\n### Fail CI if score is below threshold\n\n```bash\nnpx overdraw-audit https://example.com --fail-under 70\n# exits with code 1 if score < 70\n```\n\n### Full example with all flags\n\n```bash\nnpx overdraw-audit https://my-app.com \\\n --width 1440 \\\n --height 900 \\\n --report report.html \\\n --format json \\\n --output audit.json \\\n --fail-under 65 \\\n --verbose\n```\n\n### Verbose output example\n\n```\noverdraw-audit v2.0.0 — Aporia Labs\n\nLaunching browser...\nNavigating to https://my-app.com\nRunning 35 overdraw tests...\n\n [PASS] backdrop-filter isolation on .modal-overlay\n [FAIL] .sidebar-glass — backdrop-filter: blur(24px) with no will-change: transform\n Overdraw factor: 3.8x | Affected area: 18% viewport | Severity: HIGH\n [FAIL] .card-stack .card:nth-child(n) — stacked box-shadow (4 layers)\n Overdraw factor: 2.1x | Affected area: 34% viewport | Severity: MEDIUM\n [PASS] .nav-bar — blur promoted to own compositor layer\n [WARN] .hero-bg — filter: blur(60px) on element > 80% viewport width\n Overdraw factor: 1.6x | Affected area: 82% viewport | Severity: LOW-MEDIUM\n\nComposite Score: 58 / 100 [NEEDS WORK]\n\nTop 3 offenders:\n 1. .sidebar-glass — 3.8x overdraw, 18% viewport\n 2. .card-stack .card — 2.1x overdraw, 34% viewport \n 3. .hero-bg — 1.6x overdraw, 82% viewport\n\nReport written to: report.html\n```\n\n---\n\n## API Usage\n\n```js\nimport { OverdrawAuditor } from '@aporialab/overdraw-audit';\n\nconst auditor = new OverdrawAuditor({\n url: 'https://example.com',\n viewport: { width: 1440, height: 900 },\n headless: true,\n});\n\nconst result = await auditor.run();\n\nconsole.log(result.score); // 58\nconsole.log(result.grade); // 'C'\nconsole.log(result.offenders); // Array of OffenderReport\n\nfor (const item of result.offenders) {\n console.log(`${item.selector}: ${item.overdrawFactor}x overdraw`);\n console.log(` Cause: ${item.properties.join(', ')}`);\n console.log(` Fix: ${item.suggestion}`);\n}\n```\n\n### `OffenderReport` shape\n\n```ts\ninterface OffenderReport {\n selector: string;\n overdrawFactor: number; // e.g. 3.8 — pixels written per screen pixel\n affectedArea: number; // fraction of viewport (0.0 – 1.0)\n severity: 'LOW' | 'LOW-MEDIUM' | 'MEDIUM' | 'HIGH' | 'CRITICAL';\n properties: string[]; // CSS properties responsible\n suggestion: string; // human-readable fix\n estimatedGpuSavingMs: number; // estimated frame time saved if fixed\n}\n```\n\n### Generate an HTML report programmatically\n\n```js\nimport { OverdrawAuditor, generateHeatmapReport } from '@aporialab/overdraw-audit';\n\nconst auditor = new OverdrawAuditor({ url: 'https://example.com' });\nconst result = await auditor.run();\n\nawait generateHeatmapReport(result, './overdraw-report.html');\nconsole.log('Heatmap written to overdraw-report.html');\n```\n\n---\n\n## Score Interpretation\n\nThe composite score (0–100) normalises overdraw severity, affected viewport area, and element count into a single number comparable across projects.\n\n| Score | Grade | Meaning |\n|-------|-------|---------|\n| 90–100 | A | Excellent — GPU load from glass effects is well controlled |\n| 75–89 | B | Good — minor overdraw present, not impactful on modern hardware |\n| 60–74 | C | Needs work — noticeable on mid-range mobile devices |\n| 40–59 | D | Poor — users on integrated GPUs will experience jank |\n| 0–39 | F | Critical — significant compositing issues, address immediately |\n\n### What counts against your score\n\n| Factor | Weight |\n|--------|--------|\n| `backdrop-filter` with no compositor promotion | 30% |\n| Stacked `box-shadow` (3+ layers) | 20% |\n| Large blurred elements (>50% viewport) | 20% |\n| `filter` on non-promoted layers | 15% |\n| `mix-blend-mode` on animated elements | 10% |\n| Transparent `background` without `isolation: isolate` | 5% |\n\n---\n\n## Lighthouse Plugin\n\nInstall the plugin and add it to your Lighthouse config:\n\n```bash\nnpm install --save-dev @aporialab/overdraw-audit\n```\n\n```js\n// lighthouserc.js\nmodule.exports = {\n ci: {\n collect: {\n url: ['https://my-app.com'],\n },\n assert: {\n assertions: {\n 'categories:overdraw': ['error', { minScore: 0.7 }],\n },\n },\n },\n plugins: ['@aporialab/overdraw-audit/lighthouse-plugin'],\n};\n```\n\nThe plugin adds an **Overdraw** category to your Lighthouse report with the same 0–100 score, heatmap thumbnail, and per-element findings.\n\n---\n\n## Common Fixes\n\n### Add `will-change: transform` to composited layers\n\n```css\n/* Before */\n.glass-panel {\n backdrop-filter: blur(20px);\n}\n\n/* After — promotes to own GPU layer */\n.glass-panel {\n backdrop-filter: blur(20px);\n will-change: transform;\n}\n```\n\n### Use `isolation: isolate` to contain stacking contexts\n\n```css\n.card-container {\n isolation: isolate; /* prevents children from blending into background */\n}\n```\n\n### Reduce blur radius on large elements\n\n```css\n/* Before — 60px blur on full-width hero causes extreme overdraw */\n.hero { backdrop-filter: blur(60px); }\n\n/* After — smaller radius, same visual effect at lower cost */\n.hero { backdrop-filter: blur(8px); }\n```\n\n---\n\n## Contributing\n\n1. Fork: [github.com/AporiaLab/overdraw-audit](https://github.com/AporiaLab/overdraw-audit)\n2. Branch: `git checkout -b feat/your-feature`\n3. The test suite has 35 tests — all must pass: `npm test`\n4. For new overdraw patterns, add a fixture page in `test/fixtures/` and a corresponding test in `test/`\n5. Submit a pull request\n\n```bash\ngit clone https://github.com/AporiaLab/overdraw-audit.git\ncd overdraw-audit\nnpm install\nnpm test\n```\n\n---\n\n## Support the Project\n\nIf this tool helped you ship a faster UI, consider a Bitcoin donation to keep it maintained:\n\n**Bitcoin:**\n```\nbc1q9wpg3nrg5kywxlkkzsdd4lwkrfgd5j84jdpmjm\n```\n\n[](https://blockchain.info/address/bc1q9wpg3nrg5kywxlkkzsdd4lwkrfgd5j84jdpmjm)\n\n---\n\n## License\n\nMIT License — Copyright (c) 2025 Aporia Labs\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\n---\n\n\n","readmeFilename":"README.md"}