@astryxdesign/cli 0.6.3-canary.f22695a → 0.6.3

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

@@ -206,133 +206,6 @@ 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/palette/generate/generate.mjs

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

package/api/theme/palette/generate/generator.d.mts

@@ -22,17 +22,15 @@ 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: TonalPaletteRampDiagnostics}} GeneratedRamp */
+/** @typedef {{colors: Record<number, string>, diagnostics: Record<string, unknown>}} 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: TonalPaletteCoordinationDiagnostics[], errors: {familyId: string, message: string}[]}} PaletteGenerationResult */
+/** @typedef {{recipe: typeof PALETTE_RECIPE, status: 'candidate', request: NormalizedRequest, families: GeneratedFamily[], coordination: Record<string, unknown>[], errors: {familyId: string, message: string}[]}} PaletteGenerationResult */
 export const PALETTE_RECIPE: "astryx-oklch-v1";
 export const PALETTE_BLACK: "#000000";
 export const PALETTE_WHITE: "#ffffff";
@@ -40,9 +38,6 @@ 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 = {
@@ -57,7 +52,7 @@ export type AnchorResult = TonalPaletteAnchor & {
 };
 export type GeneratedRamp = {
     colors: Record<number, string>;
-    diagnostics: TonalPaletteRampDiagnostics;
+    diagnostics: Record<string, unknown>;
 };
 export type NormalizedFamily = {
     id: string;
@@ -66,6 +61,14 @@ 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;
@@ -78,7 +81,7 @@ export type PaletteGenerationResult = {
     status: "candidate";
     request: NormalizedRequest;
     families: GeneratedFamily[];
-    coordination: TonalPaletteCoordinationDiagnostics[];
+    coordination: Record<string, unknown>[];
     errors: {
         familyId: string;
         message: string;

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

@@ -12,17 +12,15 @@ 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: TonalPaletteRampDiagnostics}} GeneratedRamp */
+/** @typedef {{colors: Record<number, string>, diagnostics: Record<string, unknown>}} 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: TonalPaletteCoordinationDiagnostics[], errors: {familyId: string, message: string}[]}} PaletteGenerationResult */
+/** @typedef {{recipe: typeof PALETTE_RECIPE, status: 'candidate', request: NormalizedRequest, families: GeneratedFamily[], coordination: Record<string, unknown>[], errors: {familyId: string, message: string}[]}} PaletteGenerationResult */
 
 export const PALETTE_RECIPE = 'astryx-oklch-v1';
 export const PALETTE_BLACK = '#000000';
@@ -413,7 +411,6 @@ 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];
@@ -529,7 +526,6 @@ 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++) {

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

@@ -2,7 +2,7 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * astryx --json theme build <file>
+ * xds --json theme build <file>
  */
 export type ThemeBuildResponse = {
     /**
@@ -27,7 +27,7 @@ export type ThemeBuildResponse = {
     };
 };
 /**
- * astryx --json theme build <file> --check
+ * xds --json theme build <file> --check
  */
 export type ThemeBuildCheckResponse = {
     type: "theme.build.check";
@@ -42,7 +42,7 @@ export type ThemeBuildCheckResponse = {
     };
 };
 /**
- * astryx --json theme build <a> <b> … — several themes in one invocation. Each
+ * xds --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;
 };
 /**
- * astryx --json theme list
+ * xds --json theme list
  */
 export type ThemeListResponse = {
     type: "theme.list";
     data: ThemeListEntry[];
 };
 /**
- * astryx --json theme add <slug>
+ * xds --json theme add <slug>
  */
 export type ThemeAddResponse = {
     type: "theme.add";
@@ -94,7 +94,7 @@ export type ThemeAddResponse = {
     };
 };
 /**
- * astryx --json theme template
+ * xds --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;
 };
 /**
- * astryx --json theme targets [filter]
+ * xds --json theme targets [filter]
  */
 export type ThemeTargetsResponse = {
     type: "theme.targets";
@@ -134,7 +134,8 @@ export type ThemeTargetsResponse = {
     };
 };
 /**
- * A color an author pins at one stop of one mode, constraining generation.
+ * A generated palette candidate. The palette is still subject to author review
+ * and is not connected to runtime theme values.
  */
 export type TonalPaletteAnchor = {
     /**
@@ -145,10 +146,6 @@ 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
@@ -162,32 +159,11 @@ 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 = {
@@ -197,11 +173,6 @@ 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;
     /**
@@ -211,10 +182,6 @@ 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";
@@ -238,133 +205,7 @@ export type TonalPaletteCandidate = {
     }>;
 };
 /**
- * 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>
+ * xds --json theme palette generate <config>
  */
 export type ThemePaletteGenerateResponse = {
     type: "theme.palette.generate";
@@ -380,6 +221,6 @@ export type ThemePaletteGenerateResponse = {
         written: boolean;
         reason: "exists" | null;
         candidate: TonalPaletteCandidate;
-        generationReceipt: TonalPaletteGenerationReceipt;
+        generationReceipt: Record<string, unknown>;
     };
 };