@drghaliasri/butex 6.0.0 → 6.1.1

package/dist/document2.d.mts

@@ -185,12 +185,27 @@ type Document2Json = {
     references?: Reference2Json[];
     blocks: Document2BlockJson[];
 };
+type Document2InlineTokenIdJson = {
+    id: string;
+    kind: InlineToken2['kind'];
+    start: number;
+    end: number;
+};
+type Document2InlineIdsJson = {
+    field_id: string;
+    tokens: Document2InlineTokenIdJson[];
+};
+type Document2BlockMetadata = {
+    source?: 'agent' | 'user';
+};
 type Document2BlockJson = {
     /** Stable identity used by headless commands. Legacy JSON may omit it. */
     id?: string;
     command: string;
     value?: string;
     formats?: TextFormatSpan2Json[];
+    inline_ids?: Document2InlineIdsJson;
+    metadata?: Document2BlockMetadata;
     /** Stable host asset identity (e.g. S3 key / UUID); optional for \\includegraphics. */
     asset_id?: string;
     math_objects?: Array<Document2MathObjectJson | null>;
@@ -199,6 +214,7 @@ type Document2BlockJson = {
     items?: Document2ListItemJson[];
     rows?: string[][];
     cell_formats?: TextFormatSpan2Json[][][];
+    cell_inline_ids?: Document2InlineIdsJson[][];
     columns?: string;
     caption?: string;
     label?: string;
@@ -207,8 +223,10 @@ type Document2BlockJson = {
     centered?: boolean;
 };
 type Document2ListItemJson = {
+    id?: string;
     value: string;
     formats?: TextFormatSpan2Json[];
+    inline_ids?: Document2InlineIdsJson;
     math_objects?: Array<Document2MathObjectJson | null>;
     blocks?: Document2BlockJson[];
 };
@@ -283,6 +301,7 @@ type TextBlock2 = {
     kind: 'textBlock';
     command: '\\section' | '\\subsection' | '\\subsubsection' | '\\paragraph';
     field: InlineField2;
+    metadata?: Document2BlockMetadata;
     /** When true on \\paragraph, center in preview and LaTeX export. */
     centered?: boolean;
 };
@@ -297,6 +316,7 @@ type ListBlock2 = {
     command: '\\begin{itemize}' | '\\begin{enumerate}';
     closing: '\\end{itemize}' | '\\end{enumerate}';
     items: ListItem2[];
+    metadata?: Document2BlockMetadata;
 };
 type FloatMeta2 = {
     centered: boolean;
@@ -312,6 +332,7 @@ type TableBlock2 = {
     closing: '\\end{tabular}';
     columns: string;
     rows: InlineField2[][];
+    metadata?: Document2BlockMetadata;
 } & FloatMeta2;
 type ImageBlock2 = {
     id: string;
@@ -321,18 +342,21 @@ type ImageBlock2 = {
     /** Host asset identity from wire `asset_id`; preserved across value edits. */
     assetId?: string;
     options: Record<string, string>;
+    metadata?: Document2BlockMetadata;
 } & FloatMeta2;
 type BibliographyBlock2 = {
     id: string;
     kind: 'bibliography';
     command: '\\begin{thebibliography}';
     closing: '\\end{thebibliography}';
+    metadata?: Document2BlockMetadata;
 };
 type RawBlock2 = {
     id: string;
     kind: 'raw';
     command: '\\raw';
     value: string;
+    metadata?: Document2BlockMetadata;
 };
 type Document2Block = TextBlock2 | ListBlock2 | TableBlock2 | ImageBlock2 | BibliographyBlock2 | RawBlock2;
 type Document2Node = {
@@ -420,11 +444,13 @@ type PreviewBlock2 = {
     id: string;
     level: 1 | 2 | 3;
     inlines: PreviewInline2[];
+    metadata?: Document2BlockMetadata;
 } | {
     kind: 'paragraph';
     id: string;
     inlines: PreviewInline2[];
     centered?: boolean;
+    metadata?: Document2BlockMetadata;
 } | {
     kind: 'list';
     id: string;
@@ -434,6 +460,7 @@ type PreviewBlock2 = {
         inlines: PreviewInline2[];
         blocks: PreviewBlock2[];
     }>;
+    metadata?: Document2BlockMetadata;
 } | {
     kind: 'table';
     id: string;
@@ -441,6 +468,7 @@ type PreviewBlock2 = {
     caption?: string;
     label?: string;
     numberLabel?: string;
+    metadata?: Document2BlockMetadata;
 } | {
     kind: 'image';
     id: string;
@@ -450,6 +478,7 @@ type PreviewBlock2 = {
     caption?: string;
     label?: string;
     numberLabel?: string;
+    metadata?: Document2BlockMetadata;
 } | {
     kind: 'bibliography';
     id: string;
@@ -464,11 +493,13 @@ type PreviewBlock2 = {
         venue: string;
         fieldSeparator: ReferenceFieldSeparator;
     }>;
+    metadata?: Document2BlockMetadata;
 }
 /** Preview-only: raw / unknown blocks are omitted from preview until we add proper rendering. */
  | {
     kind: 'omit';
     id: string;
+    metadata?: Document2BlockMetadata;
 };
 type MathIsland2 = {
     id: string;
@@ -649,36 +680,153 @@ declare function updateDocument2Meta(document: Document2Node, patch: Document2Me
 
 type Document2TextBlockKind = 'section' | 'subsection' | 'subsubsection' | 'paragraph';
 type Document2Anchor = {
+    before_block_id: string;
+} | {
     after_block_id: string;
 } | {
     end: true;
 };
-type Document2Command = {
+type Document2InlineAnchor = {
+    before_token_id: string;
+} | {
+    after_token_id: string;
+} | {
+    start: true;
+} | {
+    end: true;
+};
+type Document2ListItemAnchor = {
+    before_item_id: string;
+} | {
+    after_item_id: string;
+} | {
+    end: true;
+};
+type Document2InlineTokenInput = {
+    kind: 'text';
+    text: string;
+    style?: TextStyle2;
+} | {
+    kind: 'math';
+    source: string;
+    math_object: MathObject2Json;
+} | {
+    kind: 'cite';
+    keys: string[];
+} | {
+    kind: 'ref';
+    keys: string[];
+    ref_command: 'ref' | 'eqref';
+};
+type BlockInsertion = {
+    anchor: Document2Anchor;
+    metadata?: Document2BlockMetadata;
+};
+type Document2Command = ({
     op: 'insert_text_block';
     kind: Document2TextBlockKind;
     text: string;
-    anchor: Document2Anchor;
-} | {
+} & BlockInsertion) | {
     op: 'replace_text_block';
     block_id: string;
     text: string;
 } | {
     op: 'remove_block';
     block_id: string;
-} | {
+} | ({
     op: 'insert_figure';
     asset_id: string;
     value?: string;
     caption?: string;
     label?: string;
-    anchor: Document2Anchor;
+} & BlockInsertion) | {
+    op: 'insert_inline_token';
+    field_id: string;
+    token: Document2InlineTokenInput;
+    anchor: Document2InlineAnchor;
+} | {
+    op: 'replace_inline_token';
+    field_id: string;
+    token_id: string;
+    token: Document2InlineTokenInput;
+} | {
+    op: 'remove_inline_token';
+    field_id: string;
+    token_id: string;
+} | ({
+    op: 'insert_list';
+    ordered: boolean;
+    items: string[];
+} & BlockInsertion) | {
+    op: 'insert_list_item';
+    list_id: string;
+    text: string;
+    anchor: Document2ListItemAnchor;
+} | {
+    op: 'replace_list_item';
+    list_id: string;
+    item_id: string;
+    text: string;
+} | {
+    op: 'remove_list_item';
+    list_id: string;
+    item_id: string;
+} | {
+    op: 'move_list_item';
+    list_id: string;
+    item_id: string;
+    anchor: Document2ListItemAnchor;
+} | ({
+    op: 'insert_table';
+    rows: string[][];
+    columns: string;
+    caption?: string;
+    label?: string;
+} & BlockInsertion) | {
+    op: 'replace_table_cell';
+    table_id: string;
+    row_index: number;
+    column_index: number;
+    text: string;
+} | {
+    op: 'insert_table_row';
+    table_id: string;
+    index: number;
+    values: string[];
+} | {
+    op: 'remove_table_row';
+    table_id: string;
+    index: number;
+} | {
+    op: 'move_table_row';
+    table_id: string;
+    from_index: number;
+    to_index: number;
+} | {
+    op: 'insert_table_column';
+    table_id: string;
+    index: number;
+    values: string[];
+    columns: string;
+} | {
+    op: 'remove_table_column';
+    table_id: string;
+    index: number;
+    columns: string;
+} | {
+    op: 'move_table_column';
+    table_id: string;
+    from_index: number;
+    to_index: number;
+    columns: string;
 };
-type Document2CommandErrorCode = 'invalid_document' | 'invalid_command' | 'missing_block_id' | 'duplicate_block_id' | 'anchor_not_found' | 'block_not_found' | 'block_kind_mismatch' | 'unsupported_inline_content';
+type Document2CommandErrorCode = 'invalid_document' | 'invalid_command' | 'missing_block_id' | 'duplicate_block_id' | 'invalid_anchor' | 'anchor_not_found' | 'block_not_found' | 'block_kind_mismatch' | 'field_not_found' | 'token_not_found' | 'list_not_found' | 'item_not_found' | 'table_not_found' | 'invalid_table_shape' | 'index_out_of_range' | 'minimum_structure' | 'invalid_inline_token' | 'math_object_mismatch' | 'unsupported_inline_content';
 declare class Document2CommandError extends Error {
     readonly code: Document2CommandErrorCode;
     constructor(code: Document2CommandErrorCode, message: string);
 }
-/** Apply one validated, top-level command and return canonical JSON. */
+
+/** Apply one validated command to canonical JSON without mutating caller input. */
 declare function applyDocument2Command(json: Document2Json, commandInput: Document2Command): Document2Json;
 
 type Document2OutlineKind = 'section' | 'subsection' | 'subsubsection' | 'paragraph' | 'list' | 'table' | 'figure' | 'bibliography' | 'raw';
@@ -824,4 +972,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, DEFAULT_REFERENCE_FIELD_SEPARATOR, type Document2Anchor, type Document2Block, type Document2BlockJson, type Document2Command, Document2CommandError, type Document2CommandErrorCode, type Document2Diagnostic, type Document2Direction, type Document2HijriDate, type Document2HistoryStacks, type Document2ImageAssetRef, type Document2Json, type Document2KeyError, type Document2KeyNamespace, type Document2LabelEntry, type Document2LabelKind, type Document2LatexOptions, type Document2MathObjectJson, type Document2MathOutput, type Document2Meta, type Document2MetaProp, type Document2Node, type Document2OutlineEntry, type Document2OutlineKind, type Document2Preview, type Document2PreviewOptions, type Document2TextBlockKind, 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 RawMathObject2Json, type RefToken2, type Reference2, type Reference2Json, type ReferenceFieldSeparator, type TableBlock2, type TextBlock2, type TextFormatSpan2Json, type TextStyle2, type TextToken2, absoluteHttpHref, addDocument2ImageBlock, addDocument2ListBlock, addDocument2ListItem, addDocument2Reference, addDocument2TableBlock, addDocument2TextBlock, applyDocument2Command, applyFloatMetaPatch, arabicXeLatexPreambleCmd, arabicXeLatexPreambleFont, arabicXeLatexPreamblePkg, bibliographyEntryBody, bibliographyEntryLatex, butexBasmalaDisplayLatex, butexBasmalaDisplayTex, butexBasmalaTitlingPreamble, butexDiwaniDisplayLatex, butexDiwaniDisplayTex, butexInColumnMaketitleHook, butexMaghribiDisplayLatex, butexMaghribiDisplayTex, citeTokenLatex, clearDocument2ImageAsset, cloneDocument2Meta, cloneDocument2Node, collectDocument2Labels, createDocument2History, createEmptyArabicEquationSession, createEmptyDocument2, createEmptyEquationSession, createEmptyReference2, createInlineField2, defaultFloatMeta, detectInlineSpans2, detectMathSpans2, document2HasAbstract, document2HasMaketitle, document2HasTitleStack, document2HistoryCanRedo, document2HistoryCanUndo, document2KeyError, document2Latex, document2Outline, 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, toDocumentJson2, toggleBlockInSelection, toggleTextTokenStyle, updateCiteTokenKeys, updateDocument2ImageAsset, 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 Document2Anchor, type Document2Block, type Document2BlockJson, type Document2BlockMetadata, type Document2Command, Document2CommandError, type Document2CommandErrorCode, type Document2Diagnostic, type Document2Direction, type Document2HijriDate, type Document2HistoryStacks, type Document2ImageAssetRef, type Document2InlineAnchor, type Document2InlineIdsJson, type Document2InlineTokenIdJson, type Document2InlineTokenInput, type Document2Json, type Document2KeyError, type Document2KeyNamespace, type Document2LabelEntry, type Document2LabelKind, type Document2LatexOptions, type Document2ListItemAnchor, type Document2MathObjectJson, type Document2MathOutput, type Document2Meta, type Document2MetaProp, type Document2Node, type Document2OutlineEntry, type Document2OutlineKind, type Document2Preview, type Document2PreviewOptions, type Document2TextBlockKind, 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 ListItem2, type MathIsland2, type MathObject2Json, type MathToken2, type PreviewBlock2, type PreviewInline2, type RawBlock2, type RawMathObject2Json, type RefToken2, type Reference2, type Reference2Json, type ReferenceFieldSeparator, type TableBlock2, type TextBlock2, type TextFormatSpan2Json, type TextStyle2, type TextToken2, absoluteHttpHref, addDocument2ImageBlock, addDocument2ListBlock, addDocument2ListItem, addDocument2Reference, addDocument2TableBlock, addDocument2TextBlock, applyDocument2Command, applyFloatMetaPatch, arabicXeLatexPreambleCmd, arabicXeLatexPreambleFont, arabicXeLatexPreamblePkg, bibliographyEntryBody, bibliographyEntryLatex, butexBasmalaDisplayLatex, butexBasmalaDisplayTex, butexBasmalaTitlingPreamble, butexDiwaniDisplayLatex, butexDiwaniDisplayTex, butexInColumnMaketitleHook, butexMaghribiDisplayLatex, butexMaghribiDisplayTex, citeTokenLatex, clearDocument2ImageAsset, cloneDocument2Meta, cloneDocument2Node, collectDocument2Labels, createDocument2History, createEmptyArabicEquationSession, createEmptyDocument2, createEmptyEquationSession, createEmptyReference2, createInlineField2, defaultFloatMeta, detectInlineSpans2, detectMathSpans2, document2HasAbstract, document2HasMaketitle, document2HasTitleStack, document2HistoryCanRedo, document2HistoryCanUndo, document2KeyError, document2Latex, document2Outline, 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, toDocumentJson2, toggleBlockInSelection, toggleTextTokenStyle, updateCiteTokenKeys, updateDocument2ImageAsset, updateDocument2ImageMeta, updateDocument2ImageValue, updateDocument2Meta, updateDocument2Reference, updateDocument2TableMeta, updateDocument2TextBlockCentered, updateMathTokenLabel, updateRefTokenKeys, updateTextToken };

package/dist/document2.d.ts

@@ -185,12 +185,27 @@ type Document2Json = {
     references?: Reference2Json[];
     blocks: Document2BlockJson[];
 };
+type Document2InlineTokenIdJson = {
+    id: string;
+    kind: InlineToken2['kind'];
+    start: number;
+    end: number;
+};
+type Document2InlineIdsJson = {
+    field_id: string;
+    tokens: Document2InlineTokenIdJson[];
+};
+type Document2BlockMetadata = {
+    source?: 'agent' | 'user';
+};
 type Document2BlockJson = {
     /** Stable identity used by headless commands. Legacy JSON may omit it. */
     id?: string;
     command: string;
     value?: string;
     formats?: TextFormatSpan2Json[];
+    inline_ids?: Document2InlineIdsJson;
+    metadata?: Document2BlockMetadata;
     /** Stable host asset identity (e.g. S3 key / UUID); optional for \\includegraphics. */
     asset_id?: string;
     math_objects?: Array<Document2MathObjectJson | null>;
@@ -199,6 +214,7 @@ type Document2BlockJson = {
     items?: Document2ListItemJson[];
     rows?: string[][];
     cell_formats?: TextFormatSpan2Json[][][];
+    cell_inline_ids?: Document2InlineIdsJson[][];
     columns?: string;
     caption?: string;
     label?: string;
@@ -207,8 +223,10 @@ type Document2BlockJson = {
     centered?: boolean;
 };
 type Document2ListItemJson = {
+    id?: string;
     value: string;
     formats?: TextFormatSpan2Json[];
+    inline_ids?: Document2InlineIdsJson;
     math_objects?: Array<Document2MathObjectJson | null>;
     blocks?: Document2BlockJson[];
 };
@@ -283,6 +301,7 @@ type TextBlock2 = {
     kind: 'textBlock';
     command: '\\section' | '\\subsection' | '\\subsubsection' | '\\paragraph';
     field: InlineField2;
+    metadata?: Document2BlockMetadata;
     /** When true on \\paragraph, center in preview and LaTeX export. */
     centered?: boolean;
 };
@@ -297,6 +316,7 @@ type ListBlock2 = {
     command: '\\begin{itemize}' | '\\begin{enumerate}';
     closing: '\\end{itemize}' | '\\end{enumerate}';
     items: ListItem2[];
+    metadata?: Document2BlockMetadata;
 };
 type FloatMeta2 = {
     centered: boolean;
@@ -312,6 +332,7 @@ type TableBlock2 = {
     closing: '\\end{tabular}';
     columns: string;
     rows: InlineField2[][];
+    metadata?: Document2BlockMetadata;
 } & FloatMeta2;
 type ImageBlock2 = {
     id: string;
@@ -321,18 +342,21 @@ type ImageBlock2 = {
     /** Host asset identity from wire `asset_id`; preserved across value edits. */
     assetId?: string;
     options: Record<string, string>;
+    metadata?: Document2BlockMetadata;
 } & FloatMeta2;
 type BibliographyBlock2 = {
     id: string;
     kind: 'bibliography';
     command: '\\begin{thebibliography}';
     closing: '\\end{thebibliography}';
+    metadata?: Document2BlockMetadata;
 };
 type RawBlock2 = {
     id: string;
     kind: 'raw';
     command: '\\raw';
     value: string;
+    metadata?: Document2BlockMetadata;
 };
 type Document2Block = TextBlock2 | ListBlock2 | TableBlock2 | ImageBlock2 | BibliographyBlock2 | RawBlock2;
 type Document2Node = {
@@ -420,11 +444,13 @@ type PreviewBlock2 = {
     id: string;
     level: 1 | 2 | 3;
     inlines: PreviewInline2[];
+    metadata?: Document2BlockMetadata;
 } | {
     kind: 'paragraph';
     id: string;
     inlines: PreviewInline2[];
     centered?: boolean;
+    metadata?: Document2BlockMetadata;
 } | {
     kind: 'list';
     id: string;
@@ -434,6 +460,7 @@ type PreviewBlock2 = {
         inlines: PreviewInline2[];
         blocks: PreviewBlock2[];
     }>;
+    metadata?: Document2BlockMetadata;
 } | {
     kind: 'table';
     id: string;
@@ -441,6 +468,7 @@ type PreviewBlock2 = {
     caption?: string;
     label?: string;
     numberLabel?: string;
+    metadata?: Document2BlockMetadata;
 } | {
     kind: 'image';
     id: string;
@@ -450,6 +478,7 @@ type PreviewBlock2 = {
     caption?: string;
     label?: string;
     numberLabel?: string;
+    metadata?: Document2BlockMetadata;
 } | {
     kind: 'bibliography';
     id: string;
@@ -464,11 +493,13 @@ type PreviewBlock2 = {
         venue: string;
         fieldSeparator: ReferenceFieldSeparator;
     }>;
+    metadata?: Document2BlockMetadata;
 }
 /** Preview-only: raw / unknown blocks are omitted from preview until we add proper rendering. */
  | {
     kind: 'omit';
     id: string;
+    metadata?: Document2BlockMetadata;
 };
 type MathIsland2 = {
     id: string;
@@ -649,36 +680,153 @@ declare function updateDocument2Meta(document: Document2Node, patch: Document2Me
 
 type Document2TextBlockKind = 'section' | 'subsection' | 'subsubsection' | 'paragraph';
 type Document2Anchor = {
+    before_block_id: string;
+} | {
     after_block_id: string;
 } | {
     end: true;
 };
-type Document2Command = {
+type Document2InlineAnchor = {
+    before_token_id: string;
+} | {
+    after_token_id: string;
+} | {
+    start: true;
+} | {
+    end: true;
+};
+type Document2ListItemAnchor = {
+    before_item_id: string;
+} | {
+    after_item_id: string;
+} | {
+    end: true;
+};
+type Document2InlineTokenInput = {
+    kind: 'text';
+    text: string;
+    style?: TextStyle2;
+} | {
+    kind: 'math';
+    source: string;
+    math_object: MathObject2Json;
+} | {
+    kind: 'cite';
+    keys: string[];
+} | {
+    kind: 'ref';
+    keys: string[];
+    ref_command: 'ref' | 'eqref';
+};
+type BlockInsertion = {
+    anchor: Document2Anchor;
+    metadata?: Document2BlockMetadata;
+};
+type Document2Command = ({
     op: 'insert_text_block';
     kind: Document2TextBlockKind;
     text: string;
-    anchor: Document2Anchor;
-} | {
+} & BlockInsertion) | {
     op: 'replace_text_block';
     block_id: string;
     text: string;
 } | {
     op: 'remove_block';
     block_id: string;
-} | {
+} | ({
     op: 'insert_figure';
     asset_id: string;
     value?: string;
     caption?: string;
     label?: string;
-    anchor: Document2Anchor;
+} & BlockInsertion) | {
+    op: 'insert_inline_token';
+    field_id: string;
+    token: Document2InlineTokenInput;
+    anchor: Document2InlineAnchor;
+} | {
+    op: 'replace_inline_token';
+    field_id: string;
+    token_id: string;
+    token: Document2InlineTokenInput;
+} | {
+    op: 'remove_inline_token';
+    field_id: string;
+    token_id: string;
+} | ({
+    op: 'insert_list';
+    ordered: boolean;
+    items: string[];
+} & BlockInsertion) | {
+    op: 'insert_list_item';
+    list_id: string;
+    text: string;
+    anchor: Document2ListItemAnchor;
+} | {
+    op: 'replace_list_item';
+    list_id: string;
+    item_id: string;
+    text: string;
+} | {
+    op: 'remove_list_item';
+    list_id: string;
+    item_id: string;
+} | {
+    op: 'move_list_item';
+    list_id: string;
+    item_id: string;
+    anchor: Document2ListItemAnchor;
+} | ({
+    op: 'insert_table';
+    rows: string[][];
+    columns: string;
+    caption?: string;
+    label?: string;
+} & BlockInsertion) | {
+    op: 'replace_table_cell';
+    table_id: string;
+    row_index: number;
+    column_index: number;
+    text: string;
+} | {
+    op: 'insert_table_row';
+    table_id: string;
+    index: number;
+    values: string[];
+} | {
+    op: 'remove_table_row';
+    table_id: string;
+    index: number;
+} | {
+    op: 'move_table_row';
+    table_id: string;
+    from_index: number;
+    to_index: number;
+} | {
+    op: 'insert_table_column';
+    table_id: string;
+    index: number;
+    values: string[];
+    columns: string;
+} | {
+    op: 'remove_table_column';
+    table_id: string;
+    index: number;
+    columns: string;
+} | {
+    op: 'move_table_column';
+    table_id: string;
+    from_index: number;
+    to_index: number;
+    columns: string;
 };
-type Document2CommandErrorCode = 'invalid_document' | 'invalid_command' | 'missing_block_id' | 'duplicate_block_id' | 'anchor_not_found' | 'block_not_found' | 'block_kind_mismatch' | 'unsupported_inline_content';
+type Document2CommandErrorCode = 'invalid_document' | 'invalid_command' | 'missing_block_id' | 'duplicate_block_id' | 'invalid_anchor' | 'anchor_not_found' | 'block_not_found' | 'block_kind_mismatch' | 'field_not_found' | 'token_not_found' | 'list_not_found' | 'item_not_found' | 'table_not_found' | 'invalid_table_shape' | 'index_out_of_range' | 'minimum_structure' | 'invalid_inline_token' | 'math_object_mismatch' | 'unsupported_inline_content';
 declare class Document2CommandError extends Error {
     readonly code: Document2CommandErrorCode;
     constructor(code: Document2CommandErrorCode, message: string);
 }
-/** Apply one validated, top-level command and return canonical JSON. */
+
+/** Apply one validated command to canonical JSON without mutating caller input. */
 declare function applyDocument2Command(json: Document2Json, commandInput: Document2Command): Document2Json;
 
 type Document2OutlineKind = 'section' | 'subsection' | 'subsubsection' | 'paragraph' | 'list' | 'table' | 'figure' | 'bibliography' | 'raw';
@@ -824,4 +972,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, DEFAULT_REFERENCE_FIELD_SEPARATOR, type Document2Anchor, type Document2Block, type Document2BlockJson, type Document2Command, Document2CommandError, type Document2CommandErrorCode, type Document2Diagnostic, type Document2Direction, type Document2HijriDate, type Document2HistoryStacks, type Document2ImageAssetRef, type Document2Json, type Document2KeyError, type Document2KeyNamespace, type Document2LabelEntry, type Document2LabelKind, type Document2LatexOptions, type Document2MathObjectJson, type Document2MathOutput, type Document2Meta, type Document2MetaProp, type Document2Node, type Document2OutlineEntry, type Document2OutlineKind, type Document2Preview, type Document2PreviewOptions, type Document2TextBlockKind, 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 RawMathObject2Json, type RefToken2, type Reference2, type Reference2Json, type ReferenceFieldSeparator, type TableBlock2, type TextBlock2, type TextFormatSpan2Json, type TextStyle2, type TextToken2, absoluteHttpHref, addDocument2ImageBlock, addDocument2ListBlock, addDocument2ListItem, addDocument2Reference, addDocument2TableBlock, addDocument2TextBlock, applyDocument2Command, applyFloatMetaPatch, arabicXeLatexPreambleCmd, arabicXeLatexPreambleFont, arabicXeLatexPreamblePkg, bibliographyEntryBody, bibliographyEntryLatex, butexBasmalaDisplayLatex, butexBasmalaDisplayTex, butexBasmalaTitlingPreamble, butexDiwaniDisplayLatex, butexDiwaniDisplayTex, butexInColumnMaketitleHook, butexMaghribiDisplayLatex, butexMaghribiDisplayTex, citeTokenLatex, clearDocument2ImageAsset, cloneDocument2Meta, cloneDocument2Node, collectDocument2Labels, createDocument2History, createEmptyArabicEquationSession, createEmptyDocument2, createEmptyEquationSession, createEmptyReference2, createInlineField2, defaultFloatMeta, detectInlineSpans2, detectMathSpans2, document2HasAbstract, document2HasMaketitle, document2HasTitleStack, document2HistoryCanRedo, document2HistoryCanUndo, document2KeyError, document2Latex, document2Outline, 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, toDocumentJson2, toggleBlockInSelection, toggleTextTokenStyle, updateCiteTokenKeys, updateDocument2ImageAsset, 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 Document2Anchor, type Document2Block, type Document2BlockJson, type Document2BlockMetadata, type Document2Command, Document2CommandError, type Document2CommandErrorCode, type Document2Diagnostic, type Document2Direction, type Document2HijriDate, type Document2HistoryStacks, type Document2ImageAssetRef, type Document2InlineAnchor, type Document2InlineIdsJson, type Document2InlineTokenIdJson, type Document2InlineTokenInput, type Document2Json, type Document2KeyError, type Document2KeyNamespace, type Document2LabelEntry, type Document2LabelKind, type Document2LatexOptions, type Document2ListItemAnchor, type Document2MathObjectJson, type Document2MathOutput, type Document2Meta, type Document2MetaProp, type Document2Node, type Document2OutlineEntry, type Document2OutlineKind, type Document2Preview, type Document2PreviewOptions, type Document2TextBlockKind, 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 ListItem2, type MathIsland2, type MathObject2Json, type MathToken2, type PreviewBlock2, type PreviewInline2, type RawBlock2, type RawMathObject2Json, type RefToken2, type Reference2, type Reference2Json, type ReferenceFieldSeparator, type TableBlock2, type TextBlock2, type TextFormatSpan2Json, type TextStyle2, type TextToken2, absoluteHttpHref, addDocument2ImageBlock, addDocument2ListBlock, addDocument2ListItem, addDocument2Reference, addDocument2TableBlock, addDocument2TextBlock, applyDocument2Command, applyFloatMetaPatch, arabicXeLatexPreambleCmd, arabicXeLatexPreambleFont, arabicXeLatexPreamblePkg, bibliographyEntryBody, bibliographyEntryLatex, butexBasmalaDisplayLatex, butexBasmalaDisplayTex, butexBasmalaTitlingPreamble, butexDiwaniDisplayLatex, butexDiwaniDisplayTex, butexInColumnMaketitleHook, butexMaghribiDisplayLatex, butexMaghribiDisplayTex, citeTokenLatex, clearDocument2ImageAsset, cloneDocument2Meta, cloneDocument2Node, collectDocument2Labels, createDocument2History, createEmptyArabicEquationSession, createEmptyDocument2, createEmptyEquationSession, createEmptyReference2, createInlineField2, defaultFloatMeta, detectInlineSpans2, detectMathSpans2, document2HasAbstract, document2HasMaketitle, document2HasTitleStack, document2HistoryCanRedo, document2HistoryCanUndo, document2KeyError, document2Latex, document2Outline, 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, toDocumentJson2, toggleBlockInSelection, toggleTextTokenStyle, updateCiteTokenKeys, updateDocument2ImageAsset, updateDocument2ImageMeta, updateDocument2ImageValue, updateDocument2Meta, updateDocument2Reference, updateDocument2TableMeta, updateDocument2TextBlockCentered, updateMathTokenLabel, updateRefTokenKeys, updateTextToken };