Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
76.3 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file Shared template discovery + IO.
 *
 * Owns everything the template leaves (list/show/skeleton/copy) AND other
 * commands (component, layout, search, init, discover, Doctor integration)
 * share: template discovery across core/external/integration sources, the
 * template-spec loaders, and the cross-command helpers (stripTemplateAssetRefs,
 * findShowcase, findRelatedBlocks, extractComponents, listTemplates). The
 * `api/template/template.mjs` barrel re-exports the public helpers so external
 * import paths keep working unchanged.
 *
 * Lives in foundation rather than under api/template because foundation itself
 * needs it: `Project` assembles templates from it. While this sat in api/, that
 * made a cycle across the layer boundary — Project reached up for discovery and
 * this module imported Project back. Nothing here depends on api/; every import
 * is node:*, jiti, foundation/*, or authoring/*, plus a lazily required
 * @babel/parser for extractComponents' local-declaration scan.
 *
 * @position packages/cli/foundation/discovery — shared template discovery/IO;
 *   consumed by Project and by the api/template leaves.
 */

import * as fs from 'node:fs';
import * as path from 'node:path';
import {createRequire} from 'node:module';
import {readDocView} from '../doc-compiler/read.mjs';
import {importDocModule} from '../doc-compiler/import.mjs';
import {CLI_ROOT, discoverExternalPackages} from '../fs/paths.mjs';
import {listDirEntries} from '../fs/listing-cache.mjs';
import {CORE_PROVIDER_ID} from '../identity/providers.mjs';
import {Project} from '../config/project.mjs';
import {
  isReference,
  parseTemplateSource,
  programPath,
  traverseTemplateSource,
  writtenNames,
} from './template-source-tree.mjs';

const require = createRequire(import.meta.url);

/** Identity used for core (built-in) templates in package-scoped listings. */
const CORE_PACKAGE = CORE_PROVIDER_ID;

/**
 * Identity for a template in package-scoped views. Core (built-in) templates
 * have no `package` field; report them under @astryxdesign/core.
 * @param {{package?: string}} t
 * @returns {string}
 */
export function pkgOf(t) {
  return t.package ?? CORE_PACKAGE;
}

/**
 * Every id that should resolve to a discovered template. Replacements keep
 * their own integration id and also own the Core id they replace.
 * @param {{dirName: string, replaces?: string}} template
 * @returns {string[]}
 */
export function templateLookupIds(template) {
  if (template.replaces && template.replaces !== template.dirName) {
    return [template.dirName, template.replaces];
  }
  return [template.dirName];
}

/**
 * Remove entries shadowed in the default discovery view while retaining them in
 * package-scoped views. An active replacement owns its target id. A rejected
 * same-id declaration falls back to Core when a Core template of the same kind
 * owns that id; otherwise the integration template remains available by kind.
 * @param {DiscoveredTemplate[]} templates
 * @returns {DiscoveredTemplate[]}
 */
export function effectiveTemplateDiscovery(templates) {
  const activeTargets = new Set(
    templates
      .filter(template => template.replaces != null)
      .map(template => `${template.type}:${template.replaces}`),
  );
  const coreIds = new Set(
    templates
      .filter(template => pkgOf(template) === CORE_PACKAGE)
      .map(template => `${template.type}:${template.dirName}`),
  );
  return templates.filter(template => {
    if (
      template.replacementRejected &&
      template.replacementTarget === template.dirName &&
      coreIds.has(`${template.type}:${template.dirName}`)
    ) {
      return false;
    }
    return (
      !activeTargets.has(`${template.type}:${template.dirName}`) ||
      template.replaces != null
    );
  });
}

/**
 * A discovered template (page or block), normalized across core, external, and
 * integration sources. Not every source populates every field, so
 * source-specific extras (`aspectRatio`, `isShowcase`, `package`) are optional.
 * @typedef {object} DiscoveredTemplate
 * @property {'page'|'block'} type
 * @property {string} dirName
 * @property {string} name
 * @property {string} [displayName]
 * @property {string} description
 * @property {string[]} [keywords]
 * @property {string} [category]
 * @property {boolean} [isReady]
 * @property {boolean} [scaffold]
 * @property {number} [aspectRatio]
 * @property {string} [exampleFor]
 * @property {string[]} [alsoExampleFor]
 * @property {string[]} [alsoShowcaseFor]
 * @property {string[]} [componentsUsed]
 * @property {Record<string, string>} [icons] the icon definition each
 *   imported icon draws, by its imported name
 * @property {boolean} [isShowcase]
 * @property {string} filePath
 * @property {string} docPath
 * @property {string} [package]
 * @property {boolean} [autolinked] whether the owning integration was discovered
 *   from package.json rather than named in astryx.config
 * @property {string} [replaces] active Core template id this integration template replaces
 * @property {boolean} [replacementRejected] whether an invalid declaration was disabled
 * @property {string} [replacementTarget] disabled declaration target
 */

/**
 * An integration-template discovery error.
 * @typedef {object} TemplateDiscoveryError
 * @property {string} package
 * @property {string} [template]
 * @property {string} message
 * @property {string} [code]
 * @property {'warning' | 'error'} [severity]
 * @property {string} [replacementTarget] Core target whose replacement set is invalid
 * @property {boolean} [autolinked] whether the declaration came from an autolinked integration
 */

/**
 * A semantic error in an integration template replacement declaration.
 * @typedef {TemplateDiscoveryError & {code: 'missing_template_replacement_target' | 'ambiguous_template_replacement' | 'invalid_template_replacement', severity: 'warning' | 'error'}} TemplateReplacementError
 */

/**
 * The loaded metadata object from a template spec (loose — authored shape).
 * @typedef {Record<string, any> | undefined | null} TemplateDocModule
 */

/**
 * Released compatibility suffixes, in precedence order. Stable 0.6.0
 * documented `.template.*`, so discovery keeps reading those files while all
 * new authoring uses `.doc.mjs`.
 */
const TEMPLATE_SUFFIXES = ['.template.ts', '.template.mjs', '.template.js'];

/**
 * Descriptor suffixes for templates, in precedence order. New authoring always
 * emits `.doc.mjs`; the TypeScript and JavaScript variants remain readable.
 */
const DOC_SUFFIXES = ['.doc.ts', '.doc.mjs', '.doc.js'];

/**
 * Every template-spec suffix, in the released precedence a core page directory
 * uses to pick one file. Integration discovery never picks: every match is a
 * template, so two specs for one stem list twice and read as ambiguous.
 */
const ALL_TEMPLATE_SUFFIXES = [...TEMPLATE_SUFFIXES, ...DOC_SUFFIXES];

/**
 * The template-spec suffix present on `file`, or null if none matches.
 * Recognizes both the canonical `.doc.*` and released `.template.*` families.
 * @param {string} file
 * @returns {string | null}
 */
function matchedTemplateSuffix(file) {
  return ALL_TEMPLATE_SUFFIXES.find(suffix => file.endsWith(suffix)) ?? null;
}

/**
 * RegExp matching either template-spec suffix family at end of a basename.
 * Used where a per-file regex is convenient (e.g. block discovery walks).
 */
const TEMPLATE_SUFFIX_RE = /\.(template|doc)\.(ts|mjs|js)$/;

/**
 * Load an integration template doc module and validate it against the template
 * envelope at the load boundary. Default export only — `.ts` via jiti,
 * `.mjs`/`.js` via dynamic import. Throws (caught by discovery) if the default
 * export is missing or fails {@link parseTemplate}. NOTE: the built-in
 * core templates use `export const doc = {...}` and are loaded by a different
 * function ({@link loadDocModule}) — this path is for INTEGRATION templates.
 *
 * @param {string} file
 * @param {string} [label]
 */
async function loadIntegrationDoc(file, label) {
  return readDocView(file, {
    root: 'templates',
    exports: ['default'],
    label: label ?? file,
    strict: true,
    value: 'parsed',
  });
}

const TEMPLATES_DIR = path.join(CLI_ROOT, 'assets', 'templates');
const PAGES_DIR = path.join(TEMPLATES_DIR, 'pages');
const BLOCKS_DIR = path.join(TEMPLATES_DIR, 'blocks');

/**
 * Inline placeholder swapped in for demo imagery when scaffolding a template,
 * so scaffolded pages render with zero setup (see stripTemplateAssetRefs).
 * Neutral hex colors (not design tokens) so it renders in any project, themed
 * or not. Mirrors apps/docsite/public/template-assets/placeholder.svg.
 */
const PLACEHOLDER_IMAGE =
  'data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%20400%20300%22%20preserveAspectRatio%3D%22xMidYMid%20slice%22%3E%3Crect%20width%3D%22400%22%20height%3D%22300%22%20fill%3D%22%23f5f6f8%22%2F%3E%3Cg%20transform%3D%22translate%28200%20150%29%22%20fill%3D%22none%22%20stroke%3D%22%23c2cad6%22%20stroke-width%3D%225%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%3E%3Crect%20x%3D%22-44%22%20y%3D%22-44%22%20width%3D%2288%22%20height%3D%2288%22%20rx%3D%2216%22%2F%3E%3Ccircle%20cx%3D%2218%22%20cy%3D%22-18%22%20r%3D%222.5%22%20fill%3D%22%23c2cad6%22%20stroke%3D%22none%22%2F%3E%3Cpath%20d%3D%22M-34%2030%20L-8%200%20L10%2018%20L20%208%20L34%2024%22%2F%3E%3C%2Fg%3E%3C%2Fsvg%3E';

/**
 * Extensions that need a video-safe placeholder rather than the image data
 * URI (see stripTemplateAssetRefs). There's no equivalent self-contained
 * inline placeholder for video: unlike an SVG data URI, a `<video src>`
 * needs actual encoded media, and hand-authoring a valid tiny MP4/WebM
 * blob isn't something we can do reliably here — an unverifiable, possibly
 * still-broken binary would just trade one silent failure for another.
 * Rather than mis-render image data as video (the original bug) or guess at
 * binary bytes, video sources are stripped to an empty string so the
 * scaffolded example is honest about needing the builder to supply their
 * own file, instead of silently pointing at something that can't play.
 *
 * @type {Set<string>}
 */
const VIDEO_EXTENSIONS = new Set(['mp4', 'webm', 'mov', 'ogv', 'm4v']);

/**
 * A video placeholder that names itself in the source, for a copy that has no
 * response to disclose the replacement in, such as the shadcn install. It is a
 * text data URL: it makes no request, it does not play, and it is not image
 * data, so a video element never receives image bytes.
 */
export const MARKED_VIDEO_PLACEHOLDER = 'data:,placeholder-video-add-your-own';

const IMAGE_EXTENSIONS = new Set([
  'svg',
  'png',
  'jpg',
  'jpeg',
  'gif',
  'webp',
  'avif',
  'ico',
]);

/**
 * First path segment of every Astryx template fixture. Template demo imagery
 * is self-hosted under the docsite's `/template-assets/*` dir (committed there,
 * mirrored into the sandbox preview by scripts/sync-templates.js), so those
 * paths only resolve inside the Astryx docsite/sandbox and are replaced on
 * scaffold. Only a root-relative URL whose first segment this is counts: the
 * same text inside a third-party URL or a product path is left untouched.
 */
const FIXTURE_SEGMENT = 'template-assets';

/** Characters that end a URL token in template source, besides whitespace. */
const TOKEN_DELIMITERS = new Set([
  "'",
  '"',
  '`',
  '(',
  ')',
  '<',
  '>',
  '{',
  '}',
  '[',
  ']',
  '\\',
  '|',
  '^',
]);

/** The closing delimiter each opening delimiter must pair with. */
const CLOSING_DELIMITERS = new Map([
  ["'", "'"],
  ['"', '"'],
  ['`', '`'],
  ['(', ')'],
]);
const CLOSERS = new Set(CLOSING_DELIMITERS.values());

/** A URL with a scheme: absolute, so never a fixture reference. */
const ABSOLUTE_URL = /^[a-z][a-z\d+.-]*:/iu;

/** What may lead up to the fixture segment inside a relative product path. */
const RELATIVE_PATH_PREFIX = /^[\w.~%@/-]+$/u;

/** Punctuation that ends a sentence or list item after a path in text. */
const PROSE_PUNCTUATION = new Set(['.', ',', ';', ':', '!', '?']);

/** `from`, `import` or `require` right before a quoted module specifier. */
const MODULE_SPECIFIER_LEAD = /(?:^|[^\w$])(?:from|import|require)\s*\(?$/u;

/**
 * Normalize path into Unix path (using forward slashes) for consistent comparison
 * across Windows, macOS, and Linux.
 *
 * @param {string} p - The file path to normalize.
 * @returns {string} The normalized Unix path.
 */
function toPosixPath(p) {
  return p.replace(/\\/g, '/');
}

/**
 * Replace each Astryx template fixture reference with a placeholder so
 * scaffolded pages render with zero setup. Images get a self-contained data
 * URI; videos (which have no equivalent inline placeholder — see
 * VIDEO_EXTENSIONS) are stripped to an empty src instead of being
 * mis-replaced with image data. Builders drop in their own media either way.
 *
 * A reference is a URL token that resolves to a root-relative path under
 * FIXTURE_SEGMENT. It is replaced whole, query and fragment included, and
 * classified by the suffix of its last path segment. A reference that cannot
 * be replaced safely throws with its path rather than being guessed at or
 * left behind. Prose is left as written: in text (JSX text, a word inside a
 * longer string) trailing punctuation is not part of a path and a path with
 * no suffix, such as the bare directory, is a mention; inside a comment
 * nothing throws.
 *
 * @param {string} source - Template source code.
 * @returns {string} Source with demo asset references replaced.
 */
export function stripTemplateAssetRefs(source) {
  return replaceDemoMedia(source).source;
}

/**
 * {@link stripTemplateAssetRefs}, plus how many references it replaced: one per
 * replaced reference, however many fixture paths its URL carries (a reference
 * is replaced whole, query included), and none for a prose mention or a
 * third-party URL left as written. That count is what a receipt discloses.
 *
 * @param {string} source - Template source code.
 * @param {{videoPlaceholder?: string}} [options] - `videoPlaceholder` replaces
 *   each video reference; the default is an empty source.
 * @returns {{source: string, demoMediaReplaced: number}}
 */
export function replaceDemoMedia(source, {videoPlaceholder = ''} = {}) {
  const needle = `/${FIXTURE_SEGMENT}`;
  let output = '';
  let copied = 0;
  let demoMediaReplaced = 0;
  /** @type {Array<[number, number]> | undefined} */
  let comments;
  let at = source.indexOf(needle);
  while (at !== -1) {
    let start = at;
    while (start > 0 && !isTokenDelimiter(source[start - 1])) start--;
    let end = at + needle.length;
    while (end < source.length && !isTokenDelimiter(source[end])) end++;
    /** @type {{text: string, end: number} | null} */
    let edit;
    try {
      edit = fixtureEdit(source, start, at, end, videoPlaceholder);
    } catch (err) {
      comments ??= commentRanges(source);
      if (!comments.some(([from, to]) => from <= at && at < to)) throw err;
      edit = null;
    }
    if (edit) {
      output += source.slice(copied, start) + edit.text;
      copied = edit.end;
      demoMediaReplaced += 1;
    }
    at = source.indexOf(needle, end);
  }
  return {source: output + source.slice(copied), demoMediaReplaced};
}

/**
 * The one module docs-only demo content is imported from. A template imports
 * an element such as a playing card's face from here so its live preview shows
 * real-looking content; the module exists only where Astryx's own previews
 * build templates, so a copy replaces every element imported from it (see
 * {@link replaceDemoContent}).
 */
export const DEMO_CONTENT_MODULE = '@astryx-docs/demo-content';

/** What a demo-content element becomes in emitted source. */
const DEMO_CONTENT_PLACEHOLDER_TEXT = 'Card content';

/** Where emitted placeholders import Text from, as catalog templates do. */
const TEXT_MODULE = '@astryxdesign/core/Text';

/** The modules an existing Astryx Text import can come from. */
const TEXT_MODULES = new Set([TEXT_MODULE, '@astryxdesign/core']);

/** The local name a new Text import takes when the file already writes `Text`. */
const TEXT_ALIAS = 'AstryxText';

/**
 * Replace each JSX element imported from {@link DEMO_CONTENT_MODULE} with a
 * generic `<Text>` placeholder and remove that import, so emitted source never
 * depends on content only Astryx's previews provide. An element that wraps one
 * element, such as a hint shown under a demo, is removed instead: its child
 * takes its place, with the indentation the child would have had without it.
 * `demoContentReplaced` counts the placeholders, because only they need the
 * consumer's own content.
 *
 * Every check resolves a name to its binding through the module's scope, so a
 * local declaration or parameter with the same name never counts as the same
 * variable. The placeholder uses an existing Text import from Astryx when that
 * import is the binding its name resolves to at every replaced element. Else
 * the placeholder imports Text, under a unique alias when the file already
 * writes the name `Text`.
 *
 * Only a plain static use is replaced: a named import used only as a JSX tag
 * whose children are whitespace or one element, and whose props are literal values or
 * read only bindings that code outside the replaced elements still reads. So
 * `faceDown={!isOpen}` is safe when the same `isOpen` is also read elsewhere.
 * Anything else (a namespace or type import, a re-export, a dynamic import, the
 * element used as a value or a type, a spread or computed prop, a prop whose
 * binding nothing else reads, other children) throws, naming the element, rather than
 * leaving a reference behind, leaving a binding unused, or dropping code the
 * rest of the file relies on. Source that never names the module is returned
 * as is.
 *
 * @param {string} source - Template source code.
 * @returns {{source: string, demoContentReplaced: number}}
 */
export function replaceDemoContent(source) {
  if (!source.includes(DEMO_CONTENT_MODULE)) {
    return {source, demoContentReplaced: 0};
  }
  /** @type {any} */
  let file;
  try {
    file = parseTemplateSource(source);
  } catch (err) {
    throw unsafeDemoContent(
      `the source does not parse (${/** @type {Error} */ (err).message})`,
    );
  }

  /** @type {any[]} */
  const demoImports = [];
  for (const statement of file.program.body) {
    if (
      statement.type !== 'ImportDeclaration' ||
      statement.source.value !== DEMO_CONTENT_MODULE
    ) {
      continue;
    }
    if (statement.importKind === 'type') {
      throw unsafeDemoContent('it is imported as a type');
    }
    for (const specifier of statement.specifiers) {
      if (
        specifier.type !== 'ImportSpecifier' ||
        specifier.importKind === 'type'
      ) {
        throw unsafeDemoContent(
          'only named value imports can be replaced; import each element by name',
        );
      }
    }
    demoImports.push(statement);
  }

  const program = programPath(file);
  const demoBindings = new Set(
    demoImports.flatMap(statement =>
      statement.specifiers.map((/** @type {any} */ specifier) =>
        program.scope.getBinding(specifier.local.name),
      ),
    ),
  );
  /** The paths of the JSX elements to replace. */
  /** @type {any[]} */
  const elements = [];
  traverseTemplateSource(file, {
    StringLiteral(/** @type {any} */ path) {
      if (
        path.node.value === DEMO_CONTENT_MODULE &&
        !(path.parentPath.isImportDeclaration() && path.key === 'source')
      ) {
        throw unsafeDemoContent(
          'it is used outside a static import (a re-export, dynamic import, require, or string value)',
        );
      }
    },
    TemplateLiteral(/** @type {any} */ path) {
      if (
        path.node.quasis.some((/** @type {any} */ quasi) =>
          quasi.value.cooked?.includes(DEMO_CONTENT_MODULE),
        )
      ) {
        throw unsafeDemoContent('it is used outside a static import');
      }
    },
    'Identifier|JSXIdentifier'(/** @type {any} */ path) {
      const {node, parentPath} = path;
      if (!demoBindings.has(path.scope.getBinding(node.name))) return;
      if (!isReference(node, path.parent, path.listKey ?? path.key)) return;
      if (path.key === 'name' && parentPath.isJSXOpeningElement()) {
        elements.push(parentPath.parentPath);
        return;
      }
      if (path.key === 'name' && parentPath.isJSXClosingElement()) return;
      if (parentPath.isJSXMemberExpression()) {
        throw unsafeDemoContent(`${node.name} is used as a namespace`);
      }
      throw unsafeDemoContent(
        `${node.name} is used as a value, not only as a JSX element`,
      );
    },
  });

  const wrappers = elements.filter(
    element => wrappedElement(element.node) !== null,
  );
  if (wrappers.length > 0) {
    return replaceDemoContent(unwrapDemoWrappers(source, wrappers));
  }

  /** @param {any} node */
  const isReplaced = node =>
    elements.some(
      element =>
        element.node.start <= node.start && node.end <= element.node.end,
    );
  for (const element of elements) {
    for (const variable of assertStaticDemoElement(element.node)) {
      const binding = element.scope.getBinding(variable);
      // An unbound name is a global: removing its read leaves nothing unused.
      if (!binding || isExportedDeclaration(binding)) continue;
      if (
        binding.referencePaths.every((/** @type {any} */ ref) =>
          isReplaced(ref.node),
        )
      ) {
        throw unsafeDemoContent(
          `<${element.node.openingElement.name.name}> reads ${variable}, and nothing else in the file reads it, so the copy would leave it unused`,
        );
      }
    }
  }

  const reused =
    elements.length === 0 ? null : astryxTextAtEvery(file, program, elements);
  const written = writtenNames(file);
  const textName =
    reused ?? (written.has('Text') ? uniqueName(TEXT_ALIAS, written) : 'Text');
  const textImport =
    elements.length > 0 && reused === null
      ? `import {${textName === 'Text' ? 'Text' : `Text as ${textName}`}} from '${TEXT_MODULE}';\n`
      : '';
  const placeholder = `<${textName}>${DEMO_CONTENT_PLACEHOLDER_TEXT}</${textName}>`;

  /** @type {Array<{start: number, end: number, text: string}>} */
  const edits = elements.map(element => ({
    start: element.node.start,
    end: element.node.end,
    text: placeholder,
  }));
  demoImports.forEach((statement, index) => {
    let end = statement.end;
    if (source[end] === '\n') end += 1;
    edits.push({
      start: statement.start,
      end,
      text: index === 0 ? textImport : '',
    });
  });
  edits.sort((a, b) => b.start - a.start);
  let output = source;
  for (const edit of edits) {
    output = output.slice(0, edit.start) + edit.text + output.slice(edit.end);
  }
  return {source: output, demoContentReplaced: elements.length};
}

/**
 * The local name of an Astryx Text import that is the binding its name
 * resolves to at every element, or null when no such import exists.
 * @param {any} file
 * @param {any} program - The program path, from {@link programPath}.
 * @param {any[]} elements - Element paths.
 * @returns {string | null}
 */
function astryxTextAtEvery(file, program, elements) {
  for (const statement of file.program.body) {
    if (
      statement.type !== 'ImportDeclaration' ||
      statement.importKind === 'type' ||
      !TEXT_MODULES.has(statement.source.value)
    ) {
      continue;
    }
    for (const specifier of statement.specifiers) {
      if (
        specifier.type !== 'ImportSpecifier' ||
        specifier.importKind === 'type' ||
        (specifier.imported.name ?? specifier.imported.value) !== 'Text'
      ) {
        continue;
      }
      const name = specifier.local.name;
      const imported = program.scope.getBinding(name);
      if (
        elements.every(element => element.scope.getBinding(name) === imported)
      ) {
        return name;
      }
    }
  }
  return null;
}

/**
 * Whether a binding is declared in an export, so code outside the file can
 * still read it.
 * @param {any} binding
 */
function isExportedDeclaration(binding) {
  const declaration = binding.path.isVariableDeclarator()
    ? binding.path.parentPath
    : binding.path;
  return Boolean(declaration.parentPath?.isExportDeclaration());
}

/**
 * `base`, or `base` with the first number from 2 that makes it a name the
 * file does not write.
 * @param {string} base
 * @param {Set<string>} written
 */
function uniqueName(base, written) {
  let name = base;
  for (let n = 2; written.has(name); n++) name = `${base}${n}`;
  return name;
}

/**
 * Replace each outermost demo-content wrapper with the element it wraps.
 * Wrappers inside a kept child go on the next pass, when they are outermost.
 * Throws when a wrapper's prop reads a binding that nothing outside the
 * wrappers' opening tags reads, so the removal would leave it unused.
 * @param {string} source
 * @param {any[]} wrappers - Element paths whose element wraps one element.
 * @returns {string}
 */
function unwrapDemoWrappers(source, wrappers) {
  /** @param {any} node */
  const isInWrapperTag = node =>
    wrappers.some(
      wrapper =>
        wrapper.node.openingElement.start <= node.start &&
        node.end <= wrapper.node.openingElement.end,
    );
  for (const wrapper of wrappers) {
    for (const variable of staticPropReads(wrapper.node)) {
      const binding = wrapper.scope.getBinding(variable);
      if (!binding || isExportedDeclaration(binding)) continue;
      if (
        binding.referencePaths.every((/** @type {any} */ ref) =>
          isInWrapperTag(ref.node),
        )
      ) {
        throw unsafeDemoContent(
          `<${wrapper.node.openingElement.name.name}> reads ${variable}, and nothing else in the file reads it, so the copy would leave it unused`,
        );
      }
    }
  }
  const outermost = wrappers.filter(
    wrapper =>
      !wrappers.some(
        other =>
          other !== wrapper &&
          other.node.start <= wrapper.node.start &&
          wrapper.node.end <= other.node.end,
      ),
  );
  let output = source;
  for (const wrapper of outermost.sort((a, b) => b.node.start - a.node.start)) {
    output =
      output.slice(0, wrapper.node.start) +
      dedentedChild(source, wrapper) +
      output.slice(wrapper.node.end);
  }
  return output;
}

/**
 * The source of the element a wrapper holds, with each of its later lines
 * moved left by the indent the wrapper added. A line that starts inside a
 * string keeps its whitespace, because that whitespace is part of the value.
 * @param {string} source
 * @param {any} wrapper - An element path whose element wraps one element.
 * @returns {string}
 */
function dedentedChild(source, wrapper) {
  const child = /** @type {any} */ (wrappedElement(wrapper.node));
  /** @param {number} offset */
  const indentOfLine = offset => {
    const lineStart = source.lastIndexOf('\n', offset - 1) + 1;
    return /^[ \t]*/u.exec(source.slice(lineStart))?.[0].length ?? 0;
  };
  const depth = indentOfLine(child.start) - indentOfLine(wrapper.node.start);
  /** @type {any[]} */
  const strings = [];
  wrapper.traverse({
    'StringLiteral|TemplateLiteral'(/** @type {any} */ path) {
      strings.push(path.node);
    },
  });
  const leadingIndent = new RegExp(`^[ \\t]{0,${Math.max(depth, 0)}}`, 'u');
  let lineStart = child.start;
  return source
    .slice(child.start, child.end)
    .split('\n')
    .map((line, index) => {
      const start = lineStart;
      lineStart += line.length + 1;
      if (
        index === 0 ||
        strings.some(string => string.start < start && start < string.end)
      ) {
        return line;
      }
      return line.replace(leadingIndent, '');
    })
    .join('\n');
}

/**
 * The one element a demo-content element wraps, or null when its children are
 * only whitespace. Throws for any other children.
 * @param {any} element
 * @returns {any}
 */
function wrappedElement(element) {
  const content = element.children.filter(
    (/** @type {any} */ child) =>
      !(child.type === 'JSXText' && child.value.trim() === ''),
  );
  if (content.length === 0) return null;
  if (
    content.length === 1 &&
    (content[0].type === 'JSXElement' || content[0].type === 'JSXFragment')
  ) {
    return content[0];
  }
  throw unsafeDemoContent(
    `<${element.openingElement.name.name}> has children other than one element`,
  );
}

/**
 * Throw unless a demo-content element can be replaced without dropping code:
 * each prop a literal or a read of variables (see {@link staticPropReads}),
 * and no children but whitespace.
 * @param {any} element
 * @returns {string[]} The variables its props read.
 */
function assertStaticDemoElement(element) {
  const variables = staticPropReads(element);
  for (const child of element.children) {
    if (child.type === 'JSXText' && child.value.trim() === '') continue;
    throw unsafeDemoContent(
      `<${element.openingElement.name.name}> has children`,
    );
  }
  return variables;
}

/**
 * Throw unless each prop of a demo-content element is a literal or a read of
 * variables (see {@link isVariableRead}).
 * @param {any} element
 * @returns {string[]} The variables its props read.
 */
function staticPropReads(element) {
  const name = element.openingElement.name.name;
  /** @type {string[]} */
  const variables = [];
  for (const attribute of element.openingElement.attributes) {
    if (attribute.type === 'JSXSpreadAttribute') {
      throw unsafeDemoContent(`<${name}> spreads props`);
    }
    const value = attribute.value;
    if (value === null || value.type === 'StringLiteral') continue;
    if (
      value.type === 'JSXExpressionContainer' &&
      (isLiteralExpression(value.expression) ||
        isVariableRead(value.expression, variables))
    ) {
      continue;
    }
    throw unsafeDemoContent(
      `<${name}> prop ${attribute.name.name ?? ''} is not a literal value or a variable read`,
    );
  }
  return variables;
}

/**
 * Whether an expression only reads variables: a variable, a non-computed
 * property of one, or its negation. Removing such a read runs no code. Adds
 * each variable it reads to `variables`.
 * @param {any} node
 * @param {string[]} variables
 * @returns {boolean}
 */
function isVariableRead(node, variables) {
  switch (node.type) {
    case 'Identifier':
      variables.push(node.name);
      return true;
    case 'MemberExpression':
      return !node.computed && isVariableRead(node.object, variables);
    case 'UnaryExpression':
      return node.operator === '!' && isVariableRead(node.argument, variables);
    default:
      return false;
  }
}

/** @param {any} node */
function isLiteralExpression(node) {
  switch (node.type) {
    case 'StringLiteral':
    case 'NumericLiteral':
    case 'BooleanLiteral':
    case 'NullLiteral':
      return true;
    case 'TemplateLiteral':
      return node.expressions.length === 0;
    case 'UnaryExpression':
      return node.operator === '-' && node.argument.type === 'NumericLiteral';
    default:
      return false;
  }
}

/** @param {string} reason */
function unsafeDemoContent(reason) {
  return new Error(
    `Demo content from ${DEMO_CONTENT_MODULE} cannot be replaced safely: ${reason}. Use each element as a JSX tag with no children or with one element child, and give each prop a literal or a variable the file also reads elsewhere.`,
  );
}

/**
 * Replace everything in a template that only Astryx's previews provide, in
 * the order a copy applies it: demo-content elements
 * ({@link replaceDemoContent}), then demo media ({@link replaceDemoMedia}).
 * Both counts are what a receipt discloses.
 *
 * @param {string} source - Template source code.
 * @param {{videoPlaceholder?: string}} [options] - As {@link replaceDemoMedia}.
 * @returns {{source: string, demoContentReplaced: number, demoMediaReplaced: number}}
 */
export function replaceTemplateDemos(source, options) {
  const {source: withContent, demoContentReplaced} = replaceDemoContent(source);
  const {source: output, demoMediaReplaced} = replaceDemoMedia(
    withContent,
    options,
  );
  return {source: output, demoContentReplaced, demoMediaReplaced};
}

/** @param {string | undefined} char */
function isTokenDelimiter(char) {
  return char === undefined || /\s/u.test(char) || TOKEN_DELIMITERS.has(char);
}

/**
 * Whitespace, the source edge, or a tag bracket: what bounds a word of text.
 * @param {string | undefined} char
 */
function isTextDelimiter(char) {
  return char === undefined || /\s/u.test(char) || char === '<' || char === '>';
}

/**
 * The path segments of a root-relative URL under FIXTURE_SEGMENT, or null.
 * @param {string} reference
 * @returns {string[] | null}
 */
function fixtureSegments(reference) {
  if (!reference.startsWith('/') || reference.startsWith('//')) return null;
  const segments = new URL(reference, 'http://template.invalid').pathname.split(
    '/',
  );
  return segments[1] === FIXTURE_SEGMENT ? segments : null;
}

/**
 * The replacement for the fixture reference in the URL token [start, end),
 * which contains FIXTURE_SEGMENT's path at `at`; null when the token is not a
 * fixture reference or is a prose mention.
 * @param {string} source
 * @param {number} start
 * @param {number} at
 * @param {number} end
 * @param {string} videoPlaceholder
 * @returns {{text: string, end: number} | null}
 */
function fixtureEdit(source, start, at, end, videoPlaceholder) {
  const token = source.slice(start, end);
  if (ABSOLUTE_URL.test(token)) return null;
  if (!token.startsWith('/')) {
    if (!fixtureSegments(source.slice(at, end))) return null;
    if (
      source[start - 1] !== '\\' &&
      RELATIVE_PATH_PREFIX.test(source.slice(start, at))
    ) {
      return null;
    }
    throw unsafeFixtureReference(
      source,
      at,
      'it is joined to text the copy cannot parse',
    );
  }

  const before = source[start - 1];
  const after = source[end];
  if (after === '{' && token.endsWith('$')) {
    if (!fixtureSegments(token.slice(0, -1))) return null;
    throw unsafeFixtureReference(
      source,
      at,
      'it is built by a template-literal interpolation',
    );
  }
  const quoted =
    before !== undefined && CLOSING_DELIMITERS.get(before) === after;
  const escapedQuoted =
    (before === "'" || before === '"') &&
    source[start - 2] === '\\' &&
    after === '\\' &&
    source[end + 1] === before;
  const whole = quoted || escapedQuoted;
  let referenceEnd = end;
  if (!whole) {
    while (
      referenceEnd > at &&
      PROSE_PUNCTUATION.has(source[referenceEnd - 1])
    ) {
      referenceEnd--;
    }
  }
  const segments = fixtureSegments(source.slice(start, referenceEnd));
  if (!segments) return null;

  const inText =
    (isTextDelimiter(before) || CLOSING_DELIMITERS.has(before)) &&
    (isTextDelimiter(after) || CLOSERS.has(after)) &&
    (isTextDelimiter(before) || isTextDelimiter(after));
  if (!whole && !inText) {
    throw unsafeFixtureReference(
      source,
      at,
      'it is not a whole quoted, url(), or text value',
    );
  }
  if (quoted && before !== '(') {
    const use = expressionUse(source, start - 1, end);
    if (use) throw unsafeFixtureReference(source, at, use);
  }

  const ext = path.posix
    .extname(segments[segments.length - 1])
    .slice(1)
    .toLowerCase();
  if (VIDEO_EXTENSIONS.has(ext)) {
    return {text: videoPlaceholder, end: referenceEnd};
  }
  if (IMAGE_EXTENSIONS.has(ext)) {
    return {text: PLACEHOLDER_IMAGE, end: referenceEnd};
  }
  if (whole || ext) {
    throw new Error(
      `Unrecognized template asset format ${ext || '(none)'} for ${displayReference(source, at)}`,
    );
  }
  return null;
}

/**
 * Why the string quoted at `open` and `close` cannot be replaced on its own,
 * or null when it is a plain value.
 * @param {string} source
 * @param {number} open
 * @param {number} close
 * @returns {string | null}
 */
function expressionUse(source, open, close) {
  let prev = open - 1;
  while (prev >= 0 && /\s/u.test(source[prev])) prev--;
  let next = close + 1;
  while (next < source.length && /\s/u.test(source[next])) next++;
  if (
    source[prev] === '+' ||
    (source[prev] === '=' && source[prev - 1] === '+') ||
    source[next] === '+'
  ) {
    return 'the string is concatenated with another value';
  }
  if (source[next] === '.' && /[A-Za-z_$]/u.test(source[next + 1] ?? '')) {
    return 'a method is called on the string';
  }
  if (
    MODULE_SPECIFIER_LEAD.test(source.slice(Math.max(0, prev - 16), prev + 1))
  ) {
    return 'it is imported as a module';
  }
  return null;
}

/** @type {typeof import('@babel/parser') | undefined} */
let babelParser;

/**
 * The template source parser, loaded on first use so listing templates
 * never pays for it.
 * @returns {typeof import('@babel/parser')}
 */
function templateSourceParser() {
  babelParser ??= require('@babel/parser');
  return /** @type {typeof import('@babel/parser')} */ (babelParser);
}

/**
 * The [start, end) range of every comment in `source`, or none when it does
 * not parse as TSX.
 * @param {string} source
 * @returns {Array<[number, number]>}
 */
function commentRanges(source) {
  try {
    const {comments} = templateSourceParser().parse(source, {
      sourceType: 'module',
      plugins: ['jsx', 'typescript'],
    });
    return (comments ?? []).map(
      comment =>
        /** @type {[number, number]} */ ([
          comment.start ?? 0,
          comment.end ?? 0,
        ]),
    );
  } catch {
    return [];
  }
}

/**
 * The fixture path at `at`, up to the next whitespace, quote, or tag bracket.
 * @param {string} source
 * @param {number} at
 */
function displayReference(source, at) {
  let end = at;
  while (end < source.length && !/[\s'"`<>]/u.test(source[end])) end++;
  return source.slice(at, end);
}

/**
 * @param {string} source
 * @param {number} at
 * @param {string} reason
 */
function unsafeFixtureReference(source, at, reason) {
  return new Error(
    `Template asset reference ${displayReference(source, at)} cannot be replaced safely: ${reason}. Use the complete path as one static string.`,
  );
}
/**
 * Load a template-spec module and return its metadata object. Supports both
 * families of suffix:
 *   - Canonical `.doc.*` specs may export the stamped object (`type: 'page' |
 *     'block'`) as the default export or use the historical named `doc` export.
 *   - Released `.template.*` compatibility specs use the same object shape.
 * Prefers the default export, falling back to the named `doc` export. `.ts` is
 * loaded via jiti; `.mjs`/`.js` via a
 * native dynamic import. Returns null if the file does not exist.
 *
 * @param {string} docPath absolute path to the spec file
 * @returns {Promise<TemplateDocModule>}
 */
async function loadDocModule(docPath) {
  if (!fs.existsSync(docPath)) return null;
  return readDocView(docPath, {root: 'templates', loader: 'template'});
}

/**
 * List the core page-template directory names (sorted). The `template --list`
 * view discovers far more; this is the minimal core-page set `init` scaffolds
 * from.
 * @returns {string[]}
 */
export function listTemplates() {
  /** @type {string[]} */
  const all = [];
  if (fs.existsSync(PAGES_DIR)) {
    all.push(
      ...listDirEntries(PAGES_DIR)
        .filter(e => e.isDirectory())
        .map(e => e.name),
    );
  }
  return all.sort();
}

/**
 * @param {string} dir
 * @param {RegExp} pattern
 * @returns {string[]}
 */
function findDocFiles(dir, pattern) {
  /** @type {string[]} */
  const results = [];
  if (!fs.existsSync(dir)) return results;
  for (const entry of listDirEntries(dir)) {
    const full = path.join(dir, entry.name);
    if (entry.isDirectory()) {
      results.push(...findDocFiles(full, pattern));
    } else if (pattern.test(entry.name)) {
      results.push(full);
    }
  }
  return results;
}

/**
 * Resolve the template-spec file for a core page directory: the first existing
 * metadata file in {@link ALL_TEMPLATE_SUFFIXES} precedence, or null.
 * @param {string} dirPath
 * @returns {string | null}
 */
export function findPageDocFile(dirPath) {
  for (const suffix of ALL_TEMPLATE_SUFFIXES) {
    const candidate = path.join(dirPath, `template${suffix}`);
    if (fs.existsSync(candidate)) return candidate;
  }
  return null;
}

async function discoverPages() {
  if (!fs.existsSync(PAGES_DIR)) return [];
  const dirs = listDirEntries(PAGES_DIR).filter(e => e.isDirectory());

  /** @type {DiscoveredTemplate[]} */
  const templates = [];
  for (const dir of dirs) {
    const dirPath = path.join(PAGES_DIR, dir.name);
    const docPath =
      findPageDocFile(dirPath) ?? path.join(dirPath, 'template.doc.mjs');
    const doc = await loadDocModule(docPath);
    templates.push({
      type: 'page',
      dirName: dir.name,
      name: doc?.name || dir.name,
      description: doc?.description || '',
      category: doc?.category || '',
      keywords: doc?.keywords ?? [],
      isReady: doc?.isReady ?? true,
      scaffold: doc?.scaffold ?? false,
      ...(doc?.icons ? {icons: doc.icons} : {}),
      filePath: path.join(dirPath, 'page.tsx'),
      docPath,
    });
  }
  return templates;
}

async function discoverBlocks() {
  const docFiles = findDocFiles(BLOCKS_DIR, TEMPLATE_SUFFIX_RE);
  /** @type {DiscoveredTemplate[]} */
  const blocks = [];
  for (const docPath of docFiles) {
    const suffix = matchedTemplateSuffix(docPath);
    if (!suffix) continue;
    const basename = path.basename(docPath, suffix);
    const tsxPath = path.join(path.dirname(docPath), basename + '.tsx');
    if (!fs.existsSync(tsxPath)) continue;
    const doc = await loadDocModule(docPath);
    const relPath = toPosixPath(
      path.relative(BLOCKS_DIR, path.dirname(docPath)),
    );
    blocks.push({
      type: 'block',
      dirName: basename,
      name: doc?.name || basename,
      description: doc?.description || '',
      keywords: doc?.keywords ?? [],
      isReady: doc?.isReady ?? true,
      aspectRatio: doc?.aspectRatio ?? 1,
      componentsUsed: doc?.componentsUsed ?? [],
      ...(doc?.icons ? {icons: doc.icons} : {}),
      isShowcase: doc?.isShowcase ?? false,
      ...(typeof doc?.exampleFor === 'string'
        ? {exampleFor: doc.exampleFor}
        : {}),
      filePath: tsxPath,
      docPath,
      category: relPath,
    });
  }
  return blocks;
}

/**
 * Discover blocks from external packages that declare `astryx.blocks` in
 * their package.json. Same shape as discoverBlocks() output.
 *
 * @param {string} [cwd]
 */
async function discoverExternalBlocks(cwd = process.cwd()) {
  const externals = discoverExternalPackages(cwd);
  /** @type {DiscoveredTemplate[]} */
  const blocks = [];

  for (const ext of externals) {
    if (!ext.blocksDir || !fs.existsSync(ext.blocksDir)) continue;
    const docFiles = findDocFiles(ext.blocksDir, TEMPLATE_SUFFIX_RE);
    for (const docPath of docFiles) {
      const suffix = matchedTemplateSuffix(docPath);
      if (!suffix) continue;
      const basename = path.basename(docPath, suffix);
      const tsxPath = path.join(path.dirname(docPath), basename + '.tsx');
      if (!fs.existsSync(tsxPath)) continue;
      const doc = await loadDocModule(docPath);
      const relPath = toPosixPath(
        path.relative(ext.blocksDir, path.dirname(docPath)),
      );
      blocks.push({
        type: 'block',
        dirName: basename,
        name: doc?.name || basename,
        description: doc?.description || '',
        keywords: doc?.keywords ?? [],
        isReady: doc?.isReady ?? true,
        aspectRatio: doc?.aspectRatio ?? 1,
        componentsUsed: doc?.componentsUsed ?? [],
        ...(doc?.icons ? {icons: doc.icons} : {}),
        isShowcase: doc?.isShowcase ?? false,
        ...(typeof doc?.exampleFor === 'string'
          ? {exampleFor: doc.exampleFor}
          : {}),
        filePath: tsxPath,
        docPath,
        category: relPath,
        package: ext.name,
      });
    }
  }

  return blocks;
}

/**
 * Discover all blocks — core + external packages.
 * @param {string} [cwd]
 * @returns {Promise<DiscoveredTemplate[]>}
 */
async function discoverAllBlocks(cwd = process.cwd()) {
  const [core, external] = await Promise.all([
    discoverBlocks(),
    discoverExternalBlocks(cwd),
  ]);
  return [...core, ...external];
}

/**
 * Discover only the templates built into @astryxdesign/core. Integration
 * authoring checks use this narrower surface so a broken project config or a
 * second integration cannot affect the core-collision result.
 * @returns {Promise<DiscoveredTemplate[]>}
 */
export async function discoverCoreTemplates() {
  const [pages, blocks] = await Promise.all([
    discoverPages(),
    discoverBlocks(),
  ]);
  return [...pages, ...blocks];
}

/**
 * Apply valid integration replacements to a raw template set.
 *
 * One declaration owns its Core target. When different configured packages
 * replace the same target, the later package wins and discovery returns a
 * warning, matching integration-doc replacement order. Multiple declarations
 * inside one package are invalid and fail closed. Missing targets and kind
 * mismatches also fail closed: Core stays selected and every integration
 * template remains addressable by its own id.
 *
 * @param {DiscoveredTemplate[]} templates
 * @param {TemplateDiscoveryError[]} [declarationErrors]
 * @returns {{templates: DiscoveredTemplate[], errors: TemplateReplacementError[]}}
 */
export function applyTemplateReplacements(templates, declarationErrors = []) {
  /** @type {Map<string, DiscoveredTemplate[]>} */
  const coreById = new Map();
  /** @type {Map<string, DiscoveredTemplate[]>} */
  const replacementsByTarget = new Map();

  for (const template of templates) {
    if (pkgOf(template) === CORE_PACKAGE) {
      const matches = coreById.get(template.dirName) ?? [];
      matches.push(template);
      coreById.set(template.dirName, matches);
    }
    if (template.replaces != null) {
      const replacements = replacementsByTarget.get(template.replaces) ?? [];
      replacements.push(template);
      replacementsByTarget.set(template.replaces, replacements);
    }
  }

  const activeReplacements = new Set();
  const replacedCore = new Set();
  /** @type {TemplateReplacementError[]} */
  const errors = declarationErrors.map(error => ({
    ...error,
    code: /** @type {TemplateReplacementError['code']} */ (
      error.code ?? 'invalid_template_replacement'
    ),
    severity: error.severity ?? 'error',
  }));
  /** @param {TemplateReplacementError} error */
  const pushError = error => {
    if (
      errors.some(
        existing =>
          existing.code === error.code &&
          existing.package === error.package &&
          existing.template === error.template &&
          existing.message === error.message,
      )
    ) {
      return;
    }
    errors.push(error);
  };
  for (const [target, replacements] of replacementsByTarget) {
    const targetErrors = errors.filter(
      error => error.replacementTarget === target,
    );
    const hasExplicitIntent =
      replacements.some(replacement => !replacement.autolinked) ||
      targetErrors.some(error => !error.autolinked);
    const contenders = hasExplicitIntent
      ? replacements.filter(replacement => !replacement.autolinked)
      : replacements;
    let targetInvalid = targetErrors.some(
      error =>
        error.severity === 'error' && (!hasExplicitIntent || !error.autolinked),
    );

    /** @type {Map<string, DiscoveredTemplate[]>} */
    const byPackage = new Map();
    for (const replacement of replacements) {
      const pkg = pkgOf(replacement);
      const fromPackage = byPackage.get(pkg) ?? [];
      fromPackage.push(replacement);
      byPackage.set(pkg, fromPackage);
    }
    for (const [pkg, declarations] of byPackage) {
      if (declarations.length < 2) continue;
      if (!hasExplicitIntent || !declarations[0].autolinked) {
        targetInvalid = true;
      }
      const message =
        `${pkg} declares ${declarations.length} templates as replacements for Core ` +
        `template "${target}" (${declarations.map(template => template.dirName).join(', ')}). ` +
        'One package must declare at most one replacement for a Core target.';
      for (const declaration of declarations) {
        pushError({
          code: 'ambiguous_template_replacement',
          severity: 'error',
          package: pkg,
          template: declaration.dirName,
          replacementTarget: target,
          autolinked: declaration.autolinked,
          message,
        });
      }
    }

    const coreMatches = coreById.get(target) ?? [];
    /** @type {Map<DiscoveredTemplate, DiscoveredTemplate>} */
    const coreMatchByReplacement = new Map();
    for (const replacement of replacements) {
      const invalidAffectsTarget =
        !hasExplicitIntent || !replacement.autolinked;
      if (coreMatches.length === 0) {
        if (invalidAffectsTarget) targetInvalid = true;
        pushError({
          code: 'missing_template_replacement_target',
          severity: 'error',
          package: pkgOf(replacement),
          template: replacement.dirName,
          replacementTarget: target,
          autolinked: replacement.autolinked,
          message: `Template "${replacement.dirName}" replaces "${target}", which is not a Core template id.`,
        });
        continue;
      }
      const sameType = coreMatches.filter(
        core => core.type === replacement.type,
      );
      if (sameType.length !== 1) {
        if (invalidAffectsTarget) targetInvalid = true;
        const kinds = coreMatches.map(core => core.type).join(', ');
        pushError({
          code: 'invalid_template_replacement',
          severity: 'error',
          package: pkgOf(replacement),
          template: replacement.dirName,
          replacementTarget: target,
          autolinked: replacement.autolinked,
          message:
            `Template "${replacement.dirName}" is a ${replacement.type} template, but Core ` +
            `template "${target}" is ${kinds || 'not available'}. A replacement must have the same type.`,
        });
        continue;
      }
      coreMatchByReplacement.set(replacement, sameType[0]);
    }

    const validContenders = contenders.filter(replacement =>
      coreMatchByReplacement.has(replacement),
    );
    if (targetInvalid || validContenders.length === 0) continue;

    const replacement = validContenders[validContenders.length - 1];
    const validReplacements = replacements.filter(candidate =>
      coreMatchByReplacement.has(candidate),
    );
    if (validReplacements.length > 1) {
      const autolinkedLost =
        hasExplicitIntent &&
        validReplacements.some(candidate => candidate.autolinked);
      const allAutolinked = validReplacements.every(
        candidate => candidate.autolinked,
      );
      pushError({
        code: 'ambiguous_template_replacement',
        severity: 'warning',
        package: pkgOf(replacement),
        template: replacement.dirName,
        replacementTarget: target,
        autolinked: replacement.autolinked,
        message: autolinkedLost
          ? `Core template "${target}" is replaced by ${validReplacements.map(candidate => pkgOf(candidate)).join(', ')}. ${pkgOf(replacement)} is explicitly configured, so it wins over autolinked integrations.`
          : allAutolinked
            ? `Core template "${target}" is replaced by autolinked dependencies ${validReplacements.map(candidate => pkgOf(candidate)).join(', ')}. ${pkgOf(replacement)} is listed later in package.json dependencies, so it wins. Add the intended package to astryx.config integrations to make precedence explicit.`
            : `Core template "${target}" is replaced by ${validReplacements.map(candidate => pkgOf(candidate)).join(', ')}. ${pkgOf(replacement)} is configured later, so it wins.`,
      });
    }

    activeReplacements.add(replacement);
    const coreMatch = coreMatchByReplacement.get(replacement);
    if (coreMatch) replacedCore.add(coreMatch);
  }

  const effective = templates.flatMap(template => {
    if (replacedCore.has(template)) return [];
    if (template.replaces != null && !activeReplacements.has(template)) {
      const fallback = {
        ...template,
        replacementRejected: true,
        replacementTarget: template.replaces,
      };
      delete fallback.replaces;
      return [fallback];
    }
    return [template];
  });

  return {
    templates: effective.sort((a, b) => a.name.localeCompare(b.name)),
    errors,
  };
}

/**
 * Discover the raw Core, external, and integration template set before
 * replacement declarations are applied.
 * @param {string} [cwd]
 * @returns {Promise<{templates: DiscoveredTemplate[], errors: TemplateDiscoveryError[]}>}
 */
async function discoverAllSources(cwd = process.cwd()) {
  const [core, external, integration] = await Promise.all([
    discoverCoreTemplates(),
    discoverExternalBlocks(cwd),
    discoverIntegrationTemplates(cwd),
  ]);
  return {
    templates: [...core, ...external, ...integration.templates],
    errors: integration.errors,
  };
}

/**
 * Discover every template without hiding replaced Core originals. Internal
 * package-qualified selection uses this view.
 * @param {string} [cwd]
 * @returns {Promise<DiscoveredTemplate[]>}
 */
export async function discoverAllUnresolved(cwd = process.cwd()) {
  return (await discoverAllSources(cwd)).templates.sort((a, b) =>
    a.name.localeCompare(b.name),
  );
}

/**
 * Resolve replacement declarations while retaining package-addressable entries
 * that are shadowed or rejected in the default discovery view.
 * @param {string} [cwd]
 * @returns {Promise<{templates: DiscoveredTemplate[], errors: Array<TemplateDiscoveryError | TemplateReplacementError>}>}
 */
async function resolveAllSources(cwd = process.cwd()) {
  const discovered = await discoverAllSources(cwd);
  const replacementErrors = discovered.errors.filter(
    error => error.replacementTarget != null,
  );
  const resolved = applyTemplateReplacements(
    discovered.templates,
    replacementErrors,
  );
  return {
    templates: resolved.templates,
    errors: [
      ...discovered.errors.filter(error => error.replacementTarget == null),
      ...resolved.errors,
    ],
  };
}

/**
 * Discover the resolved catalog before default-view shadowing. Internal
 * package-qualified selection uses this view.
 * @param {string} [cwd]
 * @returns {Promise<DiscoveredTemplate[]>}
 */
export async function discoverAllResolved(cwd = process.cwd()) {
  return (await resolveAllSources(cwd)).templates;
}

/**
 * @param {string} [cwd]
 * @returns {Promise<DiscoveredTemplate[]>}
 */
export async function discoverAll(cwd = process.cwd()) {
  return effectiveTemplateDiscovery(await discoverAllResolved(cwd));
}

/**
 * Like {@link discoverAll} but also returns integration-template discovery and
 * replacement-declaration errors. Use this when the caller wants to warn about
 * malformed integration templates or inactive replacement declarations.
 *
 * @param {string} [cwd]
 * @returns {Promise<{templates: DiscoveredTemplate[], errors: Array<TemplateDiscoveryError | TemplateReplacementError>}>}
 */
export async function discoverAllWithErrors(cwd = process.cwd()) {
  const resolved = await resolveAllSources(cwd);
  return {
    templates: effectiveTemplateDiscovery(resolved.templates),
    errors: resolved.errors,
  };
}

/**
 * Recursively collect integration template-spec files under `root`.
 * Returns absolute paths to files ending in one of ALL_TEMPLATE_SUFFIXES
 * (canonical `.doc.*` or released `.template.*` compatibility files).
 *
 * @param {string} root
 * @returns {string[]}
 */
function findIntegrationDocFiles(root) {
  /** @type {string[]} */
  const results = [];
  if (!fs.existsSync(root)) return results;
  /** @param {string} dir */
  const walk = dir => {
    for (const entry of listDirEntries(dir)) {
      const full = path.join(dir, entry.name);
      if (entry.isDirectory()) {
        walk(full);
      } else if (
        ALL_TEMPLATE_SUFFIXES.some(suffix => entry.name.endsWith(suffix))
      ) {
        results.push(full);
      }
    }
  };
  walk(root);
  return results;
}

/**
 * Discover templates contributed by configured integrations.
 *
 * For each integration with a resolved `templates` root, every
 * canonical `<id>.doc.{mjs,ts,js}` (or released `<id>.template.{ts,mjs,js}`) file is a
 * template whose id is its path relative to the templates root with the
 * matched suffix stripped (kebab-case, may be nested). The doc's `type`
 * (page|block) decides scaffolding — there is no `/pages` vs `/blocks`
 * requirement. A same-stem sibling source file (`<id>.tsx`) is required; a doc
 * missing its source, or missing `type`, is an integration error and that
 * template is skipped (recorded in `errors`).
 *
 * @param {string} [cwd]
 * @returns {Promise<{templates: DiscoveredTemplate[], errors: TemplateDiscoveryError[]}>}
 */
async function discoverIntegrationTemplates(cwd = process.cwd()) {
  /** @type {DiscoveredTemplate[]} */
  const templates = [];
  /** @type {TemplateDiscoveryError[]} */
  const errors = [];

  let loadedIntegrations;
  try {
    const project = await Project.load(cwd);
    loadedIntegrations =
      /** @type {import('../integrations/integrations.mjs').LoadedIntegration[]} */ (
        project.loadedIntegrations
      );
  } catch (err) {
    // A broken astryx.config (or an integration that fails to load) can't
    // contribute templates. Record it as a discovery error instead of
    // swallowing it silently: a bare `catch {}` also hides unexpected bugs.
    // discoverAll (the no-error variant that `astryx template` uses) and
    // Project.templates() both discard this errors array, so the template
    // command's behavior is unchanged — the full config-error UX still lives
    // in `discover`/`doctor` via Project.issues(). Only callers that opt into
    // errors (discoverAllWithErrors) now see the signal.
    errors.push({
      package: 'astryx.config',
      message: err instanceof Error ? err.message : String(err),
    });
    return {templates, errors};
  }

  for (const integration of loadedIntegrations) {
    // One integration's unreadable root must not cost core or the others theirs.
    try {
      const result = await discoverIntegrationTemplatesForOne(integration);
      templates.push(...result.templates);
      errors.push(...result.errors);
    } catch (err) {
      errors.push({
        package: integration?.name ?? integration?.__spec ?? 'integration',
        message: err instanceof Error ? err.message : String(err),
      });
    }
  }

  return {templates, errors};
}

/**
 * Report replacement declarations that cannot hold inside one package: two of
 * its templates replacing the same Core target. Cross-package precedence and
 * target checks happen in {@link applyTemplateReplacements}.
 * @param {string} pkg
 * @param {boolean | undefined} autolinked
 * @param {DiscoveredTemplate[]} templates
 * @param {TemplateDiscoveryError[]} errors
 */
function reportSamePackageReplacements(pkg, autolinked, templates, errors) {
  /** @type {Map<string, string[]>} */
  const idsByTarget = new Map();
  for (const template of templates) {
    if (template.replaces == null) continue;
    const ids = idsByTarget.get(template.replaces) ?? [];
    ids.push(template.dirName);
    idsByTarget.set(template.replaces, ids);
  }
  for (const [target, ids] of idsByTarget) {
    if (ids.length < 2) continue;
    const message =
      `${pkg} declares ${ids.length} templates as replacements for Core template ` +
      `"${target}" (${ids.join(', ')}). One package must declare at most one ` +
      'replacement for a Core target.';
    for (const template of ids) {
      errors.push({
        code: 'ambiguous_template_replacement',
        severity: 'error',
        package: pkg,
        autolinked,
        template,
        replacementTarget: target,
        message,
      });
    }
  }
}

/**
 * The fix for a template doc with no same-stem `.tsx`: rename a same-stem
 * source written in another extension, or add the `.tsx`.
 * @param {string} docPath
 * @param {string} sourcePath the `.tsx` it needs
 */
function missingTemplateSourceFix(docPath, sourcePath) {
  const source = path.basename(sourcePath);
  const stem = source.slice(0, -'.tsx'.length);
  const other = ['.jsx', '.js', '.ts', '.mjs']
    .map(extension => `${stem}${extension}`)
    .find(file => fs.existsSync(path.join(path.dirname(sourcePath), file)));
  return other
    ? `Found ${other}, but a template source must be a .tsx file. Fix: rename ${other} to ${source}.`
    : `Fix: add ${source} beside ${path.basename(docPath)}, with the template as its default export.`;
}

/**
 * Discover the templates contributed by a SINGLE integration. Same per-template
 * rules as {@link discoverIntegrationTemplates} (same-stem source required,
 * page|block type required); broken templates are recorded in `errors` rather
 * than thrown. Exposed for `doctor integration validate` and template authoring checks.
 *
 * @param {{name?: string, __spec?: string, __autolinked?: boolean, templates?: string}} integration
 * @returns {Promise<{templates: DiscoveredTemplate[], errors: TemplateDiscoveryError[]}>}
 */
export async function discoverIntegrationTemplatesForOne(integration) {
  /** @type {DiscoveredTemplate[]} */
  const templates = [];
  /** @type {TemplateDiscoveryError[]} */
  const errors = [];

  const root = integration?.templates;
  const pkgLabel = integration?.name ?? integration?.__spec ?? 'integration';
  if (!root || !fs.existsSync(root)) return {templates, errors};

  for (const docPath of findIntegrationDocFiles(root)) {
    const suffix = matchedTemplateSuffix(docPath);
    if (!suffix) continue;
    const id = path
      .relative(root, docPath)
      .slice(0, -suffix.length)
      .split(path.sep)
      .join('/');

    const sourcePath = docPath.slice(0, -suffix.length) + '.tsx';
    if (!fs.existsSync(sourcePath)) {
      errors.push({
        package: pkgLabel,
        template: id,
        message: `Template "${id}" is missing its same-stem source file ${path.basename(sourcePath)}. ${missingTemplateSourceFix(docPath, sourcePath)}`,
      });
      // A replacement this unusable template declares still counts, so its
      // target fails closed instead of going to a sibling.
      const declared = await declaredReplacement(docPath, id);
      if (declared != null) {
        errors.push({
          code: 'invalid_template_replacement',
          severity: 'error',
          package: pkgLabel,
          autolinked: integration.__autolinked,
          template: id,
          replacementTarget: declared,
          message: `Template "${id}" replaces "${declared}", but it cannot be used: it is missing its same-stem source file ${path.basename(sourcePath)}.`,
        });
      }
      continue;
    }

    let doc;
    try {
      doc = await loadIntegrationDoc(docPath, `Template "${id}"`);
    } catch (err) {
      errors.push({
        package: pkgLabel,
        template: id,
        message: `Template "${id}" failed to load: ${/** @type {any} */ (err).message}`,
      });
      // A replacement this unusable template declares still counts, so its
      // target fails closed instead of going to a sibling (spec:AST-035 FR4).
      const declared = await declaredReplacement(docPath, id);
      if (declared != null) {
        errors.push({
          code: 'invalid_template_replacement',
          severity: 'error',
          package: pkgLabel,
          autolinked: integration.__autolinked,
          template: id,
          replacementTarget: declared,
          message: `Template "${id}" replaces "${declared}", but it cannot be used: its metadata does not load.`,
        });
      }
      continue;
    }

    // loadIntegrationDoc validates against the envelope (incl. a 'page'|'block'
    // type) at the load boundary, so a valid doc always has a type. This guard
    // stays as defense-in-depth.
    const type = doc?.type;
    if (type !== 'page' && type !== 'block') {
      errors.push({
        package: pkgLabel,
        template: id,
        message: `Template "${id}" is missing a "type" of "page" or "block". Stamp the default export with type: 'page' or type: 'block'.`,
      });
      const declared =
        doc?.replaces ?? (await declaredReplacement(docPath, id));
      if (declared != null) {
        errors.push({
          code: 'invalid_template_replacement',
          severity: 'error',
          package: pkgLabel,
          autolinked: integration.__autolinked,
          template: id,
          replacementTarget: declared,
          message: `Template "${id}" replaces "${declared}", but it cannot be used: it has no "type".`,
        });
      }
      continue;
    }

    templates.push({
      type,
      dirName: id,
      name: doc?.name || id,
      displayName: doc?.displayName,
      description: doc?.description || '',
      keywords: doc?.keywords ?? [],
      category: doc?.category || '',
      isReady: doc?.isReady ?? true,
      scaffold: doc?.scaffold ?? false,
      aspectRatio: doc?.type === 'block' ? doc.aspectRatio : undefined,
      exampleFor: doc?.type === 'block' ? doc.exampleFor : undefined,
      alsoExampleFor:
        doc?.type === 'block' ? (doc.alsoExampleFor ?? []) : undefined,
      alsoShowcaseFor:
        doc?.type === 'block' ? (doc.alsoShowcaseFor ?? []) : undefined,
      isShowcase: doc?.type === 'block' ? (doc.isShowcase ?? false) : undefined,
      // The integration envelope carries `componentsUsed` for both page and
      // block templates; the rich TemplateDoc union only declares it on blocks,
      // so read it off the envelope shape here.
      componentsUsed:
        /** @type {{componentsUsed?: string[]}} */ (doc).componentsUsed ?? [],
      ...(doc?.icons ? {icons: doc.icons} : {}),
      filePath: sourcePath,
      docPath,
      package: pkgLabel,
      autolinked: integration.__autolinked,
      replaces: doc?.replaces,
    });
  }

  reportSamePackageReplacements(
    pkgLabel,
    integration.__autolinked,
    templates,
    errors,
  );
  return {templates, errors};
}

/**
 * The replacement a template doc declares, even when the doc does not validate
 * or load: an unusable template's declaration still counts, so its target
 * fails closed (spec:AST-035 FR4). Null when it declares none.
 * @param {string} docPath
 * @param {string} id
 * @returns {Promise<string | null>}
 */
async function declaredReplacement(docPath, id) {
  try {
    const doc = await loadIntegrationDoc(docPath, `Template "${id}"`);
    return doc?.replaces ?? null;
  } catch {
    // The doc does not validate; read what it declares without validating.
  }
  try {
    // The guarded importer: anything the doc writes to stdout as it loads
    // goes to stderr, so `--json` output stays clean.
    const raw = (await importDocModule(docPath))?.default;
    if (raw != null && typeof raw === 'object') {
      return typeof raw.replaces === 'string' ? raw.replaces : null;
    }
  } catch {
    // The module does not load at all; its text may still name a target.
  }
  try {
    const match = /\breplaces\s*:\s*['"]([^'"\n]+)['"]/u.exec(
      fs.readFileSync(docPath, 'utf8'),
    );
    return match ? match[1] : null;
  } catch {
    return null;
  }
}

/**
 * @param {string} componentName
 * @param {string} [cwd]
 * @returns {Promise<DiscoveredTemplate[]>}
 */
export async function findRelatedBlocks(componentName, cwd) {
  const blocks = await discoverAllBlocks(cwd);
  return blocks.filter(b =>
    (b.componentsUsed ?? []).some(
      c => c.toLowerCase() === componentName.toLowerCase(),
    ),
  );
}

/**
 * @param {string} componentName
 * @param {string} [cwd]
 * @param {{ package?: string }} [options] - When set, only search blocks from this package.
 *   Core blocks have no `package` field; external blocks have `package` set to the npm name.
 */
export async function findShowcase(componentName, cwd, options) {
  const blocks = await discoverAllBlocks(cwd);
  const lc = componentName.toLowerCase();
  const packageFilter = options?.package;

  // When scoped to a package, only consider blocks from that package.
  // Core blocks have no `package` field — filter them out when a package is specified.
  const showcases = blocks.filter(b => {
    if (!b.isShowcase) return false;
    if (packageFilter) return b.package === packageFilter;
    return true;
  });

  const toResult = (/** @type {DiscoveredTemplate} */ b) => ({
    name: b.name,
    aspectRatio: b.aspectRatio,
    filePath: b.filePath,
    docPath: b.docPath,
  });

  // Priority 0: the showcase that names the component (`exampleFor`), the
  // way packages declare it; a category no longer has to carry the name.
  const named = showcases.find(b => (b.exampleFor ?? '').toLowerCase() === lc);
  if (named) return toResult(named);

  // Priority 1: own directory (components/Badge/ for "Badge")
  const dirMatch = showcases.find(b => {
    const catDir = path.basename(b.category ?? '').toLowerCase();
    return catDir === lc;
  });
  if (dirMatch) return toResult(dirMatch);

  // Priority 2: componentsUsed in any directory (ClickableCard in Card/)
  const usedMatch = showcases.find(b =>
    (b.componentsUsed ?? []).some(c => c.toLowerCase() === lc),
  );
  if (usedMatch) return toResult(usedMatch);

  return null;
}

/** The npm scope of every Astryx package. */
const ASTRYX_PACKAGE_SCOPE = '@astryxdesign/';

/** A JSX opening tag; componentsInSource says why the pattern looks so. */
const JSX_TAG = /(?<![\w$.])<(XDS)?([A-Z]\w+)/g;

/** Comments and line breaks that may sit between two words of an import. */
// A block comment ends at its first `*/`, and a line comment at its line's
// end. So each comment has one reading, and a failed match cannot backtrack
// through every split of a comment run.
const SPACE_OR_COMMENT = String.raw`\s|\/\*(?:[^*]|\*(?!\/))*\*\/|\/\/[^\n\r\u2028\u2029]*(?![^\n\r\u2028\u2029])`;
const BETWEEN = `(?:${SPACE_OR_COMMENT})*`;
const GAP = new RegExp(`(?:${SPACE_OR_COMMENT})+`, 'g');
// The pair scan can start again at each word of a run of spaces and
// comments, so a run costs up to its length squared. The longest run in the
// bundled templates is about 10 KB.
const MAX_GAP = 16 * 1024;

/**
 * One `imported as local` pair. The imported name is an identifier (group 1)
 * or a string (group 3); the local name is group 4.
 */
const ALIAS = new RegExp(
  String.raw`(?:(?<![\p{ID_Continue}$])([\p{ID_Start}$_][\p{ID_Continue}$\u200C\u200D]*)|(['"])((?:\\[\s\S]|(?!\2)[^\\\n])*)\2)` +
    BETWEEN +
    String.raw`\bas\b` +
    BETWEEN +
    String.raw`([\p{ID_Start}$_][\p{ID_Continue}$\u200C\u200D]*)`,
  'gu',
);
// What follows each `as`: the pair scan reads the same text after its `as`.
const AS_LOCAL = new RegExp(
  String.raw`\bas\b` +
    BETWEEN +
    String.raw`([\p{ID_Start}$_][\p{ID_Continue}$\u200C\u200D]*)`,
  'gu',
);

const UBIQUITOUS = new Set([
  'Text',
  'Heading',
  'Button',
  'HStack',
  'VStack',
  'Link',
  'StackItem',
  'Icon',
]);

/**
 * The top-level bindings of a source. `declared` holds names bound by
 * `function`, `class`, `const`, `let` or `var` declarations (exported or not).
 * `astryxImports` maps each local name of a named Astryx import to the name the
 * package exports, so `Text as AstryxText` maps `AstryxText` to `Text`. Both
 * are empty when the source does not parse, so a parse failure never drops a
 * real component.
 *
 * @param {string} src
 * @returns {{declared: Set<string>, astryxImports: Map<string, string>}}
 */
function topLevelBindings(src) {
  /** @type {Set<string>} */
  const names = new Set();
  /** @type {Map<string, string>} */
  const astryxImports = new Map();
  let program;
  try {
    program = templateSourceParser().parse(src, {
      sourceType: 'module',
      plugins: ['jsx', 'typescript'],
      errorRecovery: true,
    }).program;
  } catch {
    return {declared: names, astryxImports};
  }
  for (const statement of program.body) {
    if (statement.type === 'ImportDeclaration') {
      if (!statement.source.value.startsWith(ASTRYX_PACKAGE_SCOPE)) continue;
      for (const specifier of statement.specifiers) {
        if (specifier.type !== 'ImportSpecifier') continue;
        const {imported} = specifier;
        astryxImports.set(
          specifier.local.name,
          imported.type === 'Identifier' ? imported.name : imported.value,
        );
      }
      continue;
    }
    const node =
      statement.type === 'ExportNamedDeclaration' ||
      statement.type === 'ExportDefaultDeclaration'
        ? statement.declaration
        : statement;
    if (node == null) continue;
    if (
      (node.type === 'FunctionDeclaration' ||
        node.type === 'ClassDeclaration') &&
      node.id
    ) {
      names.add(node.id.name);
    } else if (node.type === 'VariableDeclaration') {
      for (const declarator of node.declarations) {
        if (declarator.id.type === 'Identifier') {
          names.add(declarator.id.name);
        }
      }
    }
  }
  return {declared: names, astryxImports};
}

/**
 * The components a template file composes, as written in the catalog.
 * @param {string} pagePath
 * @returns {string[]}
 */
export function extractComponents(pagePath) {
  return componentsInSource(fs.readFileSync(pagePath, 'utf-8'));
}

/**
 * The components a template source composes. A surface that returns rewritten
 * source lists the components of that source, so a component the rewrite
 * removed is not listed.
 * @param {string} src
 * @returns {string[]}
 */
export function componentsInSource(src) {
  // Match JSX opening tags, e.g. `<Section` or the legacy `<XDSSection`.
  // Templates author bare component names post un-prefix migration
  // (P2380608025), so the `XDS` prefix is optional. Anchoring on the `<`
  // JSX-tag boundary keeps this precise (avoids matching imports/comments/
  // identifiers) while remaining prefix-agnostic.
  //
  // The lookbehind additionally requires that the `<` NOT follow an identifier
  // character, which is what separates a JSX tag from a TypeScript generic
  // argument list. `return <Dialog` and `rows.map(r => <ListItem` match;
  // `useState<ReadonlySet<string>>`, `ComponentType<SVGProps<SVGSVGElement>>`
  // and `Record<string, Phase>` no longer do. Those were being indexed as
  // rendered components, putting type names like `Record`, `SVGProps` and
  // `ReadonlySet` into template keyword and "components used" output.
  const tagRegex = new RegExp(JSX_TAG);
  /** @type {string[]} */
  const matches = [];
  let m;
  while ((m = tagRegex.exec(src)) !== null) {
    matches.push(m[2]);
  }

  // Exclude names bound by a top-level declaration in the same file: those are
  // page-local helpers (e.g. `function TimelineSection()`), not components a
  // builder can import. Read real bindings from the syntax tree so comments,
  // strings and type annotations cannot add or hide a name.
  const {declared: localDeclNames, astryxImports} = topLevelBindings(src);

  return catalogNames(
    matches
      .filter(n => !localDeclNames.has(n))
      .map(n => astryxImports.get(n) ?? n),
  );
}

/**
 * Rendered component names as the catalog lists them: without theme wrappers
 * and ubiquitous parts, each part suffix stripped, each name once, sorted.
 * @param {string[]} names
 * @returns {string[]}
 */
function catalogNames(names) {
  return [
    ...new Set(
      names
        .filter(n => !['Theme', 'ThemeProvider'].includes(n))
        .filter(n => !UBIQUITOUS.has(n))
        .map(n =>
          n.replace(
            // Strip only when a stem remains, so a bare `<Section>` keeps its
            // own name instead of emptying out.
            /(?<=.)(Item|Section|Header|Content|Footer|Panel|Heading|CollapseButton|Column|Sortable|Selection|Group|Source)$/,
            '',
          ),
        )
        .filter(Boolean),
    ),
  ].sort();
}

/**
 * Every name componentsInSource can return for `src`, read without parsing
 * it, or null when it cannot be bounded so. It keeps the tag names a parse
 * would drop as page-local. It adds each name an `imported as local` pair
 * makes a tag stand for, wherever that text appears. An escaped name in an
 * identifier or a string defeats the reading, so then it is null.
 * @param {string} src
 * @returns {string[] | null}
 */
export function componentNameBound(src) {
  if (src.includes('\\u')) return null;
  for (const gap of src.matchAll(GAP)) {
    if (gap[0].length > MAX_GAP) return null;
  }
  const tags = Array.from(src.matchAll(JSX_TAG), m => m[2]);
  const local = new Set(tags);
  // A pair adds a name only when its local name is a tag. Most sources have
  // no `as` before a tag's name, so they skip the slower pair scan. Each
  // match restarts one character on: a `/*` in a comment can hide a pair.
  const asLocal = new RegExp(AS_LOCAL);
  let pairs = false;
  for (let m = asLocal.exec(src); m && !pairs; m = asLocal.exec(src)) {
    asLocal.lastIndex = m.index + 1;
    pairs = local.has(m[1]);
  }
  if (!pairs) return catalogNames(tags);
  /** @type {string[]} */
  const imported = [];
  // Each match restarts one character on, so no pair hides inside another.
  const alias = new RegExp(ALIAS);
  for (let m = alias.exec(src); m; m = alias.exec(src)) {
    // Step one code point: a `u` regex moves an index inside a surrogate
    // pair back to the pair's start.
    alias.lastIndex =
      m.index + ((src.codePointAt(m.index) ?? 0) > 0xffff ? 2 : 1);
    if (!local.has(m[4])) continue;
    const name = m[1] ?? m[3];
    if (name.includes('\\')) return null;
    imported.push(name);
  }
  return catalogNames([...tags, ...imported]);
}