@astryxdesign/core 0.1.7 → 0.1.8-canary.0c4d8d7

package/src/hooks/computeOverflow.ts

@@ -0,0 +1,290 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file computeOverflow.ts
+ * @input Plain measurements (item widths, gap, available width, indicator width, limits)
+ * @output Pure overflow computation: how many items are visible and their row layout
+ * @position Pure helper consumed by useOverflow; contains no DOM or React code so the
+ *           fit/clamp math and the multi-row packing can be unit-tested in isolation.
+ *
+ * There is a single source of truth for `visibleCount`:
+ *   visibleCount = clamp(fitCount, minVisibleItems, maxVisibleItems ?? itemCount)
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/useOverflow.ts (the only caller)
+ */
+
+export interface ComputeOverflowInput {
+  /** Measured widths of each item, in original DOM order. */
+  widths: number[];
+  /** Gap between items, in pixels. */
+  gap: number;
+  /** Width available to lay items out, in pixels. */
+  availableWidth: number;
+  /** Measured width of the overflow indicator (0 if none). */
+  indicatorWidth: number;
+  /** Floor — always show at least this many items. */
+  minVisibleItems: number;
+  /** Ceiling — never show more than this many items. `undefined` = no cap. */
+  maxVisibleItems?: number;
+  /**
+   * Bounded multi-row: wrap items across up to this many rows, then collapse
+   * the rest into the overflow indicator. `undefined` (or `1`) = single line.
+   */
+  maxRows?: number;
+  /** Which end items collapse from. */
+  collapseFrom: 'start' | 'end';
+}
+
+export interface ComputeOverflowResult {
+  /** Number of items that should be rendered in the visible container. */
+  visibleCount: number;
+  /** Number of rows the visible items occupy (always 1 for the single-line path). */
+  rows: number;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(Math.min(value, max), min);
+}
+
+/**
+ * Resolve the ceiling and floor into a single [floor, ceiling] pair.
+ *
+ * `maxVisibleItems` is clamped to `itemCount` (a cap larger than the list is a
+ * no-op). When `maxVisibleItems < minVisibleItems`, the floor wins (D1) via the
+ * final clamp — the hook is responsible for the dev-only warning.
+ */
+function resolveBounds(
+  itemCount: number,
+  minVisibleItems: number,
+  maxVisibleItems: number | undefined,
+): {floor: number; ceiling: number} {
+  const floor = Math.max(0, Math.min(minVisibleItems, itemCount));
+  const rawCeiling = maxVisibleItems == null ? itemCount : maxVisibleItems;
+  const ceiling = Math.max(0, Math.min(rawCeiling, itemCount));
+  return {floor, ceiling};
+}
+
+/**
+ * Single-line greedy fit: how many items fit in one row of `availableWidth`,
+ * reserving indicator space for every non-final admitted item. Mirrors the
+ * original in-hook loop so single-line behavior is unchanged.
+ */
+function computeSingleLineFit(
+  orderedWidths: number[],
+  gap: number,
+  availableWidth: number,
+  indicatorWidth: number,
+  floor: number,
+  ceiling: number,
+): number {
+  let totalWidth = 0;
+  let count = 0;
+
+  for (let i = 0; i < orderedWidths.length; i++) {
+    if (count >= ceiling) {
+      break;
+    }
+
+    const itemWidth = orderedWidths[i];
+    const gapWidth = i > 0 ? gap : 0;
+    const candidateWidth = totalWidth + itemWidth + gapWidth;
+
+    const isLastItem = i === orderedWidths.length - 1;
+    const reservedWidth = isLastItem
+      ? 0
+      : indicatorWidth + (count > 0 || indicatorWidth > 0 ? gap : 0);
+
+    if (candidateWidth + reservedWidth > availableWidth && count >= floor) {
+      break;
+    }
+
+    totalWidth = candidateWidth;
+    count++;
+  }
+
+  return count;
+}
+
+/**
+ * Pack items into rows, wrapping when the next item would exceed
+ * `availableWidth`. On the last allowed row, keep `indicatorReserve` px free so
+ * the overflow indicator fits. Stops admitting once no further item can be
+ * placed within `maxRows`.
+ */
+function packRows(
+  orderedWidths: number[],
+  gap: number,
+  availableWidth: number,
+  indicatorReserve: number,
+  maxRows: number,
+): {placed: number; rows: number} {
+  let placed = 0;
+  let row = 1;
+  let rowWidth = 0;
+
+  for (let i = 0; i < orderedWidths.length; i++) {
+    const w = orderedWidths[i];
+    const isFirstInRow = rowWidth === 0;
+    const candidate = isFirstInRow ? w : rowWidth + gap + w;
+
+    const onLastRow = row === maxRows;
+    const reserve =
+      onLastRow && indicatorReserve > 0 ? indicatorReserve + gap : 0;
+
+    if (candidate + reserve <= availableWidth) {
+      rowWidth = candidate;
+      placed++;
+      continue;
+    }
+
+    if (isFirstInRow) {
+      // A single item wider than the row occupies this row alone (it will be
+      // clipped visually). But if it can't coexist with the reserved indicator
+      // on the last row, stop here.
+      if (onLastRow && reserve > 0) {
+        break;
+      }
+      rowWidth = candidate;
+      placed++;
+      continue;
+    }
+
+    if (row >= maxRows) {
+      break;
+    }
+    row++;
+    rowWidth = 0;
+    i--; // re-attempt this item as the first on the new row
+  }
+
+  return {placed, rows: row};
+}
+
+/** Count how many rows a set of items occupies when wrapped at availableWidth. */
+function countRows(
+  orderedWidths: number[],
+  gap: number,
+  availableWidth: number,
+): number {
+  if (orderedWidths.length === 0) {
+    return 0;
+  }
+  let rows = 1;
+  let rowWidth = 0;
+  for (let i = 0; i < orderedWidths.length; i++) {
+    const w = orderedWidths[i];
+    const isFirstInRow = rowWidth === 0;
+    const candidate = isFirstInRow ? w : rowWidth + gap + w;
+    if (candidate <= availableWidth || isFirstInRow) {
+      rowWidth = candidate;
+    } else {
+      rows++;
+      rowWidth = w;
+    }
+  }
+  return rows;
+}
+
+/**
+ * Multi-row packing (Strategy A): simulate wrapping items into rows of
+ * `availableWidth`, admitting items until a new item would require a row beyond
+ * `maxRows`, reserving indicator space on the final row when items overflow.
+ * Returns the admitted count and how many rows those items occupy. Assumes
+ * uniform row height.
+ */
+function computeMultiRowFit(
+  orderedWidths: number[],
+  gap: number,
+  availableWidth: number,
+  indicatorWidth: number,
+  maxRows: number,
+): {count: number; rows: number} {
+  const n = orderedWidths.length;
+  if (n === 0) {
+    return {count: 0, rows: 0};
+  }
+
+  // If everything fits within maxRows without reserving indicator space, there
+  // is no overflow and no indicator is needed.
+  const packAll = packRows(orderedWidths, gap, availableWidth, 0, maxRows);
+  if (packAll.placed === n) {
+    return {count: n, rows: packAll.rows};
+  }
+
+  // Overflow → reserve indicator space on the final row and re-pack.
+  const packWithIndicator = packRows(
+    orderedWidths,
+    gap,
+    availableWidth,
+    indicatorWidth,
+    maxRows,
+  );
+
+  const count = packWithIndicator.placed;
+  const rows = countRows(orderedWidths.slice(0, count), gap, availableWidth);
+
+  return {count, rows: Math.max(count > 0 ? 1 : 0, rows)};
+}
+
+/**
+ * Pure overflow computation. Given plain measurements and the configured
+ * limits, return how many items should be visible and how many rows they
+ * occupy. No DOM, no React — safe to unit-test directly.
+ */
+export function computeOverflow(
+  input: ComputeOverflowInput,
+): ComputeOverflowResult {
+  const {
+    widths,
+    gap,
+    availableWidth,
+    indicatorWidth,
+    minVisibleItems,
+    maxVisibleItems,
+    maxRows,
+    collapseFrom,
+  } = input;
+
+  const itemCount = widths.length;
+  if (itemCount === 0) {
+    return {visibleCount: 0, rows: 0};
+  }
+
+  const {floor, ceiling} = resolveBounds(
+    itemCount,
+    minVisibleItems,
+    maxVisibleItems,
+  );
+
+  const orderedWidths = collapseFrom === 'end' ? widths : [...widths].reverse();
+
+  const multiRow = maxRows != null && maxRows > 1;
+
+  if (!multiRow) {
+    const fitCount = computeSingleLineFit(
+      orderedWidths,
+      gap,
+      availableWidth,
+      indicatorWidth,
+      floor,
+      ceiling,
+    );
+    const visibleCount = clamp(fitCount, floor, ceiling);
+    return {visibleCount, rows: visibleCount > 0 ? 1 : 0};
+  }
+
+  const {count, rows} = computeMultiRowFit(
+    orderedWidths,
+    gap,
+    availableWidth,
+    indicatorWidth,
+    maxRows,
+  );
+  const visibleCount = clamp(count, floor, ceiling);
+  const resolvedRows =
+    visibleCount === count
+      ? rows
+      : countRows(orderedWidths.slice(0, visibleCount), gap, availableWidth);
+  return {visibleCount, rows: visibleCount > 0 ? Math.max(1, resolvedRows) : 0};
+}

package/src/hooks/useOverflow.test.ts

@@ -14,12 +14,15 @@ function mockContainer(width: number): HTMLElement {
 function mockMeasure(
   itemWidths: number[],
   indicatorWidth?: number,
+  itemHeight = 0,
 ): HTMLElement {
-  const children: {offsetWidth: number}[] = itemWidths.map(w => ({
-    offsetWidth: w,
-  }));
+  const children: {offsetWidth: number; offsetHeight: number}[] =
+    itemWidths.map(w => ({
+      offsetWidth: w,
+      offsetHeight: itemHeight,
+    }));
   if (indicatorWidth != null) {
-    children.push({offsetWidth: indicatorWidth});
+    children.push({offsetWidth: indicatorWidth, offsetHeight: itemHeight});
   }
   return {children} as unknown as HTMLElement;
 }
@@ -332,6 +335,95 @@ describe('useOverflow', () => {
   });
 });
 
+describe('useOverflow with maxVisibleItems (cap)', () => {
+  it('caps visible items even when they all fit', () => {
+    const {result} = renderHook(() =>
+      useOverflow(5, {gap: 10, maxVisibleItems: 3}),
+    );
+
+    act(() => {
+      result.current.measureRef(mockMeasure([50, 50, 50, 50, 50], 30));
+      result.current.containerRef(mockContainer(10000));
+    });
+
+    expect(result.current.visibleCount).toBe(3);
+    expect(result.current.hasOverflow).toBe(true);
+  });
+
+  it('cap does not raise a fit-limited count', () => {
+    const {result} = renderHook(() =>
+      useOverflow(4, {gap: 10, maxVisibleItems: 4}),
+    );
+
+    act(() => {
+      result.current.measureRef(mockMeasure([50, 50, 50, 50], 30));
+      result.current.containerRef(mockContainer(150));
+    });
+
+    expect(result.current.visibleCount).toBe(2);
+  });
+
+  it('min wins when maxVisibleItems < minVisibleItems and warns in dev', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const {result} = renderHook(() =>
+      useOverflow(5, {gap: 10, minVisibleItems: 3, maxVisibleItems: 1}),
+    );
+
+    act(() => {
+      result.current.measureRef(mockMeasure([50, 50, 50, 50, 50], 30));
+      result.current.containerRef(mockContainer(10000));
+    });
+
+    expect(result.current.visibleCount).toBe(3);
+    expect(warn).toHaveBeenCalled();
+    warn.mockRestore();
+  });
+});
+
+describe('useOverflow with maxRows (multi-row)', () => {
+  it('exposes rows and rowHeight', () => {
+    const {result} = renderHook(() => useOverflow(6, {gap: 10, maxRows: 2}));
+
+    act(() => {
+      result.current.measureRef(mockMeasure([50, 50, 50, 50, 50, 50], 40, 24));
+      result.current.containerRef(mockContainer(170));
+    });
+
+    // 3 items per row (170), 2 rows → all 6 fit
+    expect(result.current.visibleCount).toBe(6);
+    expect(result.current.rows).toBe(2);
+    expect(result.current.rowHeight).toBe(24);
+    expect(result.current.hasOverflow).toBe(false);
+  });
+
+  it('collapses items beyond maxRows into the indicator', () => {
+    const {result} = renderHook(() => useOverflow(8, {gap: 10, maxRows: 2}));
+
+    act(() => {
+      result.current.measureRef(
+        mockMeasure([50, 50, 50, 50, 50, 50, 50, 50], 40, 24),
+      );
+      result.current.containerRef(mockContainer(170));
+    });
+
+    expect(result.current.visibleCount).toBe(5);
+    expect(result.current.rows).toBe(2);
+    expect(result.current.hasOverflow).toBe(true);
+  });
+
+  it('maxRows=1 matches single-line behavior', () => {
+    const {result} = renderHook(() => useOverflow(4, {gap: 10, maxRows: 1}));
+
+    act(() => {
+      result.current.measureRef(mockMeasure([50, 50, 50, 50], 30, 24));
+      result.current.containerRef(mockContainer(150));
+    });
+
+    expect(result.current.visibleCount).toBe(2);
+    expect(result.current.rows).toBe(1);
+  });
+});
+
 describe('useOverflow with behavior=observeParent', () => {
   function mockContainerWithParent(
     parentWidth: number,

package/src/hooks/useOverflow.ts

@@ -10,15 +10,19 @@
  *
  * Measures children rendered in a hidden container to determine how many fit
  * in the available width, without flickering. Uses ResizeObserver to react
- * to container size changes.
+ * to container size changes. Supports an optional item cap (`maxVisibleItems`)
+ * and bounded multi-row wrapping (`maxRows`); the fit/clamp/row-packing math
+ * lives in the pure `computeOverflow` helper.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts
+ * - /packages/core/src/hooks/computeOverflow.ts (the pure computation)
  */
 
 import {useState, useCallback, useRef} from 'react';
 import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect';
 import {observeResize, unobserveResize} from '../utils/sharedResizeObserver';
+import {computeOverflow} from './computeOverflow';
 
 export interface UseOverflowOptions {
   /**
@@ -33,6 +37,23 @@ export interface UseOverflowOptions {
    */
   minVisibleItems?: number;
 
+  /**
+   * Maximum number of items to ever show, even if they all fit. The ceiling
+   * partner to `minVisibleItems`. `undefined` means no cap. When it is less
+   * than `minVisibleItems`, the floor wins and a dev-only warning is emitted.
+   * @default undefined
+   */
+  maxVisibleItems?: number;
+
+  /**
+   * Wrap items across up to this many rows before collapsing the rest into the
+   * overflow indicator. `undefined` (or `1`) keeps the single-line behavior.
+   * A number, not a boolean: unbounded wrapping is a plain flex-wrap layout,
+   * not overflow collapse. Assumes uniform row height.
+   * @default undefined
+   */
+  maxRows?: number;
+
   /**
    * Which end to collapse items from.
    * @default 'end'
@@ -61,6 +82,10 @@ export interface UseOverflowReturn {
   visibleCount: number;
   /** Whether any items are overflowing */
   hasOverflow: boolean;
+  /** Number of rows the visible items occupy (1 for the single-line path) */
+  rows: number;
+  /** Measured max item height in pixels; used to size the multi-row container */
+  rowHeight: number;
 }
 
 /**
@@ -88,13 +113,29 @@ export function useOverflow(
   const {
     gap = 0,
     minVisibleItems = 0,
+    maxVisibleItems,
+    maxRows,
     collapseFrom = 'end',
     behavior = 'observeSelf',
   } = options;
 
+  if (
+    process.env.NODE_ENV !== 'production' &&
+    maxVisibleItems != null &&
+    maxVisibleItems < minVisibleItems
+  ) {
+    console.warn(
+      `useOverflow: maxVisibleItems (${maxVisibleItems}) is less than ` +
+        `minVisibleItems (${minVisibleItems}); the floor wins and ` +
+        `minVisibleItems items will be shown.`,
+    );
+  }
+
   const observeParent = behavior === 'observeParent';
 
   const [visibleCount, setVisibleCount] = useState(itemCount);
+  const [rows, setRows] = useState(1);
+  const [rowHeight, setRowHeight] = useState(0);
   const containerElRef = useRef<HTMLElement | null>(null);
   const measureElRef = useRef<HTMLElement | null>(null);
   const observedElRef = useRef<HTMLElement | null>(null);
@@ -134,44 +175,45 @@ export function useOverflow(
     if (children.length === 0) {
       // eslint-disable-next-line @eslint-react/set-state-in-effect -- overflow count is derived from measured DOM widths
       setVisibleCount(0);
+      // eslint-disable-next-line @eslint-react/set-state-in-effect -- derived from measured DOM
+      setRows(0);
       return;
     }
 
-    // Collect widths of all children
     const widths = children.map(child => child.offsetWidth);
-
-    // Determine how many items fit
-    let totalWidth = 0;
-    let count = 0;
-
-    const orderedWidths =
-      collapseFrom === 'end' ? widths : [...widths].reverse();
-
-    for (let i = 0; i < orderedWidths.length; i++) {
-      const itemWidth = orderedWidths[i];
-      const gapWidth = i > 0 ? gap : 0;
-      const candidateWidth = totalWidth + itemWidth + gapWidth;
-
-      // If this isn't the last item, we need to reserve space for the indicator
-      const isLastItem = i === orderedWidths.length - 1;
-      const reservedWidth = isLastItem
-        ? 0
-        : indicatorWidth + (count > 0 || indicatorWidth > 0 ? gap : 0);
-
-      if (
-        candidateWidth + reservedWidth > availableWidth &&
-        count >= minVisibleItems
-      ) {
-        break;
-      }
-
-      totalWidth = candidateWidth;
-      count++;
-    }
+    const measuredRowHeight = children.reduce(
+      (max, child) => Math.max(max, child.offsetHeight || 0),
+      0,
+    );
+
+    const {visibleCount: nextVisible, rows: nextRows} = computeOverflow({
+      widths,
+      gap,
+      availableWidth,
+      indicatorWidth,
+      minVisibleItems,
+      maxVisibleItems,
+      maxRows,
+      collapseFrom,
+    });
 
     // eslint-disable-next-line @eslint-react/set-state-in-effect -- overflow count is derived from measured DOM widths
-    setVisibleCount(Math.max(Math.min(count, itemCount), minVisibleItems));
-  }, [itemCount, gap, minVisibleItems, collapseFrom, observeParent]);
+    setVisibleCount(nextVisible);
+    // eslint-disable-next-line @eslint-react/set-state-in-effect -- derived from measured DOM
+    setRows(prev => (prev === nextRows ? prev : nextRows));
+    // eslint-disable-next-line @eslint-react/set-state-in-effect -- derived from measured DOM
+    setRowHeight(prev =>
+      prev === measuredRowHeight ? prev : measuredRowHeight,
+    );
+  }, [
+    itemCount,
+    gap,
+    minVisibleItems,
+    maxVisibleItems,
+    maxRows,
+    collapseFrom,
+    observeParent,
+  ]);
 
   const containerRef = useCallback(
     (el: HTMLElement | null) => {
@@ -217,5 +259,7 @@ export function useOverflow(
     measureRef,
     visibleCount,
     hasOverflow,
+    rows,
+    rowHeight,
   };
 }

package/src/postinstall.test.mjs

@@ -0,0 +1,71 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Guardrail tests for the @astryxdesign/core postinstall nudge (layer 1).
+ *
+ * The marker check mirrors the CLI's single source of truth (core can't import
+ * the CLI). Tests that it detects the marker across EVERY agent-doc location
+ * (incl. Hermes) + legacy markers, and that the nudge decision matrix is correct.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {isAstryxInitialized, shouldNudge} from '../scripts/postinstall.mjs';
+
+const MARKER = '<!-- ASTRYX:START -->';
+
+let tmp;
+beforeEach(() => {
+  tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-core-postinstall-'));
+});
+afterEach(() => {
+  fs.rmSync(tmp, {recursive: true, force: true});
+});
+function write(rel, body) {
+  const p = path.join(tmp, rel);
+  fs.mkdirSync(path.dirname(p), {recursive: true});
+  fs.writeFileSync(p, body);
+}
+
+describe('core postinstall — isAstryxInitialized (mirrors CLI contract)', () => {
+  it('is false in an empty project', () => {
+    expect(isAstryxInitialized(tmp)).toBe(false);
+  });
+
+  it.each(['AGENTS.md', 'CLAUDE.md', '.claude/CLAUDE.md', '.cursorrules', '.hermes.md', 'HERMES.md'])(
+    'detects the marker in %s',
+    file => {
+      write(file, `# doc\n${MARKER}\nbody`);
+      expect(isAstryxInitialized(tmp)).toBe(true);
+    },
+  );
+
+  it('detects the legacy XDS marker', () => {
+    write('AGENTS.md', '<!-- XDS:START -->');
+    expect(isAstryxInitialized(tmp)).toBe(true);
+  });
+});
+
+describe('core postinstall — shouldNudge', () => {
+  const DEP = '/proj/node_modules/@astryxdesign/core/scripts/postinstall.mjs';
+  const NPX = '/Users/x/.npm/_npx/a1/node_modules/@astryxdesign/core/scripts/postinstall.mjs';
+  const REPO = '/repo/packages/core/scripts/postinstall.mjs';
+
+  it('nudges for a real dependency install when not set up', () => {
+    expect(shouldNudge({scriptPath: DEP, npmCommand: 'install', isSetUp: false})).toBe(true);
+  });
+  it('quiet in the monorepo/source', () => {
+    expect(shouldNudge({scriptPath: REPO, npmCommand: 'install', isSetUp: false})).toBe(false);
+  });
+  it('quiet during npx transient install (_npx path)', () => {
+    expect(shouldNudge({scriptPath: NPX, npmCommand: 'install', isSetUp: false})).toBe(false);
+  });
+  it('quiet during npx (npm_command=exec)', () => {
+    expect(shouldNudge({scriptPath: DEP, npmCommand: 'exec', isSetUp: false})).toBe(false);
+  });
+  it('quiet once set up', () => {
+    expect(shouldNudge({scriptPath: DEP, npmCommand: 'install', isSetUp: true})).toBe(false);
+  });
+});

package/src/theme/Theme.doc.mjs

@@ -39,12 +39,12 @@ export const docs = {
   },
   usage: {
     description:
-      'Wraps a subtree with a specific Astryx theme. For static production themes, use `npx astryx theme build` and import the generated CSS plus built theme object for first-paint and SSR performance. Use runtime `defineTheme()` when themes are dynamic or for prototyping.\n\n`defineTheme` accepts a `tokens` object whose keys are CSS custom property names (always prefixed with `--`). Common token names include `--color-accent`, `--color-background-surface`, `--color-background-body`, `--color-text-primary`, `--color-text-secondary`, `--radius-container`, `--spacing-1` through `--spacing-6`. Values can be a string (same for light/dark) or a `[light, dark]` tuple.\n\nExample:\n```ts\nimport {defineTheme} from \'@astryxdesign/core/theme\';\nconst myTheme = defineTheme({\n  name: \'ocean\',\n  tokens: {\n    \'--color-accent\': [\'#0077B6\', \'#48CAE4\'],\n    \'--color-background-surface\': [\'#F0F8FF\', \'#0A1628\'],\n    \'--color-text-primary\': [\'#0A1317\', \'#FFFFFF\'],\n    \'--radius-container\': \'16px\',\n  },\n});\n```',
+      'Wraps a subtree with a specific Astryx theme. For static production themes, use `astryx theme build` and import the generated CSS plus built theme object for first-paint and SSR performance. Use runtime `defineTheme()` when themes are dynamic or for prototyping.\n\n`defineTheme` accepts a `tokens` object whose keys are CSS custom property names (always prefixed with `--`). Common token names include `--color-accent`, `--color-background-surface`, `--color-background-body`, `--color-text-primary`, `--color-text-secondary`, `--radius-container`, `--spacing-1` through `--spacing-6`. Values can be a string (same for light/dark) or a `[light, dark]` tuple.\n\nExample:\n```ts\nimport {defineTheme} from \'@astryxdesign/core/theme\';\nconst myTheme = defineTheme({\n  name: \'ocean\',\n  tokens: {\n    \'--color-accent\': [\'#0077B6\', \'#48CAE4\'],\n    \'--color-background-surface\': [\'#F0F8FF\', \'#0A1628\'],\n    \'--color-text-primary\': [\'#0A1317\', \'#FFFFFF\'],\n    \'--radius-container\': \'16px\',\n  },\n});\n```',
     bestPractices: [
       {
         guidance: true,
         description:
-          'Build app themes that are known ahead of time with `npx astryx theme build`, then import the generated CSS and built theme object.',
+          'Build app themes that are known ahead of time with `astryx theme build`, then import the generated CSS and built theme object.',
       },
       {
         guidance: true,
@@ -90,12 +90,12 @@ export const docs = {
 export const docsDense = {
   usage: {
     description:
-      'Wraps subtree w/ specific Astryx theme. For static production themes, use `npx astryx theme build` + generated CSS + built theme object for first-paint/SSR performance. Use runtime `defineTheme()` for dynamic themes or prototyping. Token names always start with `--` (e.g. `--color-accent`, `--color-background-surface`).',
+      'Wraps subtree w/ specific Astryx theme. For static production themes, use `astryx theme build` + generated CSS + built theme object for first-paint/SSR performance. Use runtime `defineTheme()` for dynamic themes or prototyping. Token names always start with `--` (e.g. `--color-accent`, `--color-background-surface`).',
     bestPractices: [
       {
         guidance: true,
         description:
-          'Build app themes known ahead of time w/ `npx astryx theme build`; import generated CSS + built theme object.',
+          'Build app themes known ahead of time w/ `astryx theme build`; import generated CSS + built theme object.',
       },
       {
         guidance: true,

package/src/theme/Theme.tsx

@@ -127,7 +127,7 @@ function useThemeStyleInjection(theme: DefinedTheme): void {
           `For better performance, use the pre-built theme:\n\n` +
           `  import {${theme.name}Theme} from '@astryxdesign/theme-${theme.name}/built';\n` +
           `  import '@astryxdesign/theme-${theme.name}/theme.css';\n\n` +
-          `For custom themes, run \`npx astryx theme build <file>\` to generate ` +
+          `For custom themes, run \`npx @astryxdesign/cli theme build <file>\` to generate ` +
           `the built artifacts.`,
       );
     }