@astryxdesign/cli 0.1.4-canary.f00b844 → 0.1.4-canary.f01eb10

package/CHANGELOG.md

@@ -36,7 +36,7 @@ Thanks to everyone who contributed to this release:
 - Strict config + integration v1 schema (integrations, issuesUrl, hooks.postCodemod) and new @astryxdesign/cli/integration export.
 - File-based codemod API (createCodemod/createConfigCodemod) with the @astryxdesign/cli/codemod export and integration codemod discovery in upgrade.
 - component, template, and upgrade now print a one-line non-blocking warning when a configured integration has validation issues, pointing to validate-integration.
-- Add a Kanban Board page template: color-coded status columns, draggable task cards with priority tags, and board toolbar.
+- Add a Kanban Board page template: color-coded status columns, draggable task cards with priority tags, and board toolbar. Based on a design by @cg-hub18.
 - Add frame-first layout guidance: new `astryx docs layout` topic (shell choice, region budgets, app archetypes, cards-vs-rows policy, responsive contracts), layout rules in the generated agent cheat sheet, and layout anti-patterns in `docs principles`.
 - Add a v0.1.3 config codemod that migrates astryx.config layout.components to experimental.xle.components.
 - Add v0.1.0 codemods for migrating `declare module "@xds/core/..."` type augmentations and `.xds-*` / `[data-xds-theme]` / `@layer xds-theme` CSS surfaces to their `@astryxdesign`/`astryx-*` equivalents.
@@ -80,6 +80,7 @@ Thanks to everyone who contributed to this release:
 Thanks to everyone who contributed to this release:
 
 - @AKnassa
+- @cg-hub18
 - @ejhammond
 - @ernestt
 - @harshavardhan194

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.4-canary.f00b844",
+  "version": "0.1.4-canary.f01eb10",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -75,12 +75,16 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/core": "0.1.4-canary.f00b844",
-    "@astryxdesign/lab": "0.1.4-canary.f00b844",
-    "@astryxdesign/theme-neutral": "0.1.4-canary.f00b844",
-    "gpt-tokenizer": "^2.0.0"
+    "@astryxdesign/charts": "0.1.4-canary.f01eb10",
+    "@astryxdesign/core": "0.1.4-canary.f01eb10",
+    "@astryxdesign/lab": "0.1.4-canary.f01eb10",
+    "@astryxdesign/theme-neutral": "0.1.4-canary.f01eb10",
+    "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
+    "@astryxdesign/charts": {
+      "optional": true
+    },
     "@astryxdesign/core": {
       "optional": true
     },
@@ -92,10 +96,11 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/core": "0.1.4-canary.f00b844",
-    "@astryxdesign/lab": "0.1.4-canary.f00b844",
-    "@astryxdesign/theme-neutral": "0.1.4-canary.f00b844",
-    "gpt-tokenizer": "^2.0.0"
+    "@astryxdesign/charts": "0.1.4-canary.f01eb10",
+    "@astryxdesign/core": "0.1.4-canary.f01eb10",
+    "@astryxdesign/lab": "0.1.4-canary.f01eb10",
+    "@astryxdesign/theme-neutral": "0.1.4-canary.f01eb10",
+    "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {
     "astryx": "node bin/astryx.mjs",

package/src/api/doctor.mjs

@@ -115,10 +115,21 @@ function findThemePackages(cwd) {
     return found;
   }
   for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
     if (!entry.name.startsWith('theme-')) continue;
+    const dir = path.join(scopeDir, entry.name);
+    // pnpm installs packages as symlinks into node_modules/.pnpm, and a
+    // symlink dirent reports isDirectory() as false — stat the target instead.
+    let isDir = entry.isDirectory();
+    if (!isDir && entry.isSymbolicLink()) {
+      try {
+        isDir = fs.statSync(dir).isDirectory();
+      } catch {
+        isDir = false;
+      }
+    }
+    if (!isDir) continue;
     const name = `@astryxdesign/${entry.name}`;
-    found.push({name, version: pkgVersion(path.join(scopeDir, entry.name))});
+    found.push({name, version: pkgVersion(dir)});
   }
   return found;
 }

package/src/codemods/__tests__/runner.test.mjs

@@ -99,5 +99,43 @@ describe('runCodemods — unified config codemod path', () => {
     expect(fs.readFileSync(path.join(srcDir, 'a.ts'), 'utf-8')).toContain(
       'const bar = 1',
     );
+    // writtenFiles must be returned (consumed by upgrade.mjs to run the
+    // post-codemod formatting/lint hooks). Regression guard: it was previously
+    // built internally but omitted from the return object, so hooks received an
+    // empty file list and silently skipped, leaving codemod output unformatted.
+    expect(result.writtenFiles).toEqual([path.join(srcDir, 'a.ts')]);
+  });
+
+  it('returns writtenFiles for every changed file (post-codemod hook input)', async () => {
+    const srcDir = path.join(tmpDir, 'src');
+    fs.mkdirSync(srcDir);
+    fs.writeFileSync(path.join(srcDir, 'a.ts'), 'const foo = 1;\n');
+    fs.writeFileSync(path.join(srcDir, 'b.ts'), 'const foo = 2;\n');
+    fs.writeFileSync(path.join(srcDir, 'c.ts'), 'const untouched = 3;\n');
+
+    const versionManifests = [
+      {
+        version: '0.1.3',
+        transforms: [
+          {
+            name: 'synthetic-code-codemod',
+            meta: {title: 'Synthetic code codemod'},
+            transform: file => file.source.replace(/foo/g, 'bar'),
+          },
+        ],
+      },
+    ];
+
+    const result = await runCodemods(versionManifests, {
+      apply: true,
+      path: './src',
+      silent: true,
+    });
+
+    expect(result.totalFilesChanged).toBe(2);
+    // Only the two files that actually changed are reported (not c.ts).
+    expect([...result.writtenFiles].sort()).toEqual(
+      [path.join(srcDir, 'a.ts'), path.join(srcDir, 'b.ts')].sort(),
+    );
   });
 });

package/src/codemods/runner.mjs

@@ -178,6 +178,7 @@ function toUnifiedEntry(transformEntry, version) {
  * @param {string|undefined} options.codemod - Run only this specific transform
  * @param {Set<string>} [options.skipCodemods] - Transform names to exclude
  * @param {boolean} [options.silent] - Suppress all human-facing output (for --json)
+ * @returns {{totalFilesChanged: number, totalTransformsApplied: number, totalValidationBlocked: number, writtenFiles: string[], errors: Array, skippedOptional: Array}}
  */
 export async function runCodemods(
   versionManifests,
@@ -405,6 +406,7 @@ export async function runCodemods(
     totalFilesChanged,
     totalTransformsApplied,
     totalValidationBlocked,
+    writtenFiles,
     errors,
     skippedOptional,
   };

package/src/commands/build-theme.mjs

@@ -175,14 +175,85 @@ async function getKnownValues(componentName) {
   return _knownValuesCache.get(componentName);
 }
 
+/**
+ * Resolve `@astryxdesign/core`'s package root relative to the CLI package. Core
+ * and the CLI ship as siblings (`@astryxdesign/core`, `@astryxdesign/cli`), so
+ * `../../../core` from `src/commands/` reaches core whether installed from npm
+ * or run inside the monorepo. Returns null if it can't be found.
+ */
+function resolveCoreRoot() {
+  const cliDir = path.dirname(fileURLToPath(import.meta.url));
+  const coreRoot = path.resolve(cliDir, '../../../core');
+  return fs.existsSync(coreRoot) ? coreRoot : null;
+}
+
+/**
+ * Read the type declarations `@astryxdesign/core/<Component>` exposes so we can
+ * check whether a given augmentation-target interface actually exists before
+ * generating a module augmentation against it.
+ *
+ * Reads the shipped `dist/<Component>/index.d.ts` (what a consumer's TypeScript
+ * actually sees), falling back to the `src/<Component>/index.ts` in the
+ * monorepo. Returns the file contents, or '' if nothing is found.
+ */
+const _componentDeclCache = new Map();
+function readComponentDeclarations(pascalName) {
+  if (_componentDeclCache.has(pascalName)) {
+    return _componentDeclCache.get(pascalName);
+  }
+  let contents = '';
+  const coreRoot = resolveCoreRoot();
+  if (coreRoot) {
+    const candidates = [
+      path.join(coreRoot, 'dist', pascalName, 'index.d.ts'),
+      path.join(coreRoot, 'src', pascalName, 'index.ts'),
+    ];
+    for (const file of candidates) {
+      try {
+        if (fs.existsSync(file)) {
+          contents = fs.readFileSync(file, 'utf-8');
+          break;
+        }
+      } catch {
+        // ignore and try the next candidate
+      }
+    }
+  }
+  _componentDeclCache.set(pascalName, contents);
+  return contents;
+}
+
+/**
+ * Determine whether `@astryxdesign/core/<Component>` exports an interface named
+ * `interfaceName` that can be augmented via module augmentation.
+ *
+ * Only interfaces are extension points — closed literal-union types (e.g.
+ * `HeadingType`, `ButtonSize`) are NOT augmentable, so a generated augmentation
+ * against them is dead code. We check that the name is exported (directly or
+ * re-exported) as a type/interface.
+ */
+function componentHasAugmentableInterface(pascalName, interfaceName) {
+  const decl = readComponentDeclarations(pascalName);
+  if (!decl) return false;
+  // Word-boundary match so `ButtonVariantMap` doesn't match `XButtonVariantMap`.
+  const re = new RegExp(`\\b${interfaceName}\\b`);
+  return re.test(decl);
+}
+
 /**
  * Generate TypeScript declaration content with module augmentation for custom
  * component prop values found in the theme's `components` keys. Reads known
  * values from doc files to filter out base prop values.
  *
- * Interface naming convention: Astryx + PascalCase(component) + PascalCase(prop) + Map
- *   banner + status → XDSBannerStatusMap
- *   button + variant → XDSButtonVariantMap
+ * Interface naming convention: PascalCase(component) + PascalCase(prop) + Map
+ *   banner + status → BannerStatusMap
+ *   button + variant → ButtonVariantMap
+ *
+ * An augmentation is only emitted when `@astryxdesign/core/<Component>` actually
+ * exports a matching interface. Props backed by closed literal-union types
+ * (e.g. Button `size`, Heading `type`/`level`) have no augmentation point, so
+ * generating a `declare module` block for them would be dead code — those are
+ * skipped.
  *
  * @param {object} themeDef - Theme definition (resolved by defineTheme)
  * @returns {Promise<string|null>} TypeScript declaration content, or null if no augmentations needed
@@ -234,7 +305,14 @@ async function generateVariantDeclarationsAsync(themeDef) {
       const pascal = toPascalCase(component);
       const propPascal = prop.charAt(0).toUpperCase() + prop.slice(1);
       const modulePath = `@astryxdesign/core/${pascal}`;
-      const interfaceName = `XDS${pascal}${propPascal}Map`;
+      const interfaceName = `${pascal}${propPascal}Map`;
+
+      // Only augment interfaces that actually exist as an extension point in
+      // core. Props backed by closed literal-union types (e.g. Button `size`,
+      // Heading `type`/`level`) have no `*Map` interface — a `declare module`
+      // block against a non-existent interface just creates a new, unused
+      // interface and never extends the component's prop union, so skip it.
+      if (!componentHasAugmentableInterface(pascal, interfaceName)) continue;
 
       sections.push(`declare module '${modulePath}' {`);
       sections.push(`  interface ${interfaceName} {`);
@@ -247,6 +325,13 @@ async function generateVariantDeclarationsAsync(themeDef) {
     }
   }
 
+  // If every custom value targeted a non-augmentable prop, there's nothing to
+  // emit beyond the header — return null so no `.variants.d.ts` is written.
+  const hasEmittedAugmentation = sections.some(line =>
+    line.startsWith('declare module'),
+  );
+  if (!hasEmittedAugmentation) return null;
+
   return sections.join('\n');
 }
 
@@ -433,13 +518,21 @@ ${iconReExport}`;
 /**
  * Generate TypeScript declarations for a built theme module.
  */
-function generateBuiltTypes(themeDef, iconInfo) {
+function generateBuiltTypes(themeDef, iconInfo, variantsFileName) {
   const iconType = iconInfo
     ? `import type { IconRegistry } from '@astryxdesign/core/Icon';
 export declare const ${iconInfo.exportName}: IconRegistry;
 `
     : '';
-  return `import type { DefinedTheme } from '@astryxdesign/core/theme';
+  // Pull in the generated custom-variant augmentations so that importing the
+  // theme's types also loads the module augmentations (otherwise the
+  // `.variants.d.ts` is emitted but never referenced, and the custom variants
+  // never widen the component prop unions for consumers).
+  const variantsRef = variantsFileName
+    ? `/// <reference path="./${variantsFileName}" />
+`
+    : '';
+  return `${variantsRef}import type { DefinedTheme } from '@astryxdesign/core/theme';
 ${iconType}export declare const ${toIdentifier(themeDef.name)}Theme: DefinedTheme;
 `;
 }
@@ -894,19 +987,23 @@ export function registerTheme(program) {
 
       const iconInfo = extractIconInfo(filePath);
 
-      // Generate all file contents in memory first.
-      const cssContent = generatedHeader(sourceRelative, 'css', buildCommand) + css;
-      const jsContent = generatedHeader(sourceRelative, 'js', buildCommand) + generateBuiltModule(resolvedTheme || themeDef, iconInfo);
-      const dtsContent = generatedHeader(sourceRelative, 'ts', buildCommand) + generateBuiltTypes(themeDef, iconInfo);
-
-      // Type augmentation .d.ts if theme has custom prop values
+      // Type augmentation .d.ts if theme has custom prop values. Computed
+      // before the main .d.ts so the latter can reference it (see below).
       const augmentationSource = resolvedTheme || themeDef;
       const variantDecl = await generateVariantDeclarationsAsync(augmentationSource);
-      const variantDtsPath = variantDecl ? path.join(outDir, `${baseName}.variants.d.ts`) : null;
+      const variantsFileName = variantDecl ? `${baseName}.variants.d.ts` : null;
+      const variantDtsPath = variantDecl ? path.join(outDir, variantsFileName) : null;
       const variantContent = variantDecl
         ? generatedHeader(sourceRelative, 'ts', buildCommand) + variantDecl
         : null;
 
+      // Generate all file contents in memory first. The main .d.ts references
+      // the variants file (when present) via a triple-slash directive so
+      // importing the theme also loads the custom-variant augmentations.
+      const cssContent = generatedHeader(sourceRelative, 'css', buildCommand) + css;
+      const jsContent = generatedHeader(sourceRelative, 'js', buildCommand) + generateBuiltModule(resolvedTheme || themeDef, iconInfo);
+      const dtsContent = generatedHeader(sourceRelative, 'ts', buildCommand) + generateBuiltTypes(themeDef, iconInfo, variantsFileName);
+
       // Atomic-ish write: stage every file as `<dest>.tmp`, then rename
       // each into place. If any stage step fails we clean up partials and
       // exit; if a rename fails mid-way we still have the originals (or

package/src/commands/build-theme.variants.test.mjs

@@ -0,0 +1,204 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Regression test for the custom-variant type augmentations emitted by
+ * `astryx theme build` (#3391 companion: #3371).
+ *
+ * When a theme declares a custom component prop value (e.g.
+ * `button['variant:accentOutline']`), the build emits a `<name>.variants.d.ts`
+ * with a module augmentation so the custom value type-checks. This suite pins
+ * the two bugs that made that augmentation dead code:
+ *
+ *   1. The augmentation targeted a non-existent, `XDS`-prefixed interface
+ *      (`XDSButtonVariantMap`) instead of core's real `ButtonVariantMap`, so it
+ *      created a new unused interface and never widened the prop union.
+ *   2. Props with no augmentation point (closed literal-union types such as
+ *      Button `size` or Heading `type`/`level`) still got a `declare module`
+ *      block against a `*Map` interface that doesn't exist.
+ *   3. The generated `.variants.d.ts` was never referenced by the main
+ *      `<name>.d.ts`, so even a correct augmentation never loaded.
+ *
+ * Building `astryx theme build` requires a compiled @astryxdesign/core, so this
+ * suite builds core once in beforeAll (mirrors build-theme.prose.test.mjs).
+ */
+
+import {describe, it, expect, beforeAll, beforeEach, afterEach} from 'vitest';
+import {execFileSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {fileURLToPath} from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI_BIN = path.resolve(__dirname, '../../bin/astryx.mjs');
+const REPO_ROOT = path.resolve(__dirname, '../../../..');
+const CORE_THEME_ENTRY = path.join(
+  REPO_ROOT,
+  'packages/core/dist/theme/index.js',
+);
+// The fix reads core's shipped component declarations to decide whether an
+// interface is augmentable; those .d.ts files come from the same core build.
+const CORE_BUTTON_DTS = path.join(
+  REPO_ROOT,
+  'packages/core/dist/Button/index.d.ts',
+);
+
+function runCli(args, cwd) {
+  try {
+    const out = execFileSync('node', [CLI_BIN, ...args], {
+      cwd,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: {...process.env, FORCE_COLOR: '0'},
+    });
+    return {code: 0, stdout: out, stderr: ''};
+  } catch (e) {
+    return {
+      code: e.status ?? 1,
+      stdout: e.stdout?.toString() ?? '',
+      stderr: e.stderr?.toString() ?? '',
+    };
+  }
+}
+
+function writeTheme(dir, contents) {
+  fs.mkdirSync(dir, {recursive: true});
+  const file = path.join(dir, 'variants-theme.mjs');
+  fs.writeFileSync(file, contents);
+  return file;
+}
+
+beforeAll(() => {
+  if (!fs.existsSync(CORE_THEME_ENTRY) || !fs.existsSync(CORE_BUTTON_DTS)) {
+    execFileSync('pnpm', ['-F', '@astryxdesign/core', 'build'], {
+      cwd: REPO_ROOT,
+      stdio: 'pipe',
+      timeout: 180_000,
+    });
+  }
+}, 200_000);
+
+let tmpDir;
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-build-theme-variants-'));
+});
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('theme build custom-variant augmentations', () => {
+  it('targets the real (un-prefixed) core interface for a custom variant', () => {
+    const themeFile = writeTheme(
+      tmpDir,
+      `export default {
+        name: 'variants-theme',
+        tokens: { '--color-bg': '#fff' },
+        components: {
+          button: { 'variant:accentOutline': { backgroundColor: 'transparent' } },
+        },
+      };\n`,
+    );
+
+    const result = runCli(
+      ['theme', 'build', path.relative(tmpDir, themeFile)],
+      tmpDir,
+    );
+    expect(result.code).toBe(0);
+
+    const variantsPath = path.join(tmpDir, 'variants-theme.variants.d.ts');
+    expect(fs.existsSync(variantsPath)).toBe(true);
+    const dts = fs.readFileSync(variantsPath, 'utf-8');
+
+    // Targets core's actual augmentation point…
+    expect(dts).toContain("declare module '@astryxdesign/core/Button'");
+    expect(dts).toMatch(/interface ButtonVariantMap\b/);
+    expect(dts).toContain("'accentOutline': true;");
+    // …and NOT the old, non-existent XDS-prefixed interface.
+    expect(dts).not.toMatch(/XDSButtonVariantMap/);
+  });
+
+  it('skips props with no augmentation point (Button size, Heading type)', () => {
+    const themeFile = writeTheme(
+      tmpDir,
+      `export default {
+        name: 'variants-theme',
+        tokens: { '--color-bg': '#fff' },
+        components: {
+          button: {
+            'variant:accentOutline': { backgroundColor: 'transparent' },
+            'size:jumbo': { paddingBlock: '40px' },
+          },
+          heading: { 'type:hero': { fontSize: '80px' } },
+        },
+      };\n`,
+    );
+
+    const result = runCli(
+      ['theme', 'build', path.relative(tmpDir, themeFile)],
+      tmpDir,
+    );
+    expect(result.code).toBe(0);
+
+    const variantsPath = path.join(tmpDir, 'variants-theme.variants.d.ts');
+    expect(fs.existsSync(variantsPath)).toBe(true);
+    const dts = fs.readFileSync(variantsPath, 'utf-8');
+
+    // The augmentable variant is emitted…
+    expect(dts).toMatch(/interface ButtonVariantMap\b/);
+    // …but closed literal-union props get no dead augmentation.
+    expect(dts).not.toMatch(/ButtonSizeMap/);
+    expect(dts).not.toMatch(/HeadingTypeMap/);
+    expect(dts).not.toContain("declare module '@astryxdesign/core/Heading'");
+  });
+
+  it('does not emit a .variants.d.ts when every custom value is non-augmentable', () => {
+    const themeFile = writeTheme(
+      tmpDir,
+      `export default {
+        name: 'variants-theme',
+        tokens: { '--color-bg': '#fff' },
+        components: {
+          button: { 'size:jumbo': { paddingBlock: '40px' } },
+        },
+      };\n`,
+    );
+
+    const result = runCli(
+      ['theme', 'build', path.relative(tmpDir, themeFile)],
+      tmpDir,
+    );
+    expect(result.code).toBe(0);
+    expect(
+      fs.existsSync(path.join(tmpDir, 'variants-theme.variants.d.ts')),
+    ).toBe(false);
+  });
+
+  it('references the variants file from the main .d.ts so the augmentation loads', () => {
+    const themeFile = writeTheme(
+      tmpDir,
+      `export default {
+        name: 'variants-theme',
+        tokens: { '--color-bg': '#fff' },
+        components: {
+          button: { 'variant:accentOutline': { backgroundColor: 'transparent' } },
+        },
+      };\n`,
+    );
+
+    const result = runCli(
+      ['theme', 'build', path.relative(tmpDir, themeFile)],
+      tmpDir,
+    );
+    expect(result.code).toBe(0);
+
+    const dts = fs.readFileSync(
+      path.join(tmpDir, 'variants-theme.d.ts'),
+      'utf-8',
+    );
+    // A triple-slash reference to the variants file, so importing the theme's
+    // types also loads the module augmentation.
+    expect(dts).toMatch(
+      /\/\/\/\s*<reference path="\.\/variants-theme\.variants\.d\.ts"\s*\/>/,
+    );
+  });
+});

package/src/commands/doctor.test.mjs

@@ -63,6 +63,33 @@ function installPkg(name, version = '1.0.0') {
   return dir;
 }
 
+/**
+ * Mirror pnpm's layout: the real package lives under node_modules/.pnpm and
+ * the entry in the scope directory is a symlink to it.
+ */
+function installPkgPnpmStyle(name, version = '1.0.0') {
+  const realDir = path.join(
+    tmpDir,
+    'node_modules',
+    '.pnpm',
+    `${name.replace('/', '+')}@${version}`,
+    'node_modules',
+    ...name.split('/'),
+  );
+  fs.mkdirSync(realDir, {recursive: true});
+  fs.writeFileSync(
+    path.join(realDir, 'package.json'),
+    JSON.stringify({name, version, main: 'index.js'}),
+  );
+  fs.writeFileSync(path.join(realDir, 'index.js'), 'module.exports = {};');
+  const linkPath = path.join(tmpDir, 'node_modules', ...name.split('/'));
+  fs.mkdirSync(path.dirname(linkPath), {recursive: true});
+  // 'junction' keeps this working on Windows without elevated permissions;
+  // it is ignored on posix.
+  fs.symlinkSync(realDir, linkPath, 'junction');
+  return linkPath;
+}
+
 function find(checks, id) {
   return checks.find(c => c.id === id);
 }
@@ -119,6 +146,13 @@ describe('doctor — individual checks', () => {
     expect(res.status).toBe('pass');
   });
 
+  it('themes: detects pnpm-style symlinked theme packages (#3530)', () => {
+    installPkgPnpmStyle('@astryxdesign/theme-neutral', '0.1.2');
+    const res = checkThemes({cwd: tmpDir, configTheme: 'default'});
+    expect(res.status).toBe('pass');
+    expect(res.message).toContain('@astryxdesign/theme-neutral');
+  });
+
   it('config: INFO when no astryx.config.mjs', async () => {
     const res = await checkConfig({cwd: tmpDir, configPath: null});
     expect(res.status).toBe('info');

package/templates/blocks/components/BaseTypeahead/BaseTypeaheadCustomSearch.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'BaseTypeahead',
+  name: 'BaseTypeahead — Custom Search Bar',
+  displayName: 'BaseTypeahead — Custom Search Bar',
+  description:
+    'BaseTypeahead embedded inside a custom-styled wrapper. The wrapper provides its own border and icon chrome; anchorRef positions the dropdown relative to it. Use this pattern when Typeahead\'s built-in field layout does not fit your composition.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['BaseTypeahead', 'Icon', 'Layout', 'Text'],
+};

package/templates/blocks/components/BaseTypeahead/BaseTypeaheadCustomSearch.tsx

@@ -0,0 +1,58 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useRef, useState} from 'react';
+import {BaseTypeahead, createStaticSource} from '@astryxdesign/core/Typeahead';
+import type {SearchableItem} from '@astryxdesign/core/Typeahead';
+import {Icon} from '@astryxdesign/core/Icon';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+import {MagnifyingGlassIcon} from '@heroicons/react/24/outline';
+
+const frameworks: SearchableItem[] = [
+  {id: 'react', label: 'React'},
+  {id: 'vue', label: 'Vue'},
+  {id: 'angular', label: 'Angular'},
+  {id: 'svelte', label: 'Svelte'},
+  {id: 'solid', label: 'SolidJS'},
+  {id: 'remix', label: 'Remix'},
+  {id: 'next', label: 'Next.js'},
+  {id: 'nuxt', label: 'Nuxt'},
+];
+
+const source = createStaticSource(frameworks);
+
+export default function BaseTypeaheadCustomSearch() {
+  const [value, setValue] = useState<SearchableItem | null>(null);
+  const wrapperRef = useRef<HTMLElement>(null);
+
+  return (
+    <VStack gap={3} style={{width: 320}}>
+      <HStack
+        ref={wrapperRef}
+        gap={2}
+        vAlign="center"
+        style={{
+          border: '1px solid var(--color-border)',
+          borderRadius: 'var(--radius-control)',
+          padding: '6px 10px',
+          background: 'var(--color-surface)',
+        }}>
+        <Icon icon={MagnifyingGlassIcon} size="sm" color="secondary" />
+        <BaseTypeahead
+          searchSource={source}
+          value={value}
+          onChange={setValue}
+          anchorRef={wrapperRef}
+          placeholder="Search frameworks…"
+          hasEntriesOnFocus
+          debounceMs={0}
+        />
+      </HStack>
+      <Text type="supporting" color="secondary">
+        {value != null ? `Selected: ${value.label}` : 'No selection'}
+      </Text>
+    </VStack>
+  );
+}

package/templates/blocks/components/CodeBlock/CodeBlockTerminal.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'CodeBlock',
+  name: 'Code — Terminal',
+  displayName: 'Code — Terminal',
+  description:
+    'A dark terminal-style command block: a bash CodeBlock wrapped in SyntaxTheme with the GitHub Dark preset, copy button on, and no line numbers. Use for shell sessions or CLI output that should read as a terminal even on light pages. Reach for a dark syntax preset instead of hand-rolling a dark box with custom CSS.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['CodeBlock', 'SyntaxTheme'],
+};