@drghaliasri/butex 5.0.0 → 5.3.0

package/README.md

@@ -253,7 +253,9 @@ 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'`). 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.
+`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.
 
@@ -334,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. 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 a root `references` catalog (`key`, `authors`, `title`, `year`, `url`, `venue`) and `\cite{key1,key2}` spans in text values; 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"`.
+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

@@ -146,8 +146,21 @@ type Reference2Json = {
     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[];
 };
@@ -162,6 +175,11 @@ type Document2BlockJson = {
     items?: Document2ListItemJson[];
     rows?: string[][];
     columns?: string;
+    caption?: string;
+    label?: string;
+    caption_enabled?: boolean;
+    label_enabled?: boolean;
+    centered?: boolean;
 };
 type Document2ListItemJson = {
     value: string;
@@ -199,13 +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 InlineToken2 = TextToken2 | MathToken2 | CiteToken2;
+type RefToken2 = {
+    id: string;
+    kind: 'ref';
+    keys: string[];
+    refCommand: 'ref' | 'eqref';
+};
+type InlineToken2 = TextToken2 | MathToken2 | CiteToken2 | RefToken2;
 type InlineField2 = {
     id: string;
     tokens: InlineToken2[];
@@ -215,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;
@@ -228,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';
@@ -235,7 +271,7 @@ type TableBlock2 = {
     closing: '\\end{tabular}';
     columns: string;
     rows: InlineField2[][];
-};
+} & FloatMeta2;
 type ImageBlock2 = {
     id: string;
     kind: 'image';
@@ -244,7 +280,7 @@ type ImageBlock2 = {
     /** Host asset identity from wire `asset_id`; preserved across value edits. */
     assetId?: string;
     options: Record<string, string>;
-};
+} & FloatMeta2;
 type BibliographyBlock2 = {
     id: string;
     kind: 'bibliography';
@@ -260,6 +296,7 @@ type RawBlock2 = {
 type Document2Block = TextBlock2 | ListBlock2 | TableBlock2 | ImageBlock2 | BibliographyBlock2 | RawBlock2;
 type Document2Node = {
     nodeType: 'DocumentObject';
+    meta: Document2Meta;
     references: Reference2[];
     blocks: Document2Block[];
     diagnostics: Document2Diagnostic[];
@@ -283,9 +320,17 @@ type DetectedCiteSpan2 = {
     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;
+} & DetectedMathSpan2) | DetectedCiteSpan2 | DetectedRefSpan2;
 type PreviewInline2 = {
     kind: 'text';
     text: string;
@@ -301,8 +346,34 @@ type PreviewInline2 = {
     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;
@@ -311,6 +382,7 @@ type PreviewBlock2 = {
     kind: 'paragraph';
     id: string;
     inlines: PreviewInline2[];
+    centered?: boolean;
 } | {
     kind: 'list';
     id: string;
@@ -324,12 +396,18 @@ 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;
@@ -365,21 +443,126 @@ type FormatCiteLabelOptions = {
     digitForm?: DigitFormId;
 };
 
+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;
+}>;
+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_LINE1 = "\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";
+declare const BUTEX_BASMALA_SALAWAT = "\u0635\u064E\u0644\u064E\u0651\u0649 \u0627\u0644\u0644\u064E\u0651\u0647\u064F \u0639\u064E\u0644\u064E\u064A\u0652\u0647\u0650 \u0648\u064E\u0633\u064E\u0644\u064E\u0651\u0645\u064E";
+/** Two-line basmala joined for UI / plain-text matchers. */
+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\n\u0635\u064E\u0644\u064E\u0651\u0649 \u0627\u0644\u0644\u064E\u0651\u0647\u064F \u0639\u064E\u0644\u064E\u064A\u0652\u0647\u0650 \u0648\u064E\u0633\u064E\u0644\u064E\u0651\u0645\u064E";
+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;
+/** Two-line Diwani body for MathJax basmala islands. */
+declare function butexBasmalaDisplayTex(): string;
+/** Standalone display equation when there is no \\maketitle (title-less docs). */
+declare function butexBasmalaDisplayLatex(): string;
+/** Titling hooks so the basmala stays attached to the visible title. */
+declare function butexBasmalaTitlingPreamble(): 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;
@@ -391,6 +574,7 @@ declare function updateDocument2Reference(document: Document2Node, referenceId:
 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>;
@@ -404,10 +588,15 @@ declare function bibliographyEntryLatex(reference: Reference2): string;
 
 /** Arabic XeLaTeX preamble fragments for full-document export. */
 type ArabicDigitsMapping = 'arabicdigits' | 'digits';
-declare function arabicXeLatexPreamblePkg(): string;
+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(digitsMapping?: ArabicDigitsMapping): string;
+declare function getArabicXeLatexPreamble(digitsMappingOrOptions?: ArabicDigitsMapping | ArabicXeLatexPreambleOptions): string;
 
 type Document2LatexOptions = {
     /**
@@ -418,6 +607,8 @@ type Document2LatexOptions = {
     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, options?: Document2LatexOptions): string;
@@ -435,13 +626,29 @@ 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 spans without overlap. */
+/** Left-to-right math + \\cite + \\ref/\\eqref spans without overlap. */
 declare function detectInlineSpans2(value: string): DetectedInlineSpan2[];
 
 type Document2MathBridgeResult = {
@@ -464,7 +671,8 @@ declare function mathTokenSourceForSide(token: MathToken2, side: EditorSide): st
 type Document2PreviewOptions = {
     documentDirection?: Document2Direction;
     digitForm?: DigitFormId;
+    uiLocale?: ButexUiLocale;
 };
 declare function document2Preview(document: Document2Node, output?: Document2MathOutput, equationSide?: EditorSide, previewOptions?: Document2PreviewOptions): Document2Preview;
 
-export { type ArabicDigitsMapping, type BibliographyBlock2, type CiteToken2, DEFAULT_DOCUMENT2_HISTORY_MAX_DEPTH, type Document2Block, type Document2BlockJson, type Document2Diagnostic, type Document2Direction, type Document2HistoryStacks, type Document2Json, type Document2LatexOptions, type Document2MathOutput, type Document2Node, type Document2PreviewOptions, type FormatCiteLabelOptions, type ImageBlock2, type ImportDocument2Options, type InlineField2, type InlineToken2, type ListBlock2, type MathIsland2, type MathObject2Json, type MathToken2, type PreviewBlock2, type PreviewInline2, type RawBlock2, type Reference2, type Reference2Json, type TableBlock2, type TextBlock2, type TextToken2, addDocument2ImageBlock, addDocument2ListBlock, addDocument2ListItem, addDocument2Reference, addDocument2TableBlock, addDocument2TextBlock, arabicXeLatexPreambleCmd, arabicXeLatexPreambleFont, arabicXeLatexPreamblePkg, bibliographyEntryLatex, citeTokenLatex, cloneDocument2Node, createDocument2History, createEmptyArabicEquationSession, createEmptyDocument2, createEmptyEquationSession, createEmptyReference2, createInlineField2, detectInlineSpans2, detectMathSpans2, document2HistoryCanRedo, document2HistoryCanUndo, document2Latex, document2Preview, ensureDocument2BibliographyBlock, findFirstInlineField, formatBibliographyNumber, formatCiteLabel, fromDocumentJson2, getArabicXeLatexPreamble, inlineFieldLatex, insertCiteTokenAtCaret, insertDocument2BlockAfter, insertMathToken, insertMathTokenAtCaret, mathNodeFromArabicSession, mathNodeFromSession, mathSourceFromArabicSession, mathSourceFromSession, mathTokenSourceForSide, mathTokenToArabicEditorSession, mathTokenToEditorSession, moveDocument2BlockById, moveDocument2Reference, parseCiteKeys, pushDocument2Snapshot, referenceFromJson, referenceNumberMap, removeCiteTokenById, removeDocument2BlockById, removeDocument2ListItem, removeDocument2Reference, removeMathTokenById, replaceMathTokenFromSession, resolveCiteNumbers, restoreDocument2Redo, restoreDocument2Undo, setDocument2References, updateCiteTokenKeys, updateDocument2ImageValue, updateDocument2Reference, updateTextToken };
+export { type ArabicDigitsMapping, type ArabicXeLatexPreambleOptions, BUTEX_BASMALA, BUTEX_BASMALA_LINE1, BUTEX_BASMALA_SALAWAT, 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, butexBasmalaDisplayLatex, butexBasmalaDisplayTex, butexBasmalaTitlingPreamble, 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 };