@badreddinekarama/csspow 0.1.0

package/bin/csspow.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * csspoison — CSS Chaos Engineering CLI
+ * Author: Badreddine Karama
+ * Usage: npx csspoison run <url> [options]
+ */
+
+import { program } from 'commander';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { readFileSync } from 'fs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+let version;
+try {
+  const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+  version = pkg.version;
+} catch {
+  version = '0.1.0';
+}
+
+program
+  .name('csspoison')
+  .description('☣  CSS chaos engineering — stress-test your UI in seconds\n  by Badreddine Karama')
+  .version(version);
+
+program
+  .command('run <url>')
+  .description('Run CSS chaos modes against a URL')
+  .option('-m, --mode <preset>', 'Preset to use: light | chaos | brutal | a11y', 'chaos')
+  .option('--modes <list>', 'Comma-separated modes: rtl,zoom,font-chaos,etc')
+  .option('--record', 'Save screenshots and generate HTML report', false)
+  .option('--headless', 'Run in headless mode (default: true)', true)
+  .option('--no-headless', 'Show the browser window')
+  .option('--output <dir>', 'Output directory for report', './csspoison-report')
+  .option('--timeout <ms>', 'Page load timeout in milliseconds', '30000')
+  .action(async (url, opts) => {
+    const { run } = await import('../src/run.js');
+    await run(url, opts);
+  });
+
+program
+  .command('modes')
+  .description('List all available chaos modes')
+  .action(async () => {
+    const { listModes } = await import('../src/list-modes.js');
+    listModes();
+  });
+
+program
+  .command('presets')
+  .description('List all available presets')
+  .action(async () => {
+    const { listPresets } = await import('../src/list-presets.js');
+    listPresets();
+  });
+
+program.parse();

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@badreddinekarama/csspow",
+  "version": "0.1.0",
+  "description": "Zero-install CLI for CSS chaos testing — stress-test your UI in seconds",
+  "author": "Badreddine Karama",
+  "type": "module",
+  "bin": {
+    "csspow": "./bin/csspow.js"
+  },
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node bin/csspow.js",
+    "test": "echo \"No tests yet\"",
+    "lint": "eslint src/**/*.js"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "playwright": "^1.52.0",
+    "chalk": "^5.4.1",
+    "ora": "^8.2.0"
+  },
+  "keywords": ["css", "testing", "chaos", "playwright", "ui-testing", "cli", "accessibility"],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/core.js

@@ -0,0 +1,206 @@
+/**
+ * csspow — CSS Chaos Engine
+ * Author: Badreddine Karama
+ *
+ * Pure JS poison engine — safe to inject into any browser context.
+ * No Node.js APIs used here.
+ */
+
+export const MODES = {
+  rtl: {
+    name: 'RTL Flip',
+    description: 'Forces right-to-left text direction on the entire page',
+    category: 'layout',
+    apply(ctx) {
+      ctx.originalDir = document.documentElement.dir;
+      document.documentElement.dir = 'rtl';
+    },
+    revert(ctx) {
+      document.documentElement.dir = ctx.originalDir || '';
+    },
+  },
+
+  zoom: {
+    name: '200% Zoom',
+    description: 'Doubles the browser zoom level, exposing layout overflow issues',
+    category: 'viewport',
+    apply(ctx) {
+      ctx.originalZoom = document.body.style.zoom;
+      document.body.style.zoom = '200%';
+    },
+    revert(ctx) {
+      document.body.style.zoom = ctx.originalZoom || '';
+    },
+  },
+
+  'font-chaos': {
+    name: 'Font Chaos',
+    description: 'Replaces all fonts with random fallback families (Comic Sans, cursive, monospace)',
+    category: 'visual',
+    apply(ctx) {
+      const fonts = [
+        'Comic Sans MS, cursive',
+        'monospace',
+        'fantasy',
+        'Papyrus, fantasy',
+        'Courier New, monospace',
+      ];
+      const chosen = fonts[Math.floor(Math.random() * fonts.length)];
+      const style = document.createElement('style');
+      style.id = '__csspow_font';
+      style.textContent = `* { font-family: ${chosen} !important; }`;
+      document.head.appendChild(style);
+      ctx.fontStyleEl = style;
+    },
+    revert(ctx) {
+      if (ctx.fontStyleEl) ctx.fontStyleEl.remove();
+    },
+  },
+
+  'spacing-chaos': {
+    name: 'Spacing Chaos',
+    description: 'Applies random padding and margins to expose fragile layouts',
+    category: 'layout',
+    apply(ctx) {
+      const els = Array.from(document.querySelectorAll('div, section, article, header, footer, nav, main, aside'));
+      ctx.spacingOriginals = els.map(el => ({ el, padding: el.style.padding, margin: el.style.margin }));
+      const rand = (min, max) => Math.floor(Math.random() * (max - min + 1)) + min;
+      els.forEach(el => {
+        el.style.padding = `${rand(0, 32)}px ${rand(0, 48)}px`;
+        el.style.margin = `${rand(0, 24)}px`;
+      });
+    },
+    revert(ctx) {
+      if (ctx.spacingOriginals) {
+        ctx.spacingOriginals.forEach(({ el, padding, margin }) => {
+          el.style.padding = padding;
+          el.style.margin = margin;
+        });
+      }
+    },
+  },
+
+  'overflow-chaos': {
+    name: 'Overflow Chaos',
+    description: 'Forces narrow widths on containers to trigger text clipping and overflow',
+    category: 'layout',
+    apply(ctx) {
+      const style = document.createElement('style');
+      style.id = '__csspow_overflow';
+      style.textContent = `
+        div, section, article, p, span, a, li {
+          max-width: 200px !important;
+          overflow: visible !important;
+        }
+      `;
+      document.head.appendChild(style);
+      ctx.overflowStyleEl = style;
+    },
+    revert(ctx) {
+      if (ctx.overflowStyleEl) ctx.overflowStyleEl.remove();
+    },
+  },
+
+  contrast: {
+    name: 'High Contrast',
+    description: 'Forces extreme black/white contrast to test accessibility and legibility',
+    category: 'accessibility',
+    apply(ctx) {
+      const style = document.createElement('style');
+      style.id = '__csspow_contrast';
+      style.textContent = `
+        * { background-color: black !important; color: white !important; border-color: white !important; }
+        img, svg, video, canvas { filter: invert(1) !important; }
+        a { color: yellow !important; }
+      `;
+      document.head.appendChild(style);
+      ctx.contrastStyleEl = style;
+    },
+    revert(ctx) {
+      if (ctx.contrastStyleEl) ctx.contrastStyleEl.remove();
+    },
+  },
+
+  'motion-reduce': {
+    name: 'Reduce Motion',
+    description: 'Disables all animations and transitions',
+    category: 'accessibility',
+    apply(ctx) {
+      const style = document.createElement('style');
+      style.id = '__csspow_motion';
+      style.textContent = `
+        *, *::before, *::after {
+          animation-duration: 0.001ms !important;
+          animation-delay: 0ms !important;
+          transition-duration: 0.001ms !important;
+          transition-delay: 0ms !important;
+        }
+      `;
+      document.head.appendChild(style);
+      ctx.motionStyleEl = style;
+    },
+    revert(ctx) {
+      if (ctx.motionStyleEl) ctx.motionStyleEl.remove();
+    },
+  },
+
+  'layout-break': {
+    name: 'Layout Break',
+    description: 'Randomly changes display types (flex/block/grid) to expose fragile component structure',
+    category: 'layout',
+    apply(ctx) {
+      const displays = ['block', 'flex', 'grid', 'inline-block'];
+      const els = Array.from(document.querySelectorAll('div, section, header, nav, main, footer, aside, article'));
+      ctx.layoutOriginals = els.map(el => ({ el, display: el.style.display }));
+      els.forEach(el => {
+        el.style.display = displays[Math.floor(Math.random() * displays.length)];
+      });
+    },
+    revert(ctx) {
+      if (ctx.layoutOriginals) {
+        ctx.layoutOriginals.forEach(({ el, display }) => {
+          el.style.display = display;
+        });
+      }
+    },
+  },
+};
+
+export function detectOverflows() {
+  const overflowing = [];
+  const els = document.querySelectorAll('*');
+  for (const el of els) {
+    if (el.scrollWidth > el.clientWidth + 2) {
+      const tag = el.tagName.toLowerCase();
+      const id = el.id ? `#${el.id}` : '';
+      const cls = el.className && typeof el.className === 'string'
+        ? `.${el.className.trim().split(/\s+/).slice(0, 2).join('.')}`
+        : '';
+      overflowing.push(`${tag}${id}${cls}`);
+    }
+  }
+  return [...new Set(overflowing)].slice(0, 20);
+}
+
+export function poison(doc, options = {}) {
+  const { modes = [] } = options;
+  const results = [];
+  for (const modeId of modes) {
+    const mode = MODES[modeId];
+    if (!mode) {
+      results.push({ mode: modeId, applied: false, error: `Unknown mode: ${modeId}` });
+      continue;
+    }
+    const ctx = {};
+    try {
+      mode.apply(ctx);
+      const overflows = detectOverflows();
+      results.push({ mode: modeId, applied: true, overflows, overflowCount: overflows.length });
+    } catch (err) {
+      results.push({ mode: modeId, applied: false, error: err.message });
+    }
+  }
+  return results;
+}
+
+export const MODE_IDS = Object.keys(MODES);

package/src/index.js

@@ -0,0 +1 @@
+export { run } from './run.js';

package/src/list-modes.js

@@ -0,0 +1,29 @@
+import chalk from 'chalk';
+import { MODES } from './core.js';
+
+export function listModes() {
+  console.log('');
+  console.log(chalk.red.bold('  ☣  Available poison modes'));
+  console.log(chalk.gray('  ────────────────────────────────────────────────────'));
+
+  const byCategory = {};
+  for (const [id, mode] of Object.entries(MODES)) {
+    const cat = mode.category || 'other';
+    if (!byCategory[cat]) byCategory[cat] = [];
+    byCategory[cat].push({ id, ...mode });
+  }
+
+  for (const [cat, modes] of Object.entries(byCategory)) {
+    console.log('');
+    console.log(`  ${chalk.bold(chalk.yellow(cat.toUpperCase()))}`);
+    for (const m of modes) {
+      console.log(`    ${chalk.cyan(m.id.padEnd(18))} ${chalk.white(m.name)}`);
+      console.log(`    ${' '.repeat(18)} ${chalk.gray(m.description)}`);
+    }
+  }
+
+  console.log('');
+  console.log(chalk.gray('  Usage:'));
+  console.log(`  ${chalk.white('csspow run <url> --modes rtl,zoom,font-chaos')}`);
+  console.log('');
+}

package/src/list-presets.js

@@ -0,0 +1,20 @@
+import chalk from 'chalk';
+import { PRESETS } from './presets.js';
+
+export function listPresets() {
+  console.log('');
+  console.log(chalk.red.bold('  ☣  Available presets'));
+  console.log(chalk.gray('  ─────────────────────────────────────────────────────'));
+
+  for (const [id, preset] of Object.entries(PRESETS)) {
+    console.log('');
+    console.log(`  ${chalk.bold(chalk.yellow(id.padEnd(10)))} ${chalk.white(preset.name)}`);
+    console.log(`  ${' '.repeat(10)} ${chalk.gray(preset.description)}`);
+    console.log(`  ${' '.repeat(10)} Modes: ${chalk.cyan(preset.modes.join(', '))}`);
+  }
+
+  console.log('');
+  console.log(chalk.gray('  Usage:'));
+  console.log(`  ${chalk.white('csspow run <url> --mode brutal')}`);
+  console.log('');
+}

package/src/presets.js

@@ -0,0 +1,35 @@
+/**
+ * csspow — Presets
+ * Author: Badreddine Karama
+ */
+
+export const PRESETS = {
+  light: {
+    name: 'Light',
+    description: 'Subtle issues — zoom + fonts. Good for quick sanity checks.',
+    modes: ['zoom', 'font-chaos'],
+  },
+  chaos: {
+    name: 'Chaos',
+    description: 'Noticeable breakage — the standard experience.',
+    modes: ['rtl', 'zoom', 'spacing-chaos', 'font-chaos'],
+  },
+  brutal: {
+    name: 'Brutal',
+    description: 'Everything breaks. Maximum destruction.',
+    modes: ['rtl', 'zoom', 'font-chaos', 'spacing-chaos', 'overflow-chaos', 'contrast', 'motion-reduce', 'layout-break'],
+  },
+  a11y: {
+    name: 'A11y',
+    description: 'Accessibility-focused — tests color contrast, motion sensitivity, zoom.',
+    modes: ['contrast', 'motion-reduce', 'zoom'],
+  },
+};
+
+export function resolveModes(preset, modes) {
+  if (modes && modes.length > 0) return modes;
+  if (preset && PRESETS[preset]) return PRESETS[preset].modes;
+  return PRESETS.chaos.modes;
+}
+
+export const PRESET_NAMES = Object.keys(PRESETS);

package/src/reporter.js

@@ -0,0 +1,155 @@
+/**
+ * csspow — HTML Report Generator
+ * Author: Badreddine Karama
+ */
+
+import { writeFileSync, mkdirSync, copyFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+export function generateReport({ url, outputDir, screenshots, beforePath, durationMs }) {
+  mkdirSync(join(outputDir, 'screenshots'), { recursive: true });
+
+  const processedShots = screenshots.map(s => {
+    const filename = `${s.mode}.png`;
+    const dest = join(outputDir, 'screenshots', filename);
+    if (s.screenshotPath && existsSync(s.screenshotPath)) {
+      copyFileSync(s.screenshotPath, dest);
+    }
+    return { ...s, filename };
+  });
+
+  let beforeFilename = null;
+  if (beforePath && existsSync(beforePath)) {
+    beforeFilename = 'before.png';
+    copyFileSync(beforePath, join(outputDir, 'screenshots', beforeFilename));
+  }
+
+  const totalBreaks = processedShots.reduce((n, s) => n + (s.overflowCount || 0), 0);
+  const html = buildHTML({ url, screenshots: processedShots, beforeFilename, totalBreaks, durationMs });
+  writeFileSync(join(outputDir, 'index.html'), html, 'utf8');
+  return join(outputDir, 'index.html');
+}
+
+function buildHTML({ url, screenshots, beforeFilename, totalBreaks, durationMs }) {
+  const screenshotCards = screenshots.map(s => {
+    const breakBadge = s.overflowCount > 0
+      ? `<span class="badge bad">${s.overflowCount} overflow${s.overflowCount !== 1 ? 's' : ''}</span>`
+      : `<span class="badge ok">No overflows</span>`;
+
+    const overflowList = s.overflows && s.overflows.length > 0
+      ? `<div class="overflows"><strong>Overflowing elements:</strong><ul>${s.overflows.map(o => `<li><code>${escapeHtml(o)}</code></li>`).join('')}</ul></div>`
+      : '';
+
+    return `
+    <section class="card">
+      <div class="card-header">
+        <h2>${escapeHtml(s.modeName || s.mode)}</h2>
+        ${breakBadge}
+      </div>
+      <p class="description">${escapeHtml(s.modeDescription || '')}</p>
+      ${overflowList}
+      <div class="screenshot-wrap">
+        <img src="screenshots/${s.filename}" alt="${escapeHtml(s.mode)} screenshot" loading="lazy" />
+      </div>
+    </section>`;
+  }).join('\n');
+
+  const beforeSection = beforeFilename ? `
+    <section class="card baseline">
+      <div class="card-header">
+        <h2>Baseline</h2>
+        <span class="badge ok">Before</span>
+      </div>
+      <p class="description">Page appearance before any chaos was applied.</p>
+      <div class="screenshot-wrap">
+        <img src="screenshots/${beforeFilename}" alt="Baseline screenshot" loading="lazy" />
+      </div>
+    </section>` : '';
+
+  const duration = durationMs ? `${(durationMs / 1000).toFixed(1)}s` : '—';
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>csspow report — ${escapeHtml(url)}</title>
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', system-ui, sans-serif; background: #0d0d0d; color: #e8e8e8; line-height: 1.6; padding: 0 0 80px; }
+    header { background: linear-gradient(135deg, #1a0a00 0%, #0d0d0d 60%); border-bottom: 1px solid #2a2a2a; padding: 40px 32px; }
+    header .logo { font-size: 13px; font-weight: 700; letter-spacing: 0.2em; text-transform: uppercase; color: #ff4500; margin-bottom: 12px; }
+    header h1 { font-size: clamp(22px, 4vw, 36px); font-weight: 800; color: #fff; word-break: break-all; }
+    header h1 span { color: #ff6633; }
+    .meta { display: flex; flex-wrap: wrap; gap: 24px; margin-top: 24px; }
+    .meta-item { display: flex; flex-direction: column; gap: 2px; }
+    .meta-item .label { font-size: 11px; text-transform: uppercase; letter-spacing: 0.1em; color: #888; }
+    .meta-item .value { font-size: 20px; font-weight: 700; color: #fff; }
+    .meta-item .value.danger { color: #ff4500; }
+    .meta-item .value.ok { color: #3ddc84; }
+    .grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(540px, 1fr)); gap: 24px; padding: 32px; max-width: 1600px; margin: 0 auto; }
+    .card { background: #161616; border: 1px solid #252525; border-radius: 12px; overflow: hidden; }
+    .card.baseline { border-color: #1e3a2a; }
+    .card-header { display: flex; align-items: center; justify-content: space-between; padding: 16px 20px; border-bottom: 1px solid #252525; gap: 12px; }
+    .card-header h2 { font-size: 16px; font-weight: 700; color: #fff; }
+    .badge { font-size: 11px; font-weight: 700; padding: 3px 10px; border-radius: 20px; white-space: nowrap; flex-shrink: 0; }
+    .badge.bad { background: rgba(255,69,0,0.15); color: #ff6633; border: 1px solid rgba(255,69,0,0.3); }
+    .badge.ok { background: rgba(61,220,132,0.1); color: #3ddc84; border: 1px solid rgba(61,220,132,0.2); }
+    .description { padding: 12px 20px 0; font-size: 13px; color: #888; }
+    .overflows { margin: 12px 20px 0; padding: 12px; background: rgba(255,69,0,0.05); border: 1px solid rgba(255,69,0,0.15); border-radius: 8px; font-size: 12px; }
+    .overflows strong { color: #ff6633; display: block; margin-bottom: 8px; }
+    .overflows ul { list-style: none; display: flex; flex-wrap: wrap; gap: 6px; }
+    .overflows code { background: rgba(255,69,0,0.1); padding: 2px 6px; border-radius: 4px; font-family: monospace; font-size: 11px; color: #ffaa88; }
+    .screenshot-wrap { padding: 20px; }
+    .screenshot-wrap img { width: 100%; height: auto; border-radius: 8px; border: 1px solid #252525; display: block; }
+    footer { text-align: center; padding: 32px; font-size: 12px; color: #444; border-top: 1px solid #1a1a1a; margin-top: 40px; }
+    footer a { color: #ff6633; text-decoration: none; }
+    footer .creator { color: #666; margin-top: 6px; font-size: 11px; }
+    @media (max-width: 600px) { .grid { grid-template-columns: 1fr; padding: 16px; } header { padding: 24px 16px; } }
+  </style>
+</head>
+<body>
+  <header>
+    <div class="logo">☣ csspow report</div>
+    <h1>Testing: <span>${escapeHtml(url)}</span></h1>
+    <div class="meta">
+      <div class="meta-item">
+        <span class="label">Modes tested</span>
+        <span class="value">${screenshots.length}</span>
+      </div>
+      <div class="meta-item">
+        <span class="label">Total overflows found</span>
+        <span class="value ${totalBreaks > 0 ? 'danger' : 'ok'}">${totalBreaks}</span>
+      </div>
+      <div class="meta-item">
+        <span class="label">Run time</span>
+        <span class="value">${duration}</span>
+      </div>
+      <div class="meta-item">
+        <span class="label">Generated</span>
+        <span class="value" style="font-size:14px">${new Date().toLocaleString()}</span>
+      </div>
+    </div>
+  </header>
+
+  <div class="grid">
+    ${beforeSection}
+    ${screenshotCards}
+  </div>
+
+  <footer>
+    Generated by <a href="https://github.com/csspow/csspow" target="_blank">☣ csspow</a>
+    <div class="creator">Created by <strong style="color:#ff6633">Badreddine Karama</strong></div>
+  </footer>
+</body>
+</html>`;
+}
+
+function escapeHtml(str) {
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}

package/src/run.js

@@ -0,0 +1,239 @@
+/**
+ * csspow run command
+ * Launches Playwright, injects poison modes, captures screenshots, generates report.
+ */
+
+import { chromium } from 'playwright';
+import { setupPlaywrightEnv } from './setup-env.js';
+import { mkdirSync, existsSync, writeFileSync } from 'fs';
+import { join, resolve } from 'path';
+import chalk from 'chalk';
+import ora from 'ora';
+import { MODES, MODE_IDS } from './core.js';
+import { resolveModes, PRESETS } from './presets.js';
+import { generateReport } from './reporter.js';
+
+const POISON_INLINE = {
+  rtl: `document.documentElement.dir = 'rtl';`,
+  zoom: `document.body.style.zoom = '200%';`,
+  'font-chaos': `
+    const fonts = ['Comic Sans MS, cursive','monospace','fantasy','Courier New, monospace'];
+    const s = document.createElement('style');
+    s.textContent = '* { font-family: ' + fonts[Math.floor(Math.random()*fonts.length)] + ' !important; }';
+    document.head.appendChild(s);
+  `,
+  'spacing-chaos': `
+    const rand = (a,b) => Math.floor(Math.random()*(b-a+1))+a;
+    document.querySelectorAll('div,section,article,header,footer,nav,main,aside').forEach(el => {
+      el.style.padding = rand(0,32)+'px '+rand(0,48)+'px';
+      el.style.margin = rand(0,24)+'px';
+    });
+  `,
+  'overflow-chaos': `
+    const s = document.createElement('style');
+    s.textContent = 'div,section,article,p,span,a,li{max-width:200px!important;overflow:visible!important;}';
+    document.head.appendChild(s);
+  `,
+  contrast: `
+    const s = document.createElement('style');
+    s.textContent = '*{background-color:black!important;color:white!important;border-color:white!important;}img,svg,video,canvas{filter:invert(1)!important;}a{color:yellow!important;}';
+    document.head.appendChild(s);
+  `,
+  'motion-reduce': `
+    const s = document.createElement('style');
+    s.textContent = '*,*::before,*::after{animation-duration:0.001ms!important;transition-duration:0.001ms!important;}';
+    document.head.appendChild(s);
+  `,
+  'layout-break': `
+    const displays=['block','flex','grid','inline-block'];
+    document.querySelectorAll('div,section,header,nav,main,footer,aside,article').forEach(el => {
+      el.style.display = displays[Math.floor(Math.random()*displays.length)];
+    });
+  `,
+};
+
+const DETECT_OVERFLOWS = `
+  (() => {
+    const overflowing = [];
+    for (const el of document.querySelectorAll('*')) {
+      if (el.scrollWidth > el.clientWidth + 2) {
+        const tag = el.tagName.toLowerCase();
+        const id = el.id ? '#'+el.id : '';
+        const cls = el.className && typeof el.className === 'string'
+          ? '.'+el.className.trim().split(/\\s+/).slice(0,2).join('.')
+          : '';
+        overflowing.push(tag+id+cls);
+      }
+    }
+    return [...new Set(overflowing)].slice(0, 20);
+  })()
+`;
+
+export async function run(url, opts) {
+  const startTime = Date.now();
+
+  // Set up library paths for Playwright's Chromium (needed in Nix/NixOS environments)
+  setupPlaywrightEnv();
+
+  // Normalize URL
+  if (!url.startsWith('http://') && !url.startsWith('https://')) {
+    url = 'https://' + url;
+  }
+
+  // Resolve modes
+  const rawModes = opts.modes ? opts.modes.split(',').map(m => m.trim()) : null;
+  const modes = resolveModes(rawModes ? null : opts.mode, rawModes);
+
+  const outputDir = resolve(opts.output || './csspow-report');
+  const shouldRecord = opts.record !== false;
+
+  console.log('');
+  console.log(chalk.red.bold('  ☣  csspow') + chalk.gray('  by Badreddine Karama'));
+  console.log(chalk.gray('  ─────────────────────────────────────'));
+  console.log(`  ${chalk.bold('URL:')}     ${chalk.cyan(url)}`);
+  console.log(`  ${chalk.bold('Modes:')}   ${chalk.yellow(modes.join(', '))}`);
+  console.log(`  ${chalk.bold('Record:')}  ${shouldRecord ? chalk.green('yes → ' + outputDir) : chalk.gray('no')}`);
+  console.log(chalk.gray('  ─────────────────────────────────────'));
+  console.log('');
+
+  const spinner = ora({ color: 'red' });
+
+  // Validate modes
+  const unknown = modes.filter(m => !POISON_INLINE[m]);
+  if (unknown.length > 0) {
+    console.error(chalk.red(`  Unknown mode(s): ${unknown.join(', ')}`));
+    console.error(chalk.gray(`  Run ${chalk.white('csspow modes')} to see available modes.`));
+    process.exit(1);
+  }
+
+  spinner.start('Launching browser...');
+
+  let browser;
+  try {
+    browser = await chromium.launch({ headless: opts.headless !== false });
+  } catch (err) {
+    spinner.fail('Failed to launch browser');
+    console.error(chalk.red('\n  ' + err.message));
+    console.error(chalk.gray('\n  Make sure Playwright browsers are installed:'));
+    console.error(chalk.white('  npx playwright install chromium\n'));
+    process.exit(1);
+  }
+
+  const page = await browser.newPage({ viewport: { width: 1280, height: 800 } });
+
+  try {
+    spinner.text = `Loading ${url}...`;
+    await page.goto(url, { waitUntil: 'networkidle', timeout: parseInt(opts.timeout) || 30000 });
+  } catch (err) {
+    spinner.fail(`Failed to load ${url}`);
+    console.error(chalk.red('\n  ' + err.message + '\n'));
+    await browser.close();
+    process.exit(1);
+  }
+
+  if (shouldRecord) {
+    mkdirSync(join(outputDir, 'screenshots'), { recursive: true });
+  }
+
+  // Capture baseline
+  let beforePath = null;
+  if (shouldRecord) {
+    beforePath = join(outputDir, 'screenshots', 'before.png');
+    await page.screenshot({ path: beforePath, fullPage: true });
+    spinner.succeed('Baseline screenshot captured');
+  }
+
+  const screenshots = [];
+
+  for (const mode of modes) {
+    spinner.start(`Applying ${chalk.yellow(mode)}...`);
+
+    // Navigate fresh for each mode to avoid compound effects
+    try {
+      await page.goto(url, { waitUntil: 'networkidle', timeout: parseInt(opts.timeout) || 30000 });
+    } catch (_) {}
+
+    const script = POISON_INLINE[mode] || '';
+
+    try {
+      await page.evaluate(script);
+    } catch (err) {
+      spinner.warn(`  ${mode}: could not inject (${err.message})`);
+      continue;
+    }
+
+    // Small wait so the page settles
+    await page.waitForTimeout(400);
+
+    let overflows = [];
+    try {
+      overflows = await page.evaluate(DETECT_OVERFLOWS);
+    } catch (_) {}
+
+    let screenshotPath = null;
+    if (shouldRecord) {
+      screenshotPath = join(outputDir, 'screenshots', `${mode}.png`);
+      await page.screenshot({ path: screenshotPath, fullPage: true });
+    }
+
+    const modeInfo = MODES[mode];
+    screenshots.push({
+      mode,
+      screenshotPath: screenshotPath || '',
+      overflowCount: overflows.length,
+      overflows,
+      modeName: modeInfo?.name || mode,
+      modeDescription: modeInfo?.description || '',
+    });
+
+    const overflowText = overflows.length > 0
+      ? chalk.red(` — ${overflows.length} overflow${overflows.length !== 1 ? 's' : ''}`)
+      : chalk.green(' — clean');
+
+    spinner.succeed(`${chalk.yellow(mode)}${overflowText}`);
+
+    if (overflows.length > 0) {
+      overflows.slice(0, 5).forEach(el => {
+        console.log(chalk.gray(`    overflow: ${el}`));
+      });
+      if (overflows.length > 5) {
+        console.log(chalk.gray(`    ...and ${overflows.length - 5} more`));
+      }
+    }
+  }
+
+  await browser.close();
+
+  const durationMs = Date.now() - startTime;
+
+  // Summary
+  console.log('');
+  const totalBreaks = screenshots.reduce((n, s) => n + s.overflowCount, 0);
+  console.log(chalk.bold('  Summary'));
+  console.log(chalk.gray('  ─────────────────────────────────────'));
+  console.log(`  Modes tested:    ${chalk.white(screenshots.length)}`);
+  console.log(`  Total overflows: ${totalBreaks > 0 ? chalk.red.bold(totalBreaks) : chalk.green('0')}`);
+  console.log(`  Duration:        ${chalk.white((durationMs / 1000).toFixed(1) + 's')}`);
+
+  // Report
+  if (shouldRecord) {
+    const reportPath = generateReport({
+      url,
+      outputDir,
+      screenshots,
+      beforePath,
+      durationMs,
+    });
+
+    console.log('');
+    console.log(`  ${chalk.green('✓')} Report saved to: ${chalk.cyan(reportPath)}`);
+    console.log(chalk.gray(`  Open it in your browser: ${chalk.white('open ' + reportPath)}`));
+  }
+
+  console.log('');
+
+  // Exit code reflects whether any breaks were found
+  if (totalBreaks > 0) {
+    process.exit(0); // Still success — we found breaks, which is informational not fatal
+  }
+}

package/src/setup-env.js

@@ -0,0 +1,34 @@
+/**
+ * Set up LD_LIBRARY_PATH for Playwright's Chromium to find Nix store libraries.
+ * This is called automatically before launching any browser.
+ */
+
+import { existsSync } from 'fs';
+
+const NIX_LIBS = [
+  // libgbm — required by Chrome headless shell
+  '/nix/store/24w3s75aa2lrvvxsybficn8y3zxd27kp-mesa-libgbm-25.1.0/lib',
+  // glib
+  '/nix/store/syzi2bpl8j599spgvs20xjkjzcw758as-glib-2.84.3/lib',
+  '/nix/store/y3nxdc2x8hwivppzgx5hkrhacsh87l21-glib-2.84.3/lib',
+  '/nix/store/f7rcazhd826xlcz43il4vafv28888cgj-glib-2.86.3/lib',
+  // dbus
+  '/nix/store/231d6mmkylzr80pf30dbywa9x9aryjgy-dbus-1.14.10-lib/lib',
+  '/nix/store/zbydgvn9gypb3vg88mzydn88ky6cibaz-dbus-1.14.10/lib',
+  // alsa
+  '/nix/store/yw5xqn8lqinrifm9ij80nrmf0i6fdcbx-alsa-lib-1.2.13/lib',
+  // libxkbcommon
+  '/nix/store/sisfq9wihyqqjzmrpik9b4xksifw97ha-libxkbcommon-1.8.1/lib',
+  // libdrm
+  '/nix/store/lp1ak5dgh8fy09nrfryfsm0ayk6c0wwh-libdrm-2.4.124-bin/lib',
+];
+
+export function setupPlaywrightEnv() {
+  const existing = process.env.LD_LIBRARY_PATH || '';
+  const nixPaths = NIX_LIBS.filter(p => existsSync(p));
+
+  if (nixPaths.length === 0) return; // Not on Nix, libraries should be at system paths
+
+  const allPaths = [...new Set([...nixPaths, ...existing.split(':').filter(Boolean)])];
+  process.env.LD_LIBRARY_PATH = allPaths.join(':');
+}