@baiyibai-antora/extensions 1.13.0 → 1.15.0

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

@@ -0,0 +1,1191 @@
+"use strict";
+/**
+ * @baiyibai-antora/extensions - cite-it
+ *
+ * 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
+ * number. See macro.ts and assembly-numbering.ts for the two rendering
+ * paths this splits into.
+ *
+ * A category is defined entirely by which `.bib` file(s) an entry lives in,
+ * never by a data field inside the entry. Each category is an ordered list
+ * of source files: a shared collected file first, then zero or more
+ * component-local override files; later files' entries override earlier
+ * files' entries by citation key, the same override-by-key semantics
+ * autoterm's `mergeTerminology` already establishes.
+ *
+ * Each category generates its OWN partial (`categoryPartialName`,
+ * `<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
+ * page actually hosts the cited entry (assembly-numbering.ts's
+ * `findBibliographyScopes`/`rewriteCiteMarkers`), not just a single
+ * hardcoded bibliography page.
+ *
+ * A component-version participates automatically, with no opt-in step at
+ * all: once the playbook-level `categories` scaffold (below) gives a
+ * component-version at least one category, it is scanned and gets its
+ * generated partial(s), whether or not its own antora.yml mentions
+ * cite-it at all. `ext.cite_it` in a component-version's antora.yml is
+ * purely an OPTIONAL override, the same standing as `enabled`, `style`,
+ * `output_partial`, and `write_to_disk`: present only when a component
+ * needs to diverge from the playbook default, never required just to
+ * take part.
+ *
+ * EARLIER DESIGN, REPLACED: this extension originally required an
+ * explicit `ext.cite_it` block, even an empty one, mirroring
+ * trademark-it's own opt-in gate (heavy per-page scanning and
+ * 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 `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
+ * never participated" - either way, with no diagnostic trail under the
+ * `quiet: true` every real registration uses. Removed rather than
+ * patched further: every component-version now participates by default,
+ * so there is no opt-in state left to forget. The performance tradeoff
+ * this accepts (every component-version with categories available now
+ * gets scanned, not just ones that explicitly asked to be) is a real
+ * cost, not a free lunch; it was decided against keeping the gate.
+ *
+ * `categories` in the PLAYBOOK-level `cite_it` config (below) is the
+ * real scaffold, mirroring how `trademark_file`/`terminology_file` work
+ * 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_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 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
+ * for.
+ *
+ * Configuration in antora-playbook.yml:
+ *
+ * antora:
+ *   extensions:
+ *     - require: '@baiyibai-antora/extensions/cite-it'
+ *       cite_it:
+ *         enabled: true
+ *         # Only 'ieee-bracket' is bundled and supported in this version.
+ *         style: 'ieee-bracket'
+ *         # Base filename for each category's own generated partial
+ *         # (e.g. category "standards" -> generated-bibliography-
+ *         # standards.adoc), one per category, injected into each
+ *         # participating component-version.
+ *         output_partial: 'generated-bibliography.adoc'
+ *         # Write each generated partial to disk in the component's local
+ *         # worktree too, alongside the source files, for IDE include
+ *         # resolution. Skipped automatically for a component loaded from
+ *         # a remote source (no local worktree to write into).
+ *         write_to_disk: false
+ *         # The global scaffold: every participating component-version
+ *         # inherits these categories as-is unless it names the same
+ *         # ref_category itself, in which case its own entry extends this
+ *         # one rather than replacing it.
+ *         categories:
+ *           - ref_category: standards
+ *             ref_files: ['cite-it-data:ROOT:partial$standards.bib']
+ *           - ref_category: literature
+ *             ref_files: ['cite-it-data:ROOT:partial$literature-shared.bib']
+ *             ref_force: ['rfc2119']
+ *
+ * The generated partial itself carries no heading; a category's bibliography
+ * is a `[horizontal]` list only. The page including it supplies its own
+ * heading, ordinary authored AsciiDoc, immediately above the include line:
+ *
+ * == Standards References
+ *
+ * include::partial$generated-bibliography-standards.adoc[]
+ *
+ * Per-component configuration in antora.yml, under ext.cite_it, opts a
+ * component-version into cite-it and MAY extend the playbook-level
+ * scaffold. An empty block inherits the scaffold unchanged:
+ *
+ * ext:
+ *   cite_it: {}
+ *
+ * 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" category (above) with one
+ *       # more file, appended after the scaffold's own ref_files.
+ *       - ref_category: literature
+ *         ref_files: ['literature-local.bib']
+ *       # A category the scaffold does not define at all: local to this
+ *       # component only.
+ *       - ref_category: internal-notes
+ *         ref_files: ['internal-notes.bib']
+ *
+ * `.bib` files are resolved from the content catalog's `partial` family,
+ * the same family autoterm's terminology-table.adoc and trademark-it's
+ * trademark-table.adoc already use for shared, non-rendered reference data.
+ * Neither of those is independently published either: a `.bib` file's own
+ * confidentiality comes from which repository it lives in and who can read
+ * that repository, not from its Antora family. A category's `ref_files`
+ * list is the SAME shared-then-local-override pattern autoterm/trademark-it
+ * already establish:
+ *
+ *   - A resource-ID reference (`component:module:partial$relative`, for
+ *     example `cite-it-data:ROOT:partial$standards.bib` above) resolves
+ *     against the full catalog, including a component the SAME playbook
+ *     added as its own separate `content.sources` entry. This is the
+ *     intended shape for a shared bibliography maintained in its own
+ *     repository, the same pattern `baiyibai-autoterm-data` already
+ *     establishes for autoterm's shared terminology table.
+ *   - A bare filename (`literature-local.bib` above) resolves against the
+ *     PARTICIPATING component-version's own `partial` family files only.
+ *     This is the shape for a component-local override or addition, living
+ *     alongside that component's own pages, never published on its own,
+ *     reached only through this resolution (not through `include::`, since
+ *     `.bib` files are read directly, not transcluded).
+ *
+ * `ref_force` names citation keys always listed in that category's
+ * bibliography even when no page cites them, for example a standard a
+ * component must disclose regardless of whether it is quoted inline. It is
+ * nested inside the category it targets, not a separate flat list with a
+ * back-reference: which heading a force-included citation renders under is
+ * simply which category's `ref_force` names it, independent of which
+ * category's `ref_files` actually defines the underlying entry. In the
+ * example above, `rfc2119` is force-included under the `literature` heading
+ * even if its own entry is defined inside the `standards` category's `.bib`
+ * file: a component author choosing where a force-included citation appears
+ * is a display decision, not a statement about which file happens to hold
+ * the data.
+ *
+ * A `.bib` entry's own `supersededby` field, a custom field naming the
+ * citation key of the newer entry replacing it, is not a real BibLaTeX
+ * field (see registry.ts) but is read directly from the raw parsed entry
+ * regardless. When a category's generated partial actually lists such a
+ * key (cited or `ref_force`d), cite-it warns once at generation time,
+ * naming the newer key, so an author sees a newer revision exists without
+ * 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 `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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+const log_time_1 = require("../../lib/log-time");
+const asciidoc_conditionals_1 = require("../../lib/asciidoc-conditionals");
+const asciidoc_indexterms_1 = require("../../lib/asciidoc-indexterms");
+const index_1 = require("../trademark-it/index");
+const index_2 = require("../autoterm/index");
+const registry_1 = require("./registry");
+const csl_1 = require("./csl");
+const macro_1 = require("./macro");
+const assembly_numbering_1 = require("./assembly-numbering");
+// ---------------------------------------------------------------------------
+// Logging helpers (mirrors trademark-it/autoterm style)
+// ---------------------------------------------------------------------------
+let quietMode = true;
+function logEvent(message) {
+    console.log(`[${(0, log_time_1.nowLocal)()}] \x1b[94mEVENT\x1b[0m (cite-it): \x1b[94m${message}\x1b[0m`);
+}
+function makeLogger(hostLogger) {
+    return {
+        debug: (m) => { if (!quietMode) {
+            if (hostLogger?.debug)
+                hostLogger.debug(m);
+            else
+                console.debug(m);
+        } },
+        info: (m) => { if (!quietMode) {
+            if (hostLogger?.info)
+                hostLogger.info(m);
+            else
+                console.log(m);
+        } },
+        warn: (m) => { if (hostLogger?.warn)
+            hostLogger.warn(m);
+        else
+            console.warn(m); },
+        error: (m) => { if (hostLogger?.error)
+            hostLogger.error(m);
+        else
+            console.error(m); },
+    };
+}
+// ---------------------------------------------------------------------------
+// Config helpers (mirrors trademark-it/autoterm style)
+// ---------------------------------------------------------------------------
+function toBool(v, def) {
+    if (v === true)
+        return true;
+    if (v === false)
+        return false;
+    if (typeof v === 'string') {
+        const s = v.trim().toLowerCase();
+        if (['true', '1', 'yes', 'on'].includes(s))
+            return true;
+        if (['false', '0', 'no', 'off'].includes(s))
+            return false;
+    }
+    return def;
+}
+function toStringArray(v) {
+    if (Array.isArray(v))
+        return v.map(String);
+    if (typeof v === 'string' && v.trim())
+        return v.split(',').map((s) => s.trim()).filter(Boolean);
+    return [];
+}
+/**
+ * Locates this extension's own entry in `playbook.antora.extensions` by
+ * whether it carries `cite_it`/`citeIt` as an own key, not by matching a
+ * substring of its `require` string. A require-string match breaks the
+ * moment a consumer vendors or re-exports this package under a different
+ * name or path: the require string then never contains "cite-it"/
+ * "cite_it" at all, `.find()` returns nothing, and every configured
+ * setting silently falls back to hardcoded defaults, no warning, no error
+ * (confirmed as a real report, not a hypothetical). Checking for the
+ * config key itself identifies the right entry regardless of how it was
+ * required; the require-string check remains only as a fallback for the
+ * case where no entry carries the key at all. An empty `ext.cite_it: {}`
+ * override is still caught correctly here, since the key is present even
+ * with no options set under it.
+ */
+function findOwnExtEntry(entries) {
+    return entries.find((ext) => 'cite_it' in ext || 'citeIt' in ext)
+        ?? entries.find((ext) => {
+            const req = String(ext.require ?? '');
+            return req.includes('cite-it') || req.includes('cite_it');
+        })
+        ?? {};
+}
+function pick(obj, keys, def) {
+    for (const k of keys) {
+        if (obj && obj[k] !== undefined)
+            return obj[k];
+    }
+    return def;
+}
+function parseCategoriesConfig(v) {
+    if (!Array.isArray(v))
+        return [];
+    const result = [];
+    for (const raw of v) {
+        if (!raw || typeof raw !== 'object')
+            continue;
+        const r = raw;
+        const category = typeof r['ref_category'] === 'string' ? r['ref_category']
+            : typeof r['refCategory'] === 'string' ? r['refCategory'] : '';
+        if (!category)
+            continue;
+        result.push({
+            ref_category: category,
+            ref_files: toStringArray(r['ref_files'] ?? r['refFiles']),
+            ref_force: toStringArray(r['ref_force'] ?? r['refForce']),
+        });
+    }
+    return result;
+}
+// The playbook-level scaffold and a component's own categories[] merge by
+// 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 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 byCategory = new Map();
+    for (const cat of scaffold)
+        byCategory.set(cat.ref_category, { ...cat });
+    for (const cat of local) {
+        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 [...byCategory.values()].map((cat) => ({
+        ref_category: cat.ref_category,
+        ref_files: cat.ref_files,
+        ref_force: cat.ref_force,
+    }));
+}
+/**
+ * One generated partial per category, not one combined partial for the
+ * whole component-version: the key design feature is that an author decides
+ * where each category appears simply by choosing which page includes
+ * which category's own partial, and different categories may genuinely
+ * live on different pages, with citations correctly cross-linking to
+ * whichever page actually hosts the cited entry (see assembly-
+ * numbering.ts's `findBibliographyScopes`/`rewriteCiteMarkers`).
+ * `generated-bibliography.adoc` + category `standards` becomes
+ * `generated-bibliography-standards.adoc`.
+ */
+function categoryPartialName(base, categoryKey) {
+    const dot = base.lastIndexOf('.');
+    return dot < 0 ? `${base}-${categoryKey}` : `${base.slice(0, dot)}-${categoryKey}${base.slice(dot)}`;
+}
+// ---------------------------------------------------------------------------
+// `.bib` file resolution
+// ---------------------------------------------------------------------------
+const RESOURCE_ID_RE = /[:$]/;
+/** `.bib` files live in the `partial` family: never independently
+ * published, and the same family autoterm/trademark-it already use for
+ * shared reference data collected from another repository. A resource-ID
+ * reference resolves against the full catalog (including a separate
+ * `content.sources` entry the playbook adds for a shared data component);
+ * a bare filename resolves only against the participating component-
+ * version's own `partial` family files (a local override or addition).
+ */
+function resolveBibFiles(refs, contentCatalog, component, version, module, logger) {
+    const result = [];
+    for (const ref of refs) {
+        let file;
+        if (RESOURCE_ID_RE.test(ref) && contentCatalog.resolveResource) {
+            try {
+                file = contentCatalog.resolveResource(ref, { component, version, module }, 'partial');
+            }
+            catch {
+                file = undefined;
+            }
+        }
+        if (!file) {
+            file = contentCatalog.getFiles().find((f) => f.src.component === component &&
+                f.src.version === version &&
+                f.src.family === 'partial' &&
+                (f.src.relative === ref || f.src.basename === ref));
+        }
+        if (!file) {
+            logger.warn(`cite-it: .bib file "${ref}" not found (expected family 'partial') for ${component}@${version}`);
+            continue;
+        }
+        result.push(file);
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Orphaned cite:[key] usage: a component-version that is not scanned
+// ---------------------------------------------------------------------------
+/**
+ * Checks a SKIPPED (non-participating) component-version's own pages for
+ * `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
+ * happens to collide) or rendering a generic "unknown key" message that
+ * reads like a typo rather than "this component-version is not scanned".
+ *
+ * There is no opt-in gate to forget any more (see the module docblock):
+ * a component-version only reaches here for two real reasons, explicitly
+ * disabled (`ext.cite_it.enabled: false`) or genuinely no categories
+ * anywhere, no playbook scaffold and no local `ext.cite_it.categories`.
+ * Both are still worth flagging if the component-version's own pages cite
+ * something anyway, since the citation still cannot resolve.
+ *
+ * Deliberately does NOT resolve `include::` content, unlike the real scan
+ * pass for a participating component (which calls `collectIncludeText`):
+ * a wrapper page whose entire content is `include::other-component:...[]`
+ * correctly has nothing of its OWN to flag here, since the included
+ * content belongs to, and was authored for, a genuinely participating
+ * component. This is exactly what keeps the demo site's own
+ * include::-based wrapper pages (autoterm.adoc, trademark-it.adoc,
+ * 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 `cite:[` at
+ * all pays nothing beyond a plain string search per page.
+ */
+function checkOrphanedCiteUsage(compKey, reason, contentCatalog, component, version, logger) {
+    const pages = contentCatalog.getFiles().filter((f) => f.src.component === component && f.src.version === version && f.src.family === 'page');
+    if (pages.length === 0)
+        return;
+    const componentAttrs = (contentCatalog.getComponents?.() ?? [])
+        .find((c) => c.name === component)?.versions
+        .find((v) => (v.version ?? v.name) === version)?.asciidoc?.attributes ?? {};
+    const found = new Set();
+    for (const f of pages) {
+        const raw = f.contents.toString('utf8');
+        if (!raw.includes('cite:['))
+            continue;
+        const headerAttrs = (0, asciidoc_conditionals_1.pageHeaderAttributes)(raw);
+        const isDefined = (attr) => {
+            if (headerAttrs.has(attr))
+                return headerAttrs.get(attr) === true;
+            const v = componentAttrs[attr];
+            return v !== undefined && v !== null && v !== false;
+        };
+        const text = (0, index_1.stripNonContent)(raw, isDefined, []);
+        for (const key of (0, macro_1.scanCiteKeys)((0, asciidoc_indexterms_1.sanitizeForScan)(text)))
+            found.add(key);
+    }
+    if (found.size === 0)
+        return;
+    macro_1.orphanedCiteKeys.set(compKey, found);
+    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');
+}
+// ---------------------------------------------------------------------------
+// Antora extension entry point
+// ---------------------------------------------------------------------------
+function register(context) {
+    const ctx = context ?? this;
+    const logger = makeLogger(ctx.getLogger ? ctx.getLogger('cite-it') : undefined);
+    let cfg = {
+        enabled: true,
+        quiet: true,
+        style: 'ieee-bracket',
+        output_partial: 'generated-bibliography.adoc',
+        suppress_events: false,
+        write_to_disk: false,
+        blanket_pubstate: false,
+        categories: [],
+    };
+    const extByCompVer = new Map();
+    // Per-component-version scan context, captured during contentClassified
+    // and reused by the navigationBuilt handler below to compute true
+    // first-appearance citation numbers for PDF/assembled output, avoiding
+    // recomputing config resolution twice for the same component-version.
+    const assemblyScanContexts = new Map();
+    // component@version -> citation key -> owning category key. Needed at
+    // navigationBuilt time to turn findBibliographyScopes' per-CATEGORY
+    // page map into the per-KEY page map rewriteCiteMarkers actually needs.
+    const keyCategories = new Map();
+    // Populated later, at navigationBuilt time (see below), but declared here
+    // so the loadAsciiDoc wrapper registered immediately below can close over
+    // them: real content is not known yet when the wrapper is REGISTERED, only
+    // by the time it is actually CALLED, which is guaranteed to be later.
+    const citationNumbers = new Map();
+    const keyScopesByComp = new Map();
+    // Populated inside the if-block below, but declared here so
+    // ensureAssemblyDataComputed's own navigation self-heal (defined later
+    // in this same function) can reach both: the real, unwrapped loader,
+    // and this wrapper's own reference, needed to temporarily swap the
+    // wrapper back out and reinstall it. See that self-heal's own docblock
+    // for why.
+    let realLoadAsciiDoc;
+    let loadAsciiDocWrapper;
+    // The loadAsciiDoc wrapper is registered here, synchronously, at
+    // register() time itself, deliberately BEFORE any lifecycle event fires
+    // at all. `@antora/assembler`'s own assembleContent reads
+    // `context.getFunctions().loadAsciiDoc` exactly ONCE, synchronously, at
+    // the top of its own navigationBuilt listener, not lazily at the point it
+    // actually calls loadAsciiDoc, confirmed directly by reading
+    // assemble-content.js. If cite-it's own replaceFunctions call happened
+    // 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 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
+    // ever ran. Registering here, at register() time, fires before every
+    // playbookBuilt/contentClassified/navigationBuilt listener regardless of
+    // where cite-it appears in the extensions list, so this no longer depends
+    // on registration order at all.
+    if (ctx.getFunctions && ctx.replaceFunctions && ctx.require) {
+        // Captured ONCE, right here, BEFORE replaceFunctions below installs the
+        // wrapper: reading getFunctions().loadAsciiDoc lazily INSIDE the
+        // wrapper itself, instead, would read back the wrapper's own already-
+        // installed replacement rather than the original, an infinite
+        // recursion confirmed directly (a real "Maximum call stack size
+        // exceeded" crash against a live build, not a hypothetical). The
+        // fallback to `@antora/asciidoc-loader`'s own export, for the case
+        // getFunctions() does not carry a real loadAsciiDoc yet this early in
+        // the lifecycle, mirrors exactly what `@antora/assembler`'s own
+        // assemble-content.js does for the same reason.
+        const realLoadAsciiDocFn = (ctx.getFunctions().loadAsciiDoc ??
+            ctx.require('@antora/asciidoc-loader').loadAsciiDoc);
+        realLoadAsciiDoc = realLoadAsciiDocFn;
+        // Named, not inline, so ensureAssemblyDataComputed's own navigation
+        // self-heal can reinstall this SAME reference after temporarily
+        // swapping it out; see that function's own docblock for why.
+        loadAsciiDocWrapper = (...args) => {
+            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
+                // assemblyConfig.profile, defaulting to the export's own target
+                // backend (e.g. 'pdf') when no profile is configured explicitly
+                // — never bare `undefined` in an ordinary PDF build — then bakes
+                // it into every assembled document's own real attributes as
+                // 'assembler-profile' (assemble-content.js: intrinsicAttributes),
+                // right here in this same asciidocConfig. Passed through so
+                // ensureAssemblyDataComputed can look up navFiles under the
+                // SAME profile key assembler itself resolved, instead of always
+                // checking the unnamed default profile slot.
+                const profileName = asciidocConfig?.attributes?.['assembler-profile'];
+                ensureAssemblyDataComputed(compKey, profileName);
+                const numbers = citationNumbers.get(compKey);
+                if (numbers && numbers.size > 0) {
+                    const keyScopes = keyScopesByComp.get(compKey) ?? null;
+                    const before = file.contents.toString('utf8');
+                    const after = (0, assembly_numbering_1.rewriteCiteMarkers)(before, numbers, true, keyScopes);
+                    if (after !== before) {
+                        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.
+            try {
+                return realLoadAsciiDoc(file, catalog, asciidocConfig ?? {});
+            }
+            finally {
+                restoreForeignPages?.();
+            }
+        };
+        ctx.replaceFunctions({ loadAsciiDoc: loadAsciiDocWrapper });
+    }
+    else {
+        logger.warn('cite-it: replaceFunctions/getFunctions/require unavailable on this extension context; PDF/assembled numbering will not be applied (ordinary HTML citations are unaffected)');
+    }
+    ctx.once('contentAggregated', ({ contentAggregate }) => {
+        for (const item of (contentAggregate ?? [])) {
+            const ciExt = item.ext?.['cite_it'];
+            if (ciExt && typeof ciExt === 'object') {
+                extByCompVer.set(`${item.name}@${item.version}`, ciExt);
+            }
+        }
+    });
+    ctx.once('playbookBuilt', async ({ playbook }) => {
+        const extEntry = findOwnExtEntry(playbook?.antora?.extensions ?? []);
+        const raw = (extEntry.cite_it ?? extEntry.citeIt ?? {});
+        cfg = {
+            enabled: toBool(pick(raw, ['enabled'], cfg.enabled), cfg.enabled),
+            quiet: toBool(pick(raw, ['quiet'], cfg.quiet), cfg.quiet),
+            style: String(pick(raw, ['style'], cfg.style)),
+            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;
+        logger.debug(`cite-it config: ${JSON.stringify(cfg)}`);
+    });
+    ctx.once('contentClassified', async ({ contentCatalog }) => {
+        if (!cfg.enabled) {
+            logger.debug('cite-it disabled (skipped)');
+            return;
+        }
+        if (!contentCatalog) {
+            logger.error('contentCatalog is missing');
+            return;
+        }
+        logEvent('Executing cite-it');
+        const componentVersions = (0, index_1.getComponentVersions)(contentCatalog);
+        for (const [component, versions] of componentVersions) {
+            for (const version of versions) {
+                const compKey = `${component}@${version}`;
+                // No opt-in gate: a component-version participates automatically
+                // once the playbook-level scaffold (or its own ext.cite_it, if
+                // present) gives it at least one category. ext.cite_it in
+                // antora.yml is now purely an OPTIONAL override, exactly like
+                // enabled/style/output_partial/write_to_disk below, never a
+                // requirement to be scanned at all. See the module docblock for
+                // the earlier opt-in-gate design this replaced and why.
+                const compExt = extByCompVer.get(compKey) ?? {};
+                if (!toBool(compExt['enabled'], cfg.enabled)) {
+                    logger.debug(`cite-it: ${compKey} - skipped (enabled: false)`);
+                    checkOrphanedCiteUsage(compKey, 'skipped (enabled: false)', contentCatalog, component, version, logger);
+                    continue;
+                }
+                // 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_category. See
+                // mergeCategoriesConfig for the actual merge.
+                const categories = mergeCategoriesConfig(cfg.categories, parseCategoriesConfig(compExt['categories']));
+                if (categories.length === 0) {
+                    // Without the opt-in gate, this branch is reached by every
+                    // component-version site-wide that has nothing to do with
+                    // cite-it at all, not just ones that tried to configure
+                    // something and got it wrong; warning for all of them would
+                    // flood the build log with noise about components that never
+                    // showed any intent to use cite-it. Warn only when this
+                    // component-version's own antora.yml actually carries an
+                    // ext.cite_it block (real, if misconfigured, intent), debug
+                    // otherwise, matching every other "nothing to do here" skip
+                    // above.
+                    const hasOwnExt = extByCompVer.has(compKey);
+                    const message = `cite-it: ${compKey} - skipped (no categories: none in the playbook-level scaffold or this component's own ext.cite_it.categories)`;
+                    if (hasOwnExt)
+                        logger.warn(message);
+                    else
+                        logger.debug(message);
+                    checkOrphanedCiteUsage(compKey, 'skipped (no categories)', contentCatalog, component, version, logger);
+                    continue;
+                }
+                let files = contentCatalog.getFiles().filter((f) => f.src.component === component && f.src.version === version);
+                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
+                // include:: directive it finds, including this one, even though
+                // its own resolved text is never itself scanned for citations).
+                // Each category partial must already exist in the catalog before
+                // that resolution is attempted: a real ContentCatalog's
+                // resolveResource can memoize a failed lookup, and a resolution
+                // attempted before the partial exists would otherwise permanently
+                // poison the SAME lookup Antora Assembler needs to perform for
+                // real, later, during assembly. Injecting an empty placeholder for
+                // EVERY category now, before the scan below and before any real
+                // .bib work, means every resolveResource call for any of these
+                // resource IDs, whether at scan time or assembly time, finds a
+                // real file, first attempt onward - independent of whether this
+                // 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) => ({
+                    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);
+                }
+                // Re-fetch: the placeholders just added above are now the real
+                // targets of any include:: resolution attempted during the scan
+                // below, and the later, real injectPartial calls, with the actual
+                // content, need their own `existing` lookups to find them too.
+                // Both need a file list that reflects the placeholders, not the
+                // 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 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
+                //    scaffold applies to every component-version site-wide with
+                //    no opt-in step (see the module docblock), so an asset-only
+                //    component-version with no relation to citations at all -
+                //    vale rule sets, PDF theme/font collections, and the like -
+                //    still inherits it and used to hit real .bib resolution
+                //    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 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
+                //    does no .bib work and carries no warning of its own, and the
+                //    resolveResource-poisoning hazard it guards against applies
+                //    regardless of whether this component-version turns out to
+                //    have real citation usage.
+                // ---------------------------------------------------------------
+                const componentAttrs = (contentCatalog.getComponents?.() ?? [])
+                    .find((c) => c.name === component)?.versions
+                    .find((v) => (v.version ?? v.name) === version)?.asciidoc?.attributes ?? {};
+                const scanFiles = files.filter((f) => f.src.family === 'page');
+                const includeVisited = new Set();
+                for (const f of scanFiles) {
+                    const key = `${f.src.component}@${f.src.version}:${f.src.module}:${f.src.family}$${f.src.relative}`;
+                    includeVisited.add(key);
+                }
+                const citedKeys = new Set();
+                for (const f of scanFiles) {
+                    const raw = f.contents.toString('utf8');
+                    const headerAttrs = (0, asciidoc_conditionals_1.pageHeaderAttributes)(raw);
+                    const isDefined = (attr) => {
+                        if (headerAttrs.has(attr))
+                            return headerAttrs.get(attr) === true;
+                        const v = componentAttrs[attr];
+                        return v !== undefined && v !== null && v !== false;
+                    };
+                    let text = (0, index_1.stripNonContent)(raw, isDefined, []);
+                    const extra = (0, index_1.collectIncludeText)(text, contentCatalog, component, version, f.src.module ?? 'ROOT', includeVisited, [], undefined, [], f.src.path ?? '');
+                    if (extra)
+                        text = `${text}\n${(0, index_1.stripNonContent)(extra, isDefined, [])}`;
+                    // Same concatenation-then-convert hazard sanitizeForScan already
+                    // fixed for assembly-numbering.ts's own scan (63a6538): a page
+                    // and its resolved include target each carrying a `=`-level-0
+                    // title makes the combined text an invalid multi-document
+                    // concatenation before it ever reaches scanCiteKeys' own real
+                    // processor.convert() call. This call site concatenates the same
+                    // way but was missed in that fix; confirmed live, "Executing
+                    // cite-it" is where the level-0/incomplete-row errors actually
+                    // fired, not assembly-numbering.ts's own computeCitationNumbers.
+                    for (const key of (0, macro_1.scanCiteKeys)((0, asciidoc_indexterms_1.sanitizeForScan)(text)))
+                        citedKeys.add(key);
+                }
+                // A category's own ref_force list lists a key in the generated
+                // bibliography even when no page cites it at all (see the
+                // CiteCategoryConfig field docblock), so zero cited keys does not
+                // always mean zero real work; only skip when NEITHER a real
+                // citation nor a forced entry gives this component-version
+                // anything to generate. citedKeys.size === 0 already means the
+                // scan above found nothing to report as orphaned either, so no
+                // separate checkOrphanedCiteUsage call is needed on this path.
+                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 cite:[key] usage anywhere and no ref_force entries in any category)`;
+                    if (hasOwnExt)
+                        logger.warn(message);
+                    else
+                        logger.debug(message);
+                    continue;
+                }
+                // ---------------------------------------------------------------
+                // 2. Resolve, parse, and merge each category's .bib files.
+                //    Files listed earlier in a category's own files[] are the
+                //    shared base; later files override by citation key, mirroring
+                //    autoterm's mergeTerminology semantics exactly.
+                // ---------------------------------------------------------------
+                const combinedEntries = new Map();
+                const keyCategory = new Map();
+                const categoryKeys = new Map();
+                for (const cat of categories) {
+                    const bibFiles = resolveBibFiles(cat.ref_files, contentCatalog, component, version, module, logger);
+                    let catEntries = new Map();
+                    for (const bf of bibFiles) {
+                        const { entries, warnings } = (0, registry_1.parseCiteFile)(bf.contents.toString('utf8'), `${compKey}:${bf.src.path ?? bf.src.relative ?? ''}`);
+                        for (const w of warnings)
+                            logger.warn(`cite-it: ${w}`);
+                        const { merged } = (0, registry_1.mergeCiteRegistry)(catEntries, entries);
+                        catEntries = merged;
+                    }
+                    const keys = new Set();
+                    for (const [key, entry] of catEntries) {
+                        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_category);
+                        combinedEntries.set(key, entry);
+                        keys.add(key);
+                    }
+                    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
+                // only knows about categories processed before it. keyCategory now
+                // holds each conflicted key's final, later-wins owner; remove the
+                // key from every OTHER category's Set so only its real owner lists
+                // it, matching the warning already logged above.
+                for (const [cat, keys] of categoryKeys) {
+                    for (const key of [...keys]) {
+                        if (keyCategory.get(key) !== cat)
+                            keys.delete(key);
+                    }
+                }
+                // Each category's own ref_force list reassigns a key's category
+                // membership outright, the same mechanism as the natural conflict
+                // resolution above: strip the key from its previous category's Set,
+                // then add it to THIS category's Set, the one whose own ref_force
+                // names it. A key's rendered row lives in exactly one category at a
+                // time, so this reassignment, not an additive union, is what "force
+                // this citation under this heading" actually means. Nesting
+                // ref_force inside its own category means the target is never
+                // ambiguous: there is no separate back-reference field to get wrong.
+                //
+                // A key with no entry anywhere warns rather than silently rendering
+                // nowhere: a visible mistake beats a citation named in ref_force
+                // deliberately just vanishing over a typo.
+                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_category}"; not found in any configured category's data`);
+                            continue;
+                        }
+                        const previousCategory = keyCategory.get(key);
+                        if (previousCategory && previousCategory !== cat.ref_category) {
+                            categoryKeys.get(previousCategory)?.delete(key);
+                        }
+                        keyCategory.set(key, cat.ref_category);
+                        categoryKeys.get(cat.ref_category)?.add(key);
+                    }
+                }
+                if (!cfg.suppress_events) {
+                    logEvent(`${compKey} - ${combinedEntries.size} bibliography entr${combinedEntries.size === 1 ? 'y' : 'ies'} loaded across ${categories.length} categor${categories.length === 1 ? 'y' : 'ies'}`);
+                }
+                for (const key of citedKeys) {
+                    if (!combinedEntries.has(key)) {
+                        logger.warn(`cite-it: ${compKey} - cite:[${key}] cites an unknown key; not found in any configured category`);
+                    }
+                }
+                // ---------------------------------------------------------------
+                // 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.
+                // ---------------------------------------------------------------
+                const refForceKeys = new Set(categories.flatMap((cat) => cat.ref_force));
+                const usedKeysByCategory = new Map();
+                const allUsedKeys = [];
+                for (const cat of categories) {
+                    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_category, keys);
+                    allUsedKeys.push(...keys);
+                }
+                // A key's entry carrying a supersededby field (registry.ts) warns
+                // once here, at generation time, scoped to the keys a category's
+                // 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 cite:[key] use site (macro.ts): one clear
+                // signal per generated partial, not one per occurrence in prose.
+                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 "${category}" carries supersededby "${supersededBy}"; a newer revision is available`);
+                        }
+                    }
+                }
+                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,
+                    component,
+                    version,
+                    componentAttrs,
+                    module,
+                    categoryPartials,
+                });
+                keyCategories.set(compKey, keyCategory);
+                // ---------------------------------------------------------------
+                // 4. Generate and inject each category's own bibliography
+                //    partial. A component author routes different categories to
+                //    different pages simply by choosing which page includes
+                //    which category's partial.
+                // ---------------------------------------------------------------
+                for (const cp of categoryPartials) {
+                    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);
+                }
+            }
+        }
+        logEvent('cite-it finished');
+    });
+    // ---------------------------------------------------------------------
+    // PDF/assembled numbering. See assembly-numbering.ts's own module
+    // docblock for the full reasoning behind the numbering mechanism itself.
+    //
+    // Computed LAZILY, memoized per component-version, on the first assembled
+    // loadAsciiDoc call the wrapper above sees for that component-version,
+    // rather than eagerly in a navigationBuilt listener as an earlier version
+    // 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 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.
+    //
+    // A DIFFERENT bug surfaced later, unrelated to that race: this function
+    // used to always resolve navigation as `componentVersion?.navigation`,
+    // falling back to a hardcoded, always-unnamed assembler-profile lookup
+    // (`assemblerProfiles.get(compKey).get(undefined)`) for any navFiles
+    // override. Verified directly against @antora/assembler's own source
+    // (assemble-content.js/build-navigation.js): `componentVersion.navigation`
+    // is only ever assigned by @antora/navigation-builder for a component
+    // version that owns at least one real `nav`-family file — it stays
+    // permanently undefined otherwise, by design, not a timing artifact.
+    // Assembler itself resolves the active profile as `assemblyConfig.profile`,
+    // which DEFAULTS TO THE TARGET BACKEND NAME (e.g. 'pdf') whenever no
+    // profile is configured explicitly, never bare `undefined` in an ordinary
+    // PDF build, and looks up that component-version's navFiles override
+    // under THAT key first, falling back to the unnamed slot only as a second
+    // choice (`componentVersionProfiles?.get(baseModel.profile) ??
+    // componentVersionProfiles?.get()`). A hardcoded `.get(undefined)` lookup
+    // here therefore misses the real override in the common case. Assembler
+    // also bakes the resolved profile name into every assembled document's
+    // own real attributes as `assembler-profile` (assemble-content.js's
+    // intrinsicAttributes, merged into what the wrapper above already
+    // receives as `asciidocConfig.attributes`) specifically so a consumer
+    // like this one can read back the SAME profile it resolved, rather than
+    // needing to reimplement its resolution logic; `profileName` below is
+    // that value, threaded through from the wrapper.
+    //
+    // A THIRD gap surfaced later still, confirmed live against a real Antora
+    // build: a playbook can register @antora/pdf-extension programmatically,
+    // at normal register()-phase time, instead of through the playbook's
+    // own antora.extensions list, with no ordering race either way. With no
+    // ext.assembler block anywhere (assemblerProfiles legitimately empty)
+    // and real, unmodified Antora navigation driving assembly correctly,
+    // `componentVersion.navigation` still read empty here. Assembler's own
+    // no-profile resolution
+    // (assemble-content.js's generateSelectAssemblerProfile) never actually
+    // reads componentVersion.navigation FIRST — it reads
+    // `navigationCatalog?.getNavigation(componentVersion.name,
+    // componentVersion.version) ?? componentVersion.navigation`, the
+    // NavigationCatalog instance @antora/navigation-builder's own
+    // buildNavigation returns and generate-site.js stores as the
+    // navigationCatalog context variable, alongside (not only through)
+    // componentVersion.navigation. This function only ever checked the
+    // fallback half of that chain; matching assembler's own real
+    // precedence, primary source first, is the fix, not a guess: it can
+    // only find more, never less, than the fallback-only lookup already
+    // did.
+    //
+    // A FOURTH gap: even navigationCatalog can read empty. Confirmed live,
+    // not a codebase bug: componentVersion.navigation itself reads undefined
+    // at this exact read point despite a real nav-family file existing in
+    // the content catalog, confirmed as the SAME object reference two
+    // independent ways (this function's own
+    // manual lookup and contentCatalog.getComponentVersion()) — not a stale
+    // copy, not the wrong object. Rather than depend further on exactly
+    // when/how something else populates it, self-heal: call
+    // @antora/navigation-builder's own buildNavigation directly (exposed via
+    // getFunctions(), the same mechanism buildAlternateNavigation below
+    // already uses), which re-derives navigation from the catalog's own
+    // nav-family files and reassigns componentVersion.navigation as a
+    // genuine side effect, discarding buildNavigation's own returned
+    // NavigationCatalog (a fresh, separate instance every call) rather than
+    // touching the site's real one.
+    // ---------------------------------------------------------------------
+    function ensureAssemblyDataComputed(compKey, profileName) {
+        if (citationNumbers.has(compKey))
+            return; // already computed, or in progress
+        const scanCtx = assemblyScanContexts.get(compKey);
+        if (!scanCtx)
+            return;
+        citationNumbers.set(compKey, new Map()); // reentrancy guard, replaced below
+        // scanCtx.contentCatalog is typed against assembly-numbering.ts's own
+        // narrower ContentCatalog interface (no getComponents); the stored
+        // runtime object is the same real catalog assemblyScanContexts.set(...)
+        // captured, just narrowed at that point too, so this cast back to the
+        // wider local interface is safe.
+        const contentCatalog = scanCtx.contentCatalog;
+        const components = contentCatalog.getComponents?.() ?? [];
+        const contextVars = ctx.getVariables?.();
+        const assemblerProfiles = contextVars?.assemblerProfiles;
+        const navigationCatalog = contextVars?.navigationCatalog;
+        const componentVersion = components
+            .find((c) => c.name === scanCtx.component)?.versions
+            .find((v) => (v.version ?? v.name) === scanCtx.version);
+        let liveNavigation = navigationCatalog?.getNavigation(scanCtx.component, scanCtx.version);
+        if ((!liveNavigation || !liveNavigation.length) && ctx.getFunctions) {
+            // Self-heal: confirmed live, not a codebase bug, that
+            // componentVersion.navigation, and
+            // navigationCatalog's own record of it, can BOTH read empty here
+            // even though a real nav-family file exists in the content catalog
+            // and the SAME object reference is confirmed live two independent
+            // ways (this manual lookup and contentCatalog.getComponentVersion())
+            // — ruling out a stale copy or wrong-object bug on cite-it's own
+            // side. buildNavigation is self-contained and idempotent: it
+            // re-derives navigation straight from the catalog's own nav-family
+            // files and re-assigns componentVersion.navigation directly,
+            // discarding its own returned NavigationCatalog (a fresh, separate
+            // instance every call) rather than touching the site's real one.
+            // Same getFunctions() mechanism buildAlternateNavigation below
+            // already uses.
+            //
+            // buildNavigation's own internal implementation reads its loadAsciiDoc
+            // through this SAME live, shared function table (getFunctions'
+            // $unsafe accessor, by design, so it picks up any real replacement -
+            // including this extension's own wrapper). This self-heal fires from
+            // INSIDE that wrapper, mid-conversion of some other real page, so
+            // without intervention buildNavigation's own internal parse of each
+            // nav.adoc would recurse straight back through the wrapper, nested
+            // inside an already-in-progress loadAsciiDoc call. Sidestepped by
+            // swapping the live table back to the real, unwrapped loader for the
+            // duration of this one synchronous call only, then always restoring
+            // the wrapper again, success or failure.
+            try {
+                const buildNav = ctx.getFunctions().buildNavigation;
+                if (typeof buildNav === 'function' && realLoadAsciiDoc) {
+                    ctx.replaceFunctions?.({ loadAsciiDoc: realLoadAsciiDoc });
+                    try {
+                        buildNav(contentCatalog, componentVersion?.asciidoc);
+                    }
+                    finally {
+                        if (loadAsciiDocWrapper)
+                            ctx.replaceFunctions?.({ loadAsciiDoc: loadAsciiDocWrapper });
+                    }
+                    liveNavigation = componentVersion?.navigation;
+                }
+            }
+            catch (err) {
+                logger.warn(`cite-it: ${compKey} - buildNavigation fallback failed: ${String(err)}`);
+            }
+        }
+        const defaultNavigation = (liveNavigation ??
+            componentVersion?.navigation ??
+            []);
+        let navigation = defaultNavigation;
+        // Same two-step lookup assembler itself performs: the resolved active
+        // profile first (never bare undefined for an ordinary export whose
+        // config omits `profile:` explicitly, see the docblock above), the
+        // unnamed default slot only as a fallback.
+        const componentVersionProfiles = assemblerProfiles?.get(`${scanCtx.version}@${scanCtx.component}`);
+        const profileData = componentVersionProfiles?.get(profileName) ?? componentVersionProfiles?.get(undefined);
+        if (profileData?.navFiles?.length && ctx.require && ctx.getFunctions) {
+            try {
+                // Mirrors @antora/assembler's own resolution exactly
+                // (assemble-content.js's generateSelectAssemblerProfile):
+                // buildAlternateNavigation from the shared generator functions if
+                // some other extension already replaced it, otherwise straight
+                // from the real @antora/navigation-builder module.
+                const fxns = ctx.getFunctions();
+                const buildAlternateNavigation = fxns.buildAlternateNavigation ??
+                    ctx.require('@antora/navigation-builder').buildAlternateNavigation;
+                navigation = (buildAlternateNavigation(contentCatalog, componentVersion, profileData.navFiles, {}) ?? []);
+            }
+            catch (err) {
+                logger.warn(`cite-it: ${compKey} - could not resolve the assembler profile's alternate navigation, falling back to the default navigation for numbering: ${String(err)}`);
+            }
+        }
+        const numbers = (0, assembly_numbering_1.computeCitationNumbers)(navigation, scanCtx);
+        citationNumbers.set(compKey, numbers);
+        logger.debug(`cite-it: ${compKey} - computed ${numbers.size} true first-appearance citation number(s) for assembled output`);
+        const categoryScopes = (0, assembly_numbering_1.findBibliographyScopes)(navigation, scanCtx);
+        const keyCategory = keyCategories.get(compKey) ?? new Map();
+        const keyScopes = new Map();
+        const missingScopeCategories = new Set();
+        for (const [key] of numbers) {
+            const cat = keyCategory.get(key);
+            const scope = cat ? categoryScopes.get(cat) : undefined;
+            if (scope) {
+                keyScopes.set(key, scope);
+            }
+            else if (cat) {
+                missingScopeCategories.add(cat);
+            }
+        }
+        keyScopesByComp.set(compKey, keyScopes);
+        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 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
+        // catalog, never back through loadAsciiDoc, so the wrapper above never
+        // gets a chance to touch it otherwise (see rewritePartialForAssembly's
+        // own docblock for the full story). Safe to do here, synchronously,
+        // before returning: this function itself is always called from inside
+        // 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
+ * only, no heading. A component author decides where THIS category
+ * appears by choosing which page includes `partial$<categoryPartialName
+ * (...)>`, independent of every other category, and supplies that page's
+ * own heading directly as ordinary authored AsciiDoc immediately above
+ * the include line. Returns '' for an empty category (caller skips
+ * injecting it at all).
+ */
+function generateCategoryPartial(keys, formattedByKey) {
+    if (keys.length === 0)
+        return '';
+    // The cite-it-bibliography role is a real theming hook, not
+    // decoration: dlist_role_theming.rb (the PDF theme's own converter
+    // extension, since asciidoctor-pdf's dlist rendering has no per-role
+    // lookup of its own) reads role_cite-it-bibliography_* theme keys for
+    // this exact role to control term boldness and text alignment for PDF
+    // output, and it renders as an ordinary CSS-targetable class in HTML.
+    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 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}]]cite:[${key}]:: ${text}`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+//# sourceMappingURL=index.js.map