Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
167 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file theme build API — compile standalone themes or one selected family.
 * @input JS/TS theme modules, build/check options, and the installed Core.
 * @output Generated artifacts preserving imported and inherited icon registries.
 * @position CLI theme compiler; standalone icon provenance is icon-imports.mjs.
 *
 * `themeBuild` and `themeBuildFamily` share the same loader, compiler,
 * serializers, check, and writer. They read defineTheme() sources and, via
 * @astryxdesign/core's shared generator (the SINGLE source of truth so the
 * build emits the exact CSS the `<Theme>` runtime does), writes:
 * - A CSS file with token overrides and component styles
 * - A CSS declaration module for strict side-effect imports
 * - A JS module that re-exports the built theme (+ icon registry); function
 *   icon entries stay functions for `Icon`, beside a node view of the registry
 * - A .d.ts (plus an optional .variants.d.ts for custom prop values and the
 *   theme's icon variant names)
 *
 * It performs the writes and returns a `theme.build` receipt — its `warnings`
 * carry override problems and every declaration core's generator dropped
 * because its value could not stay one CSS declaration; `notices` carry fonts
 * the theme names but does not load (font-warning.mjs) — or `null` when the
 * theme produced no CSS (nothing to build). Standalone icon imports come from
 * the selected theme's parsed bindings and inheritance, never from comment or
 * string contents. A registry that cannot be preserved fails before output
 * generation, including in check mode. Errors throw AstryxError (with a stable
 * code). Private-variable diagnostics keep their released warnings and generated
 * files; an internal callback lets the CLI make only the process status fail.
 * Human progress is emitted through the shared `logger` (silent by default), so
 * the CLI keeps its exact output while a programmatic caller stays quiet.
 * Every output a build writes, explicit or beside the theme file, stays inside
 * `cwd` (`ERR_PATH_TRAVERSAL` otherwise). Check mode writes nothing, so it
 * compares outputs outside `cwd` read-only; only a relative `out` path that
 * escapes `cwd` is refused there too.
 *
 * The installed `@astryxdesign/core` is an independently versioned optional
 * peer, so it can be older than the CLI. A theme that uses only baseline
 * features builds against such a core unchanged; a theme that needs ordered
 * adaptations (which need core's `generateAdaptationCSS`) fails early with
 * ERR_CORE_INCOMPATIBLE rather than emitting CSS with those rules quietly
 * missing. That check is scoped to the adaptation capability — it is not a
 * general compatibility scheme for every export an arbitrary older core might
 * lack.
 *
 * Core is imported on first use, never when this module loads: the CLI loads
 * this module for every command, and Core's root entry pulls in all of Core
 * and React.
 *
 * With `{check: true}`, it compiles the same outputs in memory but writes
 * nothing: it compares each generated file against what is on disk (ignoring
 * only the volatile `@generated` `Command:` line) and returns a
 * `theme.build.check` receipt listing any stale or missing outputs. This is
 * the CI guard for committed, generated theme CSS: the source of truth is
 * `<theme>.ts`, and `theme build --check` fails when the committed
 * `<theme>.css`/`.js`/`.d.ts` no longer match it. Builds also write a
 * `<theme>.css.d.ts` import stub; check mode tolerates that one file being absent
 * so output sets from the released CLI stay valid after an upgrade.
 */

import * as fs from 'node:fs';
import * as path from 'node:path';
import {createRequire, isBuiltin} from 'node:module';
import {fileURLToPath, pathToFileURL} from 'node:url';
import {parse} from '@babel/parser';
import {createJiti} from 'jiti';
import {
  formatCliCommand,
  getCliInvocation,
} from '../../../foundation/env/package-manager.mjs';
import {
  CLI_ROOT,
  findCoreDir,
  findInstalledPackage,
  findProjectCoreDir,
} from '../../../foundation/fs/paths.mjs';
import {isGlobalCopy} from '../../../foundation/release/choose.mjs';
import {isInReleaseCache} from '../../../foundation/release/cache.mjs';
import {fetchCarriedThemeCoreDir} from '../_adapter.mjs';
import {
  assertWithin,
  sanitizeName,
  PathSafetyError,
} from '../../../foundation/fs/path-safety.mjs';
import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
import {validatePrivateVars} from '../../../foundation/config/theme-private-vars.mjs';
import {AstryxError} from '../../error.mjs';
import {applyWrites} from '../../integration/add-helpers.mjs';
import {logger} from '../../logger.mjs';
import {loadComponentDoc} from '../../../foundation/discovery/component-loader.mjs';
import {
  collectThemingTargets,
  targetsByKey,
} from '../../../foundation/discovery/theming-targets.mjs';
import {
  collectUnloadedFonts,
  formatBatchFontLoadingHelp,
  formatFontLoadingHelp,
} from './font-warning.mjs';
import {interceptCore} from './core-interception.mjs';
import {generateFamilyCSS, resolveThemeFamily} from './family.mjs';
import {resolveIconImports} from './icon-imports.mjs';

// Import shared theme processing from core. `astryx theme build` MUST produce the
// exact same CSS as the `<Theme>` runtime, so it has exactly one generation
// path: core's generator. There is no in-CLI fallback implementation — if this
// import fails, the build fails (see the ERR_CORE_NOT_FOUND guard in the theme
// action). A built, resolvable `@astryxdesign/core` is a hard requirement.
// A built, resolvable `@astryxdesign/core` is a hard requirement. These are
// populated from a dynamic import (a runtime boundary), so `any` is intentional.
// That import runs the first time a build needs Core (see `loadCliCore`), not
// when this module loads.
//
// The CLI and core are independently versioned optional peers, so this import
// can succeed against a core OLDER than the CLI. Only the exports every theme
// build needs are REQUIRED (`defineTheme`, `generateThemeRulesSplit`).
// `generateAdaptationCSS` (ordered environmental adaptations) is treated as a
// capability instead, required only by a theme that actually uses it:
// requiring it unconditionally made every theme build — adaptations or not —
// fail against an older published core. This is a targeted allowance for that
// one capability, not a general scheme; `generateOnMediaCSS` exists in every
// core that ships adaptations' predecessor surface.
/** @type {any} */ let _defineTheme = null;
/** @type {any} */ let _generateThemeRulesSplit = null;
/** @type {any} */ let _generateOnMediaCSS = null;
/** @type {any} */ let _generateAdaptationCSS = null;
/**
 * The whole `@astryxdesign/core/theme` namespace. A theme file handed a
 * wrapped core must still get every export the installed one has, including
 * ones this file never names — so interception spreads this rather than
 * rebuilding a core from the handful of functions below.
 */
/** @type {any} */ let _coreThemeModule = null;
/**
 * The `@astryxdesign/core` ROOT namespace, loaded separately because it
 * exports far more than the theme subpath. Interception must hand a theme file
 * that imports a component from the root the root's own exports, not the theme
 * namespace wearing its name. It loads on first use: see lazyRootModule.
 * @type {(() => any) | null}
 */
let _coreRootModule = null;
/** @type {any} */ let _coreImportError = null;

/**
 * The bindings one Core provides: the namespaces interception spreads, the
 * functions the build calls, and why the import failed, if it did.
 * @typedef {{
 *   themeModule: any,
 *   rootModule: (() => any) | null,
 *   importError: any,
 *   defineTheme: any,
 *   generateThemeRulesSplit: any,
 *   generateOnMediaCSS: any,
 *   generateAdaptationCSS: any,
 * }} CoreBindings
 */

/**
 * A Core's root namespace, loaded on first use. The root entry loads all of
 * Core and React, and only a theme that imports the root specifier needs it.
 * Requiring the file an import resolves to returns the namespace `import()`
 * gives. A root that cannot be loaded gives null, and interception then hands
 * the theme namespace in its place. A root that only `import()` can load
 * throws instead: one that awaits at its top level, or any root when Node runs
 * without require(esm).
 * @param {() => string | null} resolveFile
 * @returns {() => any}
 */
export function lazyRootModule(resolveFile) {
  /** @type {{namespace: any} | null} */
  let loaded = null;
  return () => {
    if (loaded) return loaded.namespace;
    let namespace = null;
    let file = null;
    try {
      file = resolveFile();
    } catch {
      // A Core whose root entry does not resolve falls back below.
    }
    try {
      if (file) namespace = createRequire(import.meta.url)(file);
    } catch (error) {
      const code = /** @type {any} */ (error)?.code;
      // The theme namespace would stand in for the root's own exports here.
      if (code === 'ERR_REQUIRE_ASYNC_MODULE' || code === 'ERR_REQUIRE_ESM') {
        throw new Error(
          `The @astryxdesign/core root entry at ${file} cannot be loaded with require() (${code}), so a theme that imports it cannot be built.`,
          {cause: error},
        );
      }
      // A Core without a usable root entry still builds themes.
    }
    loaded = {namespace};
    return namespace;
  };
}

/**
 * Import the CLI's own Core: the `@astryxdesign/core` this module resolves.
 * Never throws. A failed import is kept as `importError`, so the build can
 * surface a precise, actionable error when it runs.
 * @returns {Promise<CoreBindings>}
 */
async function importCliCore() {
  /** @type {CoreBindings} */
  const core = {
    themeModule: null,
    rootModule: null,
    importError: null,
    defineTheme: null,
    generateThemeRulesSplit: null,
    generateOnMediaCSS: null,
    generateAdaptationCSS: null,
  };
  try {
    const coreTheme = await import('@astryxdesign/core/theme');
    core.themeModule = coreTheme;
    core.defineTheme = coreTheme.defineTheme;
    core.generateThemeRulesSplit = coreTheme.generateThemeRulesSplit;
    core.generateOnMediaCSS = coreTheme.generateOnMediaCSS;
    core.generateAdaptationCSS = coreTheme.generateAdaptationCSS;
    core.rootModule = lazyRootModule(() =>
      fileURLToPath(import.meta.resolve('@astryxdesign/core')),
    );
  } catch (e) {
    // Capture the reason so the theme action can surface a precise, actionable
    // error. The hard failure happens when `theme build` runs.
    core.importError = e;
  }
  return core;
}

/**
 * The CLI's own Core, imported once, the first time a build needs it. The CLI
 * loads this module for every command, and Core's root entry loads all of Core
 * and React, so an import at module load would make every command
 * (`--version` included) pay for that whenever a Core resolves.
 * @type {Promise<CoreBindings> | null}
 */
let _cliCorePromise = null;

/**
 * The CLI's own Core, kept so each build can choose between it and the
 * project's installed Core. The first call also points the build at it, so a
 * step that runs before any build has chosen a Core reads the CLI's own.
 * @returns {Promise<CoreBindings>}
 */
function loadCliCore() {
  _cliCorePromise ??= importCliCore().then(core => {
    setCore(core);
    return core;
  });
  return _cliCorePromise;
}

/**
 * Point the build at one Core: the module-level bindings every step reads.
 * @param {CoreBindings} core
 */
function setCore(core) {
  _coreThemeModule = core.themeModule;
  _coreRootModule = core.rootModule;
  _coreImportError = core.importError;
  _defineTheme = core.defineTheme;
  _generateThemeRulesSplit = core.generateThemeRulesSplit;
  _generateOnMediaCSS = core.generateOnMediaCSS;
  _generateAdaptationCSS = core.generateAdaptationCSS;
}

/**
 * The file an `import` of `subpath` reaches through a package's `exports` map,
 * or null when the map has no entry for it. Conditions are taken in the map's
 * own order, as Node does, accepting the ones an import matches here: `node`,
 * `import`, and `default` (so `source` and `types` are skipped).
 *
 * @param {string} dir - The package directory.
 * @param {string} subpath - `'.'` or a subpath such as `'./theme'`.
 * @returns {string|null}
 */
function importTarget(dir, subpath) {
  let pkg;
  try {
    pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf-8'));
  } catch {
    return null;
  }
  const map = pkg?.exports;
  const bySubpath =
    map &&
    typeof map === 'object' &&
    !Array.isArray(map) &&
    Object.keys(map).some(key => key.startsWith('.'));
  const entry = bySubpath ? map[subpath] : subpath === '.' ? map : undefined;
  /** @param {any} value @returns {string|null} */
  const pick = value => {
    if (typeof value === 'string') return value;
    if (!value || typeof value !== 'object' || Array.isArray(value))
      return null;
    for (const [condition, target] of Object.entries(value)) {
      if (
        condition !== 'node' &&
        condition !== 'import' &&
        condition !== 'default'
      )
        continue;
      const picked = pick(target);
      if (picked) return picked;
    }
    return null;
  };
  const target = pick(entry);
  return target ? path.resolve(dir, target) : null;
}

/** @param {string} file @returns {string} its real path, or itself */
function realOrSelf(file) {
  try {
    return fs.realpathSync(file);
  } catch {
    return file;
  }
}

/**
 * `target` spelled through real directories: the deepest ancestor that exists
 * is resolved through its symlinks, and the missing rest is appended as given.
 * @param {string} target absolute path
 * @returns {string}
 */
function realLocation(target) {
  /** @type {string[]} */
  const missing = [];
  let existing = target;
  while (!fs.existsSync(existing)) {
    const parent = path.dirname(existing);
    if (parent === existing) break;
    missing.unshift(path.basename(existing));
    existing = parent;
  }
  return path.join(realOrSelf(existing), ...missing);
}

/**
 * The Core the project at `cwd` installed, when it differs from the one the
 * CLI's own import found and loads. The app's `<Theme>` runs on the app's
 * Core, so building with it keeps the CSS identical; and a CLI run one-off
 * (`npx @astryxdesign/cli`) has no Core beside it at all. Null when there is
 * nothing better than the CLI's own import: no installed Core (the Astryx
 * repository, a bare directory) or the same Core. A Core that is there but
 * does not load, or lacks the functions the build calls, throws, naming it:
 * building with another Core would not match the app's `<Theme>`.
 *
 * @param {string} cwd
 * @param {CoreBindings} cliCore - The CLI's own Core, from {@link loadCliCore}.
 * @param {{projectOnly?: boolean}} [options] `projectOnly`: never the
 *   carried Core, as for doctor (spec AST-081 FR3)
 * @returns {Promise<CoreBindings | null>}
 */
async function loadProjectCore(cwd, cliCore, {projectOnly = false} = {}) {
  // Outside a project, the Core the answering copy carries (spec AST-081 FR3).
  const installed = findInstalledPackage(cwd, '@astryxdesign/core');
  const dir = installed ?? (projectOnly ? null : fetchCarriedThemeCoreDir(cwd));
  const themeFile = dir ? importTarget(dir, './theme') : null;
  if (!dir || !themeFile) return null;
  if (cliCore.themeModule) {
    const own = cliCoreThemeFile();
    if (own != null && realOrSelf(own) === realOrSelf(themeFile)) return null;
  }
  let themeModule;
  try {
    themeModule = await import(pathToFileURL(themeFile).href);
  } catch (error) {
    throw new AstryxError(
      installed == null
        ? carriedCoreMessage(dir, /** @type {Error} */ (error))
        : coreUnavailableMessage(cwd, /** @type {Error} */ (error)),
      undefined,
      ERROR_CODES.ERR_CORE_NOT_FOUND,
    );
  }
  const missing = ['defineTheme', 'generateThemeRulesSplit'].filter(
    name => typeof themeModule[name] !== 'function',
  );
  if (missing.length > 0) {
    throw new AstryxError(
      `The @astryxdesign/core at ${path.relative(cwd, dir) || '.'} does not export ${missing.join(' or ')} from its \`./theme\` entry, which \`${formatCliCommand('theme build')}\` calls. Update it.`,
      undefined,
      ERROR_CODES.ERR_CORE_INCOMPATIBLE,
    );
  }
  const rootFile = importTarget(dir, '.');
  return {
    themeModule,
    rootModule: lazyRootModule(() => rootFile),
    importError: null,
    defineTheme: themeModule.defineTheme,
    generateThemeRulesSplit: themeModule.generateThemeRulesSplit,
    generateOnMediaCSS: themeModule.generateOnMediaCSS,
    generateAdaptationCSS: themeModule.generateAdaptationCSS,
  };
}

/**
 * The file the CLI's own `@astryxdesign/core/theme` resolves to, or null when
 * the CLI has no Core of its own (a one-off `npx` run).
 * @returns {string | null}
 */
function cliCoreThemeFile() {
  try {
    return fileURLToPath(import.meta.resolve('@astryxdesign/core/theme'));
  } catch (error) {
    const {code} = /** @type {NodeJS.ErrnoException} */ (error);
    if (
      code === 'ERR_MODULE_NOT_FOUND' ||
      code === 'ERR_PACKAGE_PATH_NOT_EXPORTED'
    ) {
      return null;
    }
    throw error;
  }
}

/**
 * The error for a Core the answering copy carries (outside a project) that
 * does not load.
 * @param {string} dir
 * @param {Error} importError
 * @returns {string}
 */
function carriedCoreMessage(dir, importError) {
  return (
    `Could not load the @astryxdesign/core this CLI release carries, at ${dir}.` +
    `\n  Import error: ${importError.message}`
  );
}

/** @type {Map<string, Awaited<ReturnType<typeof loadProjectCore>>>} */
const _projectCores = new Map();

/**
 * Choose the Core this build generates with: the project's installed one when
 * {@link loadProjectCore} finds it, else the CLI's own. With `projectOnly`,
 * only the project's installed Core: a build that cannot use it fails rather
 * than read the Core the answering copy carries (spec AST-081 FR3).
 * @param {string} cwd
 * @param {{projectOnly?: boolean}} [options]
 */
async function selectCore(cwd, {projectOnly = false} = {}) {
  const cliCore = await loadCliCore();
  const key = `${projectOnly ? 'project' : 'any'}\0${cwd}`;
  if (!_projectCores.has(key))
    _projectCores.set(key, await loadProjectCore(cwd, cliCore, {projectOnly}));
  const projectCore = _projectCores.get(key);
  // A global or cached copy's own Core is the carried one.
  if (projectOnly && !projectCore && carriesCore() && !cliCoreIsProjects(cwd)) {
    throw new AstryxError(
      "The project's Core isn't installed.",
      undefined,
      ERROR_CODES.ERR_CORE_NOT_FOUND,
    );
  }
  setCore(projectCore ?? cliCore);
}

/**
 * Whether this CLI copy is one installed for the computer or kept in the
 * per-user release cache, whose own Core import is the carried Core.
 * @returns {boolean}
 */
function carriesCore() {
  return isGlobalCopy(CLI_ROOT) || isInReleaseCache(CLI_ROOT);
}

/**
 * Whether the Core the CLI's own import loads is the one the project at
 * `cwd` installed.
 * @param {string} cwd
 * @returns {boolean}
 */
function cliCoreIsProjects(cwd) {
  const dir = findProjectCoreDir(cwd);
  if (!dir) return false;
  const own = cliCoreThemeFile();
  const theirs = importTarget(dir, './theme');
  return (
    own != null && theirs != null && realOrSelf(own) === realOrSelf(theirs)
  );
}

/**
 * Whether `cwd` sits in the Astryx repository, where Core is built from
 * source rather than installed.
 * @param {string} cwd
 */
function inAstryxRepository(cwd) {
  let dir = cwd;
  for (let i = 0; i < 6; i++) {
    try {
      const pkg = JSON.parse(
        fs.readFileSync(
          path.join(dir, 'packages', 'core', 'package.json'),
          'utf-8',
        ),
      );
      if (pkg?.name === '@astryxdesign/core') return true;
    } catch {
      // Not here; keep walking up.
    }
    const parent = path.dirname(dir);
    if (parent === dir) break;
    dir = parent;
  }
  return false;
}

/**
 * Why `theme build` has no Core to generate with, and the fix for where it
 * ran: the Astryx repository builds Core, an app installs it, and an installed
 * Core that will not load is named.
 *
 * @param {string} cwd
 * @param {any} importError - Why the import failed, when it threw.
 * @returns {string}
 */
export function coreUnavailableMessage(cwd, importError) {
  const why = `\`${formatCliCommand('theme build')}\` generates CSS with @astryxdesign/core, the same code the runtime <Theme> uses`;
  const detail = importError ? `\n  Import error: ${importError.message}` : '';
  if (inAstryxRepository(cwd)) {
    return (
      `Could not load @astryxdesign/core/theme: ${why}. Build @astryxdesign/core ` +
      `first (e.g. \`pnpm -F @astryxdesign/core build\`).${detail}`
    );
  }
  const installed = findInstalledPackage(cwd, '@astryxdesign/core');
  if (installed) {
    return (
      `Could not load the @astryxdesign/core installed at ` +
      `${path.relative(cwd, installed) || '.'}: ${why}. Reinstall it.${detail}`
    );
  }
  return (
    `This project does not have @astryxdesign/core installed: ${why}. Install ` +
    `it: \`npm install @astryxdesign/core\` (or yarn/pnpm/bun).${detail}`
  );
}

/**
 * Read a package's `version` from a resolved directory. Returns `'unknown'`
 * when it can't be read so the header always has a value.
 * @param {string|null} dir
 * @returns {string}
 */
function readPkgVersion(dir) {
  if (!dir) return 'unknown';
  try {
    const pkg = JSON.parse(
      fs.readFileSync(path.join(dir, 'package.json'), 'utf-8'),
    );
    return pkg?.version ?? 'unknown';
  } catch {
    return 'unknown';
  }
}

/**
 * Resolve the CLI and core package versions recorded in generated headers.
 * These are stable (unlike a timestamp): identical inputs produce byte-identical
 * output, so rebuilds don't churn git and `theme build --check` stays a pure
 * content-drift signal.
 * @param {string} cwd - Consumer cwd, used to locate the installed core.
 * @returns {{cli: string, core: string}}
 */
function resolveToolVersions(cwd) {
  return {
    cli: readPkgVersion(CLI_ROOT),
    core: readPkgVersion(findCoreDir(cwd)),
  };
}

/**
 * Build a @generated attribution header for generated files.
 * @param {string} sourceFile - Relative path to the source theme file
 * @param {'css'|'js'|'ts'} lang - File language (determines comment syntax)
 * @param {string} [command] - The full CLI command used to generate this file
 * @param {{cli: string, core: string}} [versions] - CLI/core versions used to build
 */
function generatedHeader(sourceFile, lang = 'js', command, versions) {
  const body = [
    `@generated by \`astryx theme build\` — do not edit manually.`,
    `Source: ${sourceFile}`,
  ];
  if (command) {
    body.push(`Command: ${command}`);
  }
  if (versions) {
    body.push(`CLI: @astryxdesign/cli@${versions.cli}`);
    body.push(`Core: @astryxdesign/core@${versions.core}`);
  }
  if (lang === 'css') {
    return `/*\n * ${body.join('\n * ')}\n */\n\n`;
  }
  return `/**\n * ${body.join('\n * ')}\n */\n\n`;
}

/**
 * Normalize generated file content for staleness comparison by dropping the
 * volatile `Command:` line of the `@generated` header (it embeds the
 * invocation, e.g. an explicit --out). Everything else — including the rest of
 * the header and all real content — is compared verbatim. Used only by
 * `--check`: a differing command must NOT report a file as stale, but any real
 * content drift must. The `CLI:`/`Core:` provenance lines are deterministic
 * for a given toolchain, so they compare verbatim like real content.
 * @param {string} content
 * @returns {string}
 */
export function normalizeThemeBuildForCompare(content) {
  return content
    .split('\n')
    .filter(line => {
      const t = line.replace(/^\s*\*?\s?/, '');
      return !t.startsWith('Command:');
    })
    .join('\n');
}

/** @param {Array<{dest: string, content: string, allowMissingInCheck?: boolean}>} writes @param {string} cwd @returns {Array<{path: string, reason: 'missing' | 'outdated'}>} */
function staleBuildOutputs(writes, cwd) {
  /** @type {Array<{path: string, reason: 'missing' | 'outdated'}>} */
  const stale = [];
  for (const write of writes) {
    const rel = path.relative(cwd, write.dest);
    if (!fs.existsSync(write.dest)) {
      if (!write.allowMissingInCheck) {
        stale.push({path: rel, reason: 'missing'});
      }
      continue;
    }
    const onDisk = fs.readFileSync(write.dest, 'utf8');
    if (
      normalizeThemeBuildForCompare(onDisk) !==
      normalizeThemeBuildForCompare(write.content)
    ) {
      stale.push({path: rel, reason: 'outdated'});
    }
  }
  return stale;
}

/** @param {Array<{dest: string, allowMissingInCheck?: boolean}>} writes @param {string} cwd */
function checkedBuildOutputs(writes, cwd) {
  return writes
    .filter(write => !write.allowMissingInCheck || fs.existsSync(write.dest))
    .map(write => path.relative(cwd, write.dest));
}

/** Remedies that end a confinement error, by where the output path came from. */
const OUT_REMEDY = 'Pass an --out path inside it.';
const SOURCE_REMEDY =
  'Without --out the outputs go beside the theme file, so run the build from a directory that contains the theme file, or pass an --out path inside the working directory.';
const FAMILY_REMEDY =
  "Family outputs go beside the family's root theme file, so run the build from a directory that contains it.";

/**
 * Refuse an output outside `root`: every write is confined, whether `out` names
 * the path or it defaults to the theme file's directory (architecture:cli-surface
 * INV10). Both sides are compared by real location, so an absolute path that
 * reaches the working directory through a symlink is inside it, and a symlink
 * inside it that leads elsewhere is not.
 * @param {string} dest absolute output path
 * @param {string} root the directory writes stay inside: the working directory
 * @param {string} remedy what to do instead; ends the error message
 * @param {string} [shown] the path as the caller wrote it, for the message
 */
function confineOutput(dest, root, remedy, shown = dest) {
  try {
    assertWithin(realLocation(dest), realOrSelf(path.resolve(root)), {
      allowAbsolute: true,
      label: 'output path',
    });
  } catch (err) {
    if (!(err instanceof PathSafetyError)) throw err;
    throw new AstryxError(
      err.code === ERROR_CODES.ERR_PATH_TRAVERSAL
        ? `Output path "${shown}" is outside the working directory (${root}). ${remedy}`
        : err.message,
      undefined,
      ERROR_CODES.ERR_PATH_TRAVERSAL,
    );
  }
}

/** @param {Array<{dest: string}>} writes @param {string} root @param {string} remedy */
function confineOutputs(writes, root, remedy) {
  for (const write of writes) confineOutput(write.dest, root, remedy);
}

/** @param {string} dest absolute output path @param {string} root @returns {boolean} whether a build at `root` refuses to write `dest` */
function refusedOutput(dest, root) {
  try {
    confineOutput(dest, root, '');
    return false;
  } catch (err) {
    if (
      err instanceof AstryxError &&
      err.code === ERROR_CODES.ERR_PATH_TRAVERSAL
    )
      return true;
    throw err;
  }
}

/** @param {string[]} dirs absolute directories @returns {string | null} the deepest directory containing all of them, or null across roots */
function commonDirectory(dirs) {
  let common = dirs[0];
  for (const dir of dirs.slice(1)) {
    while (
      path.relative(common, dir).startsWith('..') ||
      path.isAbsolute(path.relative(common, dir))
    ) {
      const parent = path.dirname(common);
      if (parent === common) return null;
      common = parent;
    }
  }
  return common;
}

/** @param {string} value @returns {string} `value` as one shell word */
function shellWord(value) {
  if (/^[A-Za-z0-9@%+=:,./_-]+$/.test(value)) return value;
  return `'${value.replace(/'/g, `'\\''`)}'`;
}

/**
 * How a stale check report ends when outputs sit outside the write root. A
 * build there refuses them, and each output's `Source:` header records the
 * directory its build ran from, so the build and the check both run from the
 * nearest directory that contains every theme file and output.
 * @param {Array<{dest: string}>} writes
 * @param {string[]} sources absolute theme files the build reads
 * @param {string} root the directory a build here keeps its writes inside
 * @param {(relative: (file: string) => string) => string[]} args the arguments after `theme build`, given each path relative to the directory to run from
 * @returns {string[] | null} report lines, or null when every output is inside `root`
 */
function outsideCheckRemedy(writes, sources, root, args) {
  if (!writes.some(write => refusedOutput(write.dest, root))) return null;
  const real = (/** @type {string} */ file) => realLocation(path.resolve(file));
  const dir = commonDirectory([
    ...sources.map(file => path.dirname(real(file))),
    ...writes.map(write => path.dirname(real(write.dest))),
  ]);
  if (!dir) {
    return [
      'These outputs are outside the working directory, so a build here refuses them. Build and check them from one directory that contains the theme files and the outputs.',
    ];
  }
  const command = (/** @type {string[]} */ extra) =>
    formatCliCommand(
      [
        'theme',
        'build',
        ...args(file => path.relative(dir, real(file))),
        ...extra,
      ]
        .map(shellWord)
        .join(' '),
      dir,
    );
  return [
    'These outputs are outside the working directory, so a build here refuses them, and each output records the directory it was built from. Build and check them from a directory that contains them:',
    `  cd ${shellWord(dir)}`,
    `  ${command([])}`,
    `  ${command(['--check'])}`,
  ];
}

/** @param {Array<{dest: string, content: string}>} writes */
function writeBuildOutputs(writes) {
  if (writes.length === 0) return;
  try {
    applyWrites(
      writes.map(write => ({
        path: write.dest,
        contents: write.content,
        createOnly: false,
      })),
    );
  } catch (error) {
    const message = `Failed to write theme outputs: ${/** @type {Error} */ (error).message}`;
    throw new AstryxError(message, undefined, ERROR_CODES.ERR_WRITE_FAILED);
  }
}

/**
 * Convert a theme name to a valid JS identifier.
 *
 * Deterministic sanitization rule — only transforms characters that are invalid
 * in JS identifiers (`-` and `.`); underscores are already valid and preserved:
 * 1. Replace every run of invalid separators (`-`, `.`) followed by an
 *    alphanumeric or underscore character with that character uppercased.
 * 2. Strip any remaining invalid separators (leading or trailing).
 * 3. If the result starts with a digit, prefix with `_`.
 * 4. If the result is empty, return `_`.
 *
 * Examples:
 *   'ocean'            → 'ocean'
 *   'default-minimal'  → 'defaultMinimal'
 *   'chaos-07'         → 'chaos07'
 *   'a-1-b'            → 'a1B'
 *   'my--theme'        → 'myTheme'
 *   'brand.v2'         → 'brandV2'
 *   'my_theme'         → 'my_theme'    (underscore preserved)
 *   'neo_wave-2.x'     → 'neo_wave2X'
 *
 * @param {string} name
 * @returns {string}
 */
function toIdentifier(name) {
  const id = name
    .replace(
      /[-.]+([a-zA-Z0-9_])/g,
      (/** @type {string} */ _, /** @type {string} */ c) => c.toUpperCase(),
    )
    .replace(/[-.]+/g, '');
  return /^\d/.test(id) ? `_${id}` : id || '_';
}

/**
 * Import specifier for install/scaffold instructions. Drops a leading `src/`
 * from the cwd-relative dir (most consumers import from a file under src/) but
 * keeps the rest of the path (e.g. `themes/gothic`). Callers note the path is
 * relative to the consumer's file.
 * @param {string} relDir
 * @param {string} base
 * @returns {string}
 */
export function importSpecifier(relDir, base) {
  const normalized = relDir === '.' ? '' : relDir;
  const withinSrc = normalized.replace(/^src\/?/, '').replace(/\/+$/, '');
  return withinSrc ? `./${withinSrc}/${base}` : `./${base}`;
}

/**
 * Convert a kebab-case component name to PascalCase.
 * e.g. 'button' → 'Button', 'progress-bar' → 'ProgressBar', 'avatar-status-dot' → 'AvatarStatusDot'
 * @param {string} name
 * @returns {string}
 */
function toPascalCase(name) {
  return name
    .split('-')
    .map(
      (/** @type {string} */ part) =>
        part.charAt(0).toUpperCase() + part.slice(1),
    )
    .join('');
}

/** @type {Promise<Record<string, Record<string, string[]>>> | null} */
let _knownValuesIndexPromise = null;

/**
 * Build one target-keyed index of built-in visual-prop values from every core
 * component doc. A rendered target often lives in a sibling doc (for example,
 * `astryx-heading` is documented by Text/Heading.doc.mjs), so directory-name
 * guessing is not a valid lookup strategy.
 */
async function loadKnownValuesIndex() {
  const coreRoot = resolveCoreRoot();
  const coreSrc = coreRoot ? path.join(coreRoot, 'src') : null;
  if (!coreSrc || !fs.existsSync(coreSrc)) return {};

  /** @type {any[]} */
  const docs = [];
  /** @param {string} dir */
  async function scan(dir) {
    for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
      const full = path.join(dir, entry.name);
      if (entry.isDirectory()) {
        if (entry.name !== 'node_modules' && entry.name !== '__tests__') {
          await scan(full);
        }
        continue;
      }
      if (!entry.name.endsWith('.doc.mjs')) continue;
      try {
        docs.push(await loadComponentDoc(full));
      } catch {
        // One malformed or optional doc must not erase validation for the rest.
      }
    }
  }
  await scan(coreSrc);

  /** @param {string} value */
  const targetName = value =>
    value
      .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
      .replace(/\s+/g, '-')
      .toLowerCase();
  /**
   * @param {any[]} props
   * @returns {Record<string, Set<string>>}
   */
  const valuesFromProps = props => {
    /** @type {Record<string, Set<string>>} */
    const result = {};
    for (const prop of props ?? []) {
      if (typeof prop?.name !== 'string' || typeof prop?.type !== 'string') {
        continue;
      }
      /** @type {Set<string>} */
      const values = new Set();
      for (const match of prop.type.match(/'([^']+)'/g) ?? []) {
        values.add(match.slice(1, -1));
      }
      for (const part of prop.type
        .split('|')
        .map((/** @type {string} */ value) => value.trim())) {
        if (/^-?\d+(?:\.\d+)?$/.test(part)) values.add(part);
      }
      if (values.size > 0) result[prop.name] = values;
    }
    return result;
  };

  // A component can appear in more than one doc: its own doc declares its
  // props, and a parent doc can list it by name only. Merge every entry, so
  // the result does not depend on the order the docs load in.
  /** @type {Record<string, Record<string, Set<string>>>} */
  const valuesByOwner = {};
  /**
   * @param {string} name
   * @param {any[]} props
   */
  const addOwnerValues = (name, props) => {
    const owner = (valuesByOwner[targetName(name)] ??= {});
    for (const [prop, values] of Object.entries(valuesFromProps(props))) {
      owner[prop] = new Set([...(owner[prop] ?? []), ...values]);
    }
  };
  for (const doc of docs) {
    if (typeof doc?.name === 'string') {
      addOwnerValues(doc.name, doc.props);
    }
    for (const component of /** @type {any[]} */ (doc?.components ?? [])) {
      if (typeof component?.name === 'string') {
        addOwnerValues(component.name, component.props);
      }
    }
  }

  /** @type {Record<string, Record<string, Set<string>>>} */
  const collected = {};
  for (const doc of docs) {
    const localValues = valuesFromProps([
      ...(doc?.props ?? []),
      ...(doc?.components ?? []).flatMap(
        (/** @type {any} */ component) => component?.props ?? [],
      ),
    ]);
    for (const target of doc?.theming?.targets ?? []) {
      if (typeof target?.className !== 'string') continue;
      const componentName = target.className.replace(/^astryx-/, '');
      const ownerValues = valuesByOwner[componentName] ?? {};
      if (!collected[componentName]) collected[componentName] = {};
      for (const prop of target.visualProps ?? []) {
        if (!collected[componentName][prop]) {
          collected[componentName][prop] = new Set();
        }
        for (const value of [
          ...(localValues[prop] ?? []),
          ...(ownerValues[prop] ?? []),
        ]) {
          collected[componentName][prop].add(value);
        }
      }
    }
  }

  return Object.fromEntries(
    Object.entries(collected).map(([component, props]) => [
      component,
      Object.fromEntries(
        Object.entries(props).map(([prop, values]) => [prop, [...values]]),
      ),
    ]),
  );
}

/**
 * @param {string} componentName
 * @returns {Promise<Record<string, string[]>>}
 */
async function getKnownValues(componentName) {
  _knownValuesIndexPromise ??= loadKnownValuesIndex();
  const index = await _knownValuesIndexPromise;
  return index[componentName] ?? {};
}

/**
 * Resolve `@astryxdesign/core`'s package root relative to the CLI package. Core
 * and the CLI ship as siblings (`@astryxdesign/core`, `@astryxdesign/cli`), so
 * `../../../../core` from `api/theme/build/` reaches core whether installed from
 * npm or run inside the monorepo. Returns null if it can't be found.
 */
function resolveCoreRoot() {
  const cliDir = path.dirname(fileURLToPath(import.meta.url));
  const coreRoot = path.resolve(cliDir, '../../../../core');
  return fs.existsSync(coreRoot) ? coreRoot : null;
}

/**
 * Read the type declarations `@astryxdesign/core/<Component>` exposes so we can
 * check whether a given augmentation-target interface actually exists before
 * generating a module augmentation against it.
 *
 * Reads the shipped `dist/<Component>/index.d.ts` (what a consumer's TypeScript
 * actually sees), falling back to the `src/<Component>/index.ts` in the
 * monorepo. Returns the file contents, or '' if nothing is found.
 */
/** @type {Map<string, string>} */
const _componentDeclCache = new Map();
/**
 * @param {string} pascalName
 * @param {{includeTypes?: boolean}} [options]
 * @returns {string}
 */
function readComponentDeclarations(pascalName, options = {}) {
  const includeTypes = options.includeTypes === true;
  const cacheKey = `${pascalName}:${includeTypes ? 'with-types' : 'index-only'}`;
  if (_componentDeclCache.has(cacheKey)) {
    return _componentDeclCache.get(cacheKey) ?? '';
  }
  let contents = '';
  const coreRoot = resolveCoreRoot();
  if (coreRoot) {
    const candidateSets = [
      [path.join(coreRoot, 'dist', pascalName, 'index.d.ts')],
      [path.join(coreRoot, 'src', pascalName, 'index.ts')],
    ];
    if (includeTypes) {
      candidateSets[0].push(
        path.join(coreRoot, 'dist', pascalName, 'types.d.ts'),
      );
      candidateSets[1].push(path.join(coreRoot, 'src', pascalName, 'types.ts'));
    }
    for (const files of candidateSets) {
      if (fs.existsSync(files[0])) {
        for (const file of files) {
          try {
            if (fs.existsSync(file)) {
              contents += fs.readFileSync(file, 'utf-8') + '\n';
            }
          } catch {
            // ignore
          }
        }
        if (contents) break;
      }
    }
  }
  _componentDeclCache.set(cacheKey, contents);
  return contents;
}

/** @type {Map<string, Array<{moduleName: string, interfacePrefix: string}>>} */
const _augmentationTargetCache = new Map();

/**
 * Resolve a rendered theme class token (the key without `astryx-`) to candidate
 * public core subpaths and interface prefixes that may own its augmentable prop
 * maps. Some tokens are subtargets documented by a parent component
 * (`avatar-status-dot` augments `@astryxdesign/core/Avatar`). Component docs are
 * the source of truth for the target token → owning component relationship.
 *
 * @param {string} componentName
 * @returns {Promise<Array<{moduleName: string, interfacePrefix: string}>>}
 */
async function resolveAugmentationTargetCandidates(componentName) {
  if (_augmentationTargetCache.has(componentName)) {
    return /** @type {Array<{moduleName: string, interfacePrefix: string}>} */ (
      _augmentationTargetCache.get(componentName)
    );
  }

  const fallback = [
    {
      moduleName: toPascalCase(componentName),
      interfacePrefix: toPascalCase(componentName),
    },
  ];

  const coreRoot = resolveCoreRoot();
  const coreSrc = coreRoot ? path.join(coreRoot, 'src') : null;
  if (!coreSrc || !fs.existsSync(coreSrc)) {
    _augmentationTargetCache.set(componentName, fallback);
    return fallback;
  }

  /** @type {Array<{moduleName: string, interfacePrefix: string}>} */
  const matches = [];
  /** @type {Set<string>} */
  const seen = new Set();

  /**
   * @param {string} moduleName
   * @param {string} interfacePrefix
   */
  function addCandidate(moduleName, interfacePrefix) {
    const key = `${moduleName}:${interfacePrefix}`;
    if (seen.has(key)) return;
    seen.add(key);
    matches.push({moduleName, interfacePrefix});
  }

  /** @param {string} dir */
  async function scan(dir) {
    const entries = fs.readdirSync(dir, {withFileTypes: true});
    for (const entry of entries) {
      const full = path.join(dir, entry.name);
      if (entry.isDirectory()) {
        if (entry.name === 'node_modules' || entry.name === '__tests__')
          continue;
        await scan(full);
        continue;
      }
      if (!entry.name.endsWith('.doc.mjs')) continue;

      /** @type {any} */
      let doc;
      try {
        doc = await loadComponentDoc(full);
      } catch {
        continue;
      }

      const matchesTarget = (doc?.theming?.targets || []).some(
        (/** @type {any} */ target) =>
          typeof target?.className === 'string' &&
          target.className.replace(/^astryx-/, '') === componentName,
      );
      if (!matchesTarget) continue;

      const moduleName =
        typeof doc?.name === 'string' && doc.name
          ? doc.name
          : path.basename(path.dirname(full));

      // Try the exact rendered token first for documented subtargets such as
      // avatar-status-dot → AvatarStatusDotVariantMap, then the owning public
      // component name (for example, ProgressBar for progress-bar-fill).
      addCandidate(moduleName, toPascalCase(componentName));
      addCandidate(moduleName, moduleName);
      if (Array.isArray(doc?.components)) {
        for (const comp of doc.components) {
          if (typeof comp?.name === 'string') {
            addCandidate(moduleName, comp.name);
          }
        }
      }
    }
  }

  await scan(coreSrc);
  // A target documented by a parent component may also have its own public
  // subpath and augmentation interface (Heading is documented under Text but
  // owns @astryxdesign/core/Heading). Keep the direct-name candidate after
  // discovered owners so both shapes are reachable without guessing which one
  // the source tree uses.
  for (const candidate of fallback) {
    addCandidate(candidate.moduleName, candidate.interfacePrefix);
  }
  const resolved = matches;
  _augmentationTargetCache.set(componentName, resolved);
  return resolved;
}

/**
 * Determine whether `@astryxdesign/core/<Component>` exports an interface named
 * `interfaceName` that can be augmented via module augmentation.
 *
 * Only interfaces are extension points — closed literal-union types (e.g.
 * `HeadingType`, `ButtonSize`) are NOT augmentable, so a generated augmentation
 * against them is dead code. We check that the name is exported (directly or
 * re-exported) as a type/interface.
 * @param {string} pascalName
 * @param {string} interfaceName
 * @param {{includeTypes?: boolean}} [options]
 * @returns {boolean}
 */
function componentHasAugmentableInterface(pascalName, interfaceName, options) {
  const decl = readComponentDeclarations(pascalName, options);
  if (!decl) return false;
  // Require an actual interface declaration in this public subpath, not just a
  // type re-export. Module augmentation only widens consumers that import the
  // module where the interface is declared; augmenting a barrel that re-exports
  // the type (e.g. Field re-exporting FieldStatusVariantMap) creates a dead
  // sibling interface for consumers of the real FieldStatus subpath.
  const re = new RegExp(String.raw`\binterface\s+${interfaceName}\b`);
  return re.test(decl);
}

/**
 * Public augmentable maps whose axis requests artwork instead of styling.
 * `Icon.variant` selects a theme's icon artwork, so it has no component styling
 * map (architecture:component-theming-surface INV14): a `components` key on it
 * never enrolls a value or generates an augmentation of its map.
 */
const ARTWORK_REQUEST_MAPS = new Set(['IconVariantMap']);

/**
 * Whether a theme's component styling keys may enroll values in `interfaceName`
 * on `@astryxdesign/core/<Component>`.
 * @param {string} pascalName
 * @param {string} interfaceName
 * @returns {boolean}
 */
function isComponentValueAugmentationPoint(pascalName, interfaceName) {
  return (
    !ARTWORK_REQUEST_MAPS.has(interfaceName) &&
    componentHasAugmentableInterface(pascalName, interfaceName)
  );
}

/**
 * Extension points whose public module and interface do not follow the usual
 * `<Component><Prop>Map` convention. TextType reads CustomTextTypes from the
 * theme module, so both classification and declaration emission must resolve
 * this same public augmentation point.
 *
 * @type {Record<string, {moduleName: string, interfaceName: string, includeTypes?: boolean}>}
 */
const AUGMENTATION_OVERRIDES = {
  'text.type': {
    moduleName: 'theme',
    interfaceName: 'CustomTextTypes',
    includeTypes: true,
  },
};

/**
 * Resolve the public module/interface that can widen a component prop value.
 * @param {string} component
 * @param {string} prop
 * @returns {Promise<{moduleName: string, interfaceName: string}|null>}
 */
async function resolveAugmentationTarget(component, prop) {
  const override = AUGMENTATION_OVERRIDES[`${component}.${prop}`];
  if (override) {
    return componentHasAugmentableInterface(
      override.moduleName,
      override.interfaceName,
      {includeTypes: override.includeTypes},
    )
      ? {moduleName: override.moduleName, interfaceName: override.interfaceName}
      : null;
  }

  const propPascal = prop.charAt(0).toUpperCase() + prop.slice(1);
  const target = (await resolveAugmentationTargetCandidates(component)).find(
    candidate =>
      isComponentValueAugmentationPoint(
        candidate.moduleName,
        `${candidate.interfacePrefix}${propPascal}Map`,
      ),
  );
  return target
    ? {
        moduleName: target.moduleName,
        interfaceName: `${target.interfacePrefix}${propPascal}Map`,
      }
    : null;
}

/**
 * Adaptation values from resolved runtime rules, raw input, or normalized built
 * metadata. Built modules intentionally omit `__adaptationRules`, so every CLI
 * diagnostic that reads rule intent must also understand `__adaptations`.
 *
 * @param {Record<string, any>} themeDef
 * @returns {Record<string, any>[]}
 */
function adaptationRuleValues(themeDef) {
  if (Array.isArray(themeDef.__adaptationRules)) {
    return themeDef.__adaptationRules;
  }
  const rules = themeDef.adaptations?.rules ?? themeDef.__adaptations?.rules;
  if (!Array.isArray(rules)) return [];
  return rules.map((/** @type {any} */ rule) => rule?.value).filter(Boolean);
}

const ADAPTATION_METADATA_KEYS = new Set(['widthBreakpoints', 'rules']);
const WIDTH_BREAKPOINT_NAMES = ['sm', 'md', 'lg', 'xl', '2xl'];

/** @param {unknown} value @returns {value is Record<string, any>} */
function isRecord(value) {
  return value !== null && typeof value === 'object' && !Array.isArray(value);
}

/**
 * A malformed adaptations block is intent too: an old core erases it before it
 * can be validated, so treating only valid non-empty arrays/maps as intent
 * would turn author errors into successful, incomplete builds.
 *
 * @param {unknown} adaptations
 * @returns {boolean}
 */
function adaptationMetadataHasIntent(adaptations) {
  if (adaptations === undefined) return false;
  if (!isRecord(adaptations)) return true;
  if (
    Object.keys(adaptations).some(key => !ADAPTATION_METADATA_KEYS.has(key))
  ) {
    return true;
  }

  if (adaptations.rules !== undefined) {
    if (!Array.isArray(adaptations.rules)) return true;
    if (adaptations.rules.length > 0) return true;
  }

  if (adaptations.widthBreakpoints !== undefined) {
    if (hasMalformedWidthBreakpoints(adaptations.widthBreakpoints)) return true;
    if (hasCustomWidthBreakpoints(adaptations.widthBreakpoints)) return true;
  }
  return false;
}

/**
 * Does this theme carry ordered-adaptation intent the installed core must be
 * able to compile or validate?
 *
 * A theme reaches the build in three shapes and this has to see all of them:
 * raw `adaptations`, resolved `__adaptationRules`, and a built module's
 * `__adaptations`. Any rule, custom width map, or malformed present metadata is
 * intent. Malformed data matters because an old core erases it before its
 * current-core validation can run; accepting it would turn an author error into
 * a successful incomplete build.
 *
 * The complete default width map with an empty rule list is the one no-op: core
 * writes that shape onto every resolved theme and every shipped built theme.
 *
 * @param {any} themeDef
 * @returns {boolean}
 */
function hasAdaptationIntent(themeDef) {
  if (!themeDef || typeof themeDef !== 'object') return false;

  if (themeDef.__adaptationRules !== undefined) {
    if (!Array.isArray(themeDef.__adaptationRules)) return true;
    if (themeDef.__adaptationRules.length > 0) return true;
  }

  return (
    adaptationMetadataHasIntent(themeDef.adaptations) ||
    adaptationMetadataHasIntent(themeDef.__adaptations)
  );
}

/**
 * The default viewport-width tier start points, in CSS px. A theme whose
 * effective map is exactly this asked for nothing.
 * SYNC: packages/core/src/theme/themeAdaptations.ts (DEFAULT_WIDTH_BREAKPOINTS)
 */
const DEFAULT_WIDTH_BREAKPOINTS = Object.freeze({
  sm: 640,
  md: 768,
  lg: 1024,
  xl: 1280,
  '2xl': 1536,
});

/**
 * @param {unknown} widthBreakpoints
 * @returns {boolean}
 */
function hasMalformedWidthBreakpoints(widthBreakpoints) {
  if (!isRecord(widthBreakpoints)) return true;
  const names = Object.keys(widthBreakpoints);
  if (names.some(name => !WIDTH_BREAKPOINT_NAMES.includes(name))) return true;
  for (const name of names) {
    const point = widthBreakpoints[name];
    if (typeof point !== 'number' || !Number.isFinite(point) || point <= 0) {
      return true;
    }
  }

  const effective = /** @type {Record<string, number>} */ ({
    ...DEFAULT_WIDTH_BREAKPOINTS,
    ...widthBreakpoints,
  });
  for (let index = 1; index < WIDTH_BREAKPOINT_NAMES.length; index++) {
    if (
      effective[WIDTH_BREAKPOINT_NAMES[index]] <=
      effective[WIDTH_BREAKPOINT_NAMES[index - 1]]
    ) {
      return true;
    }
  }
  return false;
}

/**
 * @param {unknown} widthBreakpoints
 * @returns {boolean}
 */
function hasCustomWidthBreakpoints(widthBreakpoints) {
  if (!widthBreakpoints || typeof widthBreakpoints !== 'object') return false;
  const points = /** @type {Record<string, number>} */ (widthBreakpoints);
  const defaults = /** @type {Record<string, number>} */ (
    DEFAULT_WIDTH_BREAKPOINTS
  );
  const names = Object.keys(points);
  if (names.length === 0) return false;
  // Any point that differs from the default is custom. So is a PARTIAL map:
  // core merges it over the defaults, which is a real, inheritable override
  // even when every value it names happens to match. A COMPLETE map equal to
  // the defaults asks for nothing — which is exactly what core writes onto
  // every theme it resolves, and what every shipped built theme carries.
  if (names.some(name => points[name] !== defaults[name])) return true;
  return names.length !== Object.keys(defaults).length;
}

/**
 * Fail when a theme needs ordered adaptations and the installed core cannot
 * compile them.
 *
 * The CLI and core are optional peers on independent release trains, so a
 * newer CLI routinely runs against an older published core. Adaptations are a
 * capability of core's generator: without `generateAdaptationCSS` the build
 * could still emit token and component CSS, and every adaptation rule would
 * vanish from the output with no signal. That is the one outcome this must
 * never produce — so it stops before anything is generated or written, names
 * the missing capability, and says what to do about it.
 *
 * `lineage` is the selected theme's own ancestry — the raw inputs it and its
 * bases were resolved from, captured as the file loaded (core-interception).
 * An older core's `defineTheme()` drops `adaptations` while resolving, so the
 * resolved object alone cannot answer; the raw input can. Scoping to lineage
 * is what keeps an unrelated adaptive theme in the same module from failing a
 * plain theme's build.
 *
 * `unobserved`, when non-empty, lists lineage members the recorder never saw
 * because one or more loader paths could not be intercepted. `degradation`
 * names those gaps: top-level await forced the async loader, or a CommonJS
 * source dependency could reach a frozen/non-configurable core namespace.
 * Those members cannot be proven clean, and unproven must not build.
 *
 * Silent for a theme with no adaptation intent and fully observed lineage:
 * those build against an older core exactly as they always did.
 *
 * @param {any} themeDef - Raw or resolved theme; both shapes are understood.
 * @param {{coreVersion?: string, lineage?: any[], unobserved?: any[], degradation?: {topLevelAwait?: boolean, commonJs?: boolean}}} [context]
 * @returns {void}
 */
function assertAdaptationCapability(
  themeDef,
  {coreVersion, lineage, unobserved, degradation} = {},
) {
  if (_generateAdaptationCSS) return;
  // A core that could not be imported at all is ERR_CORE_NOT_FOUND's story —
  // "upgrade core" would be the wrong advice for "core is missing".
  if (!_defineTheme || !_generateThemeRulesSplit) return;

  const candidates = lineage?.length ? lineage : [themeDef];
  const installed =
    coreVersion && coreVersion !== 'unknown'
      ? `@astryxdesign/core@${coreVersion}`
      : 'the installed @astryxdesign/core';

  if (candidates.some(hasAdaptationIntent)) {
    throw new AstryxError(
      `This theme declares ordered adaptations, but ${installed} does not ` +
        'export `generateAdaptationCSS` from @astryxdesign/core/theme, so ' +
        'its adaptation rules cannot be compiled. Building without them ' +
        'would silently drop every adaptation rule from the generated CSS. ' +
        'Upgrade @astryxdesign/core to a version that supports theme ' +
        'adaptations, or remove `adaptations` from this theme.',
      undefined,
      ERROR_CODES.ERR_CORE_INCOMPATIBLE,
    );
  }

  if (!unobserved?.length) return;

  // These lineage members carry neither a capture marker nor their own
  // `__adaptations`: they were never observed, this core would have erased any
  // adaptations they had, and nothing here can tell whether they had any.
  // Unproven is not clean.
  const named = unobserved
    .map(value => (typeof value?.name === 'string' ? `"${value.name}"` : null))
    .filter(Boolean);
  const gaps = [
    degradation?.topLevelAwait
      ? 'top-level await forced the fallback loader for installed packages'
      : null,
    degradation?.commonJs
      ? 'a CommonJS source dependency reached a frozen or non-configurable core namespace'
      : null,
  ].filter(Boolean);
  throw new AstryxError(
    `${installed} cannot compile ordered adaptations, and whether ${
      named.length > 0 ? named.join(', ') : 'part of this theme'
    } uses adaptations could not be observed${
      gaps.length > 0 ? ` because ${gaps.join(' and ')}` : ''
    }. This core erases adaptations while resolving, so building could emit ` +
      'CSS with adaptation rules silently missing. Upgrade ' +
      '@astryxdesign/core to a version that supports theme adaptations, or ' +
      'use a built theme artifact that retains adaptation metadata.',
    undefined,
    ERROR_CODES.ERR_CORE_INCOMPATIBLE,
  );
}

/**
 * Root component entries are the only surface allowed to introduce variants.
 * @param {Record<string, any>} themeDef
 * @returns {[string, Record<string, any>][]}
 */
function rootComponentEntries(themeDef) {
  return themeDef.components ? Object.entries(themeDef.components) : [];
}

/**
 * Component entries written only by adaptation rules.
 * @param {Record<string, any>} themeDef
 * @returns {[string, Record<string, any>][]}
 */
function adaptationComponentEntries(themeDef) {
  const maps = adaptationRuleValues(themeDef).map(
    (/** @type {any} */ value) => value.components,
  );
  return maps.flatMap((/** @type {any} */ map) =>
    map ? Object.entries(map) : [],
  );
}

/**
 * How one `prop:value` pair on a component target is classified — the single
 * vocabulary both the root and adaptation paths reason in.
 *
 * - `builtin` — the value is in the component doc's enumerated domain. Valid
 *   on its own; no theme has to declare anything for it.
 * - `enrollment` — the value is not built in AND core exposes an augmentable
 *   `*Map` interface for the prop, so the value becomes valid only because a
 *   theme enrolls it (the build generates module augmentation for it).
 * - `unresolved` — anything else: a closed literal-union axis with no
 *   augmentation point (Button `size`), or a domain the docs cannot enumerate.
 *   Root emits no augmentation and accepts it as pass-through.
 *
 * SYNC: packages/cli/api/theme/build/build.mjs (generateVariantDeclarationsAsync,
 * validateAdaptationEnrollment)
 *
 * @typedef {'builtin' | 'enrollment' | 'unresolved'} ComponentValueClass
 */

/**
 * Classify a component visual-prop value.
 *
 * This is the ONE place that decides what a value is, so the root and
 * adaptation paths cannot drift: per AST-012/DEC-5 an adaptation uses the same
 * target, axis, value-domain and extension validation as root `components`,
 * and adds only the rule that enrollment-dependent values may not be enrolled
 * conditionally. An unresolved result carries into adaptations unchanged, and
 * tightening root validation tightens adaptations automatically.
 *
 * @param {string} component - Rendered target token (without `astryx-`).
 * @param {string} prop
 * @param {string} value
 * @returns {Promise<ComponentValueClass>}
 */
async function classifyComponentValue(component, prop, value) {
  const known = await getKnownValues(component);
  const knownForProp = known[prop];
  if (knownForProp && knownForProp.includes(value)) {
    return 'builtin';
  }

  const target = await resolveAugmentationTarget(component, prop);
  return target ? 'enrollment' : 'unresolved';
}

/**
 * Every `prop:value` pair a component override key names. A key is `base`, a
 * bare state name, or `+`-joined `prop:value` pairs.
 *
 * @param {string} key
 * @returns {{prop: string, value: string, pair: string}[]}
 */
function componentValuePairs(key) {
  if (key === 'base') return [];
  /** @type {{prop: string, value: string, pair: string}[]} */
  const pairs = [];
  for (const pair of key.split('+')) {
    const colon = pair.indexOf(':');
    if (colon === -1) continue;
    pairs.push({
      prop: pair.slice(0, colon),
      value: pair.slice(colon + 1),
      pair,
    });
  }
  return pairs;
}

/**
 * Reject values whose validity depends on THEME ENROLLMENT when only an
 * adaptation rule enrolls them.
 *
 * Per AST-012/DEC-5 this is the single thing adaptations add to root
 * validation. Everything else — which targets and axes exist, which values a
 * domain admits — is the root path's judgement, reached through the shared
 * classifier, so there is no adaptation-specific resolver, allowlist or
 * unresolved-domain exception here:
 *
 * - `builtin` values are independently valid and need no root declaration;
 * - `unresolved` values carry root's shared result unchanged (accepting one
 *   does not make the axis extensible — the conditional-API invariant still
 *   governs it, and tightening root tightens this automatically);
 * - `enrollment` values are the exception: generated module augmentation is
 *   unconditional, so a value that exists only under a media condition would
 *   widen a component's public type from a conditional surface. Those must
 *   appear on the effective root `components` surface first.
 *
 * @param {Record<string, any>} themeDef
 * @returns {Promise<string[]>}
 */
async function validateAdaptationEnrollment(themeDef) {
  const adaptationEntries = adaptationComponentEntries(themeDef);
  if (adaptationEntries.length === 0) {
    return [];
  }

  /** @type {Set<string>} */
  const rootValues = new Set();
  for (const [component, rules] of rootComponentEntries(themeDef)) {
    for (const key of Object.keys(rules)) {
      for (const {pair} of componentValuePairs(key)) {
        rootValues.add(`${component}:${pair}`);
      }
    }
  }

  /** @type {string[]} */
  const errors = [];
  for (const [component, rules] of adaptationEntries) {
    for (const key of Object.keys(rules)) {
      for (const {prop, value, pair} of componentValuePairs(key)) {
        if (rootValues.has(`${component}:${pair}`)) continue;
        const valueClass = await classifyComponentValue(component, prop, value);
        if (valueClass !== 'enrollment') continue;
        errors.push(
          `Adaptation rule enrolls the custom value "${component}.${prop}:${value}". ` +
            'A value that is valid only because a theme enrolls it generates ' +
            'unconditional type augmentation, so it must be declared on the root ' +
            'theme first; a rule may then restyle it under a condition.',
        );
      }
    }
  }
  return [...new Set(errors)];
}

/**
 * Generate TypeScript declaration content with module augmentation for custom
 * component prop values found in the theme's `components` keys. Reads known
 * values from doc files to filter out base prop values.
 *
 * Interface naming convention: PascalCase(component) + PascalCase(prop) + Map
 *   banner + status → BannerStatusMap
 *   button + variant → ButtonVariantMap
 *
 * An augmentation is only emitted when `@astryxdesign/core/<Component>` actually
 * exports a matching interface. Props backed by closed literal-union types
 * (e.g. Button `size`, Heading `type`/`level`) have no augmentation point, so
 * generating a `declare module` block for them would be dead code — those are
 * skipped.
 *
 * A theme that lists `iconVariants` also augments `IconVariantMap` in
 * `@astryxdesign/core/Icon` with those names, when the installed core declares
 * it, so `<Icon variant>` accepts them (spec:AST-087 FR3).
 *
 * @param {{components?: Record<string, Record<string, Record<string, unknown>>>, iconVariants?: readonly string[]}} themeDef - Theme definition (resolved by defineTheme)
 * @returns {Promise<string|null>} TypeScript declaration content, or null if no augmentations needed
 */
async function generateVariantDeclarationsAsync(themeDef) {
  const componentLayers = getThemeComponentLayers(themeDef);
  const iconVariantNames =
    Array.isArray(themeDef.iconVariants) &&
    componentHasAugmentableInterface('Icon', 'IconVariantMap')
      ? [...new Set(themeDef.iconVariants)]
      : [];
  if (componentLayers.length === 0 && iconVariantNames.length === 0) {
    return null;
  }

  // Collect enrollment-dependent values: { component: { prop: [value, ...] } }
  // Classification is shared with the adaptation check, so "what is a custom
  // value" has exactly one definition (AST-012/DEC-5).
  /** @type {Record<string, Record<string, Set<string>>>} */
  const customValues = {};

  for (const {components} of componentLayers) {
    for (const [component, rules] of Object.entries(components)) {
      for (const key of Object.keys(rules)) {
        for (const {prop, value} of componentValuePairs(key)) {
          // Built-ins need no augmentation; unresolved axes have no
          // augmentation point to widen, and are passed through untouched.
          const valueClass = await classifyComponentValue(
            component,
            prop,
            value,
          );
          if (valueClass !== 'enrollment') continue;

          if (!customValues[component]) customValues[component] = {};
          if (!customValues[component][prop])
            customValues[component][prop] = new Set();
          customValues[component][prop].add(value);
        }
      }
    }
  }

  // Check if we found any custom values
  const hasCustom = Object.values(customValues).some(props =>
    Object.values(props).some(values => values.size > 0),
  );
  if (!hasCustom && iconVariantNames.length === 0) return null;

  const sections = ['// Generated by astryx theme build', 'export {};', ''];

  for (const [component, props] of Object.entries(customValues)) {
    for (const [prop, values] of Object.entries(props)) {
      if (values.size === 0) continue;

      const target = await resolveAugmentationTarget(component, prop);

      // Resolve the augmentation point again to name it. Classification has
      // already established that one exists (that is what `enrollment` means),
      // so this is a lookup, not a filter — but a target that somehow fails to
      // resolve here must not emit a `declare module` block against a
      // non-existent interface, which would create a dead sibling interface
      // rather than widening the component's prop union.
      if (!target) continue;

      const modulePath = `@astryxdesign/core/${target.moduleName}`;
      const {interfaceName} = target;

      sections.push(`declare module '${modulePath}' {`);
      sections.push(`  interface ${interfaceName} {`);
      for (const v of values) {
        sections.push(`    '${v}': true;`);
      }
      sections.push('  }');
      sections.push('}');
      sections.push('');
    }
  }

  if (iconVariantNames.length > 0) {
    sections.push(`declare module '@astryxdesign/core/Icon' {`);
    sections.push('  interface IconVariantMap {');
    for (const name of iconVariantNames) {
      sections.push(`    ${tsStringLiteral(name)}: true;`);
    }
    sections.push('  }');
    sections.push('}');
    sections.push('');
  }

  // If every custom value targeted a non-augmentable prop, there's nothing to
  // emit beyond the header — return null so no `.variants.d.ts` is written.
  const hasEmittedAugmentation = sections.some(line =>
    line.startsWith('declare module'),
  );
  if (!hasEmittedAugmentation) return null;

  return sections.join('\n');
}

/**
 * Resolve a token value — [light, dark] tuple becomes light-dark()
 * @param {unknown} value
 * @returns {unknown}
 */
function resolveTokenValue(value) {
  if (Array.isArray(value)) {
    return `light-dark(${value[0]}, ${value[1]})`;
  }
  return value;
}

// Theme @scope selector helpers. Keep the `astryx` literal in sync with
// packages/core/src/naming.ts (NAMESPACE) and generateThemeRules.ts.
// Theme scopes to data-astryx-theme; the static build path must match.
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',
];
// prettier-ignore
const registryGraphError = (/** @type {string} */ message) => new AstryxError(message, undefined, ERROR_CODES.ERR_THEME_INVALID);
// prettier-ignore
function parseRegistryModule(/** @type {string} */ source, /** @type {string} */ filePath) {
  try { return parse(source, {sourceType: 'unambiguous', plugins: ['typescript', 'jsx', 'decorators-legacy', 'importAttributes']}); }
  catch (error) { throw registryGraphError(`Cannot inspect registry module ${filePath}: ${error instanceof Error ? error.message : String(error)}`); }
}
// prettier-ignore
function moduleDependencies(/** @type {string} */ source, /** @type {string} */ filePath) {
  const ast = parseRegistryModule(source, filePath);
  /** @type {Array<{specifier: string, commonJs: boolean, imports: string[]}>} */ const found = [];
  /** @param {any} node */ const literal = node => typeof node?.value === 'string' ? node.value : node?.type === 'TemplateLiteral' && node.expressions.length === 0 ? node.quasis[0]?.value?.cooked : null;
  /** @param {any} node */ const visit = node => {
    if (!node || typeof node !== 'object') return;
    if (['ImportDeclaration', 'ExportNamedDeclaration', 'ExportAllDeclaration'].includes(node.type) && node.importKind !== 'type' && typeof node.source?.value === 'string') {
      const specifiers = /** @type {any[]} */ (node.specifiers);
      const imports = node.type === 'ImportDeclaration' ? specifiers.filter(item => item.importKind !== 'type' && item.type !== 'ImportNamespaceSpecifier').map(item => item.type === 'ImportDefaultSpecifier' ? 'default' : item.imported?.name ?? item.imported?.value) : node.type === 'ExportNamedDeclaration' ? specifiers.filter(item => item.exportKind !== 'type' && item.type === 'ExportSpecifier').map(item => item.local?.name ?? item.local?.value) : [];
      found.push({specifier: node.source.value, commonJs: false, imports});
    }
    const dependency = node.type === 'ImportExpression' ? node.source : node.type === 'CallExpression' && (node.callee?.type === 'Import' || node.callee?.name === 'require') ? node.arguments?.[0] : null;
    if (dependency) { const specifier = literal(dependency); if (specifier == null) throw registryGraphError(`Registry module ${filePath} has a non-static dependency; family output cannot prove that graph is resolvable and CSS-free.`); found.push({specifier, commonJs: node.callee?.name === 'require', imports: []}); }
    for (const value of Object.values(node)) if (Array.isArray(value)) value.forEach(child => child?.type && visit(child)); else if (value?.type) visit(value);
  };
  visit(ast); return found;
}
// prettier-ignore
function resolveRegistryModule(/** @type {string} */ specifier, /** @type {string} */ parentPath, commonJs = false) {
  if (isBuiltin(specifier) || specifier.startsWith('node:')) return null;
  let resolved;
  try {
    const resolver = createJiti(parentPath, {extensions: THEME_MODULE_EXTENSIONS});
    if (commonJs) resolved = resolver.resolve(specifier);
    else if (specifier.startsWith('.')) resolved = fileURLToPath(new URL(specifier, pathToFileURL(parentPath)));
    else if (path.isAbsolute(specifier)) resolved = specifier;
    else { const url = resolver.esmResolve(specifier); resolved = url.startsWith('file:') ? fileURLToPath(url) : url; }
  } catch (error) { throw registryGraphError(`Cannot resolve registry import "${specifier}" from ${parentPath}: ${error instanceof Error ? error.message : String(error)}`); }
  if (!fs.existsSync(resolved) || !fs.statSync(resolved).isFile()) throw registryGraphError(`Cannot resolve registry import "${specifier}" from ${parentPath}.`);
  return fs.realpathSync(resolved);
}
/** @returns {boolean | null} */
// prettier-ignore
function hasNamedExport(/** @type {string} */ file, /** @type {string} */ name, seen = new Set()) {
  const key = `${file}\0${name}`; if (seen.has(key)) return false; seen.add(key);
  const ast = parseRegistryModule(fs.readFileSync(file, 'utf8'), file); let esm = false; let unknown = false;
  for (const node of /** @type {any[]} */ (ast.program.body)) {
    if (node.type === 'ExportDefaultDeclaration') { esm = true; if (name === 'default') return true; }
    if (node.type === 'ExportNamedDeclaration') {
      esm = true; const declaration = /** @type {any} */ (node.declaration);
      if ((declaration?.id?.name === name) || (declaration?.type === 'VariableDeclaration' && declaration.declarations.some((/** @type {any} */ item) => item.id?.name === name))) return true;
      for (const specifier of /** @type {any[]} */ (node.specifiers)) if ((specifier.exported?.name ?? specifier.exported?.value) === name) {
        if (!node.source || specifier.type === 'ExportNamespaceSpecifier') return true;
        const target = resolveRegistryModule(node.source.value, file); return target ? hasNamedExport(target, specifier.local?.name ?? specifier.local?.value, seen) : false;
      }
    }
    if (node.type === 'ExportAllDeclaration') { esm = true; const target = resolveRegistryModule(node.source.value, file); const status = target ? hasNamedExport(target, name, seen) : false; if (status === true) return true; if (status === null) unknown = true; }
  }
  return esm ? unknown ? null : false : null;
}
// prettier-ignore
async function validateRegistryGraphs(/** @type {Array<{specifier: string, exportName: string}>} */ registries, /** @type {string} */ aggregatePath) {
  /** @type {Array<{specifier: string, parent: string, commonJs: boolean, imports: string[], root?: {exportName: string}}>} */ const pending = registries.map(root => ({specifier: root.specifier, parent: aggregatePath, commonJs: false, imports: [root.exportName], root}));
  /** @type {Array<{file: string, exportName: string}>} */ const runtimeChecks = []; const seen = new Set();
  while (pending.length > 0) {
    const current = pending.pop(); if (!current) break; const {specifier, parent, commonJs, imports, root} = current;
    if (/\.css(?:$|[?#])/i.test(specifier)) throw registryGraphError(`Theme family registry graph imports CSS: ${specifier}`);
    const file = resolveRegistryModule(specifier, parent, commonJs); if (!file) continue;
    if (/\.css$/i.test(file)) throw registryGraphError(`Theme family registry graph imports CSS: ${file}`);
    const external = file.split(path.sep).includes('node_modules');
    for (const name of imports) if (external) runtimeChecks.push({file, exportName: name}); else { const named = hasNamedExport(file, name); if (named === false) throw registryGraphError(`Family registry ${file} does not export "${name}".`); if (named === null) runtimeChecks.push({file, exportName: name}); }
    if (root) runtimeChecks.push({file, exportName: root.exportName});
    if (seen.has(file)) continue; seen.add(file);
    if (/\.[cm]?[jt]sx?$/i.test(file)) for (const edge of moduleDependencies(fs.readFileSync(file, 'utf8'), file)) pending.push({...edge, parent: file});
  }
  for (const [index, root] of runtimeChecks.entries()) {
    let exports; try { exports = await import(`${pathToFileURL(root.file).href}?astryx-family-check=${Date.now()}-${index}`); }
    catch (error) { throw registryGraphError(`Cannot import family registry ${root.file}: ${error instanceof Error ? error.message : String(error)}`); }
    if (!(root.exportName in exports)) throw registryGraphError(`Family registry ${root.file} does not export "${root.exportName}".`);
  }
}
/**
 * Resolve inherited source with exactly the loader's extension precedence.
 * This reads module locations only; icon discovery never executes a second load.
 * @param {string} specifier
 * @param {string} fromFile
 * @returns {string}
 */
function resolveThemeModule(specifier, fromFile) {
  return createJiti(fromFile, {extensions: THEME_MODULE_EXTENSIONS}).resolve(
    specifier,
  );
}

/**
 * Errors that mean "the synchronous loader cannot evaluate this module", as
 * opposed to "this module is broken". Only the former may fall back to the
 * async path: a genuine author error (a throw, a missing import, a real syntax
 * error) must surface as itself, and must never be quietly downgraded into a
 * load whose interception no longer reaches installed packages.
 *
 * Top-level await is the case that exists in practice — the sync path compiles
 * the module as a CommonJS function body, where `await` is a SyntaxError with
 * this exact V8 wording.
 *
 * @param {unknown} error
 * @returns {boolean}
 */
function isSyncLoaderLimitation(error) {
  if (!(error instanceof SyntaxError)) return false;
  return /await is only valid in async function/i.test(error.message);
}

/**
 * Import a theme module using jiti and find the defineTheme() result.
 * Returns the resolved DefinedTheme object, plus whether interception was
 * degraded on the way.
 *
 * When `interception` is given, the theme file — and everything it imports, at
 * any depth — is handed that wrapped core instead of resolving its own, so
 * each theme defined anywhere in the graph is associated with the raw input it
 * came from. That is the only way to see an `adaptations` block an older core
 * erases while resolving. It costs no extra execution: the theme is loaded
 * exactly once, on whichever path succeeds.
 *
 * Interception forces jiti's SYNCHRONOUS path. jiti only hands a module's
 * imports back to itself when it transpiles that module, and it skips
 * transpiling an ESM file under `import()` — so an installed package whose
 * SOURCE calls `defineTheme` would resolve its own real core and erase the
 * author's adaptations unobserved. The sync path transpiles it, so the wrapped
 * core reaches inside installed packages too.
 *
 * A module the sync path cannot evaluate (top-level await) is force-transpiled
 * through jiti's asynchronous evaluator. That keeps interception active for
 * the entry and captures its exact `extends` value; relative dependencies may
 * use native ESM, so family mode binds those objects back to the exact selected
 * source export and old-Core adaptation checks keep treating that path as
 * degraded/fail-closed.
 *
 * @param {string} filePath
 * @param {import('./core-interception.mjs').CoreInterception} [interception]
 * @returns {Promise<{theme: any, exportName: string, degraded: {topLevelAwait: boolean, commonJs: boolean}}>}
 */
// prettier-ignore
async function importThemeModule(filePath, interception, /** @type {any} */ loader = undefined) {
  const jiti =
    loader ??
    createJiti(import.meta.url, {
      moduleCache: false,
      jsx: true,
      extensions: THEME_MODULE_EXTENSIONS,
      ...(interception ? {virtualModules: interception.modules} : {}),
    });

  /** @type {any} */
  let mod;
  const degraded = {topLevelAwait: false, commonJs: false};
  if (interception) {
    // The CommonJS patch covers `.cjs` package source, which jiti always
    // loads natively; the sync path covers everything else inside packages.
    // A frozen require(esm) namespace cannot be patched, so retain that gap and
    // let the selected lineage decide whether it matters.
    const commonJsPatch = interception.patchCommonJs(filePath);
    try {
      try {
        mod = jiti(filePath);
      } catch (error) {
        // Only a sync-loader limitation may fall back. Anything else is the
        // theme's own failure and belongs to the caller unchanged.
        if (!isSyncLoaderLimitation(error)) throw error;
        degraded.topLevelAwait = true;
        // Force asynchronous transformation instead of native import: this
        // keeps virtual Core interception active even when the module uses
        // top-level await.
        mod = await jiti.evalModule(fs.readFileSync(filePath, 'utf8'), {
          id: filePath,
          filename: filePath,
          ext: path.extname(filePath),
          cache: jiti.cache,
          async: true,
          forceTranspile: true,
        });
      }
    } finally {
      // Read after the load: the root is wrapped when the load requires it.
      degraded.commonJs = !commonJsPatch.covered;
      commonJsPatch.undo();
    }
  } else {
    mod = await jiti.import(filePath);
  }

  // Both loads hand back the module. The theme is read from the module's own
  // exports, never from the module object itself: jiti's interop answers a
  // property the module lacks from its default export (and a missing
  // `default` with the module), so the module can pass for the theme while
  // its own keys hide the theme's fields.
  const isModule = mod != null && typeof mod === 'object';
  const hasDefault = isModule && Object.hasOwn(mod, 'default');
  const defaultExport = hasDefault ? mod.default : undefined;
  if (isThemeObject(defaultExport)) {
    return {theme: defaultExport, exportName: 'default', degraded};
  }
  if (isModule) {
    for (const [exportName, value] of Object.entries(mod)) {
      if (exportName === 'default' || exportName === 'module.exports') continue;
      if (isThemeObject(value)) return {theme: value, exportName, degraded};
    }
  }
  // A plain-object default export is the module's theme even when it has
  // no tokens of its own (local tokens, typography or component styles may
  // be all it defines), or no name: the build's validation says what it
  // lacks.
  if (isPlainObject(defaultExport)) {
    return {theme: defaultExport, exportName: 'default', degraded};
  }
  // A CommonJS module whose exports are the theme (`module.exports =
  // theme`) has no default of its own: interop answers `default` with
  // those exports, and without interop (a family build's loader) the module
  // is them.
  if (isModule && !hasDefault) {
    const exportsObject = mod.default ?? mod;
    if (isThemeObject(exportsObject)) {
      return {theme: exportsObject, exportName: 'default', degraded};
    }
  }

  throw new Error(
    `Could not find a defineTheme() result in ${filePath}.\n` +
      `Expected an export like: export const myTheme = defineTheme({ name: '...', tokens: {...} })`,
  );
}

/**
 * Whether the theme file's own folder resolves Core's theme entry, as the
 * theme's own `import ... from '@astryxdesign/core/theme'` would. A theme
 * outside any project (an empty folder, a fresh clone) does not, and is
 * handed the Core the CLI answers with instead, as a new project with that
 * Core would build it (`theme build` runs the same outside a project, spec
 * AST-081 FR3). Only a Core not installed there (MODULE_NOT_FOUND) reads as
 * no: an installed Core whose entry does not resolve is the theme's own, and
 * its load reports that.
 * @param {string} filePath
 * @returns {boolean}
 */
function themeFolderResolvesCore(filePath) {
  try {
    createRequire(filePath).resolve('@astryxdesign/core/theme');
    return true;
  } catch (error) {
    const {code} = /** @type {NodeJS.ErrnoException} */ (error);
    if (code === 'MODULE_NOT_FOUND') return false;
    if (code === 'ERR_PACKAGE_PATH_NOT_EXPORTED') return true;
    throw error;
  }
}

/**
 * A plain object, not an array or a module namespace: a theme module's
 * default export, read as its theme.
 * @param {any} value
 * @returns {boolean}
 */
function isPlainObject(value) {
  return (
    value != null &&
    typeof value === 'object' &&
    !Array.isArray(value) &&
    value[Symbol.toStringTag] !== 'Module'
  );
}

/**
 * @param {any} value
 * @returns {boolean}
 */
function isThemeObject(value) {
  return (
    value &&
    typeof value === 'object' &&
    typeof value.name === 'string' &&
    value.tokens &&
    typeof value.tokens === 'object'
  );
}

/**
 * Extract the theme definition from a JS/TS file, through jiti (full TS
 * support). A module that does not load fails with its own error: the theme
 * is never read from the file's text instead.
 *
 * @param {string} filePath
 * @param {import('./core-interception.mjs').CoreInterception} [interception]
 * @returns {Promise<{theme: any, exportName?: string, degraded: {topLevelAwait: boolean, commonJs: boolean}}>}
 */
// prettier-ignore
async function extractThemeDefinition(filePath, interception, /** @type {any} */ loader = undefined) {
  try {
    return await importThemeModule(filePath, interception, loader);
  } catch (jitiError) {
    const je = /** @type {Error} */ (jitiError);
    throw new Error(
      `Failed to load theme from ${filePath}: ${je.message}\n` +
        `Make sure all imports in the theme file are resolvable.`,
      {cause: jitiError},
    );
  }
}

/**
 * Load one theme through the build's real module loader and validate the raw
 * input captured from its defineTheme lineage. Used by doctor so it applies the
 * same direct-input rule as theme build without mistaking compiler output for
 * authored input.
 *
 * @param {string} file
 * @param {{cwd?: string}} [ctx]
 * @returns {Promise<string[]>}
 */
export async function validateThemePrivateInputs(
  file,
  {cwd = process.cwd()} = {},
) {
  const filePath = path.resolve(cwd, file);
  if (!fs.existsSync(filePath)) {
    throw new AstryxError(
      `File not found: ${filePath}`,
      undefined,
      ERROR_CODES.ERR_FILE_NOT_FOUND,
    );
  }

  // The CLI's own Core, unless a build in this process already chose one.
  await loadCliCore();
  const interception = interceptCore(_coreThemeModule, _coreRootModule);
  let theme;
  try {
    theme = (await extractThemeDefinition(filePath, interception)).theme;
  } catch (error) {
    const message = error instanceof Error ? error.message : String(error);
    throw new AstryxError(message, undefined, ERROR_CODES.ERR_THEME_LOAD);
  }

  const inputs = interception.lineageOf(theme);
  try {
    return [...new Set(inputs.flatMap(input => validatePrivateVars(input)))];
  } finally {
    interception.strip(theme);
  }
}

/**
 * Extract a family member's named registry import from its source file.
 * Returns { importPath, exportName } or null when the theme names none.
 * Standalone builds resolve icons through `resolveIconImports` instead.
 *
 * Looks for patterns like:
 *   import { defaultIconRegistry } from './icons';
 *   icons: defaultIconRegistry,
 * @param {string} filePath
 * @param {'icons' | 'indicators' | 'componentIcons'} field
 * @returns {{exportName: string, importPath: string} | null}
 */
function extractRegistryInfo(filePath, field) {
  const content = fs.readFileSync(filePath, 'utf8');
  const defineIndex = content.indexOf('defineTheme(');
  if (defineIndex < 0) return null;
  const themeSource = content.slice(defineIndex);
  const explicit = themeSource.match(
    new RegExp(`${field}:\\s*([a-zA-Z_][a-zA-Z0-9_]*)\\s*(?=[,}])`),
  );
  const shorthand = themeSource.match(
    new RegExp(`[,{]\\s*(${field})\\s*(?=[,}])`),
  );
  const varName = explicit?.[1] ?? shorthand?.[1];
  if (!varName) return null;
  for (const match of content.matchAll(
    /import\s*{([^}]*)}\s*from\s*['"]([^'"]+)['"]/g,
  )) {
    for (const specifier of match[1].split(',')) {
      const [exportName, localName = exportName] = specifier
        .trim()
        .split(/\s+as\s+/);
      if (localName === varName) {
        return {exportName, importPath: match[2]};
      }
    }
  }
  return null;
}

/**
 * Whether a theme's icon entries include a function of `{size, variant}`.
 * @param {Record<string, unknown> | null | undefined} entries
 * @returns {boolean}
 */
function hasFunctionIconEntry(entries) {
  return Object.values(entries ?? {}).some(
    entry => typeof entry === 'function',
  );
}

/**
 * A built theme's icon entries: a theme from defineTheme keeps them in
 * `__icons` when any is a function (its `icons` is the node view); otherwise
 * `icons` holds them.
 * @param {any} theme
 * @returns {Record<string, unknown> | undefined}
 */
function themeIconEntries(theme) {
  return theme?.__icons ?? theme?.icons;
}

/**
 * The generated code that reads a registry's entries as React nodes, each
 * function entry read at `{size: 'md'}` like core's public reads. It never
 * passes the registry to a call, so a theme extending the built module can
 * still trace the registry through its `__icons` field, and it reads no
 * global, which a registry import could shadow. The registry expression runs
 * where only `entriesName` and `nodesName` are declared, both names the
 * registry imports cannot use.
 * @param {string} entries - Expression for the registry's entries.
 * @param {string} entriesName - A reserved local name.
 * @param {string} nodesName - A reserved local name.
 * @returns {string}
 */
function iconNodesExpression(entries, entriesName, nodesName) {
  return `(() => {
  const ${entriesName} = ${entries};
  const ${nodesName} = {};
  for (const name in ${entriesName}) {
    const entry = ${entriesName}[name];
    ${nodesName}[name] = typeof entry === 'function' ? entry({size: 'md'}) : entry;
  }
  return ${nodesName};
})()`;
}

/**
 * A theme's component icon slot values: a theme from defineTheme keeps them
 * in `__componentIcons` when any is a function (its `componentIcons` is the
 * static view); otherwise `componentIcons` holds them.
 * @param {any} theme
 * @returns {Record<string, unknown> | undefined}
 */
function themeComponentIcons(theme) {
  return theme?.__componentIcons ?? theme?.componentIcons;
}

/**
 * The generated function that merges a theme's own slot values over its
 * base's, as `defineTheme` does: an own slot replaces the inherited one whole,
 * and an `undefined` own slot leaves it in place. It reads no global.
 * @param {string} name - A reserved function name.
 * @returns {string}
 */
function componentIconMergeFunction(name) {
  return `function ${name}(base, own) {
  const merged = {...base};
  for (const slot in own) {
    if (own[slot] !== undefined) merged[slot] = own[slot];
  }
  return merged;
}
`;
}

/**
 * The generated code that reads the static view of a theme's slot values:
 * every slot without a function. Like the icon node view, it reads no global
 * and declares only reserved local names.
 * @param {string} valuesName - A reserved local name bound to the values.
 * @param {string} viewName - A reserved local name.
 * @returns {string}
 */
function componentIconViewExpression(valuesName, viewName) {
  return `(() => {
  const ${viewName} = {};
  for (const slot in ${valuesName}) {
    const value = ${valuesName}[slot];
    if (value !== undefined && typeof value !== 'function') ${viewName}[slot] = value;
  }
  return ${viewName};
})()`;
}

/**
 * One import statement for a carried registry or slot binding. Ordinary named
 * imports stay byte-compatible; paths with quotes or escapes are encoded, and
 * default, namespace, and aliased bindings are kept.
 * @param {{importPath: string, importedName: string, localName: string}} binding
 * @param {string} [specifier] - Replaces the import path when given.
 * @returns {string}
 */
function importStatement({importPath, importedName, localName}, specifier) {
  const source =
    specifier !== undefined
      ? JSON.stringify(specifier)
      : /['\\\r\n]/u.test(importPath)
        ? JSON.stringify(importPath)
        : `'${importPath}'`;
  const imported = /^[$\p{ID_Start}][$\u200c\u200d\p{ID_Continue}]*$/u.test(
    importedName,
  )
    ? importedName
    : JSON.stringify(importedName);
  const binding =
    importedName === 'default'
      ? localName
      : importedName === '*'
        ? `* as ${localName}`
        : `{ ${imported}${importedName === localName ? '' : ` as ${localName}`} }`;
  return `import ${binding} from ${source};\n`;
}

/**
 * Generate a minimal JS module for a built theme.
 * 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. `resolveIconImports` reads actual
 * imports from the selected theme's source, where extensionless `./icons` uses
 * the TypeScript resolver — but the artifact here is ESM JavaScript, which
 * requires a fully specified path. Only the caller knows what its own build
 * will emit and under what name, so `iconsSpecifier` lets it say. When it is
 * not given, direct registry specifiers are preserved, and inherited relative
 * imports are rebased from the base module to the theme entry's directory.
 *
 * When an icon entry is a function of `{size, variant}`, the module keeps the
 * registry as `__icons`, which `Icon` resolves at the size and variant it
 * renders, and the theme's `icons` and the re-exported registry are the node
 * view, each function read at `{size: 'md'}` as `DefinedTheme['icons']` is.
 *
 * Component icon slots without a function are written as JSON. When a slot
 * value is a function, the module keeps the values, carried through
 * `componentIconInfo`'s imports, as `__componentIcons`, and the theme's
 * `componentIcons` is the static view, as `DefinedTheme['componentIcons']` is.
 *
 * @param {any} themeDef
 * @param {import('./icon-imports.mjs').IconImports | null} iconInfo
 * @param {string} [iconsSpecifier] - Overrides the selected registry specifier.
 * @param {{themeBinding?: string, iconsExpression?: string, indicatorsExpression?: string, artifactBaseName?: string, exportIcons?: boolean, componentIconInfo?: {imports: import('./icon-imports.mjs').IconImports['imports'], expression: string, mergeName?: string} | null}} [moduleOptions]
 * @returns {string}
 */
function generateBuiltModule(
  themeDef,
  iconInfo,
  iconsSpecifier,
  moduleOptions = {},
) {
  const themeBinding =
    moduleOptions.themeBinding ?? `${toIdentifier(themeDef.name)}Theme`;
  const artifactBaseName = moduleOptions.artifactBaseName ?? themeDef.name;
  const exportIcons = moduleOptions.exportIcons ?? true;
  const iconImport = (iconInfo?.imports ?? [])
    .map(binding =>
      importStatement(
        binding,
        iconsSpecifier !== undefined &&
          binding.importPath === iconInfo?.iconsSpecifierImportPath &&
          binding.localName === iconInfo?.iconsSpecifierLocalName
          ? iconsSpecifier
          : undefined,
      ),
    )
    .join('');
  const iconDeclaration =
    iconInfo && iconInfo.expression !== iconInfo.exportName
      ? `const ${iconInfo.exportName} = ${iconInfo.expression};\n`
      : '';
  const iconsExpression = moduleOptions.iconsExpression ?? iconInfo?.exportName;
  const iconNodes =
    iconsExpression && hasFunctionIconEntry(themeIconEntries(themeDef))
      ? `${themeBinding}IconNodes`
      : null;
  const iconNodesDeclaration =
    iconNodes && iconsExpression
      ? `const ${iconNodes} = ${iconNodesExpression(iconsExpression, `${themeBinding}IconEntries`, iconNodes)};\n`
      : '';
  const iconsField = iconNodes
    ? `  icons: ${iconNodes},\n  __icons: ${iconsExpression},`
    : iconsExpression
      ? `  icons: ${iconsExpression},`
      : '';
  const indicatorsField = moduleOptions.indicatorsExpression
    ? `\n  indicators: ${moduleOptions.indicatorsExpression},`
    : '';
  const iconReExport =
    iconInfo && exportIcons
      ? iconNodes
        ? `\nexport { ${iconNodes} as ${iconInfo.exportName} };\n`
        : `\nexport { ${iconInfo.exportName} };\n`
      : '';

  const componentIconValues = themeComponentIcons(themeDef);
  const componentIconInfo = moduleOptions.componentIconInfo ?? null;
  const carriesSlotFunctions = hasFunctionIconEntry(componentIconValues);
  if (carriesSlotFunctions && !componentIconInfo) {
    throw new AstryxError(
      `Theme "${themeDef.name}" has componentIcons slot functions that the build cannot carry. ` +
        'Import the slot functions from their own module into the theme file.',
      undefined,
      ERROR_CODES.ERR_THEME_INVALID,
    );
  }
  const componentIconValuesName = `${themeBinding}ComponentIconValues`;
  const componentIconPrelude =
    carriesSlotFunctions && componentIconInfo
      ? componentIconInfo.imports
          .map(binding => importStatement(binding))
          .join('') +
        (componentIconInfo.mergeName
          ? componentIconMergeFunction(componentIconInfo.mergeName)
          : '') +
        `const ${componentIconValuesName} = ${componentIconInfo.expression};\n`
      : '';

  // Resolve token values — tuples become light-dark() strings
  /** @type {Record<string, unknown>} */
  const resolvedTokens = {};
  if (themeDef.tokens) {
    for (const [key, value] of Object.entries(themeDef.tokens)) {
      resolvedTokens[key] = resolveTokenValue(value);
    }
  }

  const tokensStr = JSON.stringify(resolvedTokens, null, 2)
    .split('\n')
    .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
   * @param {boolean} [includeEmpty]
   * @returns {string}
   */
  const serializeField = (field, value, includeEmpty = false) => {
    if (value == null || (!includeEmpty && 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`;
  };

  // Everything a theme that `extends` this built one has to be able to read
  // back. A field missing here is silently lost by the extending theme.
  // SYNC: packages/core/src/theme/defineTheme.ts (DefinedTheme)
  const inheritableFields =
    (themeDef.__localTokenLineage !== undefined
      ? `  localTokens: ${JSON.stringify(themeDef.localTokens ?? {}, null, 2)
          .split('\n')
          .map((line, i) => (i === 0 ? line : '  ' + line))
          .join('\n')},\n` +
        `  __localTokenOwners: ${JSON.stringify(
          themeDef.__localTokenOwners ?? {},
          null,
          2,
        )
          .split('\n')
          .map((line, i) => (i === 0 ? line : '  ' + line))
          .join('\n')},\n` +
        `  __localTokenLineage: ${JSON.stringify(themeDef.__localTokenLineage)},\n`
      : '') +
    serializeField('components', themeDef.components) +
    serializeField('__onDark', themeDef.__onDark) +
    serializeField('__onLight', themeDef.__onLight) +
    serializeField('__adaptations', themeDef.__adaptations) +
    serializeField('__axes', themeDef.__axes ?? {}, true) +
    // An explicit empty list replaces an inherited one, so keep `[]`.
    serializeField('iconVariants', themeDef.iconVariants, true) +
    // Each inherited function entry keeps its defining theme's list. JSON
    // drops `undefined`, so a defining theme with no list is written as `[]`,
    // which no variant matches either.
    serializeField(
      '__iconEntryVariants',
      themeDef.__iconEntryVariants &&
        Object.fromEntries(
          Object.entries(themeDef.__iconEntryVariants).map(([name, list]) => [
            name,
            list ?? [],
          ]),
        ),
    ) +
    (carriesSlotFunctions
      ? `  componentIcons: ${componentIconViewExpression(
          componentIconValuesName,
          `${themeBinding}ComponentIconView`,
        )
          .split('\n')
          .map((line, i) => (i === 0 ? line : '  ' + line))
          .join('\n')},\n  __componentIcons: ${componentIconValuesName},\n`
      : serializeField('componentIcons', componentIconValues, true));

  return `${iconImport}${componentIconPrelude}${iconDeclaration}${iconNodesDeclaration}/**
 * ${themeDef.name} theme — built by \`${getCliInvocation()} theme build\`
 * Import the CSS file alongside this module:
 *
 *   import { ${themeBinding} } from './${artifactBaseName}';
 *   import './${artifactBaseName}.css';
 */
export const ${themeBinding} = {
  name: '${themeDef.name}',
  __built: true,
  tokens: ${tokensStr},
${inheritableFields}${iconsField}${indicatorsField}
};
${iconReExport}`;
}

/**
 * Generate TypeScript declarations for a built theme module.
 * @param {any} themeDef
 * @param {{exportName: string} | null} iconInfo - The re-exported registry, if any.
 * @param {string | null} variantsFileName
 * @param {{themeBinding?: string, includeIconExport?: boolean, includeThemeImport?: boolean}} [typeOptions]
 * @returns {string}
 */
function generateBuiltTypes(
  themeDef,
  iconInfo,
  variantsFileName,
  typeOptions = {},
) {
  const themeBinding =
    typeOptions.themeBinding ?? `${toIdentifier(themeDef.name)}Theme`;
  const iconType =
    iconInfo && (typeOptions.includeIconExport ?? true)
      ? `import type { IconRegistry } from '@astryxdesign/core/Icon';
export declare const ${iconInfo.exportName}: IconRegistry;
`
      : '';
  // Pull in the generated custom-variant augmentations so that importing the
  // theme's types also loads the module augmentations (otherwise the
  // `.variants.d.ts` is emitted but never referenced, and the custom variants
  // never widen the component prop unions for consumers).
  const variantsRef = variantsFileName
    ? `/// <reference path="./${variantsFileName}" />
`
    : '';
  const themeImport =
    (typeOptions.includeThemeImport ?? true)
      ? `import type { DefinedTheme } from '@astryxdesign/core/theme';\n`
      : '';
  return `${variantsRef}${themeImport}${iconType}export declare const ${themeBinding}: ${builtThemeType(themeDef)};\n`;
}

/**
 * A TypeScript string literal type for `value`.
 * @param {string} value
 * @returns {string}
 */
function tsStringLiteral(value) {
  const inner = JSON.stringify(value)
    .slice(1, -1)
    .replace(/\\"/g, '"')
    .replace(/'/g, "\\'");
  return `'${inner}'`;
}

/**
 * The declared type of a built theme. A theme that lists icon variants
 * carries core's type-only `__iconVariant` marker with those names, so a theme
 * that extends the built one types its icon entries' `variant` by the list,
 * exactly as it would extending the source theme.
 * SYNC: packages/core/src/theme/defineTheme.ts (ResolvedDefinedTheme)
 * @param {any} themeDef
 * @returns {string}
 */
function builtThemeType(themeDef) {
  const names = themeDef.iconVariants;
  if (!Array.isArray(names)) return 'DefinedTheme';
  const variant =
    names.length > 0
      ? [...new Set(names)].map(tsStringLiteral).join(' | ')
      : 'never';
  return `DefinedTheme & { __iconVariant?(variant: ${variant}): void }`;
}

// =============================================================================
// Component validation
// =============================================================================

/**
 * Load known theme target keys from core component docs: the visual props AND
 * runtime states each target reflects. Returns null when docs are unavailable so
 * validation skips warnings rather than guessing from a second registry.
 *
 * @returns {Promise<{propsByKey: Record<string, string[]>} | null>}
 */
async function loadKnownComponents() {
  const coreRoot = resolveCoreRoot();
  const coreSrc = coreRoot ? path.join(coreRoot, 'src') : null;
  if (!coreSrc || !fs.existsSync(coreSrc)) return null;

  const propsByKey = targetsByKey(await collectThemingTargets(coreSrc));
  return Object.keys(propsByKey).length > 0 ? {propsByKey} : null;
}

/** @type {{propsByKey: Record<string, string[]>} | null | undefined} */
let knownComponentsCache;

/**
 * @returns {Promise<{propsByKey: Record<string, string[]>} | null>}
 */
async function getKnownComponents() {
  if (knownComponentsCache === undefined) {
    knownComponentsCache = await loadKnownComponents();
  }
  return knownComponentsCache;
}

/**
 * Validate component overrides against one discovered target registry.
 *
 * @param {{components?: Record<string, Record<string, unknown>>, onDark?: {components?: Record<string, Record<string, unknown>>}, onLight?: {components?: Record<string, Record<string, unknown>>}, __onDark?: {components?: Record<string, Record<string, unknown>>}, __onLight?: {components?: Record<string, Record<string, unknown>>}}} themeDef
 * @param {{propsByKey: Record<string, string[]>}} knownComponents
 * @returns {string[]}
 */
export function validateComponentOverridesAgainstRegistry(
  themeDef,
  knownComponents,
) {
  /** @type {string[]} */
  const warnings = [];
  /** @type {{name: string, components: Record<string, Record<string, unknown>>}[]} */
  const layers = [...getThemeComponentLayers(themeDef)];
  let adaptationIndex = 0;
  for (const value of adaptationRuleValues(themeDef)) {
    adaptationIndex++;
    if (
      value.components &&
      typeof value.components === 'object' &&
      Object.keys(value.components).length > 0
    ) {
      layers.push({
        name: `adaptation rule ${adaptationIndex}`,
        components: value.components,
      });
    }
  }

  for (const {components} of layers) {
    for (const [component, rules] of Object.entries(components)) {
      if (!(component in knownComponents.propsByKey)) {
        const similar = Object.keys(knownComponents.propsByKey)
          .filter(k => {
            if (k.includes(component) || component.includes(k)) return true;
            if (Math.abs(k.length - component.length) <= 2) {
              let diff = 0;
              const longer = k.length >= component.length ? k : component;
              const shorter = k.length < component.length ? k : component;
              let j = 0;
              for (let i = 0; i < longer.length && diff <= 2; i++) {
                if (longer[i] !== shorter[j]) diff++;
                else j++;
              }
              diff += shorter.length - j;
              return diff <= 2;
            }
            return false;
          })
          .slice(0, 3);
        const hint =
          similar.length > 0 ? ` Did you mean: ${similar.join(', ')}?` : '';
        warnings.push(`Unknown component "${component}".${hint}`);
        continue;
      }

      const knownProps = knownComponents.propsByKey[component];
      for (const key of Object.keys(rules)) {
        if (key === 'base') continue;

        const pairs = key.split('+');
        for (const pair of pairs) {
          const [prop] = pair.split(':');
          if (prop && !knownProps.includes(prop)) {
            const hint =
              knownProps.length > 0
                ? ` Known props/states: ${knownProps.join(', ')}`
                : ' This component has no variant props or states.';
            warnings.push(
              `Unknown prop "${prop}" on component "${component}".${hint}`,
            );
          }
        }
      }
    }
  }

  return [...new Set(warnings)];
}

/**
 * Validate component overrides in a theme definition.
 * Warns on unknown component and prop names.
 *
 * @param {{components?: Record<string, Record<string, unknown>>, onDark?: {components?: Record<string, Record<string, unknown>>}, onLight?: {components?: Record<string, Record<string, unknown>>}, __onDark?: {components?: Record<string, Record<string, unknown>>}, __onLight?: {components?: Record<string, Record<string, unknown>>}}} themeDef
 * @returns {Promise<string[]>}
 */
async function validateComponentOverrides(themeDef) {
  const knownComponents = await getKnownComponents();
  return knownComponents == null
    ? []
    : validateComponentOverridesAgainstRegistry(themeDef, knownComponents);
}

const BUILTIN_HEADING_TYPES = new Set(['display-1', 'display-2', 'display-3']);

/**
 * Return every component-rule layer that can emit CSS for a theme. Raw theme
 * input stores media-surface overrides in `onDark`/`onLight`; a theme already
 * resolved by defineTheme stores them in `__onDark`/`__onLight` instead.
 *
 * @param {{components?: Record<string, Record<string, unknown>>, onDark?: {components?: Record<string, Record<string, unknown>>}, onLight?: {components?: Record<string, Record<string, unknown>>}, __onDark?: {components?: Record<string, Record<string, unknown>>}, __onLight?: {components?: Record<string, Record<string, unknown>>}}} themeDef
 * @returns {{name: 'base'|'onDark'|'onLight', components: Record<string, Record<string, unknown>>}[]}
 */
function getThemeComponentLayers(themeDef) {
  /** @type {{name: 'base'|'onDark'|'onLight', components: Record<string, Record<string, unknown>>}[]} */
  const layers = [];
  /**
   * @param {'base'|'onDark'|'onLight'} name
   * @param {{components?: Record<string, Record<string, unknown>>}|undefined} surface
   */
  const addLayer = (name, surface) => {
    if (
      surface?.components &&
      typeof surface.components === 'object' &&
      Object.keys(surface.components).length > 0
    ) {
      layers.push({name, components: surface.components});
    }
  };

  addLayer('base', themeDef);
  addLayer('onDark', themeDef.__onDark ?? themeDef.onDark);
  addLayer('onLight', themeDef.__onLight ?? themeDef.onLight);
  return layers;
}

/**
 * A generated type augmentation makes a custom Heading type callable with the
 * type prop, so that name needs a standalone visual rule of its own. A value
 * that appears only in a combined selector (or has an empty rule) would
 * type-check but fall back for ordinary `type="name"` use.
 *
 * @param {{components?: Record<string, Record<string, unknown>>}} themeDef
 * @returns {string[]}
 */
function validateCustomHeadingTypes(themeDef) {
  const layers = getThemeComponentLayers(themeDef);
  const customTypes = customHeadingTypes(themeDef);

  const errors = [];
  for (const type of customTypes) {
    const hasStandalone = layers.some(({components}) => {
      const headingRules = components.heading;
      if (!headingRules || typeof headingRules !== 'object') return false;
      const standalone = headingRules[`type:${type}`];
      return (
        standalone != null &&
        typeof standalone === 'object' &&
        !Array.isArray(standalone) &&
        hasUsableStyleDeclaration(standalone)
      );
    });
    if (!hasStandalone) {
      errors.push(
        `Custom Heading type "${type}" needs a non-empty standalone ` +
          `components.heading["type:${type}"], ` +
          `onDark.components.heading["type:${type}"], or ` +
          `onLight.components.heading["type:${type}"] rule.`,
      );
    }
  }
  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 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}
 */
function hasUsableStyleDeclaration(styles) {
  if (!styles || typeof styles !== 'object' || Array.isArray(styles)) {
    return false;
  }
  for (const [property, value] of Object.entries(styles)) {
    if (property.startsWith(':')) {
      if (hasUsableStyleDeclaration(value)) return true;
      continue;
    }
    if (
      value !== undefined &&
      value !== null &&
      typeof value !== 'object' &&
      String(value).trim() !== ''
    ) {
      return true;
    }
  }
  return false;
}

/**
 * Custom Heading types are only useful when the installed Core package exposes
 * the public map that the generated declaration augments. The CLI and Core
 * are optional peers and can be upgraded independently, so fail explicitly
 * instead of emitting CSS that application TypeScript cannot consume.
 *
 * @param {{components?: Record<string, Record<string, unknown>>}} themeDef
 * @returns {string[]}
 */
function validateHeadingTypeAugmentationSupport(themeDef) {
  const hasCustomType = getThemeComponentLayers(themeDef).some(
    ({components}) => {
      const headingRules = components.heading;
      return (
        headingRules &&
        typeof headingRules === 'object' &&
        Object.keys(headingRules).some(key =>
          key.split('+').some(pair => {
            const colon = pair.indexOf(':');
            return (
              colon !== -1 &&
              pair.slice(0, colon) === 'type' &&
              pair.slice(colon + 1) &&
              !BUILTIN_HEADING_TYPES.has(pair.slice(colon + 1))
            );
          }),
        )
      );
    },
  );
  if (!hasCustomType) return [];

  if (!componentHasAugmentableInterface('Heading', 'HeadingTypeMap')) {
    return [
      'Custom Heading types require an installed @astryxdesign/core that ' +
        'exports HeadingTypeMap from the public Heading subpath. Upgrade Core ' +
        'before building this theme.',
    ];
  }
  return [];
}

/**
 * Compile a defineTheme file to CSS + CSS .d.ts + JS + JS .d.ts (and an
 * optional `.variants.d.ts`). Performs the writes and returns a `theme.build` receipt,
 * or `null` when the theme produced no CSS (nothing to build). Throws
 * AstryxError (stable code) on failure. Progress is emitted through the shared
 * `logger` (silent by default).
 *
 * @param {string} file - Theme file path, resolved against `cwd`.
 * @param {{out?: string, check?: boolean, iconsSpecifier?: string, __prepareFamily?: boolean, __familyLoader?: any, __familyInterception?: any, __onPrivateVarError?: () => void, __writeRoot?: string}} [options] -
 *   `out` overrides the output CSS path; `check` compares against on-disk outputs
 *   instead of writing. `__writeRoot` replaces `cwd` as the directory every
 *   output must stay inside, for a CLI-internal scratch build. `iconsSpecifier` overrides the icon registry import
 *   specifier in the generated module (e.g. `./icons.mjs`); when omitted, the
 *   direct registry specifiers from the theme source are emitted unchanged.
 * @param {{cwd?: string, projectCore?: boolean}} [ctx] `projectCore`: only the
 *   project's installed Core (spec AST-081 FR3)
 * @returns {Promise<any>}
 */
async function themeBuildInternal(
  file,
  options = {},
  {cwd = process.cwd(), projectCore = false} = {},
  /** @type {{compact?: boolean, trailers?: ThemeBuildTrailer[]}} */ report = {},
) {
  const filePath = path.resolve(cwd, file);

  if (!fs.existsSync(filePath)) {
    throw new AstryxError(
      `File not found: ${filePath}`,
      undefined,
      ERROR_CODES.ERR_FILE_NOT_FOUND,
    );
  }

  if (!report.compact) {
    logger.log(`\nBuilding theme from ${path.relative(cwd, filePath)}...`);
  }
  // A compact report has no per-theme heading, so each warning names its file.
  const source = report.compact ? `${path.relative(cwd, filePath)}: ` : '';

  if (projectCore && !findProjectCoreDir(cwd)) {
    throw new AstryxError(
      "The project's Core isn't installed.",
      undefined,
      ERROR_CODES.ERR_CORE_NOT_FOUND,
    );
  }
  await selectCore(cwd, {projectOnly: projectCore});

  // Standalone builds need interception when an older Core could erase
  // adaptations, and when the theme's folder has no Core of its own: its
  // imports of Core are then handed the Core this build selected, as family
  // builds' are. Family preparation always supplies the same recorder as its
  // shared loader so exact authored parent identity stays CLI-private instead
  // of becoming a public DefinedTheme field.
  const interception =
    options.__familyInterception ??
    (_generateAdaptationCSS && themeFolderResolvesCore(filePath)
      ? undefined
      : interceptCore(_coreThemeModule, _coreRootModule));

  // Extract theme definition
  let themeDef;
  /** The export actually selected by the loader, not the first AST match. */
  let themeExportName;
  /** Paths through the load that interception could not fully observe. */
  let loadDegradation;
  /**
   * The theme file's bytes as loaded: read before and after the load, and the
   * registry scan below reads these rather than the file again. An editor's
   * in-place save truncates before it writes, so a later read can find an
   * empty file the load never saw; a file that changed while it loaded is not
   * built from.
   * @type {string}
   */
  let themeSource;
  try {
    const before = fs.readFileSync(filePath, 'utf8');
    const loaded = await extractThemeDefinition(
      filePath,
      interception,
      options.__familyLoader,
    );
    const after = fs.readFileSync(filePath, 'utf8');
    if (before !== after || before === '') {
      throw new Error(
        `${filePath} changed while it was loading. Build again once it is saved.`,
      );
    }
    themeSource = before;
    themeDef = loaded.theme;
    themeExportName = loaded.exportName;
    loadDegradation = loaded.degraded;
  } catch (e) {
    const err = /** @type {Error} */ (e);
    throw new AstryxError(err.message, undefined, ERROR_CODES.ERR_THEME_LOAD);
  }

  // The marker is scoped to that isolated load: drop it before the theme
  // reaches anything that reads or writes it. (Symbol keys are invisible to
  // JSON.stringify and Object.keys, so it could not reach output regardless.)
  // Both reads happen BEFORE the strip, which is what removes the evidence.
  const ancestryObserved =
    !options.__prepareFamily ||
    !interception ||
    interception.observed(themeDef) ||
    Object.hasOwn(themeDef, 'extends');
  if (options.__prepareFamily && interception) interception.retain(themeDef);
  const sourceParent =
    options.__prepareFamily && interception
      ? interception.parentOf(themeDef)
      : undefined;
  const adaptationLineage = interception
    ? interception.lineageOf(themeDef)
    : undefined;
  const capturedGenerativeAxes = interception
    ? interception.capturedAxesOf(themeDef)
    : undefined;
  const hasCoverageGap = Boolean(
    loadDegradation?.topLevelAwait || loadDegradation?.commonJs,
  );
  const unobservedLineage =
    interception && hasCoverageGap ? interception.unobservedIn(themeDef) : [];
  if (interception) interception.strip(themeDef);
  if (!ancestryObserved) {
    throw new AstryxError(
      `Theme "${themeDef.name ?? path.basename(filePath)}" exact family ancestry could not be observed during CLI loading.`,
      undefined,
      ERROR_CODES.ERR_THEME_INVALID,
    );
  }

  if (!themeDef.name) {
    throw new AstryxError(
      'Theme must have a name property.',
      undefined,
      ERROR_CODES.ERR_THEME_INVALID,
    );
  }

  // Path-safety: the theme name is used to derive output filenames
  // (e.g. `${name}.css`, `${name}.js`). Reject names containing path
  // separators or traversal markers — `../../escaped` would otherwise
  // write JS modules outside the input directory.
  try {
    sanitizeName(themeDef.name, {label: 'theme name'});
  } catch (err) {
    if (err instanceof PathSafetyError) {
      throw new AstryxError(
        err.message,
        undefined,
        ERROR_CODES.ERR_PATH_TRAVERSAL,
      );
    }
    throw err;
  }

  // A generated module must preserve the registry through an import: it may
  // contain React elements, which cannot be serialized. Validate before CSS
  // generation so neither the no-CSS return nor --check can bypass the error.
  // Family preparation keeps its own named-import registry contract, which
  // themeBuildFamily checks against the selected members' graph.
  const standaloneIcons = !options.__prepareFamily;
  // Function icon entries stay functions in the built module, beside a node
  // view bound to `<theme>IconNodes` and computed from `<theme>IconEntries`.
  const functionEntries =
    hasFunctionIconEntry(themeIconEntries(themeDef)) ||
    hasFunctionIconEntry(themeIconEntries(themeDef.extends));
  /** @param {boolean} reserveIconNodes */
  const reservedNames = reserveIconNodes => [
    `${toIdentifier(themeDef.name)}Theme`,
    ...(reserveIconNodes
      ? [
          `${toIdentifier(themeDef.name)}ThemeIconNodes`,
          `${toIdentifier(themeDef.name)}ThemeIconEntries`,
        ]
      : []),
  ];
  // Names the slot values, their static view, and their merge function take
  // in the built module.
  const componentIconNames = [
    `${toIdentifier(themeDef.name)}ThemeComponentIconValues`,
    `${toIdentifier(themeDef.name)}ThemeComponentIconView`,
    `${toIdentifier(themeDef.name)}ThemeMergeComponentIcons`,
  ];
  const iconResolution = {
    readSource: (/** @type {string} */ file) =>
      path.resolve(file) === path.resolve(filePath)
        ? themeSource
        : fs.readFileSync(file, 'utf8'),
    resolveModule: resolveThemeModule,
    reservedNames: [...reservedNames(functionEntries), ...componentIconNames],
    functionEntries,
    rawInput: 'extends' in themeDef,
    hasIcons:
      Object.keys(themeDef.icons ?? {}).length > 0 ||
      Object.keys(themeDef.extends?.icons ?? {}).length > 0,
  };
  let iconInfo = standaloneIcons
    ? await resolveIconImports(filePath, themeExportName, iconResolution)
    : null;
  /** @type {import('./icon-imports.mjs').IconImports | null} */
  let componentIconInfo = null;

  // 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(`  [warn] ${source}${w}`);
  }

  // Validate no private vars are set directly
  const privateVarErrors = validatePrivateVars(themeDef);
  for (const e of privateVarErrors) {
    warningMessages.push(e);
    logger.error(`  [error] ${source}${e}`);
  }
  if (privateVarErrors.length > 0) {
    options.__onPrivateVarError?.();
    logger.error(
      `\n  ${source}${privateVarErrors.length} private var error(s). Use standard CSS properties instead.`,
    );
  }

  const customHeadingErrors = validateCustomHeadingTypes(themeDef);
  customHeadingErrors.push(...validateHeadingTypeAugmentationSupport(themeDef));
  if (customHeadingErrors.length > 0) {
    throw new AstryxError(
      customHeadingErrors.join('\n'),
      undefined,
      ERROR_CODES.ERR_THEME_INVALID,
    );
  }

  // Generate CSS via core's shared generator — the SINGLE source of truth.
  // `astryx theme build` and the `<Theme>` runtime MUST emit identical CSS, so
  // there is exactly one generation path: @astryxdesign/core/theme. If core could not
  // be imported, fail hard rather than silently producing divergent output.
  // Only the baseline exports every theme build needs are required here;
  // capability exports are checked against what the theme actually asks for.
  if (!_defineTheme || !_generateThemeRulesSplit) {
    throw new AstryxError(
      coreUnavailableMessage(cwd, _coreImportError),
      undefined,
      ERROR_CODES.ERR_CORE_NOT_FOUND,
    );
  }

  // An adaptation theme against a core that cannot compile adaptations stops
  // here — before any CSS is generated and long before anything is written.
  // Checked against the SELECTED theme's own lineage: the raw inputs it and
  // its bases were resolved from, so an unrelated adaptive theme elsewhere in
  // the import graph cannot fail this build.
  const coreVersionForCapability = readPkgVersion(findCoreDir(cwd));
  assertAdaptationCapability(themeDef, {
    coreVersion: coreVersionForCapability,
    lineage: adaptationLineage,
    unobserved: unobservedLineage,
    degradation: loadDegradation,
  });

  let css;
  let resolvedTheme;
  let cssPlan;
  {
    // 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.
    // Fields that only ever appear on RAW defineTheme() input, never on an
    // already-resolved theme. Their presence is how the build tells the two
    // apart and decides to run defineTheme() itself. A field missing from this
    // list is dropped without a word, so every new input field belongs here.
    // SYNC: packages/core/src/theme/defineTheme.ts (DefineThemeInput)
    const INPUT_ONLY_FIELDS = [
      'extends',
      'typography',
      'motion',
      'radius',
      'color',
      'syntax',
      'onDark',
      'onLight',
      'adaptations',
    ];
    const needsResolution =
      INPUT_ONLY_FIELDS.some(field => themeDef[field] !== undefined) ||
      ('localTokens' in themeDef && themeDef.__localTokenLineage === undefined);
    if (needsResolution) {
      try {
        resolvedTheme = _defineTheme({...themeDef});
      } catch (error) {
        const message =
          error instanceof Error
            ? error.message
            : 'Theme normalization failed.';
        throw new AstryxError(
          message,
          undefined,
          ERROR_CODES.ERR_THEME_INVALID,
        );
      }
    } else {
      resolvedTheme = themeDef;
    }

    // Raw object exports can acquire icons only when Core resolves `extends`.
    // Recheck an unresolved provenance result before any generator runs.
    if (
      standaloneIcons &&
      !iconInfo &&
      Object.keys(resolvedTheme.icons ?? {}).length > 0
    ) {
      const resolvedFunctionEntries = hasFunctionIconEntry(
        themeIconEntries(resolvedTheme),
      );
      iconInfo = await resolveIconImports(filePath, themeExportName, {
        ...iconResolution,
        hasIcons: true,
        functionEntries: resolvedFunctionEntries,
        reservedNames: [
          ...reservedNames(resolvedFunctionEntries),
          ...componentIconNames,
        ],
      });
    }
    // An opaque package base can legitimately have no icons. Its .icons
    // reference is unnecessary; direct empty registry imports remain intact.
    if (
      iconInfo &&
      iconInfo.iconsSpecifierLocalName === undefined &&
      Object.keys(resolvedTheme.icons ?? {}).length === 0
    ) {
      iconInfo = null;
    }
    if (
      iconInfo &&
      options.iconsSpecifier !== undefined &&
      iconInfo.iconsSpecifierImportPath === undefined
    ) {
      throw new AstryxError(
        'The icon registry is inherited through a theme import. ' +
          'To use --icons-specifier, import the registry directly and set icons to that binding.',
        undefined,
        ERROR_CODES.ERR_THEME_INVALID,
      );
    }

    // A slot function cannot be serialized, so the module imports it from
    // where the theme source does. Static slot values are written as JSON.
    if (
      standaloneIcons &&
      hasFunctionIconEntry(themeComponentIcons(resolvedTheme))
    ) {
      componentIconInfo = await resolveIconImports(filePath, themeExportName, {
        ...iconResolution,
        field: 'componentIcons',
        mergeName: `${toIdentifier(themeDef.name)}ThemeMergeComponentIcons`,
        hasIcons: true,
        functionEntries: true,
        reservedNames: [
          ...reservedNames(true),
          ...componentIconNames,
          ...(iconInfo?.imports.map(binding => binding.localName) ?? []),
          ...(iconInfo ? [iconInfo.exportName] : []),
        ],
      });
    }

    // Cores that predate adaptations can still resolve typography, color,
    // radius, and motion into root tokens, but they do not retain the raw axis
    // inputs. Keep the effective metadata captured from the same defineTheme
    // lineage so a later current-core child can complete a partial adaptation
    // axis exactly as it would when extending the source theme.
    if (
      resolvedTheme.__axes === undefined &&
      capturedGenerativeAxes &&
      Object.keys(capturedGenerativeAxes).length > 0
    ) {
      resolvedTheme = {...resolvedTheme, __axes: capturedGenerativeAxes};
    }

    // Re-check after resolution: `extends` can pull adaptation rules in from a
    // base the entry file never mentions, and a resolver that understands them
    // surfaces them here.
    assertAdaptationCapability(resolvedTheme, {
      coreVersion: coreVersionForCapability,
      lineage: adaptationLineage,
      unobserved: unobservedLineage,
      degradation: loadDegradation,
    });

    const adaptationEnrollmentErrors =
      await validateAdaptationEnrollment(resolvedTheme);
    if (adaptationEnrollmentErrors.length > 0) {
      throw new AstryxError(
        adaptationEnrollmentErrors.join('\n'),
        undefined,
        ERROR_CODES.ERR_THEME_INVALID,
      );
    }

    const scopeSelector = themeScopeStart(themeDef.name);
    const scopeTo = THEME_SCOPE_TO;

    // 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 = [];

    let themeRules;
    try {
      themeRules = _generateThemeRulesSplit(resolvedTheme, droppedDeclarations);
    } catch (error) {
      const message =
        error instanceof Error ? error.message : 'Theme normalization failed.';
      throw new AstryxError(message, undefined, ERROR_CODES.ERR_THEME_INVALID);
    }
    const {component, prose} = themeRules;
    const cssParts = [];
    // Prose element defaults always ship — the `<Theme>` runtime
    // (generateThemeCSS) always emits them, so the build must too, or the
    // CLI output would diverge from runtime. They go in @layer reset
    // (zero-specificity :where()) so component/Markdown StyleX always wins.
    if (prose.length > 0) {
      const proseInner = prose.join('\n\n');
      cssParts.push(
        `@layer reset {\n@scope (${scopeSelector}) to (${scopeTo}) {\n${proseInner}\n}\n}`,
      );
    }
    // Ordered adaptation rules use the same generator as the runtime path.
    // An older core has no such generator; a theme that needs one never
    // reaches this line (assertAdaptationCapability above), so the empty
    // result here belongs to a theme with no adaptation rules to emit.
    let adaptationCss;
    try {
      adaptationCss = _generateAdaptationCSS
        ? _generateAdaptationCSS(resolvedTheme, droppedDeclarations)
        : {component: '', prose: ''};
    } catch (error) {
      const message =
        error instanceof Error ? error.message : 'Theme normalization failed.';
      throw new AstryxError(message, undefined, ERROR_CODES.ERR_THEME_INVALID);
    }
    const componentInner = component.join('\n\n');
    const componentScope =
      component.length > 0
        ? `@scope (${scopeSelector}) to (${scopeTo}) {\n${componentInner}\n}`
        : '';

    // #3658: also emit attribute-specific rules so <Theme mode> can override
    // color-scheme. Inspect root and rule-owned values, not generated CSS, which
    // also carries theme-independent data-token defaults with light-dark().
    const themeOwnValues = JSON.stringify([
      resolvedTheme.tokens ?? {},
      resolvedTheme.localTokens ?? {},
      resolvedTheme.components ?? {},
      ...(resolvedTheme.__adaptationRules ?? []).flatMap(
        (
          /** @type {{tokens?: Record<string, string>, localTokens?: Record<string, string>, components?: object}} */ rule,
        ) => [rule.tokens ?? {}, rule.localTokens ?? {}, rule.components ?? {}],
      ),
    ]);
    const colorSchemeDecl =
      themeOwnValues.includes('light-dark(') ||
      adaptationCss.component.includes('light-dark(')
        ? '  :root { color-scheme: light dark; }\n  html[data-theme="light"] { color-scheme: light; }\n  html[data-theme="dark"] { color-scheme: dark; }\n\n'
        : '';
    if (colorSchemeDecl || componentScope) {
      cssParts.push(
        `@layer astryx-theme {\n${colorSchemeDecl}${componentScope}\n}`,
      );
    }
    if (adaptationCss.prose) {
      cssParts.push(`@layer reset {\n${adaptationCss.prose}\n}`);
    }
    if (adaptationCss.component) {
      cssParts.push(`@layer astryx-theme {\n${adaptationCss.component}\n}`);
    }
    // Media-surface rules come last so onDark/onLight win over matching
    // adaptations on the same resolved leaf.
    let onMediaCss = '';
    if (_generateOnMediaCSS) {
      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] ${source}${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(`${source}No overrides found; nothing to build.`);
      return null;
    }
    cssParts.unshift('@layer reset, astryx-base, astryx-theme;');
    const baseCss = '';
    cssPlan = {
      base: baseCss,
      prose,
      component,
      adaptation: adaptationCss.component,
      adaptationProse: adaptationCss.prose,
      onMedia: onMediaCss,
      colorScheme: colorSchemeDecl.trimEnd(),
    };
    css = cssParts.join('\n\n') + '\n';
  }

  // Source path relative to cwd — used in @generated headers
  const sourceRelative = path.relative(cwd, filePath);
  const buildCommand = `astryx theme build ${sourceRelative}${options.out ? ' --out ' + path.relative(cwd, path.resolve(cwd, options.out)) : ''}`;
  // Stable provenance recorded in @generated headers — versions, not a
  // timestamp, so identical inputs produce byte-identical output.
  const versions = resolveToolVersions(cwd);

  // Derive the default CSS name from the theme name so .css/.js/.d.ts
  // share one scheme; an explicit --out still wins.
  const baseName = themeDef.name;
  // Every write stays inside cwd. A CLI-internal caller that renders into a
  // scratch directory it creates and removes names that directory instead.
  const writeRoot = options.__writeRoot ?? cwd;
  let outPath;
  if (options.out) {
    outPath = path.resolve(cwd, options.out);
    // A build keeps the explicit output inside the write root, relative or
    // absolute. Check mode writes nothing, so it refuses only a relative path
    // that escapes cwd.
    if (!options.check || !path.isAbsolute(options.out)) {
      confineOutput(outPath, writeRoot, OUT_REMEDY, options.out);
    }
  } else {
    outPath = path.join(path.dirname(filePath), `${baseName}.css`);
  }

  const displayTheme = resolvedTheme || themeDef;
  const tokenCount =
    Object.keys(displayTheme.tokens ?? {}).length +
    Object.keys(displayTheme.localTokens ?? {}).length;
  const componentCount = displayTheme.components
    ? Object.keys(displayTheme.components).length
    : 0;
  const size = (Buffer.byteLength(css) / 1024).toFixed(1);

  // Compute all output paths up front so we can validate them as a
  // group BEFORE writing anything. Previously the CSS would be written
  // first; if the JS write failed (e.g. ENOENT, permission), the CSS
  // was left as orphaned half-built output. Stage-then-commit avoids
  // that.
  const outDir = path.dirname(outPath);
  const cssDtsPath = `${outPath}.d.ts`;
  const jsPath = path.join(outDir, `${baseName}.js`);
  const dtsPath = path.join(outDir, `${baseName}.d.ts`);

  // Type augmentation .d.ts if theme has custom prop values. Computed
  // before the main .d.ts so the latter can reference it (see below).
  const augmentationSource = resolvedTheme || themeDef;
  const variantDecl =
    await generateVariantDeclarationsAsync(augmentationSource);
  const variantsFileName = variantDecl ? `${baseName}.variants.d.ts` : null;
  const variantDtsPath =
    variantDecl && variantsFileName
      ? path.join(outDir, variantsFileName)
      : null;
  const variantContent = variantDecl
    ? generatedHeader(sourceRelative, 'ts', buildCommand, versions) +
      variantDecl
    : null;

  // Generate all file contents in memory first. The main .d.ts references
  // the variants file (when present) via a triple-slash directive so
  // importing the theme also loads the custom-variant augmentations.
  const cssContent =
    generatedHeader(sourceRelative, 'css', buildCommand, versions) + css;
  const cssDtsContent =
    generatedHeader(sourceRelative, 'ts', buildCommand, versions) +
    'export {};\n';
  // A family member's module is generated by themeBuildFamily, which carries
  // its registries and slot functions through the family's own imports.
  const jsContent = options.__prepareFamily
    ? ''
    : generatedHeader(sourceRelative, 'js', buildCommand, versions) +
      generateBuiltModule(
        resolvedTheme || themeDef,
        iconInfo,
        options.iconsSpecifier,
        {componentIconInfo},
      );
  const dtsContent =
    generatedHeader(sourceRelative, 'ts', buildCommand, versions) +
    generateBuiltTypes(resolvedTheme || themeDef, iconInfo, variantsFileName);

  const unloadedFonts = [
    ...new Set([
      ...collectUnloadedFonts(resolvedTheme),
      ...adaptationRuleValues(resolvedTheme).flatMap(
        (/** @type {any} */ value) => collectUnloadedFonts(value),
      ),
    ]),
  ];

  if (options.__prepareFamily) {
    return {
      filePath,
      sourceRelative: sourceRelative.split(path.sep).join('/'),
      theme: displayTheme,
      sourceTheme: themeDef,
      sourceParent,
      iconInfo: extractRegistryInfo(filePath, 'icons'),
      indicatorInfo: extractRegistryInfo(filePath, 'indicators'),
      componentIconInfo: extractRegistryInfo(filePath, 'componentIcons'),
      variantDecl,
      css: cssPlan,
      versions,
      tokenCount,
      componentCount,
      warnings: warningMessages,
      unloadedFonts,
    };
  }

  const writes = [
    {dest: outPath, content: cssContent},
    {dest: cssDtsPath, content: cssDtsContent, allowMissingInCheck: true},
    {dest: jsPath, content: jsContent},
    {dest: dtsPath, content: dtsContent},
  ];
  if (variantDtsPath && variantContent) {
    writes.push({dest: variantDtsPath, content: variantContent});
  }

  // Every output a build writes stays inside cwd, including the defaults
  // beside the theme file. Check mode writes nothing, so it compares outputs
  // outside cwd read-only.
  if (!options.check) {
    confineOutputs(writes, writeRoot, options.out ? OUT_REMEDY : SOURCE_REMEDY);
  }

  // Check mode: compare generated content against what's on disk instead of
  // writing. A file is "stale" if it's missing or its content differs once the
  // volatile @generated `Command:` line is ignored. Returns a
  // receipt listing stale/missing outputs so callers (CI) can fail on drift.
  if (options.check) {
    const stale = staleBuildOutputs(writes, cwd);
    const upToDate = stale.length === 0;
    if (upToDate) {
      logger.log(`\n[ok] Theme outputs are up to date with ${sourceRelative}.`);
    } else {
      logger.error(
        `\n[fail] ${stale.length} theme output(s) are out of date with ${sourceRelative}:`,
      );
      for (const s of stale) {
        logger.error(
          `  ${s.reason === 'missing' ? 'missing' : 'stale'}: ${s.path}`,
        );
      }
      // prettier-ignore
      const remedy = outsideCheckRemedy(writes, [filePath], writeRoot, relative => [relative(filePath), ...(options.out ? ['--out', relative(outPath)] : []), ...(options.iconsSpecifier ? ['--icons-specifier', options.iconsSpecifier] : [])]);
      if (remedy) logger.error(`\n  ${remedy.join('\n  ')}`);
      else logger.error(`\n  Rebuild with: ${buildCommand}`);
    }
    return {
      type: 'theme.build.check',
      data: {
        name: themeDef.name,
        upToDate,
        stale,
        checked: checkedBuildOutputs(writes, cwd),
      },
    };
  }

  writeBuildOutputs(writes);

  if (!report.compact) {
    logger.log(`\n[ok] ${path.relative(cwd, outPath)}`);
    logger.log(`[ok] ${path.relative(cwd, cssDtsPath)}`);
    logger.log(
      `  ${tokenCount} token overrides, ${componentCount} component overrides`,
    );
    logger.log(`  ${size} KB`);
    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(
        `[ok] ${path.relative(cwd, variantDtsPath)} (${augCount} type augmentations)`,
      );
    }
  }

  const relOutDir = path.relative(cwd, outDir) || '.';
  const cssBase = path.basename(outPath, '.css');
  const jsImport = importSpecifier(relOutDir, baseName);
  const cssImport = importSpecifier(relOutDir, cssBase) + '.css';
  const exportName = `${toIdentifier(baseName)}Theme`;

  // 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).
  // 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.
  /** @type {string[]} */
  const fontNotices = [];
  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)`;
    noticeMessages.push(msg);
    fontNotices.push(msg);
  }

  /** @type {ThemeBuildTrailer} */
  const trailer = {
    themeName: themeDef.name,
    exportName,
    jsImport,
    cssImport,
    unloadedFonts,
    fontNotices,
  };
  // A batch or compact report prints this once for the whole run instead.
  if (report.trailers) report.trailers.push(trailer);
  else printBuildTrailer(trailer);

  return {
    type: 'theme.build',
    data: {
      name: themeDef.name,
      tokenCount,
      componentCount,
      sizeKB: parseFloat(size),
      outputs: {
        css: path.relative(cwd, outPath),
        cssDts: path.relative(cwd, cssDtsPath),
        js: path.relative(cwd, jsPath),
        dts: path.relative(cwd, dtsPath),
        ...(variantDecl && variantDtsPath
          ? {variantsDts: path.relative(cwd, variantDtsPath)}
          : {}),
      },
      warnings: warningMessages,
      notices: noticeMessages,
    },
  };
}

/**
 * What a standalone build prints after its [ok] lines, kept as data so a
 * batch can print it once for every theme.
 * @typedef {object} ThemeBuildTrailer
 * @property {string} themeName The theme's name.
 * @property {string} exportName The built module's theme export.
 * @property {string} jsImport Import specifier of the built JS module.
 * @property {string} cssImport Import specifier of the built CSS.
 * @property {string[]} unloadedFonts Font families the theme names but does not load.
 * @property {string[]} fontNotices One notice per unloaded font family.
 */

/**
 * Print a standalone build's install snippet and font guidance.
 * @param {ThemeBuildTrailer} trailer
 */
function printBuildTrailer(trailer) {
  logger.log(`
Install in your app (paths are relative to a file in src/; adjust if yours lives elsewhere):

  import { Theme } from '@astryxdesign/core/theme';
  import { ${trailer.exportName} } from '${trailer.jsImport}';
  import '${trailer.cssImport}';

  <Theme theme={${trailer.exportName}}>
    <App />
  </Theme>

Or with a <link> tag:

  import { Theme } from '@astryxdesign/core/theme';
  import { ${trailer.exportName} } from '${trailer.jsImport}';

  <link rel="stylesheet" href="${trailer.cssImport}" />
  <Theme theme={${trailer.exportName}}>
    <App />
  </Theme>
`);
  for (const msg of trailer.fontNotices) logger.log(`  note: ${msg}`);
  if (trailer.unloadedFonts.length > 0) {
    logger.log(formatFontLoadingHelp(trailer.themeName, trailer.unloadedFonts));
  }
}

/**
 * Print the install snippet and font guidance once for a batch: the first
 * theme as the full example, one import line per built theme, and one font
 * recipe naming every family the themes do not load.
 * @param {ThemeBuildTrailer[]} trailers
 */
export function printBatchTrailer(trailers) {
  if (trailers.length === 0) return;
  const [first] = trailers;
  logger.log(`
Install in your app (paths are relative to a file in src/; adjust if yours lives elsewhere):

  import { Theme } from '@astryxdesign/core/theme';
  import { ${first.exportName} } from '${first.jsImport}';
  import '${first.cssImport}';

  <Theme theme={${first.exportName}}>
    <App />
  </Theme>

Or with a <link> tag:

  import { Theme } from '@astryxdesign/core/theme';
  import { ${first.exportName} } from '${first.jsImport}';

  <link rel="stylesheet" href="${first.cssImport}" />
  <Theme theme={${first.exportName}}>
    <App />
  </Theme>
`);
  if (trailers.length > 1) {
    logger.log('Each built theme imports the same way:');
    for (const trailer of trailers) {
      logger.log(
        `  import { ${trailer.exportName} } from '${trailer.jsImport}'; import '${trailer.cssImport}';`,
      );
    }
  }
  const fonts = groupUnloadedFonts(trailers);
  if (fonts.length > 0) logger.log(formatBatchFontLoadingHelp(fonts));
}

/**
 * Print what a short report keeps after its one line per theme: one line
 * naming the fonts the themes do not load, and, when the caller chose no
 * detail level, where the install example and font recipe are.
 * @param {ThemeBuildTrailer[]} trailers
 * @param {{hint?: boolean}} [options]
 */
export function printCompactTrailer(trailers, {hint = false} = {}) {
  if (trailers.length === 0) return;
  const fonts = groupUnloadedFonts(trailers);
  if (fonts.length > 0) {
    const named = fonts
      .map(({family, themes}) =>
        trailers.length > 1
          ? `"${family}" (${themes.join(', ')})`
          : `"${family}"`,
      )
      .join(', ');
    logger.log(
      `[note] Fonts named but not loaded: ${named}. Load them in your app (recipe: ${formatCliCommand('docs typography')}).`,
    );
  }
  if (hint) {
    logger.log(
      'Run with --detail full for the install example and font recipe.',
    );
  }
}

/**
 * Each font family the themes name but do not load, with the themes that
 * name it, in first-seen order.
 * @param {ThemeBuildTrailer[]} trailers
 * @returns {Array<{family: string, themes: string[]}>}
 */
function groupUnloadedFonts(trailers) {
  /** @type {Map<string, {family: string, themes: string[]}>} */
  const byFamily = new Map();
  for (const trailer of trailers) {
    for (const family of trailer.unloadedFonts) {
      const key = family.toLowerCase();
      const entry = byFamily.get(key) ?? {family, themes: []};
      entry.themes.push(trailer.themeName);
      byFamily.set(key, entry);
    }
  }
  return [...byFamily.values()];
}

/**
 * Build one theme for a batch or compact CLI report. Same build, outputs, and
 * receipt as {@link themeBuild}; the install snippet and font guidance come
 * back as `trailer` instead of being printed, and `compact` leaves out the
 * per-file progress lines. CLI-internal: not exported from the API entry.
 * @param {string} file
 * @param {{out?: string, check?: boolean, iconsSpecifier?: string}} [options]
 * @param {{cwd?: string}} [ctx]
 * @param {{compact?: boolean}} [report]
 * @returns {Promise<{receipt: import('../theme.type.mjs').ThemeBuildResponse | import('../theme.type.mjs').ThemeBuildCheckResponse | null, trailer: ThemeBuildTrailer | null}>}
 */
export async function themeBuildForReport(
  file,
  options = {},
  ctx = {},
  {compact = false} = {},
) {
  /** @type {ThemeBuildTrailer[]} */
  const trailers = [];
  const receipt = /** @type {any} */ (
    await themeBuildInternal(file, options, ctx, {compact, trailers})
  );
  return {receipt, trailer: trailers[0] ?? null};
}

/** @param {string} file @param {{out?: string, check?: boolean, iconsSpecifier?: string}} [options] @param {{cwd?: string, projectCore?: boolean}} [ctx] `projectCore`: read only the project's installed Core, never the carried one (doctor; spec AST-081 FR3) @returns {Promise<import('../theme.type.mjs').ThemeBuildResponse | import('../theme.type.mjs').ThemeBuildCheckResponse | null>} */
export async function themeBuild(file, options = {}, ctx = {}) {
  return /** @type {any} */ (themeBuildInternal(file, options, ctx));
}
/** @param {string} name */
// prettier-ignore
function familyThemeBinding(name) {
  const words = name.split(/[^A-Za-z0-9_$]+/).filter(Boolean);
  let identifier = words.map((word, index) => index === 0 ? word : word.charAt(0).toUpperCase() + word.slice(1)).join('');
  if (!/^[A-Za-z_$]/.test(identifier)) identifier = `_${identifier}`;
  return `${identifier || '_'}Theme`;
}
/** @param {any[]} members */
// prettier-ignore
function allocateFamilyBindings(members) {
  const used = new Map();
  return new Map(members.map(member => { const base = familyThemeBinding(member.theme.name), count = used.get(base) ?? 0; used.set(base, count + 1); return [member.theme.name, count === 0 ? base : `${base}${count + 1}`]; }));
}
/**
 * How a family member's module carries slot functions: its parent's values,
 * then its own. A member supplies its own slot functions through a named
 * import of its whole `componentIcons` map, merged as `defineTheme` merges;
 * own static values are written as JSON. Null when the member has no slot
 * function, so its static values are written as JSON alone.
 * @param {any} member
 * @param {any} parent - The member's parent in the family, if any.
 * @param {{themeBinding: string | undefined, parentBinding: string | null | undefined, outDir: string, registryImports: Array<{specifier: string, exportName: string}>, expression: (own: string | null, inherited: string | null) => string | undefined}} context
 * @returns {{imports: Array<{importPath: string, importedName: string, localName: string}>, expression: string, mergeName?: string} | null}
 */
function familyComponentIcons(member, parent, context) {
  const values = themeComponentIcons(member.theme);
  if (!hasFunctionIconEntry(values)) return null;
  const inheritedValues = themeComponentIcons(parent?.theme);
  const inherited =
    context.parentBinding && inheritedValues
      ? `${context.parentBinding}.${hasFunctionIconEntry(inheritedValues) ? '__componentIcons' : 'componentIcons'}`
      : null;
  /** @type {Array<{importPath: string, importedName: string, localName: string}>} */
  const imports = [];
  let own = null;
  const binding =
    context.themeBinding ?? `${toIdentifier(member.theme.name)}Theme`;
  const info = member.componentIconInfo;
  if (info) {
    const input = familyRegistryInput(
      info,
      member.filePath,
      context.outDir,
      undefined,
    );
    const importPath = input.specifier ?? info.importPath;
    own = `${binding}ComponentIconSource`;
    imports.push({importPath, importedName: info.exportName, localName: own});
    context.registryImports.push({
      specifier: importPath,
      exportName: info.exportName,
    });
  } else {
    // Without an import, a member's own slots are the ones that differ from
    // its parent's; they must all be static.
    /** @type {Record<string, unknown>} */
    const ownValues = {};
    for (const [slot, value] of Object.entries(values ?? {})) {
      if (
        inheritedValues &&
        Object.hasOwn(inheritedValues, slot) &&
        inheritedValues[slot] === value
      )
        continue;
      if (typeof value === 'function') {
        throw new AstryxError(
          `Theme "${member.theme.name}" must supply its componentIcons slot functions through a named import of its whole componentIcons map for family output.`,
          undefined,
          ERROR_CODES.ERR_THEME_INVALID,
        );
      }
      ownValues[slot] = value;
    }
    if (Object.keys(ownValues).length > 0) own = JSON.stringify(ownValues);
  }
  if (info) {
    // An imported map can hold an `undefined` slot: it keeps the parent's,
    // and a root drops it, as `defineTheme` does.
    const mergeName = `${binding}MergeComponentIcons`;
    return {
      imports,
      expression: `${mergeName}(${inherited ?? '{}'}, ${own})`,
      mergeName,
    };
  }
  const expression = context.expression(own, inherited);
  return expression ? {imports, expression} : null;
}
/** Rebase a scraped relative registry import to the aggregate module. @param {any} info @param {string} filePath @param {string} outDir @param {string | undefined} override */
// prettier-ignore
function familyRegistryInput(info, filePath, outDir, override) {
  if (!info || override !== undefined) return {info, specifier: override};
  const source = info.importPath;
  if (!source.startsWith('./') && !source.startsWith('../')) return {info, specifier: undefined};
  const absolute = path.resolve(path.dirname(filePath), source);
  let specifier = path.relative(outDir, absolute).split(path.sep).join('/');
  if (!specifier.startsWith('./') && !specifier.startsWith('../')) specifier = `./${specifier}`;
  return {info, specifier};
}
/** Dependency-first load plan including local barrels between selected files. @param {string[]} files @param {string} cwd */
// prettier-ignore
function planFamilySources(files, cwd) {
  /** @type {Array<{file: string, filePath: string}>} */ const entries = files.map(file => ({file, filePath: path.resolve(cwd, file)}));
  /** @param {string} value */ const canonical = value => fs.existsSync(value) ? fs.realpathSync(value) : path.resolve(value);
  /** @type {Map<string, {file: string, filePath: string}>} */ const selected = new Map(entries.map(entry => [canonical(entry.filePath), entry]));
  if (selected.size !== entries.length) return entries.map(entry => ({...entry, selected: true}));
  /** @type {Map<string, Set<string>>} */ const reachableMemo = new Map(), dependencies = new Map();
  /** @param {string} filePath @param {Set<string>} [visiting] @returns {Set<string>} */
  const reachableSelected = (filePath, visiting = new Set()) => {
    const key = canonical(filePath), cached = reachableMemo.get(key); if (cached) return cached;
    if (visiting.has(key) || !fs.existsSync(key)) return new Set();
    visiting.add(key); /** @type {Set<string>} */ const found = new Set(), direct = new Set(); let ast;
    try { ast = parse(fs.readFileSync(key, 'utf8'), {sourceType: 'unambiguous', plugins: ['typescript', 'jsx', 'decorators-legacy', 'importAttributes']}); }
    catch { visiting.delete(key); reachableMemo.set(key, found); return found; }
    for (const node of /** @type {any[]} */ (ast.program.body)) {
      const specifier = node.importKind !== 'type' ? node.source?.value : null; if (typeof specifier !== 'string' || (!specifier.startsWith('.') && !path.isAbsolute(specifier))) continue;
      let dependency; try { dependency = canonical(createJiti(key, {extensions: THEME_MODULE_EXTENSIONS}).resolve(specifier)); } catch { continue; }
      if (!dependency.split(path.sep).includes('node_modules') && /\.[cm]?[jt]sx?$/.test(dependency)) direct.add(dependency);
      if (selected.has(dependency)) found.add(dependency); else for (const nested of reachableSelected(dependency, visiting)) found.add(nested);
    }
    visiting.delete(key); dependencies.set(key, direct); reachableMemo.set(key, found); return found;
  };
  for (const entry of entries) reachableSelected(entry.filePath);
  /** @type {Array<{file: string, filePath: string, selected: boolean}>} */ const plan = []; /** @type {Set<string>} */ const marks = new Set();
  /** @param {string} key */ const visit = key => { if (marks.has(key)) return; marks.add(key); for (const dependency of dependencies.get(key) ?? []) if (selected.has(dependency) || reachableSelected(dependency).size > 0) visit(dependency); const entry = selected.get(key); plan.push(entry ? {...entry, selected: true} : {file: key, filePath: key, selected: false}); };
  for (const entry of entries) visit(canonical(entry.filePath)); return plan;
}

/** Preload an intermediary module into the shared family cache. @param {string} filePath @param {any} loader @param {import('./core-interception.mjs').CoreInterception} interception */
// prettier-ignore
async function preloadFamilySource(filePath, loader, interception) {
  const patch = interception.patchCommonJs(filePath);
  try { try { loader(filePath); } catch (error) { if (!isSyncLoaderLimitation(error)) throw error; await loader.evalModule(fs.readFileSync(filePath, 'utf8'), {id: filePath, filename: filePath, ext: path.extname(filePath), cache: loader.cache, async: true, forceTranspile: true}); } }
  finally { patch.undo(); }
}

/** @param {string[]} files @param {{familyKey: string, check?: boolean, iconsSpecifier?: string, __onPrivateVarError?: () => void}} options @param {{cwd?: string}} [ctx] */
export async function themeBuildFamily(
  files,
  options,
  {cwd = process.cwd()} = {},
) {
  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(options?.familyKey ?? '')) {
    throw new AstryxError(
      'Family key must be an exact lower-kebab filename stem (for example, ocean-family).',
      undefined,
      ERROR_CODES.ERR_THEME_INVALID,
    );
  }
  try {
    sanitizeName(options.familyKey, {label: 'family key'});
  } catch (error) {
    const message =
      error instanceof Error ? error.message : 'Invalid family key.';
    throw new AstryxError(message, undefined, ERROR_CODES.ERR_THEME_INVALID);
  }
  await selectCore(cwd);
  const familyInterception = interceptCore(_coreThemeModule, _coreRootModule);
  // prettier-ignore
  const familyLoader = createJiti(import.meta.url, {moduleCache: true, interopDefault: false, jsx: true, extensions: THEME_MODULE_EXTENSIONS, virtualModules: familyInterception.modules});
  /** @type {any[]} */
  const prepared = [];
  for (const source of planFamilySources(files, cwd)) {
    if (!source.selected) {
      await preloadFamilySource(
        source.filePath,
        familyLoader,
        familyInterception,
      );
      continue;
    }
    const file = source.file;
    // prettier-ignore
    const member = await themeBuildInternal(file, {iconsSpecifier: options.iconsSpecifier, __prepareFamily: true, __familyLoader: familyLoader, __familyInterception: familyInterception, __onPrivateVarError: options.__onPrivateVarError}, {cwd});
    if (!member || member.type) {
      throw new AstryxError(
        `Theme family member "${file}" did not produce a complete build plan.`,
        undefined,
        ERROR_CODES.ERR_THEME_INVALID,
      );
    }
    prepared.push(member);
  }
  let members;
  try {
    members = resolveThemeFamily(prepared);
  } catch (error) {
    const message =
      error instanceof Error ? error.message : 'Invalid selected theme family.';
    throw new AstryxError(message, undefined, ERROR_CODES.ERR_THEME_INVALID);
  }
  for (const member of members) {
    for (const [field, info] of [
      ['icons', member.iconInfo],
      ['indicators', member.indicatorInfo],
    ]) {
      // A theme with a function entry gets its own node view of `icons`, so
      // an inherit-only member is recognized by its entries.
      const value =
        field === 'icons'
          ? themeIconEntries(member.theme)
          : member.theme[field];
      const inherited =
        field === 'icons'
          ? themeIconEntries(member.sourceParent)
          : member.sourceParent?.[field];
      if (
        value &&
        Object.keys(value).length > 0 &&
        value !== inherited &&
        !info
      ) {
        throw new AstryxError(
          `Theme "${member.theme.name}" must supply ${field} through a named import for family output.`,
          undefined,
          ERROR_CODES.ERR_THEME_INVALID,
        );
      }
    }
  }
  const baseName = options.familyKey;
  if (members.some(member => member.theme.name === baseName)) {
    throw new AstryxError(
      `Family key "${baseName}" collides with a selected theme's standalone outputs. Choose a distinct filename stem.`,
      undefined,
      ERROR_CODES.ERR_THEME_INVALID,
    );
  }
  const root = members[0];
  const outDir = path.dirname(root.filePath);
  const outPath = path.join(outDir, `${baseName}.css`);
  const cssDtsPath = `${outPath}.d.ts`;
  const jsPath = path.join(outDir, `${baseName}.js`);
  const dtsPath = path.join(outDir, `${baseName}.d.ts`);
  const sources = new Set(
    members.flatMap(member =>
      [path.resolve(member.filePath), fs.realpathSync(member.filePath)].map(
        value => value.toLowerCase(),
      ),
    ),
  );
  const collision = [outPath, cssDtsPath, jsPath, dtsPath].find(output => {
    const candidates = [path.resolve(output)];
    if (fs.existsSync(output)) candidates.push(fs.realpathSync(output));
    return candidates.some(value => sources.has(value.toLowerCase()));
  });
  if (collision) {
    throw new AstryxError(
      `Family output ${path.relative(cwd, collision)} collides with a selected source file.`,
      undefined,
      ERROR_CODES.ERR_THEME_INVALID,
    );
  }
  const sourceRelative = members
    .map(member => member.sourceRelative)
    .join(', ');
  const buildCommand = `${getCliInvocation()} theme build --family ${members
    .map(member => member.sourceRelative)
    .join(' ')} --family-key ${baseName}`;
  const bindings = allocateFamilyBindings(members);
  const css = generateFamilyCSS(members);
  /** @type {Array<{specifier: string, exportName: string}>} */
  const registryImports = [];
  const js = members
    .map(member => {
      const themeBinding = bindings.get(member.theme.name);
      const parentBinding = member.parentName
        ? bindings.get(member.parentName)
        : null;
      // prettier-ignore
      const icon = familyRegistryInput(member.iconInfo, member.filePath, outDir, options.iconsSpecifier);
      // prettier-ignore
      const indicator = familyRegistryInput(member.indicatorInfo, member.filePath, outDir, undefined);
      // prettier-ignore
      for (const registry of [icon, indicator]) if (registry.info) registryImports.push({specifier: registry.specifier ?? registry.info.importPath, exportName: registry.info.exportName});
      const ownIcons = icon.info ? `${themeBinding}Icons` : null;
      // A parent with function entries keeps them in `__icons`; its `icons`
      // is the node view.
      const parent = members.find(
        other => other.theme.name === member.parentName,
      );
      const inheritedIcons = parentBinding
        ? `${parentBinding}.${hasFunctionIconEntry(themeIconEntries(parent?.theme)) ? '__icons' : 'icons'}`
        : null;
      const ownIndicators = indicator.info ? `${themeBinding}Indicators` : null;
      const inheritedIndicators = parentBinding
        ? `${parentBinding}.indicators`
        : null;
      /** @param {string | null} own @param {string | null} inherited */
      const expression = (own, inherited) =>
        own && inherited
          ? `{...${inherited}, ...${own}}`
          : (own ?? inherited ?? undefined);
      const indicatorImport = indicator.info
        ? `import { ${indicator.info.exportName} as ${ownIndicators} } from ${JSON.stringify(indicator.specifier ?? indicator.info.importPath)};\n`
        : '';
      // The member's own registry import, bound to its family-unique name; a
      // rebased or overridden specifier replaces the scraped one.
      // prettier-ignore
      const iconImports = icon.info && ownIcons ? {imports: [{importPath: icon.info.importPath, importedName: icon.info.exportName, localName: ownIcons}], expression: ownIcons, exportName: ownIcons, iconsSpecifierImportPath: icon.info.importPath, iconsSpecifierLocalName: ownIcons} : null;
      const componentIconInfo = familyComponentIcons(member, parent, {
        themeBinding,
        parentBinding,
        outDir,
        registryImports,
        expression,
      });
      return (
        indicatorImport +
        generateBuiltModule(member.theme, iconImports, icon.specifier, {
          themeBinding,
          iconsExpression: expression(ownIcons, inheritedIcons),
          indicatorsExpression: expression(ownIndicators, inheritedIndicators),
          artifactBaseName: baseName,
          exportIcons: false,
          componentIconInfo,
        })
      );
    })
    .join('\n');
  await validateRegistryGraphs(registryImports, jsPath);
  const declarations = members
    .map((member, index) =>
      generateBuiltTypes(member.theme, member.iconInfo, null, {
        themeBinding: bindings.get(member.theme.name),
        includeIconExport: false,
        includeThemeImport: index === 0,
      }),
    )
    .join('');
  const augmentations = [
    ...new Set(members.map(member => member.variantDecl).filter(Boolean)),
  ].join('\n');
  const writes = [
    {
      dest: outPath,
      content:
        generatedHeader(sourceRelative, 'css', buildCommand, root.versions) +
        css,
    },
    {
      dest: cssDtsPath,
      allowMissingInCheck: true,
      content:
        generatedHeader(sourceRelative, 'ts', buildCommand, root.versions) +
        'export {};\n',
    },
    {
      dest: jsPath,
      content:
        generatedHeader(sourceRelative, 'js', buildCommand, root.versions) + js,
    },
    {
      dest: dtsPath,
      content:
        generatedHeader(sourceRelative, 'ts', buildCommand, root.versions) +
        declarations +
        (augmentations ? `\n${augmentations}` : ''),
    },
  ];
  const outputs = {
    css: path.relative(cwd, outPath),
    cssDts: path.relative(cwd, cssDtsPath),
    js: path.relative(cwd, jsPath),
    dts: path.relative(cwd, dtsPath),
  };
  // A family build's outputs stay inside cwd too; check mode only reads them.
  if (!options.check) confineOutputs(writes, cwd, FAMILY_REMEDY);
  if (options.check) {
    const stale = staleBuildOutputs(writes, cwd);
    const upToDate = stale.length === 0;
    if (upToDate) {
      logger.log(
        `\n[ok] Theme family outputs are up to date with ${sourceRelative}.`,
      );
    } else {
      logger.error(
        `\n[fail] ${stale.length} theme family output(s) are out of date:`,
      );
      for (const entry of stale) {
        logger.error(
          `  ${entry.reason === 'missing' ? 'missing' : 'stale'}: ${entry.path}`,
        );
      }
      // prettier-ignore
      const remedy = outsideCheckRemedy(writes, members.map(member => member.filePath), cwd, relative => ['--family', ...members.map(member => relative(member.filePath)), '--family-key', baseName, ...(options.iconsSpecifier ? ['--icons-specifier', options.iconsSpecifier] : [])]);
      if (remedy) logger.error(`\n  ${remedy.join('\n  ')}`);
      else logger.error(`\n  Rebuild with: ${buildCommand}`);
    }
    return {
      type: 'theme.build.check',
      data: {
        name: root.theme.name,
        upToDate,
        stale,
        checked: checkedBuildOutputs(writes, cwd),
      },
    };
  }
  writeBuildOutputs(writes);
  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);
  const cssImport = `${jsImport}.css`;
  logger.log(`
Load the family CSS once, then select any member by theme identity:
  import { ${themeBindings.join(', ')} } from '${jsImport}';
  import '${cssImport}';
Or load the same stylesheet natively:
  <link rel="stylesheet" href="${cssImport}" />
`);
  const warnings = [...new Set(members.flatMap(member => member.warnings))];
  const unloadedFonts = [
    ...new Set(members.flatMap(member => member.unloadedFonts)),
  ];
  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)`,
  );
  for (const notice of notices) logger.log(`  note: ${notice}`);
  return {
    type: 'theme.build',
    data: {
      name: root.theme.name,
      tokenCount: members.reduce((sum, member) => sum + member.tokenCount, 0),
      componentCount: members.reduce(
        (sum, member) => sum + member.componentCount,
        0,
      ),
      sizeKB: parseFloat((Buffer.byteLength(css) / 1024).toFixed(1)),
      outputs,
      warnings,
      notices,
    },
  };
}