@astryxdesign/cli 0.6.4-canary.06c8fa3 → 0.6.4-canary.0e1fbdb

package/foundation/doc-compiler/doc-loads.test.mjs

@@ -53,8 +53,8 @@ const RUNNERS = {
     sites: ['import(node:child_process)', 'worker_threads.Worker'],
   },
   'api/integration/pack-check.mjs': {
-    runs: '`npm pack`, `tar`, and a Node script that resolves the packed specifiers, to check a package as published',
-    sites: ['child_process.spawnSync ×3'],
+    runs: '`npm pack`, `tar`, and a Node script that resolves the packed specifiers, to check a package as published, and the package\'s doc modules, to see which need a newer CLI',
+    sites: ['child_process.spawnSync ×3', 'loadTopicModule'],
   },
   'api/swizzle/_github.mjs': {
     runs: '`gh auth status`, to check the GitHub CLI is signed in',
@@ -188,9 +188,22 @@ const RUNNERS = {
       'import ../../../api/integration/integrationPackCheck.doc.mjs',
       'import ./integration-add.doc.mjs',
       'import ./integration-pack.doc.mjs',
+      'import ./integration-verify.doc.mjs',
       'import ./integration.doc.mjs',
     ],
   },
+  'clients/cli/commands/layout.mjs': {
+    runs: SELF_DOCS,
+    sites: [
+      'import ../../../api/layout/layoutCheck.doc.mjs',
+      'import ../../../api/layout/layoutExpand.doc.mjs',
+      'import ../../../api/layout/layoutGrammar.doc.mjs',
+      'import ./layout-check.doc.mjs',
+      'import ./layout-expand.doc.mjs',
+      'import ./layout-grammar.doc.mjs',
+      'import ./layout.doc.mjs',
+    ],
+  },
   'clients/cli/commands/search.mjs': {
     runs: SELF_DOCS,
     sites: [

package/foundation/doc-compiler/inputs.test.mjs

@@ -90,7 +90,6 @@ describe('collectDocInputs over what this repo ships', () => {
     ).toEqual([
       'Chat',
       'ChatComposerTokenElement',
-      'Code',
       'ContextMenuItem',
       'Heading',
       'Indicator',

package/foundation/doc-compiler/tree.d.mts

@@ -240,6 +240,10 @@ export type TreeNode = {
     name: string;
     title: string;
     summary: string;
+    /**
+     * an authored namespace's search keywords
+     */
+    keywords?: string[] | undefined;
     /**
      * the parent's route; null at the top
      */

package/foundation/doc-compiler/tree.mjs

@@ -58,7 +58,7 @@ export const KIND_GROUPS = Object.freeze({
   schema: {
     segment: 'schemas',
     title: 'Schemas',
-    summary: 'Every shape the CLI reads or returns, field by field.',
+    summary: 'Data shapes, field by field.',
   },
   enum: {
     segment: 'enums',
@@ -140,6 +140,7 @@ export const UNORGANIZED = 'unorganized';
  * @property {string} name
  * @property {string} title
  * @property {string} summary
+ * @property {string[]} [keywords] an authored namespace's search keywords
  * @property {string | null} parent the parent's route; null at the top
  * @property {string | null} slot the parent slot this node sits in
  * @property {number | null} order
@@ -420,10 +421,14 @@ export function buildDocsTree({namespaces, docs, topics = []}) {
         name: input.doc.name,
         title: input.doc.title,
         summary: input.doc.summary,
+        ...(Array.isArray(input.doc.keywords)
+          ? {keywords: input.doc.keywords}
+          : {}),
         parent: parentRoute,
         slot: home?.slot ?? null,
         order: home?.order ?? null,
         generated: false,
+        ref: {selfDoc: input.doc},
         slots: Object.entries(input.doc.slots).map(([name, slot]) => ({
           name,
           title: slot.title,

package/foundation/integrations/cli-requirement.d.mts

@@ -20,13 +20,31 @@ export function lowestAdmitted(range: unknown): string | null;
  */
 export function docsTreeCliProblem(pkg: any): string | null;
 /**
- * Why a package with a template that sets `replaces` would lose its templates
- * and doc topics on an older CLI (spec:AST-035), or null when its declared CLI
+ * Why a package with a template that sets `replaces` would lose templates and
+ * doc topics on an older CLI (spec:AST-035), or null when its declared CLI
  * range admits only CLIs that read the field.
  * @param {any} pkg package.json
  * @returns {string | null}
  */
 export function replacesCliProblem(pkg: any): string | null;
+/**
+ * Why a package with a doc section that sets `id` would lose its doc topics on
+ * an older CLI, or null when its declared CLI range admits only CLIs that read
+ * the field. Published 0.6.3 rejects a section `id` and hides every doc topic
+ * the package ships.
+ * @param {any} pkg package.json
+ * @returns {string | null}
+ */
+export function sectionIdsCliProblem(pkg: any): string | null;
+/**
+ * Why a package that ships a theme would lose its themes and doc topics on an
+ * older CLI, or null when its declared CLI range admits only CLIs that read
+ * typed theme descriptors. Published 0.6.3 rejects a themes root with no
+ * `manifest.json` catalog, which `integration add theme` no longer writes.
+ * @param {any} pkg package.json
+ * @returns {string | null}
+ */
+export function themesCliProblem(pkg: any): string | null;
 /**
  * The package.json with a CLI peer that reads namespace docs: optional, unless
  * the package already says otherwise.
@@ -37,9 +55,11 @@ export function withDocsTreeCli(pkg: any): any;
 export const CLI_PACKAGE: "@astryxdesign/cli";
 /**
  * The first CLI release that reads an integration's docs tree (namespace docs
- * and placed guides) and its templates' `replaces`. A release before it can
- * hide every doc topic a package with a namespace doc or a placed guide
- * ships, with no warning, and it rejects `replaces` and withholds the
- * package's templates and doc topics.
+ * and placed guides), its templates' `replaces`, and its typed theme
+ * descriptors. A release before it can hide every doc topic a package with a
+ * namespace doc or a placed guide ships, with no warning; it rejects
+ * `replaces`, drops that template, and hides the package's doc topics; and it
+ * rejects a themes root without the `manifest.json` catalog the CLI no longer
+ * writes, withholding the package's themes and doc topics.
  */
 export const DOCS_TREE_CLI: "0.7.0";

package/foundation/integrations/cli-requirement.mjs

@@ -6,8 +6,9 @@
  * @input A package.json object.
  * @output Whether its `peerDependencies` range for `@astryxdesign/cli` admits
  *   only CLIs that read namespace docs, and the package.json that declares it.
- * @position foundation/integrations; read by `integration add doc --parent`,
- *   which declares the peer, and `integration pack --check`, which requires it.
+ * @position foundation/integrations; read by `integration add doc --parent`
+ *   and `integration add theme`, which declare the peer, and
+ *   `integration verify`, which requires it.
  */
 
 import {semverCompare} from '../env/semver.mjs';
@@ -16,10 +17,12 @@ export const CLI_PACKAGE = '@astryxdesign/cli';
 
 /**
  * The first CLI release that reads an integration's docs tree (namespace docs
- * and placed guides) and its templates' `replaces`. A release before it can
- * hide every doc topic a package with a namespace doc or a placed guide
- * ships, with no warning, and it rejects `replaces` and withholds the
- * package's templates and doc topics.
+ * and placed guides), its templates' `replaces`, and its typed theme
+ * descriptors. A release before it can hide every doc topic a package with a
+ * namespace doc or a placed guide ships, with no warning; it rejects
+ * `replaces`, drops that template, and hides the package's doc topics; and it
+ * rejects a themes root without the `manifest.json` catalog the CLI no longer
+ * writes, withholding the package's themes and doc topics.
  */
 export const DOCS_TREE_CLI = '0.7.0';
 
@@ -92,11 +95,11 @@ function cliRangeProblem(pkg, feature, loss) {
   const range = pkg?.peerDependencies?.[CLI_PACKAGE];
   const fix = `"${CLI_PACKAGE}": ">=${DOCS_TREE_CLI}" in peerDependencies (optional in peerDependenciesMeta, if the CLI is not required)`;
   if (typeof range !== 'string') {
-    return `The package ${feature} but declares no ${CLI_PACKAGE} peer. A CLI older than ${DOCS_TREE_CLI} ${loss}. Declare ${fix}.`;
+    return `The package ${feature} but declares no ${CLI_PACKAGE} peer. A stable CLI before ${DOCS_TREE_CLI} ${loss}. Declare ${fix}.`;
   }
   const lowest = lowestAdmitted(range);
   if (lowest == null || semverCompare(lowest, DOCS_TREE_CLI) < 0) {
-    return `The package ${feature}, but its ${CLI_PACKAGE} peer range "${range}" admits a CLI older than ${DOCS_TREE_CLI}, which ${loss}. Declare ${fix}.`;
+    return `The package ${feature}, but its ${CLI_PACKAGE} peer range "${range}" admits a stable CLI before ${DOCS_TREE_CLI}, which ${loss}. Declare ${fix}.`;
   }
   return null;
 }
@@ -119,8 +122,8 @@ export function docsTreeCliProblem(pkg) {
 }
 
 /**
- * Why a package with a template that sets `replaces` would lose its templates
- * and doc topics on an older CLI (spec:AST-035), or null when its declared CLI
+ * Why a package with a template that sets `replaces` would lose templates and
+ * doc topics on an older CLI (spec:AST-035), or null when its declared CLI
  * range admits only CLIs that read the field.
  * @param {any} pkg package.json
  * @returns {string | null}
@@ -129,7 +132,39 @@ export function replacesCliProblem(pkg) {
   return cliRangeProblem(
     pkg,
     'has a template that sets `replaces`',
-    "rejects the field, and withholds the package's templates and doc topics",
+    "rejects the field, drops that template, and hides the package's doc topics",
+  );
+}
+
+/**
+ * Why a package with a doc section that sets `id` would lose its doc topics on
+ * an older CLI, or null when its declared CLI range admits only CLIs that read
+ * the field. Published 0.6.3 rejects a section `id` and hides every doc topic
+ * the package ships.
+ * @param {any} pkg package.json
+ * @returns {string | null}
+ */
+export function sectionIdsCliProblem(pkg) {
+  return cliRangeProblem(
+    pkg,
+    'has a doc section that sets `id`',
+    'rejects the field, and can hide every doc topic the package ships',
+  );
+}
+
+/**
+ * Why a package that ships a theme would lose its themes and doc topics on an
+ * older CLI, or null when its declared CLI range admits only CLIs that read
+ * typed theme descriptors. Published 0.6.3 rejects a themes root with no
+ * `manifest.json` catalog, which `integration add theme` no longer writes.
+ * @param {any} pkg package.json
+ * @returns {string | null}
+ */
+export function themesCliProblem(pkg) {
+  return cliRangeProblem(
+    pkg,
+    'ships a theme',
+    "cannot read typed theme descriptors, and can drop the package's themes and hide its doc topics",
   );
 }
 

package/foundation/integrations/cli-requirement.test.mjs

@@ -32,6 +32,11 @@ describe('docsTreeCliProblem', () => {
     expect(docsTreeCliProblem({name: '@acme/kit'})).toContain(
       'declares no @astryxdesign/cli peer',
     );
+    // Stable releases: a canary built from main before its release reports
+    // the older version and reads every feature.
+    expect(docsTreeCliProblem({name: '@acme/kit'})).toContain(
+      'A stable CLI before 0.7.0 does not read the docs tree',
+    );
   });
 
   it.each(['^0.6.0', '^0.6.0 || >=0.7.0', '*', '>=0.6.3'])(
@@ -39,7 +44,7 @@ describe('docsTreeCliProblem', () => {
     range => {
       expect(
         docsTreeCliProblem({peerDependencies: {'@astryxdesign/cli': range}}),
-      ).toContain('admits a CLI older than');
+      ).toContain('admits a stable CLI before');
     },
   );
 
@@ -76,7 +81,7 @@ describe('replacesCliProblem', () => {
     );
     expect(
       replacesCliProblem({peerDependencies: {'@astryxdesign/cli': '^0.6.0'}}),
-    ).toContain('admits a CLI older than');
+    ).toContain('admits a stable CLI before');
     expect(
       replacesCliProblem({peerDependencies: {'@astryxdesign/cli': '>=0.7.0'}}),
     ).toBeNull();

package/foundation/integrations/contribution-inventory.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Contribution inventory for integration pack-check.
+ * @file Contribution inventory for `astryx integration verify`.
  *
  * Enumerates the files and contribution identities an integration package
  * declares, for cross-referencing against the npm tarball. The file inventory

package/foundation/response/error-codes.doc.mjs

@@ -36,17 +36,16 @@ export const doc = {
     {
       value: 'ERR_INVALID_OPTION',
       description:
-        'An unknown flag/option was passed (Commander `unknownOption`).',
+        'An unknown option was passed, --json was given to a command without JSON output, or layout --form got a value other than compact, outline, or auto.',
     },
     {
       value: 'ERR_INVALID_ARGUMENT',
       description:
-        "An option/argument had a value Commander's parser rejected.",
+        'An argument or option value is invalid: wrong type, out of range, an unknown choice, an extra argument, or a conflicting combination.',
     },
     {
       value: 'ERR_MISSING_ARGUMENT',
-      description:
-        'A required positional argument was omitted (Commander `missingArgument`).',
+      description: 'A required argument or option value was omitted.',
     },
     {
       value: 'ERR_INVALID_LANG',
@@ -134,12 +133,11 @@ export const doc = {
     },
     {
       value: 'ERR_UNKNOWN_PACKAGE',
-      description: 'No package matched the requested name (discover).',
+      description: 'No package matched the requested name.',
     },
     {
       value: 'ERR_UNKNOWN_AGENT',
-      description:
-        'An unrecognized `--agent` value was passed to agent-docs/init.',
+      description: 'An unrecognized `--agent` value was passed to init.',
     },
     {
       value: 'ERR_UNKNOWN_FEATURE',
@@ -272,7 +270,7 @@ export const doc = {
     {
       value: 'ERR_UNCLASSIFIED_EXIT',
       description:
-        'Recorded in the debug log, never printed: a command exited non-zero without going through cliError/jsonError, so no stable code was available.',
+        'Recorded in the debug log, never printed: a command exited non-zero without reporting an error code.',
     },
     {
       value: 'ERR_SIGNAL_TERMINATED',

package/foundation/response/error-codes.test.mjs

@@ -195,9 +195,16 @@ describe('error codes: end-to-end JSON envelopes', () => {
     // is rejected at the preAction gate with a stable invalid-option code.
     {
       name: 'json not supported',
-      args: ['theme', 'bogus-sub', '--json'],
+      args: ['theme', '--json'],
       code: 'ERR_INVALID_OPTION',
     },
+    // A group given a word it does not have names the unknown subcommand,
+    // in JSON as in text.
+    {
+      name: 'unknown subcommand of a group',
+      args: ['theme', 'bogus-sub', '--json'],
+      code: 'ERR_UNKNOWN_SUBCOMMAND',
+    },
   ];
 
   for (const {name, args, code} of cases) {
@@ -249,13 +256,31 @@ describe('error codes: human mode stays clean', () => {
     expect(stdout).not.toContain('ERR_UNKNOWN_COMPONENT');
   });
 
-  it('unknown subcommand exits 1 in human mode (code carried internally)', async () => {
-    // `theme` is not JSON-capable, so this path is human-only; we assert the
-    // failure surfaces with exit 1 and a helpful message. The stable
-    // ERR_UNKNOWN_SUBCOMMAND code rides along on the cliError call.
+  it('unknown subcommand exits 1, with the code in JSON and not in text', async () => {
+    // A group that is not JSON-capable itself still answers an unknown
+    // subcommand in JSON, so a JSON caller learns the subcommands it has.
     const {status, stderr} = await runCli(['theme', 'bogus-sub']);
     expect(status).toBe(1);
     expect(stderr).toContain("unknown subcommand 'theme bogus-sub'");
     expect(stderr).not.toContain('ERR_UNKNOWN_SUBCOMMAND');
+    for (const args of [
+      ['--json', 'theme', 'bogus-sub'],
+      ['theme', 'bogus-sub', '--json'],
+      ['--json', 'doctor', 'integration', 'bogus-sub'],
+    ]) {
+      const json = await runCli(args);
+      expect(json.status, args.join(' ')).toBe(1);
+      expect(JSON.parse(json.stdout), args.join(' ')).toMatchObject({
+        code: 'ERR_UNKNOWN_SUBCOMMAND',
+        suggestions: expect.arrayContaining([expect.objectContaining({reason: 'available subcommand'})]),
+      });
+    }
+    // Text and JSON agree for a group that shows help when run bare.
+    const text = await runCli(['doctor', 'integration', 'bogus-sub']);
+    expect(text.status).toBe(1);
+    expect(text.stderr).toContain("unknown subcommand 'doctor integration bogus-sub'");
+    const doctor = await runCli(['doctor', 'integrations']);
+    expect(doctor.status).toBe(1);
+    expect(doctor.stderr).toContain("unknown subcommand 'doctor integrations'");
   });
 });

package/foundation/response/response-types.doc.d.mts

@@ -4,9 +4,10 @@
 /**
  * @file EnumDoc for the `type` discriminant carried on every --json success
  * envelope. The vocabulary mirrors the RESPONSE_TYPES map (each command's
- * `jsonOut(...)` call sites) in `clients/cli/lib/manifest.mjs`; a consumer
- * switches on `type` to narrow the `data` payload. Descriptions follow the
- * currently published response projection, not a future package-version boundary.
+ * `jsonOut(...)` call sites) plus ROOT_RESPONSE_TYPES (help, version) in
+ * `clients/cli/lib/manifest.mjs`; a consumer switches on `type` to narrow the
+ * `data` payload. Descriptions follow the currently published response
+ * projection, not a future package-version boundary.
  *
  * @input Public response discriminants and their currently released payloads.
  * @output Generated consumer reference for every typed JSON success response.

package/foundation/response/response-types.doc.mjs

@@ -3,9 +3,10 @@
 /**
  * @file EnumDoc for the `type` discriminant carried on every --json success
  * envelope. The vocabulary mirrors the RESPONSE_TYPES map (each command's
- * `jsonOut(...)` call sites) in `clients/cli/lib/manifest.mjs`; a consumer
- * switches on `type` to narrow the `data` payload. Descriptions follow the
- * currently published response projection, not a future package-version boundary.
+ * `jsonOut(...)` call sites) plus ROOT_RESPONSE_TYPES (help, version) in
+ * `clients/cli/lib/manifest.mjs`; a consumer switches on `type` to narrow the
+ * `data` payload. Descriptions follow the currently published response
+ * projection, not a future package-version boundary.
  *
  * @input Public response discriminants and their currently released payloads.
  * @output Generated consumer reference for every typed JSON success response.
@@ -35,7 +36,7 @@ export const doc = {
     {
       value: 'component.list',
       description:
-        'The component catalog grouped by category: `detail` (the level: names | compact | full) and `components`, the grouped map of names entries ({name, package, and optional canonical import for integrations}), brief entries, or a full ComponentDoc per entry.',
+        "The component catalog grouped by component group (each component's group field): `detail` (the level: names | compact | full) and `components`, the grouped map of names entries ({name, package, and optional canonical import for integrations}), brief entries, or a full ComponentDoc per entry.",
     },
     {
       value: 'component.batch',
@@ -160,7 +161,7 @@ export const doc = {
     {
       value: 'swizzle.copy',
       description:
-        'An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and an optional maintainer note.',
+        'An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and, when the owner has an issues URL, feedback ({issuesUrl, ghCommand?}): where to report the gap that led to swizzling.',
     },
 
     // gap reports
@@ -262,6 +263,11 @@ export const doc = {
       description:
         'Every available codemod, oldest→newest, as {name, title, version, optional}; returned for --list without running anything.',
     },
+    {
+      value: 'upgrade.registry',
+      description:
+        'The copied-composition receipt for --registry: applied, ok, the counts (found, current, wouldUpdate, updated, wouldMerge, merged, wouldRefreshReceipt, receiptsRefreshed, conflicts, missing, invalid, failed), and items.',
+    },
     {
       value: 'upgrade.status',
       description:
@@ -280,11 +286,24 @@ export const doc = {
         'The CLI capability manifest: name, version, apiVersion, description, globalOptions, commands (each name, description, arguments, options, json, aliases?, responseTypes?, examples?, exitCodes? as [{code, when}], subcommands?), jsonSupported, and the flat responseTypes index.',
     },
 
+    // help and version, which no single command owns
+    {
+      value: 'help',
+      description:
+        'Help, in one of two shapes. A bare `astryx --json` returns the root manifest: name, version, commands (the command names), jsonSupported, and manifest (the full payload `astryx manifest --json` returns). ' +
+        "`--help --json` on any command, or `astryx help [command] --json`, returns that command's help: command, description, usage, options (each flags, description, and defaultValue and choices when set), and subcommands (each name and description). " +
+        'data.manifest marks the first shape; data.usage marks the second.',
+    },
+    {
+      value: 'version',
+      description: 'The CLI version, for `astryx --version --json`: {version}.',
+    },
+
     // doctor
     {
       value: 'doctor',
       description:
-        'The health-check report: `checks` (each with id, label, status: pass | warn | fail | info, a message, and a fix when not passing) plus a `summary` of counts per status.',
+        'The health-check report: `checks` (each with id, label, status: pass | warn | fail | info, a message, and an optional fix, always present on warn and fail) plus a `summary` of counts per status.',
     },
 
     // integration authoring
@@ -318,5 +337,22 @@ export const doc = {
       description:
         'The integration identity, structural issues, and Core doc overlaps. Each finding includes `severity` (`info` | `error`) and `relationship` (`replaces` | `extends` | `accidental`).',
     },
+
+    // layout (XLE/XLO)
+    {
+      value: 'layout.expand',
+      description:
+        'The expansion: parsed form, generated TSX code, componentsUsed, states (count of useState hooks scaffolded), todos, blocksReferenced (each {name, mode}), warnings, and written (the output path, or null when nothing was written).',
+    },
+    {
+      value: 'layout.check',
+      description:
+        'The validation result: a valid flag, the detected form, errors (each with line/col, message, formatted text, and suggestions), warnings, and the expression re-printed in both canonical surfaces (compact and outline).',
+    },
+    {
+      value: 'layout.grammar',
+      description:
+        "The XLE/XLO grammar cheatsheet: a text field with the full reference plus an aliases map (short name → canonical component) generated from this install's registry.",
+    },
   ],
 };

package/foundation/response/response.doc.mjs

@@ -39,16 +39,13 @@ export const doc = {
           name: 'type',
           type: 'string',
           description:
-            'Discriminator naming the payload shape. Each command guarantees ' +
-            'its own `type` at its return; there is no central union.',
+            'Names the payload shape. Every value is listed in the response-types enum.',
           required: true,
         },
         {
           name: 'data',
           type: 'unknown',
-          description:
-            "The command's payload. Structural by design, narrowed by the " +
-            'per-command return type, not by a map in the serializer.',
+          description: "The command's payload; its shape depends on `type`.",
           required: true,
         },
         {
@@ -64,7 +61,7 @@ export const doc = {
       type: '{ apiVersion: number; error: string; code: ErrorCode; suggestions?: Suggestion[] }',
       description:
         'Emitted for every failure in --json mode, including uncaught throws ' +
-        'and Commander parse errors, which are converted to this shape.',
+        'and command-line parse errors, which are converted to this shape.',
       fields: [
         {
           name: 'apiVersion',
@@ -121,7 +118,7 @@ export const doc = {
       label: 'Success',
       code: `{
   "apiVersion": 1,
-  "type": "component",
+  "type": "component.detail",
   "data": { "name": "Button" }
 }`,
     },
@@ -153,9 +150,13 @@ export const doc = {
     {
       type: 'prose',
       text:
-        'The process exit code is part of the contract too: successful commands ' +
-        'exit 0, and a JSON error envelope is accompanied by a non-zero exit ' +
-        '(jsonError exits 1).',
+        'The process exit code is part of the contract too. Exit 0 means success, ' +
+        'and every error envelope exits 1. Some commands also exit 1 with a success ' +
+        'envelope when what they report failed: a failed check (layout check, doctor ' +
+        'and its integration subcommands, integration verify, theme build ' +
+        '--check), a gap report that was not delivered, an upgrade left incomplete, ' +
+        'or init agent docs refused for a path outside the project. Read the ' +
+        'envelope, not the exit code, to tell them apart.',
     },
   ],
 };

package/foundation/xle/browser.d.mts

@@ -2,8 +2,8 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * Validate an expression and return both canonical surfaces. Never throws on
- * invalid input; returns the errors.
+ * Validate an expression and return both canonical surfaces — the browser
+ * twin of `layout check`. Never throws on invalid input; returns the errors.
  *
  * @param {string} expression
  * @param {import('./xle-ast').Registry | import('./browser').SerializedRegistry | object} registry - serialized or hydrated
@@ -19,7 +19,7 @@ export function checkExpression(expression: string, registry: import("./xle-ast"
     loose?: boolean | undefined;
 }): import("./browser").CheckResult;
 /**
- * Validate + expand to TSX.
+ * Validate + expand to TSX — the browser twin of `layout expand`.
  * Returns either {code, ...} or {errors} (never writes files).
  *
  * @param {string} expression

package/foundation/xle/browser.mjs

@@ -44,8 +44,8 @@ function formatIssue(issue) {
 }
 
 /**
- * Validate an expression and return both canonical surfaces. Never throws on
- * invalid input; returns the errors.
+ * Validate an expression and return both canonical surfaces — the browser
+ * twin of `layout check`. Never throws on invalid input; returns the errors.
  *
  * @param {string} expression
  * @param {import('./xle-ast').Registry | import('./browser').SerializedRegistry | object} registry - serialized or hydrated
@@ -85,7 +85,7 @@ export function checkExpression(expression, registry, opts = {}) {
 }
 
 /**
- * Validate + expand to TSX.
+ * Validate + expand to TSX — the browser twin of `layout expand`.
  * Returns either {code, ...} or {errors} (never writes files).
  *
  * @param {string} expression

package/foundation/xle/expand.mjs

@@ -13,7 +13,7 @@
  *
  * @input  validated doc (nodes carry .bound) + registry
  * @output expand() → {code, componentsUsed, states, todos}
- * @position lib/xle — last stage; the browser barrel orchestrates
+ * @position lib/xle — last stage; api/layout.mjs orchestrates
  */
 
 import {PAYLOAD_PROPS} from './validate.mjs';
@@ -751,7 +751,7 @@ export function expand(doc, registry, options = {}) {
     : [];
 
   const code = [
-    `// Generated by the Astryx XLE expander — this file is the artifact; edit freely.`,
+    `// Generated by \`astryx layout expand\` — this file is the artifact; edit freely.`,
     ...importLines,
     ...blockSection,
     '',

package/foundation/xle/parse.mjs

@@ -302,7 +302,7 @@ function parseAttrToken(token, line) {
  * Guard against unbounded recursion in the compact parser. A layout tree this
  * deep is never hand-authored; without the cap the recursive descent blows the
  * JS call stack and surfaces a raw RangeError (→ ERR_UNKNOWN, no line/col)
- * instead of a located parse error. The counter is module-level so it
+ * instead of a located ERR_LAYOUT_PARSE. The counter is module-level so it
  * spans group / attribute sub-streams; each parse entry point resets it.
  */
 const MAX_COMPACT_DEPTH = 512;

package/foundation/xle/print.mjs

@@ -3,8 +3,8 @@
 /**
  * @file XLE canonical printers — AST → compact (XLE) or outline (XLO) text.
  *
- * Used by `checkExpression` so either party (agent or human) can request the
- * other surface, and by round-trip conformance tests.
+ * Used by `astryx layout check --form …` so either party (agent or human)
+ * can request the other surface, and by round-trip conformance tests.
  * Printing is best-effort canonical: spelling variants the lexer
  * normalized are emitted in canonical form.
  *

package/foundation/xle/splice.mjs

@@ -18,7 +18,7 @@
  *
  * @input  block TSX source (splice) or a name+importPath (import)
  * @output prepareSpliceModule / parseImportStatements + import-merge helpers
- * @position lib/xle — used by expand.mjs; sources gathered by the caller
+ * @position lib/xle — used by expand.mjs; sources gathered in api/layout.mjs
  */
 
 const IMPORT_RE =