@astryxdesign/cli 0.4.2-canary.791f395 → 0.4.2-canary.8b07cb9

package/api/theme/build/build.icons-specifier.test.mjs

@@ -0,0 +1,149 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Direct-API tests for `themeBuild`'s `iconsSpecifier` option (#4620).
+ *
+ * The CLI surface of `--icons-specifier` is pinned in
+ * clients/cli/commands/build-theme.icons-specifier.test.mjs; these tests pin
+ * the programmatic surface that watch mode, editor tooling, and build scripts
+ * call directly: the option reaches the emitted module, its absence leaves the
+ * scraped specifier byte-for-byte alone, and `check` mode compares the
+ * specifier-bearing text like any other generated byte — outputs built with a
+ * different specifier than the one being checked against are stale, not clean.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {themeBuild} from './build.mjs';
+
+let tmpDir;
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(
+    path.join(os.tmpdir(), 'astryx-api-icons-specifier-'),
+  );
+});
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/**
+ * Write a theme source (plus a loadable icons source beside it) under
+ * `<tmpDir>/src/`. The registry is a plain object — the emit path only
+ * re-exports it, so no React is needed.
+ */
+function writeIconTheme({withIcons = true, name = 'icotheme'} = {}) {
+  const srcDir = path.join(tmpDir, 'src');
+  fs.mkdirSync(srcDir, {recursive: true});
+  fs.writeFileSync(
+    path.join(srcDir, 'icons.ts'),
+    `export const myIcons = { close: 'x' };\n`,
+  );
+  const iconLines = withIcons ? [`import { myIcons } from './icons';`] : [];
+  fs.writeFileSync(
+    path.join(srcDir, `${name}.ts`),
+    [
+      ...iconLines,
+      `export default { name: '${name}', tokens: { '--color-bg': '#fff' }${
+        withIcons ? ', icons: myIcons' : ''
+      } };`,
+      '',
+    ].join('\n'),
+  );
+  return `src/${name}.ts`;
+}
+
+function builtModule(name = 'icotheme') {
+  return fs.readFileSync(path.join(tmpDir, 'dist', `${name}.js`), 'utf8');
+}
+
+describe('themeBuild({iconsSpecifier}) — direct API', () => {
+  it('emits the declared specifier into the generated module', async () => {
+    const file = writeIconTheme();
+
+    const result = await themeBuild(
+      file,
+      {out: 'dist/theme.css', iconsSpecifier: './icons.mjs'},
+      {cwd: tmpDir},
+    );
+
+    expect(result?.type).toBe('theme.build');
+    const js = builtModule();
+    expect(js).toContain(`import { myIcons } from "./icons.mjs";`);
+    // The registry re-export survives the override.
+    expect(js).toContain('export { myIcons }');
+  });
+
+  it('emits the scraped specifier unchanged when the option is omitted', async () => {
+    const file = writeIconTheme();
+
+    const result = await themeBuild(
+      file,
+      {out: 'dist/theme.css'},
+      {cwd: tmpDir},
+    );
+
+    expect(result?.type).toBe('theme.build');
+    expect(builtModule()).toContain(`import { myIcons } from './icons';`);
+  });
+
+  it('is inert for a theme with no icons field', async () => {
+    const file = writeIconTheme({withIcons: false});
+
+    const result = await themeBuild(
+      file,
+      {out: 'dist/theme.css', iconsSpecifier: './icons.mjs'},
+      {cwd: tmpDir},
+    );
+
+    expect(result?.type).toBe('theme.build');
+    // The header comment's usage example mentions imports; only a real
+    // statement (line-leading `import`) would be a leak.
+    const js = builtModule();
+    expect(js).not.toMatch(/^import /m);
+    expect(js).not.toContain('icons.mjs');
+  });
+
+  it('check mode is clean against outputs built with the same specifier', async () => {
+    const file = writeIconTheme();
+    await themeBuild(
+      file,
+      {out: 'dist/theme.css', iconsSpecifier: './icons.mjs'},
+      {cwd: tmpDir},
+    );
+
+    const result = await themeBuild(
+      file,
+      {out: 'dist/theme.css', check: true, iconsSpecifier: './icons.mjs'},
+      {cwd: tmpDir},
+    );
+
+    expect(result?.type).toBe('theme.build.check');
+    expect(result?.data.upToDate).toBe(true);
+    expect(result?.data.stale).toEqual([]);
+  });
+
+  it('check mode reports outputs stale when the specifier differs', async () => {
+    const file = writeIconTheme();
+    await themeBuild(
+      file,
+      {out: 'dist/theme.css', iconsSpecifier: './icons.mjs'},
+      {cwd: tmpDir},
+    );
+
+    // Checking without the option regenerates with the scraped './icons' —
+    // different bytes than the on-disk module, so the check must flag it.
+    const result = await themeBuild(
+      file,
+      {out: 'dist/theme.css', check: true},
+      {cwd: tmpDir},
+    );
+
+    expect(result?.type).toBe('theme.build.check');
+    expect(result?.data.upToDate).toBe(false);
+    expect(result?.data.stale.some(entry => entry.reason === 'outdated')).toBe(
+      true,
+    );
+  });
+});

package/api/theme/build/build.mjs

@@ -591,6 +591,30 @@ const themeScopeStart = (/** @type {string} */ name) =>
   `[data-astryx-theme="${name}"]`;
 const THEME_SCOPE_TO = `[data-astryx-theme]`;
 
+/**
+ * Module extensions the theme loader resolves, source before artifact.
+ *
+ * `theme build` writes `<name>.js` next to `<name>.ts`, and jiti's default
+ * order tries `.js` first — so once a base theme had been built, every sibling
+ * theme that `extends` it resolved to that generated artifact instead of the
+ * source. The artifact carries no `components` and exports a different name,
+ * so the inheritance silently evaporated. Resolving source first is also what
+ * the author's TypeScript sees, which is the point: the CSS the build emits
+ * matches the theme they type-checked.
+ */
+const THEME_MODULE_EXTENSIONS = [
+  '.ts',
+  '.tsx',
+  '.mts',
+  '.cts',
+  '.mtsx',
+  '.ctsx',
+  '.mjs',
+  '.cjs',
+  '.js',
+  '.json',
+];
+
 /**
  * Import a theme module using jiti and find the defineTheme() result.
  * Returns the resolved DefinedTheme object.
@@ -601,6 +625,7 @@ async function importThemeModule(filePath) {
   const jiti = createJiti(import.meta.url, {
     moduleCache: false,
     jsx: true,
+    extensions: THEME_MODULE_EXTENSIONS,
   });
 
   const mod = await jiti.import(filePath, {default: true});
@@ -733,6 +758,13 @@ function extractIconInfo(filePath) {
  * Includes the theme name, marker, and re-exports the icon registry.
  * All styling is in the CSS file.
  *
+ * The module carries the theme's resolved `components` and on-media surfaces
+ * alongside its tokens. They are not needed to apply the theme — the CSS holds
+ * all of that — but a built theme is a legitimate base for `extends` (the
+ * shipped themes expose one as their `./built` subpath), and a base that
+ * carries only tokens makes its children silently lose every component
+ * override it had.
+ *
  * The icon registry is imported rather than inlined because it holds React
  * elements, which cannot be serialized. `extractIconInfo` lifts the specifier
  * out of the TypeScript source, where an extensionless `./icons` is resolved by
@@ -774,6 +806,27 @@ function generateBuiltModule(themeDef, iconInfo, iconsSpecifier) {
     .map((line, i) => (i === 0 ? line : '  ' + line))
     .join('\n');
 
+  /**
+   * Serialize a resolved theme field as an indented object literal, or '' when
+   * there is nothing to emit.
+   * @param {string} field
+   * @param {unknown} value
+   * @returns {string}
+   */
+  const serializeField = (field, value) => {
+    if (!value || Object.keys(value).length === 0) return '';
+    const body = JSON.stringify(value, null, 2)
+      .split('\n')
+      .map((line, i) => (i === 0 ? line : '  ' + line))
+      .join('\n');
+    return `  ${field}: ${body},\n`;
+  };
+
+  const inheritableFields =
+    serializeField('components', themeDef.components) +
+    serializeField('__onDark', themeDef.__onDark) +
+    serializeField('__onLight', themeDef.__onLight);
+
   return `${iconImport}/**
  * ${themeDef.name} theme — built by \`${getCliInvocation()} theme build\`
  * Import the CSS file alongside this module:
@@ -785,7 +838,7 @@ export const ${toIdentifier(themeDef.name)}Theme = {
   name: '${themeDef.name}',
   __built: true,
   tokens: ${tokensStr},
-${iconsField}
+${inheritableFields}${iconsField}
 };
 ${iconReExport}`;
 }
@@ -1099,20 +1152,29 @@ export async function themeBuild(
   let css;
   let resolvedTheme;
   {
-    // jiti returns an already-resolved theme; legacy eval returns raw input.
-    const isAlreadyResolved =
-      !themeDef.typography && !themeDef.motion && !themeDef.radius;
-    if (isAlreadyResolved) {
-      resolvedTheme = themeDef;
+    // jiti returns an already-resolved theme; a plain object literal (or the
+    // legacy eval path) returns raw defineTheme input, which still has to go
+    // through the resolver. Detect that by the input-only fields — a resolved
+    // theme has none of them — and hand the WHOLE object over: picking fields
+    // by name is how `extends` (and `color`, and `syntax`) used to be dropped
+    // on the way in.
+    const INPUT_ONLY_FIELDS = [
+      'extends',
+      'typography',
+      'motion',
+      'radius',
+      'color',
+      'syntax',
+      'onDark',
+      'onLight',
+    ];
+    const needsResolution = INPUT_ONLY_FIELDS.some(
+      field => themeDef[field] !== undefined,
+    );
+    if (needsResolution) {
+      resolvedTheme = _defineTheme({...themeDef});
     } else {
-      resolvedTheme = _defineTheme({
-        name: themeDef.name,
-        typography: themeDef.typography,
-        motion: themeDef.motion,
-        radius: themeDef.radius,
-        tokens: themeDef.tokens,
-        components: themeDef.components,
-      });
+      resolvedTheme = themeDef;
     }
     const scopeSelector = themeScopeStart(themeDef.name);
     const scopeTo = THEME_SCOPE_TO;

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

@@ -323,6 +323,180 @@ describe('themeBuild() — the shipped theme template', () => {
     expect(fs.existsSync(path.join(tmpDir, 'my-theme.css'))).toBe(true);
     // The template teaches custom variants; the augmentation it promises the
     // reader has to actually be generated.
-    expect(fs.existsSync(path.join(tmpDir, 'my-theme.variants.d.ts'))).toBe(true);
+    expect(fs.existsSync(path.join(tmpDir, 'my-theme.variants.d.ts'))).toBe(
+      true,
+    );
+  });
+});
+
+describe('themeBuild() — extends', () => {
+  // These fixtures `import {defineTheme} from '@astryxdesign/core/theme'` the
+  // way a real theme file does, so they have to sit somewhere that specifier
+  // resolves — an OS temp dir has no node_modules above it.
+  let extDir;
+  beforeEach(() => {
+    extDir = fs.mkdtempSync(
+      path.join(path.resolve(import.meta.dirname, '../../..'), '.tmp-extends-'),
+    );
+  });
+  afterEach(() => {
+    fs.rmSync(extDir, {recursive: true, force: true});
+  });
+
+  /**
+   * Every `prop: value` a generated stylesheet actually applies. Header
+   * comments and scope wrappers are ignored — two themes never share those.
+   */
+  function declarations(css) {
+    return new Set(
+      css
+        .split('\n')
+        .map(l => l.trim())
+        .filter(l => /^[-a-z][^{}]*:.+;$/.test(l)),
+    );
+  }
+  /** Every component rule a stylesheet opens, e.g. `.astryx-switch {`. */
+  function selectors(css) {
+    return new Set(
+      css
+        .split('\n')
+        .map(l => l.trim())
+        .filter(l => l.endsWith('{') && l.startsWith('.')),
+    );
+  }
+
+  /** A base theme with geometry, elevation and a component override. */
+  const BASE_SOURCE = `export const brandTheme = {
+    name: 'ext-base',
+    tokens: {
+      '--radius-element': '6px',
+      '--shadow-low': '0 1px 3px rgb(0 0 0 / 0.1)',
+      '--color-border-emphasized': '#D4D4D4',
+    },
+    components: {
+      switch: {base: {backgroundColor: 'var(--color-border-emphasized)'}},
+    },
+  };\n`;
+
+  /**
+   * The child names its base with a plain relative specifier, exactly as a
+   * generated palette does. `theme build` writes `ext-base.js` next to
+   * `ext-base.mjs`, so `./ext-base` is ambiguous — and the artifact, which
+   * exports `extBaseTheme` rather than `brandTheme`, is the wrong answer.
+   */
+  const CHILD_SOURCE = `import {defineTheme} from '@astryxdesign/core/theme';
+  import {brandTheme} from './ext-base';
+  export const paletteTheme = defineTheme({
+    name: 'ext-child',
+    extends: brandTheme,
+    tokens: {'--color-accent': 'hsl(220 88% 72%)'},
+  });\n`;
+
+  it('emits every declaration its base emits (the child stylesheet is self-contained)', async () => {
+    fs.writeFileSync(path.join(extDir, 'ext-base.mjs'), BASE_SOURCE);
+    fs.writeFileSync(path.join(extDir, 'ext-child.mjs'), CHILD_SOURCE);
+
+    // Build the base FIRST, as any real project does — that write is what
+    // used to poison the child's build.
+    await themeBuild('ext-base.mjs', {}, {cwd: extDir});
+    await themeBuild('ext-child.mjs', {}, {cwd: extDir});
+
+    const baseCss = fs.readFileSync(path.join(extDir, 'ext-base.css'), 'utf8');
+    const childCss = fs.readFileSync(
+      path.join(extDir, 'ext-child.css'),
+      'utf8',
+    );
+
+    const childDecls = declarations(childCss);
+    expect([...declarations(baseCss)].filter(d => !childDecls.has(d))).toEqual(
+      [],
+    );
+
+    const childSelectors = selectors(childCss);
+    expect([...selectors(baseCss)].filter(s => !childSelectors.has(s))).toEqual(
+      [],
+    );
+
+    // …and the child's own override still wins.
+    expect(childCss).toContain('--color-accent: hsl(220 88% 72%);');
+  });
+
+  it('resolves the base from its source, not from the generated sibling artifact', async () => {
+    fs.writeFileSync(path.join(extDir, 'ext-base.mjs'), BASE_SOURCE);
+    fs.writeFileSync(path.join(extDir, 'ext-child.mjs'), CHILD_SOURCE);
+
+    await themeBuild('ext-base.mjs', {}, {cwd: extDir});
+    const result = await themeBuild('ext-child.mjs', {}, {cwd: extDir});
+
+    expect(result?.data.componentCount).toBe(1);
+    expect(result?.data.tokenCount).toBe(4);
+  });
+
+  it('inherits component overrides when the base IS a built theme module', async () => {
+    fs.writeFileSync(path.join(extDir, 'ext-base.mjs'), BASE_SOURCE);
+    await themeBuild('ext-base.mjs', {}, {cwd: extDir});
+
+    // Extending a package's pre-built theme module (e.g. the `./built`
+    // subpath the shipped themes expose) must not silently drop its
+    // component overrides.
+    fs.writeFileSync(
+      path.join(extDir, 'ext-built-child.mjs'),
+      `import {defineTheme} from '@astryxdesign/core/theme';
+      import {extBaseTheme} from './ext-base.js';
+      export const builtChildTheme = defineTheme({
+        name: 'ext-built-child',
+        extends: extBaseTheme,
+      });\n`,
+    );
+
+    await themeBuild('ext-built-child.mjs', {}, {cwd: extDir});
+    const css = fs.readFileSync(
+      path.join(extDir, 'ext-built-child.css'),
+      'utf8',
+    );
+
+    expect(css).toContain('.astryx-switch {');
+    expect(css).toContain('--radius-element: 6px;');
+  });
+
+  it('resolves extends on a plain object theme file (no defineTheme call)', async () => {
+    fs.writeFileSync(path.join(extDir, 'ext-base.mjs'), BASE_SOURCE);
+    fs.writeFileSync(
+      path.join(extDir, 'ext-plain.mjs'),
+      `import {brandTheme} from './ext-base.mjs';
+      export default {
+        name: 'ext-plain',
+        extends: brandTheme,
+        tokens: {'--color-accent': '#ff0000'},
+      };\n`,
+    );
+
+    await themeBuild('ext-base.mjs', {}, {cwd: extDir});
+    await themeBuild('ext-plain.mjs', {}, {cwd: extDir});
+
+    const css = fs.readFileSync(path.join(extDir, 'ext-plain.css'), 'utf8');
+    expect(css).toContain('--radius-element: 6px;');
+    expect(css).toContain('.astryx-switch {');
+  });
+
+  it('fails loudly when the base import resolved to nothing', async () => {
+    fs.writeFileSync(
+      path.join(extDir, 'ext-broken.mjs'),
+      `import {defineTheme} from '@astryxdesign/core/theme';
+      import {notAThing} from './ext-missing.mjs';
+      export const brokenTheme = defineTheme({
+        name: 'ext-broken',
+        extends: notAThing,
+        tokens: {'--color-accent': '#ff0000'},
+      });\n`,
+    );
+    fs.writeFileSync(
+      path.join(extDir, 'ext-missing.mjs'),
+      `export const somethingElse = 1;\n`,
+    );
+
+    await expect(
+      themeBuild('ext-broken.mjs', {}, {cwd: extDir}),
+    ).rejects.toThrow(/extends/);
   });
 });

package/assets/docs/theme.doc.mjs

@@ -253,10 +253,15 @@ const brandTheme = defineTheme({
             ['tokens', 'Base tokens are copied first, then child tokens override on top.'],
             ['components', 'Deep-merged: child component rules override matching keys from the base.'],
             ['icons', 'Shallow-merged: child icons override matching names from the base.'],
-            ['fonts', 'Base fonts included first, then child fonts appended.'],
+            ['indicators', 'Shallow-merged: child indicators override matching names from the base.'],
+            ['onDark, onLight', "Deep-merged per surface: the base's resolved surface first, then the child's overrides."],
             ['typography, motion, radius, color', 'Child config replaces base entirely (these are scale inputs, not additive).'],
           ],
         },
+        {
+          type: 'prose',
+          text: 'Inheritance is resolved when the theme is defined, so an extended theme is flat: `astryx theme build` emits one self-contained stylesheet holding everything the child inherited, and the base theme\'s CSS does not need to be loaded next to it. A base that is not a theme — most often an import that missed — is a build error rather than a theme that silently inherits nothing.',
+        },
       ],
     },
     {

package/assets/templates/blocks/components/ComplexSelector/ComplexSelectorDeadlinePicker.doc.mjs

@@ -0,0 +1,20 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'ComplexSelector',
+  name: 'ComplexSelector — Deadline Picker',
+  displayName: 'Complex Selector — Deadline Picker',
+  description:
+    'A multi-step deadline field: pick a preset like Today or Next week, or switch to a custom date and time before applying. The popup stays open until the user commits, so the content owns the Apply action.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: [
+    'ComplexSelector',
+    'RadioList',
+    'DateInput',
+    'TimeInput',
+    'Button',
+  ],
+};

package/assets/templates/blocks/components/ComplexSelector/ComplexSelectorDeadlinePicker.tsx

@@ -0,0 +1,87 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {ComplexSelector} from '@astryxdesign/core/ComplexSelector';
+import {RadioList, RadioListItem} from '@astryxdesign/core/RadioList';
+import {DateInput} from '@astryxdesign/core/DateInput';
+import {TimeInput} from '@astryxdesign/core/TimeInput';
+import {Button} from '@astryxdesign/core/Button';
+import {VStack} from '@astryxdesign/core/Layout';
+
+type ISODate =
+  `${number}${number}${number}${number}-${number}${number}-${number}${number}`;
+type ISOTime = string & {readonly __brand: 'ISOTimeString'};
+
+interface Deadline {
+  preset: 'today' | 'next-week' | 'custom';
+  date: ISODate;
+  time: ISOTime;
+}
+
+const presetLabels: Record<Deadline['preset'], string> = {
+  today: 'Today',
+  'next-week': 'Next week',
+  custom: 'Custom date',
+};
+
+function formatDeadline(value: Deadline) {
+  if (value.preset === 'custom') {
+    return `${value.date} at ${value.time}`;
+  }
+  return presetLabels[value.preset];
+}
+
+export default function ComplexSelectorDeadlinePicker() {
+  const [value, setValue] = useState<Deadline>({
+    preset: 'today',
+    date: '2026-04-06' as ISODate,
+    time: '17:00' as ISOTime,
+  });
+
+  return (
+    <ComplexSelector<Deadline>
+      label="Deadline"
+      description="Choose a preset or set a custom date and time."
+      value={value}
+      onChange={setValue}
+      triggerLabel={formatDeadline(value)}
+      style={{width: 320}}>
+      {(selectedValue, onChange, close) => {
+        const set = (patch: Partial<Deadline>) =>
+          onChange({...selectedValue, ...patch});
+
+        return (
+          <VStack gap={4} style={{width: 320}}>
+            <RadioList
+              label="When is it due?"
+              value={selectedValue.preset}
+              onChange={preset => set({preset: preset as Deadline['preset']})}>
+              <RadioListItem label="Today" value="today" />
+              <RadioListItem label="Next week" value="next-week" />
+              <RadioListItem label="Custom date" value="custom" />
+            </RadioList>
+
+            {selectedValue.preset === 'custom' && (
+              <VStack gap={3}>
+                <DateInput
+                  label="Date"
+                  value={selectedValue.date}
+                  onChange={date => date && set({date})}
+                />
+                <TimeInput
+                  label="Time"
+                  value={selectedValue.time}
+                  onChange={time => time && set({time})}
+                />
+              </VStack>
+            )}
+
+            <Button label="Apply" variant="primary" onClick={close} />
+          </VStack>
+        );
+      }}
+    </ComplexSelector>
+  );
+}

package/assets/templates/blocks/components/ComplexSelector/ComplexSelectorShowcase.doc.mjs

@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'ComplexSelector',
+  name: 'ComplexSelector',
+  displayName: 'Complex Selector',
+  description:
+    'A two-axis picker: choose a fruit and a ripeness level from one control. ComplexSelector owns the trigger, popover, and focus restore while the custom grid owns its keyboard semantics.',
+  isReady: true,
+  aspectRatio: 1,
+  isShowcase: true,
+  componentsUsed: ['ComplexSelector', 'Text'],
+};

package/assets/templates/blocks/components/ComplexSelector/ComplexSelectorShowcase.tsx

@@ -0,0 +1,199 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useEffect, useState} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {ComplexSelector} from '@astryxdesign/core/ComplexSelector';
+import {Text} from '@astryxdesign/core/Text';
+import {useGridFocus} from '@astryxdesign/core/hooks';
+import {
+  borderVars,
+  colorVars,
+  radiusVars,
+  spacingVars,
+} from '@astryxdesign/core/theme/tokens.stylex';
+
+type Fruit = 'Apple' | 'Pear' | 'Peach' | 'Plum';
+type Ripeness = 'Crisp' | 'Tender' | 'Juicy' | 'Peak';
+
+interface FruitValue {
+  fruit: Fruit;
+  ripeness: Ripeness;
+}
+
+const fruits: Array<{id: Fruit; emoji: string; description: string}> = [
+  {id: 'Apple', emoji: '🍎', description: 'Bright and balanced'},
+  {id: 'Pear', emoji: '🍐', description: 'Soft floral sweetness'},
+  {id: 'Peach', emoji: '🍑', description: 'Round summer flavor'},
+  {id: 'Plum', emoji: '🟣', description: 'Jammy and tart'},
+];
+
+const ripenessLevels: Array<{
+  id: Ripeness;
+  shortLabel: string;
+  description: string;
+}> = [
+  {id: 'Crisp', shortLabel: 'C', description: 'Snappy bite'},
+  {id: 'Tender', shortLabel: 'T', description: 'Easy bite'},
+  {id: 'Juicy', shortLabel: 'J', description: 'Full juice'},
+  {id: 'Peak', shortLabel: 'P', description: 'Most intense'},
+];
+
+const GRID_CELL_SELECTOR = '[role="gridcell"]';
+
+const styles = stylex.create({
+  grid: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: spacingVars['--spacing-1'],
+    minWidth: 280,
+  },
+  row: {
+    display: 'grid',
+    gridTemplateColumns: 'minmax(150px, 1fr) repeat(4, 44px)',
+    alignItems: 'center',
+    columnGap: spacingVars['--spacing-1'],
+  },
+  rowHeader: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: spacingVars['--spacing-2'],
+    textAlign: 'start',
+    minWidth: 0,
+  },
+  emoji: {
+    fontSize: 18,
+    flexShrink: 0,
+  },
+  fruitText: {
+    display: 'flex',
+    flexDirection: 'column',
+    minWidth: 0,
+  },
+  cell: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    height: 36,
+    borderWidth: borderVars['--border-width'],
+    borderStyle: 'solid',
+    borderColor: colorVars['--color-border'],
+    borderRadius: radiusVars['--radius-container'],
+    backgroundColor: colorVars['--color-background-card'],
+    color: colorVars['--color-text-secondary'],
+    fontFamily: 'inherit',
+    cursor: 'pointer',
+    ':hover': {
+      '@media (hover: hover)': {
+        borderColor: colorVars['--color-border-emphasized'],
+        color: colorVars['--color-text-primary'],
+      },
+    },
+  },
+  cellSelected: {
+    borderColor: colorVars['--color-accent'],
+    backgroundColor: colorVars['--color-accent'],
+    color: colorVars['--color-on-accent'],
+  },
+});
+
+function FruitRipenessGrid({
+  value,
+  onChange,
+}: {
+  value: FruitValue;
+  onChange: (value: FruitValue) => void;
+}) {
+  const {gridRef, handleKeyDown, handleFocus, focusCell} =
+    useGridFocus<HTMLDivElement>({
+      columns: ripenessLevels.length,
+      cellSelector: GRID_CELL_SELECTOR,
+      hasRovingTabIndex: true,
+    });
+
+  useEffect(() => {
+    const rowIndex = fruits.findIndex(f => f.id === value.fruit);
+    const columnIndex = ripenessLevels.findIndex(l => l.id === value.ripeness);
+    requestAnimationFrame(() => {
+      focusCell(
+        rowIndex >= 0 && columnIndex >= 0
+          ? rowIndex * ripenessLevels.length + columnIndex
+          : 0,
+      );
+    });
+  }, [focusCell, value]);
+
+  return (
+    <div
+      ref={gridRef}
+      role="grid"
+      aria-label="Fruit ripeness choices"
+      onKeyDown={handleKeyDown}
+      onFocus={handleFocus}
+      {...stylex.props(styles.grid)}>
+      {fruits.map(fruit => (
+        <div key={fruit.id} role="row" {...stylex.props(styles.row)}>
+          <div role="rowheader" {...stylex.props(styles.rowHeader)}>
+            <span aria-hidden="true" {...stylex.props(styles.emoji)}>
+              {fruit.emoji}
+            </span>
+            <span {...stylex.props(styles.fruitText)}>
+              <Text type="body">{fruit.id}</Text>
+              <Text type="supporting" color="secondary">
+                {fruit.description}
+              </Text>
+            </span>
+          </div>
+          {ripenessLevels.map(level => {
+            const isSelected =
+              value.fruit === fruit.id && value.ripeness === level.id;
+            return (
+              <button
+                key={`${fruit.id}-${level.id}`}
+                type="button"
+                role="gridcell"
+                aria-label={`${fruit.id}, ${level.id}: ${level.description}`}
+                aria-selected={isSelected || undefined}
+                tabIndex={isSelected ? 0 : -1}
+                onClick={() => onChange({fruit: fruit.id, ripeness: level.id})}
+                {...stylex.props(
+                  styles.cell,
+                  isSelected && styles.cellSelected,
+                )}>
+                {level.shortLabel}
+              </button>
+            );
+          })}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+export default function ComplexSelectorShowcase() {
+  const [value, setValue] = useState<FruitValue>({
+    fruit: 'Apple',
+    ripeness: 'Juicy',
+  });
+
+  return (
+    <ComplexSelector<FruitValue>
+      label="Fruit blend"
+      description="Choose a fruit and ripeness in one control. Arrow keys move across the grid."
+      value={value}
+      onChange={setValue}
+      triggerLabel={`${value.fruit} · ${value.ripeness}`}
+      style={{width: 280}}>
+      {(selectedValue, onChange, close) => (
+        <FruitRipenessGrid
+          value={selectedValue}
+          onChange={nextValue => {
+            onChange(nextValue);
+            close();
+          }}
+        />
+      )}
+    </ComplexSelector>
+  );
+}

package/assets/templates/blocks/components/ComplexSelector/ComplexSelectorTreeSearch.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'ComplexSelector',
+  name: 'ComplexSelector — Tree Search',
+  displayName: 'Complex Selector — Tree Search',
+  description:
+    'A destination picker that combines a search field with a TreeList hierarchy. TreeList owns tree keyboard navigation; ComplexSelector owns the trigger, popover, and focus restore. Selecting a folder closes the popup.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['ComplexSelector', 'TextInput', 'TreeList'],
+};

package/assets/templates/blocks/components/ComplexSelector/ComplexSelectorTreeSearch.tsx

@@ -0,0 +1,188 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useMemo, useState} from 'react';
+import {ComplexSelector} from '@astryxdesign/core/ComplexSelector';
+import {TextInput} from '@astryxdesign/core/TextInput';
+import {TreeList, type TreeListItemData} from '@astryxdesign/core/TreeList';
+import {Text} from '@astryxdesign/core/Text';
+import {VStack} from '@astryxdesign/core/Layout';
+
+interface DestinationNode {
+  id: string;
+  label: string;
+  path: string;
+  children?: DestinationNode[];
+}
+
+interface Destination {
+  id: string;
+  label: string;
+  path: string;
+}
+
+const destinationTree: DestinationNode[] = [
+  {
+    id: 'workspace',
+    label: 'Workspace',
+    path: '/Workspace',
+    children: [
+      {
+        id: 'research',
+        label: 'Research',
+        path: '/Workspace/Research',
+        children: [
+          {
+            id: 'field-notes',
+            label: 'Field notes',
+            path: '/Workspace/Research/Field notes',
+          },
+          {
+            id: 'interviews',
+            label: 'Interviews',
+            path: '/Workspace/Research/Interviews',
+          },
+        ],
+      },
+      {
+        id: 'roadmap',
+        label: 'Roadmap',
+        path: '/Workspace/Roadmap',
+      },
+    ],
+  },
+  {
+    id: 'teams',
+    label: 'Teams',
+    path: '/Teams',
+    children: [
+      {
+        id: 'design-systems',
+        label: 'Design systems',
+        path: '/Teams/Design systems',
+        children: [
+          {
+            id: 'accessibility',
+            label: 'Accessibility',
+            path: '/Teams/Design systems/Accessibility',
+          },
+        ],
+      },
+    ],
+  },
+];
+
+function matches(node: DestinationNode, query: string): boolean {
+  if (node.label.toLowerCase().includes(query)) {
+    return true;
+  }
+  return (node.children ?? []).some(child => matches(child, query));
+}
+
+function filterTree(
+  nodes: DestinationNode[],
+  query: string,
+): DestinationNode[] {
+  if (!query) {
+    return nodes;
+  }
+  return nodes
+    .filter(node => matches(node, query))
+    .map(node => ({
+      ...node,
+      children: node.children ? filterTree(node.children, query) : undefined,
+    }));
+}
+
+function toItems(
+  nodes: DestinationNode[],
+  selectedId: string,
+  onSelect: (value: Destination) => void,
+): TreeListItemData[] {
+  return nodes.map(node => {
+    const hasChildren = (node.children ?? []).length > 0;
+    return {
+      id: node.id,
+      label: node.label,
+      isSelected: node.id === selectedId,
+      isExpanded: true,
+      onClick: hasChildren
+        ? undefined
+        : () => onSelect({id: node.id, label: node.label, path: node.path}),
+      children: hasChildren
+        ? toItems(node.children ?? [], selectedId, onSelect)
+        : undefined,
+    };
+  });
+}
+
+function DestinationSearch({
+  value,
+  onChange,
+  close,
+}: {
+  value: Destination;
+  onChange: (value: Destination) => void;
+  close: () => void;
+}) {
+  const [query, setQuery] = useState('');
+  const items = useMemo(
+    () =>
+      toItems(
+        filterTree(destinationTree, query.toLowerCase()),
+        value.id,
+        next => {
+          onChange(next);
+          close();
+        },
+      ),
+    [query, value.id, onChange, close],
+  );
+
+  return (
+    <VStack gap={3} style={{width: 360}}>
+      <TextInput
+        label="Search destinations"
+        isLabelHidden
+        value={query}
+        onChange={setQuery}
+        hasClear
+        placeholder="Search folders or teams"
+      />
+      {items.length > 0 ? (
+        <TreeList items={items} density="compact" />
+      ) : (
+        <Text type="supporting" color="secondary">
+          No matching destinations.
+        </Text>
+      )}
+    </VStack>
+  );
+}
+
+export default function ComplexSelectorTreeSearch() {
+  const [value, setValue] = useState<Destination>({
+    id: 'accessibility',
+    label: 'Accessibility',
+    path: '/Teams/Design systems/Accessibility',
+  });
+
+  return (
+    <ComplexSelector<Destination>
+      label="Destination"
+      description="Search and browse nested folders."
+      value={value}
+      onChange={setValue}
+      triggerLabel={value.path}
+      style={{width: 360}}>
+      {(selectedValue, onChange, close) => (
+        <DestinationSearch
+          value={selectedValue}
+          onChange={onChange}
+          close={close}
+        />
+      )}
+    </ComplexSelector>
+  );
+}

package/clients/cli/commands/build-theme.icons-specifier.test.mjs

@@ -15,15 +15,34 @@
  * declared rather than inferred. Absent the flag, output is byte-for-byte what
  * it was before, which keeps the default no-`--out` flow — where the neighbour
  * is an uncompiled `icons.tsx` that only a bundler can resolve — working.
+ *
+ * The spawned-process block at the bottom pins what only real processes can
+ * prove: the emitted module actually loads under Node ESM, and the watch
+ * loop's child re-invocations carry the flag to every rebuild.
  */
 
 import {describe, it, expect, beforeAll, beforeEach, afterEach} from 'vitest';
+import {spawn, spawnSync} from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
+import {fileURLToPath, pathToFileURL} from 'node:url';
 import {ensureCoreBuilt} from './ensure-core-built.mjs';
 import {runCli} from '../../../test-utils/run-cli.mjs';
 
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI_BIN = path.resolve(__dirname, '../bin/astryx.mjs');
+
+/** Poll until `predicate()` is true or the timeout elapses. */
+async function waitFor(predicate, {timeout = 20000, interval = 100} = {}) {
+  const start = Date.now();
+  for (;;) {
+    if (predicate()) return true;
+    if (Date.now() - start > timeout) return false;
+    await new Promise(r => setTimeout(r, interval));
+  }
+}
+
 /**
  * The emitted icon import, or null. Reads the statement rather than the whole
  * file: the `@generated` header quotes the source filename and a usage example,
@@ -142,13 +161,7 @@ describe('theme build --icons-specifier', () => {
     const relativeTheme = path.relative(project, themeFile);
 
     const built = await runCli(
-      [
-        'theme',
-        'build',
-        relativeTheme,
-        '--icons-specifier',
-        './icons.mjs',
-      ],
+      ['theme', 'build', relativeTheme, '--icons-specifier', './icons.mjs'],
       project,
     );
     expect(built.code).toBe(0);
@@ -223,3 +236,114 @@ describe('theme build --icons-specifier', () => {
     expect(generated).not.toContain('icons:');
   });
 });
+
+describe('theme build --icons-specifier (spawned processes)', () => {
+  it('emits a module Node can actually load', async () => {
+    const project = path.join(tmpDir, 'project');
+    const themeFile = writeThemeWithIcons(project, 'loadable');
+
+    const result = await runCli(
+      [
+        'theme',
+        'build',
+        path.relative(project, themeFile),
+        '--icons-specifier',
+        './icons.mjs',
+      ],
+      project,
+    );
+    expect(result.code).toBe(0);
+
+    // The text assertions above prove the emitted line; only a real Node
+    // process proves the module resolves and evaluates. That distinction is
+    // the regression #4620 shipped: every byte existed, none of them loaded.
+    const builtUrl = pathToFileURL(path.join(project, 'loadable.js'));
+    const probe = spawnSync(
+      process.execPath,
+      [
+        '--input-type=module',
+        '-e',
+        `const m = await import(${JSON.stringify(builtUrl.href)});` +
+          `if (m.loadableTheme?.name !== 'loadable') throw new Error('bad theme export');` +
+          `if (typeof m.testIcons !== 'object') throw new Error('bad registry export');`,
+      ],
+      {encoding: 'utf8'},
+    );
+    expect(probe.stderr).toBe('');
+    expect(probe.status).toBe(0);
+  });
+
+  it('watch mode forwards the flag to every rebuild', async () => {
+    const project = path.join(tmpDir, 'project');
+    const themeFile = writeThemeWithIcons(project, 'watched');
+    const cssFile = path.join(project, 'out', 'theme.css');
+    const builtFile = path.join(project, 'out', 'watched.js');
+    const declaredImport = 'import { testIcons } from "./icons.mjs";';
+
+    const child = spawn(
+      process.execPath,
+      [
+        CLI_BIN,
+        'theme',
+        'build',
+        path.relative(project, themeFile),
+        '--out',
+        'out/theme.css',
+        '--icons-specifier',
+        './icons.mjs',
+        '--watch',
+      ],
+      {cwd: project, env: {...process.env, FORCE_COLOR: '0'}},
+    );
+    let output = '';
+    child.stdout.on('data', d => (output += d.toString()));
+    child.stderr.on('data', d => (output += d.toString()));
+
+    try {
+      // Initial build: the declared specifier reaches the module.
+      expect(await waitFor(() => fs.existsSync(cssFile))).toBe(true);
+      expect(await waitFor(() => /Watching/i.test(output))).toBe(true);
+      expect(iconImportLine(fs.readFileSync(builtFile, 'utf8'))).toBe(
+        declaredImport,
+      );
+
+      // Rebuilds run through a child re-invocation of `theme build`, so the
+      // flag reaches them only if the watch loop forwards it. Change a token
+      // and wait for the rebuilt CSS. fs.watch delivery is best-effort under
+      // load, so re-touch until the rebuild shows up (idempotent write).
+      const touched =
+        `import {testIcons} from './icons';\n` +
+        `export default {\n` +
+        `  name: "watched",\n` +
+        `  icons: testIcons,\n` +
+        `  tokens: {'--color-bg': '#0a0b0c'},\n` +
+        `};\n`;
+      fs.writeFileSync(themeFile, touched);
+      const rebuilt = await waitFor(() => {
+        try {
+          if (fs.readFileSync(cssFile, 'utf-8').includes('#0a0b0c'))
+            return true;
+        } catch {
+          // CSS mid-write; fall through to re-touch.
+        }
+        try {
+          fs.writeFileSync(themeFile, touched);
+        } catch {
+          // Retried on the next poll.
+        }
+        return false;
+      });
+      expect(rebuilt).toBe(true);
+
+      // The regenerated module still carries the declared specifier — the
+      // forwarding is what this test pins. A watch loop that dropped the flag
+      // would regenerate with the scraped './icons' here and ship the #4620
+      // bytes on every save.
+      expect(iconImportLine(fs.readFileSync(builtFile, 'utf8'))).toBe(
+        declaredImport,
+      );
+    } finally {
+      child.kill('SIGINT');
+    }
+  }, 60_000);
+});

package/foundation/fs/path-safety.mjs

@@ -154,9 +154,9 @@ export function sanitizeName(name, options = {}) {
     );
   }
 
-  if (name === '.' || name === '..' || name.startsWith('..')) {
+  if (name === '.' || name === '..' || name.startsWith('.')) {
     throw new PathSafetyError(
-      `Invalid ${label} "${name}": must not be '.' or start with '..'.`,
+      `Invalid ${label} "${name}": must not start with '.'.`,
       'NAME_TRAVERSAL',
     );
   }

package/foundation/fs/path-safety.test.mjs

@@ -91,6 +91,13 @@ describe('sanitizeName', () => {
     expect(() => sanitizeName('.')).toThrow(PathSafetyError);
   });
 
+  it('rejects dotfile names (.env, .htaccess) that could create hidden files', () => {
+    expect(() => sanitizeName('.env')).toThrow(PathSafetyError);
+    expect(() => sanitizeName('.htaccess')).toThrow(PathSafetyError);
+    expect(() => sanitizeName('.bashrc')).toThrow(PathSafetyError);
+    expect(() => sanitizeName('.gitignore')).toThrow(PathSafetyError);
+  });
+
   it('rejects NUL bytes', () => {
     expect(() => sanitizeName('foo\0bar')).toThrow(PathSafetyError);
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.4.2-canary.791f395",
+  "version": "0.4.2-canary.8b07cb9",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -84,10 +84,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "0.4.2-canary.791f395",
-    "@astryxdesign/core": "0.4.2-canary.791f395",
-    "@astryxdesign/lab": "0.4.2-canary.791f395",
-    "@astryxdesign/theme-neutral": "0.4.2-canary.791f395",
+    "@astryxdesign/charts": "0.4.2-canary.8b07cb9",
+    "@astryxdesign/core": "0.4.2-canary.8b07cb9",
+    "@astryxdesign/lab": "0.4.2-canary.8b07cb9",
+    "@astryxdesign/theme-neutral": "0.4.2-canary.8b07cb9",
     "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
@@ -105,10 +105,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.4.2-canary.791f395",
-    "@astryxdesign/core": "0.4.2-canary.791f395",
-    "@astryxdesign/lab": "0.4.2-canary.791f395",
-    "@astryxdesign/theme-neutral": "0.4.2-canary.791f395",
+    "@astryxdesign/charts": "0.4.2-canary.8b07cb9",
+    "@astryxdesign/core": "0.4.2-canary.8b07cb9",
+    "@astryxdesign/lab": "0.4.2-canary.8b07cb9",
+    "@astryxdesign/theme-neutral": "0.4.2-canary.8b07cb9",
     "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {