@astryxdesign/cli 0.4.2 → 0.4.3-canary.5939961

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @xds/cli
 
+# 0.4.3
+
+#### Fixes
+
+- The unloaded-font advisory is a notice, not a warning. A theme file cannot load a font — Astryx sets `--font-family-*` and loading is the app's job — so #5045's advisory fires on any theme naming a webfont, including a perfectly correct one. As a warning that made a clean build read as defective, and it put the shipped template permanently in violation of its own "compiles with no warnings" guard (#5079 had to allowlist the template's two font names in that assertion).
+  The `theme.build` receipt now separates the two: `warnings` are defects the author should fix, `notices` are advisories about a correct theme. The font advisory moves to `notices` and to stdout with the rest of the build's progress; stderr stays for defects. The template guard is back to `warnings` being empty, and no longer needs to know which fonts the template names.
+
+  Programmatic callers reading `data.warnings` for font advisories should read `data.notices`; the message text is unchanged.
+- `extends` now reaches the CSS. A theme that extended another built a stylesheet holding only the declarations it stated itself: the base's tokens, component overrides and surface rules were all absent, and because each theme is `@scope`d to its own `data-astryx-theme` value, loading the base's stylesheet alongside could not fill the gap either. Every consumer of an inheritance chain silently got stock geometry, elevation and type with a new palette painted over it (#5067). Nothing warned; the loss only showed up by diffing two generated stylesheets token by token.
+  The cause was `theme build` shadowing its own inputs. It writes `<name>.js` next to `<name>.ts`, and the loader resolved a plain `./<name>` specifier to that generated artifact before the source — so the second build of a family read the artifact, which carries no `components` and exports `<name>Theme` rather than whatever the source exports. A named import that missed became `extends: undefined`, and `defineTheme` treated an absent base as no base at all. The loader now resolves source extensions first, which is also the resolution the author's TypeScript sees, so the CSS a build emits matches the theme that type-checked.
+
+  Three things behind it are fixed too, so the failure cannot come back by another route. `defineTheme` **throws** when `extends` is present but is not a theme, naming the likely cause, instead of inheriting nothing — the one behavior change here, and it turns a silent stylesheet into a build error. A theme's `onDark`/`onLight` surfaces and its `__inputTokens` are now inherited like its tokens and components were, so a child no longer reverts its base's inverted-surface customizations to the defaults or loses its `[light, dark]` tuples. And a built theme module now carries the resolved `components` and surfaces alongside its tokens, so extending one — the `./built` subpath every shipped theme exposes — is no longer lossy. `theme build` also stopped hand-picking fields when it re-resolves a plain object theme file, which dropped `extends`, `color` and `syntax` on the way in.
+
+  An extended theme is flat: everything it inherits is resolved into its own output, and its stylesheet stands alone. Measured on a 14-theme family (one base, 13 palettes extending it): each palette went from 25 custom properties and no component rules to the base's full 175 and 70, with its own colours still winning.
+
+#### Contributors
+
+Thanks to everyone who contributed to this release:
+
+- @cixzhang
+
+---
+
 # 0.4.2
 
 #### New Features

package/api/theme/build/build.font-warning.test.mjs

@@ -1,13 +1,18 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * API-contract tests for the font-loading warning in `themeBuild()` (#5015):
+ * API-contract tests for the font-loading advisory in `themeBuild()` (#5015):
  * a theme that names font families it does not load gets one entry per family
- * in the `theme.build` receipt's `warnings` array, on BOTH load paths — a raw
+ * in the `theme.build` receipt's `notices` array, on BOTH load paths — a raw
  * typography config (resolved through core's defineTheme) and an
  * already-resolved theme that sets `--font-family-*` tokens directly. Themes
- * that only name generics or known system families warn about nothing, and
- * the warning never breaks the API's silence contract (default noopLogger).
+ * that only name generics or known system families say nothing, and the
+ * advisory never breaks the API's silence contract (default noopLogger).
+ *
+ * `notices`, not `warnings`: a theme file cannot load a font — that is the
+ * app's job by design — so this fires on correct themes and is context, not a
+ * defect to fix. Every assertion here also pins it OUT of `warnings`, since
+ * the whole point is that a good theme builds warning-free.
  *
  * Needs a built core — the `node` project's globalSetup
  * (vitest.global-setup.node.mjs) builds it once before workers fork.
@@ -45,15 +50,16 @@ describe('themeBuild() — font-loading warnings in the receipt', () => {
     const result = await themeBuild('fonty.mjs', {}, {cwd: tmpDir});
 
     expect(result?.type).toBe('theme.build');
-    const warnings = result?.data.warnings ?? [];
-    expect(warnings).toEqual(
+    const notices = result?.data.notices ?? [];
+    expect(notices).toEqual(
       expect.arrayContaining([
         expect.stringContaining('Font "Space Grotesk"'),
         expect.stringContaining('Font "JetBrains Mono"'),
       ]),
     );
-    // Heading inherits body's family; the shared family warns exactly once.
-    expect(warnings.filter(w => w.includes('Space Grotesk'))).toHaveLength(1);
+    // Heading inherits body's family; the shared family is named exactly once.
+    expect(notices.filter(w => w.includes('Space Grotesk'))).toHaveLength(1);
+    expect(result?.data.warnings).toEqual([]);
   });
 
   it('warns for an already-resolved theme: font-family tokens and component overrides, nothing else', async () => {
@@ -74,13 +80,14 @@ describe('themeBuild() — font-loading warnings in the receipt', () => {
     // Exactly the two named families — a non-family --font-* token must not
     // produce a bogus "Font \\"1rem\\"" entry, and the components half of the
     // feature must survive the real themeBuild path, not just the unit helper.
-    const fontWarnings = (result?.data.warnings ?? []).filter(w =>
+    const fontNotices = (result?.data.notices ?? []).filter(w =>
       w.startsWith('Font "'),
     );
-    expect(fontWarnings).toEqual([
+    expect(fontNotices).toEqual([
       expect.stringContaining('Font "Bungee"'),
       expect.stringContaining('Font "Orbitron"'),
     ]);
+    expect(result?.data.warnings).toEqual([]);
   });
 
   it('warns for a family named only inside a pseudo-class component override (defineTheme path)', async () => {
@@ -102,13 +109,14 @@ describe('themeBuild() — font-loading warnings in the receipt', () => {
 
     const result = await themeBuild('pseudo.mjs', {}, {cwd: tmpDir});
 
-    const fontWarnings = (result?.data.warnings ?? []).filter(w =>
+    const fontNotices = (result?.data.notices ?? []).filter(w =>
       w.startsWith('Font "'),
     );
     // Exactly the hidden family — Helvetica/Arial are system fonts.
-    expect(fontWarnings).toEqual([
+    expect(fontNotices).toEqual([
       expect.stringContaining('Font "Rubik Doodle"'),
     ]);
+    expect(result?.data.warnings).toEqual([]);
   });
 
   it('warns about nothing when every named family is a generic or known system font', async () => {
@@ -126,10 +134,11 @@ describe('themeBuild() — font-loading warnings in the receipt', () => {
     const result = await themeBuild('sys.mjs', {}, {cwd: tmpDir});
 
     expect(result?.type).toBe('theme.build');
+    expect(result?.data.notices).toEqual([]);
     expect(result?.data.warnings).toEqual([]);
   });
 
-  it('stays silent under the default noopLogger even when font warnings fire', async () => {
+  it('stays silent under the default noopLogger even when font notices fire', async () => {
     fs.writeFileSync(
       path.join(tmpDir, 'loud.mjs'),
       `export default { name: 'loud', tokens: { '--font-family-body': '"Orbitron", sans-serif' } };\n`,
@@ -144,7 +153,7 @@ describe('themeBuild() — font-loading warnings in the receipt', () => {
 
     try {
       const result = await themeBuild('loud.mjs', {}, {cwd: tmpDir});
-      expect(result?.data.warnings).toEqual(
+      expect(result?.data.notices).toEqual(
         expect.arrayContaining([expect.stringContaining('Font "Orbitron"')]),
       );
       expect(logSpy).not.toHaveBeenCalled();

package/api/theme/build/build.icons-specifier.test.mjs

@@ -0,0 +1,149 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Direct-API tests for `themeBuild`'s `iconsSpecifier` option (#4620).
+ *
+ * The CLI surface of `--icons-specifier` is pinned in
+ * clients/cli/commands/build-theme.icons-specifier.test.mjs; these tests pin
+ * the programmatic surface that watch mode, editor tooling, and build scripts
+ * call directly: the option reaches the emitted module, its absence leaves the
+ * scraped specifier byte-for-byte alone, and `check` mode compares the
+ * specifier-bearing text like any other generated byte — outputs built with a
+ * different specifier than the one being checked against are stale, not clean.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {themeBuild} from './build.mjs';
+
+let tmpDir;
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(
+    path.join(os.tmpdir(), 'astryx-api-icons-specifier-'),
+  );
+});
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/**
+ * Write a theme source (plus a loadable icons source beside it) under
+ * `<tmpDir>/src/`. The registry is a plain object — the emit path only
+ * re-exports it, so no React is needed.
+ */
+function writeIconTheme({withIcons = true, name = 'icotheme'} = {}) {
+  const srcDir = path.join(tmpDir, 'src');
+  fs.mkdirSync(srcDir, {recursive: true});
+  fs.writeFileSync(
+    path.join(srcDir, 'icons.ts'),
+    `export const myIcons = { close: 'x' };\n`,
+  );
+  const iconLines = withIcons ? [`import { myIcons } from './icons';`] : [];
+  fs.writeFileSync(
+    path.join(srcDir, `${name}.ts`),
+    [
+      ...iconLines,
+      `export default { name: '${name}', tokens: { '--color-bg': '#fff' }${
+        withIcons ? ', icons: myIcons' : ''
+      } };`,
+      '',
+    ].join('\n'),
+  );
+  return `src/${name}.ts`;
+}
+
+function builtModule(name = 'icotheme') {
+  return fs.readFileSync(path.join(tmpDir, 'dist', `${name}.js`), 'utf8');
+}
+
+describe('themeBuild({iconsSpecifier}) — direct API', () => {
+  it('emits the declared specifier into the generated module', async () => {
+    const file = writeIconTheme();
+
+    const result = await themeBuild(
+      file,
+      {out: 'dist/theme.css', iconsSpecifier: './icons.mjs'},
+      {cwd: tmpDir},
+    );
+
+    expect(result?.type).toBe('theme.build');
+    const js = builtModule();
+    expect(js).toContain(`import { myIcons } from "./icons.mjs";`);
+    // The registry re-export survives the override.
+    expect(js).toContain('export { myIcons }');
+  });
+
+  it('emits the scraped specifier unchanged when the option is omitted', async () => {
+    const file = writeIconTheme();
+
+    const result = await themeBuild(
+      file,
+      {out: 'dist/theme.css'},
+      {cwd: tmpDir},
+    );
+
+    expect(result?.type).toBe('theme.build');
+    expect(builtModule()).toContain(`import { myIcons } from './icons';`);
+  });
+
+  it('is inert for a theme with no icons field', async () => {
+    const file = writeIconTheme({withIcons: false});
+
+    const result = await themeBuild(
+      file,
+      {out: 'dist/theme.css', iconsSpecifier: './icons.mjs'},
+      {cwd: tmpDir},
+    );
+
+    expect(result?.type).toBe('theme.build');
+    // The header comment's usage example mentions imports; only a real
+    // statement (line-leading `import`) would be a leak.
+    const js = builtModule();
+    expect(js).not.toMatch(/^import /m);
+    expect(js).not.toContain('icons.mjs');
+  });
+
+  it('check mode is clean against outputs built with the same specifier', async () => {
+    const file = writeIconTheme();
+    await themeBuild(
+      file,
+      {out: 'dist/theme.css', iconsSpecifier: './icons.mjs'},
+      {cwd: tmpDir},
+    );
+
+    const result = await themeBuild(
+      file,
+      {out: 'dist/theme.css', check: true, iconsSpecifier: './icons.mjs'},
+      {cwd: tmpDir},
+    );
+
+    expect(result?.type).toBe('theme.build.check');
+    expect(result?.data.upToDate).toBe(true);
+    expect(result?.data.stale).toEqual([]);
+  });
+
+  it('check mode reports outputs stale when the specifier differs', async () => {
+    const file = writeIconTheme();
+    await themeBuild(
+      file,
+      {out: 'dist/theme.css', iconsSpecifier: './icons.mjs'},
+      {cwd: tmpDir},
+    );
+
+    // Checking without the option regenerates with the scraped './icons' —
+    // different bytes than the on-disk module, so the check must flag it.
+    const result = await themeBuild(
+      file,
+      {out: 'dist/theme.css', check: true},
+      {cwd: tmpDir},
+    );
+
+    expect(result?.type).toBe('theme.build.check');
+    expect(result?.data.upToDate).toBe(false);
+    expect(result?.data.stale.some(entry => entry.reason === 'outdated')).toBe(
+      true,
+    );
+  });
+});

package/api/theme/build/build.mjs

@@ -591,6 +591,30 @@ const themeScopeStart = (/** @type {string} */ name) =>
   `[data-astryx-theme="${name}"]`;
 const THEME_SCOPE_TO = `[data-astryx-theme]`;
 
+/**
+ * Module extensions the theme loader resolves, source before artifact.
+ *
+ * `theme build` writes `<name>.js` next to `<name>.ts`, and jiti's default
+ * order tries `.js` first — so once a base theme had been built, every sibling
+ * theme that `extends` it resolved to that generated artifact instead of the
+ * source. The artifact carries no `components` and exports a different name,
+ * so the inheritance silently evaporated. Resolving source first is also what
+ * the author's TypeScript sees, which is the point: the CSS the build emits
+ * matches the theme they type-checked.
+ */
+const THEME_MODULE_EXTENSIONS = [
+  '.ts',
+  '.tsx',
+  '.mts',
+  '.cts',
+  '.mtsx',
+  '.ctsx',
+  '.mjs',
+  '.cjs',
+  '.js',
+  '.json',
+];
+
 /**
  * Import a theme module using jiti and find the defineTheme() result.
  * Returns the resolved DefinedTheme object.
@@ -601,6 +625,7 @@ async function importThemeModule(filePath) {
   const jiti = createJiti(import.meta.url, {
     moduleCache: false,
     jsx: true,
+    extensions: THEME_MODULE_EXTENSIONS,
   });
 
   const mod = await jiti.import(filePath, {default: true});
@@ -733,6 +758,13 @@ function extractIconInfo(filePath) {
  * Includes the theme name, marker, and re-exports the icon registry.
  * All styling is in the CSS file.
  *
+ * The module carries the theme's resolved `components` and on-media surfaces
+ * alongside its tokens. They are not needed to apply the theme — the CSS holds
+ * all of that — but a built theme is a legitimate base for `extends` (the
+ * shipped themes expose one as their `./built` subpath), and a base that
+ * carries only tokens makes its children silently lose every component
+ * override it had.
+ *
  * The icon registry is imported rather than inlined because it holds React
  * elements, which cannot be serialized. `extractIconInfo` lifts the specifier
  * out of the TypeScript source, where an extensionless `./icons` is resolved by
@@ -774,6 +806,27 @@ function generateBuiltModule(themeDef, iconInfo, iconsSpecifier) {
     .map((line, i) => (i === 0 ? line : '  ' + line))
     .join('\n');
 
+  /**
+   * Serialize a resolved theme field as an indented object literal, or '' when
+   * there is nothing to emit.
+   * @param {string} field
+   * @param {unknown} value
+   * @returns {string}
+   */
+  const serializeField = (field, value) => {
+    if (!value || Object.keys(value).length === 0) return '';
+    const body = JSON.stringify(value, null, 2)
+      .split('\n')
+      .map((line, i) => (i === 0 ? line : '  ' + line))
+      .join('\n');
+    return `  ${field}: ${body},\n`;
+  };
+
+  const inheritableFields =
+    serializeField('components', themeDef.components) +
+    serializeField('__onDark', themeDef.__onDark) +
+    serializeField('__onLight', themeDef.__onLight);
+
   return `${iconImport}/**
  * ${themeDef.name} theme — built by \`${getCliInvocation()} theme build\`
  * Import the CSS file alongside this module:
@@ -785,7 +838,7 @@ export const ${toIdentifier(themeDef.name)}Theme = {
   name: '${themeDef.name}',
   __built: true,
   tokens: ${tokensStr},
-${iconsField}
+${inheritableFields}${iconsField}
 };
 ${iconReExport}`;
 }
@@ -1061,6 +1114,8 @@ export async function themeBuild(
   // Validate component overrides
   const warnings = await validateComponentOverrides(themeDef);
   const warningMessages = [];
+  /** Advisories about a correct theme — see the `notices` note on the receipt. */
+  const noticeMessages = [];
   for (const w of warnings) {
     warningMessages.push(w);
     logger.warn(`  ⚠ ${w}`);
@@ -1099,20 +1154,29 @@ export async function themeBuild(
   let css;
   let resolvedTheme;
   {
-    // jiti returns an already-resolved theme; legacy eval returns raw input.
-    const isAlreadyResolved =
-      !themeDef.typography && !themeDef.motion && !themeDef.radius;
-    if (isAlreadyResolved) {
-      resolvedTheme = themeDef;
+    // jiti returns an already-resolved theme; a plain object literal (or the
+    // legacy eval path) returns raw defineTheme input, which still has to go
+    // through the resolver. Detect that by the input-only fields — a resolved
+    // theme has none of them — and hand the WHOLE object over: picking fields
+    // by name is how `extends` (and `color`, and `syntax`) used to be dropped
+    // on the way in.
+    const INPUT_ONLY_FIELDS = [
+      'extends',
+      'typography',
+      'motion',
+      'radius',
+      'color',
+      'syntax',
+      'onDark',
+      'onLight',
+    ];
+    const needsResolution = INPUT_ONLY_FIELDS.some(
+      field => themeDef[field] !== undefined,
+    );
+    if (needsResolution) {
+      resolvedTheme = _defineTheme({...themeDef});
     } else {
-      resolvedTheme = _defineTheme({
-        name: themeDef.name,
-        typography: themeDef.typography,
-        motion: themeDef.motion,
-        radius: themeDef.radius,
-        tokens: themeDef.tokens,
-        components: themeDef.components,
-      });
+      resolvedTheme = themeDef;
     }
     const scopeSelector = themeScopeStart(themeDef.name);
     const scopeTo = THEME_SCOPE_TO;
@@ -1350,11 +1414,18 @@ Or with a <link> tag:
   // Fonts the theme names but nothing loads (#5015). Resolved tokens and
   // component overrides carry the final font-family values on both load
   // paths, so this sees jiti-resolved and legacy themes alike.
+  //
+  // A NOTICE, not a warning: naming a font a theme file cannot load is how
+  // the API is meant to be used — Astryx sets `--font-family-*` and loading
+  // is the app's job, which no theme can do for it. So this fires on any
+  // theme with a webfont, including a perfect one, and as a warning it made
+  // every such build read as defective (it also put the shipped template
+  // permanently in violation of its own "compiles with no warnings" guard).
   const unloadedFonts = collectUnloadedFonts(resolvedTheme);
   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)`;
-    warningMessages.push(msg);
-    logger.warn(`  ⚠ ${msg}`);
+    noticeMessages.push(msg);
+    logger.log(`  note: ${msg}`);
   }
   if (unloadedFonts.length > 0) {
     logger.log(formatFontLoadingHelp(themeDef.name, unloadedFonts));
@@ -1376,6 +1447,7 @@ Or with a <link> tag:
           : {}),
       },
       warnings: warningMessages,
+      notices: noticeMessages,
     },
   };
 }

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

@@ -299,11 +299,10 @@ describe('themeBuild() — component override validation', () => {
 describe('themeBuild() — the shipped theme template', () => {
   // `assets/theme.template.ts` is what `astryx theme template` puts in a
   // consumer's project. It is the one theme file we hand out, so it has to
-  // compile as shipped — and cleanly apart from the font warnings it earns on
-  // purpose: a template that greets its first reader with warnings teaches them
-  // to ignore warnings. The claims its comments make are checked separately by
-  // scripts/check-theme-template.test.mjs.
-  it('compiles as shipped, warning only about the fonts it deliberately names', async () => {
+  // compile as shipped — and cleanly: a template that greets its first reader
+  // with warnings teaches them to ignore warnings. The claims its comments make
+  // are checked separately by scripts/check-theme-template.test.mjs.
+  it('compiles as shipped, with no warnings', async () => {
     const src = path.resolve(
       import.meta.dirname,
       '../../../assets/theme.template.ts',
@@ -312,17 +311,189 @@ describe('themeBuild() — the shipped theme template', () => {
 
     const result = await themeBuild('theme.template.ts', {}, {cwd: tmpDir});
 
-    // The template names Inter and Geist Mono to teach "SHIP THE FONTS YOU
-    // NAME", and loads neither — so the unloaded-font warning firing here is
-    // the lesson landing, not a defect. Any OTHER warning still fails.
-    const unexpected = (result?.data.warnings ?? []).filter(
-      w => !/^Font "(Inter|Geist Mono)" is named by this theme but not loaded/.test(w),
-    );
-    expect(unexpected).toEqual([]);
-    expect(result?.data.warnings).toHaveLength(2);
+    expect(result?.data.warnings).toEqual([]);
+    // It DOES name Inter and Geist Mono without loading them, to teach "SHIP
+    // THE FONTS YOU NAME" — advisories about a correct file, which is why they
+    // are notices. Asserted here so moving them out of `warnings` cannot
+    // quietly become dropping them.
+    expect(result?.data.notices).toHaveLength(2);
     expect(fs.existsSync(path.join(tmpDir, 'my-theme.css'))).toBe(true);
     // The template teaches custom variants; the augmentation it promises the
     // reader has to actually be generated.
-    expect(fs.existsSync(path.join(tmpDir, 'my-theme.variants.d.ts'))).toBe(true);
+    expect(fs.existsSync(path.join(tmpDir, 'my-theme.variants.d.ts'))).toBe(
+      true,
+    );
+  });
+});
+
+describe('themeBuild() — extends', () => {
+  // These fixtures `import {defineTheme} from '@astryxdesign/core/theme'` the
+  // way a real theme file does, so they have to sit somewhere that specifier
+  // resolves — an OS temp dir has no node_modules above it.
+  let extDir;
+  beforeEach(() => {
+    extDir = fs.mkdtempSync(
+      path.join(path.resolve(import.meta.dirname, '../../..'), '.tmp-extends-'),
+    );
+  });
+  afterEach(() => {
+    fs.rmSync(extDir, {recursive: true, force: true});
+  });
+
+  /**
+   * Every `prop: value` a generated stylesheet actually applies. Header
+   * comments and scope wrappers are ignored — two themes never share those.
+   */
+  function declarations(css) {
+    return new Set(
+      css
+        .split('\n')
+        .map(l => l.trim())
+        .filter(l => /^[-a-z][^{}]*:.+;$/.test(l)),
+    );
+  }
+  /** Every component rule a stylesheet opens, e.g. `.astryx-switch {`. */
+  function selectors(css) {
+    return new Set(
+      css
+        .split('\n')
+        .map(l => l.trim())
+        .filter(l => l.endsWith('{') && l.startsWith('.')),
+    );
+  }
+
+  /** A base theme with geometry, elevation and a component override. */
+  const BASE_SOURCE = `export const brandTheme = {
+    name: 'ext-base',
+    tokens: {
+      '--radius-element': '6px',
+      '--shadow-low': '0 1px 3px rgb(0 0 0 / 0.1)',
+      '--color-border-emphasized': '#D4D4D4',
+    },
+    components: {
+      switch: {base: {backgroundColor: 'var(--color-border-emphasized)'}},
+    },
+  };\n`;
+
+  /**
+   * The child names its base with a plain relative specifier, exactly as a
+   * generated palette does. `theme build` writes `ext-base.js` next to
+   * `ext-base.mjs`, so `./ext-base` is ambiguous — and the artifact, which
+   * exports `extBaseTheme` rather than `brandTheme`, is the wrong answer.
+   */
+  const CHILD_SOURCE = `import {defineTheme} from '@astryxdesign/core/theme';
+  import {brandTheme} from './ext-base';
+  export const paletteTheme = defineTheme({
+    name: 'ext-child',
+    extends: brandTheme,
+    tokens: {'--color-accent': 'hsl(220 88% 72%)'},
+  });\n`;
+
+  it('emits every declaration its base emits (the child stylesheet is self-contained)', async () => {
+    fs.writeFileSync(path.join(extDir, 'ext-base.mjs'), BASE_SOURCE);
+    fs.writeFileSync(path.join(extDir, 'ext-child.mjs'), CHILD_SOURCE);
+
+    // Build the base FIRST, as any real project does — that write is what
+    // used to poison the child's build.
+    await themeBuild('ext-base.mjs', {}, {cwd: extDir});
+    await themeBuild('ext-child.mjs', {}, {cwd: extDir});
+
+    const baseCss = fs.readFileSync(path.join(extDir, 'ext-base.css'), 'utf8');
+    const childCss = fs.readFileSync(
+      path.join(extDir, 'ext-child.css'),
+      'utf8',
+    );
+
+    const childDecls = declarations(childCss);
+    expect([...declarations(baseCss)].filter(d => !childDecls.has(d))).toEqual(
+      [],
+    );
+
+    const childSelectors = selectors(childCss);
+    expect([...selectors(baseCss)].filter(s => !childSelectors.has(s))).toEqual(
+      [],
+    );
+
+    // …and the child's own override still wins.
+    expect(childCss).toContain('--color-accent: hsl(220 88% 72%);');
+  });
+
+  it('resolves the base from its source, not from the generated sibling artifact', async () => {
+    fs.writeFileSync(path.join(extDir, 'ext-base.mjs'), BASE_SOURCE);
+    fs.writeFileSync(path.join(extDir, 'ext-child.mjs'), CHILD_SOURCE);
+
+    await themeBuild('ext-base.mjs', {}, {cwd: extDir});
+    const result = await themeBuild('ext-child.mjs', {}, {cwd: extDir});
+
+    expect(result?.data.componentCount).toBe(1);
+    expect(result?.data.tokenCount).toBe(4);
+  });
+
+  it('inherits component overrides when the base IS a built theme module', async () => {
+    fs.writeFileSync(path.join(extDir, 'ext-base.mjs'), BASE_SOURCE);
+    await themeBuild('ext-base.mjs', {}, {cwd: extDir});
+
+    // Extending a package's pre-built theme module (e.g. the `./built`
+    // subpath the shipped themes expose) must not silently drop its
+    // component overrides.
+    fs.writeFileSync(
+      path.join(extDir, 'ext-built-child.mjs'),
+      `import {defineTheme} from '@astryxdesign/core/theme';
+      import {extBaseTheme} from './ext-base.js';
+      export const builtChildTheme = defineTheme({
+        name: 'ext-built-child',
+        extends: extBaseTheme,
+      });\n`,
+    );
+
+    await themeBuild('ext-built-child.mjs', {}, {cwd: extDir});
+    const css = fs.readFileSync(
+      path.join(extDir, 'ext-built-child.css'),
+      'utf8',
+    );
+
+    expect(css).toContain('.astryx-switch {');
+    expect(css).toContain('--radius-element: 6px;');
+  });
+
+  it('resolves extends on a plain object theme file (no defineTheme call)', async () => {
+    fs.writeFileSync(path.join(extDir, 'ext-base.mjs'), BASE_SOURCE);
+    fs.writeFileSync(
+      path.join(extDir, 'ext-plain.mjs'),
+      `import {brandTheme} from './ext-base.mjs';
+      export default {
+        name: 'ext-plain',
+        extends: brandTheme,
+        tokens: {'--color-accent': '#ff0000'},
+      };\n`,
+    );
+
+    await themeBuild('ext-base.mjs', {}, {cwd: extDir});
+    await themeBuild('ext-plain.mjs', {}, {cwd: extDir});
+
+    const css = fs.readFileSync(path.join(extDir, 'ext-plain.css'), 'utf8');
+    expect(css).toContain('--radius-element: 6px;');
+    expect(css).toContain('.astryx-switch {');
+  });
+
+  it('fails loudly when the base import resolved to nothing', async () => {
+    fs.writeFileSync(
+      path.join(extDir, 'ext-broken.mjs'),
+      `import {defineTheme} from '@astryxdesign/core/theme';
+      import {notAThing} from './ext-missing.mjs';
+      export const brokenTheme = defineTheme({
+        name: 'ext-broken',
+        extends: notAThing,
+        tokens: {'--color-accent': '#ff0000'},
+      });\n`,
+    );
+    fs.writeFileSync(
+      path.join(extDir, 'ext-missing.mjs'),
+      `export const somethingElse = 1;\n`,
+    );
+
+    await expect(
+      themeBuild('ext-broken.mjs', {}, {cwd: extDir}),
+    ).rejects.toThrow(/extends/);
   });
 });