@drghaliasri/butex 5.3.1 → 5.3.2

package/dist/document2.d.mts

@@ -1,51 +1,3 @@
-type ArabicNodeJson = {
-    node_type: string;
-    expr?: string;
-    name?: string;
-    superscript?: ChainJson | null;
-    subscript?: ChainJson | null;
-    left_delim_expr?: string;
-    right_delim_expr?: string;
-    inner_expr?: ChainJson;
-    optional_args?: ChainJson[];
-    mandatory_args?: ChainJson[];
-    opening?: string;
-    closing?: string;
-    lines?: ChainJson[];
-};
-type ChainJson = {
-    node_type: 'ChainClass';
-    chain: ArabicNodeJson[];
-};
-declare class State {
-}
-declare class BaseAstNode {
-    state: State;
-    superscript: ChainNode | null;
-    subscript: ChainNode | null;
-    nodeType: string;
-    constructor(state?: State | null);
-    latex(): string;
-    arabicLatex(): string;
-    toArabicLatex(): string;
-    /** Latin-style scripts: `^{...}` and `_{...}` for english_json rendering. */
-    latexScripts(): string;
-    /**
-     * Arabic scripts use \\prescript{sup}{sub}{content} (matches reference Python output).
-     * Call with rendered strings for sup/sub chains (may be empty strings).
-     */
-    arabicLatexScripts(sup: string, sub: string, content: string): string;
-}
-declare class ChainNode {
-    chain: BaseAstNode[];
-    constructor(chain?: BaseAstNode[]);
-    latex(): string;
-    toEnglishLatex(): string;
-    /** RTL: reverse order relative to Latin chain (see test/ref_tests.txt). */
-    arabicLatex(): string;
-    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';
@@ -122,6 +74,56 @@ type EditorSession = {
     debugLog: EditorDebugEntry[];
 };
 
+type ButexUiLocale = 'ar' | 'en';
+
+type ArabicNodeJson = {
+    node_type: string;
+    expr?: string;
+    name?: string;
+    superscript?: ChainJson | null;
+    subscript?: ChainJson | null;
+    left_delim_expr?: string;
+    right_delim_expr?: string;
+    inner_expr?: ChainJson;
+    optional_args?: ChainJson[];
+    mandatory_args?: ChainJson[];
+    opening?: string;
+    closing?: string;
+    lines?: ChainJson[];
+};
+type ChainJson = {
+    node_type: 'ChainClass';
+    chain: ArabicNodeJson[];
+};
+declare class State {
+}
+declare class BaseAstNode {
+    state: State;
+    superscript: ChainNode | null;
+    subscript: ChainNode | null;
+    nodeType: string;
+    constructor(state?: State | null);
+    latex(): string;
+    arabicLatex(): string;
+    toArabicLatex(): string;
+    /** Latin-style scripts: `^{...}` and `_{...}` for english_json rendering. */
+    latexScripts(): string;
+    /**
+     * Arabic scripts use \\prescript{sup}{sub}{content} (matches reference Python output).
+     * Call with rendered strings for sup/sub chains (may be empty strings).
+     */
+    arabicLatexScripts(sup: string, sub: string, content: string): string;
+}
+declare class ChainNode {
+    chain: BaseAstNode[];
+    constructor(chain?: BaseAstNode[]);
+    latex(): string;
+    toEnglishLatex(): string;
+    /** RTL: reverse order relative to Latin chain (see test/ref_tests.txt). */
+    arabicLatex(): string;
+    toArabicLatex(): string;
+}
+
 type MathNode = {
     nodeType: 'MathObject';
     mathMode: string;
@@ -138,6 +140,7 @@ type MathObject2Json = {
     lines: ChainJson[];
     closing: string;
 };
+type ReferenceFieldSeparator = ',' | '،';
 type Reference2Json = {
     key: string;
     authors?: string;
@@ -145,6 +148,8 @@ type Reference2Json = {
     year?: string;
     url?: string;
     venue?: string;
+    /** Bibliography field join: LTR `,` or Arabic `،`. Defaults to `،` when omitted. */
+    field_separator?: ReferenceFieldSeparator;
 };
 type HijriMonthId = 'محرم' | 'صفر' | 'ربيع الأول' | 'ربيع الآخر' | 'جمادى الأولى' | 'جمادى الآخرة' | 'رجب' | 'شعبان' | 'رمضان' | 'شوال' | 'ذو القعدة' | 'ذو الحجة';
 type Document2HijriDate = {
@@ -199,6 +204,8 @@ type Reference2 = {
     year: string;
     url: string;
     venue: string;
+    /** Joins authors/title/venue/year in bibliography display and export. */
+    fieldSeparator: ReferenceFieldSeparator;
 };
 type TextToken2 = {
     id: string;
@@ -420,6 +427,7 @@ type PreviewBlock2 = {
         year: string;
         url: string;
         venue: string;
+        fieldSeparator: ReferenceFieldSeparator;
     }>;
 }
 /** Preview-only: raw / unknown blocks are omitted from preview until we add proper rendering. */
@@ -490,12 +498,19 @@ declare function labelNumberMap(document: Document2Node): Map<string, {
     kind: Document2LabelKind;
     number: number;
 }>;
+type FormatFloatCaptionTitleOptions = {
+    uiLocale?: ButexUiLocale;
+    documentDirection?: Document2Direction;
+    digitForm?: DigitFormId;
+};
+/** Localized numbered float/equation title: الشكل ١ / Figure 1 / المعادلة ١. */
+declare function formatFloatCaptionTitle(kind: Document2LabelKind, number: number, options?: FormatFloatCaptionTitleOptions): string;
+/** Caption line as shown in document preview: الشكل ١: نص / Figure 1. text. */
+declare function formatFloatCaptionPreview(title: string, caption: string | undefined, uiLocale?: ButexUiLocale): string;
 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 \u0671\u0644\u0644\u064E\u0651\u0670\u0647\u0650 \u0671\u0644\u0631\u064E\u0651\u062D\u0652\u0645\u064E\u0670\u0646\u0650 \u0671\u0644\u0631\u064E\u0651\u062D\u0650\u064A\u0645\u0650";
 declare const BUTEX_BASMALA_LINE2 = "\u0648\u064E\u0671\u0644\u0635\u064E\u0651\u0644\u064E\u0627\u0629\u064F \u0648\u064E\u0671\u0644\u0633\u064E\u0651\u0644\u064E\u0627\u0645\u064F \u0639\u064E\u0644\u064E\u0649\u0670 \u0631\u064E\u0633\u064F\u0648\u0644\u0650 \u0671\u0644\u0644\u064E\u0651\u0670\u0647\u0650";
 declare const BUTEX_BASMALA_SALAWAT = "\u0635\u064E\u0644\u064E\u0651\u0649 \u0671\u0644\u0644\u064E\u0651\u0647\u064F \u0639\u064E\u0644\u064E\u064A\u0652\u0647\u0650 \u0648\u064E\u0633\u064E\u0644\u064E\u0651\u0645\u064E";
@@ -585,6 +600,26 @@ declare function moveDocument2Reference(document: Document2Node, referenceId: st
 declare function setDocument2References(document: Document2Node, references: Reference2[]): Document2Node;
 declare function updateDocument2Meta(document: Document2Node, patch: Document2MetaProp): Document2Node;
 
+type Document2KeyError = 'empty' | 'invalid' | 'duplicate';
+/** NFC-normalize and trim a document key (label or bibliography). */
+declare function normalizeDocument2Key(key: string): string;
+/** True when key matches Unicode letters/marks, ASCII digits, and :._- with no spaces. */
+declare function isValidDocument2Key(key: string): boolean;
+type Document2KeyNamespace = {
+    references?: Array<Pick<Reference2, 'id' | 'key'>>;
+    labels?: Array<Pick<Document2LabelEntry, 'ownerId' | 'key'>>;
+    /** Skip this reference id when checking (editing that entry). */
+    excludeReferenceId?: string;
+    /** Skip this label owner id when checking (editing that float/eq). */
+    excludeOwnerId?: string;
+};
+/** Returns true if another reference or label already uses this key (NFC match). */
+declare function isDuplicateDocument2Key(key: string, namespace: Document2KeyNamespace): boolean;
+/** Classify a key for UI messaging: empty, invalid charset, or duplicate. */
+declare function document2KeyError(key: string, namespace?: Document2KeyNamespace): Document2KeyError | null;
+
+declare const DEFAULT_REFERENCE_FIELD_SEPARATOR: ReferenceFieldSeparator;
+declare function normalizeReferenceFieldSeparator(value: unknown): ReferenceFieldSeparator;
 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;
@@ -593,7 +628,17 @@ 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;
+/** Joined authors/title/venue/year for preview and export (no \\bibitem wrapper). */
+declare function bibliographyEntryBody(reference: Pick<Reference2, 'authors' | 'title' | 'venue' | 'year' | 'fieldSeparator'>, separator?: ReferenceFieldSeparator, options?: {
+    digitForm?: DigitFormId;
+}): string;
 declare function bibliographyEntryLatex(reference: Reference2): string;
+/**
+ * Build an href for a bibliography URL. Values without a scheme become https://…
+ * so the browser does not resolve them against the editor origin (e.g. localhost).
+ * Leaves http(s)/mailto/ftp and other schemed URLs unchanged. Empty → ''.
+ */
+declare function absoluteHttpHref(url: string): string;
 
 /** Arabic XeLaTeX preamble fragments for full-document export. */
 type ArabicDigitsMapping = 'arabicdigits' | 'digits';
@@ -684,4 +729,4 @@ type Document2PreviewOptions = {
 };
 declare function document2Preview(document: Document2Node, output?: Document2MathOutput, equationSide?: EditorSide, previewOptions?: Document2PreviewOptions): Document2Preview;
 
-export { type ArabicDigitsMapping, type ArabicXeLatexPreambleOptions, BUTEX_BASMALA, BUTEX_BASMALA_LINE1, BUTEX_BASMALA_LINE2, 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, butexInColumnMaketitleHook, 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 };
+export { type ArabicDigitsMapping, type ArabicXeLatexPreambleOptions, BUTEX_BASMALA, BUTEX_BASMALA_LINE1, BUTEX_BASMALA_LINE2, BUTEX_BASMALA_SALAWAT, BUTEX_CLOSING_HAMDALA, type BibliographyBlock2, type BlockSelectionRange, type BlockSelectionState, type CiteToken2, DEFAULT_DOCUMENT2_HISTORY_MAX_DEPTH, DEFAULT_HIJRI_DATE, DEFAULT_REFERENCE_FIELD_SEPARATOR, type Document2Block, type Document2BlockJson, type Document2Diagnostic, type Document2Direction, type Document2HijriDate, type Document2HistoryStacks, type Document2Json, type Document2KeyError, type Document2KeyNamespace, type Document2LabelEntry, type Document2LabelKind, type Document2LatexOptions, type Document2MathOutput, type Document2Meta, type Document2MetaProp, type Document2Node, type Document2Preview, type Document2PreviewOptions, type FloatMeta2, type FloatMetaPatch, type FormatCiteLabelOptions, type FormatFloatCaptionTitleOptions, 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 ReferenceFieldSeparator, type TableBlock2, type TextBlock2, type TextToken2, absoluteHttpHref, addDocument2ImageBlock, addDocument2ListBlock, addDocument2ListItem, addDocument2Reference, addDocument2TableBlock, addDocument2TextBlock, applyFloatMetaPatch, arabicXeLatexPreambleCmd, arabicXeLatexPreambleFont, arabicXeLatexPreamblePkg, bibliographyEntryBody, bibliographyEntryLatex, butexBasmalaDisplayLatex, butexBasmalaDisplayTex, butexBasmalaTitlingPreamble, butexDiwaniDisplayLatex, butexDiwaniDisplayTex, butexInColumnMaketitleHook, citeTokenLatex, cloneDocument2Meta, cloneDocument2Node, collectDocument2Labels, createDocument2History, createEmptyArabicEquationSession, createEmptyDocument2, createEmptyEquationSession, createEmptyReference2, createInlineField2, defaultFloatMeta, detectInlineSpans2, detectMathSpans2, document2HasAbstract, document2HasMaketitle, document2HasTitleStack, document2HistoryCanRedo, document2HistoryCanUndo, document2KeyError, document2Latex, document2Preview, emptyBlockSelection, emptyDocument2Meta, ensureDocument2BibliographyBlock, extendBlockSelectionFromAnchor, fillDocument2MetaGaps, findFirstInlineField, formatBibliographyNumber, formatCiteLabel, formatFloatCaptionPreview, formatFloatCaptionTitle, formatHijriDate, formatRefLabel, fromDocumentJson2, getArabicXeLatexPreamble, hijriMonthLabel, inlineFieldLatex, insertCiteTokenAtCaret, insertDocument2BlockAfter, insertMathToken, insertMathTokenAtCaret, insertRefTokenAtCaret, isDuplicateDocument2Key, isValidDocument2Key, labelNumberMap, mathNodeFromArabicSession, mathNodeFromSession, mathSourceFromArabicSession, mathSourceFromSession, mathTokenSourceForSide, mathTokenToArabicEditorSession, mathTokenToEditorSession, mergeDocument2Meta, moveDocument2BlockById, moveDocument2BlockRange, moveDocument2Reference, normalizeBlockSelection, normalizeDocument2HijriDate, normalizeDocument2Key, normalizeDocument2Meta, normalizeReferenceFieldSeparator, 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 };

package/dist/document2.d.ts

@@ -1,51 +1,3 @@
-type ArabicNodeJson = {
-    node_type: string;
-    expr?: string;
-    name?: string;
-    superscript?: ChainJson | null;
-    subscript?: ChainJson | null;
-    left_delim_expr?: string;
-    right_delim_expr?: string;
-    inner_expr?: ChainJson;
-    optional_args?: ChainJson[];
-    mandatory_args?: ChainJson[];
-    opening?: string;
-    closing?: string;
-    lines?: ChainJson[];
-};
-type ChainJson = {
-    node_type: 'ChainClass';
-    chain: ArabicNodeJson[];
-};
-declare class State {
-}
-declare class BaseAstNode {
-    state: State;
-    superscript: ChainNode | null;
-    subscript: ChainNode | null;
-    nodeType: string;
-    constructor(state?: State | null);
-    latex(): string;
-    arabicLatex(): string;
-    toArabicLatex(): string;
-    /** Latin-style scripts: `^{...}` and `_{...}` for english_json rendering. */
-    latexScripts(): string;
-    /**
-     * Arabic scripts use \\prescript{sup}{sub}{content} (matches reference Python output).
-     * Call with rendered strings for sup/sub chains (may be empty strings).
-     */
-    arabicLatexScripts(sup: string, sub: string, content: string): string;
-}
-declare class ChainNode {
-    chain: BaseAstNode[];
-    constructor(chain?: BaseAstNode[]);
-    latex(): string;
-    toEnglishLatex(): string;
-    /** RTL: reverse order relative to Latin chain (see test/ref_tests.txt). */
-    arabicLatex(): string;
-    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';
@@ -122,6 +74,56 @@ type EditorSession = {
     debugLog: EditorDebugEntry[];
 };
 
+type ButexUiLocale = 'ar' | 'en';
+
+type ArabicNodeJson = {
+    node_type: string;
+    expr?: string;
+    name?: string;
+    superscript?: ChainJson | null;
+    subscript?: ChainJson | null;
+    left_delim_expr?: string;
+    right_delim_expr?: string;
+    inner_expr?: ChainJson;
+    optional_args?: ChainJson[];
+    mandatory_args?: ChainJson[];
+    opening?: string;
+    closing?: string;
+    lines?: ChainJson[];
+};
+type ChainJson = {
+    node_type: 'ChainClass';
+    chain: ArabicNodeJson[];
+};
+declare class State {
+}
+declare class BaseAstNode {
+    state: State;
+    superscript: ChainNode | null;
+    subscript: ChainNode | null;
+    nodeType: string;
+    constructor(state?: State | null);
+    latex(): string;
+    arabicLatex(): string;
+    toArabicLatex(): string;
+    /** Latin-style scripts: `^{...}` and `_{...}` for english_json rendering. */
+    latexScripts(): string;
+    /**
+     * Arabic scripts use \\prescript{sup}{sub}{content} (matches reference Python output).
+     * Call with rendered strings for sup/sub chains (may be empty strings).
+     */
+    arabicLatexScripts(sup: string, sub: string, content: string): string;
+}
+declare class ChainNode {
+    chain: BaseAstNode[];
+    constructor(chain?: BaseAstNode[]);
+    latex(): string;
+    toEnglishLatex(): string;
+    /** RTL: reverse order relative to Latin chain (see test/ref_tests.txt). */
+    arabicLatex(): string;
+    toArabicLatex(): string;
+}
+
 type MathNode = {
     nodeType: 'MathObject';
     mathMode: string;
@@ -138,6 +140,7 @@ type MathObject2Json = {
     lines: ChainJson[];
     closing: string;
 };
+type ReferenceFieldSeparator = ',' | '،';
 type Reference2Json = {
     key: string;
     authors?: string;
@@ -145,6 +148,8 @@ type Reference2Json = {
     year?: string;
     url?: string;
     venue?: string;
+    /** Bibliography field join: LTR `,` or Arabic `،`. Defaults to `،` when omitted. */
+    field_separator?: ReferenceFieldSeparator;
 };
 type HijriMonthId = 'محرم' | 'صفر' | 'ربيع الأول' | 'ربيع الآخر' | 'جمادى الأولى' | 'جمادى الآخرة' | 'رجب' | 'شعبان' | 'رمضان' | 'شوال' | 'ذو القعدة' | 'ذو الحجة';
 type Document2HijriDate = {
@@ -199,6 +204,8 @@ type Reference2 = {
     year: string;
     url: string;
     venue: string;
+    /** Joins authors/title/venue/year in bibliography display and export. */
+    fieldSeparator: ReferenceFieldSeparator;
 };
 type TextToken2 = {
     id: string;
@@ -420,6 +427,7 @@ type PreviewBlock2 = {
         year: string;
         url: string;
         venue: string;
+        fieldSeparator: ReferenceFieldSeparator;
     }>;
 }
 /** Preview-only: raw / unknown blocks are omitted from preview until we add proper rendering. */
@@ -490,12 +498,19 @@ declare function labelNumberMap(document: Document2Node): Map<string, {
     kind: Document2LabelKind;
     number: number;
 }>;
+type FormatFloatCaptionTitleOptions = {
+    uiLocale?: ButexUiLocale;
+    documentDirection?: Document2Direction;
+    digitForm?: DigitFormId;
+};
+/** Localized numbered float/equation title: الشكل ١ / Figure 1 / المعادلة ١. */
+declare function formatFloatCaptionTitle(kind: Document2LabelKind, number: number, options?: FormatFloatCaptionTitleOptions): string;
+/** Caption line as shown in document preview: الشكل ١: نص / Figure 1. text. */
+declare function formatFloatCaptionPreview(title: string, caption: string | undefined, uiLocale?: ButexUiLocale): string;
 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 \u0671\u0644\u0644\u064E\u0651\u0670\u0647\u0650 \u0671\u0644\u0631\u064E\u0651\u062D\u0652\u0645\u064E\u0670\u0646\u0650 \u0671\u0644\u0631\u064E\u0651\u062D\u0650\u064A\u0645\u0650";
 declare const BUTEX_BASMALA_LINE2 = "\u0648\u064E\u0671\u0644\u0635\u064E\u0651\u0644\u064E\u0627\u0629\u064F \u0648\u064E\u0671\u0644\u0633\u064E\u0651\u0644\u064E\u0627\u0645\u064F \u0639\u064E\u0644\u064E\u0649\u0670 \u0631\u064E\u0633\u064F\u0648\u0644\u0650 \u0671\u0644\u0644\u064E\u0651\u0670\u0647\u0650";
 declare const BUTEX_BASMALA_SALAWAT = "\u0635\u064E\u0644\u064E\u0651\u0649 \u0671\u0644\u0644\u064E\u0651\u0647\u064F \u0639\u064E\u0644\u064E\u064A\u0652\u0647\u0650 \u0648\u064E\u0633\u064E\u0644\u064E\u0651\u0645\u064E";
@@ -585,6 +600,26 @@ declare function moveDocument2Reference(document: Document2Node, referenceId: st
 declare function setDocument2References(document: Document2Node, references: Reference2[]): Document2Node;
 declare function updateDocument2Meta(document: Document2Node, patch: Document2MetaProp): Document2Node;
 
+type Document2KeyError = 'empty' | 'invalid' | 'duplicate';
+/** NFC-normalize and trim a document key (label or bibliography). */
+declare function normalizeDocument2Key(key: string): string;
+/** True when key matches Unicode letters/marks, ASCII digits, and :._- with no spaces. */
+declare function isValidDocument2Key(key: string): boolean;
+type Document2KeyNamespace = {
+    references?: Array<Pick<Reference2, 'id' | 'key'>>;
+    labels?: Array<Pick<Document2LabelEntry, 'ownerId' | 'key'>>;
+    /** Skip this reference id when checking (editing that entry). */
+    excludeReferenceId?: string;
+    /** Skip this label owner id when checking (editing that float/eq). */
+    excludeOwnerId?: string;
+};
+/** Returns true if another reference or label already uses this key (NFC match). */
+declare function isDuplicateDocument2Key(key: string, namespace: Document2KeyNamespace): boolean;
+/** Classify a key for UI messaging: empty, invalid charset, or duplicate. */
+declare function document2KeyError(key: string, namespace?: Document2KeyNamespace): Document2KeyError | null;
+
+declare const DEFAULT_REFERENCE_FIELD_SEPARATOR: ReferenceFieldSeparator;
+declare function normalizeReferenceFieldSeparator(value: unknown): ReferenceFieldSeparator;
 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;
@@ -593,7 +628,17 @@ 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;
+/** Joined authors/title/venue/year for preview and export (no \\bibitem wrapper). */
+declare function bibliographyEntryBody(reference: Pick<Reference2, 'authors' | 'title' | 'venue' | 'year' | 'fieldSeparator'>, separator?: ReferenceFieldSeparator, options?: {
+    digitForm?: DigitFormId;
+}): string;
 declare function bibliographyEntryLatex(reference: Reference2): string;
+/**
+ * Build an href for a bibliography URL. Values without a scheme become https://…
+ * so the browser does not resolve them against the editor origin (e.g. localhost).
+ * Leaves http(s)/mailto/ftp and other schemed URLs unchanged. Empty → ''.
+ */
+declare function absoluteHttpHref(url: string): string;
 
 /** Arabic XeLaTeX preamble fragments for full-document export. */
 type ArabicDigitsMapping = 'arabicdigits' | 'digits';
@@ -684,4 +729,4 @@ type Document2PreviewOptions = {
 };
 declare function document2Preview(document: Document2Node, output?: Document2MathOutput, equationSide?: EditorSide, previewOptions?: Document2PreviewOptions): Document2Preview;
 
-export { type ArabicDigitsMapping, type ArabicXeLatexPreambleOptions, BUTEX_BASMALA, BUTEX_BASMALA_LINE1, BUTEX_BASMALA_LINE2, 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, butexInColumnMaketitleHook, 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 };
+export { type ArabicDigitsMapping, type ArabicXeLatexPreambleOptions, BUTEX_BASMALA, BUTEX_BASMALA_LINE1, BUTEX_BASMALA_LINE2, BUTEX_BASMALA_SALAWAT, BUTEX_CLOSING_HAMDALA, type BibliographyBlock2, type BlockSelectionRange, type BlockSelectionState, type CiteToken2, DEFAULT_DOCUMENT2_HISTORY_MAX_DEPTH, DEFAULT_HIJRI_DATE, DEFAULT_REFERENCE_FIELD_SEPARATOR, type Document2Block, type Document2BlockJson, type Document2Diagnostic, type Document2Direction, type Document2HijriDate, type Document2HistoryStacks, type Document2Json, type Document2KeyError, type Document2KeyNamespace, type Document2LabelEntry, type Document2LabelKind, type Document2LatexOptions, type Document2MathOutput, type Document2Meta, type Document2MetaProp, type Document2Node, type Document2Preview, type Document2PreviewOptions, type FloatMeta2, type FloatMetaPatch, type FormatCiteLabelOptions, type FormatFloatCaptionTitleOptions, 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 ReferenceFieldSeparator, type TableBlock2, type TextBlock2, type TextToken2, absoluteHttpHref, addDocument2ImageBlock, addDocument2ListBlock, addDocument2ListItem, addDocument2Reference, addDocument2TableBlock, addDocument2TextBlock, applyFloatMetaPatch, arabicXeLatexPreambleCmd, arabicXeLatexPreambleFont, arabicXeLatexPreamblePkg, bibliographyEntryBody, bibliographyEntryLatex, butexBasmalaDisplayLatex, butexBasmalaDisplayTex, butexBasmalaTitlingPreamble, butexDiwaniDisplayLatex, butexDiwaniDisplayTex, butexInColumnMaketitleHook, citeTokenLatex, cloneDocument2Meta, cloneDocument2Node, collectDocument2Labels, createDocument2History, createEmptyArabicEquationSession, createEmptyDocument2, createEmptyEquationSession, createEmptyReference2, createInlineField2, defaultFloatMeta, detectInlineSpans2, detectMathSpans2, document2HasAbstract, document2HasMaketitle, document2HasTitleStack, document2HistoryCanRedo, document2HistoryCanUndo, document2KeyError, document2Latex, document2Preview, emptyBlockSelection, emptyDocument2Meta, ensureDocument2BibliographyBlock, extendBlockSelectionFromAnchor, fillDocument2MetaGaps, findFirstInlineField, formatBibliographyNumber, formatCiteLabel, formatFloatCaptionPreview, formatFloatCaptionTitle, formatHijriDate, formatRefLabel, fromDocumentJson2, getArabicXeLatexPreamble, hijriMonthLabel, inlineFieldLatex, insertCiteTokenAtCaret, insertDocument2BlockAfter, insertMathToken, insertMathTokenAtCaret, insertRefTokenAtCaret, isDuplicateDocument2Key, isValidDocument2Key, labelNumberMap, mathNodeFromArabicSession, mathNodeFromSession, mathSourceFromArabicSession, mathSourceFromSession, mathTokenSourceForSide, mathTokenToArabicEditorSession, mathTokenToEditorSession, mergeDocument2Meta, moveDocument2BlockById, moveDocument2BlockRange, moveDocument2Reference, normalizeBlockSelection, normalizeDocument2HijriDate, normalizeDocument2Key, normalizeDocument2Meta, normalizeReferenceFieldSeparator, 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 };