@astryxdesign/cli 0.6.3-canary.98a2e4e → 0.6.3-canary.9c4d44d

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 */
@@ -100,7 +101,7 @@ function serializeCandidate(candidate, outputPath) {
   );
 }
 
-/** @param {PaletteGenerationResult} result @param {string} candidateText @param {string | null} [previewText] */
+/** @param {PaletteGenerationResult} result @param {string} candidateText @param {string | null} [previewText] @returns {import('../../theme.type.mjs').TonalPaletteGenerationReceipt} */
 function receiptFor(result, candidateText, previewText = null) {
   return {
     schemaVersion: 1,
@@ -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.d.mts

@@ -22,15 +22,17 @@ export function generateTonalPalette(input: import("../../theme.type.mjs").Tonal
 export function serializeGenerationResult(result: unknown): string;
 /** @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";
 export const PALETTE_WHITE: "#ffffff";
@@ -38,6 +40,9 @@ export const DEFAULT_21_STOPS: readonly number[];
 export const COMPACT_11_STOPS: readonly number[];
 export type TonalPaletteAnchor = import("../../theme.type.mjs").TonalPaletteAnchor;
 export type TonalPaletteGenerationInput = import("../../theme.type.mjs").TonalPaletteGenerationInput;
+export type TonalPaletteRampDiagnostics = import("../../theme.type.mjs").TonalPaletteRampDiagnostics;
+export type TonalPaletteCoordinationDiagnostics = import("../../theme.type.mjs").TonalPaletteCoordinationDiagnostics;
+export type NormalizedRequest = import("../../theme.type.mjs").TonalPaletteNormalizedRequest;
 export type ColorTriple = [number, number, number];
 export type PaletteMode = "light" | "dark";
 export type PolarColor = {
@@ -52,7 +57,7 @@ export type AnchorResult = TonalPaletteAnchor & {
 };
 export type GeneratedRamp = {
     colors: Record<number, string>;
-    diagnostics: Record<string, unknown>;
+    diagnostics: TonalPaletteRampDiagnostics;
 };
 export type NormalizedFamily = {
     id: string;
@@ -61,14 +66,6 @@ export type NormalizedFamily = {
     kind: "chromatic" | "neutral";
     anchors: TonalPaletteAnchor[];
 };
-export type NormalizedRequest = {
-    recipe: typeof PALETTE_RECIPE;
-    vibrancy: number;
-    neutralProfile: string;
-    modeStrategy: string;
-    stops: number[];
-    families: NormalizedFamily[];
-};
 export type GeneratedFamily = {
     id: string;
     name: string;
@@ -81,7 +78,7 @@ export type PaletteGenerationResult = {
     status: "candidate";
     request: NormalizedRequest;
     families: GeneratedFamily[];
-    coordination: Record<string, unknown>[];
+    coordination: TonalPaletteCoordinationDiagnostics[];
     errors: {
         familyId: string;
         message: string;

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;
     };
 };