@ai-matrx/print 0.6.1 → 0.7.0

package/dist/document.d.cts

@@ -0,0 +1,490 @@
+/**
+ * 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
+ * page layout, numbering, captions, cross-references and citations.
+ */
+type PageSizeName = "letter" | "legal" | "tabloid" | "executive" | "a3" | "a4" | "a5" | "b5";
+type Orientation = "portrait" | "landscape";
+/** All lengths are PostScript points (1in = 72pt). */
+interface Margins {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+type CitationStyle = "apa" | "mla" | "chicago";
+/**
+ * A running header or footer. Each slot is a template: `{page}`, `{pages}`,
+ * `{title}`, `{subtitle}`, `{author}`, `{date}` are substituted per page.
+ */
+interface RunningTemplate {
+    left?: string | undefined;
+    center?: string | undefined;
+    right?: string | undefined;
+}
+/** CSL-JSON name (the citation-style-language standard item shape). */
+interface CslName {
+    family?: string | undefined;
+    given?: string | undefined;
+    literal?: string | undefined;
+}
+/** A CSL-JSON reference item (the subset the three built-in styles read). */
+interface CslItem {
+    id: string;
+    type?: string | undefined;
+    title?: string | undefined;
+    author?: CslName[] | undefined;
+    editor?: CslName[] | undefined;
+    issued?: {
+        "date-parts"?: Array<Array<number | string>> | undefined;
+        literal?: string | undefined;
+    } | undefined;
+    "container-title"?: string | undefined;
+    publisher?: string | undefined;
+    "publisher-place"?: string | undefined;
+    volume?: string | number | undefined;
+    issue?: string | number | undefined;
+    page?: string | undefined;
+    edition?: string | number | undefined;
+    URL?: string | undefined;
+    DOI?: string | undefined;
+}
+interface DocumentSettings {
+    title?: string | undefined;
+    subtitle?: string | undefined;
+    author?: string | undefined;
+    date?: string | undefined;
+    /** Durable http(s) or data: URL for the cover logo. */
+    logo?: string | undefined;
+    lang: string;
+    page: {
+        size: PageSizeName;
+        /** Portrait width/height in points for `size`. */
+        width: number;
+        height: number;
+        orientation: Orientation;
+        margins: Margins;
+    };
+    cover: boolean;
+    toc: {
+        enabled: boolean;
+        depth: number;
+        title: string;
+    };
+    header: RunningTemplate | null;
+    footer: RunningTemplate | null;
+    /** No running header/footer on page 1 (always true with a cover page). */
+    differentFirstPage: boolean;
+    columns: 1 | 2 | 3;
+    numberSections: boolean;
+    citationStyle: CitationStyle;
+    bibliographyTitle: string;
+    references: CslItem[];
+    hyphenate: boolean;
+    /** Body size in points. */
+    fontSize: number;
+}
+interface DocumentNotice {
+    code: "frontmatter-invalid" | "setting-ignored" | "xref-unresolved" | "citation-unresolved" | "html-stripped" | "image-unavailable" | "glyph-substituted" | "empty-document";
+    message: string;
+    remedy: string;
+}
+type Inline = {
+    type: "text";
+    value: string;
+} | {
+    type: "strong" | "emphasis" | "delete";
+    children: Inline[];
+} | {
+    type: "code";
+    value: string;
+} | {
+    type: "link";
+    url: string;
+    children: Inline[];
+} | {
+    type: "break";
+} | {
+    type: "image";
+    url: string;
+    alt: string;
+}
+/** `@fig:x` / `@tbl:x` / `@sec:x` — `label` is final text ("Figure 2"). */
+ | {
+    type: "xref";
+    target: string;
+    label: string;
+    resolved: boolean;
+}
+/** `[@key]` — `label` is the formatted in-text citation. */
+ | {
+    type: "cite";
+    keys: string[];
+    label: string;
+    resolved: boolean;
+} | {
+    type: "noteRef";
+    n: number;
+};
+interface Caption {
+    kind: "fig" | "tbl";
+    /** Author id without prefix ("growth" for `{#fig:growth}`), if any. */
+    id?: string | undefined;
+    number: number;
+    /** "Figure 3" / "Table 1". */
+    label: string;
+    children: Inline[];
+}
+type Block = {
+    type: "heading";
+    level: number;
+    id: string;
+    /** "2.1" when section numbering is on. */
+    number?: string | undefined;
+    plain: string;
+    children: Inline[];
+    /** false for `{-}` / `{.unnumbered}` headings and the bibliography. */
+    numbered: boolean;
+} | {
+    type: "paragraph";
+    children: Inline[];
+} | {
+    type: "list";
+    ordered: boolean;
+    start: number;
+    items: ListItem[];
+} | {
+    type: "blockquote";
+    children: Block[];
+} | {
+    type: "code";
+    lang: string;
+    value: string;
+} | {
+    type: "table";
+    align: Array<"left" | "center" | "right" | null>;
+    header: Inline[][];
+    rows: Inline[][][];
+    caption?: Caption | undefined;
+} | {
+    type: "figure";
+    url: string;
+    alt: string;
+    caption?: Caption | undefined;
+} | {
+    type: "rule";
+} | {
+    type: "pageBreak";
+} | {
+    type: "toc";
+} | {
+    type: "bibliography";
+} | {
+    type: "notes";
+};
+interface ListItem {
+    checked: boolean | null;
+    children: Block[];
+}
+interface DocSection {
+    orientation: Orientation;
+    columns: 1 | 2 | 3;
+    blocks: Block[];
+}
+interface TocEntry {
+    id: string;
+    level: number;
+    /** Number + title, as printed ("2.1 Methods"). */
+    text: string;
+}
+interface BibliographyEntry {
+    id: string;
+    children: Inline[];
+}
+interface DocTree {
+    settings: DocumentSettings;
+    /** The markdown body (frontmatter removed). */
+    body: string;
+    sections: DocSection[];
+    toc: TocEntry[];
+    figures: Caption[];
+    tables: Caption[];
+    bibliography: BibliographyEntry[];
+    notes: Array<{
+        n: number;
+        children: Block[];
+    }>;
+    notices: DocumentNotice[];
+}
+/** An image fetched once and shared by every renderer. */
+interface ResolvedImage {
+    dataUrl: string;
+    bytes: Uint8Array;
+    mime: "image/png" | "image/jpeg" | "image/gif";
+    width: number;
+    height: number;
+}
+type ImageMap = Map<string, ResolvedImage | null>;
+
+/**
+ * Document settings carried in the markdown source's YAML frontmatter.
+ *
+ * Grammar: the source's FIRST line is exactly `---`; the block ends at the
+ * next line that is exactly `---` or `...`; the lines between are YAML 1.2
+ * (core schema — `2026-09-25` stays a string). A leading `---` with no closing
+ * line is a thematic break, not frontmatter. This is the same rule pandoc,
+ * Jekyll, Hugo and Obsidian use.
+ *
+ * Keys follow pandoc's names where pandoc has one (`title`, `subtitle`,
+ * `author`, `date`, `lang`, `papersize`, `geometry`, `toc`, `toc-depth`,
+ * `numbersections`, `csl`, `references`, `fontsize`) and accept camelCase /
+ * snake_case / kebab-case spellings of every key. Unknown keys are ignored
+ * silently (frontmatter is shared with other tools); a KNOWN key with a value
+ * we cannot use is announced with the remedy.
+ */
+
+/** Portrait page sizes in points. */
+declare const PAGE_SIZES: Readonly<Record<PageSizeName, {
+    width: number;
+    height: number;
+    label: string;
+}>>;
+declare const DEFAULT_FOOTER: RunningTemplate;
+interface FrontmatterSplit {
+    /** Parsed YAML mapping (empty when there is no frontmatter). */
+    data: Record<string, unknown>;
+    /** The markdown after the frontmatter block. */
+    body: string;
+    /** The raw YAML text, or null when the source has no frontmatter. */
+    raw: string | null;
+}
+/** Split `---` YAML frontmatter off a markdown source. Never throws. */
+declare function splitFrontmatter(source: string, notices?: DocumentNotice[]): FrontmatterSplit;
+/** A length: `1in`, `2.5cm`, `25mm`, `72pt`, `96px`, or a bare number (inches). */
+declare function parseLength(v: unknown): number | undefined;
+/** Accept CSL-JSON items plus friendly shorthands (`authors: [...]`, `year: 2020`). */
+declare function normalizeReference(raw: unknown): CslItem | null;
+interface ResolveSettingsOptions {
+    /** Used when the frontmatter has no `title`. */
+    title?: string | undefined;
+    /** Extra references (e.g. from a host's source records); frontmatter wins on id clash. */
+    references?: CslItem[] | undefined;
+    /** "Today" for `date: today` — injectable so tests are deterministic. */
+    now?: Date | undefined;
+}
+/** Turn a frontmatter mapping into complete, validated settings. */
+declare function resolveSettings(data: Record<string, unknown>, notices: DocumentNotice[], options?: ResolveSettingsOptions): DocumentSettings;
+/** Fill a running template for one page. */
+declare function fillTemplate(template: string, s: DocumentSettings, page: number | string, pages: number | string): string;
+
+/**
+ * markdown (+ frontmatter) → DocTree. The ONE parse every document output
+ * (PDF, DOCX, EPUB, HTML) renders from.
+ *
+ * Grammar:
+ *   • CommonMark + GFM (tables, task lists, strikethrough, autolinks,
+ *     footnotes) via micromark/mdast — the reference parser, not a regex.
+ *   • Page/section breaks, TOC and bibliography placement come ONLY from
+ *     `../directives` (the grammar the chat preview and the print skins share).
+ *   • Captions + cross-references follow pandoc-crossref:
+ *       ![A caption](url){#fig:growth}        figure, numbered "Figure N"
+ *       Table: A caption {#tbl:sales}         caption line before/after a table
+ *       ## Methods {#sec:methods}             heading id  (`{-}` = unnumbered)
+ *       see @fig:growth, @tbl:sales, @sec:methods
+ *   • Citations follow pandoc: [@key], [@key, p. 4], [@a; @b], [-@key], @key.
+ */
+
+interface ParseDocumentOptions extends ResolveSettingsOptions {
+    /** Where dropped/degraded content is announced (also collected on the tree). */
+    onNotice?: (notice: DocumentNotice) => void;
+}
+declare function plainText(inlines: Inline[]): string;
+/** Parse a markdown source (with optional frontmatter) into the document tree. */
+declare function parseDocument(source: string, options?: ParseDocumentOptions): DocTree;
+
+/**
+ * DocTree → HTML. Two uses, one renderer:
+ *   • `documentToHtml` — a standalone, print-grade HTML file: CSS paged media
+ *     (@page size/margins/orientation, running header/footer margin boxes with
+ *     "Page X of Y", a different first page, named landscape pages per
+ *     section, columns, widow/orphan control, keep-with-next headings, no
+ *     breaks inside tables/code/figures, hyphenation), always light.
+ *   • `renderBlocksHtml` — the block renderer the EPUB writer reuses (XHTML).
+ */
+
+interface HtmlRenderContext {
+    tree: DocTree;
+    images?: ImageMap | undefined;
+    /** XHTML output (EPUB): self-closed void elements. */
+    xhtml?: boolean;
+    /** Where an in-document id lives (EPUB chapters split the document). */
+    hrefFor?: (id: string) => string;
+    /** Image URL override (EPUB packages images inside the book). */
+    srcFor?: (url: string) => string;
+}
+declare function renderBlocksHtml(blocks: Block[], x: HtmlRenderContext): string;
+/** The print stylesheet for a document's settings. Light mode, always. */
+declare function documentCss(s: DocumentSettings): string;
+interface DocumentHtmlOptions {
+    images?: ImageMap | undefined;
+}
+/** 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.
+ *
+ * Word-native everywhere it matters, so the file keeps working when the reader
+ * edits it: real sections (size, margins, orientation, columns per section),
+ * running headers/footers with PAGE / NUMPAGES fields, a different first page
+ * (titlePage), a real TOC field pre-filled with entries and page numbers (and
+ * `updateFields` so Word refreshes it on open), SEQ-field captions with
+ * bookmarks, cross-references as internal hyperlinks, heading keep-with-next,
+ * widow/orphan control, table rows that never split with repeating header
+ * rows, automatic hyphenation.
+ */
+
+interface DocxOptions {
+    images?: ImageMap | undefined;
+    /** Heading id → page number (from the PDF layout) for the cached TOC. */
+    headingPages?: Map<string, number> | undefined;
+}
+declare function documentToDocx(tree: DocTree, options?: DocxOptions): Promise<Uint8Array>;
+
+/**
+ * DocTree → EPUB 3 (reflowable). The same block renderer as the HTML output
+ * (XHTML mode), one chapter per top-level heading, a navigation document built
+ * from the same TOC entries, images packaged inside the book.
+ *
+ * Container rules honoured: `mimetype` is the first entry and STORED
+ * (uncompressed); META-INF/container.xml points at the package document;
+ * nav.xhtml carries `epub:type="toc"`; dcterms:modified is set.
+ */
+
+interface EpubOptions {
+    images?: ImageMap | undefined;
+    /** Book identifier (defaults to a random urn:uuid). */
+    identifier?: string | undefined;
+    /** Modification time — injectable for deterministic tests. */
+    now?: Date | undefined;
+}
+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.
+ *
+ * ONE parsed tree (`parseDocument`) → PDF, DOCX, EPUB, HTML (+ the markdown
+ * source itself), so every format carries the same page setup, cover, TOC,
+ * numbered captions, cross-references, citations and bibliography.
+ *
+ * Settings live in the markdown's YAML frontmatter:
+ *
+ *   ---
+ *   title: Quarterly Review
+ *   subtitle: Operations
+ *   author: Jane Park
+ *   date: today
+ *   cover: true
+ *   toc: true                      # or { depth: 2, title: Contents }
+ *   page: { size: a4, orientation: portrait, margins: 1in }
+ *   header: "{title} | | {date}"   # left | center | right
+ *   footer: "Page {page} of {pages}"
+ *   firstPage: different
+ *   columns: 2
+ *   numberSections: true
+ *   csl: apa                       # apa | mla | chicago
+ *   references:
+ *     - id: smith2020
+ *       title: Paper Cuts
+ *       author: [Smith, Jane]
+ *       issued: 2020
+ *   ---
+ *
+ * Heavy engines (pdfmake, docx, jszip) load lazily when an export is called;
+ * parsing and HTML are pure string work and safe on the server.
+ */
+
+type DocumentFormat = "pdf" | "docx" | "epub" | "html" | "markdown";
+declare const DOCUMENT_FORMATS: ReadonlyArray<{
+    format: DocumentFormat;
+    label: string;
+    extension: string;
+    mime: string;
+}>;
+/** Load image bytes for a URL. Default: data: URLs decode, http(s) fetches. */
+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 {
+    /** File name without extension (default: the document title). */
+    fileName?: string | undefined;
+    imageLoader?: ImageLoader | undefined;
+}
+interface DocumentExport {
+    format: DocumentFormat;
+    bytes: Uint8Array;
+    mime: string;
+    fileName: string;
+    /** PDF only. */
+    pageCount?: number | undefined;
+    tree: DocTree;
+    notices: DocumentNotice[];
+}
+/** Export a markdown source to any document format. */
+declare function exportDocument(source: string, format: DocumentFormat, options?: ExportDocumentOptions): Promise<DocumentExport>;
+/** 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 };