@baiyibai-antora/extensions 1.13.0 → 1.14.0

package/dist/extensions/cite-it/assembly-numbering.d.ts

@@ -0,0 +1,202 @@
+/**
+ * cite-it: true first-appearance numbering for Antora Assembler-flattened
+ * (PDF) output.
+ *
+ * `@antora/pdf-extension` shells the stitched document out to the real Ruby
+ * `asciidoctor-pdf` CLI as a subprocess. Ruby never loads this package's JS
+ * `citeit:[key]` macro (asciidoc.ts), so a live-macro-only design silently
+ * fails for PDF output: the macro simply never runs. The fix needs no Ruby
+ * code at all: `@antora/assembler`'s own `produceAssemblyFile` builds the
+ * stitched document from `doc.getSourceLines()` on a Document `loadAsciiDoc`
+ * (Asciidoctor.js) just parsed, so whatever text is fed into `loadAsciiDoc`
+ * is exactly what ends up in Ruby's stdin. This module rewrites
+ * `citeit:[key]` to its final number in the page's own text before calling
+ * the real `loadAsciiDoc`, using Antora's own `replaceFunctions` extension-
+ * cooperation point (`@antora/site-generator`'s `GeneratorContext`).
+ *
+ * True first-appearance order across an assembled multi-page document is
+ * only knowable from the same page order `@antora/assembler` itself
+ * assembles in, so this module computes that order independently in Node,
+ * from the SAME navigation source assembler resolves to. This accounts for
+ * a custom assembler-profile `nav:` override, via the shared
+ * `assemblerProfiles` variable `@antora/assembler`'s own `configure.js`
+ * computes and publishes at `componentsRegistered`, well before
+ * `navigationBuilt`, rather than assuming the component-version's default
+ * navigation always applies.
+ *
+ * Scope limitation, deliberate for this version: only the DEFAULT assembler
+ * profile (the unnamed/undefined profile key) is used for numbering. A
+ * component-version with multiple assembler profiles producing multiple
+ * PDFs with genuinely different nav overrides per profile is not
+ * disambiguated: the `loader-assembler` discriminator this module (and the
+ * live macro) relies on does not itself carry which profile is being
+ * assembled. Documented, not silently mishandled: a component using more
+ * than the default profile should be verified manually before relying on
+ * cite-it's PDF numbering.
+ */
+interface NavigationEntry {
+    urlType?: string;
+    url?: string;
+    hash?: string;
+    unresolved?: boolean;
+    items?: NavigationEntry[];
+}
+interface VirtualFileSrc {
+    path?: string;
+    family?: string;
+    component?: string;
+    version?: string;
+    module?: string;
+    relative?: string;
+    contents?: Buffer | Uint8Array | string;
+}
+interface VirtualFile {
+    src: VirtualFileSrc;
+    contents: Buffer | Uint8Array;
+    path?: string;
+    pub?: {
+        url?: string;
+    };
+}
+interface ContentCatalog {
+    getFiles: () => VirtualFile[];
+    resolveResource?: (spec: string, context?: Record<string, unknown>, defaultFamily?: string, permittedFamilies?: string[]) => VirtualFile | undefined;
+    getByPath?: (criteria: {
+        component?: string;
+        version?: string;
+        path: string;
+    }) => VirtualFile | undefined;
+}
+export interface ScanContext {
+    contentCatalog: ContentCatalog;
+    component: string;
+    version: string;
+    componentAttrs: Record<string, unknown>;
+    module: string;
+    /**
+     * One generated partial per category is the key design feature this
+     * carries. Different categories may be included on genuinely different
+     * pages, since a component author decides where by choosing which page
+     * includes which category's own partial. Citations correctly cross-link
+     * to whichever page actually hosts the cited entry, not just a single
+     * hardcoded bibliography page. Needed both to rewrite each partial's own
+     * citeit:[key] row labels for assembled output (rewritePartialForAssembly)
+     * and to resolve each key's own host page (findBibliographyScopes).
+     */
+    categoryPartials: Array<{
+        section: string;
+        relative: string;
+    }>;
+}
+/**
+ * True first-appearance citation numbers for one component-version's
+ * assembled output: walks its pages in real assembly order, scans each in
+ * turn (comments/unset-conditionals stripped first, includes resolved,
+ * mirroring index.ts's own per-page scan exactly) for citeit:[key]
+ * occurrences in encounter order, and assigns each distinct key the next
+ * number on its first appearance across the whole ordered sequence.
+ */
+export declare function computeCitationNumbers(navigation: NavigationEntry[] | undefined, ctx: ScanContext): Map<string, number>;
+/**
+ * The docname of each category's own host page, one lookup per category
+ * partial in `ctx.categoryPartials`, since different categories may
+ * genuinely live on different pages, the whole point of splitting
+ * generation per category at all. A category whose partial is not included
+ * anywhere simply does not appear in the returned map; callers already
+ * treat a missing scope as "render this citation unlinked"
+ * (rewriteCiteMarkers).
+ *
+ * The docname each key resolves to is the SCOPE PREFIX `@antora/
+ * assembler`'s own id-uniquing rewriter assigns to every anchor defined on
+ * that page, needed to build a cross-page xref target that actually
+ * resolves. See `rewriteCiteMarkers`'s own docblock for the full reasoning
+ * behind why a page-qualified xref, not a bare local id, is required here.
+ */
+export declare function findBibliographyScopes(navigation: NavigationEntry[] | undefined, ctx: ScanContext): Map<string, string>;
+/**
+ * `asLink: true` (the default, used for citing pages' own body text)
+ * rewrites a citation to a real, clickable `xref:<scope>.adoc#cite-<key>[[N\]]`
+ * pointing at the bibliography entry's own anchor, producing a genuine
+ * internal PDF link rather than literal bracket text. `asLink: false` (used
+ * for the bibliography list's own row labels, which already carry that same
+ * anchor immediately to their left, see `generateCategoryPartial` in
+ * index.ts) rewrites to a plain `[N]` instead: a bibliography entry linking
+ * to itself would be pointless.
+ *
+ * The inner `]` must be escaped (`\]`) inside the xref's own attribute
+ * list: `xref:target[[N]]` looks correct but Asciidoctor's attrlist parser
+ * closes on the first unescaped `]` it finds, so the link text becomes `[N`
+ * and the trailing `]` ends up stray, unlinked, literal text right after
+ * it.
+ *
+ * `scopes`: a `Map<key, docname>` (from `findBibliographyScopes`), one
+ * entry per citation key, giving each key's own bibliography host page,
+ * not a single global scope, since different categories may genuinely live
+ * on different pages (the whole point of splitting generation per
+ * category; see `ScanContext.categoryPartials`). A citation's target names
+ * its host page explicitly (`xref:<scopes.get(key)>.adoc#cite-<key>[...]`),
+ * an ordinary, Antora-native cross-page reference, rather than a bare
+ * `xref:cite-<key>[...]`. Two other forms were tried and rejected, verified
+ * against a real multi-page assembled PDF's internal link data (`ruby
+ * -rpdf-reader`, dumping both `Annots`/`Dest` and the document's own
+ * `Names/Dests` tree):
+ *
+ *   1. A bare `xref:cite-<key>[]`: broken. `@antora/assembler` rewrites
+ *      every page's own ids/xrefs sequentially as it stitches
+ *      (`produce-assembly-file.js`'s `rewriteXrefs`), prefixing each with
+ *      its own page's docname for uniqueness. A citation on an earlier
+ *      page (the normal case, since a bibliography conventionally comes
+ *      last) cites forward to a page the rewriter has not reached yet, so
+ *      it cannot know the real scope and defaults to prefixing with the
+ *      citing page's own scope instead. A citation on "page-two" produced
+ *      a link to `page-two:::cite-lee2021`, which does not exist; the real
+ *      destination is `references:::cite-lee2021` (the anchor's own host
+ *      page).
+ *   2. A pre-scoped `xref:<scope>:::cite-<key>[]` (manually prepending the
+ *      correct prefix): also broken, and worse. The rewriter does not
+ *      recognize an already-scoped target as special, so it double-
+ *      prefixes it with the citing page's own scope on top, producing
+ *      `index:::references:::cite-smith2020`.
+ *   3. `xref:<scope>.adoc#cite-<key>[]` (this one, working): an ordinary
+ *      inter-page Antora xref, explicitly naming its own target page,
+ *      exactly how an author would write a real cross-page reference in
+ *      normal, non-assembled content. Produces a real PDF `GoTo` action
+ *      with `Dest="references:::cite-smith2020"`, matching the real named
+ *      destination exactly.
+ *
+ * Falls back to a plain, unlinked `[N]` when a key has no entry in
+ * `scopes`: its category's host page was not found. This should not
+ * normally happen for a properly configured component, but a
+ * known-correct number with no link is a safer failure than a link known
+ * to point nowhere.
+ */
+export declare function rewriteCiteMarkers(text: string, numbers: Map<string, number>, asLink?: boolean, scopes?: Map<string, string> | null): string;
+export declare function reorderBibliographyRows(text: string, numbers: Map<string, number>): string;
+/**
+ * Rewrites the generated bibliography partial's OWN `citeit:[key]` row
+ * labels to their final `[N]` numbers, mutating the file directly in the
+ * content catalog.
+ *
+ * Needed for a reason distinct from rewriteCiteMarkers' normal call site:
+ * Antora's own include processor resolves an `include::partial$...[]`
+ * directive by reading the target file's content directly from the
+ * catalog, without recursing back through `loadAsciiDoc` for the included
+ * content. That means the loadAsciiDoc wrapper (index.ts), which only sees
+ * each page's own raw text before it is parsed, never gets a chance to
+ * rewrite text that arrives via an include inside that parse; a citing
+ * page's own `citeit:[key]` usage rewrites correctly, but the generated
+ * partial's own row labels, pulled in during the same parse, would
+ * otherwise reach Ruby unrewritten. Called once per component-version,
+ * before any assembly-time loadAsciiDoc call can run (synchronous within
+ * the same navigationBuilt handler that computes `numbers`), so the
+ * partial is already correct by the time anything tries to include it.
+ *
+ * Also reorders the partial's rows into ascending citation-number order
+ * (reorderBibliographyRows) before rewriting labels: the order the partial
+ * was generated in has no relationship to citation number (Node does not
+ * know numbers yet at generation time), and a numbered bibliography listed
+ * out of number order reads as broken to anyone looking at it.
+ */
+export declare function rewritePartialForAssembly(ctx: ScanContext, numbers: Map<string, number>): void;
+export {};
+//# sourceMappingURL=assembly-numbering.d.ts.map

package/dist/extensions/cite-it/assembly-numbering.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assembly-numbering.d.ts","sourceRoot":"","sources":["../../../src/extensions/cite-it/assembly-numbering.ts"],"names":[],"mappings":"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"}

package/dist/extensions/cite-it/assembly-numbering.js

@@ -0,0 +1,385 @@
+"use strict";
+/**
+ * cite-it: true first-appearance numbering for Antora Assembler-flattened
+ * (PDF) output.
+ *
+ * `@antora/pdf-extension` shells the stitched document out to the real Ruby
+ * `asciidoctor-pdf` CLI as a subprocess. Ruby never loads this package's JS
+ * `citeit:[key]` macro (asciidoc.ts), so a live-macro-only design silently
+ * fails for PDF output: the macro simply never runs. The fix needs no Ruby
+ * code at all: `@antora/assembler`'s own `produceAssemblyFile` builds the
+ * stitched document from `doc.getSourceLines()` on a Document `loadAsciiDoc`
+ * (Asciidoctor.js) just parsed, so whatever text is fed into `loadAsciiDoc`
+ * is exactly what ends up in Ruby's stdin. This module rewrites
+ * `citeit:[key]` to its final number in the page's own text before calling
+ * the real `loadAsciiDoc`, using Antora's own `replaceFunctions` extension-
+ * cooperation point (`@antora/site-generator`'s `GeneratorContext`).
+ *
+ * True first-appearance order across an assembled multi-page document is
+ * only knowable from the same page order `@antora/assembler` itself
+ * assembles in, so this module computes that order independently in Node,
+ * from the SAME navigation source assembler resolves to. This accounts for
+ * a custom assembler-profile `nav:` override, via the shared
+ * `assemblerProfiles` variable `@antora/assembler`'s own `configure.js`
+ * computes and publishes at `componentsRegistered`, well before
+ * `navigationBuilt`, rather than assuming the component-version's default
+ * navigation always applies.
+ *
+ * Scope limitation, deliberate for this version: only the DEFAULT assembler
+ * profile (the unnamed/undefined profile key) is used for numbering. A
+ * component-version with multiple assembler profiles producing multiple
+ * PDFs with genuinely different nav overrides per profile is not
+ * disambiguated: the `loader-assembler` discriminator this module (and the
+ * live macro) relies on does not itself carry which profile is being
+ * assembled. Documented, not silently mishandled: a component using more
+ * than the default profile should be verified manually before relying on
+ * cite-it's PDF numbering.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeCitationNumbers = computeCitationNumbers;
+exports.findBibliographyScopes = findBibliographyScopes;
+exports.rewriteCiteMarkers = rewriteCiteMarkers;
+exports.reorderBibliographyRows = reorderBibliographyRows;
+exports.rewritePartialForAssembly = rewritePartialForAssembly;
+const macro_1 = require("./macro");
+const index_1 = require("../trademark-it/index");
+const index_2 = require("../autoterm/index");
+const asciidoc_conditionals_1 = require("../../lib/asciidoc-conditionals");
+const asciidoc_indexterms_1 = require("../../lib/asciidoc-indexterms");
+// ---------------------------------------------------------------------------
+// Navigation walk: which pages, in what order, does the assembled output
+// stitch together. Mirrors @antora/assembler's own selectPagesInOutline
+// (produce-assembly-file.js), a straightforward depth-first pre-order
+// walk of the navigation tree, visiting each internal-URL entry before its
+// children, deduplicating by pathname (an entry the tree references more
+// than once, for example a shared "next steps" page linked from two spots,
+// contributes only at its first position, matching what the real assembler
+// itself stitches).
+// ---------------------------------------------------------------------------
+function walkNavigationForPathnames(entries, seen, out) {
+    for (const entry of entries ?? []) {
+        if (entry.urlType === 'internal' && !entry.unresolved && entry.url) {
+            const pathname = entry.hash ? entry.url.substring(0, entry.url.length - entry.hash.length) : entry.url;
+            if (!seen.has(pathname)) {
+                seen.add(pathname);
+                out.push(pathname);
+            }
+        }
+        walkNavigationForPathnames(entry.items, seen, out);
+    }
+}
+/**
+ * The ordered list of page VirtualFiles the assembled output for
+ * `component`@`version` stitches together, resolved from `navigation`:
+ * either the component-version's default navigation, or a profile's
+ * alternate navigation, the caller decides which.
+ */
+function pagesInNavigationOrder(navigation, files) {
+    const pathnames = [];
+    walkNavigationForPathnames(navigation, new Set(), pathnames);
+    const pagesByUrl = new Map();
+    for (const f of files) {
+        if (f.src.family === 'page' && f.pub?.url)
+            pagesByUrl.set(f.pub.url, f);
+    }
+    const result = [];
+    for (const pathname of pathnames) {
+        const page = pagesByUrl.get(pathname);
+        if (page)
+            result.push(page);
+    }
+    return result;
+}
+/**
+ * True first-appearance citation numbers for one component-version's
+ * assembled output: walks its pages in real assembly order, scans each in
+ * turn (comments/unset-conditionals stripped first, includes resolved,
+ * mirroring index.ts's own per-page scan exactly) for citeit:[key]
+ * occurrences in encounter order, and assigns each distinct key the next
+ * number on its first appearance across the whole ordered sequence.
+ */
+function computeCitationNumbers(navigation, ctx) {
+    const numbers = new Map();
+    const files = ctx.contentCatalog.getFiles().filter((f) => f.src.component === ctx.component && f.src.version === ctx.version);
+    const pages = pagesInNavigationOrder(navigation, files);
+    // Pre-populated with the keys of files this loop is ALSO about to scan
+    // directly (pages, not every page-or-partial in the component-version):
+    // collectIncludeText checks visited.has(key) before ever reading a
+    // target's content, so a key present for any reason suppresses that
+    // include outright, not merely dedups it. trademark-it/index.ts's own
+    // scan loop pre-populates from scanFiles, the exact set it also scans
+    // directly, so pre-marking those visited only avoids double-counting.
+    // This loop only scans `pages` directly; partials are never scanned on
+    // their own here, only ever reached via include. Pre-populating from
+    // `files` (every page or partial) used to mark partials visited before
+    // any page's include was ever resolved, silently and permanently
+    // excluding their content, and any citeit:[key] inside it, from the
+    // scan on first encounter rather than deduping a real prior resolution.
+    const includeVisited = new Set();
+    for (const page of pages) {
+        includeVisited.add(`${page.src.component}@${page.src.version}:${page.src.module}:${page.src.family}$${page.src.relative}`);
+    }
+    for (const page of pages) {
+        // page.contents holds the CONVERTED HTML by navigationBuilt time:
+        // documentsConverted, which overwrites it, runs earlier in Antora's
+        // real lifecycle. @antora/assembler's own produce-assembly-file.js reads
+        // page.src.contents specifically for this reason: the raw source
+        // @antora/assembler's own enableKeepSource mechanism preserves there.
+        // This scan needs the same raw AsciiDoc source, not the rendered HTML.
+        const rawSource = page.src.contents ?? page.contents;
+        const raw = rawSource.toString('utf8');
+        const headerAttrs = (0, asciidoc_conditionals_1.pageHeaderAttributes)(raw);
+        const isDefined = (attr) => {
+            if (headerAttrs.has(attr))
+                return headerAttrs.get(attr) === true;
+            const v = ctx.componentAttrs[attr];
+            return v !== undefined && v !== null && v !== false;
+        };
+        let text = (0, index_1.stripNonContent)(raw, isDefined, []);
+        const extra = (0, index_1.collectIncludeText)(text, ctx.contentCatalog, ctx.component, ctx.version, page.src.module ?? 'ROOT', includeVisited, [], undefined, [], page.src.path ?? '');
+        if (extra)
+            text = `${text}\n${(0, index_1.stripNonContent)(extra, isDefined, [])}`;
+        // The concatenation above is not always one well-formed document: a
+        // page and its resolved include target each carrying their own
+        // `=`-level-0 title makes the combined text an invalid multi-document
+        // concatenation ("level 0 sections can only be used when doctype is
+        // book", confirmed live) before it ever reaches scanCiteKeysOrdered's
+        // own real processor.convert() call. asciidoc-indexterms.ts's scanner
+        // hit the exact same hazard first; reusing its sanitizeForScan here
+        // rather than a second, independently-maintained copy of the same fix.
+        const orderedKeys = (0, macro_1.scanCiteKeysOrdered)((0, asciidoc_indexterms_1.sanitizeForScan)(text));
+        for (const key of orderedKeys) {
+            if (!numbers.has(key))
+                numbers.set(key, numbers.size + 1);
+        }
+    }
+    return numbers;
+}
+/**
+ * The docname of each category's own host page, one lookup per category
+ * partial in `ctx.categoryPartials`, since different categories may
+ * genuinely live on different pages, the whole point of splitting
+ * generation per category at all. A category whose partial is not included
+ * anywhere simply does not appear in the returned map; callers already
+ * treat a missing scope as "render this citation unlinked"
+ * (rewriteCiteMarkers).
+ *
+ * The docname each key resolves to is the SCOPE PREFIX `@antora/
+ * assembler`'s own id-uniquing rewriter assigns to every anchor defined on
+ * that page, needed to build a cross-page xref target that actually
+ * resolves. See `rewriteCiteMarkers`'s own docblock for the full reasoning
+ * behind why a page-qualified xref, not a bare local id, is required here.
+ */
+function findBibliographyScopes(navigation, ctx) {
+    const scopes = new Map();
+    const files = ctx.contentCatalog.getFiles().filter((f) => f.src.component === ctx.component && f.src.version === ctx.version);
+    const pages = pagesInNavigationOrder(navigation, files);
+    const remaining = new Map(ctx.categoryPartials.map((cp) => [cp.relative, cp.section]));
+    for (const page of pages) {
+        if (remaining.size === 0)
+            break;
+        const raw = (page.src.contents ?? page.contents).toString('utf8');
+        for (const [relative, section] of [...remaining]) {
+            if ((0, index_2.includesPartial)(raw, relative)) {
+                scopes.set(section, (page.src.relative ?? '').replace(/\.[^./]+$/, ''));
+                remaining.delete(relative);
+            }
+        }
+    }
+    return scopes;
+}
+// ---------------------------------------------------------------------------
+// Text rewrite: replace citeit:[key] with its final [N] number, applied
+// only to assembly-time page loads (loader-assembler present), before the
+// real loadAsciiDoc parses the page. NOT a blind regex substitution: skips
+// occurrences inside // and //// comments (mirrors trademark-it's own
+// stripComments logic) and occurrences wrapped in a monospace span
+// (`citeit:[key]` or `+citeit:[key]+`), the two shapes documentation
+// showing citeit:[key] as literal example syntax would realistically use.
+// Deliberately narrower than a full Asciidoctor-parse-based substitution:
+// the citeit:[key] syntax is simple and fixed enough that this scoped guard
+// covers the realistic false-positive shapes without the cost of a second
+// real parse on every assembly-time page load.
+// ---------------------------------------------------------------------------
+const CITE_MARKER_RE = /citeit:\[([a-zA-Z0-9][\w.:/-]*)\]/g;
+/**
+ * `asLink: true` (the default, used for citing pages' own body text)
+ * rewrites a citation to a real, clickable `xref:<scope>.adoc#cite-<key>[[N\]]`
+ * pointing at the bibliography entry's own anchor, producing a genuine
+ * internal PDF link rather than literal bracket text. `asLink: false` (used
+ * for the bibliography list's own row labels, which already carry that same
+ * anchor immediately to their left, see `generateCategoryPartial` in
+ * index.ts) rewrites to a plain `[N]` instead: a bibliography entry linking
+ * to itself would be pointless.
+ *
+ * The inner `]` must be escaped (`\]`) inside the xref's own attribute
+ * list: `xref:target[[N]]` looks correct but Asciidoctor's attrlist parser
+ * closes on the first unescaped `]` it finds, so the link text becomes `[N`
+ * and the trailing `]` ends up stray, unlinked, literal text right after
+ * it.
+ *
+ * `scopes`: a `Map<key, docname>` (from `findBibliographyScopes`), one
+ * entry per citation key, giving each key's own bibliography host page,
+ * not a single global scope, since different categories may genuinely live
+ * on different pages (the whole point of splitting generation per
+ * category; see `ScanContext.categoryPartials`). A citation's target names
+ * its host page explicitly (`xref:<scopes.get(key)>.adoc#cite-<key>[...]`),
+ * an ordinary, Antora-native cross-page reference, rather than a bare
+ * `xref:cite-<key>[...]`. Two other forms were tried and rejected, verified
+ * against a real multi-page assembled PDF's internal link data (`ruby
+ * -rpdf-reader`, dumping both `Annots`/`Dest` and the document's own
+ * `Names/Dests` tree):
+ *
+ *   1. A bare `xref:cite-<key>[]`: broken. `@antora/assembler` rewrites
+ *      every page's own ids/xrefs sequentially as it stitches
+ *      (`produce-assembly-file.js`'s `rewriteXrefs`), prefixing each with
+ *      its own page's docname for uniqueness. A citation on an earlier
+ *      page (the normal case, since a bibliography conventionally comes
+ *      last) cites forward to a page the rewriter has not reached yet, so
+ *      it cannot know the real scope and defaults to prefixing with the
+ *      citing page's own scope instead. A citation on "page-two" produced
+ *      a link to `page-two:::cite-lee2021`, which does not exist; the real
+ *      destination is `references:::cite-lee2021` (the anchor's own host
+ *      page).
+ *   2. A pre-scoped `xref:<scope>:::cite-<key>[]` (manually prepending the
+ *      correct prefix): also broken, and worse. The rewriter does not
+ *      recognize an already-scoped target as special, so it double-
+ *      prefixes it with the citing page's own scope on top, producing
+ *      `index:::references:::cite-smith2020`.
+ *   3. `xref:<scope>.adoc#cite-<key>[]` (this one, working): an ordinary
+ *      inter-page Antora xref, explicitly naming its own target page,
+ *      exactly how an author would write a real cross-page reference in
+ *      normal, non-assembled content. Produces a real PDF `GoTo` action
+ *      with `Dest="references:::cite-smith2020"`, matching the real named
+ *      destination exactly.
+ *
+ * Falls back to a plain, unlinked `[N]` when a key has no entry in
+ * `scopes`: its category's host page was not found. This should not
+ * normally happen for a properly configured component, but a
+ * known-correct number with no link is a safer failure than a link known
+ * to point nowhere.
+ */
+function rewriteCiteMarkers(text, numbers, asLink = true, scopes = null) {
+    const lines = text.split('\n');
+    let inBlockComment = false;
+    return lines
+        .map((line) => {
+        const trimmed = line.trimStart();
+        if (trimmed.startsWith('////')) {
+            inBlockComment = !inBlockComment;
+            return line;
+        }
+        if (inBlockComment || trimmed.startsWith('//'))
+            return line;
+        return line.replace(CITE_MARKER_RE, (match, key, offset) => {
+            const before = line.slice(Math.max(0, offset - 1), offset);
+            const after = line.slice(offset + match.length, offset + match.length + 1);
+            // Skip a citeit:[key] wrapped in a monospace span (`citeit:[key]`)
+            // or a passthrough (+citeit:[key]+): both are how documentation
+            // shows the macro as literal example syntax, not a real citation.
+            if ((before === '`' && after === '`') || (before === '+' && after === '+'))
+                return match;
+            const num = numbers.get(key);
+            if (num === undefined)
+                return match;
+            if (!asLink)
+                return `[${num}]`;
+            const scope = scopes?.get(key);
+            return scope ? `xref:${scope}.adoc#cite-${key}[[${num}\\]]` : `[${num}]`;
+        });
+    })
+        .join('\n');
+}
+/**
+ * Reorders the generated bibliography partial's rows, within each
+ * `[horizontal]` block, into ascending citation-number order: the
+ * conventional reading order for a numbered bibliography, and NOT the
+ * order the partial was originally generated in. Node does not know
+ * citation numbers yet at that point; see `generateCategoryPartial` in
+ * index.ts. Only meaningful for assembled/PDF output, since that is the
+ * only context with numbers at all; called from the same place and at
+ * the same time as the row-label rewrite (rewritePartialForAssembly),
+ * after ordinary HTML conversion has already used the original order.
+ *
+ * A row is recognized by its leading `[[cite-<key>]]` anchor.
+ * `generateCategoryPartial` always emits one immediately before each row's
+ * label, so this matches on the anchor rather than the citeit:[key] token
+ * itself, meaning it still works whether called before or after
+ * rewriteCiteMarkers has already turned that token into its final `[N]`
+ * form. A row whose key never received a number, a ref_force entry
+ * genuinely never cited, sorts after every numbered row, in original
+ * order; this should not normally happen, since ref_force keys are
+ * always in the ordered-key list computeCitationNumbers assigns from, but
+ * is defended anyway.
+ */
+const ANCHOR_RE = /^\[\[cite-([\w.:/-]+)\]\]/;
+function reorderBibliographyRows(text, numbers) {
+    const lines = text.split('\n');
+    const out = [];
+    let block = null;
+    const flush = () => {
+        if (!block)
+            return;
+        block
+            .slice()
+            .sort((a, b) => (numbers.get(a.key) ?? Infinity) - (numbers.get(b.key) ?? Infinity))
+            .forEach((row) => out.push(row.line));
+        block = null;
+    };
+    for (const line of lines) {
+        const m = line.match(ANCHOR_RE);
+        if (m) {
+            block ?? (block = []);
+            block.push({ key: m[1], line });
+            continue;
+        }
+        flush();
+        out.push(line);
+    }
+    flush();
+    return out.join('\n');
+}
+/**
+ * Rewrites the generated bibliography partial's OWN `citeit:[key]` row
+ * labels to their final `[N]` numbers, mutating the file directly in the
+ * content catalog.
+ *
+ * Needed for a reason distinct from rewriteCiteMarkers' normal call site:
+ * Antora's own include processor resolves an `include::partial$...[]`
+ * directive by reading the target file's content directly from the
+ * catalog, without recursing back through `loadAsciiDoc` for the included
+ * content. That means the loadAsciiDoc wrapper (index.ts), which only sees
+ * each page's own raw text before it is parsed, never gets a chance to
+ * rewrite text that arrives via an include inside that parse; a citing
+ * page's own `citeit:[key]` usage rewrites correctly, but the generated
+ * partial's own row labels, pulled in during the same parse, would
+ * otherwise reach Ruby unrewritten. Called once per component-version,
+ * before any assembly-time loadAsciiDoc call can run (synchronous within
+ * the same navigationBuilt handler that computes `numbers`), so the
+ * partial is already correct by the time anything tries to include it.
+ *
+ * Also reorders the partial's rows into ascending citation-number order
+ * (reorderBibliographyRows) before rewriting labels: the order the partial
+ * was generated in has no relationship to citation number (Node does not
+ * know numbers yet at generation time), and a numbered bibliography listed
+ * out of number order reads as broken to anyone looking at it.
+ */
+function rewritePartialForAssembly(ctx, numbers) {
+    if (numbers.size === 0)
+        return;
+    for (const cp of ctx.categoryPartials) {
+        const partial = ctx.contentCatalog.getFiles().find((f) => f.src.component === ctx.component &&
+            f.src.version === ctx.version &&
+            f.src.family === 'partial' &&
+            f.src.module === ctx.module &&
+            f.src.relative === cp.relative);
+        if (!partial)
+            continue;
+        const before = partial.contents.toString('utf8');
+        const reordered = reorderBibliographyRows(before, numbers);
+        const after = rewriteCiteMarkers(reordered, numbers, false);
+        if (after !== before)
+            partial.contents = Buffer.from(after, 'utf8');
+    }
+}
+//# sourceMappingURL=assembly-numbering.js.map

package/dist/extensions/cite-it/assembly-numbering.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assembly-numbering.js","sourceRoot":"","sources":["../../../src/extensions/cite-it/assembly-numbering.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;;AAsIH,wDAyEC;AAiBD,wDAsBC;AA0ED,gDAiCC;AA0BD,0DA2BC;AA2BD,8DAiBC;AAhcD,mCAA8C;AAC9C,iDAA4E;AAC5E,6CAAoD;AACpD,2EAAuE;AACvE,uEAAgE;AA+ChE,8EAA8E;AAC9E,yEAAyE;AACzE,wEAAwE;AACxE,sEAAsE;AACtE,2EAA2E;AAC3E,yEAAyE;AACzE,2EAA2E;AAC3E,2EAA2E;AAC3E,oBAAoB;AACpB,8EAA8E;AAE9E,SAAS,0BAA0B,CAAC,OAAsC,EAAE,IAAiB,EAAE,GAAa;IAC1G,KAAK,MAAM,KAAK,IAAI,OAAO,IAAI,EAAE,EAAE,CAAC;QAClC,IAAI,KAAK,CAAC,OAAO,KAAK,UAAU,IAAI,CAAC,KAAK,CAAC,UAAU,IAAI,KAAK,CAAC,GAAG,EAAE,CAAC;YACnE,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC;YACvG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACxB,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;gBACnB,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACrB,CAAC;QACH,CAAC;QACD,0BAA0B,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;IACrD,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAS,sBAAsB,CAC7B,UAAyC,EACzC,KAAoB;IAEpB,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,0BAA0B,CAAC,UAAU,EAAE,IAAI,GAAG,EAAE,EAAE,SAAS,CAAC,CAAC;IAE7D,MAAM,UAAU,GAAG,IAAI,GAAG,EAAuB,CAAC;IAClD,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,CAAC,GAAG,CAAC,MAAM,KAAK,MAAM,IAAI,CAAC,CAAC,GAAG,EAAE,GAAG;YAAE,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IAC1E,CAAC;IAED,MAAM,MAAM,GAAkB,EAAE,CAAC;IACjC,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACtC,IAAI,IAAI;YAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAyBD;;;;;;;GAOG;AACH,SAAgB,sBAAsB,CACpC,UAAyC,EACzC,GAAgB;IAEhB,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC1C,MAAM,KAAK,GAAG,GAAG,CAAC,cAAc,CAAC,QAAQ,EAAE,CAAC,MAAM,CAChD,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,KAAK,GAAG,CAAC,SAAS,IAAI,CAAC,CAAC,GAAG,CAAC,OAAO,KAAK,GAAG,CAAC,OAAO,CAC1E,CAAC;IACF,MAAM,KAAK,GAAG,sBAAsB,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IACxD,uEAAuE;IACvE,wEAAwE;IACxE,mEAAmE;IACnE,oEAAoE;IACpE,sEAAsE;IACtE,sEAAsE;IACtE,sEAAsE;IACtE,uEAAuE;IACvE,qEAAqE;IACrE,uEAAuE;IACvE,iEAAiE;IACjE,oEAAoE;IACpE,wEAAwE;IACxE,MAAM,cAAc,GAAG,IAAI,GAAG,EAAU,CAAC;IACzC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,cAAc,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC7H,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,kEAAkE;QAClE,oEAAoE;QACpE,yEAAyE;QACzE,iEAAiE;QACjE,sEAAsE;QACtE,uEAAuE;QACvE,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC;QACrD,MAAM,GAAG,GAAG,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACvC,MAAM,WAAW,GAAG,IAAA,4CAAoB,EAAC,GAAG,CAAC,CAAC;QAC9C,MAAM,SAAS,GAAG,CAAC,IAAY,EAAW,EAAE;YAC1C,IAAI,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,OAAO,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC;YACjE,MAAM,CAAC,GAAG,GAAG,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;YACnC,OAAO,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,KAAK,CAAC;QACtD,CAAC,CAAC;QAEF,IAAI,IAAI,GAAG,IAAA,uBAAe,EAAC,GAAG,EAAE,SAAS,EAAE,EAAE,CAAC,CAAC;QAC/C,MAAM,KAAK,GAAG,IAAA,0BAAkB,EAC9B,IAAI,EACJ,GAAG,CAAC,cAAqE,EACzE,GAAG,CAAC,SAAS,EACb,GAAG,CAAC,OAAO,EACX,IAAI,CAAC,GAAG,CAAC,MAAM,IAAI,MAAM,EACzB,cAAc,EACd,EAAE,EACF,SAAS,EACT,EAAE,EACF,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CACpB,CAAC;QACF,IAAI,KAAK;YAAE,IAAI,GAAG,GAAG,IAAI,KAAK,IAAA,uBAAe,EAAC,KAAK,EAAE,SAAS,EAAE,EAAE,CAAC,EAAE,CAAC;QAEtE,oEAAoE;QACpE,+DAA+D;QAC/D,sEAAsE;QACtE,oEAAoE;QACpE,sEAAsE;QACtE,sEAAsE;QACtE,oEAAoE;QACpE,uEAAuE;QACvE,MAAM,WAAW,GAAG,IAAA,2BAAmB,EAAC,IAAA,qCAAe,EAAC,IAAI,CAAC,CAAC,CAAC;QAC/D,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;YAC9B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAgB,sBAAsB,CACpC,UAAyC,EACzC,GAAgB;IAEhB,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,MAAM,KAAK,GAAG,GAAG,CAAC,cAAc,CAAC,QAAQ,EAAE,CAAC,MAAM,CAChD,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,KAAK,GAAG,CAAC,SAAS,IAAI,CAAC,CAAC,GAAG,CAAC,OAAO,KAAK,GAAG,CAAC,OAAO,CAC1E,CAAC;IACF,MAAM,KAAK,GAAG,sBAAsB,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IACxD,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAEvF,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,SAAS,CAAC,IAAI,KAAK,CAAC;YAAE,MAAM;QAChC,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAClE,KAAK,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,EAAE,CAAC;YACjD,IAAI,IAAA,uBAAe,EAAC,GAAG,EAAE,QAAQ,CAAC,EAAE,CAAC;gBACnC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC;gBACxE,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC7B,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,8EAA8E;AAC9E,wEAAwE;AACxE,0EAA0E;AAC1E,2EAA2E;AAC3E,sEAAsE;AACtE,mEAAmE;AACnE,qEAAqE;AACrE,0EAA0E;AAC1E,0EAA0E;AAC1E,4EAA4E;AAC5E,0EAA0E;AAC1E,+CAA+C;AAC/C,8EAA8E;AAC9E,MAAM,cAAc,GAAG,oCAAoC,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,SAAgB,kBAAkB,CAChC,IAAY,EACZ,OAA4B,EAC5B,MAAM,GAAG,IAAI,EACb,SAAqC,IAAI;IAEzC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,cAAc,GAAG,KAAK,CAAC;IAE3B,OAAO,KAAK;SACT,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACZ,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;QACjC,IAAI,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YAC/B,cAAc,GAAG,CAAC,cAAc,CAAC;YACjC,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,cAAc,IAAI,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QAE5D,OAAO,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE;YACzD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;YAC3D,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YAC3E,mEAAmE;YACnE,gEAAgE;YAChE,kEAAkE;YAClE,IAAI,CAAC,MAAM,KAAK,GAAG,IAAI,KAAK,KAAK,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,GAAG,IAAI,KAAK,KAAK,GAAG,CAAC;gBAAE,OAAO,KAAK,CAAC;YACzF,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC7B,IAAI,GAAG,KAAK,SAAS;gBAAE,OAAO,KAAK,CAAC;YACpC,IAAI,CAAC,MAAM;gBAAE,OAAO,IAAI,GAAG,GAAG,CAAC;YAC/B,MAAM,KAAK,GAAG,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;YAC/B,OAAO,KAAK,CAAC,CAAC,CAAC,QAAQ,KAAK,cAAc,GAAG,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,GAAG,GAAG,CAAC;QAC3E,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,SAAS,GAAG,2BAA2B,CAAC;AAE9C,SAAgB,uBAAuB,CAAC,IAAY,EAAE,OAA4B;IAChF,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,IAAI,KAAK,GAAgD,IAAI,CAAC;IAE9D,MAAM,KAAK,GAAG,GAAG,EAAE;QACjB,IAAI,CAAC,KAAK;YAAE,OAAO;QACnB,KAAK;aACF,KAAK,EAAE;aACP,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,QAAQ,CAAC,CAAC;aACnF,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;QACxC,KAAK,GAAG,IAAI,CAAC;IACf,CAAC,CAAC;IAEF,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAChC,IAAI,CAAC,EAAE,CAAC;YACN,KAAK,KAAL,KAAK,GAAK,EAAE,EAAC;YACb,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;YAChC,SAAS;QACX,CAAC;QACD,KAAK,EAAE,CAAC;QACR,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjB,CAAC;IACD,KAAK,EAAE,CAAC;IAER,OAAO,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACxB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,SAAgB,yBAAyB,CAAC,GAAgB,EAAE,OAA4B;IACtF,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO;IAC/B,KAAK,MAAM,EAAE,IAAI,GAAG,CAAC,gBAAgB,EAAE,CAAC;QACtC,MAAM,OAAO,GAAG,GAAG,CAAC,cAAc,CAAC,QAAQ,EAAE,CAAC,IAAI,CAChD,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,CAAC,GAAG,CAAC,SAAS,KAAK,GAAG,CAAC,SAAS;YACjC,CAAC,CAAC,GAAG,CAAC,OAAO,KAAK,GAAG,CAAC,OAAO;YAC7B,CAAC,CAAC,GAAG,CAAC,MAAM,KAAK,SAAS;YAC1B,CAAC,CAAC,GAAG,CAAC,MAAM,KAAK,GAAG,CAAC,MAAM;YAC3B,CAAC,CAAC,GAAG,CAAC,QAAQ,KAAK,EAAE,CAAC,QAAQ,CACjC,CAAC;QACF,IAAI,CAAC,OAAO;YAAE,SAAS;QACvB,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACjD,MAAM,SAAS,GAAG,uBAAuB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC3D,MAAM,KAAK,GAAG,kBAAkB,CAAC,SAAS,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;QAC5D,IAAI,KAAK,KAAK,MAAM;YAAE,OAAO,CAAC,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACtE,CAAC;AACH,CAAC"}

package/dist/extensions/cite-it/csl.d.ts

@@ -0,0 +1,45 @@
+/**
+ * cite-it: CSL bibliography-entry formatting.
+ *
+ * Wraps `citeproc` to format CSL-JSON items into bibliography-entry text
+ * for the generated partial. citeproc's own citation-cluster numbering is
+ * not used: `processCitationCluster` needs the full running cluster
+ * history passed back on every call to number correctly, making it the
+ * wrong tool for `citeit:[key]`'s per-Document counter, which already
+ * solves numbering by walking the document in natural order (see
+ * assembly-numbering.ts and macro.ts's own render-mode numbering).
+ * citeproc here formats bibliography-entry text only; the entry's
+ * number/label comes from `citeit:[key]` itself, reused as the generated
+ * partial's row label (macro.ts), so the two numbering sources agree by
+ * construction rather than by cross-checking two independent counters.
+ *
+ * `STYLES` currently bundles one entry, `ieee-bracket`. This is a scope
+ * limit, not an architectural one: `loadEngine` takes any CSL style/locale
+ * pair placed under `resources/cite-it/` and registered in `STYLES` below,
+ * so adding a style is a matter of shipping its `.csl`/`.xml` files and one
+ * new `STYLES` entry, not a design change. A `style` value not present in
+ * `STYLES` is rejected with a clear error rather than silently falling
+ * back, since a silently wrong citation style is a worse failure than a
+ * build error naming the actual gap.
+ */
+import type { CslJsonItem } from './registry';
+/**
+ * Convert one citeproc bibliography entry's raw HTML fragment into AsciiDoc
+ * inline text. citeproc's output shape is two sibling <div>s per entry:
+ * `csl-left-margin` (the [N] bracket, citeproc's own numbering, discarded
+ * here since citeit:[key] supplies the real number) and `csl-right-inline`
+ * (the formatted entry text, kept). Only `csl-right-inline`'s content is
+ * used.
+ */
+export declare function htmlEntryToAsciiDoc(entryHtml: string): string;
+/**
+ * Format bibliography-entry text for a set of CSL-JSON items, keyed by
+ * citation key. `items` is the full merged registry (used for
+ * `retrieveItem` cross-references between entries, for example a
+ * `container-title` shared across a collection); `keys` selects and orders
+ * which items are actually formatted and returned: order does not need to
+ * match true citation order, since citeproc's own numbering is discarded
+ * (see the module docblock).
+ */
+export declare function formatBibliographyEntries(styleName: string, items: Map<string, CslJsonItem>, keys: string[]): Map<string, string>;
+//# sourceMappingURL=csl.d.ts.map

package/dist/extensions/cite-it/csl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csl.d.ts","sourceRoot":"","sources":["../../../src/extensions/cite-it/csl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AA4C9C;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAU7D;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,EAC/B,IAAI,EAAE,MAAM,EAAE,GACb,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAerB"}