@astryxdesign/cli 0.6.3-canary.d0d49a4 → 0.6.3-canary.dea6813

package/api/theme/build/build.mjs

@@ -224,10 +224,10 @@ function staleBuildOutputs(writes, cwd) {
 /** @param {Array<{dest: string, content: string}>} writes */
 function writeBuildOutputs(writes) {
   if (writes.length === 0) return;
-  fs.mkdirSync(path.dirname(writes[0].dest), {recursive: true});
   /** @type {Array<{tmp: string, dest: string}>} */
   const staged = [];
   try {
+    fs.mkdirSync(path.dirname(writes[0].dest), {recursive: true});
     for (const write of writes) {
       const tmp = `${write.dest}.${process.pid}.tmp`;
       fs.writeFileSync(tmp, write.content);
@@ -1871,7 +1871,7 @@ function validatePrivateVars(themeDef) {
           if (prop.startsWith('--_')) {
             errors.push(
               `Component "${component}" (${[key, ...path].join(' ')}) sets private var "${prop}". ` +
-                `Private vars (--_*) are internal — use standard CSS properties ` +
+                `Private vars (--_*) are internal; use standard CSS properties ` +
                 `(e.g. borderRadius, padding) instead. The pipeline expands them automatically.`,
             );
           }
@@ -1931,20 +1931,7 @@ function getThemeComponentLayers(themeDef) {
  */
 function validateCustomHeadingTypes(themeDef) {
   const layers = getThemeComponentLayers(themeDef);
-  const customTypes = new Set();
-  for (const {components} of layers) {
-    const headingRules = components.heading;
-    if (!headingRules || typeof headingRules !== 'object') continue;
-
-    for (const key of Object.keys(headingRules)) {
-      for (const pair of key.split('+')) {
-        const colon = pair.indexOf(':');
-        if (colon === -1 || pair.slice(0, colon) !== 'type') continue;
-        const value = pair.slice(colon + 1);
-        if (value && !BUILTIN_HEADING_TYPES.has(value)) customTypes.add(value);
-      }
-    }
-  }
+  const customTypes = customHeadingTypes(themeDef);
 
   const errors = [];
   for (const type of customTypes) {
@@ -1971,10 +1958,65 @@ function validateCustomHeadingTypes(themeDef) {
   return errors;
 }
 
+/**
+ * Custom Heading type names declared on the root or media-surface component
+ * maps: the names the generated `HeadingTypeMap` augmentation enrolls.
+ *
+ * @param {{components?: Record<string, Record<string, unknown>>}} themeDef
+ * @returns {Set<string>}
+ */
+function customHeadingTypes(themeDef) {
+  /** @type {Set<string>} */
+  const customTypes = new Set();
+  for (const {components} of getThemeComponentLayers(themeDef)) {
+    const headingRules = components.heading;
+    if (!headingRules || typeof headingRules !== 'object') continue;
+
+    for (const key of Object.keys(headingRules)) {
+      for (const pair of key.split('+')) {
+        const colon = pair.indexOf(':');
+        if (colon === -1 || pair.slice(0, colon) !== 'type') continue;
+        const value = pair.slice(colon + 1);
+        if (value && !BUILTIN_HEADING_TYPES.has(value)) customTypes.add(value);
+      }
+    }
+  }
+  return customTypes;
+}
+
+/**
+ * Custom Heading types with no standalone rule in the generated CSS. A type
+ * whose every declaration the compiler dropped still passes the source check,
+ * and its augmentation would then name a type that has no styles.
+ *
+ * @param {Set<string>} types
+ * @param {string} css - Generated root component and media-surface rules.
+ * @returns {string[]}
+ */
+function headingTypesWithoutEmittedRule(types, css) {
+  /** @type {string[]} */
+  const missing = [];
+  for (const type of types) {
+    const selector = `.astryx-heading[data-type="${type}"]`;
+    let emitted = false;
+    for (
+      let at = css.indexOf(selector);
+      at !== -1 && !emitted;
+      at = css.indexOf(selector, at + 1)
+    ) {
+      // A following attribute is a combined selector, not the standalone rule.
+      emitted = css[at + selector.length] !== '[';
+    }
+    if (!emitted) missing.push(type);
+  }
+  return missing;
+}
+
 /**
  * Return true when a style object contains a declaration that the theme
- * generator can emit. Empty pseudo blocks do not count: they produce no CSS
- * and would leave the generated type augmentation without a usable rule.
+ * generator can emit. Empty pseudo blocks and blank values do not count: they
+ * produce no usable CSS and would leave the generated type augmentation
+ * without a usable rule.
  *
  * @param {unknown} styles
  * @returns {boolean}
@@ -1988,7 +2030,12 @@ function hasUsableStyleDeclaration(styles) {
       if (hasUsableStyleDeclaration(value)) return true;
       continue;
     }
-    if (value !== undefined && value !== null && typeof value !== 'object') {
+    if (
+      value !== undefined &&
+      value !== null &&
+      typeof value !== 'object' &&
+      String(value).trim() !== ''
+    ) {
       return true;
     }
   }
@@ -2163,14 +2210,14 @@ async function themeBuildInternal(
   const noticeMessages = [];
   for (const w of warnings) {
     warningMessages.push(w);
-    logger.warn(`  ⚠ ${w}`);
+    logger.warn(`  [warn] ${w}`);
   }
 
   // Validate no private vars are set directly
   const privateVarErrors = validatePrivateVars(themeDef);
   for (const e of privateVarErrors) {
     warningMessages.push(e);
-    logger.error(`  ✗ ${e}`);
+    logger.error(`  [error] ${e}`);
   }
   if (privateVarErrors.length > 0) {
     logger.error(
@@ -2196,7 +2243,7 @@ async function themeBuildInternal(
   // capability exports are checked against what the theme actually asks for.
   if (!_defineTheme || !_generateThemeRulesSplit) {
     throw new AstryxError(
-      'Could not load @astryxdesign/core/theme — `astryx theme build` requires a ' +
+      'Could not load @astryxdesign/core/theme: `astryx theme build` requires a ' +
         'built, resolvable @astryxdesign/core so it emits the same CSS as the ' +
         'runtime <Theme>. Build @astryxdesign/core first (e.g. `pnpm -F @astryxdesign/core ' +
         'build`)' +
@@ -2385,10 +2432,29 @@ async function themeBuildInternal(
     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(`  ⚠ ${w}`);
+      logger.warn(`  [warn] ${w}`);
+    }
+    const unemittedHeadingTypes = headingTypesWithoutEmittedRule(
+      customHeadingTypes(themeDef),
+      `${component.join('\n')}\n${onMediaCss}`,
+    );
+    if (unemittedHeadingTypes.length > 0) {
+      throw new AstryxError(
+        unemittedHeadingTypes
+          .map(
+            type =>
+              `Custom Heading type "${type}" has no declaration the theme ` +
+              `compiler could emit: every declaration in its standalone ` +
+              `"type:${type}" rule was dropped. Give that rule at least one ` +
+              'valid declaration.',
+          )
+          .join('\n'),
+        undefined,
+        ERROR_CODES.ERR_THEME_INVALID,
+      );
     }
     if (cssParts.length === 0) {
-      logger.log('No overrides found — nothing to build.');
+      logger.log('No overrides found; nothing to build.');
       return null;
     }
     // The data-token defaults are theme-independent and go in @layer
@@ -2439,7 +2505,18 @@ async function themeBuildInternal(
     // Guard: relative paths must not escape cwd via `../`. Absolute paths are
     // trusted (the user explicitly controls where output goes, like gcc -o).
     if (!path.isAbsolute(options.out)) {
-      assertWithin(options.out, cwd, {label: 'output path'});
+      try {
+        assertWithin(options.out, cwd, {label: 'output path'});
+      } catch (err) {
+        if (err instanceof PathSafetyError) {
+          throw new AstryxError(
+            err.message,
+            undefined,
+            ERROR_CODES.ERR_PATH_TRAVERSAL,
+          );
+        }
+        throw err;
+      }
     }
   } else {
     outPath = path.join(path.dirname(filePath), `${baseName}.css`);
@@ -2548,10 +2625,10 @@ async function themeBuildInternal(
     const stale = staleBuildOutputs(writes, cwd);
     const upToDate = stale.length === 0;
     if (upToDate) {
-      logger.log(`\n✓ Theme outputs are up to date with ${sourceRelative}.`);
+      logger.log(`\n[ok] Theme outputs are up to date with ${sourceRelative}.`);
     } else {
       logger.error(
-        `\n✗ ${stale.length} theme output(s) are out of date with ${sourceRelative}:`,
+        `\n[fail] ${stale.length} theme output(s) are out of date with ${sourceRelative}:`,
       );
       for (const s of stale) {
         logger.error(
@@ -2573,17 +2650,17 @@ async function themeBuildInternal(
 
   writeBuildOutputs(writes);
 
-  logger.log(`\n✓ ${path.relative(cwd, outPath)}`);
+  logger.log(`\n[ok] ${path.relative(cwd, outPath)}`);
   logger.log(
     `  ${tokenCount} token overrides, ${componentCount} component overrides`,
   );
   logger.log(`  ${size} KB`);
-  logger.log(`✓ ${path.relative(cwd, jsPath)}`);
-  logger.log(`✓ ${path.relative(cwd, dtsPath)}`);
+  logger.log(`[ok] ${path.relative(cwd, jsPath)}`);
+  logger.log(`[ok] ${path.relative(cwd, dtsPath)}`);
   if (variantDtsPath && variantDecl) {
     const augCount = (variantDecl.match(/': true;/g) || []).length;
     logger.log(
-      `✓ ${path.relative(cwd, variantDtsPath)} (${augCount} type augmentations)`,
+      `[ok] ${path.relative(cwd, variantDtsPath)} (${augCount} type augmentations)`,
     );
   }
 
@@ -2593,7 +2670,7 @@ async function themeBuildInternal(
   const cssImport = importSpecifier(relOutDir, cssBase) + '.css';
   const exportName = `${toIdentifier(baseName)}Theme`;
   logger.log(`
-Install in your app (paths are relative to a file in src/ — adjust if yours lives elsewhere):
+Install in your app (paths are relative to a file in src/; adjust if yours lives elsewhere):
 
   import { ${exportName} } from '${jsImport}';
   import '${cssImport}';
@@ -2625,7 +2702,7 @@ Or with a <link> tag:
   // Adaptation rules are resolved theme writes in their own right, so a family
   // named only inside one needs the same notice as one named at the root.
   for (const family of unloadedFonts) {
-    const msg = `Font "${family}" is named by this theme but not loaded — add a <link> or @font-face in your app (recipe: astryx docs typography)`;
+    const msg = `Font "${family}" is named by this theme but not loaded; add a <link> or @font-face in your app (recipe: astryx docs typography)`;
     noticeMessages.push(msg);
     logger.log(`  note: ${msg}`);
   }
@@ -2919,11 +2996,11 @@ export async function themeBuildFamily(
     const upToDate = stale.length === 0;
     if (upToDate) {
       logger.log(
-        `\n✓ Theme family outputs are up to date with ${sourceRelative}.`,
+        `\n[ok] Theme family outputs are up to date with ${sourceRelative}.`,
       );
     } else {
       logger.error(
-        `\n✗ ${stale.length} theme family output(s) are out of date:`,
+        `\n[fail] ${stale.length} theme family output(s) are out of date:`,
       );
       for (const entry of stale) {
         logger.error(
@@ -2943,7 +3020,7 @@ export async function themeBuildFamily(
     };
   }
   writeBuildOutputs(writes);
-  for (const output of Object.values(outputs)) logger.log(`✓ ${output}`);
+  for (const output of Object.values(outputs)) logger.log(`[ok] ${output}`);
   const themeBindings = members.map(member => bindings.get(member.theme.name));
   const relOutDir = path.relative(cwd, outDir) || '.';
   const jsImport = importSpecifier(relOutDir, baseName);
@@ -2961,7 +3038,7 @@ Or load the same stylesheet natively:
   ];
   const notices = unloadedFonts.map(
     family =>
-      `Font "${family}" is named by this theme family but not loaded — add a <link> or @font-face in your app (recipe: astryx docs typography)`,
+      `Font "${family}" is named by this theme family but not loaded; add a <link> or @font-face in your app (recipe: astryx docs typography)`,
   );
   for (const notice of notices) logger.log(`  note: ${notice}`);
   return {

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

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

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

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

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

@@ -211,11 +211,11 @@ export function formatFontLoadingHelp(themeName, families) {
   const first = families[0];
   const slug = first.toLowerCase().replace(/ /g, '-');
   return `
-⚠ Theme "${themeName}" names fonts it does not load: ${named}
-  The built CSS only sets font-family — load these in your app, or every
+[note] Theme "${themeName}" names fonts it does not load: ${named}
+  The built CSS only sets font-family; load these in your app, or every
   browser quietly falls back.
 
-  Google Fonts (add :wght@… axes as your theme's weights require):
+  Google Fonts (add :wght@... axes as your theme's weights require):
 
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />

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

@@ -227,12 +227,15 @@ describe('formatFontLoadingHelp', () => {
   const help = formatFontLoadingHelp('ocean', ['Fraunces', 'JetBrains Mono']);
 
   it('names the theme and every family in the headline', () => {
-    expect(help).toContain('⚠');
-    expect(help).toContain('ocean');
+    expect(help).toContain('[note] Theme "ocean"');
     expect(help).toContain('"Fraunces"');
     expect(help).toContain('"JetBrains Mono"');
   });
 
+  it('is plain ASCII', () => {
+    expect(help).not.toMatch(/[\u0080-\uffff]/);
+  });
+
   it('includes the Google Fonts recipe: preconnect pair + the exact css2 URL', () => {
     expect(help).toContain(
       '<link rel="preconnect" href="https://fonts.googleapis.com"',

package/api/theme/palette/generate/generate.mjs

@@ -86,7 +86,8 @@ function serializePalette(palette, indentation = 0) {
 
 /** @param {TonalPaletteCandidate} candidate */
 export function serializePaletteCandidate(candidate) {
-  return `{\n  "schemaVersion": 1,\n  "status": "candidate",\n  "recipe": ${JSON.stringify(candidate.recipe)},\n  "black": ${JSON.stringify(candidate.black)},\n  "white": ${JSON.stringify(candidate.white)},\n  "stops": ${JSON.stringify(candidate.stops)},\n  "palette": ${serializePalette(candidate.palette, 2)}\n}\n`;
+  const stops = candidate.stops.map(stop => `    ${JSON.stringify(stop)}`);
+  return `{\n  "schemaVersion": 1,\n  "status": "candidate",\n  "recipe": ${JSON.stringify(candidate.recipe)},\n  "black": ${JSON.stringify(candidate.black)},\n  "white": ${JSON.stringify(candidate.white)},\n  "stops": [\n${stops.join(',\n')}\n  ],\n  "palette": ${serializePalette(candidate.palette, 2)}\n}\n`;
 }
 
 /** @param {TonalPaletteCandidate} candidate @param {string} outputPath */
@@ -168,7 +169,11 @@ function existingFileIdentity(filePath) {
     ) {
       return null;
     }
-    throw error;
+    throw new AstryxError(
+      `Could not write palette candidate: ${error instanceof Error ? error.message : String(error)}`,
+      undefined,
+      ERROR_CODES.ERR_WRITE_FAILED,
+    );
   }
 }
 

package/api/theme/palette/generate/generate.test.mjs

@@ -1,9 +1,11 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+import {createHash} from 'node:crypto';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import {afterEach, describe, expect, it} from 'vitest';
+import {isErrorCode} from '../../../../foundation/response/error-codes.mjs';
 import {themePaletteGenerate} from './generate.mjs';
 
 const temporaryDirectories = [];
@@ -101,6 +103,81 @@ describe('themePaletteGenerate', () => {
     expect(result.data.receipt).toBe('ocean.palette.receipt.json');
   });
 
+  it('writes candidate JSON byte-identical to the recipe fixtures', () => {
+    const families = [
+      {id: 'neutral', name: 'Neutral', seed: '#777777', kind: 'neutral'},
+      {id: 'blue', name: 'Blue', seed: '#0074e2'},
+      {id: 'orange', name: 'Orange', seed: '#d57113'},
+    ];
+    const fixtures = [
+      [
+        {families},
+        3755,
+        '11c40191d508274d89d631bb4e1cb662f70ff0dce6c0dec101c317f9f69d3e25',
+      ],
+      [
+        {
+          modeStrategy: 'light-only',
+          stops: [20, 50, 80],
+          families: [
+            {
+              id: 'blue',
+              name: 'Blue',
+              seed: '#0074e2',
+              anchors: [
+                {mode: 'light', stop: 50, color: '#1682d5', policy: 'exact'},
+              ],
+            },
+          ],
+        },
+        327,
+        'c42929be3c4b5cb857cada078f62bb5a2242c1a22cfa4ae7546a18592540f7f3',
+      ],
+      [
+        {
+          modeStrategy: 'dark-only',
+          stops: [40],
+          families: [{id: 'red', name: 'Red', seed: '#d62830'}],
+        },
+        258,
+        '88d3d69865c74c7fb14347b9967575285a7d44ab893087a08bc842bb66b29bbb',
+      ],
+      [
+        {
+          stops: [60, 80, 95],
+          families: [
+            {id: 'green', name: 'Green', seed: '#358a3a'},
+            {id: 'teal', name: 'Teal', seed: '#0c7365'},
+            {id: 'cyan', name: 'Cyan', seed: '#0c6f82'},
+          ],
+        },
+        910,
+        '873821574fdbe3357304dbc06986bd2e5ec88af80d0f36305626fd826c3cf07b',
+      ],
+    ];
+
+    for (const [request, bytes, sha256] of fixtures) {
+      const cwd = fixture();
+      fs.writeFileSync(
+        path.join(cwd, 'palette.config.json'),
+        JSON.stringify(request),
+      );
+
+      const printed = themePaletteGenerate('palette.config.json', {}, {cwd});
+      expect(printed.data.generationReceipt.candidateSha256).toBe(sha256);
+
+      const result = themePaletteGenerate(
+        'palette.config.json',
+        {out: 'candidate.json'},
+        {cwd},
+      );
+      const written = fs.readFileSync(path.join(cwd, 'candidate.json'));
+      expect(written.length).toBe(bytes);
+      expect(createHash('sha256').update(written).digest('hex')).toBe(sha256);
+      expect(result.data.generationReceipt.candidateSha256).toBe(sha256);
+    }
+  });
+
   it('preserves mixed decimal and integer stop order in every artifact', () => {
     const cwd = fixture();
     fs.writeFileSync(
@@ -267,4 +344,23 @@ describe('themePaletteGenerate', () => {
       themePaletteGenerate('palette.config.json', {}, {cwd}),
     ).toThrow('Could not parse palette config');
   });
+
+  it('reports an output path it cannot use with a registered error code', () => {
+    const cwd = fixture();
+    fs.writeFileSync(path.join(cwd, 'blocker'), '');
+
+    for (const options of [
+      {out: 'blocker/ocean.palette.json'},
+      {preview: 'blocker/ocean.palette.html'},
+    ]) {
+      let error;
+      try {
+        themePaletteGenerate('palette.config.json', options, {cwd});
+      } catch (caught) {
+        error = caught;
+      }
+      expect(error).toMatchObject({code: 'ERR_WRITE_FAILED'});
+      expect(isErrorCode(error.code)).toBe(true);
+    }
+  });
 });

package/api/theme/palette/generate/generator.mjs

@@ -37,6 +37,7 @@ export const COMPACT_11_STOPS = Object.freeze([
 
 const DARK_CHROMA_FACTOR = 0.85;
 const RESERVED_FAMILY_IDS = new Set(['black', 'white']);
+const NEUTRAL_PROFILES = ['neutral-v1', 'warm-v1', 'cool-v1', 'custom'];
 
 /** @param {number} value @param {number} minimum @param {number} maximum */
 function clamp(value, minimum, maximum) {
@@ -665,11 +666,17 @@ export function normalizeGenerationRequest(input) {
       anchors,
     };
   });
+  const neutralProfile = input.neutralProfile ?? 'neutral-v1';
+  // The receipt records this request, so an unknown profile fails even when no
+  // neutral family reads it.
+  if (!NEUTRAL_PROFILES.includes(neutralProfile)) {
+    throw new Error(`Unknown neutral profile: ${String(neutralProfile)}`);
+  }
   /** @type {NormalizedRequest} */
   const request = {
     recipe: PALETTE_RECIPE,
     vibrancy: input.vibrancy ?? 50,
-    neutralProfile: input.neutralProfile ?? 'neutral-v1',
+    neutralProfile,
     modeStrategy,
     stops,
     families: normalizedFamilies,

package/api/theme/palette/generate/generator.test.mjs

@@ -293,6 +293,16 @@ describe('astryx-oklch-v1 palette generator', () => {
     ).toThrow('Anchor mode dark is not generated by mode strategy light-only');
   });
 
+  it('rejects an unknown neutral profile even without a neutral family', () => {
+    expect(() =>
+      generatePaletteSet({neutralProfile: 'warm-v2', families: [families[1]]}),
+    ).toThrow('Unknown neutral profile: warm-v2');
+    expect(
+      generatePaletteSet({neutralProfile: 'warm-v1', families: [families[1]]})
+        .request.neutralProfile,
+    ).toBe('warm-v1');
+  });
+
   it('normalizes anchor colors in the generation receipt', () => {
     const result = generatePaletteSet({
       modeStrategy: 'light-only',

package/api/theme/template/template.mjs

@@ -62,8 +62,17 @@ export function themeTemplate(options = {}) {
 
   // Our repo header has no business in someone else's source tree.
   const contents = stripCopyrightHeader(fs.readFileSync(THEME_TEMPLATE_SRC, 'utf-8'));
-  fs.mkdirSync(path.dirname(resolved), {recursive: true});
-  fs.writeFileSync(resolved, contents);
+  try {
+    fs.mkdirSync(path.dirname(resolved), {recursive: true});
+    fs.writeFileSync(resolved, contents);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new AstryxError(
+      `Failed to write the theme template to ${relative}: ${message}`,
+      undefined,
+      ERROR_CODES.ERR_WRITE_FAILED,
+    );
+  }
 
   return {type: 'theme.template', data: {path: relative, written: true, reason: null}};
 }

package/api/theme/template/template.test.mjs

@@ -14,6 +14,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import {themeTemplate, THEME_TEMPLATE_DEFAULT_PATH} from './template.mjs';
+import {isErrorCode} from '../../../foundation/response/error-codes.mjs';
 
 let tmpDir;
 beforeEach(() => {
@@ -79,4 +80,18 @@ describe('themeTemplate()', () => {
     );
     expect(fs.existsSync(path.join(path.dirname(tmpDir), 'escaped.ts'))).toBe(false);
   });
+
+  it('reports a failed write with a registered error code', () => {
+    fs.writeFileSync(path.join(tmpDir, 'blocker'), '');
+
+    let error;
+    try {
+      themeTemplate({cwd: tmpDir, targetPath: 'blocker/theme.ts'});
+    } catch (caught) {
+      error = caught;
+    }
+
+    expect(error).toMatchObject({code: 'ERR_WRITE_FAILED'});
+    expect(isErrorCode(error.code)).toBe(true);
+  });
 });