@baiyibai-antora/extensions 1.14.0 → 1.15.0

package/dist/extensions/cite-it/index.js

@@ -2,7 +2,7 @@
 /**
  * @baiyibai-antora/extensions - cite-it
  *
- * Resolves `citeit:[key]` citations against BibTeX/BibLaTeX `.bib` files and
+ * Resolves `cite:[key]` citations against BibTeX/BibLaTeX `.bib` files and
  * generates a categorized bibliography partial. Numbering is a PDF/Antora
  * Assembler-flattened-output concept only; ordinary, non-assembled HTML
  * citations render a templated author/year fragment instead, carrying no
@@ -17,7 +17,7 @@
  * autoterm's `mergeTerminology` already establishes.
  *
  * Each category generates its OWN partial (`categoryPartialName`,
- * `<output_partial>-<ref_section>.adoc`). A component author routes a
+ * `<output_partial>-<ref_category>.adoc`). A component author routes a
  * category to whichever page they choose, simply by including that
  * category's own partial there; different categories may genuinely live
  * on different pages, and citations correctly cross-link to whichever
@@ -41,7 +41,7 @@
  * generated-partial injection are real per-build cost, so a component
  * shouldn't pay it just because a sibling component happens to use
  * cite-it). In practice this produced a bad failure mode: a page citing
- * a key with `citeit:[key]` in a component-version that forgot the
+ * a key with `cite:[key]` in a component-version that forgot the
  * `ext.cite_it` block either silently rendered an unrelated component's
  * entry (if the key happened to collide) or a generic "unknown key"
  * message that read like a typo rather than "this component-version
@@ -58,10 +58,10 @@
  * for trademark-it/autoterm: declared once, inherited by every
  * component-version automatically. A component-version's own
  * `ext.cite_it.categories`, if present at all, is entirely optional and
- * purely additive to the scaffold, matched by `ref_section` (see
- * mergeCategoriesConfig): naming a section already in the scaffold
+ * purely additive to the scaffold, matched by `ref_category` (see
+ * mergeCategoriesConfig): naming a category already in the scaffold
  * extends it (its `ref_files`/`ref_force` append to the scaffold's),
- * and naming a new section adds a category local to that component
+ * and naming a new category adds one local to that component
  * alone. A component-version with
  * genuinely no categories anywhere, no playbook scaffold and no local
  * `ext.cite_it.categories`, is still skipped: there is nothing to scan
@@ -77,7 +77,7 @@
  *         # Only 'ieee-bracket' is bundled and supported in this version.
  *         style: 'ieee-bracket'
  *         # Base filename for each category's own generated partial
- *         # (e.g. section "standards" -> generated-bibliography-
+ *         # (e.g. category "standards" -> generated-bibliography-
  *         # standards.adoc), one per category, injected into each
  *         # participating component-version.
  *         output_partial: 'generated-bibliography.adoc'
@@ -88,12 +88,12 @@
  *         write_to_disk: false
  *         # The global scaffold: every participating component-version
  *         # inherits these categories as-is unless it names the same
- *         # ref_section itself, in which case its own entry extends this
+ *         # ref_category itself, in which case its own entry extends this
  *         # one rather than replacing it.
  *         categories:
- *           - ref_section: standards
+ *           - ref_category: standards
  *             ref_files: ['cite-it-data:ROOT:partial$standards.bib']
- *           - ref_section: literature
+ *           - ref_category: literature
  *             ref_files: ['cite-it-data:ROOT:partial$literature-shared.bib']
  *             ref_force: ['rfc2119']
  *
@@ -112,19 +112,19 @@
  * ext:
  *   cite_it: {}
  *
- * A component needing a local-only addition to an existing section, or a
+ * A component needing a local-only addition to an existing category, or a
  * wholly local category the scaffold does not define, adds only that:
  *
  * ext:
  *   cite_it:
  *     categories:
- *       # Extends the scaffold's own "literature" section (above) with one
+ *       # Extends the scaffold's own "literature" category (above) with one
  *       # more file, appended after the scaffold's own ref_files.
- *       - ref_section: literature
+ *       - ref_category: literature
  *         ref_files: ['literature-local.bib']
- *       # A section the scaffold does not define at all: local to this
+ *       # A category the scaffold does not define at all: local to this
  *       # component only.
- *       - ref_section: internal-notes
+ *       - ref_category: internal-notes
  *         ref_files: ['internal-notes.bib']
  *
  * `.bib` files are resolved from the content catalog's `partial` family,
@@ -172,7 +172,7 @@
  * reading the `.bib` file directly. Bibtex itself carries no native
  * concept of an outdated reference; this is a cite-it-specific convention,
  * not a standard `.bib` field any external tool is expected to recognize.
- * Deliberately not raised again at each `citeit:[key]` use site in prose,
+ * Deliberately not raised again at each `cite:[key]` use site in prose,
  * one signal per generated partial is enough; managing `.bib` data itself,
  * including deciding when an entry is superseded, stays outside cite-it's
  * own scope (see the docs page's own "Scope" section).
@@ -281,12 +281,12 @@ function parseCategoriesConfig(v) {
         if (!raw || typeof raw !== 'object')
             continue;
         const r = raw;
-        const section = typeof r['ref_section'] === 'string' ? r['ref_section']
-            : typeof r['refSection'] === 'string' ? r['refSection'] : '';
-        if (!section)
+        const category = typeof r['ref_category'] === 'string' ? r['ref_category']
+            : typeof r['refCategory'] === 'string' ? r['refCategory'] : '';
+        if (!category)
             continue;
         result.push({
-            ref_section: section,
+            ref_category: category,
             ref_files: toStringArray(r['ref_files'] ?? r['refFiles']),
             ref_force: toStringArray(r['ref_force'] ?? r['refForce']),
         });
@@ -294,25 +294,25 @@ function parseCategoriesConfig(v) {
     return result;
 }
 // The playbook-level scaffold and a component's own categories[] merge by
-// ref_section, the same shared-then-local-override precedence autoterm's
+// ref_category, the same shared-then-local-override precedence autoterm's
 // mergeTerminology and a single category's own ref_files list both already
-// establish: a section named at both levels extends (ref_files/ref_force
-// concatenate, playbook first) rather than replaces, and a section named
-// only at the component level is added as a wholly local category.
+// establish: a category named at both levels extends (ref_files/ref_force
+// concatenate, playbook first) rather than replaces, and a category named
+// only at the component level is added as a wholly local one.
 function mergeCategoriesConfig(scaffold, local) {
-    const bySection = new Map();
+    const byCategory = new Map();
     for (const cat of scaffold)
-        bySection.set(cat.ref_section, { ...cat });
+        byCategory.set(cat.ref_category, { ...cat });
     for (const cat of local) {
-        const existing = bySection.get(cat.ref_section);
-        bySection.set(cat.ref_section, existing ? {
-            ref_section: cat.ref_section,
+        const existing = byCategory.get(cat.ref_category);
+        byCategory.set(cat.ref_category, existing ? {
+            ref_category: cat.ref_category,
             ref_files: [...existing.ref_files, ...cat.ref_files],
             ref_force: [...existing.ref_force, ...cat.ref_force],
         } : cat);
     }
-    return [...bySection.values()].map((cat) => ({
-        ref_section: cat.ref_section,
+    return [...byCategory.values()].map((cat) => ({
+        ref_category: cat.ref_category,
         ref_files: cat.ref_files,
         ref_force: cat.ref_force,
     }));
@@ -371,11 +371,11 @@ function resolveBibFiles(refs, contentCatalog, component, version, module, logge
     return result;
 }
 // ---------------------------------------------------------------------------
-// Orphaned citeit:[key] usage: a component-version that is not scanned
+// Orphaned cite:[key] usage: a component-version that is not scanned
 // ---------------------------------------------------------------------------
 /**
  * Checks a SKIPPED (non-participating) component-version's own pages for
- * `citeit:[key]` usage that will never resolve, and records any found into
+ * `cite:[key]` usage that will never resolve, and records any found into
  * `orphanedCiteKeys` (macro.ts) for the macro to detect at render time and
  * report clearly, instead of either silently borrowing an unrelated
  * component's data through the cross-component fallback (if the key
@@ -399,7 +399,7 @@ function resolveBibFiles(refs, contentCatalog, component, version, module, logge
  * cite-it.adoc's own siblings) from being misreported.
  *
  * A cheap substring pre-check gates the real, Asciidoctor-based scan
- * (`scanCiteKeys`): a component-version that never mentions `citeit:[` at
+ * (`scanCiteKeys`): a component-version that never mentions `cite:[` at
  * all pays nothing beyond a plain string search per page.
  */
 function checkOrphanedCiteUsage(compKey, reason, contentCatalog, component, version, logger) {
@@ -412,7 +412,7 @@ function checkOrphanedCiteUsage(compKey, reason, contentCatalog, component, vers
     const found = new Set();
     for (const f of pages) {
         const raw = f.contents.toString('utf8');
-        if (!raw.includes('citeit:['))
+        if (!raw.includes('cite:['))
             continue;
         const headerAttrs = (0, asciidoc_conditionals_1.pageHeaderAttributes)(raw);
         const isDefined = (attr) => {
@@ -428,7 +428,7 @@ function checkOrphanedCiteUsage(compKey, reason, contentCatalog, component, vers
     if (found.size === 0)
         return;
     macro_1.orphanedCiteKeys.set(compKey, found);
-    logger.warn(`cite-it: ${compKey} - ${reason}, but citeit:[${[...found].join('], citeit:[')}] is used directly on its own page(s); ` +
+    logger.warn(`cite-it: ${compKey} - ${reason}, but cite:[${[...found].join('], cite:[')}] is used directly on its own page(s); ` +
         'these citations will not resolve for this component-version, regardless of the playbook-level configuration');
 }
 // ---------------------------------------------------------------------------
@@ -444,6 +444,7 @@ function register(context) {
         output_partial: 'generated-bibliography.adoc',
         suppress_events: false,
         write_to_disk: false,
+        blanket_pubstate: false,
         categories: [],
     };
     const extByCompVer = new Map();
@@ -480,7 +481,7 @@ function register(context) {
     // inside ITS OWN navigationBuilt listener instead, as an earlier version
     // of this code did, whichever extension's navigationBuilt listener runs
     // first would win: a playbook that lists cite-it after
-    // `@antora/pdf-extension` would silently get unrewritten citeit:[key]
+    // `@antora/pdf-extension` would silently get unrewritten cite:[key]
     // literal text in PDF output, no error, no warning, since
     // assembleContent's own loadAsciiDoc reference would already be frozen to
     // the original, unwrapped function before cite-it's replaceFunctions call
@@ -509,6 +510,7 @@ function register(context) {
             const [origFile, catalog, asciidocConfig] = args;
             let file = origFile;
             const isAssembled = !!(asciidocConfig?.attributes && 'loader-assembler' in asciidocConfig.attributes);
+            let restoreForeignPages;
             if (isAssembled && file?.contents && file.src?.component && file.src?.version) {
                 const compKey = `${file.src.component}@${file.src.version}`;
                 // @antora/assembler resolves the active profile as
@@ -532,11 +534,17 @@ function register(context) {
                         file = Object.assign(Object.create(Object.getPrototypeOf(file)), file, { contents: Buffer.from(after, 'utf8') });
                     }
                 }
+                restoreForeignPages = rewriteForeignCitedPages(file.src, profileName);
             }
             // realLoadAsciiDoc is always assigned by this point: this closure is
             // only ever reachable after the synchronous assignment a few lines
             // above it in this same if-block has already run.
-            return realLoadAsciiDoc(file, catalog, asciidocConfig ?? {});
+            try {
+                return realLoadAsciiDoc(file, catalog, asciidocConfig ?? {});
+            }
+            finally {
+                restoreForeignPages?.();
+            }
         };
         ctx.replaceFunctions({ loadAsciiDoc: loadAsciiDocWrapper });
     }
@@ -561,6 +569,7 @@ function register(context) {
             output_partial: String(pick(raw, ['output_partial', 'outputPartial'], cfg.output_partial)),
             suppress_events: toBool(pick(raw, ['suppress_events', 'suppressEvents'], cfg.suppress_events), cfg.suppress_events),
             write_to_disk: toBool(pick(raw, ['write_to_disk', 'writeToDisk'], cfg.write_to_disk), cfg.write_to_disk),
+            blanket_pubstate: toBool(pick(raw, ['blanket_pubstate', 'blanketPubstate'], cfg.blanket_pubstate), cfg.blanket_pubstate),
             categories: Array.isArray(raw['categories']) ? parseCategoriesConfig(raw['categories']) : cfg.categories,
         };
         quietMode = cfg.quiet;
@@ -595,7 +604,7 @@ function register(context) {
                 }
                 // The playbook-level categories scaffold needs no counterpart here
                 // at all: a component's own categories[] is entirely optional,
-                // additive to the scaffold by ref_section. See
+                // additive to the scaffold by ref_category. See
                 // mergeCategoriesConfig for the actual merge.
                 const categories = mergeCategoriesConfig(cfg.categories, parseCategoriesConfig(compExt['categories']));
                 if (categories.length === 0) {
@@ -622,6 +631,7 @@ function register(context) {
                 const compStyle = typeof compExt['style'] === 'string' ? compExt['style'] : cfg.style;
                 const compOutPartial = typeof compExt['output_partial'] === 'string' ? compExt['output_partial'] : cfg.output_partial;
                 const compWriteToDisk = toBool(compExt['write_to_disk'] ?? compExt['writeToDisk'], cfg.write_to_disk);
+                const compBlanketPubstate = toBool(compExt['blanket_pubstate'] ?? compExt['blanketPubstate'], cfg.blanket_pubstate);
                 const module = files.find((f) => f.src.family === 'page')?.src.module ?? 'ROOT';
                 // A page's own include::partial$<category-partial>[] is resolved
                 // as part of the scan below (collectIncludeText walks every
@@ -640,8 +650,8 @@ function register(context) {
                 // component-version turns out to have any real citation usage at
                 // all, which the scan below has not yet determined at this point.
                 const categoryPartials = categories.map((cat) => ({
-                    section: cat.ref_section,
-                    relative: categoryPartialName(compOutPartial, cat.ref_section),
+                    category: cat.ref_category,
+                    relative: categoryPartialName(compOutPartial, cat.ref_category),
                 }));
                 for (const cp of categoryPartials) {
                     (0, index_2.injectPartial)(contentCatalog, files, component, version, module, cp.relative, '', false, logger);
@@ -654,7 +664,7 @@ function register(context) {
                 // stale snapshot from before they existed.
                 files = contentCatalog.getFiles().filter((f) => f.src.component === component && f.src.version === version);
                 // ---------------------------------------------------------------
-                // 1. Scan pages (+ resolved includes) for citeit:[key] usage,
+                // 1. Scan pages (+ resolved includes) for cite:[key] usage,
                 //    through a real Asciidoctor conversion (macro.ts's
                 //    scanCiteKeys), not a hand-rolled regex. Runs BEFORE ever
                 //    resolving or reading a single .bib file: the playbook-level
@@ -666,7 +676,7 @@ function register(context) {
                 //    unconditionally, warning "not found" for files it never had
                 //    any reason to carry. Scanning first and skipping entirely
                 //    when nothing was found (see below) means a component-version
-                //    with zero real citeit:[] usage anywhere never even looks for
+                //    with zero real cite:[] usage anywhere never even looks for
                 //    its category files in the first place, rather than looking
                 //    and then discovering there was nothing to find. Placeholder
                 //    injection above still runs unconditionally either way: it
@@ -721,7 +731,7 @@ function register(context) {
                 const anyForced = categories.some((cat) => cat.ref_force.length > 0);
                 if (citedKeys.size === 0 && !anyForced) {
                     const hasOwnExt = extByCompVer.has(compKey);
-                    const message = `cite-it: ${compKey} - skipped (no citeit:[key] usage anywhere and no ref_force entries in any category)`;
+                    const message = `cite-it: ${compKey} - skipped (no cite:[key] usage anywhere and no ref_force entries in any category)`;
                     if (hasOwnExt)
                         logger.warn(message);
                     else
@@ -749,14 +759,14 @@ function register(context) {
                     }
                     const keys = new Set();
                     for (const [key, entry] of catEntries) {
-                        if (keyCategory.has(key) && keyCategory.get(key) !== cat.ref_section) {
-                            logger.warn(`cite-it: ${compKey} - citation key "${key}" appears in both category "${keyCategory.get(key)}" and "${cat.ref_section}"; the later category's membership wins`);
+                        if (keyCategory.has(key) && keyCategory.get(key) !== cat.ref_category) {
+                            logger.warn(`cite-it: ${compKey} - citation key "${key}" appears in both category "${keyCategory.get(key)}" and "${cat.ref_category}"; the later category's membership wins`);
                         }
-                        keyCategory.set(key, cat.ref_section);
+                        keyCategory.set(key, cat.ref_category);
                         combinedEntries.set(key, entry);
                         keys.add(key);
                     }
-                    categoryKeys.set(cat.ref_section, keys);
+                    categoryKeys.set(cat.ref_category, keys);
                 }
                 // A key claimed by more than one category was added to every
                 // claiming category's own Set above, since each category's loop
@@ -786,15 +796,15 @@ function register(context) {
                 for (const cat of categories) {
                     for (const key of cat.ref_force) {
                         if (!combinedEntries.has(key)) {
-                            logger.warn(`cite-it: ${compKey} - ref_force names unknown key "${key}" in category "${cat.ref_section}"; not found in any configured category's data`);
+                            logger.warn(`cite-it: ${compKey} - ref_force names unknown key "${key}" in category "${cat.ref_category}"; not found in any configured category's data`);
                             continue;
                         }
-                        const previousSection = keyCategory.get(key);
-                        if (previousSection && previousSection !== cat.ref_section) {
-                            categoryKeys.get(previousSection)?.delete(key);
+                        const previousCategory = keyCategory.get(key);
+                        if (previousCategory && previousCategory !== cat.ref_category) {
+                            categoryKeys.get(previousCategory)?.delete(key);
                         }
-                        keyCategory.set(key, cat.ref_section);
-                        categoryKeys.get(cat.ref_section)?.add(key);
+                        keyCategory.set(key, cat.ref_category);
+                        categoryKeys.get(cat.ref_category)?.add(key);
                     }
                 }
                 if (!cfg.suppress_events) {
@@ -802,11 +812,11 @@ function register(context) {
                 }
                 for (const key of citedKeys) {
                     if (!combinedEntries.has(key)) {
-                        logger.warn(`cite-it: ${compKey} - citeit:[${key}] cites an unknown key; not found in any configured category`);
+                        logger.warn(`cite-it: ${compKey} - cite:[${key}] cites an unknown key; not found in any configured category`);
                     }
                 }
                 // ---------------------------------------------------------------
-                // 3. Populate the shared cache the citeit:[key] macro reads at
+                // 3. Populate the shared cache the cite:[key] macro reads at
                 //    real conversion time (macro.ts). Formatted only for keys
                 //    actually used (cited, or ref_force), same set the
                 //    generated partial lists.
@@ -815,10 +825,10 @@ function register(context) {
                 const usedKeysByCategory = new Map();
                 const allUsedKeys = [];
                 for (const cat of categories) {
-                    const keys = [...(categoryKeys.get(cat.ref_section) ?? new Set())]
+                    const keys = [...(categoryKeys.get(cat.ref_category) ?? new Set())]
                         .filter((k) => citedKeys.has(k) || refForceKeys.has(k))
                         .sort((a, b) => a.localeCompare(b));
-                    usedKeysByCategory.set(cat.ref_section, keys);
+                    usedKeysByCategory.set(cat.ref_category, keys);
                     allUsedKeys.push(...keys);
                 }
                 // A key's entry carrying a supersededby field (registry.ts) warns
@@ -826,18 +836,18 @@ function register(context) {
                 // partial actually lists (cited or ref_force'd), not every entry
                 // the registry happens to hold: an unused entry going stale is not
                 // this component-version's problem to flag. Deliberately not
-                // raised again at each citeit:[key] use site (macro.ts): one clear
+                // raised again at each cite:[key] use site (macro.ts): one clear
                 // signal per generated partial, not one per occurrence in prose.
-                for (const [section, keys] of usedKeysByCategory) {
+                for (const [category, keys] of usedKeysByCategory) {
                     for (const key of keys) {
                         const supersededBy = combinedEntries.get(key)?.['supersededby'];
                         if (typeof supersededBy === 'string' && supersededBy) {
-                            logger.warn(`cite-it: ${compKey} - citation "${key}" in category "${section}" carries supersededby "${supersededBy}"; a newer revision is available`);
+                            logger.warn(`cite-it: ${compKey} - citation "${key}" in category "${category}" carries supersededby "${supersededBy}"; a newer revision is available`);
                         }
                     }
                 }
-                const formattedByKey = (0, csl_1.formatBibliographyEntries)(compStyle, combinedEntries, allUsedKeys);
-                const cacheData = { entriesByKey: combinedEntries, formattedByKey };
+                const formattedByKey = (0, csl_1.formatBibliographyEntries)(compStyle, combinedEntries, allUsedKeys, compBlanketPubstate);
+                const cacheData = { entriesByKey: combinedEntries, formattedByKey, blanketPubstate: compBlanketPubstate };
                 macro_1.citeCache.set(compKey, cacheData);
                 assemblyScanContexts.set(compKey, {
                     contentCatalog: contentCatalog,
@@ -855,8 +865,8 @@ function register(context) {
                 //    which category's partial.
                 // ---------------------------------------------------------------
                 for (const cp of categoryPartials) {
-                    const cat = categories.find((c) => c.ref_section === cp.section);
-                    const keys = usedKeysByCategory.get(cat.ref_section) ?? [];
+                    const cat = categories.find((c) => c.ref_category === cp.category);
+                    const keys = usedKeysByCategory.get(cat.ref_category) ?? [];
                     const content = generateCategoryPartial(keys, formattedByKey);
                     (0, index_2.injectPartial)(contentCatalog, files, component, version, module, cp.relative, content, compWriteToDisk, logger);
                 }
@@ -874,7 +884,7 @@ function register(context) {
     // of this code did (the earlier version genuinely raced against
     // `@antora/assembler`'s own navigationBuilt listener and lost against a
     // real playbook where `@antora/pdf-extension` preceded cite-it in
-    // `antora.extensions`, leaving every citeit:[key] unrewritten with no
+    // `antora.extensions`, leaving every cite:[key] unrewritten with no
     // error). Computing lazily on first actual use, inside this same wrapper
     // invocation, sidesteps that race entirely regardless of extension order.
     //
@@ -1053,7 +1063,7 @@ function register(context) {
         for (const cat of missingScopeCategories) {
             logger.warn(`cite-it: ${compKey} - could not find the page that includes category "${cat}"'s generated partial; its citation links will render as plain numbers, not clickable links`);
         }
-        // The generated bibliography partial's own citeit:[key] row labels
+        // The generated bibliography partial's own cite:[key] row labels
         // need rewriting too, and specifically now, before any assembly-time
         // loadAsciiDoc call resolves an include:: of it: Antora's include
         // processor reads an included partial's content directly from the
@@ -1064,6 +1074,89 @@ function register(context) {
         // the wrapper, before that same invocation's real loadAsciiDoc call.
         (0, assembly_numbering_1.rewritePartialForAssembly)(scanCtx, numbers);
     }
+    // Per participating component-version, the pages whose raw source
+    // carries a cite:[ marker at all. Memoized on first use: the set is
+    // fixed by contentClassified time, and rewriteForeignCitedPages below
+    // runs once per assembled page load, site-wide.
+    const citedPagesByComp = new Map();
+    function rawSourceHolder(f) {
+        const src = f.src;
+        return src.contents !== undefined ? src : f;
+    }
+    // ---------------------------------------------------------------------
+    // Cross-component includes in assembled output. The wrapper above
+    // rewrites only the buffer @antora/assembler hands to loadAsciiDoc, the
+    // page's own source. A page whose body is `include::other:ROOT:page$x.adoc[]`
+    // carries no citation of its own, and Antora's include processor then
+    // reads the included page (and, through it, the included bibliography
+    // partial) straight from the catalog, never back through loadAsciiDoc.
+    // Confirmed live: a component's own PDF rendered `[1]` correctly while a
+    // sibling component wrapping the same page in an include:: shipped the
+    // literal `cite:[key]` text, both inline and as the bibliography's own
+    // row label, since Ruby asciidoctor-pdf has no citeit macro.
+    //
+    // For the duration of one real loadAsciiDoc call, every cited page of
+    // every OTHER participating component-version is rewritten in the
+    // catalog with its OWN component's numbers (the same numbering the
+    // included partial, already rewritten by rewritePartialForAssembly, now
+    // carries), then restored in the wrapper's finally block. Computing
+    // every other component's numbers here, rather than only the loaded
+    // page's own, also removes an ordering dependency: a wrapper component
+    // assembled BEFORE the component it includes used to see that partial
+    // still unrewritten, because rewritePartialForAssembly had not yet run
+    // for it.
+    //
+    // A link target exists only when the included page itself hosts the
+    // key's bibliography anchor: the anchor then lands inside the loaded
+    // page's own fragment of the assembly, so the xref names the loaded
+    // page, not the source page (an unqualified `xref:<page>.adoc` resolves
+    // against the including document's component, where the source page's
+    // name need not exist). Any other key is rewritten to a plain, unlinked
+    // number, the same known-correct-but-unlinked fallback rewriteCiteMarkers
+    // already applies to a key with no scope.
+    // ---------------------------------------------------------------------
+    function rewriteForeignCitedPages(loadedSrc, profileName) {
+        const loadedKey = `${loadedSrc.component}@${loadedSrc.version}`;
+        const loadedDocname = (loadedSrc.relative ?? '').replace(/\.[^./]+$/, '');
+        const restores = [];
+        for (const [compKey, scanCtx] of assemblyScanContexts) {
+            if (compKey === loadedKey)
+                continue;
+            ensureAssemblyDataComputed(compKey, profileName);
+            const numbers = citationNumbers.get(compKey);
+            if (!numbers || numbers.size === 0)
+                continue;
+            const hostScopes = keyScopesByComp.get(compKey) ?? new Map();
+            let pages = citedPagesByComp.get(compKey);
+            if (!pages) {
+                pages = scanCtx.contentCatalog.getFiles().filter((f) => f.src.component === scanCtx.component &&
+                    f.src.version === scanCtx.version &&
+                    f.src.family === 'page' &&
+                    Buffer.from(rawSourceHolder(f).contents).toString('utf8').includes('cite:['));
+                citedPagesByComp.set(compKey, pages);
+            }
+            for (const page of pages) {
+                const pageDocname = (page.src.relative ?? '').replace(/\.[^./]+$/, '');
+                const scopes = new Map();
+                for (const [key, host] of hostScopes) {
+                    if (host === pageDocname)
+                        scopes.set(key, loadedDocname);
+                }
+                const holder = rawSourceHolder(page);
+                const original = holder.contents;
+                const before = Buffer.from(original).toString('utf8');
+                const after = (0, assembly_numbering_1.rewriteCiteMarkers)(before, numbers, true, scopes);
+                if (after === before)
+                    continue;
+                holder.contents = Buffer.from(after, 'utf8');
+                restores.push(() => { holder.contents = original; });
+            }
+        }
+        if (restores.length === 0)
+            return undefined;
+        return () => { for (const restore of restores)
+            restore(); };
+    }
 }
 /**
  * One category's own generated partial content: the bibliography list
@@ -1086,11 +1179,11 @@ function generateCategoryPartial(keys, formattedByKey) {
     const lines = ['[horizontal.cite-it-bibliography]'];
     for (const key of keys) {
         const text = formattedByKey.get(key) ?? `(no formatted text for "${key}")`;
-        // The [[cite-<key>]] anchor is what an inline citeit:[key] citation
+        // The [[cite-<key>]] anchor is what an inline cite:[key] citation
         // links to for assembled/PDF output (rewriteCiteMarkers, asLink:
         // true), see assembly-numbering.ts. Harmless, invisible in ordinary
         // HTML rendering.
-        lines.push(`[[cite-${key}]]citeit:[${key}]:: ${text}`);
+        lines.push(`[[cite-${key}]]cite:[${key}]:: ${text}`);
     }
     lines.push('');
     return lines.join('\n');