@aporialab/overdraw-audit

CSS glass-effect overdraw auditor — find exactly which elements are killing your GPU performance.

Features · Installation · CLI · API · Scoring · Lighthouse Plugin

The Problem

Modern glassmorphism UIs look stunning. They also silently destroy GPU performance on mid-range devices.

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.

Most 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.

Features

• Real browser analysis via Puppeteer — no guessing from source code; the page is actually rendered and composited layers are inspected
• GPU overdraw heatmap — visual HTML/PNG output showing overdraw intensity per region
• 35 automated tests covering blur, backdrop-filter, box-shadow, opacity stacking, mix-blend-mode, and filter combinations
• DealScore-style composite scoring — single 0–100 score summarising overdraw severity, normalized by viewport and element count
• Lighthouse plugin — drop-in integration for CI pipelines via lighthouse-plugin-overdraw
• Per-element breakdown — overdraw factor, CSS properties responsible, suggested fixes, and estimated GPU savings
• JSON, HTML, and stdout report formats

Installation

npm install @aporialab/overdraw-audit

yarn add @aporialab/overdraw-audit

pnpm add @aporialab/overdraw-audit

For global CLI access:

npm install -g @aporialab/overdraw-audit

Requirements: Node.js >= 18.0.0, Chromium (installed automatically by Puppeteer)

CLI Usage

Audit a URL

npx overdraw-audit https://example.com

Audit a local file

npx overdraw-audit ./dist/index.html

Generate an HTML heatmap report

npx overdraw-audit https://example.com --report heatmap.html

Output raw JSON

npx overdraw-audit https://example.com --format json --output audit.json

Set viewport

npx overdraw-audit https://example.com --width 1440 --height 900

Fail CI if score is below threshold

npx overdraw-audit https://example.com --fail-under 70
# exits with code 1 if score < 70

Full example with all flags

npx overdraw-audit https://my-app.com \
  --width 1440 \
  --height 900 \
  --report report.html \
  --format json \
  --output audit.json \
  --fail-under 65 \
  --verbose

Verbose output example

overdraw-audit v2.0.0 — Aporia Labs

Launching browser...
Navigating to https://my-app.com
Running 35 overdraw tests...

  [PASS]  backdrop-filter isolation on .modal-overlay
  [FAIL]  .sidebar-glass — backdrop-filter: blur(24px) with no will-change: transform
          Overdraw factor: 3.8x | Affected area: 18% viewport | Severity: HIGH
  [FAIL]  .card-stack .card:nth-child(n) — stacked box-shadow (4 layers)
          Overdraw factor: 2.1x | Affected area: 34% viewport | Severity: MEDIUM
  [PASS]  .nav-bar — blur promoted to own compositor layer
  [WARN]  .hero-bg — filter: blur(60px) on element > 80% viewport width
          Overdraw factor: 1.6x | Affected area: 82% viewport | Severity: LOW-MEDIUM

Composite Score: 58 / 100  [NEEDS WORK]

Top 3 offenders:
  1. .sidebar-glass          — 3.8x overdraw, 18% viewport
  2. .card-stack .card       — 2.1x overdraw, 34% viewport  
  3. .hero-bg                — 1.6x overdraw, 82% viewport

Report written to: report.html

API Usage

import { OverdrawAuditor } from '@aporialab/overdraw-audit';

const auditor = new OverdrawAuditor({
  url: 'https://example.com',
  viewport: { width: 1440, height: 900 },
  headless: true,
});

const result = await auditor.run();

console.log(result.score);        // 58
console.log(result.grade);        // 'C'
console.log(result.offenders);    // Array of OffenderReport

for (const item of result.offenders) {
  console.log(`${item.selector}: ${item.overdrawFactor}x overdraw`);
  console.log(`  Cause: ${item.properties.join(', ')}`);
  console.log(`  Fix:   ${item.suggestion}`);
}

OffenderReport shape

interface OffenderReport {
  selector: string;
  overdrawFactor: number;       // e.g. 3.8 — pixels written per screen pixel
  affectedArea: number;         // fraction of viewport (0.0 – 1.0)
  severity: 'LOW' | 'LOW-MEDIUM' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
  properties: string[];         // CSS properties responsible
  suggestion: string;           // human-readable fix
  estimatedGpuSavingMs: number; // estimated frame time saved if fixed
}

Generate an HTML report programmatically

import { OverdrawAuditor, generateHeatmapReport } from '@aporialab/overdraw-audit';

const auditor = new OverdrawAuditor({ url: 'https://example.com' });
const result = await auditor.run();

await generateHeatmapReport(result, './overdraw-report.html');
console.log('Heatmap written to overdraw-report.html');

Score Interpretation

The composite score (0–100) normalises overdraw severity, affected viewport area, and element count into a single number comparable across projects.

| Score | Grade | Meaning | |-------|-------|---------| | 90–100 | A | Excellent — GPU load from glass effects is well controlled | | 75–89 | B | Good — minor overdraw present, not impactful on modern hardware | | 60–74 | C | Needs work — noticeable on mid-range mobile devices | | 40–59 | D | Poor — users on integrated GPUs will experience jank | | 0–39 | F | Critical — significant compositing issues, address immediately |

What counts against your score

| Factor | Weight | |--------|--------| | backdrop-filter with no compositor promotion | 30% | | Stacked box-shadow (3+ layers) | 20% | | Large blurred elements (>50% viewport) | 20% | | filter on non-promoted layers | 15% | | mix-blend-mode on animated elements | 10% | | Transparent background without isolation: isolate | 5% |

Lighthouse Plugin

Install the plugin and add it to your Lighthouse config:

npm install --save-dev @aporialab/overdraw-audit

// lighthouserc.js
module.exports = {
  ci: {
    collect: {
      url: ['https://my-app.com'],
    },
    assert: {
      assertions: {
        'categories:overdraw': ['error', { minScore: 0.7 }],
      },
    },
  },
  plugins: ['@aporialab/overdraw-audit/lighthouse-plugin'],
};

The plugin adds an Overdraw category to your Lighthouse report with the same 0–100 score, heatmap thumbnail, and per-element findings.

Common Fixes

Add will-change: transform to composited layers

/* Before */
.glass-panel {
  backdrop-filter: blur(20px);
}

/* After — promotes to own GPU layer */
.glass-panel {
  backdrop-filter: blur(20px);
  will-change: transform;
}

Use isolation: isolate to contain stacking contexts

.card-container {
  isolation: isolate; /* prevents children from blending into background */
}

Reduce blur radius on large elements

/* Before — 60px blur on full-width hero causes extreme overdraw */
.hero { backdrop-filter: blur(60px); }

/* After — smaller radius, same visual effect at lower cost */
.hero { backdrop-filter: blur(8px); }

Contributing

1. Fork: github.com/AporiaLab/overdraw-audit
2. Branch: git checkout -b feat/your-feature
3. The test suite has 35 tests — all must pass: npm test
4. For new overdraw patterns, add a fixture page in test/fixtures/ and a corresponding test in test/
5. Submit a pull request

git clone https://github.com/AporiaLab/overdraw-audit.git
cd overdraw-audit
npm install
npm test

Support the Project

If this tool helped you ship a faster UI, consider a Bitcoin donation to keep it maintained:

Bitcoin:

bc1q9wpg3nrg5kywxlkkzsdd4lwkrfgd5j84jdpmjm

License

MIT License — Copyright (c) 2025 Aporia Labs

Permission 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:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE 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.