@astryxdesign/cli 0.3.0-canary.c857354 → 0.3.0-canary.d52d2cb

package/foundation/integrations/integration-warnings.mjs

@@ -19,7 +19,7 @@
  *     ADDS a one-line nudge.
  */
 
-import {validateLoadedIntegration} from '../../api/integration/validate-integration.mjs';
+import {validateLoadedIntegration} from './validate-contributions.mjs';
 
 /**
  * For each configured (already-loaded) integration, compute its issues using

package/foundation/integrations/integrations.d.mts

@@ -0,0 +1,80 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Return the conventional root manifest paths present in `dir`, in
+ * load-precedence order. Unlike {@link resolveManifestPath} this never throws —
+ * callers (e.g. validate-integration) decide how to treat zero / multiple.
+ * @param {string} dir
+ * @returns {string[]} absolute manifest paths
+ */
+export function findManifestPaths(dir: string): string[];
+/**
+ * Load and validate a manifest module's default export against the integration
+ * schema. Default export only — `.ts` is loaded via jiti; `.mjs`/`.js` via
+ * dynamic import. Throws if the default export is missing or invalid. Exposed
+ * for validate-integration.
+ * @param {string} file absolute manifest path
+ * @param {string} [label] used in error messages
+ * @returns {Promise<import('../../authoring/integration/type').AstryxIntegration>}
+ */
+export function loadManifestObject(file: string, label?: string): Promise<import("../../authoring/integration/type").AstryxIntegration>;
+/**
+ * Resolve the directory of an installed integration package from the consumer's
+ * node_modules.
+ * @param {string} packageName
+ * @param {string} [cwd]
+ */
+export function resolvePackageDir(packageName: string, cwd?: string): string;
+/**
+ * Load configured integrations.
+ *
+ * @param {string[]} [specs] package names
+ * @param {{cwd?: string}} [options]
+ * @returns {Promise<LoadedIntegration[]>}
+ */
+export function loadIntegrations(specs?: string[], { cwd }?: {
+    cwd?: string;
+}): Promise<LoadedIntegration[]>;
+/**
+ * A fully-resolved, loaded integration. Identity (`name`, `version`) comes from
+ * the package's package.json; the `components`/`templates`/`codemods` roots are
+ * absolute paths resolved from the manifest. The `__`-prefixed fields are
+ * internal bookkeeping used by validate-integration and Project.
+ * @typedef {object} LoadedIntegration
+ * @property {string} name
+ * @property {string} [version]
+ * @property {string} [components]
+ * @property {string} [templates]
+ * @property {string} [codemods]
+ * @property {string} [issuesUrl]
+ * @property {string} __spec
+ * @property {string} __packageDir
+ * @property {string} __manifestFile
+ * @property {string} [__loadError] set when the manifest failed to load/validate;
+ *   such an integration contributes nothing and is surfaced via Project.issues()
+ */
+/** Conventional manifest basenames, in load-precedence order. */
+export const MANIFEST_BASENAMES: string[];
+/**
+ * A fully-resolved, loaded integration. Identity (`name`, `version`) comes from
+ * the package's package.json; the `components`/`templates`/`codemods` roots are
+ * absolute paths resolved from the manifest. The `__`-prefixed fields are
+ * internal bookkeeping used by validate-integration and Project.
+ */
+export type LoadedIntegration = {
+    name: string;
+    version?: string | undefined;
+    components?: string | undefined;
+    templates?: string | undefined;
+    codemods?: string | undefined;
+    issuesUrl?: string | undefined;
+    __spec: string;
+    __packageDir: string;
+    __manifestFile: string;
+    /**
+     * set when the manifest failed to load/validate;
+     * such an integration contributes nothing and is surfaced via Project.issues()
+     */
+    __loadError?: string | undefined;
+};

package/foundation/integrations/validate-contributions.d.mts

@@ -0,0 +1,22 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @typedef {import('./issue').AstryxIntegrationIssue} Issue
+ * @typedef {import('./integrations.mjs').LoadedIntegration} LoadedIntegration
+ */
+/** @param {string} code @param {string} message @returns {Issue} */
+export function issueError(code: string, message: string): Issue;
+/**
+ * Validate an already-LOADED integration (as produced by `loadIntegrations` —
+ * absolute contribution roots plus identity) and return its issues. This is the
+ * reuse seam for everyday commands that have already loaded the configured
+ * integrations and want the SAME validators that `validate-integration` runs,
+ * without re-resolving the manifest from disk.
+ *
+ * @param {LoadedIntegration} loaded loaded-integration-shaped object
+ * @returns {Promise<Issue[]>}
+ */
+export function validateLoadedIntegration(loaded: LoadedIntegration): Promise<Issue[]>;
+export type Issue = import("./issue").AstryxIntegrationIssue;
+export type LoadedIntegration = import("./integrations.mjs").LoadedIntegration;

package/foundation/integrations/validate-contributions.mjs

@@ -0,0 +1,162 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file On-disk contribution checks for a LOADED integration.
+ *
+ * These validators live in foundation rather than beside the
+ * `validate-integration` command because foundation itself needs them:
+ * `Project` collects integration issues while assembling components/templates,
+ * and `integration-warnings` nudges about them on ordinary commands. Keeping
+ * them here means those callers no longer reach up into `api/`.
+ *
+ * The manifest schema is NOT re-validated here — `loadIntegrations` already did
+ * that and throws otherwise. What is re-checked is the on-disk contributions
+ * (roots + codemods/templates/components), because those regress independently
+ * of the manifest: a deleted directory, a template that lost its source file.
+ *
+ * @input a loaded-integration-shaped object (absolute contribution roots + identity)
+ * @output AstryxIntegrationIssue[]
+ * @position packages/cli/foundation/integrations — shared contribution validators
+ */
+
+import * as fs from 'node:fs';
+import {discoverIntegrationCodemods} from '../../assets/codemods/integration-discovery.mjs';
+import {discoverIntegrationTemplatesForOne} from '../discovery/template-adapter.mjs';
+import * as componentDiscovery from '../discovery/component-discovery.mjs';
+
+/**
+ * @typedef {import('./issue').AstryxIntegrationIssue} Issue
+ * @typedef {import('./integrations.mjs').LoadedIntegration} LoadedIntegration
+ */
+
+/** @param {string} code @param {string} message @returns {Issue} */
+export function issueError(code, message) {
+  return {code, severity: 'error', message};
+}
+
+/**
+ * Verify each declared contribution root exists on disk. A declared-but-missing
+ * root is a `missing_root` error.
+ * @param {{components?: string, templates?: string, codemods?: string}} resolved
+ *   absolute resolved roots (undefined when not declared)
+ * @param {Issue[]} issues
+ */
+function checkRoots(resolved, issues) {
+  const kinds = /** @type {const} */ (['components', 'templates', 'codemods']);
+  for (const kind of kinds) {
+    const root = resolved[kind];
+    if (root == null) continue;
+    if (!fs.existsSync(root)) {
+      issues.push(
+        issueError(
+          'missing_root',
+          `Declared ${kind} root does not exist on disk: ${root}`,
+        ),
+      );
+    }
+  }
+}
+
+/**
+ * Validate the integration's codemods via the landed discovery. Discovery is
+ * strict (throws on bad export / duplicate id); we convert any throw into an
+ * `invalid_codemod` error.
+ * @param {LoadedIntegration} integration loaded-integration-shaped object
+ * @param {Issue[]} issues
+ */
+async function checkCodemods(integration, issues) {
+  if (!integration.codemods || !fs.existsSync(integration.codemods)) return;
+  try {
+    await discoverIntegrationCodemods([integration]);
+  } catch (err) {
+    issues.push(issueError('invalid_codemod', /** @type {any} */ (err).message));
+  }
+}
+
+/**
+ * Validate the integration's templates via the landed discovery. Per-template
+ * problems are reported as `invalid_template` errors.
+ * @param {LoadedIntegration} integration loaded-integration-shaped object
+ * @param {Issue[]} issues
+ */
+async function checkTemplates(integration, issues) {
+  if (!integration.templates || !fs.existsSync(integration.templates)) return;
+  try {
+    const {errors} = await discoverIntegrationTemplatesForOne(integration);
+    for (const e of errors) {
+      issues.push(issueError('invalid_template', e.message));
+    }
+  } catch (err) {
+    issues.push(issueError('invalid_template', /** @type {any} */ (err).message));
+  }
+}
+
+/**
+ * Validate the integration's components via the landed ownership discovery.
+ * Feature-detected: if the component-ownership export isn't present in this
+ * build (sibling PR not yet merged), component validation is skipped rather
+ * than hard-failing.
+ *
+ * `discoverIntegrationComponents` returns ownership records and does not throw
+ * on a missing same-stem source — it records `sourcePath: null`. We surface
+ * each such record as an `invalid_component` error.
+ * @param {LoadedIntegration} integration loaded-integration-shaped object
+ * @param {Issue[]} issues
+ */
+async function checkComponents(integration, issues) {
+  if (!integration.components || !fs.existsSync(integration.components)) return;
+  const discover = componentDiscovery.discoverIntegrationComponents;
+  if (typeof discover !== 'function') return; // feature not present yet
+  try {
+    const records = (await discover(integration)) ?? [];
+    for (const record of records) {
+      if (record?.sourcePath == null) {
+        issues.push(
+          issueError(
+            'invalid_component',
+            `Component "${record?.name}" is missing its same-stem source file ${record?.name}.tsx.`,
+          ),
+        );
+      }
+    }
+  } catch (err) {
+    issues.push(issueError('invalid_component', /** @type {any} */ (err).message));
+  }
+}
+
+/**
+ * Run every contribution validator against a loaded-integration-shaped object.
+ * @param {LoadedIntegration} integration
+ * @param {Issue[]} issues
+ */
+async function runContributionChecks(integration, issues) {
+  await checkCodemods(integration, issues);
+  await checkTemplates(integration, issues);
+  await checkComponents(integration, issues);
+}
+
+/**
+ * Validate an already-LOADED integration (as produced by `loadIntegrations` —
+ * absolute contribution roots plus identity) and return its issues. This is the
+ * reuse seam for everyday commands that have already loaded the configured
+ * integrations and want the SAME validators that `validate-integration` runs,
+ * without re-resolving the manifest from disk.
+ *
+ * @param {LoadedIntegration} loaded loaded-integration-shaped object
+ * @returns {Promise<Issue[]>}
+ */
+export async function validateLoadedIntegration(loaded) {
+  /** @type {Issue[]} */
+  const issues = [];
+  if (!loaded || typeof loaded !== 'object') return issues;
+  checkRoots(
+    {
+      components: loaded.components,
+      templates: loaded.templates,
+      codemods: loaded.codemods,
+    },
+    issues,
+  );
+  await runContributionChecks(loaded, issues);
+  return issues;
+}

package/foundation/response/error-codes.d.mts

@@ -0,0 +1,103 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Type guard: is `value` one of the known error codes?
+ * @param {unknown} value
+ * @returns {value is ErrorCode}
+ */
+export function isErrorCode(value: unknown): value is ErrorCode;
+/**
+ * All error code string values, sorted. Handy for tests and tooling.
+ * @returns {string[]}
+ */
+export function allErrorCodes(): string[];
+/**
+ * @file Astryx CLI — stable machine-readable error codes.
+ *
+ * ## Why codes exist
+ *
+ * The JSON error envelope (see json.mjs) carries a human-readable `error`
+ * string. That string is for people. It changes whenever we improve the
+ * wording, add detail, or localize. AI agents and CI scripts that consume
+ * `xds --json` must NOT branch on prose — string-matching "No component
+ * named X" is brittle and silently breaks the moment we reword it.
+ *
+ * The `code` field is the stable contract. Every error — whether raised by a
+ * command, the API layer (`AstryxError`), or Commander's own parse machinery —
+ * carries one of the identifiers below. Codes are append-only: once shipped,
+ * a code's meaning never changes and the code is never removed. The message
+ * may change freely; the code never does.
+ *
+ * ## Naming
+ *
+ * `ERR_<SUBJECT>[_<QUALIFIER>]`, SCREAMING_SNAKE_CASE, always prefixed
+ * `ERR_`. Group by subject (component, hook, docs, template, theme, …).
+ *
+ * ## Usage
+ *
+ *   import {ERROR_CODES} from './error-codes.mjs';
+ *   cliError('No component named "Buton"', {code: ERROR_CODES.ERR_UNKNOWN_COMPONENT});
+ *   throw new AstryxError('No component named "Buton"', suggestions, ERROR_CODES.ERR_UNKNOWN_COMPONENT);
+ *
+ * Consumers read `envelope.code` and compare against the published list in
+ * packages/cli/README.md.
+ */
+/**
+ * Stable error-code string union. Append-only.
+ *
+ * @typedef {(
+ *   | 'ERR_UNKNOWN'
+ *   | 'ERR_UNKNOWN_COMMAND'
+ *   | 'ERR_UNKNOWN_SUBCOMMAND'
+ *   | 'ERR_INVALID_OPTION'
+ *   | 'ERR_INVALID_ARGUMENT'
+ *   | 'ERR_MISSING_ARGUMENT'
+ *   | 'ERR_INVALID_LANG'
+ *   | 'ERR_INVALID_DETAIL'
+ *   | 'ERR_NODE_VERSION'
+ *   | 'ERR_CORE_NOT_FOUND'
+ *   | 'ERR_UNKNOWN_COMPONENT'
+ *   | 'ERR_UNKNOWN_HOOK'
+ *   | 'ERR_UNKNOWN_TOPIC'
+ *   | 'ERR_UNKNOWN_SECTION'
+ *   | 'ERR_UNKNOWN_CATEGORY'
+ *   | 'ERR_UNKNOWN_TEMPLATE'
+ *   | 'ERR_AMBIGUOUS_TEMPLATE'
+ *   | 'ERR_AMBIGUOUS_COMPONENT'
+ *   | 'ERR_UNKNOWN_THEME'
+ *   | 'ERR_UNKNOWN_PACKAGE'
+ *   | 'ERR_UNKNOWN_AGENT'
+ *   | 'ERR_UNKNOWN_FEATURE'
+ *   | 'ERR_UNKNOWN_CODEMOD'
+   | 'ERR_CODEMOD_FAILED'
+ *   | 'ERR_NOT_FOUND'
+ *   | 'ERR_NO_DOC'
+ *   | 'ERR_NO_SHOWCASE'
+ *   | 'ERR_NO_SOURCE'
+ *   | 'ERR_INVALID_DOC'
+ *   | 'ERR_FILE_NOT_FOUND'
+ *   | 'ERR_FILE_EXISTS'
+ *   | 'ERR_PATH_TRAVERSAL'
+ *   | 'ERR_WRITE_FAILED'
+ *   | 'ERR_THEME_INVALID'
+ *   | 'ERR_THEME_LOAD'
+ *   | 'ERR_VERSION_DETECT'
+ *   | 'ERR_INVALID_VERSION'
+ *   | 'ERR_DEP_MISSING'
+ *   | 'ERR_GH_CLI'
+ *   | 'ERR_UNKNOWN_POST'
+ *   | 'ERR_FETCH_FAILED'
+ *   | 'ERR_LAYOUT_PARSE'
+ *   | 'ERR_LAYOUT_INVALID'
+ * )} ErrorCode
+ */
+/**
+ * The complete, frozen set of Astryx CLI error codes. Append-only.
+ * @type {Readonly<Record<ErrorCode, ErrorCode>>}
+ */
+export const ERROR_CODES: Readonly<Record<ErrorCode, ErrorCode>>;
+/**
+ * Stable error-code string union. Append-only.
+ */
+export type ErrorCode = ("ERR_UNKNOWN" | "ERR_UNKNOWN_COMMAND" | "ERR_UNKNOWN_SUBCOMMAND" | "ERR_INVALID_OPTION" | "ERR_INVALID_ARGUMENT" | "ERR_MISSING_ARGUMENT" | "ERR_INVALID_LANG" | "ERR_INVALID_DETAIL" | "ERR_NODE_VERSION" | "ERR_CORE_NOT_FOUND" | "ERR_UNKNOWN_COMPONENT" | "ERR_UNKNOWN_HOOK" | "ERR_UNKNOWN_TOPIC" | "ERR_UNKNOWN_SECTION" | "ERR_UNKNOWN_CATEGORY" | "ERR_UNKNOWN_TEMPLATE" | "ERR_AMBIGUOUS_TEMPLATE" | "ERR_AMBIGUOUS_COMPONENT" | "ERR_UNKNOWN_THEME" | "ERR_UNKNOWN_PACKAGE" | "ERR_UNKNOWN_AGENT" | "ERR_UNKNOWN_FEATURE" | "ERR_UNKNOWN_CODEMOD" | "ERR_CODEMOD_FAILED" | "ERR_NOT_FOUND" | "ERR_NO_DOC" | "ERR_NO_SHOWCASE" | "ERR_NO_SOURCE" | "ERR_INVALID_DOC" | "ERR_FILE_NOT_FOUND" | "ERR_FILE_EXISTS" | "ERR_PATH_TRAVERSAL" | "ERR_WRITE_FAILED" | "ERR_THEME_INVALID" | "ERR_THEME_LOAD" | "ERR_VERSION_DETECT" | "ERR_INVALID_VERSION" | "ERR_DEP_MISSING" | "ERR_GH_CLI" | "ERR_UNKNOWN_POST" | "ERR_FETCH_FAILED" | "ERR_LAYOUT_PARSE" | "ERR_LAYOUT_INVALID");

package/foundation/response/error-codes.doc.d.mts

@@ -0,0 +1,11 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file EnumDoc for the CLI's stable error-code taxonomy. Colocated with the
+ * source of truth it documents (`error-codes.mjs`); the member set must stay in
+ * lockstep with ERROR_CODES — a drift test enforces that the two match exactly.
+ * @position packages/cli/foundation/response — enum documentation
+ */
+/** @type {import('@astryxdesign/cli/authoring').EnumDoc} */
+export const doc: import("@astryxdesign/cli/authoring").EnumDoc;

package/foundation/response/json.d.mts

@@ -0,0 +1,75 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Enable/disable JSON mode globally. Called once from index.mjs as soon as
+ * the root options are known (preAction), before any command body runs.
+ * @param {boolean} on
+ */
+export function setJsonMode(on: boolean): void;
+/** @returns {boolean} */
+export function isJsonMode(): boolean;
+/**
+ * Human-facing output that is automatically suppressed in --json mode.
+ *
+ * This is the stdout-discipline primitive: instead of scattering
+ * `if (!json) console.log(...)` across commands (easy to forget, and one
+ * miss corrupts the JSON), route all human chatter through humanLog. In JSON
+ * mode it is a no-op, guaranteeing stdout carries only the JSON envelope.
+ *
+ * @param {...unknown} args
+ */
+export function humanLog(...args: unknown[]): void;
+/**
+ * Human-facing stderr (warnings, hints). Also suppressed in JSON mode so a
+ * stray warning can't interleave with piped output. Use jsonError for real
+ * errors that must reach a JSON consumer.
+ * @param {...unknown} args
+ */
+export function humanWarn(...args: unknown[]): void;
+/**
+ * Output a JSON response envelope and mark it handled.
+ *
+ * Structural serializer: pass a command/API result straight through as
+ * `{type, data, meta?}`. There is no central response union — the correctness
+ * of the `type` discriminator is guaranteed at each API function's `@returns`
+ * (that's the fractal source-of-truth point), not by a map in this file.
+ *
+ * @param {{type: string, data: unknown, meta?: Record<string, unknown>}} response
+ * @returns {void}
+ */
+export function jsonOut(response: {
+    type: string;
+    data: unknown;
+    meta?: Record<string, unknown>;
+}): void;
+/**
+ * Build a structured error envelope without emitting it. Used by the bin
+ * error boundary to convert an uncaught throw into the contract's error
+ * shape.
+ *
+ * The `code` is resolved in priority order: an explicit `code` argument,
+ * then a `code` property carried on a thrown Error/AstryxError, then the
+ * generic `ERR_UNKNOWN` fallback. It always appears on the envelope so
+ * consumers can branch on it unconditionally.
+ *
+ * @param {unknown} err
+ * @param {import('./base').Suggestion[]} [suggestions]
+ * @param {string} [code] - Explicit stable error code. Overrides any code
+ *   carried on a thrown Error.
+ * @returns {{apiVersion: number, error: string, code: string, suggestions?: import('./base').Suggestion[]}}
+ */
+export function toErrorEnvelope(err: unknown, suggestions?: import("./base").Suggestion[], code?: string): {
+    apiVersion: number;
+    error: string;
+    code: string;
+    suggestions?: import("./base").Suggestion[];
+};
+/**
+ * Output a structured JSON error and exit.
+ * @param {string} message
+ * @param {import('./base').Suggestion[]} [suggestions]
+ * @param {string} [code] - Stable machine-readable error code (error-codes.mjs).
+ */
+export function jsonError(message: string, suggestions?: import("./base").Suggestion[], code?: string): void;
+export const API_VERSION: 1;

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

@@ -0,0 +1,12 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @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.
+ * @position packages/cli/foundation/response — enum documentation
+ */
+/** @type {import('@astryxdesign/cli/authoring').EnumDoc} */
+export const doc: import("@astryxdesign/cli/authoring").EnumDoc;

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

@@ -0,0 +1,11 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file SchemaDoc for the Astryx CLI JSON output envelope (the `astryx --json`
+ * contract). Colocated with the serializer (`json.mjs`) and shared types
+ * (`base.d.ts`) it documents.
+ * @position packages/cli/foundation/response — schema documentation
+ */
+/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
+export const doc: import("@astryxdesign/cli/authoring").SchemaDoc;

package/foundation/text/levenshtein.d.mts

@@ -0,0 +1,21 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * @file Levenshtein edit distance — pure, dependency-free.
+ *
+ * Lives apart from string-utils.mjs (which dynamically imports node:fs/path
+ * for component search) so browser-bundled code — the XLE/XLO layout
+ * language — can use fuzzy matching without dragging node: schemes into the
+ * webpack graph.
+ *
+ * @input  two strings
+ * @output edit distance (number)
+ * @position lib — shared by string-utils.mjs and lib/xle/validate.mjs
+ */
+/**
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+export function levenshteinDistance(a: string, b: string): number;

package/foundation/text/string-utils.d.mts

@@ -0,0 +1,43 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Find the closest component names to a given (possibly misspelled) name.
+ * Returns matches sorted by distance, filtered to maxDistance.
+ * @param {string} name
+ * @param {Record<string, string[]>} components
+ * @param {number} [maxDistance]
+ * @returns {{name: string, distance: number}[]}
+ */
+export function findClosestComponents(name: string, components: Record<string, string[]>, maxDistance?: number): {
+    name: string;
+    distance: number;
+}[];
+/**
+ * Unified component search that scores matches across multiple signals:
+ * name similarity, keyword matches, and description/feature text search.
+ *
+ * Always returns results (top 5 minimum). Scores determine confidence:
+ *   100  exact name match
+ *    90  exact keyword match
+ *    80  name Levenshtein distance 1
+ *    70  keyword substring or Levenshtein distance 1
+ *    60  substring match on component name (min 4 chars, 50%+ coverage)
+ *    50  description or feature text contains the search term
+ *    40  name Levenshtein distance 2
+ *    30  keyword Levenshtein distance 2
+ *    20  name Levenshtein distance 3
+ *
+ * Each result: { name, score, reason }
+ *
+ * @param {string} needle
+ * @param {string} coreDir
+ * @param {Record<string, string[]>} components
+ * @returns {Promise<{name: string, score: number, reason: string}[]>}
+ */
+export function searchComponents(needle: string, coreDir: string, components: Record<string, string[]>): Promise<{
+    name: string;
+    score: number;
+    reason: string;
+}[]>;
+export { levenshteinDistance } from "./levenshtein.mjs";

package/foundation/xle/browser.d.mts

@@ -0,0 +1,89 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * 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
+ * @param {object} [opts]
+ * @param {import('./browser').XLEBlock[]} [opts.blocks] - block list for {hint} resolution (default [])
+ * @param {'compact'|'outline'|'auto'} [opts.form]
+ * @param {boolean} [opts.loose]
+ * @returns {import('./browser').CheckResult}
+ */
+export function checkExpression(expression: string, registry: import("./xle-ast").Registry | import("./browser").SerializedRegistry | object, opts?: {
+    blocks?: import("./browser").XLEBlock[] | undefined;
+    form?: "compact" | "outline" | "auto" | undefined;
+    loose?: boolean | undefined;
+}): import("./browser").CheckResult;
+/**
+ * Validate + expand to TSX — the browser twin of `layout expand`.
+ * Returns either {code, ...} or {errors} (never writes files).
+ *
+ * @param {string} expression
+ * @param {import('./xle-ast').Registry | import('./browser').SerializedRegistry | object} registry
+ * @param {object} [opts]
+ * @param {import('./browser').XLEBlock[]} [opts.blocks]
+ * @param {'compact'|'outline'|'auto'} [opts.form]
+ * @param {boolean} [opts.loose]
+ * @param {string} [opts.name] - generated component name (PascalCase)
+ * @param {Map<string, import('./xle-ast').BlockModule>} [opts.blockModules] - prepared block sources/imports for splicing;
+ *   omit in the browser (hints stay as TODO markers without sources)
+ */
+export function expandExpression(expression: string, registry: import("./xle-ast").Registry | import("./browser").SerializedRegistry | object, opts?: {
+    blocks?: import("./browser").XLEBlock[] | undefined;
+    form?: "compact" | "outline" | "auto" | undefined;
+    loose?: boolean | undefined;
+    name?: string | undefined;
+    blockModules?: Map<string, import("./xle-ast").BlockModule> | undefined;
+}): {
+    ok: boolean;
+    errors: {
+        message: string;
+        line: number;
+        col: number;
+        formatted: string;
+        kind: string;
+    }[];
+    form?: undefined;
+    code?: undefined;
+    componentsUsed?: undefined;
+    states?: undefined;
+    todos?: undefined;
+    warnings?: undefined;
+} | {
+    ok: boolean;
+    errors: {
+        formatted: string;
+        message: string;
+        line?: number;
+        col?: number;
+        suggestions?: string[];
+    }[];
+    form?: undefined;
+    code?: undefined;
+    componentsUsed?: undefined;
+    states?: undefined;
+    todos?: undefined;
+    warnings?: undefined;
+} | {
+    ok: boolean;
+    form: "compact" | "outline";
+    code: string;
+    componentsUsed: string[];
+    states: number;
+    todos: string[];
+    warnings: string[];
+    errors?: undefined;
+};
+import { parse } from './parse.mjs';
+import { detectForm } from './parse.mjs';
+import { XLEParseError } from './parse.mjs';
+import { validate } from './validate.mjs';
+import { expand } from './expand.mjs';
+import { toCompact } from './print.mjs';
+import { toOutline } from './print.mjs';
+export { parse, detectForm, XLEParseError, validate, expand, toCompact, toOutline };
+export { hydrateRegistry, serializeRegistry, ALIAS_TABLE, resolveComponent, SPACING_STEPS } from "./registry-core.mjs";

package/foundation/xle/expand.d.mts

@@ -0,0 +1,23 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Expand a validated document into a complete TSX module.
+ *
+ * @param {{roots: import('./xle-ast').XLEItem[], overlays: import('./xle-ast').XLEItem[]}} doc
+ * @param {import('./xle-ast').Registry} registry
+ * @param {{componentName?: string, blockModules?: Map<string, import('./xle-ast').BlockModule>}} [options]
+ * @returns {{code: string, componentsUsed: string[], states: number, todos: string[]}}
+ */
+export function expand(doc: {
+    roots: import("./xle-ast").XLEItem[];
+    overlays: import("./xle-ast").XLEItem[];
+}, registry: import("./xle-ast").Registry, options?: {
+    componentName?: string;
+    blockModules?: Map<string, import("./xle-ast").BlockModule>;
+}): {
+    code: string;
+    componentsUsed: string[];
+    states: number;
+    todos: string[];
+};