@astryxdesign/cli 0.6.3 → 0.6.4-canary.06c8fa3

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

@@ -206,6 +206,133 @@ describe('themeBuild() — receipt', () => {
   });
 });
 
+describe('themeBuild() — dropped declarations reach the receipt', () => {
+  // Core's generator refuses a declaration whose value would end it early
+  // (an unquoted `;` or brace, an unclosed string/comment/url). The runtime
+  // says so on the console; a build has a receipt, so every drop must land in
+  // `warnings` — a programmatic caller otherwise sees `warnings: []` while the
+  // CSS silently omits a value the generated JS still carries.
+  it('reports every dropped declaration, from every generator path, in warnings', async () => {
+    const themeFile = path.join(tmpDir, 'dropped.mjs');
+    fs.writeFileSync(
+      themeFile,
+      `export default {
+        name: 'dropped',
+        tokens: {
+          '--color-bg': '#0a0a0a } body { background: url(https://example.com/token) ',
+        },
+        components: {
+          button: {
+            'variant:secondary': {
+              backgroundColor: 'red; background-image: url(https://example.com/component)',
+              ':hover': {color: '"https://example.com/pseudo'},
+            },
+          },
+        },
+        onDark: {
+          tokens: {'--color-bg': 'url(https://example.com/dark'},
+        },
+        adaptations: {
+          rules: [
+            {
+              when: {pointer: 'coarse'},
+              value: {tokens: {'--color-bg': 'red /* https://example.com/adaptation'}},
+            },
+          ],
+        },
+      };\n`,
+    );
+
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    let result;
+    try {
+      result = await themeBuild('dropped.mjs', {}, {cwd: tmpDir});
+      // Drops are collected, not printed: the programmatic API stays silent.
+      expect(warnSpy).not.toHaveBeenCalled();
+    } finally {
+      warnSpy.mockRestore();
+    }
+
+    const css = fs.readFileSync(path.join(tmpDir, 'dropped.css'), 'utf8');
+    expect(css).not.toContain('example.com');
+
+    const warnings = result?.data.warnings ?? [];
+    expect(warnings).toHaveLength(5);
+    expect(warnings).toEqual(
+      expect.arrayContaining([
+        expect.stringMatching(
+          /^Declaration dropped "--color-bg" in tokens: an unquoted "}" would close the rule/,
+        ),
+        expect.stringMatching(
+          /^Declaration dropped "background-color" in components\.button\["variant:secondary"\]: an unquoted ";" would end the declaration/,
+        ),
+        expect.stringMatching(
+          /^Declaration dropped "color" in components\.button\["variant:secondary"\]\[":hover"\]: an unclosed " string/,
+        ),
+        expect.stringMatching(
+          /^Declaration dropped "--color-bg" in onDark\.tokens: an unclosed url\(/,
+        ),
+        expect.stringMatching(
+          /^Declaration dropped "--color-bg" in adaptations\[0\]\.tokens: an unclosed \/\* comment/,
+        ),
+      ]),
+    );
+    for (const w of warnings) {
+      expect(w).toContain('The generated CSS omits it');
+    }
+  });
+
+  it('generates CSS for legacy null tokens without losing neighboring declarations', async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, 'legacy.mjs'),
+      `export default {
+        name: 'legacy',
+        tokens: {'--color-background-body': null, '--spacing-4': 12},
+        onDark: {tokens: {'--color-background-body': null}},
+        components: {button: {base: {borderRadius: '4px'}}},
+      };\n`,
+    );
+
+    const result = await themeBuild('legacy.mjs', {}, {cwd: tmpDir});
+    const css = fs.readFileSync(path.join(tmpDir, 'legacy.css'), 'utf8');
+    expect(css).toContain('--color-background-body: null;');
+    expect(css).toContain('--spacing-4: 12;');
+    expect(css).toContain('border-radius: 4px;');
+    expect(result?.data.warnings).toEqual([]);
+  });
+
+  it('keeps valid CSS that carries semicolons, and reports nothing', async () => {
+    const themeFile = path.join(tmpDir, 'kept.mjs');
+    fs.writeFileSync(
+      themeFile,
+      `export default {
+        name: 'kept',
+        tokens: {'--font-family-body': 'Gill\\\\ Sans, "Segoe;UI", serif /* ; */'},
+        components: {
+          button: {
+            'variant:secondary': {
+              backgroundImage: 'URL(data:image/svg+xml;base64,PHN2Zz4=)',
+              WebkitLineClamp: '2',
+            },
+          },
+        },
+      };\n`,
+    );
+
+    const result = await themeBuild('kept.mjs', {}, {cwd: tmpDir});
+    const css = fs.readFileSync(path.join(tmpDir, 'kept.css'), 'utf8');
+
+    expect(css).toContain(
+      '--font-family-body: Gill\\ Sans, "Segoe;UI", serif /* ; */;',
+    );
+    expect(css).toContain(
+      'background-image: URL(data:image/svg+xml;base64,PHN2Zz4=);',
+    );
+    expect(css).toContain('-webkit-line-clamp: 2;');
+    expect(result?.data.warnings).toEqual([]);
+  });
+});
+
 describe('themeBuild() — nothing to build', () => {
   it('returns null and writes nothing when the generator yields no CSS', async () => {
     const themeFile = path.join(tmpDir, 'empty.mjs');

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/generateTonalPalette.doc.mjs

@@ -5,6 +5,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'generateTonalPalette',
+  namespace: 'cli/api',
   displayName: 'generateTonalPalette()',
   summary: 'Generate candidate tonal palette data without filesystem effects.',
   description:

package/api/theme/integration-themes.test.mjs

@@ -7,18 +7,14 @@ import {themeAdd} from './add/add.mjs';
 
 let tmpDir;
 
-function installThemeIntegration(
-  packageName,
-  slug,
-  source = 'export const oceanTheme = {};\n',
-  extraFiles = {},
-) {
+function installThemeIntegration(packageName, slug, source, extraFiles = {}) {
   const packageDir = path.join(
     tmpDir,
     'node_modules',
     ...packageName.split('/'),
   );
   const themeDir = path.join(packageDir, 'themes', slug);
+  const stem = `${slug.replace(/-([a-z0-9])/gu, (_, character) => character.toUpperCase())}Theme`;
   fs.mkdirSync(themeDir, {recursive: true});
   fs.writeFileSync(
     path.join(packageDir, 'package.json'),
@@ -26,26 +22,21 @@ function installThemeIntegration(
   );
   fs.writeFileSync(
     path.join(packageDir, 'astryx.integration.mjs'),
-    `export default {themes: './themes'};\n`,
+    `export default {themes: './themes'};
+`,
   );
   fs.writeFileSync(
-    path.join(packageDir, 'themes', 'manifest.json'),
-    JSON.stringify({
-      version: 1,
-      themes: [
-        {
-          slug,
-          displayName: slug === 'neutral' ? 'Neutral Plus' : 'Ocean',
-          description: 'Integration-owned theme.',
-          maintained: true,
-          entry: 'oceanTheme.ts',
-          exportName: 'oceanTheme',
-          files: ['oceanTheme.ts', ...Object.keys(extraFiles)],
-        },
-      ],
-    }),
+    path.join(themeDir, `${stem}.doc.mjs`),
+    `/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
+export default {type: 'theme', name: '${slug}', displayName: '${slug === 'neutral' ? 'Neutral Plus' : 'Ocean'}', description: 'Integration-owned theme.', maintained: true};
+`,
+  );
+  fs.writeFileSync(
+    path.join(themeDir, `${stem}.ts`),
+    source ??
+      `export const ${stem} = {};
+`,
   );
-  fs.writeFileSync(path.join(themeDir, 'oceanTheme.ts'), source);
   for (const [relativePath, contents] of Object.entries(extraFiles)) {
     const file = path.join(themeDir, relativePath);
     fs.mkdirSync(path.dirname(file), {recursive: true});
@@ -85,23 +76,43 @@ describe('themeAdd with integration themes', () => {
     ).toContain('oceanTheme');
   });
 
-  it('copies nested files listed by an integration theme catalog', async () => {
+  it('copies the complete nested integration theme directory', async () => {
     installThemeIntegration(
       '@acme/themes',
       'ocean',
       "import {oceanBlue} from './tokens/colors';\nexport const oceanTheme = {oceanBlue};\n",
-      {'tokens/colors.ts': "export const oceanBlue = '#0064e0';\n"},
+      {
+        'tokens/colors.ts': "export const oceanBlue = '#0064e0';\n",
+        'receipts/palette.json': '{"version":1}\n',
+      },
     );
 
     const result = await themeAdd('ocean', {cwd: tmpDir});
 
-    expect(result.data.files).toEqual(['oceanTheme.ts', 'tokens/colors.ts']);
+    expect(result.data.files).toEqual([
+      'oceanTheme.ts',
+      'oceanTheme.doc.mjs',
+      'receipts/palette.json',
+      'tokens/colors.ts',
+    ]);
+    expect(
+      fs.readFileSync(
+        path.join(tmpDir, 'src', 'themes', 'ocean', 'oceanTheme.doc.mjs'),
+        'utf-8',
+      ),
+    ).toContain("type: 'theme'");
     expect(
       fs.readFileSync(
         path.join(tmpDir, 'src', 'themes', 'ocean', 'tokens', 'colors.ts'),
         'utf-8',
       ),
     ).toContain('oceanBlue');
+    expect(
+      fs.readFileSync(
+        path.join(tmpDir, 'src', 'themes', 'ocean', 'receipts', 'palette.json'),
+        'utf-8',
+      ),
+    ).toBe('{"version":1}\n');
   });
 
   it('rejects a nested destination symlink that escapes the project', async () => {
@@ -146,7 +157,7 @@ describe('themeAdd with integration themes', () => {
     expect(result.data.package).toBe('@acme/themes');
   });
 
-  it('reports a selected installed package with a corrupted theme catalog', async () => {
+  it('reports a selected installed package with a corrupted theme directory', async () => {
     installThemeIntegration(
       '@acme/themes',
       'ocean',
@@ -170,7 +181,7 @@ describe('themeAdd with integration themes', () => {
       themeAdd('ocean', {cwd: tmpDir, package: '@acme/themes'}),
     ).rejects.toMatchObject({
       code: 'ERR_THEME_INVALID',
-      message: expect.stringContaining('tokens/colors.ts'),
+      message: expect.stringContaining('./tokens/colors'),
     });
   });
 

package/api/theme/list/list.test.mjs

@@ -9,8 +9,13 @@ import {BUNDLED_THEME_PACKAGE} from '../../../foundation/discovery/theme-discove
 let tmpDir;
 
 function installThemeIntegration(packageName = '@acme/themes', slug = 'ocean') {
-  const packageDir = path.join(tmpDir, 'node_modules', ...packageName.split('/'));
+  const packageDir = path.join(
+    tmpDir,
+    'node_modules',
+    ...packageName.split('/'),
+  );
   const themeDir = path.join(packageDir, 'themes', slug);
+  const stem = `${slug.replace(/-([a-z0-9])/gu, (_, character) => character.toUpperCase())}Theme`;
   fs.mkdirSync(themeDir, {recursive: true});
   fs.writeFileSync(
     path.join(packageDir, 'package.json'),
@@ -18,28 +23,19 @@ function installThemeIntegration(packageName = '@acme/themes', slug = 'ocean') {
   );
   fs.writeFileSync(
     path.join(packageDir, 'astryx.integration.mjs'),
-    `export default {themes: './themes'};\n`,
+    `export default {themes: './themes'};
+`,
   );
   fs.writeFileSync(
-    path.join(packageDir, 'themes', 'manifest.json'),
-    JSON.stringify({
-      version: 1,
-      themes: [
-        {
-          slug,
-          displayName: 'Ocean',
-          description: 'Blue and calm.',
-          maintained: true,
-          entry: 'oceanTheme.ts',
-          exportName: 'oceanTheme',
-          files: ['oceanTheme.ts'],
-        },
-      ],
-    }),
+    path.join(themeDir, `${stem}.doc.mjs`),
+    `/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */
+export default {type: 'theme', name: '${slug}', displayName: 'Ocean', description: 'Blue and calm.', maintained: true};
+`,
   );
   fs.writeFileSync(
-    path.join(themeDir, 'oceanTheme.ts'),
-    'export const oceanTheme = {};\n',
+    path.join(themeDir, `${stem}.ts`),
+    `export const ${stem} = {};
+`,
   );
 }
 
@@ -47,7 +43,10 @@ beforeEach(() => {
   tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-theme-list-'));
   fs.writeFileSync(
     path.join(tmpDir, 'package.json'),
-    JSON.stringify({name: 'consumer', dependencies: {'@acme/themes': '^1.0.0'}}),
+    JSON.stringify({
+      name: 'consumer',
+      dependencies: {'@acme/themes': '^1.0.0'},
+    }),
   );
 });
 

package/api/theme/listThemes.doc.mjs

@@ -9,25 +9,26 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'listThemes',
+  namespace: 'cli/api',
   displayName: 'listThemes()',
-  summary: 'Read the CLI bundled-theme manifest.',
+  summary: 'Read the CLI bundled-theme descriptors.',
   description:
-    'Reads templates/themes/manifest.json and returns its raw entries synchronously. This low-level helper keeps its historical bundled-only contract; project-aware themeList() and themeAdd() also discover source themes from installed integrations.',
+    'Reads the typed same-stem descriptors under templates/themes and returns normalized entries synchronously. This low-level helper keeps its historical bundled-only contract; project-aware themeList() and themeAdd() also discover source themes from installed integrations.',
   importPath: '@astryxdesign/cli/api',
   signature: 'listThemes(): BundledTheme[]',
-  keywords: ['theme', 'themes', 'manifest', 'bundled', 'adapter', 'list'],
+  keywords: ['theme', 'themes', 'descriptor', 'bundled', 'adapter', 'list'],
   params: [],
   returns: [
     {
       type: 'BundledTheme[]',
       description:
-        'The bundled manifest entries: slug, displayName, description, maintained, entry, exportName, and files.',
+        'The normalized bundled descriptor entries: slug, displayName, description, maintained, entry, exportName, and files.',
     },
   ],
   throws: [
     {
       code: 'ERR_NO_SOURCE',
-      when: 'the bundled catalog is missing, invalid, or references missing source files',
+      when: 'the bundled descriptors are missing, invalid, or have missing source files',
     },
   ],
   examples: [

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;