designlang 7.0.0 → 7.2.0

package/src/extractors/wide-gamut.js

@@ -0,0 +1,47 @@
+// Catalog of wide-gamut / modern color function usages from the crawler's
+// scan of stylesheet cssText. Produces counts + sample raw values + converted
+// sRGB hex for oklch/oklab values.
+
+import { oklchLikeToHex } from '../utils/color-gamut.js';
+
+export function extractWideGamut(modernColors) {
+  const src = Array.isArray(modernColors) ? modernColors : [];
+  const catalog = {
+    oklch: { count: 0, samples: [] },
+    oklab: { count: 0, samples: [] },
+    colorMix: { count: 0, samples: [] },
+    lightDark: { count: 0, samples: [] },
+    displayP3: { count: 0, samples: [] },
+    rec2020: { count: 0, samples: [] },
+  };
+
+  const bucket = {
+    oklch: catalog.oklch,
+    oklab: catalog.oklab,
+    'color-mix': catalog.colorMix,
+    'light-dark': catalog.lightDark,
+    'display-p3': catalog.displayP3,
+    rec2020: catalog.rec2020,
+  };
+
+  for (const entry of src) {
+    const b = bucket[entry.type];
+    if (!b) continue;
+    b.count++;
+    if (b.samples.length < 10) {
+      const sample = {
+        raw: entry.raw,
+        property: entry.property || '',
+        selector: entry.selector || '',
+      };
+      if (entry.type === 'oklch' || entry.type === 'oklab') {
+        const hex = oklchLikeToHex(entry.raw);
+        if (hex) sample.value = hex;
+      }
+      b.samples.push(sample);
+    }
+  }
+
+  const totalCount = Object.values(catalog).reduce((n, c) => n + c.count, 0);
+  return { ...catalog, totalCount };
+}

package/src/formatters/routes-reconciliation.js

@@ -0,0 +1,160 @@
+// Shared-vs-per-route reconciliation for multi-page token extraction.
+// Input: [{ url, path, tokens: DTCG-shaped { primitive, semantic, ... } }]
+// Output: { shared, perRoute: { <slug>: { added, changed } }, summary }
+//
+// "Shared" = a token path present with the same $value in ALL routes.
+// "Added"  = a token path present on this route but missing from the shared set.
+// "Changed"= a token path present in shared but with a different $value here.
+
+export function slugForPath(p) {
+  if (!p || p === '/' || p === '') return 'index';
+  return String(p)
+    .replace(/^\/+|\/+$/g, '')
+    .replace(/[^a-z0-9]+/gi, '-')
+    .replace(/^-+|-+$/g, '')
+    .toLowerCase() || 'index';
+}
+
+function isLeaf(node) {
+  return node && typeof node === 'object' && '$value' in node;
+}
+
+// Walk a DTCG tree and produce a flat map of dotted-path -> serialized $value.
+function flattenTokens(tree, prefix = '', out = {}) {
+  if (!tree || typeof tree !== 'object') return out;
+  if (isLeaf(tree)) {
+    out[prefix] = JSON.stringify(tree.$value);
+    return out;
+  }
+  for (const [k, v] of Object.entries(tree)) {
+    if (k.startsWith('$')) continue;
+    const p = prefix ? `${prefix}.${k}` : k;
+    if (v && typeof v === 'object') flattenTokens(v, p, out);
+  }
+  return out;
+}
+
+// Set a dotted-path key to a (JSON-parsed) value on a nested object (leaf as DTCG $value).
+function setPath(root, dotted, jsonVal) {
+  const parts = dotted.split('.');
+  let cur = root;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const p = parts[i];
+    if (!cur[p] || typeof cur[p] !== 'object') cur[p] = {};
+    cur = cur[p];
+  }
+  cur[parts[parts.length - 1]] = { $value: JSON.parse(jsonVal) };
+}
+
+export function reconcileRoutes(routes) {
+  const safeRoutes = Array.isArray(routes) ? routes.filter(r => r && r.tokens) : [];
+  if (safeRoutes.length === 0) {
+    return {
+      shared: {},
+      perRoute: {},
+      summary: { routeCount: 0, sharedTokenCount: 0, totalUnique: 0, drift: [] },
+    };
+  }
+
+  // Flatten each route's tokens (combining primitive + semantic trees).
+  const flat = safeRoutes.map(r => {
+    const merged = {};
+    flattenTokens(r.tokens.primitive || {}, 'primitive', merged);
+    flattenTokens(r.tokens.semantic || {}, 'semantic', merged);
+    return { route: r, flat: merged };
+  });
+
+  // Build shared set: paths present across ALL routes with identical serialized value.
+  const firstKeys = Object.keys(flat[0].flat);
+  const sharedFlat = {};
+  for (const key of firstKeys) {
+    const v = flat[0].flat[key];
+    const allAgree = flat.every(f => f.flat[key] === v);
+    if (allAgree) sharedFlat[key] = v;
+  }
+
+  // Rebuild shared as DTCG tree.
+  const shared = {};
+  for (const [k, v] of Object.entries(sharedFlat)) setPath(shared, k, v);
+
+  // Per-route deltas.
+  const perRoute = {};
+  const usedSlugs = new Map();
+  const drift = [];
+  for (const { route, flat: f } of flat) {
+    let slug = slugForPath(route.path);
+    // Slug collision resolution.
+    if (usedSlugs.has(slug)) {
+      const n = usedSlugs.get(slug) + 1;
+      usedSlugs.set(slug, n);
+      slug = `${slug}-${n}`;
+    } else {
+      usedSlugs.set(slug, 1);
+    }
+
+    const added = {};
+    const changed = {};
+    for (const [k, v] of Object.entries(f)) {
+      if (!(k in sharedFlat)) {
+        // Not shared at all — either unique to this route or conflicts across routes.
+        // If the key exists in another route with a different value, it's a "changed" vs shared is not applicable;
+        // we classify as added when the token is absent from sharedFlat entirely.
+        const existsInOthers = flat.some(o => o.flat !== f && (k in o.flat));
+        if (!existsInOthers) {
+          setPath(added, k, v);
+        } else {
+          // Present in multiple routes but disagreeing values -> changed relative to the shared baseline.
+          setPath(changed, k, v);
+          drift.push({ path: route.path, token: k, value: JSON.parse(v) });
+        }
+      }
+    }
+    perRoute[slug] = { url: route.url, path: route.path, added, changed };
+  }
+
+  const allKeys = new Set();
+  for (const f of flat) for (const k of Object.keys(f.flat)) allKeys.add(k);
+
+  return {
+    shared,
+    perRoute,
+    summary: {
+      routeCount: safeRoutes.length,
+      sharedTokenCount: Object.keys(sharedFlat).length,
+      totalUnique: allKeys.size,
+      drift,
+    },
+  };
+}
+
+export function formatRoutesReport(reconciled) {
+  const { summary, perRoute } = reconciled;
+  const lines = [];
+  lines.push('# Multi-route Token Reconciliation');
+  lines.push('');
+  lines.push(`- Routes crawled: **${summary.routeCount}**`);
+  lines.push(`- Shared tokens: **${summary.sharedTokenCount}**`);
+  lines.push(`- Total unique tokens across routes: **${summary.totalUnique}**`);
+  lines.push(`- Cross-route drift entries: **${summary.drift.length}**`);
+  lines.push('');
+  lines.push('## Per-route contributions');
+  for (const [slug, entry] of Object.entries(perRoute)) {
+    const addedCount = countLeaves(entry.added);
+    const changedCount = countLeaves(entry.changed);
+    lines.push(`- \`${entry.path}\` (${slug}): ${addedCount} added, ${changedCount} changed`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+function countLeaves(tree) {
+  let n = 0;
+  const walk = (node) => {
+    if (!node || typeof node !== 'object') return;
+    if (isLeaf(node)) { n++; return; }
+    for (const [k, v] of Object.entries(node)) {
+      if (!k.startsWith('$')) walk(v);
+    }
+  };
+  walk(tree);
+  return n;
+}

package/src/index.js

@@ -21,6 +21,11 @@ import { extractCssHealth } from './extractors/css-health.js';
 import { remediateFailingPairs } from './extractors/a11y-remediation.js';
 import { extractSemanticRegions } from './extractors/semantic-regions.js';
 import { clusterComponents } from './extractors/component-clusters.js';
+import { extractModernCss } from './extractors/modern-css.js';
+import { extractWideGamut } from './extractors/wide-gamut.js';
+import { extractTokenSources } from './extractors/token-sources.js';
+import { extractInteractionStates } from './extractors/interaction-states.js';
+import { formatDtcgTokens } from './formatters/dtcg-tokens.js';
 
 function safeExtract(fn, ...args) {
   try { return fn(...args); } catch { return null; }
@@ -30,6 +35,7 @@ export async function extractDesignLanguage(url, options = {}) {
   const rawData = await crawlPage(url, {
     ...options,
     ignore: options.ignore,
+    deepInteract: options.deepInteract,
   });
   const styles = rawData.light.computedStyles;
   const warnings = [];
@@ -63,6 +69,10 @@ export async function extractDesignLanguage(url, options = {}) {
     cssHealth: safeExtract(extractCssHealth, rawData.light.cssCoverage) || null,
     regions: safeExtract(extractSemanticRegions, rawData.light.sections) || [],
     componentClusters: safeExtract(clusterComponents, rawData.light.componentCandidates) || [],
+    modernCss: safeExtract(extractModernCss, rawData) || { pseudoElements: { count: 0, samples: [] }, variableFonts: { count: 0, axes: [] }, openTypeFeatures: [], textWrap: { wrap: [], decorationStyle: [], decorationThickness: [], underlineOffset: [] }, containerQueries: { count: 0, rules: [] }, envUsage: [] },
+    wideGamut: safeExtract(extractWideGamut, rawData.light.modernColors || []) || { oklch: { count: 0, samples: [] }, oklab: { count: 0, samples: [] }, colorMix: { count: 0, samples: [] }, lightDark: { count: 0, samples: [] }, displayP3: { count: 0, samples: [] }, rec2020: { count: 0, samples: [] }, totalCount: 0 },
+    tokenSources: [],
+    interactionStates: safeExtract(extractInteractionStates, rawData.interactState || rawData.light.interactState) || { scrollSettled: false, menusOpened: 0, hover: { sampled: 0, changed: 0, deltas: [] }, accordionsOpened: 0, modals: [] },
     score: null,
   };
 
@@ -106,6 +116,25 @@ export async function extractDesignLanguage(url, options = {}) {
     };
   } catch { /* non-fatal */ }
 
+  design.tokenSources = safeExtract(extractTokenSources, design, styles) || [];
+
+  // Per-route token extraction (Tier 2 multi-page reconciliation).
+  if (Array.isArray(rawData.routes) && rawData.routes.length > 0) {
+    design.routes = rawData.routes.map(r => {
+      const rStyles = r.computedStylesSample || [];
+      const rDesign = {
+        meta: { url: r.url },
+        colors: safeExtract(extractColors, rStyles) || { all: [], neutrals: [], backgrounds: [], text: [], gradients: [] },
+        typography: safeExtract(extractTypography, rStyles) || { families: [], scale: [] },
+        spacing: safeExtract(extractSpacing, rStyles) || { scale: [], base: null },
+        shadows: safeExtract(extractShadows, rStyles) || { values: [] },
+        borders: safeExtract(extractBorders, rStyles) || { radii: [] },
+      };
+      const tokens = safeExtract(formatDtcgTokens, rDesign) || { primitive: {}, semantic: {} };
+      return { url: r.url, path: r.path, tokens };
+    });
+  }
+
   design.score = safeExtract(scoreDesignSystem, design);
   if (design.score === null) warnings.push('scoring failed');
 

package/src/utils/color-gamut.js

@@ -0,0 +1,82 @@
+// OKLCH / OKLab → sRGB hex conversion utilities.
+// Based on the public OKLab formulas by Björn Ottosson
+// (https://bottosson.github.io/posts/oklab/). Implemented locally (no deps).
+
+function clamp01(v) { return Math.max(0, Math.min(1, v)); }
+
+function linearToSrgb(x) {
+  // Convert linear-light sRGB [0..1] to sRGB gamma-encoded [0..1]
+  if (x < 0) x = 0;
+  if (x > 1) x = 1;
+  return x <= 0.0031308 ? 12.92 * x : 1.055 * Math.pow(x, 1 / 2.4) - 0.055;
+}
+
+export function oklabToSrgb(L, a, b) {
+  const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
+  const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
+  const s_ = L - 0.0894841775 * a - 1.2914855480 * b;
+
+  const l = l_ * l_ * l_;
+  const m = m_ * m_ * m_;
+  const s = s_ * s_ * s_;
+
+  const r = +4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s;
+  const g = -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s;
+  const b2 = -0.0041960863 * l - 0.7034186147 * m + 1.7076147010 * s;
+
+  return [linearToSrgb(r), linearToSrgb(g), linearToSrgb(b2)];
+}
+
+export function oklchToSrgb(L, C, h) {
+  const hr = (h * Math.PI) / 180;
+  const a = C * Math.cos(hr);
+  const b = C * Math.sin(hr);
+  return oklabToSrgb(L, a, b);
+}
+
+function toHex(v) {
+  const n = Math.round(clamp01(v) * 255);
+  return n.toString(16).padStart(2, '0');
+}
+
+export function rgbToHex(r, g, b) {
+  return '#' + toHex(r) + toHex(g) + toHex(b);
+}
+
+// Parse an oklch() or oklab() CSS value. Accepts values like:
+//   oklch(62.8% 0.258 29.23)
+//   oklch(0.628 0.258 29.23)
+//   oklab(0.628 0.1 -0.1)
+// Returns { type: 'oklch'|'oklab', L, C, h, a, b, raw } or null.
+export function parseOklchOrOklab(raw) {
+  if (!raw || typeof raw !== 'string') return null;
+  const m = raw.match(/^\s*(oklch|oklab)\(\s*([^)]+)\)\s*$/i);
+  if (!m) return null;
+  const type = m[1].toLowerCase();
+  // Strip alpha (everything after /)
+  const body = m[2].split('/')[0].trim();
+  const parts = body.split(/[\s,]+/).filter(Boolean);
+  if (parts.length < 3) return null;
+
+  function parseNum(s, scale = 1) {
+    if (s.endsWith('%')) return parseFloat(s) / 100;
+    return parseFloat(s) * scale;
+  }
+
+  const p0 = parts[0].endsWith('%') ? parseFloat(parts[0]) / 100 : parseFloat(parts[0]);
+  const p1 = parseFloat(parts[1]);
+  const p2 = parseFloat(parts[2]);
+  if ([p0, p1, p2].some(v => Number.isNaN(v))) return null;
+
+  if (type === 'oklch') return { type, L: p0, C: p1, h: p2, raw };
+  return { type, L: p0, a: p1, b: p2, raw };
+}
+
+export function oklchLikeToHex(raw) {
+  const parsed = parseOklchOrOklab(raw);
+  if (!parsed) return null;
+  const [r, g, b] = parsed.type === 'oklch'
+    ? oklchToSrgb(parsed.L, parsed.C, parsed.h)
+    : oklabToSrgb(parsed.L, parsed.a, parsed.b);
+  return rgbToHex(r, g, b);
+}

package/src/utils-cookies.js

@@ -0,0 +1,73 @@
+// Cookie file loaders. Supports three formats so users can paste whatever
+// their existing tooling exports:
+//   - JSON array of Playwright cookie objects: [{name, value, domain, path, …}]
+//   - Playwright storageState JSON: { cookies: [...], origins: [...] }
+//   - Netscape cookies.txt: tab-separated lines (curl / wget / browser extensions)
+//
+// Returned shape is always the Playwright cookie array.
+
+import { readFileSync } from 'fs';
+
+function parseNetscape(text, targetUrl) {
+  const cookies = [];
+  const lines = text.split(/\r?\n/);
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (!line) continue;
+    // Skip comment lines, but keep the Netscape `#HttpOnly_<domain>` prefix
+    // that browsers use to mark HttpOnly cookies — those are real entries.
+    if (line.startsWith('#') && !/^#HttpOnly_/i.test(line)) continue;
+    const parts = raw.split('\t');
+    if (parts.length < 7) continue;
+    const [domain, , path, secure, expires, name, value] = parts;
+    if (!name) continue;
+    const cookie = {
+      name,
+      value: value ?? '',
+      domain: domain.replace(/^#HttpOnly_/i, ''),
+      path: path || '/',
+      secure: secure === 'TRUE',
+      httpOnly: /^#HttpOnly_/i.test(domain),
+    };
+    const exp = Number(expires);
+    if (Number.isFinite(exp) && exp > 0) cookie.expires = exp;
+    if (!cookie.domain && targetUrl) cookie.url = targetUrl;
+    cookies.push(cookie);
+  }
+  return cookies;
+}
+
+function parseJson(text) {
+  const parsed = JSON.parse(text);
+  // Playwright storageState: { cookies: [...], origins: [...] }
+  if (parsed && Array.isArray(parsed.cookies)) return parsed.cookies;
+  // Raw array
+  if (Array.isArray(parsed)) return parsed;
+  throw new Error('cookie file: JSON must be a cookie array or Playwright storageState');
+}
+
+export function loadCookiesFromFile(filePath, targetUrl) {
+  const text = readFileSync(filePath, 'utf-8');
+  const trimmed = text.trimStart();
+  if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+    return parseJson(text);
+  }
+  return parseNetscape(text, targetUrl);
+}
+
+// Merge CLI-provided cookies (name=value strings) with file cookies.
+// Later entries (file) override earlier entries (CLI) at the same name+domain.
+export function mergeCookies(cliCookies = [], fileCookies = [], targetUrl) {
+  const seen = new Map();
+  const parseCli = (c) => {
+    if (typeof c !== 'string') return c;
+    const [name, ...rest] = c.split('=');
+    return { name, value: rest.join('='), url: targetUrl };
+  };
+  for (const c of [...cliCookies.map(parseCli), ...fileCookies]) {
+    if (!c || !c.name) continue;
+    const key = `${c.name}|${c.domain || c.url || ''}`;
+    seen.set(key, c);
+  }
+  return [...seen.values()];
+}

package/tests/cookies.test.js

@@ -0,0 +1,98 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { writeFileSync, mkdtempSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { loadCookiesFromFile, mergeCookies } from '../src/utils-cookies.js';
+
+const tmp = mkdtempSync(join(tmpdir(), 'dl-cookies-'));
+
+function tmpFile(name, text) {
+  const p = join(tmp, name);
+  writeFileSync(p, text, 'utf-8');
+  return p;
+}
+
+describe('loadCookiesFromFile', () => {
+  it('loads JSON array', () => {
+    const f = tmpFile('c.json', JSON.stringify([
+      { name: 'session', value: 'abc', domain: '.example.com', path: '/' },
+    ]));
+    const out = loadCookiesFromFile(f, 'https://example.com');
+    assert.equal(out.length, 1);
+    assert.equal(out[0].name, 'session');
+    assert.equal(out[0].domain, '.example.com');
+  });
+
+  it('loads Playwright storageState', () => {
+    const f = tmpFile('state.json', JSON.stringify({
+      cookies: [{ name: 'csrf', value: 'xyz', domain: 'example.com', path: '/' }],
+      origins: [],
+    }));
+    const out = loadCookiesFromFile(f, 'https://example.com');
+    assert.equal(out.length, 1);
+    assert.equal(out[0].name, 'csrf');
+  });
+
+  it('loads Netscape cookies.txt with tab-separated lines and comment', () => {
+    const netscape = [
+      '# Netscape HTTP Cookie File',
+      '# comment',
+      '.example.com\tTRUE\t/\tFALSE\t1765000000\tsid\tabc123',
+      '#HttpOnly_.example.com\tTRUE\t/\tTRUE\t0\tauth\ttoken-value',
+    ].join('\n');
+    const f = tmpFile('c.txt', netscape);
+    const out = loadCookiesFromFile(f, 'https://example.com');
+    assert.equal(out.length, 2);
+    const sid = out.find((c) => c.name === 'sid');
+    assert.equal(sid.value, 'abc123');
+    assert.equal(sid.domain, '.example.com');
+    assert.equal(sid.secure, false);
+    assert.equal(sid.expires, 1765000000);
+    const auth = out.find((c) => c.name === 'auth');
+    assert.equal(auth.httpOnly, true);
+    assert.equal(auth.secure, true);
+  });
+
+  it('throws on invalid JSON shape', () => {
+    const f = tmpFile('bad.json', '{"not":"array"}');
+    assert.throws(() => loadCookiesFromFile(f, 'https://example.com'));
+  });
+});
+
+describe('mergeCookies', () => {
+  it('parses CLI name=value strings into cookie objects', () => {
+    const out = mergeCookies(['session=abc'], [], 'https://example.com');
+    assert.equal(out.length, 1);
+    assert.equal(out[0].name, 'session');
+    assert.equal(out[0].value, 'abc');
+    assert.equal(out[0].url, 'https://example.com');
+  });
+
+  it('lets file cookies override CLI cookies with the same name+domain', () => {
+    const out = mergeCookies(
+      [{ name: 'session', value: 'cli', domain: '.example.com' }],
+      [{ name: 'session', value: 'file', domain: '.example.com' }],
+      'https://example.com',
+    );
+    assert.equal(out.length, 1);
+    assert.equal(out[0].value, 'file');
+  });
+
+  it('keeps cookies with different domains separately', () => {
+    const out = mergeCookies(
+      [],
+      [
+        { name: 'x', value: '1', domain: 'a.example.com' },
+        { name: 'x', value: '2', domain: 'b.example.com' },
+      ],
+      'https://example.com',
+    );
+    assert.equal(out.length, 2);
+  });
+
+  it('strips entries without a name', () => {
+    const out = mergeCookies([], [{ value: 'orphan' }], 'https://example.com');
+    assert.equal(out.length, 0);
+  });
+});

package/tests/interaction-states.test.js

@@ -0,0 +1,62 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { extractInteractionStates } from '../src/extractors/interaction-states.js';
+
+describe('extractInteractionStates', () => {
+  it('returns a default shape on empty input', () => {
+    const r = extractInteractionStates(null);
+    assert.equal(r.scrollSettled, false);
+    assert.equal(r.menusOpened, 0);
+    assert.deepEqual(r.modals, []);
+    assert.equal(r.hover.sampled, 0);
+  });
+
+  it('computes hover deltas between before/after style snapshots', () => {
+    const r = extractInteractionStates({
+      scrollSettled: true,
+      menusOpened: 2,
+      hoverSamples: [
+        {
+          selector: 'button:nth-of-type(1)',
+          before: { color: 'rgb(0,0,0)', backgroundColor: 'rgb(255,255,255)' },
+          after: { color: 'rgb(0,0,0)', backgroundColor: 'rgb(240,240,240)' },
+        },
+        {
+          selector: 'a:nth-of-type(1)',
+          before: { color: 'rgb(0,0,0)' },
+          after: { color: 'rgb(0,0,0)' },
+        },
+      ],
+      accordionsOpened: 3,
+      modals: [],
+    });
+    assert.equal(r.hover.sampled, 2);
+    assert.equal(r.hover.changed, 1);
+    assert.equal(r.hover.deltas[0].changes.backgroundColor.from, 'rgb(255,255,255)');
+    assert.equal(r.hover.deltas[0].changes.backgroundColor.to, 'rgb(240,240,240)');
+    assert.equal(r.accordionsOpened, 3);
+    assert.equal(r.menusOpened, 2);
+    assert.equal(r.scrollSettled, true);
+  });
+
+  it('normalizes modal snapshots', () => {
+    const r = extractInteractionStates({
+      modals: [
+        { trigger: 'Sign in', snapshot: { tag: 'dialog', role: 'dialog', bg: 'rgb(255,255,255)', color: 'rgb(17,17,17)', boxShadow: '0 10px 30px rgba(0,0,0,.2)', borderRadius: '12px', width: 400, height: 300 } },
+      ],
+    });
+    assert.equal(r.modals.length, 1);
+    assert.equal(r.modals[0].trigger, 'Sign in');
+    assert.equal(r.modals[0].bg, 'rgb(255,255,255)');
+    assert.equal(r.modals[0].width, 400);
+  });
+
+  it('handles missing snapshot fields gracefully', () => {
+    const r = extractInteractionStates({
+      hoverSamples: [{ selector: 'x', before: null, after: null }],
+      modals: [{ trigger: 'Menu' }],
+    });
+    assert.equal(r.hover.changed, 0);
+    assert.equal(r.modals[0].bg, '');
+  });
+});

package/tests/modern-css.test.js

@@ -0,0 +1,104 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { extractModernCss } from '../src/extractors/modern-css.js';
+
+function mkStyle(overrides = {}) {
+  return {
+    tag: 'div',
+    classList: '',
+    fontVariationSettings: 'normal',
+    fontFeatureSettings: 'normal',
+    textWrap: '',
+    textDecorationStyle: '',
+    textDecorationThickness: '',
+    textUnderlineOffset: '',
+    pseudo: null,
+    ...overrides,
+  };
+}
+
+describe('extractModernCss', () => {
+  it('returns zeroed structure for empty payload', () => {
+    const r = extractModernCss({});
+    assert.equal(r.pseudoElements.count, 0);
+    assert.equal(r.variableFonts.count, 0);
+    assert.equal(r.containerQueries.count, 0);
+    assert.deepEqual(r.envUsage, []);
+  });
+
+  it('counts pseudo-elements and captures samples', () => {
+    const light = {
+      computedStyles: [
+        mkStyle({ tag: 'a', pseudo: { before: { content: '"→"', color: 'red' }, after: null } }),
+        mkStyle({ tag: 'li', pseudo: { before: { content: '"•"' }, after: { content: '"x"' } } }),
+      ],
+    };
+    const r = extractModernCss({ light });
+    assert.equal(r.pseudoElements.count, 3);
+    assert.ok(r.pseudoElements.samples.length >= 2);
+    assert.equal(r.pseudoElements.samples[0].which, '::before');
+  });
+
+  it('aggregates variable-font axes with min/max', () => {
+    const light = {
+      computedStyles: [
+        mkStyle({ fontVariationSettings: '"wght" 400, "slnt" 0' }),
+        mkStyle({ fontVariationSettings: '"wght" 700, "slnt" -8' }),
+      ],
+    };
+    const r = extractModernCss({ light });
+    assert.equal(r.variableFonts.count, 2);
+    const wght = r.variableFonts.axes.find(a => a.axis === 'wght');
+    assert.ok(wght);
+    assert.equal(wght.min, 400);
+    assert.equal(wght.max, 700);
+    const slnt = r.variableFonts.axes.find(a => a.axis === 'slnt');
+    assert.equal(slnt.min, -8);
+    assert.equal(slnt.max, 0);
+  });
+
+  it('collects OpenType features and counts', () => {
+    const light = {
+      computedStyles: [
+        mkStyle({ fontFeatureSettings: '"ss01" on, "cv11"' }),
+        mkStyle({ fontFeatureSettings: '"ss01"' }),
+      ],
+    };
+    const r = extractModernCss({ light });
+    const ss01 = r.openTypeFeatures.find(f => f.feature === 'ss01');
+    assert.equal(ss01.count, 2);
+    const cv11 = r.openTypeFeatures.find(f => f.feature === 'cv11');
+    assert.equal(cv11.count, 1);
+  });
+
+  it('collects modern text-layout properties', () => {
+    const light = {
+      computedStyles: [
+        mkStyle({ textWrap: 'balance', textDecorationStyle: 'wavy', textDecorationThickness: '2px', textUnderlineOffset: '3px' }),
+        mkStyle({ textWrap: 'balance' }),
+        mkStyle({ textWrap: 'pretty' }),
+      ],
+    };
+    const r = extractModernCss({ light });
+    const balance = r.textWrap.wrap.find(w => w.value === 'balance');
+    assert.equal(balance.count, 2);
+    assert.equal(r.textWrap.decorationStyle[0].value, 'wavy');
+    assert.equal(r.textWrap.decorationThickness[0].value, '2px');
+    assert.equal(r.textWrap.underlineOffset[0].value, '3px');
+  });
+
+  it('passes through container queries and env() usage', () => {
+    const light = {
+      computedStyles: [],
+      containerQueries: [
+        { condition: '(min-width: 480px)', selectorText: '.card', declarationCount: 3 },
+      ],
+      envUsage: ['safe-area-inset-top', 'safe-area-inset-top', 'viewport-segment-top'],
+    };
+    const r = extractModernCss({ light });
+    assert.equal(r.containerQueries.count, 1);
+    assert.equal(r.containerQueries.rules[0].condition, '(min-width: 480px)');
+    assert.equal(r.envUsage.length, 2);
+    assert.ok(r.envUsage.includes('safe-area-inset-top'));
+  });
+});