@astryxdesign/cli 0.6.3-canary.ea2f048 → 0.6.3-canary.ee13359

package/api/theme/add/add.staging.test.mjs

@@ -0,0 +1,66 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {themeAdd} from './add.mjs';
+import {listThemes} from '../_adapter.mjs';
+import {isErrorCode} from '../../../foundation/response/error-codes.mjs';
+
+let tmpDir;
+let outsideDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-themeadd-staging-'));
+  outsideDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-themeadd-outside-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+  fs.rmSync(outsideDir, {recursive: true, force: true});
+});
+
+/**
+ * Put a symlink where `theme add` stages the first file of `slug`.
+ * @param {string} slug
+ * @param {string} target
+ */
+function plantStagingLink(slug, target) {
+  const theme = listThemes().find(entry => entry.slug === slug);
+  if (!theme) throw new Error(`missing bundled theme ${slug}`);
+  const first = theme.files[0];
+  const dest = path.join(tmpDir, 'src', 'themes', slug, first);
+  fs.mkdirSync(path.dirname(dest), {recursive: true});
+  fs.symlinkSync(target, `${dest}.${process.pid}.tmp`);
+  return dest;
+}
+
+describe('themeAdd staging writes stay inside the project', () => {
+  it('refuses a staging path that links outside the project', async () => {
+    const victim = path.join(outsideDir, 'victim.txt');
+    fs.writeFileSync(victim, 'outside\n');
+    const dest = plantStagingLink('stone', victim);
+
+    await expect(themeAdd('stone', {cwd: tmpDir})).rejects.toMatchObject({
+      code: 'ERR_PATH_TRAVERSAL',
+    });
+    expect(fs.readFileSync(victim, 'utf-8')).toBe('outside\n');
+    expect(fs.existsSync(dest)).toBe(false);
+  });
+
+  it('never creates a file through a dangling staging link', async () => {
+    const victim = path.join(outsideDir, 'created.txt');
+    plantStagingLink('stone', victim);
+
+    let error;
+    try {
+      await themeAdd('stone', {cwd: tmpDir});
+    } catch (caught) {
+      error = caught;
+    }
+
+    expect(isErrorCode(error?.code)).toBe(true);
+    expect(fs.existsSync(victim)).toBe(false);
+  });
+});

package/api/theme/add/add.test.mjs

@@ -30,7 +30,20 @@ describe('themeAdd (api/theme/add)', () => {
     expect(result.data.slug).toBe('neutral');
     expect(result.data.package).toBe('@astryxdesign/cli');
     expect(result.data.outputDir).toBe(path.join('src', 'themes', 'neutral'));
-    expect(result.data.files.length).toBeGreaterThan(0);
+    // Exactly what the bundle has always copied, in that order: the CLI's own
+    // descriptor stays behind.
+    expect(result.data.files).toEqual([
+      'neutralTheme.ts',
+      'icons.tsx',
+      'neutralPalettes.ts',
+      'neutralPalettes.generated.ts',
+      'neutralPaletteRefs.generated.ts',
+      'neutralPalettes.generated.receipt.json',
+      'palette.config.json',
+    ]);
+    expect(
+      fs.readdirSync(path.join(tmpDir, 'src', 'themes', 'neutral')).sort(),
+    ).toEqual([...result.data.files].sort());
     for (const f of result.data.files) {
       expect(
         fs.existsSync(path.join(tmpDir, 'src', 'themes', 'neutral', f)),

package/api/theme/build/build.mjs

@@ -12,9 +12,10 @@
  * - A .d.ts (plus an optional .variants.d.ts for custom prop values)
  *
  * It performs the writes and returns a `theme.build` receipt — its `warnings`
- * carry override problems and any fonts the theme names but does not load
- * (font-warning.mjs) — or `null` when the theme produced no CSS (nothing to
- * build). Errors throw AstryxError (with
+ * carry override problems, every declaration core's generator dropped because
+ * its value could not stay one CSS declaration, and any fonts the theme names
+ * but does not load (font-warning.mjs) — or `null` when the theme produced no
+ * CSS (nothing to build). Errors throw AstryxError (with
  * a stable code). Human progress is emitted through the shared `logger`
  * (silent by default), so the CLI keeps its exact output while a programmatic
  * caller stays quiet.
@@ -223,10 +224,10 @@ function staleBuildOutputs(writes, cwd) {
 /** @param {Array<{dest: string, content: string}>} writes */
 function writeBuildOutputs(writes) {
   if (writes.length === 0) return;
-  fs.mkdirSync(path.dirname(writes[0].dest), {recursive: true});
   /** @type {Array<{tmp: string, dest: string}>} */
   const staged = [];
   try {
+    fs.mkdirSync(path.dirname(writes[0].dest), {recursive: true});
     for (const write of writes) {
       const tmp = `${write.dest}.${process.pid}.tmp`;
       fs.writeFileSync(tmp, write.content);
@@ -1870,7 +1871,7 @@ function validatePrivateVars(themeDef) {
           if (prop.startsWith('--_')) {
             errors.push(
               `Component "${component}" (${[key, ...path].join(' ')}) sets private var "${prop}". ` +
-                `Private vars (--_*) are internal — use standard CSS properties ` +
+                `Private vars (--_*) are internal; use standard CSS properties ` +
                 `(e.g. borderRadius, padding) instead. The pipeline expands them automatically.`,
             );
           }
@@ -1930,20 +1931,7 @@ function getThemeComponentLayers(themeDef) {
  */
 function validateCustomHeadingTypes(themeDef) {
   const layers = getThemeComponentLayers(themeDef);
-  const customTypes = new Set();
-  for (const {components} of layers) {
-    const headingRules = components.heading;
-    if (!headingRules || typeof headingRules !== 'object') continue;
-
-    for (const key of Object.keys(headingRules)) {
-      for (const pair of key.split('+')) {
-        const colon = pair.indexOf(':');
-        if (colon === -1 || pair.slice(0, colon) !== 'type') continue;
-        const value = pair.slice(colon + 1);
-        if (value && !BUILTIN_HEADING_TYPES.has(value)) customTypes.add(value);
-      }
-    }
-  }
+  const customTypes = customHeadingTypes(themeDef);
 
   const errors = [];
   for (const type of customTypes) {
@@ -1970,10 +1958,65 @@ function validateCustomHeadingTypes(themeDef) {
   return errors;
 }
 
+/**
+ * Custom Heading type names declared on the root or media-surface component
+ * maps: the names the generated `HeadingTypeMap` augmentation enrolls.
+ *
+ * @param {{components?: Record<string, Record<string, unknown>>}} themeDef
+ * @returns {Set<string>}
+ */
+function customHeadingTypes(themeDef) {
+  /** @type {Set<string>} */
+  const customTypes = new Set();
+  for (const {components} of getThemeComponentLayers(themeDef)) {
+    const headingRules = components.heading;
+    if (!headingRules || typeof headingRules !== 'object') continue;
+
+    for (const key of Object.keys(headingRules)) {
+      for (const pair of key.split('+')) {
+        const colon = pair.indexOf(':');
+        if (colon === -1 || pair.slice(0, colon) !== 'type') continue;
+        const value = pair.slice(colon + 1);
+        if (value && !BUILTIN_HEADING_TYPES.has(value)) customTypes.add(value);
+      }
+    }
+  }
+  return customTypes;
+}
+
+/**
+ * Custom Heading types with no standalone rule in the generated CSS. A type
+ * whose every declaration the compiler dropped still passes the source check,
+ * and its augmentation would then name a type that has no styles.
+ *
+ * @param {Set<string>} types
+ * @param {string} css - Generated root component and media-surface rules.
+ * @returns {string[]}
+ */
+function headingTypesWithoutEmittedRule(types, css) {
+  /** @type {string[]} */
+  const missing = [];
+  for (const type of types) {
+    const selector = `.astryx-heading[data-type="${type}"]`;
+    let emitted = false;
+    for (
+      let at = css.indexOf(selector);
+      at !== -1 && !emitted;
+      at = css.indexOf(selector, at + 1)
+    ) {
+      // A following attribute is a combined selector, not the standalone rule.
+      emitted = css[at + selector.length] !== '[';
+    }
+    if (!emitted) missing.push(type);
+  }
+  return missing;
+}
+
 /**
  * Return true when a style object contains a declaration that the theme
- * generator can emit. Empty pseudo blocks do not count: they produce no CSS
- * and would leave the generated type augmentation without a usable rule.
+ * generator can emit. Empty pseudo blocks and blank values do not count: they
+ * produce no usable CSS and would leave the generated type augmentation
+ * without a usable rule.
  *
  * @param {unknown} styles
  * @returns {boolean}
@@ -1987,7 +2030,12 @@ function hasUsableStyleDeclaration(styles) {
       if (hasUsableStyleDeclaration(value)) return true;
       continue;
     }
-    if (value !== undefined && value !== null && typeof value !== 'object') {
+    if (
+      value !== undefined &&
+      value !== null &&
+      typeof value !== 'object' &&
+      String(value).trim() !== ''
+    ) {
       return true;
     }
   }
@@ -2162,14 +2210,14 @@ async function themeBuildInternal(
   const noticeMessages = [];
   for (const w of warnings) {
     warningMessages.push(w);
-    logger.warn(`  ⚠ ${w}`);
+    logger.warn(`  [warn] ${w}`);
   }
 
   // Validate no private vars are set directly
   const privateVarErrors = validatePrivateVars(themeDef);
   for (const e of privateVarErrors) {
     warningMessages.push(e);
-    logger.error(`  ✗ ${e}`);
+    logger.error(`  [error] ${e}`);
   }
   if (privateVarErrors.length > 0) {
     logger.error(
@@ -2195,7 +2243,7 @@ async function themeBuildInternal(
   // capability exports are checked against what the theme actually asks for.
   if (!_defineTheme || !_generateThemeRulesSplit) {
     throw new AstryxError(
-      'Could not load @astryxdesign/core/theme — `astryx theme build` requires a ' +
+      'Could not load @astryxdesign/core/theme: `astryx theme build` requires a ' +
         'built, resolvable @astryxdesign/core so it emits the same CSS as the ' +
         'runtime <Theme>. Build @astryxdesign/core first (e.g. `pnpm -F @astryxdesign/core ' +
         'build`)' +
@@ -2303,7 +2351,15 @@ async function themeBuildInternal(
     const scopeSelector = themeScopeStart(themeDef.name);
     const scopeTo = THEME_SCOPE_TO;
 
-    const {component, prose} = _generateThemeRulesSplit(resolvedTheme);
+    // Older cores ignore this optional collector. Current core writes the same
+    // warning text here that runtime callers receive on the console.
+    /** @type {string[]} */
+    const droppedDeclarations = [];
+
+    const {component, prose} = _generateThemeRulesSplit(
+      resolvedTheme,
+      droppedDeclarations,
+    );
     const cssParts = [];
     // Prose element defaults always ship — the `<Theme>` runtime
     // (generateThemeCSS) always emits them, so the build must too, or the
@@ -2322,7 +2378,7 @@ async function themeBuildInternal(
     let adaptationCss;
     try {
       adaptationCss = _generateAdaptationCSS
-        ? _generateAdaptationCSS(resolvedTheme)
+        ? _generateAdaptationCSS(resolvedTheme, droppedDeclarations)
         : {component: '', prose: ''};
     } catch (error) {
       const message =
@@ -2368,13 +2424,37 @@ async function themeBuildInternal(
     // adaptations on the same resolved leaf.
     let onMediaCss = '';
     if (_generateOnMediaCSS) {
-      onMediaCss = _generateOnMediaCSS(resolvedTheme);
+      onMediaCss = _generateOnMediaCSS(resolvedTheme, droppedDeclarations);
       if (onMediaCss) {
         cssParts.push(`@layer astryx-theme {\n${onMediaCss}\n}`);
       }
     }
+    for (const message of droppedDeclarations) {
+      const w = `Declaration ${message}. The generated CSS omits it; fix the value in the theme source.`;
+      warningMessages.push(w);
+      logger.warn(`  [warn] ${w}`);
+    }
+    const unemittedHeadingTypes = headingTypesWithoutEmittedRule(
+      customHeadingTypes(themeDef),
+      `${component.join('\n')}\n${onMediaCss}`,
+    );
+    if (unemittedHeadingTypes.length > 0) {
+      throw new AstryxError(
+        unemittedHeadingTypes
+          .map(
+            type =>
+              `Custom Heading type "${type}" has no declaration the theme ` +
+              `compiler could emit: every declaration in its standalone ` +
+              `"type:${type}" rule was dropped. Give that rule at least one ` +
+              'valid declaration.',
+          )
+          .join('\n'),
+        undefined,
+        ERROR_CODES.ERR_THEME_INVALID,
+      );
+    }
     if (cssParts.length === 0) {
-      logger.log('No overrides found — nothing to build.');
+      logger.log('No overrides found; nothing to build.');
       return null;
     }
     // The data-token defaults are theme-independent and go in @layer
@@ -2425,7 +2505,18 @@ async function themeBuildInternal(
     // Guard: relative paths must not escape cwd via `../`. Absolute paths are
     // trusted (the user explicitly controls where output goes, like gcc -o).
     if (!path.isAbsolute(options.out)) {
-      assertWithin(options.out, cwd, {label: 'output path'});
+      try {
+        assertWithin(options.out, cwd, {label: 'output path'});
+      } catch (err) {
+        if (err instanceof PathSafetyError) {
+          throw new AstryxError(
+            err.message,
+            undefined,
+            ERROR_CODES.ERR_PATH_TRAVERSAL,
+          );
+        }
+        throw err;
+      }
     }
   } else {
     outPath = path.join(path.dirname(filePath), `${baseName}.css`);
@@ -2534,10 +2625,10 @@ async function themeBuildInternal(
     const stale = staleBuildOutputs(writes, cwd);
     const upToDate = stale.length === 0;
     if (upToDate) {
-      logger.log(`\n✓ Theme outputs are up to date with ${sourceRelative}.`);
+      logger.log(`\n[ok] Theme outputs are up to date with ${sourceRelative}.`);
     } else {
       logger.error(
-        `\n✗ ${stale.length} theme output(s) are out of date with ${sourceRelative}:`,
+        `\n[fail] ${stale.length} theme output(s) are out of date with ${sourceRelative}:`,
       );
       for (const s of stale) {
         logger.error(
@@ -2559,17 +2650,17 @@ async function themeBuildInternal(
 
   writeBuildOutputs(writes);
 
-  logger.log(`\n✓ ${path.relative(cwd, outPath)}`);
+  logger.log(`\n[ok] ${path.relative(cwd, outPath)}`);
   logger.log(
     `  ${tokenCount} token overrides, ${componentCount} component overrides`,
   );
   logger.log(`  ${size} KB`);
-  logger.log(`✓ ${path.relative(cwd, jsPath)}`);
-  logger.log(`✓ ${path.relative(cwd, dtsPath)}`);
+  logger.log(`[ok] ${path.relative(cwd, jsPath)}`);
+  logger.log(`[ok] ${path.relative(cwd, dtsPath)}`);
   if (variantDtsPath && variantDecl) {
     const augCount = (variantDecl.match(/': true;/g) || []).length;
     logger.log(
-      `✓ ${path.relative(cwd, variantDtsPath)} (${augCount} type augmentations)`,
+      `[ok] ${path.relative(cwd, variantDtsPath)} (${augCount} type augmentations)`,
     );
   }
 
@@ -2579,7 +2670,7 @@ async function themeBuildInternal(
   const cssImport = importSpecifier(relOutDir, cssBase) + '.css';
   const exportName = `${toIdentifier(baseName)}Theme`;
   logger.log(`
-Install in your app (paths are relative to a file in src/ — adjust if yours lives elsewhere):
+Install in your app (paths are relative to a file in src/; adjust if yours lives elsewhere):
 
   import { ${exportName} } from '${jsImport}';
   import '${cssImport}';
@@ -2611,7 +2702,7 @@ Or with a <link> tag:
   // Adaptation rules are resolved theme writes in their own right, so a family
   // named only inside one needs the same notice as one named at the root.
   for (const family of unloadedFonts) {
-    const msg = `Font "${family}" is named by this theme but not loaded — add a <link> or @font-face in your app (recipe: astryx docs typography)`;
+    const msg = `Font "${family}" is named by this theme but not loaded; add a <link> or @font-face in your app (recipe: astryx docs typography)`;
     noticeMessages.push(msg);
     logger.log(`  note: ${msg}`);
   }
@@ -2905,11 +2996,11 @@ export async function themeBuildFamily(
     const upToDate = stale.length === 0;
     if (upToDate) {
       logger.log(
-        `\n✓ Theme family outputs are up to date with ${sourceRelative}.`,
+        `\n[ok] Theme family outputs are up to date with ${sourceRelative}.`,
       );
     } else {
       logger.error(
-        `\n✗ ${stale.length} theme family output(s) are out of date:`,
+        `\n[fail] ${stale.length} theme family output(s) are out of date:`,
       );
       for (const entry of stale) {
         logger.error(
@@ -2929,7 +3020,7 @@ export async function themeBuildFamily(
     };
   }
   writeBuildOutputs(writes);
-  for (const output of Object.values(outputs)) logger.log(`✓ ${output}`);
+  for (const output of Object.values(outputs)) logger.log(`[ok] ${output}`);
   const themeBindings = members.map(member => bindings.get(member.theme.name));
   const relOutDir = path.relative(cwd, outDir) || '.';
   const jsImport = importSpecifier(relOutDir, baseName);
@@ -2947,7 +3038,7 @@ Or load the same stylesheet natively:
   ];
   const notices = unloadedFonts.map(
     family =>
-      `Font "${family}" is named by this theme family but not loaded — add a <link> or @font-face in your app (recipe: astryx docs typography)`,
+      `Font "${family}" is named by this theme family but not loaded; add a <link> or @font-face in your app (recipe: astryx docs typography)`,
   );
   for (const notice of notices) logger.log(`  note: ${notice}`);
   return {

package/api/theme/build/build.public-component-vars.test.mjs

@@ -19,7 +19,7 @@
  * next one is covered without touching this file.
  *
  * Asserted on the receipt's `warnings` rather than on a rejection: a private
- * var is reported (logged `✗`, collected into the receipt) and the build then
+ * var is reported (logged `[error]`, collected into the receipt) and the build then
  * emits its CSS and resolves anyway. Asserting a throw would pass for the
  * wrong reason — it never throws, which is why a throwaway build read as a
  * pass on the first version of #5214.

package/api/theme/build/build.receipt-doc.test.mjs

@@ -0,0 +1,111 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Every field `themeBuild()` returns is named in its FunctionDoc and in the
+ * response-types doc.
+ *
+ * The receipt is a stable machine-readable response, so each field needs
+ * consumer documentation, not only a typedef. The fields are read off a real
+ * build, so a field added to the receipt without documentation fails here.
+ */
+
+import {describe, it, expect, beforeAll, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {themeBuild} from './build.mjs';
+import {doc} from '../themeBuild.doc.mjs';
+import {doc as responseTypes} from '../../../foundation/response/response-types.doc.mjs';
+import {ensureCoreBuilt} from '../../../clients/cli/commands/ensure-core-built.mjs';
+
+/** @type {string[]} */
+const dirs = [];
+
+beforeAll(() => {
+  ensureCoreBuilt();
+}, 200_000);
+
+afterEach(() => {
+  for (const dir of dirs.splice(0)) {
+    fs.rmSync(dir, {recursive: true, force: true});
+  }
+});
+
+/** @returns {string} a temp dir holding a theme that exercises every field */
+function themeDir() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-receipt-doc-'));
+  dirs.push(dir);
+  fs.writeFileSync(
+    path.join(dir, 'ocean.mjs'),
+    `export default {
+  name: 'ocean',
+  tokens: {'--color-background-body': '#ffffff', '--font-family-body': '"Inter", sans-serif'},
+  components: {progressbar: {base: {color: 'red'}}},
+};
+`,
+  );
+  return dir;
+}
+
+/** @param {string} type */
+function returnsDescription(type) {
+  const entry = doc.returns?.find(r => r.type === type);
+  expect(entry, `themeBuild doc has no ${type} return`).toBeDefined();
+  return /** @type {{description: string}} */ (entry).description;
+}
+
+/** @param {string} description @param {string[]} fields */
+function undocumented(description, fields) {
+  return fields.filter(
+    field => !new RegExp(String.raw`\b${field}\b`).test(description),
+  );
+}
+
+describe('themeBuild() consumer docs name every receipt field', () => {
+  it('theme.build', async () => {
+    const dir = themeDir();
+    const result = await themeBuild('ocean.mjs', {}, {cwd: dir});
+
+    expect(result?.type).toBe('theme.build');
+    const data = /** @type {Record<string, any>} */ (result?.data);
+    // The theme is chosen so the optional arrays are non-empty.
+    expect(data.warnings.length).toBeGreaterThan(0);
+    expect(data.notices.length).toBeGreaterThan(0);
+
+    const fields = [
+      ...Object.keys(data),
+      ...Object.keys(data.outputs),
+      'variantsDts',
+    ];
+    expect(undocumented(returnsDescription('theme.build'), fields)).toEqual([]);
+  });
+
+  it('theme.build in the response-types doc', async () => {
+    const dir = themeDir();
+    const result = await themeBuild('ocean.mjs', {}, {cwd: dir});
+    const data = /** @type {Record<string, any>} */ (result?.data);
+    const member = responseTypes.members.find(m => m.value === 'theme.build');
+    expect(member, 'response-types has no theme.build member').toBeDefined();
+
+    const fields = [
+      ...Object.keys(data),
+      ...Object.keys(data.outputs),
+      'variantsDts',
+    ];
+    expect(
+      undocumented(/** @type {{description: string}} */ (member).description, fields),
+    ).toEqual([]);
+  });
+
+  it('theme.build.check', async () => {
+    const dir = themeDir();
+    const result = await themeBuild('ocean.mjs', {check: true}, {cwd: dir});
+
+    expect(result?.type).toBe('theme.build.check');
+    const data = /** @type {Record<string, any>} */ (result?.data);
+    const fields = [...Object.keys(data), ...Object.keys(data.stale[0])];
+    expect(
+      undocumented(returnsDescription('theme.build.check'), fields),
+    ).toEqual([]);
+  });
+});

package/api/theme/build/build.test.mjs

@@ -206,6 +206,133 @@ describe('themeBuild() — receipt', () => {
   });
 });
 
+describe('themeBuild() — dropped declarations reach the receipt', () => {
+  // Core's generator refuses a declaration whose value would end it early
+  // (an unquoted `;` or brace, an unclosed string/comment/url). The runtime
+  // says so on the console; a build has a receipt, so every drop must land in
+  // `warnings` — a programmatic caller otherwise sees `warnings: []` while the
+  // CSS silently omits a value the generated JS still carries.
+  it('reports every dropped declaration, from every generator path, in warnings', async () => {
+    const themeFile = path.join(tmpDir, 'dropped.mjs');
+    fs.writeFileSync(
+      themeFile,
+      `export default {
+        name: 'dropped',
+        tokens: {
+          '--color-bg': '#0a0a0a } body { background: url(https://example.com/token) ',
+        },
+        components: {
+          button: {
+            'variant:secondary': {
+              backgroundColor: 'red; background-image: url(https://example.com/component)',
+              ':hover': {color: '"https://example.com/pseudo'},
+            },
+          },
+        },
+        onDark: {
+          tokens: {'--color-bg': 'url(https://example.com/dark'},
+        },
+        adaptations: {
+          rules: [
+            {
+              when: {pointer: 'coarse'},
+              value: {tokens: {'--color-bg': 'red /* https://example.com/adaptation'}},
+            },
+          ],
+        },
+      };\n`,
+    );
+
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    let result;
+    try {
+      result = await themeBuild('dropped.mjs', {}, {cwd: tmpDir});
+      // Drops are collected, not printed: the programmatic API stays silent.
+      expect(warnSpy).not.toHaveBeenCalled();
+    } finally {
+      warnSpy.mockRestore();
+    }
+
+    const css = fs.readFileSync(path.join(tmpDir, 'dropped.css'), 'utf8');
+    expect(css).not.toContain('example.com');
+
+    const warnings = result?.data.warnings ?? [];
+    expect(warnings).toHaveLength(5);
+    expect(warnings).toEqual(
+      expect.arrayContaining([
+        expect.stringMatching(
+          /^Declaration dropped "--color-bg" in tokens: an unquoted "}" would close the rule/,
+        ),
+        expect.stringMatching(
+          /^Declaration dropped "background-color" in components\.button\["variant:secondary"\]: an unquoted ";" would end the declaration/,
+        ),
+        expect.stringMatching(
+          /^Declaration dropped "color" in components\.button\["variant:secondary"\]\[":hover"\]: an unclosed " string/,
+        ),
+        expect.stringMatching(
+          /^Declaration dropped "--color-bg" in onDark\.tokens: an unclosed url\(/,
+        ),
+        expect.stringMatching(
+          /^Declaration dropped "--color-bg" in adaptations\[0\]\.tokens: an unclosed \/\* comment/,
+        ),
+      ]),
+    );
+    for (const w of warnings) {
+      expect(w).toContain('The generated CSS omits it');
+    }
+  });
+
+  it('generates CSS for legacy null tokens without losing neighboring declarations', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'legacy.mjs'),
+      `export default {
+        name: 'legacy',
+        tokens: {'--color-background-body': null, '--spacing-4': 12},
+        onDark: {tokens: {'--color-background-body': null}},
+        components: {button: {base: {borderRadius: '4px'}}},
+      };\n`,
+    );
+
+    const result = await themeBuild('legacy.mjs', {}, {cwd: tmpDir});
+    const css = fs.readFileSync(path.join(tmpDir, 'legacy.css'), 'utf8');
+    expect(css).toContain('--color-background-body: null;');
+    expect(css).toContain('--spacing-4: 12;');
+    expect(css).toContain('border-radius: 4px;');
+    expect(result?.data.warnings).toEqual([]);
+  });
+
+  it('keeps valid CSS that carries semicolons, and reports nothing', async () => {
+    const themeFile = path.join(tmpDir, 'kept.mjs');
+    fs.writeFileSync(
+      themeFile,
+      `export default {
+        name: 'kept',
+        tokens: {'--font-family-body': 'Gill\\\\ Sans, "Segoe;UI", serif /* ; */'},
+        components: {
+          button: {
+            'variant:secondary': {
+              backgroundImage: 'URL(data:image/svg+xml;base64,PHN2Zz4=)',
+              WebkitLineClamp: '2',
+            },
+          },
+        },
+      };\n`,
+    );
+
+    const result = await themeBuild('kept.mjs', {}, {cwd: tmpDir});
+    const css = fs.readFileSync(path.join(tmpDir, 'kept.css'), 'utf8');
+
+    expect(css).toContain(
+      '--font-family-body: Gill\\ Sans, "Segoe;UI", serif /* ; */;',
+    );
+    expect(css).toContain(
+      'background-image: URL(data:image/svg+xml;base64,PHN2Zz4=);',
+    );
+    expect(css).toContain('-webkit-line-clamp: 2;');
+    expect(result?.data.warnings).toEqual([]);
+  });
+});
+
 describe('themeBuild() — nothing to build', () => {
   it('returns null and writes nothing when the generator yields no CSS', async () => {
     const themeFile = path.join(tmpDir, 'empty.mjs');