@astryxdesign/cli 0.1.1 → 0.1.2-canary.2581eb4

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # @xds/cli
 
+# 0.1.2
+
+#### Breaking Changes
+
+- `Text`, `Heading`, `Link`, and `Timestamp` rename the `color="active"` value to `color="accent"`, now mapping to the dedicated `--color-text-accent` token (legible accent text ink) instead of `--color-accent`. Run `astryx upgrade` to migrate call sites automatically. (#2863)
+
+#### New Features
+
+- Let `astryx.config.mjs` integrations contribute package docs, gap-report hooks, template fetching hooks, upgrade codemods, and post-codemod hooks.
+- Add `astryx theme add <slug> [path]` (and `astryx theme list`) to scaffold a theme's source into your project as editable files you own, with theme sources bundled into the CLI
+
+#### Fixes
+
+- align `astryx init` theme instructions with the runtime built-theme recommendation (#3080)
+  `astryx init` now points users at the pre-built theme path (`@astryxdesign/theme-neutral/built` + `theme.css`) and the base CSS imports, matching the runtime `<Theme>` console guidance, instead of the slower runtime style-injection import that left apps unstyled.
+- `astryx theme build` now derives every output file (.css/.js/.d.ts) from the theme name so they share one naming scheme, shows import paths as bare `./<name>` specifiers (instead of a cwd-rooted `./src/...` path that was wrong when your file already lives under src/), and no longer warns about the `variant` prop on `card`
+
+#### Documentation
+
+- Rename the ClickableCard and SelectableCard examples to follow the "Component — Variant" title convention (`Clickable Card — Nested Button`, `Selectable Card — Multi-select`), and add playground defaults to both card docs so their docsite previews show realistic card content (#2877)
+- Declare playground scaffolds for the Chat sub-components so they preview at a realistic width (ChatComposer and ChatComposerDrawer wrap in a sized container, and the drawer seeds default content), and drop the redundant visible value label from the ChatComposerDrawer "With Progress" example while keeping the accessible label (#2877)
+- Rename the DateInput "Date Range" example to "Min/Max Constraints" — it demos a single input constrained to a min/max window, not a date-range picker (#2692)
+- Wire local state into more showcase examples that were frozen (static value + no-op onChange): TextInput, TextArea, NumberInput, SegmentedControl, RadioList, Tab, TabList, and TabMenu. Follows the same fix as the Slider/Selector/MultiSelector showcases so the docsite previews are actually interactive
+- Wire local state into the Typeahead, Tokenizer, and FileInput showcase examples (static value + no-op onChange → frozen previews). Completes the interactive-showcase fixes started for Slider/Selector/MultiSelector (#3187-#3189) and the input/tab batch
+- Wire local state into the Slider, Selector, and MultiSelector showcase examples so they are interactive — they were controlled components with a static value and a no-op/missing onChange, so the docsite previews appeared frozen (#3187, #3188, #3189)
+- Add a LinkProvider example block showing how to swap in a framework router link (e.g. Next.js Link) for client-side routing (#2733)
+- Add a showcase block for Outline so its docs page has a hero preview, alongside the existing example blocks (#2871)
+- Remove the "MoreMenu — In Toolbar" example block — it rendered incorrectly and was redundant with the other MoreMenu examples (#2870)
+- Add rendered example blocks for the two column-axis Table plugin hooks,
+  shown on their own subcomponent pages:
+- Move the "ToggleButton — Group" example to the ToggleButtonGroup page, where it belongs (it demonstrates grouped toggle behavior) (#2842)
+- Make the Toolbar "Table Filter" example use real Selector controls for its Status and Priority filters instead of buttons styled to look like dropdowns, and add meaningful playground defaults plus richer slot options (buttons, icon buttons, tabs, segmented controls, selectors) to the Toolbar docs (#2877).
+
+#### Other Changes
+
+- `useTableStickyColumns — Pinned Columns` (on /components/useTableStickyColumns)
+- `useTableColumnResize — Draggable Columns` (on /components/useTableColumnResize)
+
+#### Contributors
+
+Thanks to everyone who contributed to this release:
+
+- @cixzhang
+- @durvesh1992
+- @ejhammond
+- @humbertovirtudes
+- @rubyycheung
+
+---
+
 # 0.1.1
 
 #### New Features

package/docs/theme.doc.mjs

@@ -53,7 +53,7 @@ function App() {
         },
         {
           type: 'prose',
-          text: 'Each theme ships as its own npm package. Install the one you want, then wrap your app in `<Theme>` — the same pattern works for every theme; just swap the package and import name.',
+          text: 'Each theme ships as its own npm package. Install the one you want, then wrap your app in `<Theme>`. The same pattern works for every theme; just swap the package and import name.',
         },
         {
           type: 'prose',
@@ -261,7 +261,7 @@ const brandTheme = defineTheme({
       content: [
         {
           type: 'prose',
-          text: 'The `components` field in defineTheme uses semantic component keys and style keys — not raw CSS selectors. Use `base` for all instances, `variant:value` or `stateName` for specific props/states, and let the theme pipeline choose the underlying selector. For raw external CSS escape hatches, prefer the data-attribute selector surface documented in `astryx docs styling`.',
+          text: 'The `components` field in defineTheme uses semantic component keys and style keys, not raw CSS selectors. Use `base` for all instances, `variant:value` or `stateName` for specific props/states, and let the theme pipeline choose the underlying selector. For raw external CSS escape hatches, prefer the data-attribute selector surface documented in `astryx docs styling`.',
         },
         {
           type: 'code',

package/docs/working-with-ai.doc.mjs

@@ -34,11 +34,11 @@ export const docs = {
           type: 'code',
           lang: 'text',
           label: 'Paste this into your AI',
-          code: 'Install @astryxdesign/cli and run `npx astryx agent-docs` to set up your Astryx context. Read the generated file.',
+          code: 'Install @astryxdesign/cli and run `npx astryx init --features agents` to set up your Astryx context. Read the generated file.',
         },
         {
           type: 'prose',
-          text: 'That\'s it. The agent-docs command generates everything your AI needs (component index, behavioral rules, CLI reference) pulled from your installed version. After a version bump, run it again to update in place.',
+          text: 'That\'s it. The `init --features agents` command generates everything your AI needs (component index, behavioral rules, CLI reference) pulled from your installed version. After a version bump, run it again to update in place.',
         },
         {
           type: 'prose',
@@ -48,9 +48,9 @@ export const docs = {
           type: 'code',
           lang: 'bash',
           label: 'Manual options',
-          code: `npx astryx agent-docs --agent claude    # CLAUDE.md
-npx astryx agent-docs --agent cursor    # .cursorrules
-npx astryx agent-docs --agent codex     # AGENTS.md (Copilot, Codex, etc.)`,
+          code: `npx astryx init --features agents --agent claude    # CLAUDE.md
+npx astryx init --features agents --agent cursor    # .cursorrules
+npx astryx init --features agents --agent codex     # AGENTS.md (Copilot, Codex, etc.)`,
         },
       ],
     },
@@ -88,7 +88,7 @@ npx astryx agent-docs --agent codex     # AGENTS.md (Copilot, Codex, etc.)`,
           lang: 'bash',
           label: 'Install as a Cursor user rule',
           code: `mkdir -p ~/.cursor/rules
-npx astryx agent-docs --agent-docs-path ~/.cursor/rules/xds.mdc`,
+npx astryx init --features agents --agent-docs-path ~/.cursor/rules/xds.mdc`,
         },
       ],
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.1",
+  "version": "0.1.2-canary.2581eb4",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -38,6 +38,14 @@
     "./api": {
       "types": "./src/types/api.d.ts",
       "import": "./src/api/index.mjs"
+    },
+    "./config": {
+      "types": "./src/types/config.d.ts",
+      "import": "./src/config.mjs"
+    },
+    "./xle": {
+      "types": "./src/lib/xle/browser.d.ts",
+      "import": "./src/lib/xle/browser.mjs"
     }
   },
   "files": [
@@ -51,12 +59,14 @@
     "@clack/prompts": "^1.5.1",
     "commander": "^12.1.0",
     "jiti": "^2.7.0",
-    "jscodeshift": "^17.3.0"
+    "jscodeshift": "^17.3.0",
+    "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/core": "*",
-    "@astryxdesign/lab": "*",
-    "@astryxdesign/theme-neutral": "*"
+    "@astryxdesign/core": "0.1.2-canary.2581eb4",
+    "@astryxdesign/lab": "0.1.2-canary.2581eb4",
+    "@astryxdesign/theme-neutral": "0.1.2-canary.2581eb4",
+    "gpt-tokenizer": "^2.0.0"
   },
   "peerDependenciesMeta": {
     "@astryxdesign/core": {
@@ -70,9 +80,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/core": "*",
-    "@astryxdesign/lab": "*",
-    "@astryxdesign/theme-neutral": "*"
+    "@astryxdesign/core": "0.1.2-canary.2581eb4",
+    "@astryxdesign/lab": "0.1.2-canary.2581eb4",
+    "@astryxdesign/theme-neutral": "0.1.2-canary.2581eb4",
+    "gpt-tokenizer": "^2.0.0"
   },
   "scripts": {
     "astryx": "node bin/astryx.mjs",

package/src/api/discover.mjs

@@ -5,19 +5,28 @@
  */
 
 import {loadConfig} from '../lib/config.mjs';
-import {scanAllPackages, findComponentInPackages} from '../lib/package-scanner.mjs';
+import {
+  scanAllPackages,
+  findComponentInPackages,
+} from '../lib/package-scanner.mjs';
 import {loadDocs} from '../lib/component-loader.mjs';
 import {levenshteinDistance} from '../lib/string-utils.mjs';
 import {AstryxError} from './error.mjs';
 import {ERROR_CODES} from '../lib/error-codes.mjs';
 
 function validateDocs(docs) {
-  if (!docs || typeof docs !== 'object') return 'docs export is missing or not an object';
-  if (typeof docs.name !== 'string' || !docs.name) return 'docs.name is missing or not a string';
-  if (!docs.usage || typeof docs.usage.description !== 'string') return 'docs.usage.description is missing or not a string';
-  if (docs.props && !Array.isArray(docs.props)) return 'docs.props must be an array';
-  if (docs.components && !Array.isArray(docs.components)) return 'docs.components must be an array';
-  if (docs.usage?.bestPractices && !Array.isArray(docs.usage.bestPractices)) return 'docs.usage.bestPractices must be an array';
+  if (!docs || typeof docs !== 'object')
+    return 'docs export is missing or not an object';
+  if (typeof docs.name !== 'string' || !docs.name)
+    return 'docs.name is missing or not a string';
+  if (!docs.usage || typeof docs.usage.description !== 'string')
+    return 'docs.usage.description is missing or not a string';
+  if (docs.props && !Array.isArray(docs.props))
+    return 'docs.props must be an array';
+  if (docs.components && !Array.isArray(docs.components))
+    return 'docs.components must be an array';
+  if (docs.usage?.bestPractices && !Array.isArray(docs.usage.bestPractices))
+    return 'docs.usage.bestPractices must be an array';
   return null;
 }
 
@@ -32,7 +41,7 @@ function validateDocs(docs) {
 export async function discover(query, options = {}) {
   const {lang = null, zh = false} = options;
   const config = await loadConfig();
-  const toEntry = (pkg) => ({
+  const toEntry = pkg => ({
     name: pkg.name,
     category: pkg.category,
     components: pkg.components,
@@ -41,11 +50,14 @@ export async function discover(query, options = {}) {
     displayName: pkg.displayName,
   });
 
-  if (config.packages.length === 0) {
+  const explicitPackages = (config.loadedIntegrations ?? [])
+    .map(integration => integration.package)
+    .filter(Boolean);
+  if (config.packages.length === 0 && explicitPackages.length === 0) {
     return {type: 'discover.list', data: [], meta: {configured: false}};
   }
 
-  const packages = scanAllPackages(config.packages);
+  const packages = scanAllPackages(config.packages, explicitPackages);
 
   if (packages.length === 0) {
     return {type: 'discover.list', data: [], meta: {configured: true}};
@@ -61,7 +73,10 @@ export async function discover(query, options = {}) {
     if (slashIdx > 0) {
       const pkgName = query.slice(0, slashIdx);
       const compName = query.slice(slashIdx + 1);
-      return await resolveComponentDocs(packages, compName, pkgName, {lang, zh});
+      return await resolveComponentDocs(packages, compName, pkgName, {
+        lang,
+        zh,
+      });
     }
 
     const pkg = packages.find(p => p.name === query);
@@ -99,7 +114,16 @@ export async function discover(query, options = {}) {
   }
 
   if (substringMatches.length > 1) {
-    return {type: 'discover.search', data: {query, matches: substringMatches.map(m => ({package: m.pkg.name, component: m.comp}))}};
+    return {
+      type: 'discover.search',
+      data: {
+        query,
+        matches: substringMatches.map(m => ({
+          package: m.pkg.name,
+          component: m.comp,
+        })),
+      },
+    };
   }
 
   // Fuzzy fallback
@@ -110,7 +134,10 @@ export async function discover(query, options = {}) {
     }
   }
   const fuzzyMatches = allComponents
-    .map(item => ({...item, distance: levenshteinDistance(lower, item.comp.toLowerCase())}))
+    .map(item => ({
+      ...item,
+      distance: levenshteinDistance(lower, item.comp.toLowerCase()),
+    }))
     .filter(m => m.distance <= 3)
     .sort((a, b) => a.distance - b.distance)
     .slice(0, 5);
@@ -118,30 +145,46 @@ export async function discover(query, options = {}) {
   if (fuzzyMatches.length > 0) {
     throw new AstryxError(
       `"${query}" not found`,
-      fuzzyMatches.map(m => ({name: m.pkg.name + '/' + m.comp, reason: 'similar name'})),
+      fuzzyMatches.map(m => ({
+        name: m.pkg.name + '/' + m.comp,
+        reason: 'similar name',
+      })),
       ERROR_CODES.ERR_NOT_FOUND,
     );
   }
 
-  throw new AstryxError(`"${query}" not found in any package`, undefined, ERROR_CODES.ERR_NOT_FOUND);
+  throw new AstryxError(
+    `"${query}" not found in any package`,
+    undefined,
+    ERROR_CODES.ERR_NOT_FOUND,
+  );
 }
 
 async function resolveComponentDocs(packages, compName, pkgName, {lang, zh}) {
   const pkg = packages.find(p => p.name === pkgName);
-  if (!pkg) throw new AstryxError(`Package "${pkgName}" not found`, undefined, ERROR_CODES.ERR_UNKNOWN_PACKAGE);
+  if (!pkg)
+    throw new AstryxError(
+      `Package "${pkgName}" not found`,
+      undefined,
+      ERROR_CODES.ERR_UNKNOWN_PACKAGE,
+    );
 
   const result = findComponentInPackages([pkg], compName);
   if (!result) {
     const lower = compName.toLowerCase();
     const hits = pkg.components.filter(c => c.toLowerCase().includes(lower));
-    const suggestions = hits.length > 0
-      ? hits
-      : pkg.components
-        .map(c => ({name: c, distance: levenshteinDistance(lower, c.toLowerCase())}))
-        .filter(m => m.distance <= 3)
-        .sort((a, b) => a.distance - b.distance)
-        .slice(0, 5)
-        .map(m => m.name);
+    const suggestions =
+      hits.length > 0
+        ? hits
+        : pkg.components
+            .map(c => ({
+              name: c,
+              distance: levenshteinDistance(lower, c.toLowerCase()),
+            }))
+            .filter(m => m.distance <= 3)
+            .sort((a, b) => a.distance - b.distance)
+            .slice(0, 5)
+            .map(m => m.name);
     throw new AstryxError(
       `Component "${compName}" not found in ${pkgName}`,
       suggestions.map(s => ({name: s, reason: 'similar name'})),
@@ -157,9 +200,18 @@ async function loadAndValidate(result, {lang, zh}) {
   try {
     docs = await loadDocs(result.docPath, {zh, lang});
   } catch (e) {
-    throw new AstryxError(`Failed to load docs for ${result.componentName}: ${e.message}`, undefined, ERROR_CODES.ERR_INVALID_DOC);
+    throw new AstryxError(
+      `Failed to load docs for ${result.componentName}: ${e.message}`,
+      undefined,
+      ERROR_CODES.ERR_INVALID_DOC,
+    );
   }
   const err = validateDocs(docs);
-  if (err) throw new AstryxError(`Invalid docs for ${result.componentName}: ${err}`, undefined, ERROR_CODES.ERR_INVALID_DOC);
+  if (err)
+    throw new AstryxError(
+      `Invalid docs for ${result.componentName}: ${err}`,
+      undefined,
+      ERROR_CODES.ERR_INVALID_DOC,
+    );
   return {type: 'discover.detail.doc', data: docs};
 }

package/src/api/index.mjs

@@ -23,6 +23,7 @@ export {component} from './component.mjs';
 export {docs} from './docs.mjs';
 export {discover} from './discover.mjs';
 export {template} from './template.mjs';
+export {themeAdd, listThemes} from './theme-add.mjs';
 export {hook} from './hook.mjs';
 export {search} from './search.mjs';
 export {doctor} from './doctor.mjs';

package/src/api/layout.mjs

@@ -0,0 +1,301 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Programmatic API for the layout command (XLE/XLO).
+ *
+ * `astryx layout` turns token-compressed layout expressions into validated
+ * XDS TSX. Two input surfaces — compact (Emmet-derived XLE) and outline
+ * (indentation-based XLO) — share one AST, one validator, and one
+ * expander. See the research: pastes P2376666892 (spec) and P2376717669
+ * (outline surface).
+ *
+ * @input  expression string (+ options)
+ * @output {type, data} envelopes: layout.expand / layout.check / layout.grammar
+ * @position api — pure orchestration over lib/xle; command wrapper in commands/layout.mjs
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {AstryxError} from './error.mjs';
+import {ERROR_CODES} from '../lib/error-codes.mjs';
+import {assertWithin, isFilePathArg, PathSafetyError} from '../utils/path-safety.mjs';
+import {parse, detectForm, XLEParseError} from '../lib/xle/parse.mjs';
+import {validate} from '../lib/xle/validate.mjs';
+import {expand} from '../lib/xle/expand.mjs';
+import {toCompact, toOutline} from '../lib/xle/print.mjs';
+import {buildRegistry, ALIAS_TABLE} from '../lib/xle/registry.mjs';
+import {discoverTemplates, stripTemplateAssetRefs} from './template.mjs';
+import {loadConfig} from '../lib/config.mjs';
+
+/**
+ * The catalog a `{hint}` can resolve to: template blocks (spliced inline) plus
+ * any app-registered local components from astryx.config.mjs `layout.components`
+ * (imported by name). App components are how XLE reaches domain pieces — the
+ * KpiCard/chart/drawer set that the @astryxdesign/core registry can't see.
+ */
+async function loadBlocks(cwd) {
+  const blocks = [];
+  try {
+    const all = await discoverTemplates(cwd);
+    for (const t of all) if (t.type === 'block') blocks.push({...t, kind: 'template'});
+  } catch {
+    // discovery is best-effort
+  }
+  try {
+    const config = await loadConfig(cwd);
+    const components = config.layout?.components || {};
+    for (const [name, spec] of Object.entries(components)) {
+      const importPath = typeof spec === 'string' ? spec : spec.from;
+      if (!importPath) continue;
+      blocks.push({
+        type: 'block',
+        kind: 'component',
+        dirName: name,
+        name,
+        description: typeof spec === 'object' ? spec.description || '' : '',
+        category: 'app',
+        importPath,
+        isDefault: typeof spec === 'object' ? Boolean(spec.default) : false,
+      });
+    }
+  } catch {
+    // config is optional
+  }
+  return blocks;
+}
+
+const normKey = (name) => name.toLowerCase().replace(/[^a-z0-9]/g, '');
+
+/** Collect the block names referenced by {hints} anywhere in the doc. */
+function collectHintNames(doc) {
+  const names = new Set();
+  const visitNode = (node) => {
+    if (!node || node.kind === 'group') {
+      (node?.children || []).forEach(visit);
+      return;
+    }
+    if (node.hint?.block) names.add(node.hint.block.name);
+    for (const slot of node.slots || []) {
+      if (slot.value?.hint?.block) names.add(slot.value.hint.block.name);
+      (slot.value?.subexpr || []).forEach(visit);
+    }
+    (node.children || []).forEach(visit);
+  };
+  const visit = (item) => (item?.kind === 'group' ? item.children.forEach(visit) : visitNode(item));
+  doc.roots.forEach(visit);
+  doc.overlays.forEach(visit);
+  return names;
+}
+
+/**
+ * Build the blockModules map expand() needs: import-mode for app components,
+ * splice-mode (reading + asset-stripping the block source) for template blocks.
+ * Only blocks actually referenced are read.
+ */
+function buildBlockModules(doc, blocks) {
+  const referenced = collectHintNames(doc);
+  if (referenced.size === 0) return new Map();
+  const byKey = new Map(blocks.map(b => [normKey(b.dirName), b]));
+  const modules = new Map();
+  for (const name of referenced) {
+    const block = byKey.get(normKey(name));
+    if (!block) continue;
+    if (block.kind === 'component') {
+      modules.set(name, {mode: 'import', componentName: block.name, importPath: block.importPath, isDefault: block.isDefault});
+    } else if (block.filePath && fs.existsSync(block.filePath)) {
+      modules.set(name, {mode: 'splice', componentName: block.dirName, source: stripTemplateAssetRefs(fs.readFileSync(block.filePath, 'utf-8'))});
+    }
+  }
+  return modules;
+}
+
+function formatIssue(issue) {
+  const where = issue.line != null ? `line ${issue.line}: ` : '';
+  return `${where}${issue.message}`;
+}
+
+/**
+ * Parse + validate, throwing structured XDSErrors on failure.
+ * Returns {doc, registry, blocks, warnings}.
+ */
+async function analyze(expression, {form = 'auto', loose = false, cwd = process.cwd()} = {}) {
+  const registry = await buildRegistry({cwd});
+  const blocks = await loadBlocks(cwd);
+
+  let doc;
+  try {
+    doc = parse(expression, {form});
+  } catch (e) {
+    if (e instanceof XLEParseError) {
+      throw new AstryxError(
+        `Layout expression syntax error at line ${e.line}, col ${e.col}: ${e.message}`,
+        undefined,
+        ERROR_CODES.ERR_LAYOUT_PARSE,
+      );
+    }
+    throw e;
+  }
+
+  const {errors, warnings} = validate(doc, registry, blocks, {loose});
+  return {doc, registry, blocks, errors, warnings};
+}
+
+/**
+ * `astryx layout expand "<expr>" [path]`
+ *
+ * @param {string} expression
+ * @param {object} [options]
+ * @param {string} [options.targetPath] - write TSX here (validated against cwd)
+ * @param {'compact'|'outline'|'auto'} [options.form]
+ * @param {boolean} [options.loose] - downgrade unknown {hints} to TODO warnings
+ * @param {string} [options.name] - generated component name
+ * @param {string} [options.cwd]
+ */
+export async function layoutExpand(expression, options = {}) {
+  const {targetPath, form = 'auto', loose = false, name, cwd = process.cwd()} = options;
+  const {doc, registry, blocks, errors, warnings} = await analyze(expression, {form, loose, cwd});
+
+  if (errors.length > 0) {
+    throw new AstryxError(
+      `Layout expression is invalid:\n` + errors.map(e => `  - ${formatIssue(e)}`).join('\n'),
+      errors.flatMap(e => (e.suggestions || []).map(s => ({name: s, reason: 'did you mean this?'}))),
+      ERROR_CODES.ERR_LAYOUT_INVALID,
+    );
+  }
+
+  const componentName = name || 'GeneratedLayout';
+  if (!/^[A-Z][A-Za-z0-9]*$/.test(componentName)) {
+    throw new AstryxError(
+      `--name must be a PascalCase component name, got '${componentName}'`,
+      undefined,
+      ERROR_CODES.ERR_INVALID_ARGUMENT,
+    );
+  }
+  const blockModules = buildBlockModules(doc, blocks);
+  const result = expand(doc, registry, {componentName, blockModules});
+
+  let written = null;
+  if (targetPath) {
+    let resolved;
+    try {
+      resolved = assertWithin(targetPath, cwd, {label: 'layout target path'});
+    } catch (err) {
+      if (err instanceof PathSafetyError) {
+        throw new AstryxError(err.message, undefined, ERROR_CODES.ERR_PATH_TRAVERSAL);
+      }
+      throw err;
+    }
+    const filePath = isFilePathArg(targetPath)
+      ? resolved
+      : path.join(resolved, `${componentName}.tsx`);
+    fs.mkdirSync(path.dirname(filePath), {recursive: true});
+    fs.writeFileSync(filePath, result.code);
+    written = path.relative(cwd, filePath);
+  }
+
+  return {
+    type: 'layout.expand',
+    data: {
+      form: form === 'auto' ? detectForm(expression) : form,
+      code: result.code,
+      componentsUsed: result.componentsUsed,
+      states: result.states,
+      todos: result.todos,
+      blocksReferenced: [...blockModules.entries()].map(([name, m]) => ({name, mode: m.mode})),
+      warnings: warnings.map(formatIssue),
+      written,
+    },
+  };
+}
+
+/**
+ * `astryx layout check "<expr>" [--form compact|outline]`
+ * Validates without expanding; echoes both canonical surfaces.
+ */
+export async function layoutCheck(expression, options = {}) {
+  const {form = 'auto', loose = false, cwd = process.cwd()} = options;
+  const {doc, errors, warnings} = await analyze(expression, {form, loose, cwd});
+
+  return {
+    type: 'layout.check',
+    data: {
+      valid: errors.length === 0,
+      form: doc.form,
+      errors: errors.map(e => ({...e, formatted: formatIssue(e)})),
+      warnings: warnings.map(formatIssue),
+      compact: toCompact(doc),
+      outline: toOutline(doc),
+    },
+  };
+}
+
+/**
+ * `astryx layout grammar` — the agent cheatsheet, with the alias table
+ * generated from this branch's registry (never hand-maintained).
+ */
+export async function layoutGrammar(options = {}) {
+  const {cwd = process.cwd()} = options;
+  const registry = await buildRegistry({cwd});
+
+  const aliasLines = [];
+  const byTarget = new Map();
+  for (const [alias, target] of registry.aliases) {
+    if (!byTarget.has(target)) byTarget.set(target, []);
+    byTarget.get(target).push(alias);
+  }
+  for (const [target, aliases] of [...byTarget.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    aliasLines.push(`${aliases.join('/')}=${target}`);
+  }
+
+  const text = `XLE/XLO — XDS layout expressions (branch-generated; aliases reflect this install)
+
+WORKFLOW
+  astryx layout check "<expr>"           validate; echoes canonical compact + outline forms
+  astryx layout expand "<expr>" [path]   emit validated TSX (path optional; --name <Pascal>)
+  Errors carry line/col + suggestions. Fix and resubmit; nothing is guessed.
+
+TWO SURFACES, ONE LANGUAGE (autodetected; --form to force)
+  compact: A[cp6 @topNav=TN] > L > LC > S[p6] > (C{card-callout}*4) + T
+  outline: indentation = nesting · same-indent = siblings · "repeat N:" block = (...)*N
+           slot lines:  topNav: TN     (or a block:  topNav:\\n    TN ...)
+
+NODE ANATOMY   Name#id.enum"payload"[attrs]{hint}*N > children
+  .enum        unique enum value of any prop:  Bd.success  Tx.lg  B.primary
+  "payload"    primary text prop (label/title/heading) or text child:  TI"Email"  B"Save"
+  {hint}       kebab-case template/component reference (see TEMPLATE REFERENCING) — NEVER text
+  *N / xN      repeat (use $ for the counter:  Tk"item-$"*3)
+  trailing !   initial selection for scaffolded state:  Tab"Overview"!
+
+ATTRS [...] (outline: bare tokens after the name, no brackets)
+  fused        p6 g4 c4 w240 h2 cp2 mw960 rg2 cg2  (per-component: padding lives on Card/Section/AppShell.cp — p6 on AppShell/Layout/VStack errors with a correction)
+  key=value    t=email href='/x' c{min:340} dv=[top,bottom] — keys validated per component
+  flags        req opt dis striped hover divider … (isX/hasX props) · negate: !scroll
+  align        j= main axis, a= cross axis — expander picks hAlign/vAlign per stack direction
+  slots        @slotName=Node | @slotName=(sub > expr) | @slotName='text' | @slotName=#id
+  trigger      opens=#id  (a plain attr, no @ — binds an onClick that opens the overlay)
+  fill         on a stack child → wraps in <StackItem size="fill">
+
+TEMPLATE REFERENCING  ({hint} pulls in real content — this is how XLE reaches past the @astryxdesign/core shell)
+  C{card-callout}              splice a template block (astryx template --list --type block):
+                              the block is co-defined once in the file, referenced, imports merged
+  {kpi-card}                   standalone reference (no wrapper element) — place a component directly
+  {kpi-card}*4                 repeat a reference; the definition/import is emitted once
+  app components               register local ones in astryx.config.mjs to import them by name:
+                                 export default {layout: {components: {KpiCard: '@/components/KpiCard'}}}
+                               then {kpi-card} → import {KpiCard} + <KpiCard /> (kebab ↔ Pascal)
+
+STRUCTURE THE EXPANDER HANDLES
+  Layout > LH + LC + LF + LP   children auto-route into header/content/footer/start slots
+  T > (TR>THC*4) + (TR>TC*4)*6 rows partition into TableHeader/TableBody automatically
+  TabList/inputs               required value+onChange scaffold typed useState automatically
+  overlays                     compact: tree ;; Dlg#confirm[...] · outline: overlays: section
+                               trigger: B"Delete"[opens=#confirm]
+
+ALIASES (full component names always valid; XDS prefix optional)
+  ${aliasLines.join('  ')}
+`;
+
+  return {type: 'layout.grammar', data: {text, aliases: Object.fromEntries(registry.aliases)}};
+}
+
+export {ALIAS_TABLE};