@astryxdesign/cli 0.6.4-canary.ed2e54e → 0.6.4

package/api/layout/expand/expand.mjs

@@ -0,0 +1,155 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx layout expand` leaf — expand a validated layout expression into
+ * XDS TSX (optionally written to disk). Resolution + validation come from
+ * ../_adapter.mjs (analyze); this leaf owns block-module assembly, code
+ * generation, and the path-safe write, and projects the `layout.expand` envelope.
+ *
+ * @input  expression string (+ options)
+ * @output {type:'layout.expand', data}
+ * @position api — leaf over ../_adapter.mjs + lib/xle/expand
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {AstryxError} from '../../error.mjs';
+import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
+import {assertWithin, isFilePathArg, PathSafetyError} from '../../../foundation/fs/path-safety.mjs';
+import {detectForm} from '../../../foundation/xle/parse.mjs';
+import {expand} from '../../../foundation/xle/expand.mjs';
+import {stripTemplateAssetRefs} from '../../template/template.mjs';
+import {analyze, formatIssue} from '../_adapter.mjs';
+
+/** @param {string} name */
+const normKey = (name) => name.toLowerCase().replace(/[^a-z0-9]/g, '');
+
+/**
+ * Collect the block names referenced by {hints} anywhere in the doc.
+ * @param {import('../../../foundation/xle/xle-ast').XLEDoc} doc
+ */
+function collectHintNames(doc) {
+  /** @type {Set<string>} */
+  const names = new Set();
+  /** @param {import('../../../foundation/xle/xle-ast').XLEItem} node */
+  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 || []) {
+      const value = slot.value;
+      if (value && typeof value === 'object' && 'hint' in value && value.hint?.block) {
+        names.add(value.hint.block.name);
+      }
+      if (value && typeof value === 'object' && 'subexpr' in value) {
+        (value.subexpr || []).forEach(visit);
+      }
+    }
+    (node.children || []).forEach(visit);
+  };
+  /** @param {import('../../../foundation/xle/xle-ast').XLEItem} item */
+  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.
+ *
+ * @param {import('../../../foundation/xle/xle-ast').XLEDoc} doc
+ * @param {import('../_adapter.mjs').LayoutBlock[]} blocks
+ * @returns {Map<string, import('../../../foundation/xle/xle-ast').BlockModule>}
+ */
+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]));
+  /** @type {Map<string, import('../../../foundation/xle/xle-ast').BlockModule>} */
+  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, /** @type {import('../../../foundation/xle/xle-ast').BlockModule} */ (/** @type {unknown} */ ({mode: 'import', componentName: block.name, importPath: block.importPath, isDefault: block.isDefault})));
+    } else if (block.filePath && fs.existsSync(block.filePath)) {
+      modules.set(name, /** @type {import('../../../foundation/xle/xle-ast').BlockModule} */ ({mode: 'splice', componentName: block.dirName, source: stripTemplateAssetRefs(fs.readFileSync(block.filePath, 'utf-8'))}));
+    }
+  }
+  return modules;
+}
+
+/**
+ * `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]
+ * @returns {Promise<import('../layout.type.mjs').LayoutExpandResponse>}
+ */
+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) {
+    // The guard sees the file that will be written, not only its directory:
+    // a symlink at that name would otherwise carry the write outside the root.
+    const fileTarget = isFilePathArg(targetPath)
+      ? targetPath
+      : path.join(targetPath, `${componentName}.tsx`);
+    let filePath;
+    try {
+      filePath = assertWithin(fileTarget, cwd, {label: 'layout target path'});
+    } catch (err) {
+      if (err instanceof PathSafetyError) {
+        throw new AstryxError(err.message, undefined, ERROR_CODES.ERR_PATH_TRAVERSAL);
+      }
+      throw err;
+    }
+    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,
+    },
+  };
+}

package/api/layout/expand/expand.path-safety.test.mjs

@@ -0,0 +1,53 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Path-safety tests for the `layout.expand` write. The file written, not
+ * only the directory it lands in, must stay inside the project root.
+ */
+
+import {describe, it, expect, beforeAll} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {layoutExpand} from '../layout.mjs';
+import {buildRegistry} from '../../../foundation/xle/registry.mjs';
+
+const SLOW = 30_000;
+
+// The registry imports every component doc on first use; warm it once.
+beforeAll(async () => {
+  await buildRegistry();
+}, 120_000);
+
+describe('layout.expand — write confinement', () => {
+  it('rejects a directory target whose generated file is a symlink leading outside cwd', async () => {
+    // Inside the workspace so @astryxdesign/core resolves.
+    const cwd = fs.mkdtempSync(path.join(process.cwd(), '.xle-confine-test-'));
+    const outside = fs.mkdtempSync(path.join(os.tmpdir(), 'xle-confine-outside-'));
+    try {
+      const victim = path.join(outside, 'victim.tsx');
+      fs.writeFileSync(victim, 'OUTSIDE');
+      fs.mkdirSync(path.join(cwd, 'out'));
+      fs.symlinkSync(victim, path.join(cwd, 'out', 'GeneratedLayout.tsx'));
+
+      await expect(
+        layoutExpand('V > B', {targetPath: './out', cwd}),
+      ).rejects.toMatchObject({code: 'ERR_PATH_TRAVERSAL'});
+      expect(fs.readFileSync(victim, 'utf-8')).toBe('OUTSIDE');
+    } finally {
+      fs.rmSync(cwd, {recursive: true, force: true});
+      fs.rmSync(outside, {recursive: true, force: true});
+    }
+  }, SLOW);
+
+  it('still writes <Name>.tsx into a plain directory target', async () => {
+    const cwd = fs.mkdtempSync(path.join(process.cwd(), '.xle-confine-test-'));
+    try {
+      const result = await layoutExpand('V > B', {targetPath: './out', name: 'Demo', cwd});
+      expect(result.data.written).toBe(path.join('out', 'Demo.tsx'));
+      expect(fs.existsSync(path.join(cwd, 'out', 'Demo.tsx'))).toBe(true);
+    } finally {
+      fs.rmSync(cwd, {recursive: true, force: true});
+    }
+  }, SLOW);
+});

package/api/layout/grammar/grammar.d.mts

@@ -0,0 +1,13 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * `astryx layout grammar` — the agent cheatsheet, with the alias table
+ * generated from this branch's registry (never hand-maintained).
+ *
+ * @param {{cwd?: string}} [options]
+ * @returns {Promise<import('../layout.type.mjs').LayoutGrammarResponse>}
+ */
+export function layoutGrammar(options?: {
+    cwd?: string;
+}): Promise<import("../layout.type.mjs").LayoutGrammarResponse>;

package/api/layout/grammar/grammar.mjs

@@ -0,0 +1,87 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx layout grammar` leaf — the agent cheatsheet, with the alias
+ * table generated from this branch's registry (never hand-maintained). Reads
+ * only the registry; shares nothing with expand/check, so it has no adapter.
+ *
+ * @output {type:'layout.grammar', data}
+ * @position api — leaf over lib/xle/registry
+ */
+
+import {buildRegistry} from '../../../foundation/xle/registry.mjs';
+import {MAX_REPEAT} from '../../../foundation/xle/expand.mjs';
+
+/**
+ * `astryx layout grammar` — the agent cheatsheet, with the alias table
+ * generated from this branch's registry (never hand-maintained).
+ *
+ * @param {{cwd?: string}} [options]
+ * @returns {Promise<import('../layout.type.mjs').LayoutGrammarResponse>}
+ */
+export async function layoutGrammar(options = {}) {
+  const {cwd = process.cwd()} = options;
+  const registry = await buildRegistry({cwd});
+
+  /** @type {string[]} */
+  const aliasLines = [];
+  /** @type {Map<string, string[]>} */
+  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, at most ${MAX_REPEAT} copies (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 {experimental: {xle: {components: {KpiCard: {from: '@/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)}};
+}

package/api/layout/layout.d.mts

@@ -0,0 +1,6 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+export { layoutExpand } from "./expand/expand.mjs";
+export { layoutCheck } from "./check/check.mjs";
+export { layoutGrammar } from "./grammar/grammar.mjs";

package/api/layout/layout.mjs

@@ -0,0 +1,17 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `layout` command barrel — re-exports the expand/check/grammar leaves so
+ * the CLI (cli/commands/layout.mjs) and scripted callers import from one place.
+ * Each leaf is also importable directly (e.g. api/layout/expand/expand.mjs). The
+ * shared analysis core lives in ./_adapter.mjs. `layout` has real subcommands,
+ * so there is no flag-dispatch here — the CLI calls the leaf it wants.
+ *
+ * @input  layout expressions (+ options), per leaf
+ * @output {type, data} envelopes: layout.expand / layout.check / layout.grammar
+ * @position api — command barrel over the expand/check/grammar leaves
+ */
+
+export {layoutExpand} from './expand/expand.mjs';
+export {layoutCheck} from './check/check.mjs';
+export {layoutGrammar} from './grammar/grammar.mjs';

package/api/layout/layout.test.mjs

@@ -0,0 +1,297 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Integration tests for the layout API against the real @astryxdesign/core
+ * registry and real template blocks. Every expansion is additionally
+ * checked for TSX syntactic validity with the TypeScript parser, so the
+ * "expansion emits compilable JSX" contract is enforced, not assumed.
+ */
+
+import {describe, it, expect, beforeAll} from 'vitest';
+import {mkdtempSync, writeFileSync, rmSync} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import ts from 'typescript';
+import {layoutExpand, layoutCheck, layoutGrammar} from './layout.mjs';
+import {buildRegistry} from '../../foundation/xle/registry.mjs';
+
+// The registry imports ~140 .doc.mjs modules on first use; under full-suite
+// parallel load that can exceed the default 5s test timeout. Warm it once.
+beforeAll(async () => {
+  await buildRegistry();
+}, 120_000);
+
+const SLOW = 30_000;
+
+/** Assert TSX parses cleanly; returns the source file for inspection. */
+function expectValidTsx(code) {
+  const sourceFile = ts.createSourceFile('generated.tsx', code, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  const diagnostics = sourceFile.parseDiagnostics || [];
+  const messages = diagnostics.map(d => ts.flattenDiagnosticMessageText(d.messageText, ' '));
+  expect(messages).toEqual([]);
+  return sourceFile;
+}
+
+const LOGIN_COMPACT =
+  'Ctr[h="100dvh"] > C[w=400 p8] > V[g6] > ' +
+  '(V[g1] > Tx"Welcome back" + Tx[t=supporting]"Sign in to your account") + ' +
+  '(F > TI"Email"[t=email req] + TI"Password"[t=password req]) + ' +
+  '(H[j=between a=center] > CB"Remember me" + Lk[href="/forgot"]"Forgot password?") + ' +
+  'B.primary"Sign in"';
+
+const CHAT_OUTLINE = `
+AppShell
+  topNav: TN
+  Layout > LC !scroll
+    ChL
+      composer:
+        ChC
+      ChML
+        ChS "Today"
+        repeat 2:
+          ChM
+            ChB "Reply $"
+    Tbar "Actions"
+      B "Delete" opens=#confirm
+
+overlays:
+  AD#confirm "Delete item?"
+`;
+
+const DASHBOARD_COMPACT =
+  'A[@topNav=TN @sideNav=SN] > L > V[g6] > ' +
+  '(G[c4 g4] > C{card-callout}*4) + ' +
+  '(C[p0] > T[striped] > (TR > THC"Name" + THC"Amount") + (TR > TC"Order $" + TC"\\$12.00")*3)';
+
+describe('layoutExpand', () => {
+  it('expands the login card with typed state scaffolds', async () => {
+    const result = await layoutExpand(LOGIN_COMPACT);
+    expect(result.type).toBe('layout.expand');
+    const {code} = result.data;
+    expectValidTsx(code);
+
+    expect(code).toContain(`const [email, setEmail] = useState('');`);
+    expect(code).toContain(`const [rememberMe, setRememberMe] = useState(false);`);
+    expect(code).toContain('<XDSCenter height="100dvh">');
+    expect(code).toContain('variant="primary"');
+    // axis-neutral j/a resolved onto the HStack's real props
+    expect(code).toContain('hAlign="between"');
+    expect(code).toContain('vAlign="center"');
+    // payload routed to label props, not duplicated as children
+    expect(code).not.toMatch(/label="Forgot password\?"[\s\S]{0,80}Forgot password\?/);
+  }, SLOW);
+
+  it('expands the outline chat page: slots, repeat blocks, overlays, triggers', async () => {
+    const result = await layoutExpand(CHAT_OUTLINE);
+    const {code, form} = result.data;
+    expect(form).toBe('outline');
+    expectValidTsx(code);
+
+    expect(code).toContain('composer={');
+    // slot satisfied required prop — no double assignment, no TODO for it
+    expect(code.match(/composer=/g)).toHaveLength(1);
+    expect(code).toContain('TODO(xle): open #confirm');
+    expect(code).toContain('overlays — wire open state');
+    expect((code.match(/<XDSChatMessage\b/g) || [])).toHaveLength(2);
+  }, SLOW);
+
+  it('expands the dashboard: table partition, repeats with $ counter and \\$ escape', async () => {
+    const result = await layoutExpand(DASHBOARD_COMPACT);
+    const {code} = result.data;
+    expectValidTsx(code);
+
+    expect(code).toContain('<XDSTableHeader>');
+    expect(code).toContain('<XDSTableBody>');
+    expect(code).toContain('Order 1');
+    expect(code).toContain('Order 3');
+    expect(code).toContain('$12.00');
+    expect(code).not.toContain('112.00');
+    // {card-callout} now splices: the block is co-defined once and referenced
+    // four times — no TODO marker.
+    expect((code.match(/^function CardCallout\(\)/gm) || [])).toHaveLength(1);
+    expect((code.match(/<CardCallout \/>/g) || [])).toHaveLength(4);
+    expect(code).not.toContain("TODO(xle): content block 'CardCallout'");
+  }, SLOW);
+
+  it('compact and outline surfaces expand to identical TSX', async () => {
+    const check = await layoutCheck(LOGIN_COMPACT);
+    const fromCompact = await layoutExpand(LOGIN_COMPACT);
+    const fromOutline = await layoutExpand(check.data.outline, {form: 'outline'});
+    expect(fromOutline.data.code).toEqual(fromCompact.data.code);
+  }, SLOW);
+
+  it('expansion is deterministic', async () => {
+    const a = await layoutExpand(DASHBOARD_COMPACT);
+    const b = await layoutExpand(DASHBOARD_COMPACT);
+    expect(a.data.code).toEqual(b.data.code);
+  }, SLOW);
+
+  it('throws structured errors with suggestions on invalid expressions', async () => {
+    await expect(layoutExpand('A[p6] > Grdi')).rejects.toMatchObject({
+      code: 'ERR_LAYOUT_INVALID',
+      message: expect.stringMatching(/AppShell has no prop 'padding'/),
+    });
+  });
+
+  it('rejects non-PascalCase --name', async () => {
+    await expect(layoutExpand('V > C', {name: 'not pascal'})).rejects.toMatchObject({
+      code: 'ERR_INVALID_ARGUMENT',
+    });
+  });
+
+  it('surfaces parse errors with positions', async () => {
+    await expect(layoutExpand('V > > C')).rejects.toMatchObject({
+      code: 'ERR_LAYOUT_PARSE',
+      message: expect.stringMatching(/line 1/),
+    });
+  });
+
+  it('maps pathologically deep nesting to a coded parse error, not ERR_UNKNOWN', async () => {
+    await expect(layoutCheck('V > '.repeat(2000) + 'C')).rejects.toMatchObject({
+      code: 'ERR_LAYOUT_PARSE',
+    });
+  });
+
+  it('wraps top-level repeats and groups in a fragment (valid JSX)', async () => {
+    for (const expr of ['B"Sign in"*3', '(B"a" + B"b")', '(B"a" + B"b")*2']) {
+      const {data} = await layoutExpand(expr);
+      expectValidTsx(data.code);
+      expect(data.code).toContain('<>');
+    }
+  }, SLOW);
+
+  it('wraps a top-level outline repeat block in a fragment', async () => {
+    const {data} = await layoutExpand('repeat 3:\n  B "x"', {form: 'outline'});
+    expectValidTsx(data.code);
+  }, SLOW);
+
+  it('emits JSX-safe TSX for text payloads containing < and >', async () => {
+    const result = await layoutExpand('Text"5 < 3 and 3 > 1"');
+    expectValidTsx(result.data.code);
+  }, SLOW);
+
+  it('emits JSX-safe TSX for text payloads containing { and }', async () => {
+    const result = await layoutExpand('Text"cost is {price}"');
+    expectValidTsx(result.data.code);
+  }, SLOW);
+
+  it('emits JSX-safe TSX when a text payload looks like a closing tag', async () => {
+    const result = await layoutExpand('Text"end</Text><img/>"');
+    expectValidTsx(result.data.code);
+  }, SLOW);
+
+  it('emits JSX-safe TSX for JSX-special chars in outline form', async () => {
+    const result = await layoutExpand('VStack\n  Text "a < b"', {form: 'outline'});
+    expectValidTsx(result.data.code);
+  }, SLOW);
+});
+
+describe('layoutCheck', () => {
+  it('returns both canonical surfaces for valid input', async () => {
+    const result = await layoutCheck('V[g6] > C{card-callout}*2');
+    expect(result.data.valid).toBe(true);
+    expect(result.data.compact).toContain('{card-callout}');
+    expect(result.data.outline).toContain('C {card-callout} x2');
+  });
+
+  it('collects all errors instead of stopping at the first', async () => {
+    const result = await layoutCheck('A[p6] > V[g7] > Bd.sucess"x" + C{not-a-block}');
+    expect(result.data.valid).toBe(false);
+    expect(result.data.errors.length).toBeGreaterThanOrEqual(4);
+    const all = result.data.errors.map(e => e.message).join('\n');
+    expect(all).toMatch(/no prop 'padding'/);
+    expect(all).toMatch(/must be one of/);
+    expect(all).toMatch(/Unknown block/);
+  });
+});
+
+describe('template referencing', () => {
+  it('splices a template block: co-defined once, referenced, imports merged', async () => {
+    const result = await layoutExpand('S[p6] > C{card-callout}*3', {name: 'Demo'});
+    const {code} = result.data;
+    expectValidTsx(code);
+    // co-defined exactly once, referenced three times, no TODO
+    expect((code.match(/^function CardCallout\(\)/gm) || [])).toHaveLength(1);
+    expect((code.match(/<CardCallout \/>/g) || [])).toHaveLength(3);
+    expect(code).not.toContain('TODO(xle)');
+    // the block's own import is hoisted, and shared specifiers dedupe
+    expect((code.match(/from '@astryxdesign\/core\/Card'/g) || [])).toHaveLength(1);
+    // the block lost its export — it's a local declaration now
+    expect(code).not.toContain('export default function CardCallout');
+    expect(result.data.blocksReferenced).toEqual([{name: 'CardCallout', mode: 'splice'}]);
+  }, SLOW);
+
+  it('merges a stateful block useState into a single react import', async () => {
+    const result = await layoutExpand(
+      'V > TI"Search"[t=text] + {table-column-settings-table}',
+      {name: 'Demo'},
+    );
+    const {code} = result.data;
+    expectValidTsx(code);
+    // page TextInput scaffolds useState; block also uses useState → one import
+    expect((code.match(/^import \{useState\} from 'react';$/gm) || [])).toHaveLength(1);
+    expect(code).toContain('function TableColumnSettingsTable()');
+  }, SLOW);
+
+  it('imports app-registered local components (the local-component bridge)', async () => {
+    // Inside the workspace so @astryxdesign/core resolves; cleaned up after.
+    // A package.json beside the config makes Project.load resolve it as the
+    // sibling-of-nearest-package.json (the standard config resolution).
+    const cwd = mkdtempSync(join(process.cwd(), '.xle-imp-test-'));
+    try {
+      writeFileSync(join(cwd, 'package.json'), '{"name": "xle-imp-fixture"}\n');
+      writeFileSync(
+        join(cwd, 'astryx.config.mjs'),
+        `export default {experimental: {xle: {components: {KpiCard: {from: '@/components/KpiCard'}, TimeRangePicker: {from: '@/components/TimeRangePicker'}}}}};\n`,
+      );
+      const result = await layoutExpand('S[p6] > (G[c4 g4] > {kpi-card}*4) + {time-range-picker}', {
+        name: 'Demo',
+        cwd,
+      });
+      const {code} = result.data;
+      expectValidTsx(code);
+      expect(code).toContain("import {KpiCard} from '@/components/KpiCard';");
+      expect(code).toContain("import {TimeRangePicker} from '@/components/TimeRangePicker';");
+      expect((code.match(/<KpiCard \/>/g) || [])).toHaveLength(4);
+      expect(code).toContain('<TimeRangePicker />');
+      expect(result.data.blocksReferenced).toContainEqual({name: 'KpiCard', mode: 'import'});
+    } finally {
+      rmSync(cwd, {recursive: true, force: true});
+    }
+  }, SLOW);
+
+  it('parses a standalone {block} in both surfaces', async () => {
+    const check = await layoutCheck('G[c4 g4] > {card-callout}*2');
+    expect(check.data.valid).toBe(true);
+    expect(check.data.compact).toContain('{card-callout}*2');
+    expect(check.data.outline).toMatch(/\{card-callout\} x2/);
+  });
+});
+
+describe('layoutGrammar', () => {
+  it('emits the cheatsheet with branch-generated aliases', async () => {
+    const result = await layoutGrammar();
+    expect(result.data.text).toContain('TWO SURFACES');
+    expect(result.data.aliases.V).toBe('VStack');
+    expect(result.data.aliases.TB).toBe('TableBody');
+    // every alias target must exist — the table is registry-filtered
+    expect(Object.values(result.data.aliases)).not.toContain(undefined);
+  });
+});
+
+
+describe('layout — input validation (API matches CLI)', () => {
+  it('rejects an invalid --form value instead of silently parsing as compact', async () => {
+    await expect(layoutCheck('V > C', {form: /** @type {any} */ ('xml')})).rejects.toMatchObject({
+      code: 'ERR_INVALID_OPTION',
+    });
+    await expect(layoutExpand('V > C', {form: /** @type {any} */ ('nonsense')})).rejects.toMatchObject({
+      code: 'ERR_INVALID_OPTION',
+    });
+  });
+
+  it('rejects an empty expression at the API layer', async () => {
+    await expect(layoutCheck('')).rejects.toMatchObject({code: 'ERR_INVALID_ARGUMENT'});
+    await expect(layoutExpand('   ')).rejects.toMatchObject({code: 'ERR_INVALID_ARGUMENT'});
+  });
+});