@cparkerwebm/webmonterey 1.0.0

package/src/cli/codemods.test.ts

@@ -0,0 +1,42 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { codemodsBetween, CODEMODS, type Codemod } from './codemods.ts';
+
+const stub = (version: string): Codemod => ({ version, title: version, run: () => [] });
+const ALL = [stub('3.0.0'), stub('1.1.0'), stub('2.1.0'), stub('2.0.0')];
+const versions = (from: string, to: string) => codemodsBetween(from, to, ALL).map((c) => c.version);
+
+test('the shipped codemods are exactly the versions this release claims', () => {
+  // A registry assertion rather than nothing: adding a codemod is a deliberate act somebody
+  // reviews, and this line is where the review happens.
+  assert.deepEqual(
+    CODEMODS.map((c) => c.version),
+    [],
+  );
+});
+
+test('the range is exclusive at the bottom and inclusive at the top', () => {
+  // 1.1.0's codemod already ran when the site landed on 1.1.0.
+  assert.deepEqual(versions('1.1.0', '2.0.0'), ['2.0.0']);
+  assert.deepEqual(versions('1.0.0', '2.0.0'), ['1.1.0', '2.0.0']);
+});
+
+test('results are ordered by version, whatever order they were registered in', () => {
+  assert.deepEqual(versions('1.0.0', '3.0.0'), ['1.1.0', '2.0.0', '2.1.0', '3.0.0']);
+});
+
+test('an upgrade that skips majors runs every codemod in between', () => {
+  assert.deepEqual(versions('1.0.0', '2.1.0'), ['1.1.0', '2.0.0', '2.1.0']);
+});
+
+test('no movement runs nothing', () => {
+  assert.deepEqual(versions('2.0.0', '2.0.0'), []);
+});
+
+test('a fresh install runs everything up to the installed version', () => {
+  assert.deepEqual(versions('0.0.0', '2.0.0'), ['1.1.0', '2.0.0']);
+});
+
+test('a two-part version is treated as x.y.0', () => {
+  assert.deepEqual(versions('2.0', '2.1.0'), ['2.1.0']);
+});

package/src/cli/codemods.ts

@@ -0,0 +1,51 @@
+/*
+ * Codemods, keyed by the version that introduces the break.
+ *
+ * A MAJOR WITHOUT A CODEMOD IS A MAJOR THAT WILL NOT GET ADOPTED. Generation 1 is the evidence:
+ * it shipped a framework that six sites could have used and one did, because moving forward meant
+ * hand-editing every consumer.
+ *
+ * Each entry runs against a site root and reports what it changed. They must be IDEMPOTENT - a
+ * half-finished upgrade gets re-run, and a codemod that doubles an import on the second pass is
+ * worse than no codemod.
+ */
+export interface Codemod {
+  /** The version whose changes this handles, e.g. '2.0.0'. */
+  version: string;
+  title: string;
+  /** Returns a description of every change made. Empty means nothing needed doing. */
+  run(siteRoot: string): string[];
+}
+
+/*
+ * EMPTY AT 1.0.0, and that is the registry's normal state. A codemod is added in the same change
+ * as the break it repairs, and a test asserts the list is exactly what the release claims - so
+ * adding one is a deliberate act somebody reviews rather than a surprise.
+ *
+ * The shape to copy when the first one arrives: read the site's file, MERGE the change in
+ * (never replace a file the site may have added to), and return [] when there is nothing left to
+ * do, so a second run is a no-op.
+ */
+export const CODEMODS: Codemod[] = [];
+
+/** Semver compare, on the three numeric parts only. Prerelease tags are not used here. */
+function compareVersions(a: string, b: string): number {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) - (pb[i] ?? 0);
+  return 0;
+}
+
+/**
+ * Codemods that apply when moving from `from` to `to`, in version order.
+ *
+ * Exclusive at the bottom, inclusive at the top: upgrading 1.1.0 -> 2.0.0 runs 2.0.0's codemod
+ * and not 1.1.0's, which already ran when the site landed on 1.1.0.
+ *
+ * `list` is injectable so the range logic is testable without registering a real codemod.
+ */
+export function codemodsBetween(from: string, to: string, list: Codemod[] = CODEMODS): Codemod[] {
+  return list
+    .filter((c) => compareVersions(c.version, from) > 0 && compareVersions(c.version, to) <= 0)
+    .sort((a, b) => compareVersions(a.version, b.version));
+}

package/src/cli/compare.test.ts

@@ -0,0 +1,144 @@
+/*
+ * The rebuild comparison. Each layer exists because the one before it missed something real.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { visibleText, headTags, jsonLd, cssDeclarations, compare } from './compare.ts';
+
+test('visible text ignores scripts, styles and comments', () => {
+  const html = `<html><head><style>.a{color:red}</style></head>
+    <body><!-- hidden --><script>var x=1</script><p>Hello there</p></body></html>`;
+  assert.equal(visibleText(html), 'Hello there');
+});
+
+test('text alone would have passed a rebuild that lost its typeface', () => {
+  /*
+   * THIS IS WHY THERE ARE FOUR LAYERS. On the webmonterey.com rebuild, comparing text reported
+   * "identical on every page" while the site had silently stopped loading its self-hosted font -
+   * every word present, in the wrong face. The words are the same here too.
+   */
+  const before = `<html><head><link rel="stylesheet" href="/a.css"></head><body><p>Same words</p></body></html>`;
+  const after = `<html><head></head><body><p>Same words</p></body></html>`;
+  assert.equal(visibleText(before), visibleText(after), 'text cannot see it');
+  assert.notDeepEqual(headTags(before), headTags(after), 'the head layer can');
+});
+
+test('head tags are order-independent, because head order is not meaningful', () => {
+  const a = `<head><meta name="a" content="1"><link rel="canonical" href="/x"></head>`;
+  const b = `<head><link rel="canonical" href="/x"><meta name="a" content="1"></head>`;
+  assert.deepEqual(headTags(a), headTags(b));
+});
+
+test('a changed canonical is caught', () => {
+  const a = `<head><link rel="canonical" href="/x"></head>`;
+  const b = `<head><link rel="canonical" href="/y"></head>`;
+  assert.notDeepEqual(headTags(a), headTags(b));
+});
+
+test('JSON-LD is compared as parsed data, not as text', () => {
+  // Key order and whitespace change between builds and mean nothing.
+  const a = `<script type="application/ld+json">{"a":1,"b":2}</script>`;
+  const b = `<script type="application/ld+json">{"a":1,"b":2}</script>`;
+  assert.equal(jsonLd(a), jsonLd(b));
+  const c = `<script type="application/ld+json">{"a":1}</script>`;
+  assert.notEqual(jsonLd(a), jsonLd(c));
+});
+
+test('malformed JSON-LD does not throw, it falls back to raw text', () => {
+  const bad = `<script type="application/ld+json">{not json</script>`;
+  assert.match(jsonLd(bad), /not json/);
+});
+
+test('bundler hashes in asset URLs are not a difference', () => {
+  /*
+   * The hash is content-derived and changes every build. Without stripping it, every stylesheet
+   * and script tag reads as both missing and added on a rebuild that changed nothing - and a
+   * comparison tool that cries wolf on every run is one nobody reads.
+   */
+  const a = `<head><link rel="stylesheet" href="/_astro/base.D8TeHbgD.css"></head>`;
+  const b = `<head><link rel="stylesheet" href="/_astro/base.B7aTneAO.css"></head>`;
+  assert.deepEqual(headTags(a), headTags(b));
+});
+
+test('a genuinely different stylesheet is still caught', () => {
+  const a = `<head><link rel="stylesheet" href="/_astro/base.AAAAAAAA.css"></head>`;
+  const b = `<head><link rel="stylesheet" href="/_astro/other.BBBBBBBB.css"></head>`;
+  assert.notDeepEqual(headTags(a), headTags(b), 'the NAME differs, not just the hash');
+});
+
+test('CSS is gathered from inline <style> as well as from files', () => {
+  /*
+   * Astro inlines a small stylesheet into the HTML instead of emitting a file, and which way it
+   * goes depends on size - so the same rule sits in _astro/*.css on one build and inside <style>
+   * on the next. Reading only the files reported a whole component stylesheet as missing when it
+   * had simply moved, on a rebuild that was correct.
+   */
+  const dir = mkdtempSync(join(tmpdir(), 'webm-cmp-'));
+  mkdirSync(join(dir, '_astro'), { recursive: true });
+  writeFileSync(join(dir, '_astro', 'a.css'), '.from-file{color:red}');
+  writeFileSync(
+    join(dir, 'index.html'),
+    '<html><head><style>.inlined{padding:1rem}</style></head></html>',
+  );
+
+  const decls = cssDeclarations(dir);
+  assert.ok(
+    [...decls].some((d) => d.includes('color:red')),
+    'the file',
+  );
+  assert.ok(
+    [...decls].some((d) => d.includes('padding:1rem')),
+    'and the inline block',
+  );
+});
+
+test('a build that only GAINS css declarations is not a regression', () => {
+  /*
+   * The case that nearly cost the tool its credibility. A package upgrade adds declarations and
+   * removes none, and the old summary line said "no differences in ... CSS" - which is false, and
+   * false in the direction that makes you doubt a working tool. Worse, it hides the evidence that
+   * an upgrade landed at all.
+   */
+  const dir = mkdtempSync(join(tmpdir(), 'cmp-'));
+  const oldDist = join(dir, 'old');
+  const newDist = join(dir, 'new');
+  for (const d of [oldDist, newDist]) mkdirSync(join(d, '_astro'), { recursive: true });
+
+  writeFileSync(join(oldDist, 'index.html'), '<html><body><p>Same words</p></body></html>');
+  writeFileSync(join(newDist, 'index.html'), '<html><body><p>Same words</p></body></html>');
+  writeFileSync(join(oldDist, '_astro', 'a.css'), 'a{color:red}');
+  writeFileSync(join(newDist, '_astro', 'a.css'), 'a{color:red}b{outline:1px solid blue}');
+
+  const diffs = compare(oldDist, newDist);
+  assert.equal(diffs.length, 1, 'the gain is reported');
+  assert.equal(diffs[0]!.info, true, 'but it is not a regression');
+  assert.deepEqual(diffs[0]!.missing, [], 'nothing was lost');
+  assert.ok(
+    diffs[0]!.added.some((d) => d.includes('outline:1px solid blue')),
+    'and the new declaration is named, so you can see the upgrade landed',
+  );
+
+  rmSync(dir, { recursive: true, force: true });
+});
+
+test('a lost declaration is still a regression even when others are gained', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'cmp-'));
+  const oldDist = join(dir, 'old');
+  const newDist = join(dir, 'new');
+  for (const d of [oldDist, newDist]) mkdirSync(join(d, '_astro'), { recursive: true });
+
+  writeFileSync(join(oldDist, 'index.html'), '<html><body><p>Same words</p></body></html>');
+  writeFileSync(join(newDist, 'index.html'), '<html><body><p>Same words</p></body></html>');
+  writeFileSync(join(oldDist, '_astro', 'a.css'), '@font-face{src:url(x.woff2)}');
+  writeFileSync(join(newDist, '_astro', 'a.css'), 'b{outline:1px solid blue}');
+
+  const diffs = compare(oldDist, newDist);
+  const css = diffs.find((d) => d.layer === 'css')!;
+  assert.notEqual(css.info, true, 'a loss is never downgraded to information');
+  assert.ok(css.missing.some((d) => d.includes('url(x.woff2)')));
+
+  rmSync(dir, { recursive: true, force: true });
+});

package/src/cli/compare.ts

@@ -0,0 +1,222 @@
+/*
+ * `webm compare <old-dist> <new-dist>` - did the rebuild change anything a visitor can see?
+ *
+ * A rebuild moves every file in a site. The only honest way to know it is faithful is to build
+ * the old one, build the new one, and diff the OUTPUT - the source is expected to differ
+ * everywhere, so comparing source proves nothing.
+ *
+ * FOUR LAYERS, BECAUSE THE FIRST ONE ALONE LIES. Comparing rendered text on the webmonterey.com
+ * rebuild reported "identical on every page" while the site had silently stopped loading its
+ * self-hosted typeface: the words were all present, in the wrong font. Text, head, structured
+ * data and CSS each catch a different class of regression and none subsumes another.
+ *
+ *   text    visible words, tags stripped        content loss, duplicated headings
+ *   head    meta and link tags                  canonical, robots, Open Graph, favicons
+ *   jsonld  the structured-data graph           the SEO surface, which no page shows
+ *   css     every declaration in the bundle     fonts, tokens, whole stylesheets not imported
+ *
+ * Astro's per-build scope hashes are normalized away, or every component rule reads as changed.
+ */
+import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+export interface Diff {
+  layer: 'text' | 'head' | 'jsonld' | 'css';
+  /* Reported, but not a regression - it does not fail the run. Only CSS gains use this: a
+   * declaration the new build serves and the old did not is the expected shape of a package
+   * upgrade, and staying silent about it made the summary line claim there was no difference
+   * at all. Seeing the gain is how you confirm a fix actually reached the bundle. */
+  info?: boolean;
+  page: string;
+  missing: string[];
+  added: string[];
+}
+
+function walk(dir: string, match: (f: string) => boolean): string[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true }).flatMap((e) => {
+    const full = join(dir, e.name);
+    return e.isDirectory() ? walk(full, match) : match(e.name) ? [full] : [];
+  });
+}
+
+/** Visible words, with script, style and comments removed. */
+export function visibleText(html: string): string {
+  return html
+    .replace(/<(script|style)[^>]*>[\s\S]*?<\/\1>/gi, ' ')
+    .replace(/<!--[\s\S]*?-->/g, ' ')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/&[a-z]+;|&#\d+;/gi, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/**
+ * Every meta and link tag, normalized and sorted - order in <head> is not meaningful.
+ *
+ * BUNDLER HASHES ARE STRIPPED. `/_astro/base.D8TeHbgD.css` becomes `/_astro/base.css`: the hash
+ * is content-derived and changes on every build, so without this every stylesheet and script tag
+ * reads as both missing and added on a rebuild that changed nothing. That noise is what makes a
+ * comparison tool get ignored.
+ */
+export function headTags(html: string): string[] {
+  const head = html.slice(0, html.indexOf('</head>') + 1);
+  return [...head.matchAll(/<(meta|link)\b[^>]*>/gi)]
+    .map((m) =>
+      m[0]
+        .replace(/\s+/g, ' ')
+        .replace(/\.[A-Za-z0-9_-]{8,}\.(css|js|woff2?|png|jpg|webp|svg)/g, '.$1')
+        /*
+         * Server-island preloads carry the island's ENCRYPTED PROPS in the query string, and
+         * those are re-encrypted every build. Without this each one reads as both missing and
+         * added, on every page that defers anything.
+         */
+        .replace(/(\/_server-islands\/[A-Za-z0-9_-]+)\?[^"']*/g, '$1'),
+    )
+    .sort();
+}
+
+export function jsonLd(html: string): string {
+  const blocks = [
+    ...html.matchAll(/<script[^>]+application\/ld\+json[^>]*>([\s\S]*?)<\/script>/gi),
+  ];
+  try {
+    return JSON.stringify(
+      blocks.map((b) => JSON.parse(b[1]!)),
+      null,
+      1,
+    );
+  } catch {
+    return blocks.map((b) => b[1]).join('\n');
+  }
+}
+
+/**
+ * Every CSS declaration in the bundle, as a set.
+ *
+ * A set rather than a diff of files: the bundler splits and names files differently between
+ * builds, so file-level comparison is noise. What matters is whether a declaration that used to
+ * be served still is.
+ */
+export function cssDeclarations(dist: string): Set<string> {
+  /*
+   * BOTH SOURCES, and missing the second one makes this lie. Astro INLINES a small stylesheet
+   * into the HTML rather than emitting a file, and which way it goes depends on size - so the
+   * same rule can be in _astro/*.css on one build and inside <style> on the next. Reading only
+   * the files reported a component's entire stylesheet as missing when it had simply moved.
+   */
+  const inline = walk(dist, (f) => f.endsWith('.html'))
+    .flatMap((f) => [...readFileSync(f, 'utf8').matchAll(/<style[^>]*>([\s\S]*?)<\/style>/gi)])
+    .map((m) => m[1]!);
+
+  const css = [
+    ...walk(join(dist, '_astro'), (f) => f.endsWith('.css')).map((f) => readFileSync(f, 'utf8')),
+    ...inline,
+  ]
+    .join('\n')
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    /* Astro's scope hash changes every build; without this every scoped rule reads as changed. */
+    .replace(/\[data-astro-cid-[a-z0-9]+\]/gi, '');
+
+  return new Set(
+    css
+      .split(/[{};]/)
+      .map((d) => d.trim())
+      .filter((d) => d.includes(':') && d.length < 300),
+  );
+}
+
+const setDiff = (a: Set<string>, b: Set<string>) => [...a].filter((x) => !b.has(x));
+const words = (s: string) => new Set(s.split(' ').filter(Boolean));
+
+export function compare(oldDist: string, newDist: string): Diff[] {
+  const diffs: Diff[] = [];
+  const pages = walk(oldDist, (f) => f.endsWith('.html')).map((f) => relative(oldDist, f));
+
+  for (const page of pages) {
+    const a = readFileSync(join(oldDist, page), 'utf8');
+    const bPath = join(newDist, page);
+    if (!existsSync(bPath)) {
+      diffs.push({ layer: 'text', page, missing: ['THE WHOLE PAGE'], added: [] });
+      continue;
+    }
+    const b = readFileSync(bPath, 'utf8');
+
+    const at = words(visibleText(a));
+    const bt = words(visibleText(b));
+    if (setDiff(at, bt).length || setDiff(bt, at).length) {
+      diffs.push({ layer: 'text', page, missing: setDiff(at, bt), added: setDiff(bt, at) });
+    }
+
+    const ah = new Set(headTags(a));
+    const bh = new Set(headTags(b));
+    if (setDiff(ah, bh).length || setDiff(bh, ah).length) {
+      diffs.push({ layer: 'head', page, missing: setDiff(ah, bh), added: setDiff(bh, ah) });
+    }
+
+    if (jsonLd(a) !== jsonLd(b)) {
+      diffs.push({ layer: 'jsonld', page, missing: ['graph differs'], added: [] });
+    }
+  }
+
+  const ac = cssDeclarations(oldDist);
+  const bc = cssDeclarations(newDist);
+  const lost = setDiff(ac, bc);
+  const gained = setDiff(bc, ac);
+  if (lost.length) {
+    /*
+     * Only LOST declarations fail. The new build legitimately gains rules - a package base rule
+     * that the old site had edited in place now sits alongside the override that supersedes it.
+     * A declaration that vanished is the regression.
+     */
+    diffs.push({ layer: 'css', page: '(bundle)', missing: lost, added: gained });
+  } else if (gained.length) {
+    diffs.push({ layer: 'css', page: '(bundle)', missing: [], added: gained, info: true });
+  }
+
+  return diffs;
+}
+
+export function run(argv: string[]): number {
+  const [oldDist, newDist] = argv;
+  if (!oldDist || !newDist) {
+    console.error('webm compare <old-dist/client> <new-dist/client>');
+    console.error('\n  Build both sites first. Compares text, head tags, JSON-LD and CSS.');
+    return 1;
+  }
+  for (const d of [oldDist, newDist]) {
+    if (!existsSync(d) || !statSync(d).isDirectory()) {
+      console.error(`webm compare: no such directory: ${d}`);
+      return 1;
+    }
+  }
+
+  const diffs = compare(oldDist, newDist);
+  const pages = walk(oldDist, (f) => f.endsWith('.html')).length;
+  const regressions = diffs.filter((d) => !d.info);
+
+  if (!diffs.length) {
+    console.log(`webm compare: ${pages} pages, no differences in text, head, JSON-LD or CSS.`);
+    return 0;
+  }
+
+  for (const d of diffs) {
+    console.log(`\n${d.layer.toUpperCase()}${d.info ? ' (not a regression)' : ''}  ${d.page}`);
+    for (const m of d.missing.slice(0, 25)) console.log(`  - ${m.slice(0, 160)}`);
+    if (d.missing.length > 25) console.log(`  … ${d.missing.length - 25} more missing`);
+    for (const a of d.added.slice(0, 10)) console.log(`  + ${a.slice(0, 160)}`);
+    if (d.added.length > 10) console.log(`  … ${d.added.length - 10} more added`);
+  }
+  if (!regressions.length) {
+    console.log(
+      `\nwebm compare: ${pages} pages, no regressions in text, head, JSON-LD or CSS.` +
+        ` The additions above are what the new build serves and the old did not.`,
+    );
+    return 0;
+  }
+
+  console.log(
+    `\n${regressions.length} differences across ${pages} pages. A "-" line is something the old site served and the new one does not.`,
+  );
+  return 1;
+}

package/src/cli/design-extract.test.ts

@@ -0,0 +1,96 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { extract, parseTokens } from './design-extract.ts';
+import { compileToCss } from '../design/compile.ts';
+
+test('a stylesheet identical to the defaults extracts to an empty design', () => {
+  const r = extract(compileToCss());
+  assert.equal(r.mapped.length, 0);
+  assert.equal(r.overridden.length, 0);
+  assert.equal(r.added.length, 0);
+  assert.deepEqual(r.design, { version: 1 });
+});
+
+test('a changed brand color maps to a structured field, not an override', () => {
+  const r = extract(compileToCss({ color: { action: { base: '#bfb23b' } } }));
+  assert.deepEqual(r.design.color?.action, { base: '#bfb23b' });
+  assert.equal(r.design.overrides, undefined);
+  assert.deepEqual(r.mapped, ['--webm-action']);
+});
+
+test('a changed token with no structured field falls back to overrides, and is reported', () => {
+  const r = extract(compileToCss({ overrides: { '--webm-space-md': '2rem' } }));
+  assert.deepEqual(r.design.overrides, { '--webm-space-md': '2rem' });
+  assert.deepEqual(r.overridden, ['--webm-space-md']);
+  assert.deepEqual(r.added, []);
+});
+
+test('a token the system does not define is reported separately as a site token', () => {
+  const r = extract(':root { --webm-hero-height: 80vh; }');
+  assert.deepEqual(r.added, ['--webm-hero-height']);
+  assert.deepEqual(r.design.overrides, { '--webm-hero-height': '80vh' });
+});
+
+test('extraction round-trips: extract then compile reproduces the input', () => {
+  const original = compileToCss({
+    color: { action: { base: '#bfb23b' }, base: { '700': '#2f3030' } },
+    font: { sans: '"DM Sans", system-ui, sans-serif' },
+    overrides: { '--webm-space-md': '2rem', '--webm-hero-height': '80vh' },
+  });
+  const rebuilt = compileToCss(extract(original).design);
+  assert.deepEqual(parseTokens(rebuilt), parseTokens(original));
+});
+
+test('comments are ignored, so a commented-out token is not extracted', () => {
+  const r = extract(':root { /* --webm-action: #ff0000; */ --webm-action: #00ff00; }');
+  assert.equal(r.design.color?.action?.base, '#00ff00');
+});
+
+test('a token overridden inside @media does not overwrite its base value', () => {
+  /*
+   * THE MIGRATION BUG. The old parser was a flat regex, last-write-wins, so the reduced-motion
+   * override became the site's real value. Converting webmonterey.com that way wrote
+   * --webm-duration-fast: 0ms as the base: every animation disabled for every visitor, from a
+   * command that printed success.
+   */
+  const css = `
+    @layer webm.tokens {
+      :root {
+        --webm-duration-fast: 140ms;
+        --webm-chrome-inset: var(--webm-space-16);
+      }
+      @media (prefers-reduced-motion: reduce) {
+        :root { --webm-duration-fast: 0ms; }
+      }
+      @media (width < 48rem) {
+        :root { --webm-chrome-inset: var(--webm-space-sm); }
+      }
+    }
+  `;
+  const { base, conditional } = parseTokens(css);
+
+  assert.equal(base.get('--webm-duration-fast'), '140ms', 'the REAL value, not the media override');
+  assert.equal(base.get('--webm-chrome-inset'), 'var(--webm-space-16)');
+  assert.ok(conditional.has('--webm-duration-fast'), 'the override is reported, not lost');
+  assert.match(conditional.get('--webm-duration-fast')!.join(' '), /prefers-reduced-motion/);
+  assert.match(conditional.get('--webm-chrome-inset')!.join(' '), /width < 48rem/);
+});
+
+test('a conditional-only token never becomes a base value', () => {
+  const css = `
+    :root { --webm-action: #006abe; }
+    @media print { :root { --webm-action: #000000; } }
+  `;
+  const { base, conditional } = parseTokens(css);
+  assert.equal(base.get('--webm-action'), '#006abe');
+  assert.deepEqual(conditional.get('--webm-action'), ['@media print']);
+});
+
+test('extract reports the conditional tokens it could not carry across', () => {
+  const result = extract(`
+    :root { --webm-duration-fast: 140ms; }
+    @media (prefers-reduced-motion: reduce) { :root { --webm-duration-fast: 0ms; } }
+  `);
+  assert.equal(result.design.overrides?.['--webm-duration-fast'], '140ms');
+  assert.ok(result.conditional.has('--webm-duration-fast'));
+});