@drghaliasri/butex 4.4.0 → 5.2.0

package/README.md

@@ -253,6 +253,10 @@ const latex = document2Latex(documentNode);
 const preview = document2Preview(documentNode, 'svg');
 ```
 
+`document2Latex(doc)` emits a **complete Arabic XeLaTeX document** by default (preamble + `\begin{document}` + body + `\end{document}`). Pass `{ wrapDocument: false }` for body-only blocks. Optional `digitsMapping: 'arabicdigits' | 'digits'` controls eastern vs western digit font mapping in the preamble (default `'arabicdigits'`). Pass `{ twocolumn: true }` for `\documentclass[12pt,a4paper,twocolumn]{article}`. See [`examples/example-latex-export.tex`](examples/example-latex-export.tex) for a full sample (regenerated by the wrap vitest). Hosts can also call `getArabicXeLatexPreamble()` alone.
+
+Figures and tables always export as centered `figure` / `table` floats. Optional caption/label fields (checkbox-driven in the editor) emit `\caption` / `\label`. Display math stays `\[…\]` unless an equation label is enabled, then export uses `\begin{equation}…\label{…}\end{equation}`. Internal cross-refs use `\ref` / `\eqref` tokens (separate from bibliography `\cite`).
+
 V2 exports Arabic TeX by default for equations saved from the embedded editor. Imported raw-only math is preserved as raw source and marked non-editable until a structured equation object is attached.
 
 ### Document JSON contract (`value` + `math_objects`)
@@ -332,7 +336,7 @@ export default function Page() {
 }
 ```
 
-Host apps still register BuTeX with MathJax before preview rendering. `uiLocale` selects Arabic (`"ar"`, the default) or English (`"en"`) document-editor chrome and is passed to the embedded equation editor. `documentDirection` independently controls prose inputs and preview flow without creating a second document tree. `equationSide` independently controls whether structured equations open, render, and save from the `"english"` or `"arabic"` side. Set `editableEquations={false}` to show math islands without equation insertion, deletion, or editor access. Set `previewOnly={true}` to render only the read-only document preview with no toolbar, editor panel, or equation drawer. Raw-only equations keep their original source because the browser does not parse raw LaTeX into equation ASTs. Document editor v2 defaults to **`tex-svg.js`**; use `tex-chtml.js` only if you pass `mathOutput="chtml"`.
+Host apps still register BuTeX with MathJax before preview rendering. `uiLocale` selects Arabic (`"ar"`, the default) or English (`"en"`) document-editor chrome and is passed to the embedded equation editor. `documentDirection` independently controls prose inputs and preview flow without creating a second document tree. `equationSide` independently controls whether structured equations open, render, and save from the `"english"` or `"arabic"` side. Set `editableEquations={false}` to show math islands without equation insertion, deletion, or editor access. Set `previewOnly={true}` to render only the read-only document preview with no toolbar, editor panel, or equation drawer. Optional `\includegraphics` `asset_id` is preserved on import; pass `resolveImageUrl={({ assetId, value }) => …})` so preview can load S3/CDN/local assets while plain `value` URLs keep working without a resolver. Document JSON may include root `meta` (`title`, `authors`, structured Hijri `date` `{ day, month, year }` with Arabic month names such as `"محرم"`, `abstract`) plus a `references` catalog (`key`, `authors`, `title`, `year`, `url`, `venue`) and `\cite{key1,key2}` spans in text values. Pass `documentMeta` to seed missing meta fields from the host; JSON keys win when present. The editor always centers a fixed basmala line before the title block and a closing ḥamdala after the body (preview + LaTeX). Hijri date uses day/month/year dropdowns (no calendar conversion; default year 1448). The editor shows numeric cite chips and a bibliography block. RTL preview/chips render reversed labels such as `[٣،٢،١]` (Arabic comma); LTR stays `[1, 2, 3]`. Pass `digitForm` (`western` / `arabicIndic` / `persianIndic`, defaulting from `documentDirection`) or use the toolbar digit control. LaTeX export keeps logical `\cite{…}` key order for XeLaTeX; digit shaping and bidi display in PDF belong in the host preamble (`bidi`/polyglossia + font `Mapping`, see `references/commands.py`). Range compression (`[3–7]`) is not implemented yet. Raw-only equations keep their original source because the browser does not parse raw LaTeX into equation ASTs. Document editor v2 defaults to **`tex-svg.js`**; use `tex-chtml.js` only if you pass `mathOutput="chtml"`.
 
 ### Styling/theming contract
 

package/dist/document2.d.mts

@@ -46,6 +46,82 @@ declare class ChainNode {
     toArabicLatex(): string;
 }
 
+type EditorSide = 'english' | 'arabic';
+type EditorNodeKind = 'char' | 'number' | 'operator' | 'delimiter' | 'frac' | 'sqrt' | 'env' | 'atomicCommand' | 'atomicOperatorCommand';
+type MatrixEnvStyle = 'matrix' | 'pmatrix' | 'bmatrix' | 'Bmatrix' | 'vmatrix' | 'Vmatrix';
+type GridEnvName = MatrixEnvStyle | 'array' | 'aligned';
+type EnvColumnAlignment = 'l' | 'c' | 'r';
+type CharacterFontId = 'default' | 'takween' | 'diwani' | 'diwaniOutline';
+type DigitFormId = 'western' | 'arabicIndic' | 'persianIndic';
+type EditorSyncState = 'synced' | 'diverged';
+type EditorChain = {
+    id: string;
+    nodes: EditorNode[];
+};
+type EditorNode = {
+    id: string;
+    kind: EditorNodeKind;
+    expr: string;
+    characterFont?: CharacterFontId;
+    superscript: EditorChain | null;
+    subscript: EditorChain | null;
+    leftDelimExpr: string;
+    rightDelimExpr: string;
+    innerExpr: EditorChain | null;
+    numerator: EditorChain | null;
+    denominator: EditorChain | null;
+    radicand: EditorChain | null;
+    rootIndex: EditorChain | null;
+    envName: GridEnvName | null;
+    matrixStyle: MatrixEnvStyle | null;
+    matrixRows: EditorChain[][] | null;
+    columnAlignments: EnvColumnAlignment[] | null;
+};
+type EditorCaret = {
+    chainId: string;
+    index: number;
+};
+type EditorSelectionRange = {
+    chainId: string;
+    anchorIndex: number;
+    focusIndex: number;
+};
+type EditorSyncMap = Record<string, {
+    expr: EditorSyncState;
+}>;
+type EditorDebugEntry = {
+    timestamp: string;
+    command: string;
+    activeSide: EditorSide;
+    englishLatex: string;
+    arabicLatex: string;
+    renderOk: boolean;
+    renderError: string | null;
+    note: string;
+};
+type EditorSession = {
+    englishTree: EditorChain;
+    arabicTree: EditorChain;
+    activeSide: EditorSide;
+    /** When true, each typed letter/digit inserts a new char/number leaf; when false, merge into adjacent same-kind leaves. */
+    splitLeafTyping: boolean;
+    /** One-shot: when true, the next insertChar/insertNumber bypasses leaf-merge (used by Space in merge mode). */
+    forceSplitNextLeaf: boolean;
+    /** When true and active side is Arabic, merged number typing prepends digits (RTL-style); still mirrored on EN/AR. */
+    arabicReverseNumberTyping: boolean;
+    /** Font applied to newly typed char nodes. */
+    currentCharacterFont: CharacterFontId;
+    /** Digit glyph form used for editor display and LaTeX preview output. */
+    currentDigitForm: DigitFormId;
+    caret: EditorCaret;
+    /** Whole-node range selection inside a single chain (anchor==focus means no selection). */
+    selection: EditorSelectionRange | null;
+    selectedNodeId: string | null;
+    selectedStructureNodeId: string | null;
+    sync: EditorSyncMap;
+    debugLog: EditorDebugEntry[];
+};
+
 type MathNode = {
     nodeType: 'MathObject';
     mathMode: string;
@@ -55,25 +131,55 @@ type MathNode = {
 
 type Document2ParseMode = 'english' | 'arabic';
 type Document2MathOutput = 'svg' | 'chtml';
+type Document2Direction = 'rtl' | 'ltr';
 type MathObject2Json = {
     node_type: 'MathObject';
     math_mode: string;
     lines: ChainJson[];
     closing: string;
 };
+type Reference2Json = {
+    key: string;
+    authors?: string;
+    title?: string;
+    year?: string;
+    url?: string;
+    venue?: string;
+};
+type HijriMonthId = 'محرم' | 'صفر' | 'ربيع الأول' | 'ربيع الآخر' | 'جمادى الأولى' | 'جمادى الآخرة' | 'رجب' | 'شعبان' | 'رمضان' | 'شوال' | 'ذو القعدة' | 'ذو الحجة';
+type Document2HijriDate = {
+    day: number;
+    month: HijriMonthId;
+    year: number;
+};
+type Document2Meta = {
+    title: string;
+    authors: string;
+    date: Document2HijriDate;
+    abstract: string;
+};
 type Document2Json = {
     node_type: 'DocumentObject';
+    meta?: Document2Meta;
+    references?: Reference2Json[];
     blocks: Document2BlockJson[];
 };
 type Document2BlockJson = {
     command: string;
     value?: string;
+    /** Stable host asset identity (e.g. S3 key / UUID); optional for \\includegraphics. */
+    asset_id?: string;
     math_objects?: MathObject2Json[];
     options?: Record<string, string>;
     closing?: string;
     items?: Document2ListItemJson[];
     rows?: string[][];
     columns?: string;
+    caption?: string;
+    label?: string;
+    caption_enabled?: boolean;
+    label_enabled?: boolean;
+    centered?: boolean;
 };
 type Document2ListItemJson = {
     value: string;
@@ -85,6 +191,15 @@ type Document2Diagnostic = {
     message: string;
     path: string;
 };
+type Reference2 = {
+    id: string;
+    key: string;
+    authors: string;
+    title: string;
+    year: string;
+    url: string;
+    venue: string;
+};
 type TextToken2 = {
     id: string;
     kind: 'text';
@@ -102,8 +217,22 @@ type MathToken2 = {
     editable: boolean;
     reason?: string;
     sourceOwner: 'imported-structured' | 'raw' | 'editor';
+    /** When true on display math, export as equation env with \\label. */
+    labelEnabled?: boolean;
+    label?: string;
+};
+type CiteToken2 = {
+    id: string;
+    kind: 'cite';
+    keys: string[];
+};
+type RefToken2 = {
+    id: string;
+    kind: 'ref';
+    keys: string[];
+    refCommand: 'ref' | 'eqref';
 };
-type InlineToken2 = TextToken2 | MathToken2;
+type InlineToken2 = TextToken2 | MathToken2 | CiteToken2 | RefToken2;
 type InlineField2 = {
     id: string;
     tokens: InlineToken2[];
@@ -113,6 +242,8 @@ type TextBlock2 = {
     kind: 'textBlock';
     command: '\\section' | '\\subsection' | '\\subsubsection' | '\\paragraph';
     field: InlineField2;
+    /** When true on \\paragraph, center in preview and LaTeX export. */
+    centered?: boolean;
 };
 type ListItem2 = {
     id: string;
@@ -126,6 +257,13 @@ type ListBlock2 = {
     closing: '\\end{itemize}' | '\\end{enumerate}';
     items: ListItem2[];
 };
+type FloatMeta2 = {
+    centered: boolean;
+    captionEnabled: boolean;
+    caption: string;
+    labelEnabled: boolean;
+    label: string;
+};
 type TableBlock2 = {
     id: string;
     kind: 'table';
@@ -133,13 +271,21 @@ type TableBlock2 = {
     closing: '\\end{tabular}';
     columns: string;
     rows: InlineField2[][];
-};
+} & FloatMeta2;
 type ImageBlock2 = {
     id: string;
     kind: 'image';
     command: '\\includegraphics';
     value: string;
+    /** Host asset identity from wire `asset_id`; preserved across value edits. */
+    assetId?: string;
     options: Record<string, string>;
+} & FloatMeta2;
+type BibliographyBlock2 = {
+    id: string;
+    kind: 'bibliography';
+    command: '\\begin{thebibliography}';
+    closing: '\\end{thebibliography}';
 };
 type RawBlock2 = {
     id: string;
@@ -147,9 +293,11 @@ type RawBlock2 = {
     command: '\\raw';
     value: string;
 };
-type Document2Block = TextBlock2 | ListBlock2 | TableBlock2 | ImageBlock2 | RawBlock2;
+type Document2Block = TextBlock2 | ListBlock2 | TableBlock2 | ImageBlock2 | BibliographyBlock2 | RawBlock2;
 type Document2Node = {
     nodeType: 'DocumentObject';
+    meta: Document2Meta;
+    references: Reference2[];
     blocks: Document2Block[];
     diagnostics: Document2Diagnostic[];
 };
@@ -165,6 +313,24 @@ type DetectedMathSpan2 = {
     closing: string;
     display: boolean;
 };
+type DetectedCiteSpan2 = {
+    kind: 'cite';
+    start: number;
+    end: number;
+    source: string;
+    keys: string[];
+};
+type DetectedRefSpan2 = {
+    kind: 'ref';
+    start: number;
+    end: number;
+    source: string;
+    keys: string[];
+    refCommand: 'ref' | 'eqref';
+};
+type DetectedInlineSpan2 = ({
+    kind: 'math';
+} & DetectedMathSpan2) | DetectedCiteSpan2 | DetectedRefSpan2;
 type PreviewInline2 = {
     kind: 'text';
     text: string;
@@ -175,8 +341,39 @@ type PreviewInline2 = {
     display: boolean;
     output: Document2MathOutput;
     editable: boolean;
+} | {
+    kind: 'cite';
+    id: string;
+    keys: string[];
+    label: string;
+} | {
+    kind: 'ref';
+    id: string;
+    keys: string[];
+    refCommand: 'ref' | 'eqref';
+    label: string;
 };
 type PreviewBlock2 = {
+    kind: 'basmala';
+    id: string;
+    text: string;
+    tex: string;
+} | {
+    kind: 'titleBlock';
+    id: string;
+    title?: string;
+    authors?: string;
+    date?: string;
+} | {
+    kind: 'abstract';
+    id: string;
+    text: string;
+} | {
+    kind: 'closing';
+    id: string;
+    text: string;
+    tex: string;
+} | {
     kind: 'heading';
     id: string;
     level: 1 | 2 | 3;
@@ -185,6 +382,7 @@ type PreviewBlock2 = {
     kind: 'paragraph';
     id: string;
     inlines: PreviewInline2[];
+    centered?: boolean;
 } | {
     kind: 'list';
     id: string;
@@ -198,11 +396,31 @@ type PreviewBlock2 = {
     kind: 'table';
     id: string;
     rows: PreviewInline2[][][];
+    caption?: string;
+    label?: string;
+    numberLabel?: string;
 } | {
     kind: 'image';
     id: string;
     src: string;
+    assetId?: string;
     options: Record<string, string>;
+    caption?: string;
+    label?: string;
+    numberLabel?: string;
+} | {
+    kind: 'bibliography';
+    id: string;
+    items: Array<{
+        id: string;
+        numberLabel: string;
+        key: string;
+        authors: string;
+        title: string;
+        year: string;
+        url: string;
+        venue: string;
+    }>;
 }
 /** Preview-only: raw / unknown blocks are omitted from preview until we add proper rendering. */
  | {
@@ -220,103 +438,171 @@ type Document2Preview = {
     blocks: PreviewBlock2[];
     mathIslands: MathIsland2[];
 };
-
-type EditorSide = 'english' | 'arabic';
-type EditorNodeKind = 'char' | 'number' | 'operator' | 'delimiter' | 'frac' | 'sqrt' | 'env' | 'atomicCommand' | 'atomicOperatorCommand';
-type MatrixEnvStyle = 'matrix' | 'pmatrix' | 'bmatrix' | 'Bmatrix' | 'vmatrix' | 'Vmatrix';
-type GridEnvName = MatrixEnvStyle | 'array' | 'aligned';
-type EnvColumnAlignment = 'l' | 'c' | 'r';
-type CharacterFontId = 'default' | 'takween' | 'diwani' | 'diwaniOutline';
-type DigitFormId = 'western' | 'arabicIndic' | 'persianIndic';
-type EditorSyncState = 'synced' | 'diverged';
-type EditorChain = {
-    id: string;
-    nodes: EditorNode[];
-};
-type EditorNode = {
-    id: string;
-    kind: EditorNodeKind;
-    expr: string;
-    characterFont?: CharacterFontId;
-    superscript: EditorChain | null;
-    subscript: EditorChain | null;
-    leftDelimExpr: string;
-    rightDelimExpr: string;
-    innerExpr: EditorChain | null;
-    numerator: EditorChain | null;
-    denominator: EditorChain | null;
-    radicand: EditorChain | null;
-    rootIndex: EditorChain | null;
-    envName: GridEnvName | null;
-    matrixStyle: MatrixEnvStyle | null;
-    matrixRows: EditorChain[][] | null;
-    columnAlignments: EnvColumnAlignment[] | null;
-};
-type EditorCaret = {
-    chainId: string;
-    index: number;
-};
-type EditorSelectionRange = {
-    chainId: string;
-    anchorIndex: number;
-    focusIndex: number;
+type FormatCiteLabelOptions = {
+    documentDirection?: Document2Direction;
+    digitForm?: DigitFormId;
 };
-type EditorSyncMap = Record<string, {
-    expr: EditorSyncState;
+
+type Document2LabelKind = 'fig' | 'tab' | 'eq';
+type Document2LabelEntry = {
+    key: string;
+    kind: Document2LabelKind;
+    caption: string;
+    /** Block id for fig/tab, or math token id for eq. */
+    ownerId: string;
+    number: number;
+};
+type FloatMetaPatch = {
+    centered?: boolean;
+    captionEnabled?: boolean;
+    caption?: string;
+    labelEnabled?: boolean;
+    label?: string;
+};
+declare function defaultFloatMeta(): {
+    centered: true;
+    captionEnabled: false;
+    caption: '';
+    labelEnabled: false;
+    label: '';
+};
+declare function parseFloatMetaFromJson(json: {
+    caption?: string;
+    label?: string;
+    caption_enabled?: boolean;
+    label_enabled?: boolean;
+    centered?: boolean;
+}): {
+    centered: boolean;
+    captionEnabled: boolean;
+    caption: string;
+    labelEnabled: boolean;
+    label: string;
+};
+declare function parseRefKeys(source: string): {
+    keys: string[];
+    refCommand: 'ref' | 'eqref';
+};
+declare function refTokenLatex(keys: string[], refCommand: 'ref' | 'eqref'): string;
+/** Collect enabled labels in document order, numbering per kind. */
+declare function collectDocument2Labels(document: Document2Node): Document2LabelEntry[];
+declare function labelNumberMap(document: Document2Node): Map<string, {
+    kind: Document2LabelKind;
+    number: number;
 }>;
-type EditorDebugEntry = {
-    timestamp: string;
-    command: string;
-    activeSide: EditorSide;
-    englishLatex: string;
-    arabicLatex: string;
-    renderOk: boolean;
-    renderError: string | null;
-    note: string;
-};
-type EditorSession = {
-    englishTree: EditorChain;
-    arabicTree: EditorChain;
-    activeSide: EditorSide;
-    /** When true, each typed letter/digit inserts a new char/number leaf; when false, merge into adjacent same-kind leaves. */
-    splitLeafTyping: boolean;
-    /** One-shot: when true, the next insertChar/insertNumber bypasses leaf-merge (used by Space in merge mode). */
-    forceSplitNextLeaf: boolean;
-    /** When true and active side is Arabic, merged number typing prepends digits (RTL-style); still mirrored on EN/AR. */
-    arabicReverseNumberTyping: boolean;
-    /** Font applied to newly typed char nodes. */
-    currentCharacterFont: CharacterFontId;
-    /** Digit glyph form used for editor display and LaTeX preview output. */
-    currentDigitForm: DigitFormId;
-    caret: EditorCaret;
-    /** Whole-node range selection inside a single chain (anchor==focus means no selection). */
-    selection: EditorSelectionRange | null;
-    selectedNodeId: string | null;
-    selectedStructureNodeId: string | null;
-    sync: EditorSyncMap;
-    debugLog: EditorDebugEntry[];
-};
+declare function formatRefLabel(keys: string[], document: Document2Node, refCommand: 'ref' | 'eqref', options?: FormatCiteLabelOptions): string;
+declare function stripDisplayMathDelimiters(source: string): string;
+declare function applyFloatMetaPatch<T extends ImageBlock2 | TableBlock2>(block: T, patch: FloatMetaPatch): void;
+
+type ButexUiLocale = 'ar' | 'en';
+
+declare const BUTEX_BASMALA = "\u0628\u0650\u0633\u0652\u0645\u0650 \u0627\u0644\u0644\u064E\u0651\u0647\u0650 \u0627\u0644\u0631\u064E\u0651\u062D\u0652\u0645\u064E\u0670\u0646\u0650 \u0627\u0644\u0631\u064E\u0651\u062D\u0650\u064A\u0645\u0650 \u0648\u064E\u0627\u0644\u0635\u064E\u0651\u0644\u064E\u0627\u0629\u064F \u0648\u064E\u0627\u0644\u0633\u064E\u0651\u0644\u064E\u0627\u0645\u064F \u0639\u064E\u0644\u064E\u0649\u0670 \u0631\u064E\u0633\u064F\u0648\u0644\u0650 \u0627\u0644\u0644\u064E\u0651\u0647\u0650 \uFDFA";
+declare const BUTEX_CLOSING_HAMDALA = "\u0627\u0644\u0652\u062D\u064E\u0645\u0652\u062F\u064F \u0644\u0650\u0644\u064E\u0651\u0647\u0650 \u0646\u064E\u0641\u064E\u0639\u064E\u0646\u064E\u0627 \u0628\u0650\u0639\u0650\u0644\u0652\u0645\u0650\u0647\u0650";
+/** Display-math body using BuTeX Diwani (for MathJax preview islands). */
+declare function butexDiwaniDisplayTex(text: string): string;
+/** Full display equation for XeLaTeX export. */
+declare function butexDiwaniDisplayLatex(text: string): string;
+declare const HIJRI_YEAR_MIN = 1400;
+declare const HIJRI_YEAR_MAX = 1500;
+declare const HIJRI_MONTH_IDS: HijriMonthId[];
+declare const DEFAULT_HIJRI_DATE: Document2HijriDate;
+declare function hijriMonthLabel(month: HijriMonthId, locale?: ButexUiLocale): string;
+declare function emptyDocument2Meta(): Document2Meta;
+declare function normalizeDocument2HijriDate(value: unknown): Document2HijriDate;
+declare function normalizeDocument2Meta(value: unknown): Document2Meta;
+type Document2MetaProp = Partial<Omit<Document2Meta, 'date'>> & {
+    date?: Partial<Document2HijriDate>;
+};
+/** Prop fills gaps; JSON wins only when the key is present on the JSON object. */
+declare function mergeDocument2Meta(fromJson: unknown, fromProp?: Document2MetaProp): Document2Meta;
+/** For live Document2Node meta: prop fills empty title/authors/abstract; date patch merges. */
+declare function fillDocument2MetaGaps(current: Document2Meta, fromProp?: Document2MetaProp): Document2Meta;
+declare function document2HasMaketitle(meta: Document2Meta): boolean;
+declare function document2HasAbstract(meta: Document2Meta): boolean;
+declare function document2HasTitleStack(meta: Document2Meta): boolean;
+type FormatHijriDateOptions = {
+    locale?: ButexUiLocale;
+    digitForm?: DigitFormId;
+};
+declare function formatHijriDate(date: Document2HijriDate, options?: FormatHijriDateOptions | ButexUiLocale): string;
+declare function cloneDocument2Meta(meta: Document2Meta): Document2Meta;
 
 declare function findFirstInlineField(document: Document2Node): InlineField2 | null;
 declare function updateTextToken(document: Document2Node, fieldId: string, tokenId: string, text: string): Document2Node;
 declare function cloneDocument2Node(document: Document2Node): Document2Node;
 declare function insertDocument2BlockAfter(document: Document2Node, afterBlockId: string | null | undefined, block: Document2Block): Document2Node;
 declare function moveDocument2BlockById(document: Document2Node, blockId: string, direction: -1 | 1): Document2Node;
+declare function moveDocument2BlockRange(document: Document2Node, from: number, to: number, direction: -1 | 1): Document2Node;
+declare function removeDocument2BlockRange(document: Document2Node, from: number, to: number): Document2Node;
 declare function removeMathTokenById(document: Document2Node, tokenId: string): Document2Node;
 declare function insertMathTokenAtCaret(document: Document2Node, fieldId: string, textTokenId: string | null, caretOffset: number, session: EditorSession, opening?: string, closing?: string, side?: EditorSide): Document2Node;
 declare function insertMathToken(document: Document2Node, fieldId: string, insertIndex: number, session: EditorSession, opening?: string, closing?: string, side?: EditorSide): Document2Node;
 declare function replaceMathTokenFromSession(document: Document2Node, tokenId: string, session: EditorSession, opening?: string, closing?: string, side?: EditorSide): Document2Node;
 declare function addDocument2TextBlock(document: Document2Node, command?: '\\section' | '\\subsection' | '\\subsubsection' | '\\paragraph', afterBlockId?: string | null): Document2Node;
+declare function updateDocument2TextBlockCentered(document: Document2Node, blockId: string, centered: boolean): Document2Node;
 declare function removeDocument2BlockById(document: Document2Node, blockId: string): Document2Node;
 declare function addDocument2ListBlock(document: Document2Node, ordered: boolean, afterBlockId?: string | null): Document2Node;
 declare function addDocument2TableBlock(document: Document2Node, columns?: string, rowCount?: number, colCount?: number, afterBlockId?: string | null): Document2Node;
 declare function addDocument2ImageBlock(document: Document2Node, src?: string, afterBlockId?: string | null): Document2Node;
 declare function updateDocument2ImageValue(document: Document2Node, blockId: string, value: string): Document2Node;
+declare function updateDocument2ImageMeta(document: Document2Node, blockId: string, patch: FloatMetaPatch): Document2Node;
+declare function updateDocument2TableMeta(document: Document2Node, blockId: string, patch: FloatMetaPatch): Document2Node;
+declare function updateMathTokenLabel(document: Document2Node, tokenId: string, patch: {
+    labelEnabled?: boolean;
+    label?: string;
+}): Document2Node;
+declare function insertRefTokenAtCaret(document: Document2Node, fieldId: string, textTokenId: string | null, caretOffset: number, keys: string[], refCommand?: 'ref' | 'eqref'): Document2Node;
+declare function updateRefTokenKeys(document: Document2Node, tokenId: string, keys: string[], refCommand?: 'ref' | 'eqref'): Document2Node;
+declare function removeRefTokenById(document: Document2Node, tokenId: string): Document2Node;
 declare function addDocument2ListItem(document: Document2Node, listBlockId: string): Document2Node;
 declare function removeDocument2ListItem(document: Document2Node, listBlockId: string, itemId: string): Document2Node;
+declare function insertCiteTokenAtCaret(document: Document2Node, fieldId: string, textTokenId: string | null, caretOffset: number, keys: string[]): Document2Node;
+declare function updateCiteTokenKeys(document: Document2Node, tokenId: string, keys: string[]): Document2Node;
+declare function removeCiteTokenById(document: Document2Node, tokenId: string): Document2Node;
+declare function ensureDocument2BibliographyBlock(document: Document2Node, afterBlockId?: string | null): Document2Node;
+declare function addDocument2Reference(document: Document2Node, partial?: Partial<Reference2Json>): Document2Node;
+declare function updateDocument2Reference(document: Document2Node, referenceId: string, patch: Partial<Reference2Json>): Document2Node;
+declare function removeDocument2Reference(document: Document2Node, referenceId: string): Document2Node;
+declare function moveDocument2Reference(document: Document2Node, referenceId: string, direction: -1 | 1): Document2Node;
+declare function setDocument2References(document: Document2Node, references: Reference2[]): Document2Node;
+declare function updateDocument2Meta(document: Document2Node, patch: Document2MetaProp): Document2Node;
+
+declare function referenceNumberMap(references: Array<Pick<Reference2, 'key'>>): Map<string, number>;
+declare function resolveCiteNumbers(keys: string[], references: Array<Pick<Reference2, 'key'>>): Array<number | null>;
+declare function formatCiteLabel(keys: string[], references: Array<Pick<Reference2, 'key'>>, options?: FormatCiteLabelOptions): string;
+declare function formatBibliographyNumber(index: number, options?: FormatCiteLabelOptions): string;
+declare function parseCiteKeys(source: string): string[];
+declare function citeTokenLatex(keys: string[]): string;
+declare function referenceFromJson(json: Reference2Json): Reference2;
+declare function createEmptyReference2(partial?: Partial<Reference2Json>): Reference2;
+declare function bibliographyEntryLatex(reference: Reference2): string;
 
+/** Arabic XeLaTeX preamble fragments for full-document export. */
+type ArabicDigitsMapping = 'arabicdigits' | 'digits';
+type ArabicXeLatexPreambleOptions = {
+    digitsMapping?: ArabicDigitsMapping;
+    /** When true, add the article class twocolumn option. Default false. */
+    twocolumn?: boolean;
+};
+declare function arabicXeLatexPreamblePkg(twocolumn?: boolean): string;
+declare function arabicXeLatexPreambleFont(digitsMapping?: ArabicDigitsMapping): string;
+declare function arabicXeLatexPreambleCmd(): string;
+declare function getArabicXeLatexPreamble(digitsMappingOrOptions?: ArabicDigitsMapping | ArabicXeLatexPreambleOptions): string;
+
+type Document2LatexOptions = {
+    /**
+     * When true (default), emit a complete Arabic XeLaTeX file:
+     * preamble + \\begin{document} + body + \\end{document}.
+     * Pass false for body-only blocks.
+     */
+    wrapDocument?: boolean;
+    /** Font digit Mapping when wrapping. Default 'arabicdigits'. */
+    digitsMapping?: ArabicDigitsMapping;
+    /** When true, use article class option twocolumn. Default false. */
+    twocolumn?: boolean;
+};
 declare function inlineFieldLatex(field: InlineField2): string;
-declare function document2Latex(document: Document2Node): string;
+declare function document2Latex(document: Document2Node, options?: Document2LatexOptions): string;
 
 declare const DEFAULT_DOCUMENT2_HISTORY_MAX_DEPTH = 100;
 type Document2HistoryStacks = {
@@ -331,11 +617,30 @@ declare function restoreDocument2Redo(stacks: Document2HistoryStacks, documentNo
 declare function document2HistoryCanUndo(stacks: Document2HistoryStacks): boolean;
 declare function document2HistoryCanRedo(stacks: Document2HistoryStacks): boolean;
 
+type BlockSelectionRange = {
+    from: number;
+    to: number;
+};
+type BlockSelectionState = {
+    selection: BlockSelectionRange | null;
+    anchor: number | null;
+};
+declare function emptyBlockSelection(): BlockSelectionState;
+declare function normalizeBlockSelection(selection: BlockSelectionRange | null, blockCount: number): BlockSelectionRange | null;
+/** Checkbox click without Shift */
+declare function toggleBlockInSelection(state: BlockSelectionState, index: number, blockCount: number): BlockSelectionState;
+/** Shift+click on checkbox or header label */
+declare function extendBlockSelectionFromAnchor(state: BlockSelectionState, index: number, blockCount: number): BlockSelectionState;
+declare function remapSelectionAfterRangeMove(selection: BlockSelectionRange, direction: -1 | 1): BlockSelectionRange;
+
 declare function createInlineField2(value?: string, mathObjects?: MathObject2Json[], options?: ImportDocument2Options, path?: string, diagnostics?: Document2Diagnostic[]): InlineField2;
 declare function fromDocumentJson2(json: unknown, options?: ImportDocument2Options): Document2Node;
 declare function createEmptyDocument2(): Document2Node;
 
+/** Math-only spans (used for math_objects alignment counts). */
 declare function detectMathSpans2(value: string): DetectedMathSpan2[];
+/** Left-to-right math + \\cite + \\ref/\\eqref spans without overlap. */
+declare function detectInlineSpans2(value: string): DetectedInlineSpan2[];
 
 type Document2MathBridgeResult = {
     editable: true;
@@ -354,6 +659,11 @@ declare function mathNodeFromSession(session: EditorSession, opening?: string, c
 declare function mathNodeFromArabicSession(session: EditorSession, opening?: string, closing?: string): MathNode;
 declare function mathTokenSourceForSide(token: MathToken2, side: EditorSide): string;
 
-declare function document2Preview(document: Document2Node, output?: Document2MathOutput, equationSide?: EditorSide): Document2Preview;
+type Document2PreviewOptions = {
+    documentDirection?: Document2Direction;
+    digitForm?: DigitFormId;
+    uiLocale?: ButexUiLocale;
+};
+declare function document2Preview(document: Document2Node, output?: Document2MathOutput, equationSide?: EditorSide, previewOptions?: Document2PreviewOptions): Document2Preview;
 
-export { DEFAULT_DOCUMENT2_HISTORY_MAX_DEPTH, type Document2Block, type Document2BlockJson, type Document2Diagnostic, type Document2HistoryStacks, type Document2Json, type Document2MathOutput, type Document2Node, type ImageBlock2, type ImportDocument2Options, type InlineField2, type InlineToken2, type ListBlock2, type MathIsland2, type MathObject2Json, type MathToken2, type PreviewBlock2, type PreviewInline2, type RawBlock2, type TableBlock2, type TextBlock2, type TextToken2, addDocument2ImageBlock, addDocument2ListBlock, addDocument2ListItem, addDocument2TableBlock, addDocument2TextBlock, cloneDocument2Node, createDocument2History, createEmptyArabicEquationSession, createEmptyDocument2, createEmptyEquationSession, createInlineField2, detectMathSpans2, document2HistoryCanRedo, document2HistoryCanUndo, document2Latex, document2Preview, findFirstInlineField, fromDocumentJson2, inlineFieldLatex, insertDocument2BlockAfter, insertMathToken, insertMathTokenAtCaret, mathNodeFromArabicSession, mathNodeFromSession, mathSourceFromArabicSession, mathSourceFromSession, mathTokenSourceForSide, mathTokenToArabicEditorSession, mathTokenToEditorSession, moveDocument2BlockById, pushDocument2Snapshot, removeDocument2BlockById, removeDocument2ListItem, removeMathTokenById, replaceMathTokenFromSession, restoreDocument2Redo, restoreDocument2Undo, updateDocument2ImageValue, updateTextToken };
+export { type ArabicDigitsMapping, type ArabicXeLatexPreambleOptions, BUTEX_BASMALA, BUTEX_CLOSING_HAMDALA, type BibliographyBlock2, type BlockSelectionRange, type BlockSelectionState, type CiteToken2, DEFAULT_DOCUMENT2_HISTORY_MAX_DEPTH, DEFAULT_HIJRI_DATE, type Document2Block, type Document2BlockJson, type Document2Diagnostic, type Document2Direction, type Document2HijriDate, type Document2HistoryStacks, type Document2Json, type Document2LabelEntry, type Document2LabelKind, type Document2LatexOptions, type Document2MathOutput, type Document2Meta, type Document2MetaProp, type Document2Node, type Document2Preview, type Document2PreviewOptions, type FloatMeta2, type FloatMetaPatch, type FormatCiteLabelOptions, HIJRI_MONTH_IDS, HIJRI_YEAR_MAX, HIJRI_YEAR_MIN, type HijriMonthId, type ImageBlock2, type ImportDocument2Options, type InlineField2, type InlineToken2, type ListBlock2, type MathIsland2, type MathObject2Json, type MathToken2, type PreviewBlock2, type PreviewInline2, type RawBlock2, type RefToken2, type Reference2, type Reference2Json, type TableBlock2, type TextBlock2, type TextToken2, addDocument2ImageBlock, addDocument2ListBlock, addDocument2ListItem, addDocument2Reference, addDocument2TableBlock, addDocument2TextBlock, applyFloatMetaPatch, arabicXeLatexPreambleCmd, arabicXeLatexPreambleFont, arabicXeLatexPreamblePkg, bibliographyEntryLatex, butexDiwaniDisplayLatex, butexDiwaniDisplayTex, citeTokenLatex, cloneDocument2Meta, cloneDocument2Node, collectDocument2Labels, createDocument2History, createEmptyArabicEquationSession, createEmptyDocument2, createEmptyEquationSession, createEmptyReference2, createInlineField2, defaultFloatMeta, detectInlineSpans2, detectMathSpans2, document2HasAbstract, document2HasMaketitle, document2HasTitleStack, document2HistoryCanRedo, document2HistoryCanUndo, document2Latex, document2Preview, emptyBlockSelection, emptyDocument2Meta, ensureDocument2BibliographyBlock, extendBlockSelectionFromAnchor, fillDocument2MetaGaps, findFirstInlineField, formatBibliographyNumber, formatCiteLabel, formatHijriDate, formatRefLabel, fromDocumentJson2, getArabicXeLatexPreamble, hijriMonthLabel, inlineFieldLatex, insertCiteTokenAtCaret, insertDocument2BlockAfter, insertMathToken, insertMathTokenAtCaret, insertRefTokenAtCaret, labelNumberMap, mathNodeFromArabicSession, mathNodeFromSession, mathSourceFromArabicSession, mathSourceFromSession, mathTokenSourceForSide, mathTokenToArabicEditorSession, mathTokenToEditorSession, mergeDocument2Meta, moveDocument2BlockById, moveDocument2BlockRange, moveDocument2Reference, normalizeBlockSelection, normalizeDocument2HijriDate, normalizeDocument2Meta, parseCiteKeys, parseFloatMetaFromJson, parseRefKeys, pushDocument2Snapshot, refTokenLatex, referenceFromJson, referenceNumberMap, remapSelectionAfterRangeMove, removeCiteTokenById, removeDocument2BlockById, removeDocument2BlockRange, removeDocument2ListItem, removeDocument2Reference, removeMathTokenById, removeRefTokenById, replaceMathTokenFromSession, resolveCiteNumbers, restoreDocument2Redo, restoreDocument2Undo, setDocument2References, stripDisplayMathDelimiters, toggleBlockInSelection, updateCiteTokenKeys, updateDocument2ImageMeta, updateDocument2ImageValue, updateDocument2Meta, updateDocument2Reference, updateDocument2TableMeta, updateDocument2TextBlockCentered, updateMathTokenLabel, updateRefTokenKeys, updateTextToken };