@astryxdesign/cli 0.6.3-canary.ea2f048 → 0.6.3-canary.ebaebc4

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/palette/generate/generate.mjs

@@ -100,7 +100,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,

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';
@@ -411,6 +413,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 +529,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++) {

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