@astryxdesign/cli 0.6.3-canary.98a2e4e → 0.6.3-canary.9c4d44d

package/foundation/discovery/template-adapter.mjs

@@ -23,13 +23,15 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import {createJiti} from 'jiti';
-import {loadModuleWithParser} from '../fs/module-loader.mjs';
-import {parseTemplate} from '../../authoring/doctypes/template/parse.mjs';
+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 {CORE_PROVIDER_ID} from '../identity/providers.mjs';
 import {Project} from '../config/project.mjs';
 
+const require = createRequire(import.meta.url);
+
 /** Identity used for core (built-in) templates in package-scoped listings. */
 const CORE_PACKAGE = CORE_PROVIDER_ID;
 
@@ -43,6 +45,53 @@ 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
@@ -65,6 +114,11 @@ export function pkgOf(t) {
  * @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
  */
 
 /**
@@ -73,6 +127,15 @@ export function pkgOf(t) {
  * @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
  */
 
 /**
@@ -81,31 +144,28 @@ export function pkgOf(t) {
  */
 
 /**
- * Canonical basename suffixes for template-spec files, in precedence order.
- * A template spec is a scaffoldable TEMPLATE (a plain object stamped with a
- * `type` of `'page'` or `'block'`), so `.template.*` is the descriptive family
- * name.
+ * 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'];
 
 /**
- * Legacy basename suffixes for template-spec files, in precedence order.
- * `.doc.*` was inherited from the component-doc convention before templates
- * had their own name; it is still accepted during the transition window.
+ * 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'];
 
 /**
- * The union of canonical + legacy template-spec suffixes, canonical first so
- * `.template.*` wins over `.doc.*` when both stems exist. All template
- * discovery matches this union so a `Foo.template.ts` file is treated exactly
- * like a legacy `Foo.doc.mjs`.
+ * 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 `.template.*` and legacy `.doc.*` families.
+ * Recognizes both the canonical `.doc.*` and released `.template.*` families.
  * @param {string} file
  * @returns {string | null}
  */
@@ -119,16 +179,6 @@ function matchedTemplateSuffix(file) {
  */
 const TEMPLATE_SUFFIX_RE = /\.(template|doc)\.(ts|mjs|js)$/;
 
-/** @type {ReturnType<typeof createJiti> | undefined} */
-let jitiInstance;
-/** Lazily-created jiti for loading `.ts` template specs (JSX-capable). */
-function getJiti() {
-  if (!jitiInstance) {
-    jitiInstance = createJiti(import.meta.url, {jsx: true});
-  }
-  return jitiInstance;
-}
-
 /**
  * Load an integration template doc module and validate it against the template
  * envelope at the load boundary. Default export only — `.ts` via jiti,
@@ -141,7 +191,13 @@ function getJiti() {
  * @param {string} [label]
  */
 async function loadIntegrationDoc(file, label) {
-  return loadModuleWithParser(file, parseTemplate, {label});
+  return readDocView(file, {
+    root: 'templates',
+    exports: ['default'],
+    label: label ?? file,
+    strict: true,
+    value: 'parsed',
+  });
 }
 
 const TEMPLATES_DIR = path.join(CLI_ROOT, 'assets', 'templates');
@@ -185,17 +241,53 @@ const IMAGE_EXTENSIONS = new Set([
 ]);
 
 /**
- * Demo-asset sources to strip from scaffolded projects. Template demo imagery
+ * 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). Those paths
- * only resolve inside the Astryx docsite/sandbox, so on scaffold they're
- * replaced — a scaffolded project has no `/template-assets/` dir and would
- * otherwise 404. Genuine third-party URLs (e.g. brand logos from
- * paypalobjects.com) are intentionally left untouched.
- *
- * @type {RegExp}
+ * 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 DEMO_ASSET_PATTERN = /\/template-assets\/[\w.-]+\.(\w+)/g;
+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
@@ -209,36 +301,255 @@ function toPosixPath(p) {
 }
 
 /**
- * Replace demo asset references 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.
+ * 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 source.replace(DEMO_ASSET_PATTERN, (match, extension) => {
-    const ext = extension.toLowerCase();
-    if (VIDEO_EXTENSIONS.has(ext)) {
-      return '';
+  const needle = `/${FIXTURE_SEGMENT}`;
+  let output = '';
+  let copied = 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);
+    } catch (err) {
+      comments ??= commentRanges(source);
+      if (!comments.some(([from, to]) => from <= at && at < to)) throw err;
+      edit = null;
     }
-    if (IMAGE_EXTENSIONS.has(ext)) {
-      return PLACEHOLDER_IMAGE;
+    if (edit) {
+      output += source.slice(copied, start) + edit.text;
+      copied = edit.end;
     }
-    throw new Error(`Unrecognized template asset format ${ext} for ${match}`);
-  });
+    at = source.indexOf(needle, end);
+  }
+  return output + source.slice(copied);
+}
+
+/** @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
+ * @returns {{text: string, end: number} | null}
+ */
+function fixtureEdit(source, start, at, end) {
+  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: '', 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;
+}
+
+/**
+ * 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 {parse} = require('@babel/parser');
+    const {comments} = 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:
- *   - Legacy `.doc.*` core/external specs export `export const doc = {...}`.
- *   - Canonical `.template.*` specs export the stamped object (`type: 'page' |
- *     'block'`) as the default export.
- * Prefers the default export, falling back to the named `doc` export, so a
- * `Foo.template.ts` (default export) is read identically to a legacy
- * `Foo.doc.mjs` (`doc` export). `.ts` is loaded via jiti; `.mjs`/`.js` via a
+ *   - 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
@@ -246,10 +557,7 @@ export function stripTemplateAssetRefs(source) {
  */
 async function loadDocModule(docPath) {
   if (!fs.existsSync(docPath)) return null;
-  const docModule = docPath.endsWith('.ts')
-    ? await getJiti().import(docPath)
-    : await import(`file://${docPath}`);
-  return docModule.default ?? docModule.doc;
+  return readDocView(docPath, {root: 'templates', loader: 'template'});
 }
 
 /**
@@ -294,11 +602,11 @@ function findDocFiles(dir, pattern) {
 
 /**
  * Resolve the template-spec file for a core page directory: the first existing
- * `template.<suffix>` in canonical-then-legacy precedence, or null.
+ * metadata file in {@link ALL_TEMPLATE_SUFFIXES} precedence, or null.
  * @param {string} dirPath
  * @returns {string | null}
  */
-function findPageDocFile(dirPath) {
+export function findPageDocFile(dirPath) {
   for (const suffix of ALL_TEMPLATE_SUFFIXES) {
     const candidate = path.join(dirPath, `template${suffix}`);
     if (fs.existsSync(candidate)) return candidate;
@@ -437,44 +745,297 @@ export async function discoverCoreTemplates() {
 }
 
 /**
+ * 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<DiscoveredTemplate[]>}
+ * @returns {Promise<{templates: DiscoveredTemplate[], errors: TemplateDiscoveryError[]}>}
  */
-export async function discoverAll(cwd = process.cwd()) {
+async function discoverAllSources(cwd = process.cwd()) {
   const [core, external, integration] = await Promise.all([
     discoverCoreTemplates(),
     discoverExternalBlocks(cwd),
     discoverIntegrationTemplates(cwd),
   ]);
-  return [...core, ...external, ...integration.templates].sort((a, b) =>
+  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),
   );
 }
 
 /**
- * Like {@link discoverAll} but also returns integration-template discovery
- * errors (missing same-stem source, missing `type`, load failure). Use this
- * when the caller wants to warn about malformed integration templates.
+ * 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: TemplateDiscoveryError[]}>}
+ * @returns {Promise<{templates: DiscoveredTemplate[], errors: Array<TemplateDiscoveryError | TemplateReplacementError>}>}
  */
 export async function discoverAllWithErrors(cwd = process.cwd()) {
-  const [pages, blocks, integration] = await Promise.all([
-    discoverPages(),
-    discoverAllBlocks(cwd),
-    discoverIntegrationTemplates(cwd),
-  ]);
-  const templates = [...pages, ...blocks, ...integration.templates].sort(
-    (a, b) => a.name.localeCompare(b.name),
-  );
-  return {templates, errors: integration.errors};
+  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 `.template.*` or legacy `.doc.*`).
+ * (canonical `.doc.*` or released `.template.*` compatibility files).
  *
  * @param {string} root
  * @returns {string[]}
@@ -504,7 +1065,7 @@ function findIntegrationDocFiles(root) {
  * Discover templates contributed by configured integrations.
  *
  * For each integration with a resolved `templates` root, every
- * `<id>.template.{ts,mjs,js}` (or legacy `<id>.doc.{ts,mjs,js}`) file is a
+ * 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`
@@ -545,21 +1106,67 @@ async function discoverIntegrationTemplates(cwd = process.cwd()) {
   }
 
   for (const integration of loadedIntegrations) {
-    const result = await discoverIntegrationTemplatesForOne(integration);
-    templates.push(...result.templates);
-    errors.push(...result.errors);
+    // 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,
+      });
+    }
+  }
+}
+
 /**
  * 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, templates?: string}} integration
+ * @param {{name?: string, __spec?: string, __autolinked?: boolean, templates?: string}} integration
  * @returns {Promise<{templates: DiscoveredTemplate[], errors: TemplateDiscoveryError[]}>}
  */
 export async function discoverIntegrationTemplatesForOne(integration) {
@@ -588,6 +1195,20 @@ export async function discoverIntegrationTemplatesForOne(integration) {
         template: id,
         message: `Template "${id}" is missing its same-stem source file ${path.basename(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;
     }
 
@@ -600,6 +1221,20 @@ export async function discoverIntegrationTemplatesForOne(integration) {
         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;
     }
 
@@ -613,6 +1248,18 @@ export async function discoverIntegrationTemplatesForOne(integration) {
         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;
     }
 
@@ -640,12 +1287,55 @@ export async function discoverIntegrationTemplatesForOne(integration) {
       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]