@astryxdesign/cli 0.6.3 → 0.6.4-canary.078fd25

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

@@ -12,15 +12,17 @@ import {
 
 /** @typedef {import('../../theme.type.mjs').TonalPaletteAnchor} TonalPaletteAnchor */
 /** @typedef {import('../../theme.type.mjs').TonalPaletteGenerationInput} TonalPaletteGenerationInput */
+/** @typedef {import('../../theme.type.mjs').TonalPaletteRampDiagnostics} TonalPaletteRampDiagnostics */
+/** @typedef {import('../../theme.type.mjs').TonalPaletteCoordinationDiagnostics} TonalPaletteCoordinationDiagnostics */
+/** @typedef {import('../../theme.type.mjs').TonalPaletteNormalizedRequest} NormalizedRequest */
 /** @typedef {[number, number, number]} ColorTriple */
 /** @typedef {'light' | 'dark'} PaletteMode */
 /** @typedef {{lightness: number, chroma: number, hue: number}} PolarColor */
 /** @typedef {TonalPaletteAnchor & {color: string, generatedColor: string, deltaE: number}} AnchorResult */
-/** @typedef {{colors: Record<number, string>, diagnostics: Record<string, unknown>}} GeneratedRamp */
+/** @typedef {{colors: Record<number, string>, diagnostics: TonalPaletteRampDiagnostics}} GeneratedRamp */
 /** @typedef {{id: string, name: string, seed: string, kind: 'chromatic' | 'neutral', anchors: TonalPaletteAnchor[]}} NormalizedFamily */
-/** @typedef {{recipe: typeof PALETTE_RECIPE, vibrancy: number, neutralProfile: string, modeStrategy: string, stops: number[], families: NormalizedFamily[]}} NormalizedRequest */
 /** @typedef {{id: string, name: string, seed: string, light?: GeneratedRamp, dark?: GeneratedRamp}} GeneratedFamily */
-/** @typedef {{recipe: typeof PALETTE_RECIPE, status: 'candidate', request: NormalizedRequest, families: GeneratedFamily[], coordination: Record<string, unknown>[], errors: {familyId: string, message: string}[]}} PaletteGenerationResult */
+/** @typedef {{recipe: typeof PALETTE_RECIPE, status: 'candidate', request: NormalizedRequest, families: GeneratedFamily[], coordination: TonalPaletteCoordinationDiagnostics[], errors: {familyId: string, message: string}[]}} PaletteGenerationResult */
 
 export const PALETTE_RECIPE = 'astryx-oklch-v1';
 export const PALETTE_BLACK = '#000000';
@@ -35,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) {
@@ -411,6 +414,7 @@ function buildDiagnostics(colors, stops, sourceHue, gamutMappedStops, anchors) {
   let minimumAdjacentDeltaE = Number.POSITIVE_INFINITY;
   let maximumAdjacentDeltaE = 0;
   let maximumHueDrift = 0;
+  /** @type {TonalPaletteRampDiagnostics['hueIdentityRisk']} */
   let hueIdentityRisk = null;
   for (let index = 0; index < stops.length; index++) {
     const stop = stops[index];
@@ -526,6 +530,7 @@ function buildCoordinationDiagnostics(request, families) {
           chroma: hexToOklch(color).C,
         };
       });
+    /** @type {[string, string] | null} */
     let closestFamilies = null;
     let minimumFamilyDeltaE = Number.POSITIVE_INFINITY;
     for (let index = 0; index < samples.length; index++) {
@@ -661,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

@@ -13,7 +13,9 @@ import {describe, it, expect, beforeEach, afterEach} from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
+import {themeTemplate as publicThemeTemplate} from '../../index.mjs';
 import {themeTemplate, THEME_TEMPLATE_DEFAULT_PATH} from './template.mjs';
+import {isErrorCode} from '../../../foundation/response/error-codes.mjs';
 
 let tmpDir;
 beforeEach(() => {
@@ -24,6 +26,10 @@ afterEach(() => {
 });
 
 describe('themeTemplate()', () => {
+  it('is available through the public API entry point', () => {
+    expect(publicThemeTemplate).toBe(themeTemplate);
+  });
+
   it('writes the template and returns a theme.template receipt', () => {
     const res = themeTemplate({cwd: tmpDir});
 
@@ -79,4 +85,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);
+  });
 });

package/api/theme/theme.type.d.mts

@@ -2,7 +2,7 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * xds --json theme build <file>
+ * astryx --json theme build <file>
  */
 export type ThemeBuildResponse = {
     /**
@@ -27,7 +27,7 @@ export type ThemeBuildResponse = {
     };
 };
 /**
- * xds --json theme build <file> --check
+ * astryx --json theme build <file> --check
  */
 export type ThemeBuildCheckResponse = {
     type: "theme.build.check";
@@ -42,7 +42,7 @@ export type ThemeBuildCheckResponse = {
     };
 };
 /**
- * xds --json theme build <a> <b> … — several themes in one invocation. Each
+ * astryx --json theme build <a> <b> … — several themes in one invocation. Each
  * result carries the file as it was passed and the receipt a single-file build
  * would have returned (null when that theme produced no CSS). One file still
  * returns the bare theme.build / theme.build.check envelope.
@@ -71,14 +71,14 @@ export type ThemeListEntry = {
     package?: string | undefined;
 };
 /**
- * xds --json theme list
+ * astryx --json theme list
  */
 export type ThemeListResponse = {
     type: "theme.list";
     data: ThemeListEntry[];
 };
 /**
- * xds --json theme add <slug>
+ * astryx --json theme add <slug>
  */
 export type ThemeAddResponse = {
     type: "theme.add";
@@ -94,7 +94,7 @@ export type ThemeAddResponse = {
     };
 };
 /**
- * xds --json theme template
+ * astryx --json theme template
  * `written: false` with `reason: 'exists'` is a success: the command is safe to
  * re-run, and an edited template is the consumer's file to keep.
  */
@@ -123,7 +123,7 @@ export type ThemeTargetEntry = {
     deprecatedFor?: string | undefined;
 };
 /**
- * xds --json theme targets [filter]
+ * astryx --json theme targets [filter]
  */
 export type ThemeTargetsResponse = {
     type: "theme.targets";
@@ -134,8 +134,7 @@ export type ThemeTargetsResponse = {
     };
 };
 /**
- * A generated palette candidate. The palette is still subject to author review
- * and is not connected to runtime theme values.
+ * A color an author pins at one stop of one mode, constraining generation.
  */
 export type TonalPaletteAnchor = {
     /**
@@ -146,6 +145,10 @@ export type TonalPaletteAnchor = {
      * Existing requested stop where the anchor applies.
      */
     stop: number;
+    /**
+     * sRGB hex the stop is pulled toward: three or six
+     * digits, with or without `#`; the generator normalizes it.
+     */
     color: string;
     /**
      * `exact` preserves the
@@ -159,11 +162,32 @@ export type TonalPaletteAnchor = {
      */
     maxDeltaE?: number | undefined;
 };
+/**
+ * One requested family: a seed color and the constraints applied to its ramp.
+ */
 export type TonalPaletteFamilyInput = {
+    /**
+     * Lower-kebab-case key for the family in the generated
+     * palette. `black` and `white` are reserved for the standalone values.
+     */
     id: string;
+    /**
+     * sRGB hex the ramp is generated from: three or six
+     * digits, with or without `#`; the generator normalizes it.
+     */
     seed: string;
+    /**
+     * Display name for review artifacts; defaults to `id`.
+     */
     name?: string | undefined;
+    /**
+     * `neutral` derives the ramp from
+     * `neutralProfile` instead of the seed hue; defaults to `chromatic`.
+     */
     kind?: "neutral" | "chromatic" | undefined;
+    /**
+     * Colors pinned at specific stops.
+     */
     anchors?: TonalPaletteAnchor[] | undefined;
 };
 export type TonalPaletteGenerationInput = {
@@ -173,6 +197,11 @@ export type TonalPaletteGenerationInput = {
      * (default) to 100 (most vivid).
      */
     vibrancy?: number | undefined;
+    /**
+     * Hue treatment for `neutral` families: `neutral-v1` is fully achromatic,
+     * `warm-v1` and `cool-v1` add a slight tint, and `custom` derives the hue from
+     * the family's own seed. Defaults to `neutral-v1`.
+     */
     neutralProfile?: "custom" | "neutral-v1" | "warm-v1" | "cool-v1" | undefined;
     modeStrategy?: "light-only" | "dark-only" | "light-and-dark" | undefined;
     /**
@@ -182,6 +211,10 @@ export type TonalPaletteGenerationInput = {
      */
     stops?: number[] | undefined;
 };
+/**
+ * A generated palette candidate. The palette is still subject to author review
+ * and is not connected to runtime theme values.
+ */
 export type TonalPaletteCandidate = {
     schemaVersion: 1;
     status: "candidate";
@@ -205,7 +238,133 @@ export type TonalPaletteCandidate = {
     }>;
 };
 /**
- * xds --json theme palette generate <config>
+ * Per-ramp evidence recorded for one family in one mode.
+ */
+export type TonalPaletteRampDiagnostics = {
+    /**
+     * Whether luminance rises across every stop.
+     */
+    monotonic: boolean;
+    /**
+     * Smallest perceptual gap between
+     * neighboring stops; a small value means two stops read as one color.
+     */
+    minimumAdjacentDeltaE: number;
+    /**
+     * Largest gap between neighboring stops.
+     */
+    maximumAdjacentDeltaE: number;
+    /**
+     * Largest hue distance, in degrees, between
+     * a stop and the family's reference hue.
+     */
+    maximumHueDrift: number;
+    /**
+     * Named
+     * drift the ramp is at risk of, or `null`.
+     */
+    hueIdentityRisk: "blue-to-purple" | "yellow-to-brown" | null;
+    /**
+     * Stops whose ideal color fell outside
+     * sRGB and was mapped back into it.
+     */
+    gamutMappedStops: number[];
+    /**
+     * Each anchor with the color the stop received after its policy was applied
+     * and the perceptual distance that color still has from the requested target.
+     */
+    anchors: Array<TonalPaletteAnchor & {
+        generatedColor: string;
+        deltaE: number;
+    }>;
+};
+/**
+ * Cross-family evidence for one mode, sampled at the stop nearest 50.
+ */
+export type TonalPaletteCoordinationDiagnostics = {
+    /**
+     * Mode these samples come from.
+     */
+    mode: "light" | "dark";
+    /**
+     * Sampled stop.
+     */
+    stop: number;
+    /**
+     * The two chromatic
+     * families hardest to tell apart, or `null` with fewer than two.
+     */
+    closestFamilies: [string, string] | null;
+    /**
+     * Perceptual distance between them.
+     */
+    minimumFamilyDeltaE: number | null;
+    /**
+     * Most saturated family at this stop.
+     */
+    strongestFamily: string | null;
+    /**
+     * Least saturated family at this stop.
+     */
+    weakestFamily: string | null;
+    /**
+     * Strongest chroma over weakest; a large
+     * ratio means the families are unbalanced.
+     */
+    chromaRatio: number | null;
+};
+/**
+ * The request as the generator resolved it, with every default filled in.
+ */
+export type TonalPaletteNormalizedRequest = {
+    recipe: "astryx-oklch-v1";
+    vibrancy: number;
+    neutralProfile: "neutral-v1" | "warm-v1" | "cool-v1" | "custom";
+    modeStrategy: "light-only" | "dark-only" | "light-and-dark";
+    stops: number[];
+    families: Array<{
+        id: string;
+        name: string;
+        seed: string;
+        kind: "chromatic" | "neutral";
+        anchors: TonalPaletteAnchor[];
+    }>;
+};
+/**
+ * The detached receipt written beside a candidate. It records what was asked
+ * for and what the generator observed, so a candidate can be traced back to
+ * its request without rerunning generation.
+ */
+export type TonalPaletteGenerationReceipt = {
+    schemaVersion: 1;
+    /**
+     * Recipe that produced the candidate.
+     */
+    recipe: "astryx-oklch-v1";
+    /**
+     * SHA-256 over the candidate bytes as written.
+     */
+    candidateSha256: string;
+    /**
+     * Present when preview
+     * content was generated for the request, even if no file was written because
+     * the target already exists.
+     */
+    preview?: {
+        version: string;
+        sha256: string;
+    } | undefined;
+    request: TonalPaletteNormalizedRequest;
+    diagnostics: {
+        families: Record<string, {
+            light?: TonalPaletteRampDiagnostics;
+            dark?: TonalPaletteRampDiagnostics;
+        }>;
+        coordination: TonalPaletteCoordinationDiagnostics[];
+    };
+};
+/**
+ * astryx --json theme palette generate <config>
  */
 export type ThemePaletteGenerateResponse = {
     type: "theme.palette.generate";
@@ -221,6 +380,6 @@ export type ThemePaletteGenerateResponse = {
         written: boolean;
         reason: "exists" | null;
         candidate: TonalPaletteCandidate;
-        generationReceipt: Record<string, unknown>;
+        generationReceipt: TonalPaletteGenerationReceipt;
     };
 };

package/api/theme/theme.type.mjs

@@ -6,23 +6,23 @@
  * directly (functions own their types); the public `@astryxdesign/cli/api`
  * surface re-exports them via types/theme.d.ts, so consumers see the same names.
  *
- * Invocation                                 -> type discriminator
+ * Invocation                                  -> type discriminator
  * ------------------------------------------------------------------
- * xds --json theme build <file>             -> theme.build
- * xds --json theme build <file> --check     -> theme.build.check
- * xds --json theme build <a> <b> …          -> theme.build.batch
- * xds --json theme list                     -> theme.list
- * xds --json theme add <slug>               -> theme.add
- * xds --json theme template                 -> theme.template
- * xds --json theme targets [filter]         -> theme.targets
- * xds --json theme palette generate <file>  -> theme.palette.generate
- * (file not found / parse error)            -> CLIError
+ * astryx --json theme build <file>            -> theme.build
+ * astryx --json theme build <file> --check    -> theme.build.check
+ * astryx --json theme build <a> <b> …         -> theme.build.batch
+ * astryx --json theme list                    -> theme.list
+ * astryx --json theme add <slug>              -> theme.add
+ * astryx --json theme template                -> theme.template
+ * astryx --json theme targets [filter]        -> theme.targets
+ * astryx --json theme palette generate <file> -> theme.palette.generate
+ * (file not found / parse error)              -> CLIError
  *
  * @position api — colocated typedefs for api/theme/{theme,build,add,list,template,targets,_adapter}
  */
 
 /**
- * xds --json theme build <file>
+ * astryx --json theme build <file>
  * @typedef {object} ThemeBuildResponse
  * @property {'theme.build'} type
  * `warnings` are defects the theme author should fix. `notices` are advisories
@@ -32,14 +32,14 @@
  */
 
 /**
- * xds --json theme build <file> --check
+ * astryx --json theme build <file> --check
  * @typedef {object} ThemeBuildCheckResponse
  * @property {'theme.build.check'} type
  * @property {{name: string, upToDate: boolean, stale: Array<{path: string, reason: 'missing' | 'outdated'}>, checked: string[]}} data
  */
 
 /**
- * xds --json theme build <a> <b> … — several themes in one invocation. Each
+ * astryx --json theme build <a> <b> … — several themes in one invocation. Each
  * result carries the file as it was passed and the receipt a single-file build
  * would have returned (null when that theme produced no CSS). One file still
  * returns the bare theme.build / theme.build.check envelope.
@@ -59,21 +59,21 @@
  */
 
 /**
- * xds --json theme list
+ * astryx --json theme list
  * @typedef {object} ThemeListResponse
  * @property {'theme.list'} type
  * @property {ThemeListEntry[]} data
  */
 
 /**
- * xds --json theme add <slug>
+ * astryx --json theme add <slug>
  * @typedef {object} ThemeAddResponse
  * @property {'theme.add'} type
  * @property {{slug: string, displayName: string, maintained: boolean, package: string, outputDir: string, entry: string, exportName: string, files: string[]}} data
  */
 
 /**
- * xds --json theme template
+ * astryx --json theme template
  * `written: false` with `reason: 'exists'` is a success: the command is safe to
  * re-run, and an edited template is the consumer's file to keep.
  * @typedef {object} ThemeTemplateResponse
@@ -95,19 +95,19 @@
  */
 
 /**
- * xds --json theme targets [filter]
+ * astryx --json theme targets [filter]
  * @typedef {object} ThemeTargetsResponse
  * @property {'theme.targets'} type
  * @property {{filter: string | null, componentCount: number, targets: ThemeTargetEntry[]}} data
  */
 
 /**
- * A generated palette candidate. The palette is still subject to author review
- * and is not connected to runtime theme values.
+ * A color an author pins at one stop of one mode, constraining generation.
  * @typedef {object} TonalPaletteAnchor
  * @property {'light' | 'dark'} mode Mode containing the anchored stop.
  * @property {number} stop Existing requested stop where the anchor applies.
- * @property {string} color
+ * @property {string} color sRGB hex the stop is pulled toward: three or six
+ * digits, with or without `#`; the generator normalizes it.
  * @property {'exact' | 'bounded' | 'flexible'} policy `exact` preserves the
  * chosen color at that stop; `bounded` permits adjustment within `maxDeltaE`;
  * `flexible` treats the color as guidance and blends toward it.
@@ -116,12 +116,16 @@
  */
 
 /**
+ * One requested family: a seed color and the constraints applied to its ramp.
  * @typedef {object} TonalPaletteFamilyInput
- * @property {string} id
- * @property {string} seed
- * @property {string} [name]
- * @property {'chromatic' | 'neutral'} [kind]
- * @property {TonalPaletteAnchor[]} [anchors]
+ * @property {string} id Lower-kebab-case key for the family in the generated
+ * palette. `black` and `white` are reserved for the standalone values.
+ * @property {string} seed sRGB hex the ramp is generated from: three or six
+ * digits, with or without `#`; the generator normalizes it.
+ * @property {string} [name] Display name for review artifacts; defaults to `id`.
+ * @property {'chromatic' | 'neutral'} [kind] `neutral` derives the ramp from
+ * `neutralProfile` instead of the seed hue; defaults to `chromatic`.
+ * @property {TonalPaletteAnchor[]} [anchors] Colors pinned at specific stops.
  */
 
 /**
@@ -130,6 +134,9 @@
  * @property {number} [vibrancy] Chroma control from 0 (most muted) through 50
  * (default) to 100 (most vivid).
  * @property {'neutral-v1' | 'warm-v1' | 'cool-v1' | 'custom'} [neutralProfile]
+ * Hue treatment for `neutral` families: `neutral-v1` is fully achromatic,
+ * `warm-v1` and `cool-v1` add a slight tint, and `custom` derives the hue from
+ * the family's own seed. Defaults to `neutral-v1`.
  * @property {'light-only' | 'dark-only' | 'light-and-dark'} [modeStrategy]
  * @property {number[]} [stops] Ordered stops shared by every requested family;
  * defaults to 0 through 100 in increments of 5. Decimal stops are supported,
@@ -137,6 +144,8 @@
  */
 
 /**
+ * A generated palette candidate. The palette is still subject to author review
+ * and is not connected to runtime theme values.
  * @typedef {object} TonalPaletteCandidate
  * @property {1} schemaVersion
  * @property {'candidate'} status
@@ -148,10 +157,68 @@
  */
 
 /**
- * xds --json theme palette generate <config>
+ * Per-ramp evidence recorded for one family in one mode.
+ * @typedef {object} TonalPaletteRampDiagnostics
+ * @property {boolean} monotonic Whether luminance rises across every stop.
+ * @property {number} minimumAdjacentDeltaE Smallest perceptual gap between
+ * neighboring stops; a small value means two stops read as one color.
+ * @property {number} maximumAdjacentDeltaE Largest gap between neighboring stops.
+ * @property {number} maximumHueDrift Largest hue distance, in degrees, between
+ * a stop and the family's reference hue.
+ * @property {'blue-to-purple' | 'yellow-to-brown' | null} hueIdentityRisk Named
+ * drift the ramp is at risk of, or `null`.
+ * @property {number[]} gamutMappedStops Stops whose ideal color fell outside
+ * sRGB and was mapped back into it.
+ * @property {Array<TonalPaletteAnchor & {generatedColor: string, deltaE: number}>} anchors
+ * Each anchor with the color the stop received after its policy was applied
+ * and the perceptual distance that color still has from the requested target.
+ */
+
+/**
+ * Cross-family evidence for one mode, sampled at the stop nearest 50.
+ * @typedef {object} TonalPaletteCoordinationDiagnostics
+ * @property {'light' | 'dark'} mode Mode these samples come from.
+ * @property {number} stop Sampled stop.
+ * @property {[string, string] | null} closestFamilies The two chromatic
+ * families hardest to tell apart, or `null` with fewer than two.
+ * @property {number | null} minimumFamilyDeltaE Perceptual distance between them.
+ * @property {string | null} strongestFamily Most saturated family at this stop.
+ * @property {string | null} weakestFamily Least saturated family at this stop.
+ * @property {number | null} chromaRatio Strongest chroma over weakest; a large
+ * ratio means the families are unbalanced.
+ */
+
+/**
+ * The request as the generator resolved it, with every default filled in.
+ * @typedef {object} TonalPaletteNormalizedRequest
+ * @property {'astryx-oklch-v1'} recipe
+ * @property {number} vibrancy
+ * @property {'neutral-v1' | 'warm-v1' | 'cool-v1' | 'custom'} neutralProfile
+ * @property {'light-only' | 'dark-only' | 'light-and-dark'} modeStrategy
+ * @property {number[]} stops
+ * @property {Array<{id: string, name: string, seed: string, kind: 'chromatic' | 'neutral', anchors: TonalPaletteAnchor[]}>} families
+ */
+
+/**
+ * The detached receipt written beside a candidate. It records what was asked
+ * for and what the generator observed, so a candidate can be traced back to
+ * its request without rerunning generation.
+ * @typedef {object} TonalPaletteGenerationReceipt
+ * @property {1} schemaVersion
+ * @property {'astryx-oklch-v1'} recipe Recipe that produced the candidate.
+ * @property {string} candidateSha256 SHA-256 over the candidate bytes as written.
+ * @property {{version: string, sha256: string}} [preview] Present when preview
+ * content was generated for the request, even if no file was written because
+ * the target already exists.
+ * @property {TonalPaletteNormalizedRequest} request
+ * @property {{families: Record<string, {light?: TonalPaletteRampDiagnostics, dark?: TonalPaletteRampDiagnostics}>, coordination: TonalPaletteCoordinationDiagnostics[]}} diagnostics
+ */
+
+/**
+ * astryx --json theme palette generate <config>
  * @typedef {object} ThemePaletteGenerateResponse
  * @property {'theme.palette.generate'} type
- * @property {{recipe: 'astryx-oklch-v1', status: 'candidate', familyCount: number, stopCount: number, modes: string[], output: string | null, receipt: string | null, preview: string | null, written: boolean, reason: 'exists' | null, candidate: TonalPaletteCandidate, generationReceipt: Record<string, unknown>}} data
+ * @property {{recipe: 'astryx-oklch-v1', status: 'candidate', familyCount: number, stopCount: number, modes: string[], output: string | null, receipt: string | null, preview: string | null, written: boolean, reason: 'exists' | null, candidate: TonalPaletteCandidate, generationReceipt: TonalPaletteGenerationReceipt}} data
  */
 
 // Make this a module so the @typedefs above are importable as types via