@ai-matrx/print 0.7.1 → 0.8.0

package/dist/document.d.cts

@@ -1,3 +1,50 @@
+type SplitWord = (word: string) => string[];
+/** Width of `text` in points for a pdfmake run's font/size. */
+type Measure = (text: string, run: Record<string, unknown>) => number;
+/** The embedded faces, measured and queried with fontkit (what pdfkit embeds). */
+interface Faces {
+    measure: Measure;
+    /** Can the body font draw this code point? */
+    body: (cp: number) => boolean;
+    /** Fallback faces in order (pdfmake font name + coverage). */
+    fallbacks: Array<{
+        font: string;
+        has: (cp: number) => boolean;
+    }>;
+}
+interface Typography {
+    split: SplitWord;
+    measure: Measure;
+}
+
+interface MathSpan {
+    tex: string;
+    display: boolean;
+}
+/** Replace every math span with a private-use token; returns the spans. */
+declare function extractMath(body: string): {
+    text: string;
+    spans: MathSpan[];
+};
+interface TypesetMath {
+    /** MathML (<math …>…</math>) for HTML/EPUB and the Word/PDF-inline writers. */
+    mathml: string;
+    /** SVG for PDF display math; widths in ex (1ex ≈ 0.442em in MathJax). */
+    svg?: string | undefined;
+    widthEx?: number | undefined;
+    heightEx?: number | undefined;
+    /** Error message when the TeX could not be typeset. */
+    error?: string | undefined;
+}
+declare const mathKey: (tex: string, display: boolean) => string;
+interface MNode {
+    tag: string;
+    attrs: Record<string, string>;
+    children: MNode[];
+    text: string;
+}
+declare function parseMathML(xml: string): MNode;
+
 /**
  * The document model every output of `@ai-matrx/print/document` is rendered
  * from. ONE parsed tree → PDF, DOCX, EPUB, HTML — so the four always agree on
@@ -12,7 +59,8 @@ interface Margins {
     bottom: number;
     left: number;
 }
-type CitationStyle = "apa" | "mla" | "chicago";
+/** A CSL style id or URL ("apa", "modern-language-association", "nature", https://…). */
+type CitationStyle = string;
 /**
  * A running header or footer. Each slot is a template: `{page}`, `{pages}`,
  * `{title}`, `{subtitle}`, `{author}`, `{date}` are substituted per page.
@@ -85,7 +133,7 @@ interface DocumentSettings {
     fontSize: number;
 }
 interface DocumentNotice {
-    code: "frontmatter-invalid" | "setting-ignored" | "xref-unresolved" | "citation-unresolved" | "html-stripped" | "image-unavailable" | "glyph-substituted" | "empty-document";
+    code: "frontmatter-invalid" | "setting-ignored" | "xref-unresolved" | "citation-unresolved" | "html-stripped" | "image-unavailable" | "glyph-substituted" | "content-lost" | "math-error" | "empty-document";
     message: string;
     remedy: string;
 }
@@ -125,6 +173,12 @@ type Inline = {
 } | {
     type: "noteRef";
     n: number;
+}
+/** TeX math; `display` = a `$$…$$` / `\[…\]` formula set inside text. */
+ | {
+    type: "math";
+    tex: string;
+    display: boolean;
 };
 interface Caption {
     kind: "fig" | "tbl";
@@ -181,6 +235,11 @@ type Block = {
     type: "bibliography";
 } | {
     type: "notes";
+}
+/** A display formula on its own. */
+ | {
+    type: "math";
+    tex: string;
 };
 interface ListItem {
     checked: boolean | null;
@@ -215,6 +274,11 @@ interface DocTree {
         children: Block[];
     }>;
     notices: DocumentNotice[];
+    /**
+     * Typeset math keyed by `mathKey(tex, display)`; filled by
+     * `prepareDocument` / `exportDocument` (empty after a bare `parseDocument`).
+     */
+    math: Map<string, TypesetMath>;
 }
 /** An image fetched once and shared by every renderer. */
 interface ResolvedImage {
@@ -226,6 +290,128 @@ interface ResolvedImage {
 }
 type ImageMap = Map<string, ResolvedImage | null>;
 
+/**
+ * DocTree → PDF (real text PDF via pdfmake — selectable, searchable,
+ * link-bearing; never a screenshot). pdfmake is loaded lazily at call time.
+ *
+ * Print behaviours: page size / margins / orientation, per-section
+ * orientation and 1–3 newspaper columns, cover page, running header/footer
+ * with "Page X of Y", different first page, table of contents WITH page
+ * numbers, numbered captions, cross-reference links, keep-with-next headings
+ * (a heading is never the last thing on a page), short paragraphs never split
+ * (orphan/widow control), table rows never split and header rows repeat,
+ * tables/code/figures kept whole when they fit on a page.
+ */
+
+/** Build the pdfmake document definition (exported for tests and hosts). */
+declare function buildPdfDefinition(tree: DocTree, images?: ImageMap, pageCountSink?: (n: number) => void, typo?: Typography, faces?: Faces): Record<string, unknown>;
+/** Loads a fallback font's bytes (TTF/OTF/WOFF); null when unavailable. */
+type FontLoader = () => Promise<Uint8Array | null>;
+/** Noto Emoji (SIL OFL) — the fontsource emoji subset. */
+declare const NOTO_EMOJI_URL = "https://cdn.jsdelivr.net/npm/@fontsource/noto-emoji@5.3.2/files/noto-emoji-emoji-400-normal.woff";
+/** Noto Sans Math (SIL OFL) — arrows, math operators, box drawing, geometric shapes. */
+declare const NOTO_SYMBOLS_URL = "https://cdn.jsdelivr.net/npm/@fontsource/noto-sans-math@5.3.0/files/noto-sans-math-latin-400-normal.woff";
+declare const defaultEmojiFontLoader: FontLoader;
+declare const defaultSymbolFontLoader: FontLoader;
+interface FallbackFontLoaders {
+    emoji?: FontLoader | undefined;
+    symbols?: FontLoader | undefined;
+}
+/**
+ * Words pdfmake did not put on a page: a text node with no position was never
+ * placed, and a node measured taller than its page (`__height`) whose lines
+ * all landed on ONE page was cut off (pdfmake keeps only the first page of an
+ * unbreakable block or unbreakable row). Header and footer are functions, not
+ * content, so they are not counted.
+ */
+declare function countUnplacedWords(content: unknown): number;
+/** Lay out a pdfmake definition (fonts registered); returns the PDF bytes. */
+declare function renderPdfDefinition(def: Record<string, unknown>): Promise<Uint8Array>;
+interface PdfResult {
+    bytes: Uint8Array;
+    pageCount: number;
+}
+declare function documentToPdf(tree: DocTree, images?: ImageMap, fonts?: FallbackFontLoaders): Promise<PdfResult>;
+
+/**
+ * Citation SYNTAX (pandoc). Formatting is done by a real CSL processor —
+ * citeproc-js over the official CSL styles (`./csl/engine.ts`).
+ *
+ * Syntax (pandoc): `[@smith2020]`, `[@smith2020, p. 4]`, `[@a; @b]`,
+ * `[-@smith2020]` (suppress the author), and a bare `@smith2020` in running
+ * text (narrative: "Smith (2020)") — the bare form only fires for a key that
+ * is actually in the reference list, so an email or an @-handle is never
+ * mistaken for a citation.
+ */
+interface CiteRef {
+    key: string;
+    locator?: string | undefined;
+    suppressAuthor: boolean;
+}
+/** Parse the inside of `[...]` into cite refs; null if it is not a citation. */
+declare function parseCitationGroup(inner: string): CiteRef[] | null;
+/**
+ * Every citation key a markdown body uses: bracketed groups and bare
+ * namespaced keys (`@research:…`, `@file:…`). Used to ask a host resolver
+ * for the references the frontmatter does not carry.
+ */
+declare function scanCitationKeys(body: string): string[];
+
+/**
+ * Citations through a real CSL processor — citeproc-js (the engine Zotero and
+ * Mendeley use) over styles from the official Citation Style Language
+ * repository. Any of its ~10,000 styles works by name:
+ *
+ *   csl: apa | mla | chicago | chicago-notes | ieee | harvard   (bundled, offline)
+ *   csl: nature | vancouver | american-medical-association | …  (fetched by name)
+ *   csl: https://…/my-style.csl                                  (fetched by URL)
+ *
+ * A dependent style (e.g. `nature` → its parent) is resolved to its
+ * independent parent. Note styles (Chicago notes and bibliography, …) turn
+ * each citation into a numbered note; in-text styles print it inline.
+ */
+
+/** Friendly names → CSL repository ids. */
+declare const CSL_STYLE_ALIASES: Readonly<Record<string, string>>;
+/** Normalize a `csl:` value to a repository id (or keep a URL). */
+declare function cslStyleId(name: string): string;
+/** The styles that ship inside the package (offline, no fetch). */
+declare const BUNDLED_STYLE_IDS: readonly string[];
+/** Fetches a URL's text; the host may override (proxy, cache, offline store). */
+type CslFetcher = (url: string) => Promise<string | null>;
+declare const defaultCslFetcher: CslFetcher;
+/** Load a style by id or URL, following a dependent style to its parent. */
+declare function loadCslStyle(name: string, fetcher?: CslFetcher): Promise<string | null>;
+/** Load a CSL locale (en-US is bundled). */
+declare function loadCslLocale(lang: string, fetcher?: CslFetcher): Promise<string | null>;
+/** Locator text ("p. 4", "chap. 3", "§ 2", "12") → CSL label + locator. */
+declare function parseLocator(raw: string | undefined): {
+    label?: string | undefined;
+    locator?: string | undefined;
+    suffix?: string | undefined;
+};
+interface CitationResult {
+    /** Plain in-text label, e.g. "(Kim & Alvarez, 2021, p. 58)" or "[1]". */
+    label: string;
+    /** Called when a LATER citation changes this one (disambiguation, ibid.). */
+    onUpdate: (fn: (label: string) => void) => void;
+}
+declare class CitationEngine {
+    private readonly engine;
+    private readonly clusters;
+    /** A note style: every citation becomes a numbered note. */
+    readonly isNote: boolean;
+    private readonly numeric;
+    constructor(styleXml: string, localeXml: string, items: CslItem[], lang: string);
+    /** Cite a group; `noteIndex` is the note number for note styles (0 = in text). */
+    cite(refs: CiteRef[], opts?: {
+        narrative?: boolean;
+        noteIndex?: number;
+    }): CitationResult;
+    /** The formatted reference list, in the style's order. */
+    bibliography(): BibliographyEntry[];
+}
+
 /**
  * Document settings carried in the markdown source's YAML frontmatter.
  *
@@ -297,6 +483,16 @@ declare function fillTemplate(template: string, s: DocumentSettings, page: numbe
 interface ParseDocumentOptions extends ResolveSettingsOptions {
     /** Where dropped/degraded content is announced (also collected on the tree). */
     onNotice?: (notice: DocumentNotice) => void;
+    /**
+     * CSL inputs loaded ahead of time (`prepareDocument` does this): style XML
+     * by style id, and the locale XML for the document's language. Bundled
+     * styles (apa, mla, chicago, chicago-notes, ieee, harvard) and en-US need
+     * nothing here.
+     */
+    csl?: {
+        styles?: Record<string, string> | undefined;
+        locale?: string | undefined;
+    } | undefined;
 }
 declare function plainText(inlines: Inline[]): string;
 /** Parse a markdown source (with optional frontmatter) into the document tree. */
@@ -331,27 +527,6 @@ interface DocumentHtmlOptions {
 /** A complete, standalone print-grade HTML document. */
 declare function documentToHtml(tree: DocTree, options?: DocumentHtmlOptions): string;
 
-/**
- * DocTree → PDF (real text PDF via pdfmake — selectable, searchable,
- * link-bearing; never a screenshot). pdfmake is loaded lazily at call time.
- *
- * Print behaviours: page size / margins / orientation, per-section
- * orientation and 1–3 newspaper columns, cover page, running header/footer
- * with "Page X of Y", different first page, table of contents WITH page
- * numbers, numbered captions, cross-reference links, keep-with-next headings
- * (a heading is never the last thing on a page), short paragraphs never split
- * (orphan/widow control), table rows never split and header rows repeat,
- * tables/code/figures kept whole when they fit on a page.
- */
-
-/** Build the pdfmake document definition (exported for tests and hosts). */
-declare function buildPdfDefinition(tree: DocTree, images?: ImageMap, pageCountSink?: (n: number) => void): Record<string, unknown>;
-interface PdfResult {
-    bytes: Uint8Array;
-    pageCount: number;
-}
-declare function documentToPdf(tree: DocTree, images?: ImageMap): Promise<PdfResult>;
-
 /**
  * DocTree → DOCX (Word). Uses the `docx` package, loaded lazily.
  *
@@ -391,36 +566,6 @@ interface EpubOptions {
 }
 declare function documentToEpub(tree: DocTree, options?: EpubOptions): Promise<Uint8Array>;
 
-/**
- * Citations and the reference list — pandoc citation syntax over CSL-JSON
- * reference items, formatted in three built-in styles:
- *
- *   apa      APA 7th edition (author–date)      (Smith & Jones, 2020, p. 4)
- *   mla      MLA 9th edition (author–page)      (Smith and Jones 4)
- *   chicago  Chicago 17th, author–date          (Smith and Jones 2020, 4)
- *
- * Syntax (pandoc): `[@smith2020]`, `[@smith2020, p. 4]`, `[@a; @b]`,
- * `[-@smith2020]` (suppress the author), and a bare `@smith2020` in running
- * text (narrative: "Smith (2020)") — the bare form only fires for a key that
- * is actually in the reference list, so an email or an @-handle is never
- * mistaken for a citation.
- */
-
-interface CiteRef {
-    key: string;
-    locator?: string | undefined;
-    suppressAuthor: boolean;
-}
-/** Parse the inside of `[...]` into cite refs; null if it is not a citation. */
-declare function parseCitationGroup(inner: string): CiteRef[] | null;
-/** Format one citation group as in-text text, e.g. "(Smith, 2020, p. 4; Lee, 2019)". */
-declare function formatCitation(refs: CiteRef[], lookup: (key: string) => CslItem | undefined, style: CitationStyle, narrative?: boolean): {
-    label: string;
-    resolved: boolean;
-};
-/** Format the reference list for the cited keys, sorted as the style requires. */
-declare function formatBibliography(items: CslItem[], style: CitationStyle): BibliographyEntry[];
-
 /**
  * @ai-matrx/print/document — print-grade documents from markdown.
  *
@@ -467,10 +612,35 @@ type ImageLoader = (url: string) => Promise<Uint8Array | null>;
 declare const defaultImageLoader: ImageLoader;
 /** Resolve every figure/logo image once. Failures are announced, never fatal. */
 declare function resolveDocumentImages(tree: DocTree, loader?: ImageLoader, onNotice?: (n: DocumentNotice) => void): Promise<ImageMap>;
-interface ExportDocumentOptions extends ParseDocumentOptions {
+interface PrepareDocumentOptions extends ParseDocumentOptions {
+    /**
+     * The host's reference resolver: given citation keys the frontmatter does
+     * not define (e.g. `research:<id>`, `file:<id>`), return CSL-JSON items for
+     * the ones it knows. AI Matrx resolves its research sources and files.
+     */
+    resolveReferences?: ((keys: string[]) => Promise<CslItem[]>) | undefined;
+    /** Fetches CSL styles/locales not bundled (default: the CSL repositories on GitHub). */
+    cslFetcher?: CslFetcher | undefined;
+}
+/**
+ * Parse with everything loaded: a citation style that is not bundled is
+ * fetched by name (following a dependent style to its parent), the CSL locale
+ * for `lang`, and references the host resolves. Use this (or exportDocument)
+ * whenever the document may cite; `parseDocument` stays synchronous.
+ */
+declare function prepareDocument(source: string, options?: PrepareDocumentOptions): Promise<DocTree>;
+/** Typeset the tree's math (MathJax, loaded only when there is math). */
+declare function typesetDocumentMath(tree: DocTree, onNotice?: (n: DocumentNotice) => void): Promise<void>;
+interface ExportDocumentOptions extends PrepareDocumentOptions {
     /** File name without extension (default: the document title). */
     fileName?: string | undefined;
     imageLoader?: ImageLoader | undefined;
+    /**
+     * PDF fallback fonts, loaded only when the document has characters Roboto
+     * cannot draw: `emoji` (default Noto Emoji) and `symbols` (default Noto Sans
+     * Math — arrows, math, box drawing), both from jsDelivr at call time.
+     */
+    fonts?: FallbackFontLoaders | undefined;
 }
 interface DocumentExport {
     format: DocumentFormat;
@@ -487,4 +657,4 @@ declare function exportDocument(source: string, format: DocumentFormat, options?
 /** Browser helper: save an export through a download link. */
 declare function downloadDocumentExport(exp: DocumentExport): void;
 
-export { type BibliographyEntry, type Block, type Caption, type CitationStyle, type CslItem, type CslName, DEFAULT_FOOTER, DOCUMENT_FORMATS, type DocSection, type DocTree, type DocumentExport, type DocumentFormat, type DocumentNotice, type DocumentSettings, type ExportDocumentOptions, type ImageLoader, type ImageMap, type Inline, type ListItem, type Margins, type Orientation, PAGE_SIZES, type PageSizeName, type ParseDocumentOptions, type ResolvedImage, type RunningTemplate, type TocEntry, buildPdfDefinition, defaultImageLoader, documentCss, documentToDocx, documentToEpub, documentToHtml, documentToPdf, downloadDocumentExport, exportDocument, fillTemplate, formatBibliography, formatCitation, normalizeReference, parseCitationGroup, parseDocument, parseLength, plainText, renderBlocksHtml, resolveDocumentImages, resolveSettings, splitFrontmatter };
+export { BUNDLED_STYLE_IDS, type BibliographyEntry, type Block, CSL_STYLE_ALIASES, type Caption, CitationEngine, type CitationStyle, type CslFetcher, type CslItem, type CslName, DEFAULT_FOOTER, DOCUMENT_FORMATS, type DocSection, type DocTree, type DocumentExport, type DocumentFormat, type DocumentNotice, type DocumentSettings, type ExportDocumentOptions, type FallbackFontLoaders, type FontLoader, type ImageLoader, type ImageMap, type Inline, type ListItem, type Margins, type MathSpan, NOTO_EMOJI_URL, NOTO_SYMBOLS_URL, type Orientation, PAGE_SIZES, type PageSizeName, type ParseDocumentOptions, type PrepareDocumentOptions, type ResolvedImage, type RunningTemplate, type TocEntry, type TypesetMath, buildPdfDefinition, countUnplacedWords, cslStyleId, defaultCslFetcher, defaultEmojiFontLoader, defaultImageLoader, defaultSymbolFontLoader, documentCss, documentToDocx, documentToEpub, documentToHtml, documentToPdf, downloadDocumentExport, exportDocument, extractMath, fillTemplate, loadCslLocale, loadCslStyle, mathKey, normalizeReference, parseCitationGroup, parseDocument, parseLength, parseLocator, parseMathML, plainText, prepareDocument, renderBlocksHtml, renderPdfDefinition, resolveDocumentImages, resolveSettings, scanCitationKeys, splitFrontmatter, typesetDocumentMath };