@astryxdesign/cli 0.7.2-canary.fbc03f7 → 0.7.2-canary.fdd384f

package/api/search/search.mjs

@@ -81,12 +81,20 @@
 
 import {withListingCache} from '../../foundation/fs/listing-cache.mjs';
 import {readDocView} from '../../foundation/doc-compiler/read.mjs';
-import {findCoreDir} from '../../foundation/fs/paths.mjs';
+import {
+  discoverExternalPackages,
+  findCoreDir,
+} from '../../foundation/fs/paths.mjs';
 import {
   discoverComponents,
   discoverValidIntegrationComponents,
+  docStem,
   familyMember,
   findComponentReadme,
+  forEachIntegrationDoc,
+  integrationMemberEntry,
+  integrationRecordHold,
+  isIntegrationMember,
   resolveImportPath,
   resolveIntegrationImportPath,
   CORE_PACKAGE,
@@ -98,6 +106,7 @@ import {
 import {
   loadComponentReplacements,
   loadIntegrationsSafely,
+  resolveLegacyExternalDoc,
 } from '../component/_adapter.mjs';
 import {levenshteinDistance} from '../../foundation/text/string-utils.mjs';
 import {discoverTemplates, extractComponents} from '../template/template.mjs';
@@ -150,6 +159,9 @@ import {setResultCoverage} from './coverage.mjs';
  * @property {'page'|'block'} [_kind]
  * @property {string} [_resultName]
  * @property {string} [_commandName]
+ * @property {'file'|'doc'} [_hold] - How an integration component holds its
+ *   name, for the owner rule.
+ * @property {string} [_docPath] - An integration component's doc.
  */
 
 /**
@@ -1110,20 +1122,57 @@ async function gatherCoreComponents(coreDir) {
  * usage/description from each component's .doc.mjs, same as core. Without
  * this, an integration component is invisible to `search`/`build` even
  * though `component --list`/`component <Name>` already resolve it — the two
- * discovery paths silently disagreed.
+ * discovery paths silently disagreed. Also returns, per name, the docs that
+ * hold it by their file name and the loadable docs that only record it.
  * @param {import('../../foundation/integrations/integrations.mjs').LoadedIntegration[]} loadedIntegrations
- * @returns {Promise<Candidate[]>}
+ * @returns {Promise<{candidates: Candidate[], fileNamed: Map<string, Set<string>>, documented: Map<string, Set<string>>}>}
  */
 async function gatherIntegrationComponents(loadedIntegrations) {
   /** @type {Candidate[]} */
   const candidates = [];
+  // What the owner rule reads: the docs that hold a name by their file name,
+  // loadable or not and hidden ones too, and the loadable docs that only
+  // record it.
+  /** @type {Map<string, Set<string>>} */
+  const fileNamed = new Map();
+  /** @type {Map<string, Set<string>>} */
+  const documented = new Map();
+  /** @param {Map<string, Set<string>>} map @param {string} name @param {string} docPath */
+  const hold = (map, name, docPath) =>
+    map.set(name, (map.get(name) ?? new Set()).add(docPath));
   for (const integration of loadedIntegrations) {
-    const {components} = await discoverValidIntegrationComponents(integration);
+    const {components, discovered} =
+      await discoverValidIntegrationComponents(integration);
+    const renamed = new Set(
+      discovered
+        .filter(rec => integrationRecordHold(rec) === 'doc')
+        .filter(rec => !isIntegrationMember(rec))
+        .map(rec => rec.docPath),
+    );
+    forEachIntegrationDoc(integration.components, (docPath, stem) => {
+      if (!renamed.has(docPath)) hold(fileNamed, stem, docPath);
+    });
     for (const rec of components) {
-      const doc = await loadModuleDoc(rec.docPath);
+      const loaded = await loadModuleDoc(rec.docPath);
+      // A family member is indexed from its own entry: the family's keywords
+      // and guidance describe the family.
+      const member = isIntegrationMember(rec);
+      const doc = member ? integrationMemberEntry(loaded, rec) : loaded;
+      // A doc that names another export of its file still answers to the
+      // file's name, as `component <file name>` does.
+      const fileName = docStem(rec.docPath);
+      if (integrationRecordHold(rec) === 'doc') {
+        hold(documented, rec.name, rec.docPath);
+      }
+      if (renamed.has(rec.docPath) && !member) {
+        hold(documented, fileName, rec.docPath);
+      }
       candidates.push({
         domain: 'component',
         name: rec.name,
+        aliases: !member && fileName !== rec.name ? [fileName] : [],
+        _hold: integrationRecordHold(rec),
+        _docPath: rec.docPath,
         keywords: doc && Array.isArray(doc.keywords) ? doc.keywords : [],
         description: doc ? doc.usage?.description || doc.description || '' : '',
         guidance: guidanceFrom(doc),
@@ -1143,12 +1192,12 @@ async function gatherIntegrationComponents(loadedIntegrations) {
             packageName: rec.package,
           },
           rec.name,
-          doc?.import,
+          loaded?.import,
         ),
       });
     }
   }
-  return candidates;
+  return {candidates, fileNamed, documented};
 }
 
 /**
@@ -1160,11 +1209,12 @@ async function gatherIntegrationComponents(loadedIntegrations) {
  */
 async function gatherComponents(coreDir, cwd) {
   const loadedIntegrations = await loadIntegrationsSafely(cwd);
-  const [core, integrations, replacements] = await Promise.all([
+  const [core, gathered, replacements] = await Promise.all([
     gatherCoreComponents(coreDir),
     gatherIntegrationComponents(loadedIntegrations),
     loadComponentReplacements(coreDir, loadedIntegrations),
   ]);
+  const {candidates: integrations, fileNamed, documented} = gathered;
   // An active replacement answers to the Core name it replaces, so a search
   // for that name finds the replacement and not the Core original
   // (spec:AST-035 FR11).
@@ -1175,9 +1225,43 @@ async function gatherComponents(coreDir, cwd) {
       active.target,
     ]),
   );
+  // The owner rule, as component detail applies it: a candidate `component
+  // <name>` does not open names its package and follows the owner, and a
+  // file-name alias that opens another owner is dropped.
+  const coreNames = new Set(core.map(candidate => candidate.name));
+  /** @param {string} name @param {Candidate} candidate */
+  const opens = (name, candidate) =>
+    !coreNames.has(name) &&
+    findComponentReadme(coreDir, name) == null &&
+    [...(fileNamed.get(name) ?? [])].every(doc => doc === candidate._docPath) &&
+    [...(documented.get(name) ?? [])].every(doc => doc === candidate._docPath);
+  // A legacy docs package keeps an exact name over an export name a doc records.
+  /** @type {ReturnType<typeof discoverExternalPackages> | undefined} */
+  let externals;
+  /** @param {string} name */
+  const legacyDocuments = name =>
+    (externals ??= discoverExternalPackages(cwd)).some(
+      ext => resolveLegacyExternalDoc(ext, name) != null,
+    );
+  const ruled = integrations.map(candidate => {
+    const aliases = (candidate.aliases ?? []).filter(alias =>
+      opens(alias, candidate),
+    );
+    return candidate._hold === 'doc' &&
+      (!opens(candidate.name, candidate) || legacyDocuments(candidate.name))
+      ? {
+          ...candidate,
+          aliases,
+          _command: `astryx component ${candidate.name} --package ${candidate._package}`,
+        }
+      : {...candidate, aliases};
+  });
   return [
     ...core.filter(candidate => !replacements.forTarget(candidate.name)),
-    ...integrations.map(candidate => {
+    ...[
+      ...ruled.filter(candidate => !candidate._command),
+      ...ruled.filter(candidate => candidate._command),
+    ].map(candidate => {
       const target = targetOf.get(`${candidate._package}\0${candidate.name}`);
       if (target != null) {
         return {...candidate, aliases: [...(candidate.aliases ?? []), target]};
@@ -1244,10 +1328,13 @@ export async function componentKeywords(coreDir, cwd) {
   const integrations = loadedIntegrations.map(async integration => {
     const {components} = await discoverValidIntegrationComponents(integration);
     return Promise.all(
-      components.map(async rec => ({
-        name: rec.name,
-        keywords: keywordsOf(await loadModuleDoc(rec.docPath)),
-      })),
+      components.map(async rec => {
+        const loaded = await loadModuleDoc(rec.docPath);
+        return {
+          name: rec.name,
+          keywords: keywordsOf(integrationMemberEntry(loaded, rec) ?? loaded),
+        };
+      }),
     );
   });
   return [

package/api/swizzle/copy/copy.mjs

@@ -21,8 +21,10 @@ import {checkGhCli} from '../_github.mjs';
 import {Project} from '../../../foundation/config/project.mjs';
 import {
   CORE_PACKAGE,
-  findIntegrationComponentDoc,
-  findIntegrationComponentSource,
+  docStem,
+  findComponentReadme,
+  findIntegrationComponent,
+  unscopedComponentOwners,
 } from '../../../foundation/discovery/component-discovery.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {AstryxError, writeFailed} from '../../error.mjs';
@@ -126,33 +128,38 @@ async function loadConfigSafely(cwd) {
 
 /**
  * Build the set of OWNER packages that provide a component named `name` across
- * core + every loaded integration.
+ * core + every loaded integration. Core holds every name it documents, but has
+ * source to copy (`sourceDir`) only for a name with its own folder.
  * @param {string} coreDir
  * @param {Array<{name: string, components?: string, issuesUrl?: string}>} loadedIntegrations
  * @param {string} name
  * @param {string|undefined} coreIssuesUrl
- * @returns {Array<{package: string, sourceDir: string|null, ownerPackage: string, issuesUrl: string|undefined}>}
+ * @returns {Array<{package: string, sourceDir: string|null, docPath: string|null, ownerPackage: string, issuesUrl: string|undefined, hold: string}>}
  */
 function resolveOwners(coreDir, loadedIntegrations, name, coreIssuesUrl) {
   const owners = [];
   const coreComponentDir = path.join(coreDir, 'src', name);
-  if (fs.existsSync(coreComponentDir)) {
+  const coreFolder = fs.existsSync(coreComponentDir);
+  if (coreFolder || findComponentReadme(coreDir, name)) {
     owners.push({
       package: CORE_PACKAGE,
-      sourceDir: coreComponentDir,
+      sourceDir: coreFolder ? coreComponentDir : null,
+      docPath: null,
       ownerPackage: CORE_PACKAGE,
       issuesUrl: coreIssuesUrl || DEFAULT_ISSUES_URL,
+      hold: 'core',
     });
   }
   for (const integration of loadedIntegrations) {
-    const docPath = findIntegrationComponentDoc(integration, name);
-    if (!docPath) continue;
-    const sourcePath = findIntegrationComponentSource(integration, name);
+    const found = findIntegrationComponent(integration, name);
+    if (!found) continue;
     owners.push({
       package: integration.name,
-      sourceDir: sourcePath ? path.dirname(sourcePath) : null,
+      sourceDir: found.sourcePath ? path.dirname(found.sourcePath) : null,
+      docPath: found.docPath,
       ownerPackage: integration.name,
       issuesUrl: integration.issuesUrl,
+      hold: found.hold,
     });
   }
   return owners;
@@ -222,25 +229,32 @@ export async function swizzleCopy(component, options = {}) {
     : undefined;
   // An active integration replacement answers to the Core name it replaces,
   // bare or qualified by its own package (spec:AST-035 FR11): copy it under its
-  // own name. `--package @astryxdesign/core` still copies the Core original.
+  // doc's file name, the folder it has always gone to. `--package
+  // @astryxdesign/core` still copies the Core original.
   if (pkg !== CORE_PACKAGE) {
     const replacement = await resolveComponentReplacement(
       coreDir,
       loadedIntegrations,
       dirName,
     );
+    const copyName = replacement ? docStem(replacement.docPath) : null;
     if (
       replacement &&
-      (!pkg || (pkg === replacement.package && replacement.name !== dirName))
+      copyName &&
+      (!pkg || (pkg === replacement.package && copyName !== dirName))
     ) {
-      return swizzleCopy(replacement.name, {
+      return swizzleCopy(copyName, {
         ...options,
         package: replacement.package,
       });
     }
   }
 
-  const allOwners = resolveOwners(coreDir, loadedIntegrations, dirName, coreIssuesUrl);
+  const found = resolveOwners(coreDir, loadedIntegrations, dirName, coreIssuesUrl);
+  // The owner rule, then a Core name without its own folder drops out.
+  const allOwners = (pkg ? found : unscopedComponentOwners(found)).filter(
+    owner => owner.package !== CORE_PACKAGE || owner.sourceDir != null,
+  );
 
   if (allOwners.length === 0) {
     throw new AstryxError(

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

@@ -13,6 +13,7 @@ import {themeBuild, themeBuildFamily} from './build.mjs';
 import {interceptCore} from './core-interception.mjs';
 import {ensureCoreBuilt} from '../../../clients/cli/commands/ensure-core-built.mjs';
 import {runCli} from '../../../test-utils/run-cli.mjs';
+import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
 vi.setConfig({testTimeout: 120_000});
 const CLI_ROOT = path.resolve(import.meta.dirname, '../../..');
 const FAMILY_KEY = 'ocean-family';
@@ -252,22 +253,69 @@ describe('themeBuildFamily()', () => {
     expect(fs.existsSync(dtsPath)).toBe(false);
   });
 
-  it('refuses family outputs outside cwd before checking or writing', async () => {
+  it('refuses to write family outputs outside cwd, and checks them read-only', async () => {
     const dir = makeDir();
     const files = writeFamily(dir).map(file => path.join(dir, file));
     const app = path.join(dir, 'app');
     fs.mkdirSync(app);
 
-    for (const check of [false, true]) {
-      await expect(
-        themeBuildFamily(files, {familyKey: FAMILY_KEY, check}, {cwd: app}),
-      ).rejects.toMatchObject({code: 'ERR_PATH_TRAVERSAL'});
-    }
+    await expect(
+      themeBuildFamily(files, {familyKey: FAMILY_KEY}, {cwd: app}),
+    ).rejects.toMatchObject({code: 'ERR_PATH_TRAVERSAL'});
+    const checked = await themeBuildFamily(
+      files,
+      {familyKey: FAMILY_KEY, check: true},
+      {cwd: app},
+    );
+    expect(checked?.type).toBe('theme.build.check');
+    expect(checked?.data.upToDate).toBe(false);
+    // The `.css.d.ts` import stub may be absent in check mode.
+    expect(checked?.data.stale).toEqual(
+      OUTPUTS.filter(file => !file.endsWith('.css.d.ts')).map(file => ({
+        path: `../themes/${file}`,
+        reason: 'missing',
+      })),
+    );
     for (const output of OUTPUTS) {
       expect(fs.existsSync(path.join(dir, 'themes', output))).toBe(false);
     }
   });
 
+  it('ends a stale family report for outputs outside cwd with a remedy that works', async () => {
+    const dir = makeDir();
+    const files = writeFamily(dir).map(file => path.join(dir, file));
+    const app = path.join(dir, 'app');
+    fs.mkdirSync(app);
+    const family = ['--family', ...files, '--family-key', FAMILY_KEY];
+
+    const stale = await runCli(['theme', 'build', ...family, '--check'], app);
+    expect(stale.code).toBe(1);
+    // The old remedy ran the build from cwd, which refuses these outputs.
+    expect(stale.stderr).not.toContain('Rebuild with:');
+
+    const lines = stale.stderr.split('\n').map(line => line.trim());
+    const runDir = lines.find(line => line.startsWith('cd '))?.slice(3);
+    expect(runDir).toBe(fs.realpathSync(path.join(dir, 'themes')));
+    const stem = `${getCliInvocation(runDir)} theme build `;
+    const [buildArgs, checkArgs] = lines
+      .filter(line => line.startsWith(stem))
+      .map(line => line.slice(stem.length).split(' '));
+    expect(checkArgs).toEqual([...buildArgs, '--check']);
+
+    // Following the remedy builds, and the check from there passes.
+    const built = await runCli(['theme', 'build', ...buildArgs], runDir);
+    expect(built.code).toBe(0);
+    for (const output of OUTPUTS) {
+      expect(fs.existsSync(path.join(dir, 'themes', output))).toBe(true);
+    }
+    const checked = await runCli(
+      ['--json', 'theme', 'build', ...checkArgs],
+      runDir,
+    );
+    expect(checked.code).toBe(0);
+    expect(JSON.parse(checked.stdout).data.upToDate).toBe(true);
+  });
+
   it('fails without publishing a mixed trio when staging a write fails', async () => {
     const dir = makeDir();
     const files = writeFamily(dir);

package/api/theme/build/build.mjs

@@ -27,8 +27,10 @@
  * 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, explicit or beside the theme file, stays inside `cwd`
- * (`ERR_PATH_TRAVERSAL` otherwise), in check mode too.
+ * 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
@@ -60,7 +62,10 @@ import {isBuiltin} from 'node:module';
 import {fileURLToPath, pathToFileURL} from 'node:url';
 import {parse} from '@babel/parser';
 import {createJiti} from 'jiti';
-import {getCliInvocation} from '../../../foundation/env/package-manager.mjs';
+import {
+  formatCliCommand,
+  getCliInvocation,
+} from '../../../foundation/env/package-manager.mjs';
 import {
   CLI_ROOT,
   findCoreDir,
@@ -568,6 +573,86 @@ 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;
@@ -2859,9 +2944,13 @@ async function themeBuildInternal(
   const writeRoot = options.__writeRoot ?? cwd;
   let outPath;
   if (options.out) {
-    // Relative or absolute, the explicit output stays inside the write root.
     outPath = path.resolve(cwd, options.out);
-    confineOutput(outPath, writeRoot, OUT_REMEDY, 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`);
   }
@@ -2957,10 +3046,12 @@ async function themeBuildInternal(
     writes.push({dest: variantDtsPath, content: variantContent});
   }
 
-  // Every output stays inside cwd, including the defaults beside the theme
-  // file. Check mode refuses the same paths, so it never passes outputs that a
-  // build would refuse to write.
-  confineOutputs(writes, writeRoot, options.out ? OUT_REMEDY : SOURCE_REMEDY);
+  // 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
@@ -2980,7 +3071,10 @@ async function themeBuildInternal(
           `  ${s.reason === 'missing' ? 'missing' : 'stale'}: ${s.path}`,
         );
       }
-      logger.error(`\n  Rebuild with: ${buildCommand}`);
+      // 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',
@@ -3093,7 +3187,7 @@ 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';
+  import { Theme } from '@astryxdesign/core/theme';
   import { ${trailer.exportName} } from '${trailer.jsImport}';
   import '${trailer.cssImport}';
 
@@ -3103,7 +3197,7 @@ Install in your app (paths are relative to a file in src/; adjust if yours lives
 
 Or with a <link> tag:
 
-  import { Theme } from '@astryxdesign/core';
+  import { Theme } from '@astryxdesign/core/theme';
   import { ${trailer.exportName} } from '${trailer.jsImport}';
 
   <link rel="stylesheet" href="${trailer.cssImport}" />
@@ -3129,7 +3223,7 @@ export function printBatchTrailer(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';
+  import { Theme } from '@astryxdesign/core/theme';
   import { ${first.exportName} } from '${first.jsImport}';
   import '${first.cssImport}';
 
@@ -3139,7 +3233,7 @@ Install in your app (paths are relative to a file in src/; adjust if yours lives
 
 Or with a <link> tag:
 
-  import { Theme } from '@astryxdesign/core';
+  import { Theme } from '@astryxdesign/core/theme';
   import { ${first.exportName} } from '${first.jsImport}';
 
   <link rel="stylesheet" href="${first.cssImport}" />
@@ -3506,8 +3600,8 @@ export async function themeBuildFamily(
     js: path.relative(cwd, jsPath),
     dts: path.relative(cwd, dtsPath),
   };
-  // The family's outputs stay inside cwd too, in check mode as well.
-  confineOutputs(writes, cwd, FAMILY_REMEDY);
+  // 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;
@@ -3524,7 +3618,10 @@ export async function themeBuildFamily(
           `  ${entry.reason === 'missing' ? 'missing' : 'stale'}: ${entry.path}`,
         );
       }
-      logger.error(`\n  Rebuild with: ${buildCommand}`);
+      // 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',

package/api/theme/themeBuild.doc.mjs

@@ -58,13 +58,13 @@ export const doc = {
       name: 'options.out',
       type: 'string',
       description:
-        'Override the output CSS path, relative or absolute; it must resolve inside cwd. The .js, .d.ts and any .variants.d.ts are written in the same directory, named after the theme (<name>.js), not after the CSS file.',
+        'Override the output CSS path, relative or absolute; a build refuses a path outside cwd, and check mode refuses only a relative path that escapes cwd. The .js, .d.ts and any .variants.d.ts are written in the same directory, named after the theme (<name>.js), not after the CSS file.',
     },
     {
       name: 'options.check',
       type: 'boolean',
       description:
-        'Compile in memory and compare each output against what is on disk instead of writing: the CI drift guard.',
+        'Compile in memory and compare each output against what is on disk instead of writing: the CI drift guard. Because it writes nothing, it also compares outputs outside cwd; when those are stale, the report names the directory that contains them and the build and check commands to run from there, since a build refuses them and each output records the directory it was built from.',
       default: 'false',
     },
     {
@@ -77,7 +77,7 @@ export const doc = {
       name: 'ctx.cwd',
       type: 'string',
       description:
-        'Directory the theme file, a relative out path, and the returned output paths resolve against. Every output is written inside it, including the default outputs beside the theme file.',
+        'Directory the theme file, a relative out path, and the returned output paths resolve against. Every output a build writes is inside it, including the default outputs beside the theme file.',
       default: 'process.cwd()',
     },
   ],
@@ -105,7 +105,7 @@ export const doc = {
     },
     {
       code: 'ERR_PATH_TRAVERSAL',
-      when: 'the theme name contains a path separator or traversal marker, or an output resolves outside cwd (including through a symlink): an `out` path, relative or absolute, or the default outputs beside a theme file outside cwd (also rejected in check mode)',
+      when: 'the theme name contains a path separator or traversal marker, or a written output resolves outside cwd (including through a symlink): an `out` path, relative or absolute, or the default outputs beside a theme file outside cwd. Check mode writes nothing, so it refuses only a relative `out` path that escapes cwd',
     },
     {
       code: 'ERR_CORE_NOT_FOUND',

package/assets/docs/README.md

@@ -51,6 +51,16 @@ The material is usually good; the finding is placement, not quality. It goes in
 
 Worked example: a responsive-and-interaction readiness rubric is grading criteria → **Component-Audit-Rubric**, or **Component-Lifecycle** if it is a promotion gate.
 
+## Imports in code samples
+
+Import each Core export from the path `astryx component <Name>` prints: the
+component's own entry when Core has one (`@astryxdesign/core/VStack`,
+`@astryxdesign/core/Heading`), and `@astryxdesign/core/theme` for `Theme`,
+`defineTheme` and the rest of the theme API. A reader copies one sample and then
+reads `astryx component`, and two paths for one export read as two different
+things. The no-build CDN page is the exception: its import map names only the
+package root.
+
 ## Sections are read one at a time
 
 `astryx docs <topic> --index` lists a topic's sections, and readers then open

package/assets/docs/author-a-theme.doc.mjs

@@ -120,7 +120,7 @@ export const docs = {
           ['ocean.variants.d.ts', "(Optional) Module augmentations for custom component prop values"],
         ]},
         {type: 'prose', text: 'The `__built: true` flag tells Theme to skip runtime `<style>` injection; the CSS file handles it. Load the generated CSS wherever you load the module.'},
-        {type: 'code', lang: 'tsx', label: 'Using a custom built theme', code: "import {Theme} from '@astryxdesign/core';\nimport {oceanTheme} from './themes/ocean';\nimport './themes/ocean.css';\n\n<Theme theme={oceanTheme}>\n  <App />\n</Theme>"},
+        {type: 'code', lang: 'tsx', label: 'Using a custom built theme', code: "import {Theme} from '@astryxdesign/core/theme';\nimport {oceanTheme} from './themes/ocean';\nimport './themes/ocean.css';\n\n<Theme theme={oceanTheme}>\n  <App />\n</Theme>"},
         {type: 'prose', text: "After upgrading Astryx, rerun `astryx theme build` for every custom prebuilt theme. Deploy the regenerated files together. The runtime intentionally trusts `__built: true` and will not repair stale CSS from an older build. The build also warns when the theme names font families it does not load. See {@link generic:font-setup} for the full recipe."},
         {type: 'prose', text: 'For the runtime vs built tradeoff, see the Runtime vs Built section of {@link generic:use-a-theme}.'},
       ],