@drghaliasri/butex 5.6.0 → 6.0.0

package/dist/document2.mjs

@@ -1,7 +1,8 @@
 // src/document2/ids.ts
 var nextId = 1;
+var instanceId = `${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
 function document2Id(prefix) {
-  const id = `${prefix}_${String(nextId)}`;
+  const id = `${prefix}_${instanceId}_${String(nextId)}`;
   nextId += 1;
   return id;
 }
@@ -1177,6 +1178,19 @@ function asBlockJson(value) {
   }
   return value;
 }
+function blockIdFromJson(json, state) {
+  const imported = typeof json.id === "string" ? json.id.trim() : "";
+  if (imported.length > 0 && !state.used.has(imported)) {
+    state.used.add(imported);
+    return imported;
+  }
+  let generated = document2Id("block");
+  while (state.used.has(generated)) {
+    generated = document2Id("block");
+  }
+  state.used.add(generated);
+  return generated;
+}
 function pushDiagnostic(diagnostics, options, path, message) {
   if (options.strict) {
     throw new Error(message);
@@ -1358,40 +1372,44 @@ function pushFormattedTextTokens(tokens, text, sourceStart, formats) {
 function closingForList(command) {
   return command === "\\begin{itemize}" ? "\\end{itemize}" : "\\end{enumerate}";
 }
-function parseTextBlock(json, options, path, diagnostics) {
+function parseTextBlock(json, options, path, diagnostics, blockIds) {
   const value = requireString(json.value, `${json.command} requires string value`);
   return {
-    id: document2Id("block"),
+    id: blockIdFromJson(json, blockIds),
     kind: "textBlock",
     command: json.command,
     field: createInlineField2(value, json.math_objects ?? [], options, `${path}.value`, diagnostics, json.command === "\\paragraph" ? json.formats ?? [] : []),
     ...json.centered === true ? { centered: true } : {}
   };
 }
-function parseListItem(json, options, path, diagnostics) {
+function parseListItem(json, options, path, diagnostics, blockIds) {
   const value = requireString(json.value, "Document list item requires string value");
   const blocksJson = Array.isArray(json.blocks) ? json.blocks : [];
   return {
     id: document2Id("item"),
     field: createInlineField2(value, json.math_objects ?? [], options, `${path}.value`, diagnostics, json.formats ?? []),
-    blocks: blocksJson.map((block, index) => parseBlock(asBlockJson(block), options, `${path}.blocks[${String(index)}]`, diagnostics))
+    blocks: blocksJson.map(
+      (block, index) => parseBlock(asBlockJson(block), options, `${path}.blocks[${String(index)}]`, diagnostics, blockIds)
+    )
   };
 }
-function parseListBlock(json, options, path, diagnostics) {
+function parseListBlock(json, options, path, diagnostics, blockIds) {
   if (!Array.isArray(json.items)) {
     throw new Error(`${json.command} requires items array`);
   }
   const command = json.command;
   const closing = closingForList(command);
   return {
-    id: document2Id("block"),
+    id: blockIdFromJson(json, blockIds),
     kind: "list",
     command,
     closing,
-    items: json.items.map((item, index) => parseListItem(item, options, `${path}.items[${String(index)}]`, diagnostics))
+    items: json.items.map(
+      (item, index) => parseListItem(item, options, `${path}.items[${String(index)}]`, diagnostics, blockIds)
+    )
   };
 }
-function parseTableBlock(json, options, path, diagnostics) {
+function parseTableBlock(json, options, path, diagnostics, blockIds) {
   if (!Array.isArray(json.rows)) {
     throw new Error("\\begin{tabular} requires rows array");
   }
@@ -1414,7 +1432,7 @@ function parseTableBlock(json, options, path, diagnostics) {
     pushDiagnostic(diagnostics, options, path, `math_objects count mismatch: detected ${String(mathObjectIndex)}, got ${String(mathObjects.length)}`);
   }
   return {
-    id: document2Id("block"),
+    id: blockIdFromJson(json, blockIds),
     kind: "table",
     command: "\\begin{tabular}",
     closing: "\\end{tabular}",
@@ -1423,11 +1441,11 @@ function parseTableBlock(json, options, path, diagnostics) {
     ...parseFloatMetaFromJson(json)
   };
 }
-function parseImageBlock(json) {
+function parseImageBlock(json, blockIds) {
   const assetId = typeof json.asset_id === "string" && json.asset_id.length > 0 ? json.asset_id : void 0;
   const value = assetId !== void 0 ? typeof json.value === "string" ? json.value : "" : requireString(json.value, "\\includegraphics requires string value");
   return {
-    id: document2Id("block"),
+    id: blockIdFromJson(json, blockIds),
     kind: "image",
     command: "\\includegraphics",
     value,
@@ -1436,43 +1454,43 @@ function parseImageBlock(json) {
     ...parseFloatMetaFromJson(json)
   };
 }
-function parseRawBlock(json) {
+function parseRawBlock(json, blockIds) {
   return {
-    id: document2Id("block"),
+    id: blockIdFromJson(json, blockIds),
     kind: "raw",
     command: "\\raw",
     value: typeof json.value === "string" ? json.value : ""
   };
 }
-function parseBibliographyBlock() {
+function parseBibliographyBlock(json, blockIds) {
   return {
-    id: document2Id("block"),
+    id: blockIdFromJson(json, blockIds),
     kind: "bibliography",
     command: "\\begin{thebibliography}",
     closing: "\\end{thebibliography}"
   };
 }
-function parseBlock(json, options, path, diagnostics) {
+function parseBlock(json, options, path, diagnostics, blockIds) {
   if (TEXT_COMMANDS.has(json.command)) {
-    return parseTextBlock(json, options, path, diagnostics);
+    return parseTextBlock(json, options, path, diagnostics, blockIds);
   }
   if (LIST_COMMANDS.has(json.command)) {
-    return parseListBlock(json, options, path, diagnostics);
+    return parseListBlock(json, options, path, diagnostics, blockIds);
   }
   if (json.command === "\\begin{tabular}") {
-    return parseTableBlock(json, options, path, diagnostics);
+    return parseTableBlock(json, options, path, diagnostics, blockIds);
   }
   if (json.command === "\\includegraphics") {
-    return parseImageBlock(json);
+    return parseImageBlock(json, blockIds);
   }
   if (json.command === "\\begin{thebibliography}" || json.command === "\\bibliography") {
-    return parseBibliographyBlock();
+    return parseBibliographyBlock(json, blockIds);
   }
   if (json.command === "\\raw") {
-    return parseRawBlock(json);
+    return parseRawBlock(json, blockIds);
   }
   return {
-    id: document2Id("block"),
+    id: blockIdFromJson(json, blockIds),
     kind: "raw",
     command: "\\raw",
     value: typeof json.value === "string" ? json.value : json.command
@@ -1486,11 +1504,14 @@ function fromDocumentJson2(json, options = {}) {
     throw new Error("DocumentObject requires blocks array");
   }
   const diagnostics = [];
+  const blockIds = { used: /* @__PURE__ */ new Set() };
   return {
     nodeType: "DocumentObject",
     meta: normalizeDocument2Meta(json.meta),
     references: parseReferences(json.references),
-    blocks: json.blocks.map((block, index) => parseBlock(asBlockJson(block), options, `$.blocks[${String(index)}]`, diagnostics)),
+    blocks: json.blocks.map(
+      (block, index) => parseBlock(asBlockJson(block), options, `$.blocks[${String(index)}]`, diagnostics, blockIds)
+    ),
     diagnostics
   };
 }
@@ -4574,21 +4595,21 @@ function splitTextForInsertion(token) {
 function cloneDocument2Node(document2) {
   return cloneDocument(document2);
 }
-function insertBlockAfter(blocks, afterBlockId, block) {
-  if (!afterBlockId) {
+function insertBlockAfter(blocks, afterBlockId2, block) {
+  if (!afterBlockId2) {
     blocks.push(block);
     return;
   }
-  const index = blocks.findIndex((entry) => entry.id === afterBlockId);
+  const index = blocks.findIndex((entry) => entry.id === afterBlockId2);
   if (index < 0) {
     blocks.push(block);
     return;
   }
   blocks.splice(index + 1, 0, block);
 }
-function insertDocument2BlockAfter(document2, afterBlockId, block) {
+function insertDocument2BlockAfter(document2, afterBlockId2, block) {
   const next = cloneDocument(document2);
-  insertBlockAfter(next.blocks, afterBlockId, block);
+  insertBlockAfter(next.blocks, afterBlockId2, block);
   return next;
 }
 function moveDocument2BlockById(document2, blockId, direction) {
@@ -4808,7 +4829,7 @@ function replaceMathTokenFromSession(document2, tokenId, session, opening, closi
   });
   return next;
 }
-function addDocument2TextBlock(document2, command = "\\paragraph", afterBlockId) {
+function addDocument2TextBlock(document2, command = "\\paragraph", afterBlockId2) {
   const block = {
     id: document2Id("block"),
     kind: "textBlock",
@@ -4816,7 +4837,7 @@ function addDocument2TextBlock(document2, command = "\\paragraph", afterBlockId)
     field: createInlineField2(""),
     ...command === "\\paragraph" ? { centered: false } : {}
   };
-  return insertDocument2BlockAfter(document2, afterBlockId, block);
+  return insertDocument2BlockAfter(document2, afterBlockId2, block);
 }
 function updateDocument2TextBlockCentered(document2, blockId, centered) {
   const next = cloneDocument(document2);
@@ -4855,10 +4876,10 @@ function newListBlock(ordered) {
     items: [{ id: document2Id("item"), field: createInlineField2(""), blocks: [] }]
   };
 }
-function addDocument2ListBlock(document2, ordered, afterBlockId) {
-  return insertDocument2BlockAfter(document2, afterBlockId, newListBlock(ordered));
+function addDocument2ListBlock(document2, ordered, afterBlockId2) {
+  return insertDocument2BlockAfter(document2, afterBlockId2, newListBlock(ordered));
 }
-function addDocument2TableBlock(document2, columns = "lll", rowCount = 3, colCount = 3, afterBlockId) {
+function addDocument2TableBlock(document2, columns = "lll", rowCount = 3, colCount = 3, afterBlockId2) {
   const rows = Math.max(1, rowCount);
   const cols = Math.max(1, colCount);
   const tableRows = [];
@@ -4878,18 +4899,29 @@ function addDocument2TableBlock(document2, columns = "lll", rowCount = 3, colCou
     rows: tableRows,
     ...defaultFloatMeta()
   };
-  return insertDocument2BlockAfter(document2, afterBlockId, block);
+  return insertDocument2BlockAfter(document2, afterBlockId2, block);
+}
+function normalizeImageInput(srcOrAsset) {
+  if (typeof srcOrAsset === "string") {
+    return srcOrAsset.length > 0 ? { value: srcOrAsset, assetId: srcOrAsset } : { value: "" };
+  }
+  if (srcOrAsset && srcOrAsset.assetId.length > 0) {
+    return { value: srcOrAsset.value ?? srcOrAsset.assetId, assetId: srcOrAsset.assetId };
+  }
+  return { value: "" };
 }
-function addDocument2ImageBlock(document2, src = "", afterBlockId) {
+function addDocument2ImageBlock(document2, srcOrAsset, afterBlockId2) {
+  const image = normalizeImageInput(srcOrAsset);
   const block = {
     id: document2Id("block"),
     kind: "image",
     command: "\\includegraphics",
-    value: src,
+    value: image.value,
+    ...image.assetId !== void 0 ? { assetId: image.assetId } : {},
     options: { width: "0.8\\columnwidth" },
     ...defaultFloatMeta()
   };
-  return insertDocument2BlockAfter(document2, afterBlockId, block);
+  return insertDocument2BlockAfter(document2, afterBlockId2, block);
 }
 function updateDocument2ImageValue(document2, blockId, value) {
   const next = cloneDocument(document2);
@@ -4912,6 +4944,55 @@ function updateDocument2ImageValue(document2, blockId, value) {
   visit(next.blocks);
   return next;
 }
+function updateDocument2ImageAsset(document2, blockId, asset) {
+  const next = cloneDocument(document2);
+  const image = normalizeImageInput(asset);
+  function visit(blocks) {
+    for (const block of blocks) {
+      if (block.id === blockId && block.kind === "image") {
+        block.value = image.value;
+        if (image.assetId !== void 0) {
+          block.assetId = image.assetId;
+        } else {
+          delete block.assetId;
+        }
+        return true;
+      }
+      if (block.kind === "list") {
+        for (const item of block.items) {
+          if (visit(item.blocks)) {
+            return true;
+          }
+        }
+      }
+    }
+    return false;
+  }
+  visit(next.blocks);
+  return next;
+}
+function clearDocument2ImageAsset(document2, blockId) {
+  const next = cloneDocument(document2);
+  function visit(blocks) {
+    for (const block of blocks) {
+      if (block.id === blockId && block.kind === "image") {
+        block.value = "";
+        delete block.assetId;
+        return true;
+      }
+      if (block.kind === "list") {
+        for (const item of block.items) {
+          if (visit(item.blocks)) {
+            return true;
+          }
+        }
+      }
+    }
+    return false;
+  }
+  visit(next.blocks);
+  return next;
+}
 function updateDocument2ImageMeta(document2, blockId, patch) {
   const next = cloneDocument(document2);
   function visit(blocks) {
@@ -5130,7 +5211,7 @@ function removeCiteTokenById(document2, tokenId) {
   });
   return next;
 }
-function ensureDocument2BibliographyBlock(document2, afterBlockId) {
+function ensureDocument2BibliographyBlock(document2, afterBlockId2) {
   if (document2.blocks.some((block2) => block2.kind === "bibliography")) {
     return document2;
   }
@@ -5140,7 +5221,7 @@ function ensureDocument2BibliographyBlock(document2, afterBlockId) {
     command: "\\begin{thebibliography}",
     closing: "\\end{thebibliography}"
   };
-  return insertDocument2BlockAfter(document2, afterBlockId ?? null, block);
+  return insertDocument2BlockAfter(document2, afterBlockId2 ?? null, block);
 }
 function addDocument2Reference(document2, partial = {}) {
   const next = cloneDocument(document2);
@@ -5212,6 +5293,440 @@ function updateDocument2Meta(document2, patch) {
   return next;
 }
 
+// src/document2/exportJson.ts
+function serializeField(field) {
+  let value = "";
+  let hasPersistedMath = false;
+  const formats = [];
+  const mathObjects = [];
+  for (const token of field.tokens) {
+    if (token.kind === "text") {
+      const start = value.length;
+      value += token.text;
+      if (token.text.length > 0 && (token.style?.bold || token.style?.italic || token.style?.underline)) {
+        formats.push({
+          start,
+          end: value.length,
+          ...token.style.bold ? { bold: true } : {},
+          ...token.style.italic ? { italic: true } : {},
+          ...token.style.underline ? { underline: true } : {}
+        });
+      }
+      continue;
+    }
+    if (token.kind === "cite") {
+      value += citeTokenLatex(token.keys);
+      continue;
+    }
+    if (token.kind === "ref") {
+      value += refTokenLatex(token.keys, token.refCommand);
+      continue;
+    }
+    value += token.source;
+    if (!token.math || token.sourceOwner === "raw") {
+      if (token.labelEnabled !== void 0 || token.label !== void 0) {
+        hasPersistedMath = true;
+        mathObjects.push({
+          node_type: "RawMathObject",
+          ...token.labelEnabled !== void 0 ? { label_enabled: token.labelEnabled } : {},
+          ...token.label !== void 0 ? { label: token.label } : {}
+        });
+      } else {
+        mathObjects.push(null);
+      }
+      continue;
+    }
+    hasPersistedMath = true;
+    mathObjects.push({
+      ...toMathObjectJson(token.math),
+      ...token.sourceSide ? { source_side: token.sourceSide } : {},
+      source_owner: token.sourceOwner,
+      ...token.labelEnabled !== void 0 ? { label_enabled: token.labelEnabled } : {},
+      ...token.label !== void 0 ? { label: token.label } : {}
+    });
+  }
+  return { value, formats, mathObjects, hasPersistedMath };
+}
+function fieldJson(field) {
+  const serialized = serializeField(field);
+  return {
+    value: serialized.value,
+    ...serialized.formats.length > 0 ? { formats: serialized.formats } : {},
+    ...serialized.hasPersistedMath ? { math_objects: serialized.mathObjects } : {}
+  };
+}
+function listItemJson(item) {
+  const field = fieldJson(item.field);
+  return {
+    value: field.value ?? "",
+    ...field.formats ? { formats: field.formats } : {},
+    ...field.math_objects ? { math_objects: field.math_objects } : {},
+    ...item.blocks.length > 0 ? { blocks: item.blocks.map(blockJson) } : {}
+  };
+}
+function blockJson(block) {
+  if (block.kind === "textBlock") {
+    return {
+      id: block.id,
+      command: block.command,
+      ...fieldJson(block.field),
+      ...block.command === "\\paragraph" ? { centered: block.centered === true } : {}
+    };
+  }
+  if (block.kind === "list") {
+    return {
+      id: block.id,
+      command: block.command,
+      closing: block.closing,
+      items: block.items.map(listItemJson)
+    };
+  }
+  if (block.kind === "table") {
+    const fields = block.rows.map((row) => row.map(serializeField));
+    const hasPersistedMath = fields.some((row) => row.some((field) => field.hasPersistedMath));
+    return {
+      id: block.id,
+      command: block.command,
+      closing: block.closing,
+      columns: block.columns,
+      rows: fields.map((row) => row.map((field) => field.value)),
+      ...fields.some((row) => row.some((field) => field.formats.length > 0)) ? { cell_formats: fields.map((row) => row.map((field) => field.formats)) } : {},
+      ...hasPersistedMath ? { math_objects: fields.flatMap((row) => row.flatMap((field) => field.mathObjects)) } : {},
+      centered: block.centered,
+      caption_enabled: block.captionEnabled,
+      caption: block.caption,
+      label_enabled: block.labelEnabled,
+      label: block.label
+    };
+  }
+  if (block.kind === "image") {
+    return {
+      id: block.id,
+      command: block.command,
+      value: block.value,
+      ...block.assetId !== void 0 ? { asset_id: block.assetId } : {},
+      options: { ...block.options },
+      centered: block.centered,
+      caption_enabled: block.captionEnabled,
+      caption: block.caption,
+      label_enabled: block.labelEnabled,
+      label: block.label
+    };
+  }
+  if (block.kind === "bibliography") {
+    return { id: block.id, command: block.command, closing: block.closing };
+  }
+  return { id: block.id, command: block.command, value: block.value };
+}
+function referenceJson(reference) {
+  return {
+    key: reference.key,
+    authors: reference.authors,
+    title: reference.title,
+    year: reference.year,
+    url: reference.url,
+    venue: reference.venue,
+    field_separator: reference.fieldSeparator
+  };
+}
+function toDocumentJson2(document2) {
+  if (document2.nodeType !== "DocumentObject" || !Array.isArray(document2.blocks)) {
+    throw new Error("toDocumentJson2 requires a live Document2Node");
+  }
+  return {
+    node_type: "DocumentObject",
+    meta: {
+      title: document2.meta.title,
+      authors: document2.meta.authors,
+      date: { ...document2.meta.date },
+      abstract: document2.meta.abstract
+    },
+    references: document2.references.map(referenceJson),
+    blocks: document2.blocks.map(blockJson)
+  };
+}
+
+// src/document2/jsonCommands.ts
+var Document2CommandError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "Document2CommandError";
+    this.code = code;
+  }
+};
+function isObject3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireString2(value, field, allowEmpty = true) {
+  if (typeof value !== "string" || !allowEmpty && value.trim().length === 0) {
+    throw new Document2CommandError("invalid_command", `${field} must be a${allowEmpty ? "" : " non-empty"} string`);
+  }
+  return value;
+}
+function parseAnchor(value) {
+  if (!isObject3(value)) {
+    throw new Document2CommandError("invalid_command", "anchor must be an object");
+  }
+  const hasEnd = value.end === true;
+  const afterBlockId2 = typeof value.after_block_id === "string" ? value.after_block_id.trim() : "";
+  const hasAfterBlock = afterBlockId2.length > 0;
+  if (hasEnd && hasAfterBlock) {
+    throw new Document2CommandError("invalid_command", "anchor cannot contain both end and after_block_id");
+  }
+  if (hasEnd) {
+    return { end: true };
+  }
+  if (hasAfterBlock) {
+    return { after_block_id: afterBlockId2 };
+  }
+  throw new Document2CommandError("invalid_command", "anchor requires end: true or a non-empty after_block_id");
+}
+function optionalString(value, field) {
+  if (!(field in value)) {
+    return void 0;
+  }
+  if (typeof value[field] !== "string") {
+    throw new Document2CommandError("invalid_command", `${field} must be a string when provided`);
+  }
+  return value[field];
+}
+function parseTextBlockKind(value) {
+  if (value === "section" || value === "subsection" || value === "subsubsection" || value === "paragraph") {
+    return value;
+  }
+  throw new Document2CommandError("invalid_command", "kind must be section, subsection, subsubsection, or paragraph");
+}
+function parseCommand2(value) {
+  if (!isObject3(value) || typeof value.op !== "string") {
+    throw new Document2CommandError("invalid_command", "command requires an op");
+  }
+  if (value.op === "insert_text_block") {
+    return {
+      op: value.op,
+      kind: parseTextBlockKind(value.kind),
+      text: requireString2(value.text, "text"),
+      anchor: parseAnchor(value.anchor)
+    };
+  }
+  if (value.op === "replace_text_block") {
+    return {
+      op: value.op,
+      block_id: requireString2(value.block_id, "block_id", false).trim(),
+      text: requireString2(value.text, "text")
+    };
+  }
+  if (value.op === "remove_block") {
+    return {
+      op: value.op,
+      block_id: requireString2(value.block_id, "block_id", false).trim()
+    };
+  }
+  if (value.op === "insert_figure") {
+    const figureValue = optionalString(value, "value");
+    const caption = optionalString(value, "caption");
+    const label = optionalString(value, "label");
+    return {
+      op: value.op,
+      asset_id: requireString2(value.asset_id, "asset_id", false).trim(),
+      ...figureValue !== void 0 ? { value: figureValue } : {},
+      ...caption !== void 0 ? { caption } : {},
+      ...label !== void 0 ? { label } : {},
+      anchor: parseAnchor(value.anchor)
+    };
+  }
+  throw new Document2CommandError("invalid_command", `Unsupported document command: ${value.op}`);
+}
+function parseDocument(json) {
+  try {
+    return fromDocumentJson2(json);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Invalid DocumentObject JSON";
+    throw new Document2CommandError("invalid_document", message);
+  }
+}
+function commandForKind(kind) {
+  if (kind === "section") {
+    return "\\section";
+  }
+  if (kind === "subsection") {
+    return "\\subsection";
+  }
+  if (kind === "subsubsection") {
+    return "\\subsubsection";
+  }
+  return "\\paragraph";
+}
+function insertionIndex(document2, anchor) {
+  if ("end" in anchor) {
+    return document2.blocks.length;
+  }
+  const index = document2.blocks.findIndex((block) => block.id === anchor.after_block_id);
+  if (index < 0) {
+    throw new Document2CommandError("anchor_not_found", `Anchor block was not found: ${anchor.after_block_id}`);
+  }
+  return index + 1;
+}
+function afterBlockId(document2, index) {
+  return index > 0 ? document2.blocks[index - 1]?.id ?? null : null;
+}
+function insertedBlock(document2, index) {
+  const block = document2.blocks[index];
+  if (!block) {
+    throw new Document2CommandError("invalid_command", "Document command did not insert a block");
+  }
+  return block;
+}
+function insertTextBlock(document2, command) {
+  const index = insertionIndex(document2, command.anchor);
+  const next = addDocument2TextBlock(document2, commandForKind(command.kind), afterBlockId(document2, index));
+  const block = insertedBlock(next, index);
+  if (block.kind !== "textBlock") {
+    throw new Document2CommandError("block_kind_mismatch", "Inserted block is not a text block");
+  }
+  block.field = createInlineField2(command.text);
+  return next;
+}
+function replaceTextBlock(document2, command) {
+  const index = document2.blocks.findIndex((block2) => block2.id === command.block_id);
+  if (index < 0) {
+    throw new Document2CommandError("block_not_found", `Document block was not found: ${command.block_id}`);
+  }
+  const block = document2.blocks[index];
+  if (!block || block.kind !== "textBlock") {
+    throw new Document2CommandError("block_kind_mismatch", `Document block is not a text block: ${command.block_id}`);
+  }
+  if (block.field.tokens.some((token) => token.kind !== "text" || token.style !== void 0)) {
+    throw new Document2CommandError(
+      "unsupported_inline_content",
+      "Whole-block replacement is not supported for formatted or structured inline content"
+    );
+  }
+  const next = parseDocument(toDocumentJson2(document2));
+  const nextBlock = next.blocks[index];
+  if (!nextBlock || nextBlock.kind !== "textBlock") {
+    throw new Document2CommandError("block_kind_mismatch", `Document block is not a text block: ${command.block_id}`);
+  }
+  nextBlock.field = createInlineField2(command.text);
+  return next;
+}
+function removeBlock(document2, command) {
+  if (!document2.blocks.some((block) => block.id === command.block_id)) {
+    throw new Document2CommandError("block_not_found", `Document block was not found: ${command.block_id}`);
+  }
+  return removeDocument2BlockById(document2, command.block_id);
+}
+function insertFigure(document2, command) {
+  const index = insertionIndex(document2, command.anchor);
+  const next = addDocument2ImageBlock(
+    document2,
+    { assetId: command.asset_id, ...command.value !== void 0 ? { value: command.value } : {} },
+    afterBlockId(document2, index)
+  );
+  const block = insertedBlock(next, index);
+  if (block.kind !== "image") {
+    throw new Document2CommandError("block_kind_mismatch", "Inserted block is not a figure");
+  }
+  if (command.caption !== void 0) {
+    block.caption = command.caption;
+    block.captionEnabled = command.caption.trim().length > 0;
+  }
+  if (command.label !== void 0) {
+    block.label = command.label;
+    block.labelEnabled = command.label.trim().length > 0;
+  }
+  return next;
+}
+function applyDocument2Command(json, commandInput) {
+  const document2 = parseDocument(json);
+  const command = parseCommand2(commandInput);
+  let next;
+  if (command.op === "insert_text_block") {
+    next = insertTextBlock(document2, command);
+  } else if (command.op === "replace_text_block") {
+    next = replaceTextBlock(document2, command);
+  } else if (command.op === "remove_block") {
+    next = removeBlock(document2, command);
+  } else {
+    next = insertFigure(document2, command);
+  }
+  return toDocumentJson2(next);
+}
+
+// src/document2/outline.ts
+var EXCERPT_LIMIT = 160;
+function normalizeExcerpt(value) {
+  const normalized = value.replace(/\s+/g, " ").trim();
+  if (normalized.length <= EXCERPT_LIMIT) {
+    return normalized;
+  }
+  return `${normalized.slice(0, EXCERPT_LIMIT - 3)}...`;
+}
+function outlineKind(command) {
+  if (command === "\\section") {
+    return "section";
+  }
+  if (command === "\\subsection") {
+    return "subsection";
+  }
+  if (command === "\\subsubsection") {
+    return "subsubsection";
+  }
+  if (command === "\\paragraph") {
+    return "paragraph";
+  }
+  if (command === "\\begin{itemize}" || command === "\\begin{enumerate}") {
+    return "list";
+  }
+  if (command === "\\begin{tabular}") {
+    return "table";
+  }
+  if (command === "\\includegraphics") {
+    return "figure";
+  }
+  if (command === "\\begin{thebibliography}" || command === "\\bibliography") {
+    return "bibliography";
+  }
+  return "raw";
+}
+function blockExcerpt(block) {
+  if (block.command === "\\begin{itemize}" || block.command === "\\begin{enumerate}") {
+    return normalizeExcerpt((block.items ?? []).map((item) => item.value).join(" "));
+  }
+  if (block.command === "\\begin{tabular}") {
+    return normalizeExcerpt((block.rows ?? []).flat().join(" "));
+  }
+  if (block.command === "\\includegraphics") {
+    return normalizeExcerpt(block.caption || block.asset_id || block.value || "");
+  }
+  return normalizeExcerpt(block.value ?? "");
+}
+function document2Outline(json) {
+  if (!json || json.node_type !== "DocumentObject" || !Array.isArray(json.blocks)) {
+    throw new Document2CommandError("invalid_document", "DocumentObject requires a blocks array");
+  }
+  const usedIds = /* @__PURE__ */ new Set();
+  return json.blocks.map((block) => {
+    if (!block || typeof block !== "object" || typeof block.command !== "string") {
+      throw new Document2CommandError("invalid_document", "Document outline requires blocks with string commands");
+    }
+    const id = typeof block.id === "string" ? block.id.trim() : "";
+    if (id.length === 0) {
+      throw new Document2CommandError("missing_block_id", "Document outline requires canonical block IDs");
+    }
+    if (usedIds.has(id)) {
+      throw new Document2CommandError("duplicate_block_id", `Duplicate document block ID: ${id}`);
+    }
+    usedIds.add(id);
+    return {
+      id,
+      kind: outlineKind(block.command),
+      command: block.command,
+      excerpt: blockExcerpt(block)
+    };
+  });
+}
+
 // src/document2/keys.ts
 var DOCUMENT2_KEY_PATTERN = /^[\p{L}\p{M}0-9:._-]+$/u;
 function normalizeDocument2Key(key) {
@@ -5696,155 +6211,6 @@ ${body}
 `;
 }
 
-// src/document2/exportJson.ts
-function serializeField(field) {
-  let value = "";
-  let hasPersistedMath = false;
-  const formats = [];
-  const mathObjects = [];
-  for (const token of field.tokens) {
-    if (token.kind === "text") {
-      const start = value.length;
-      value += token.text;
-      if (token.text.length > 0 && (token.style?.bold || token.style?.italic || token.style?.underline)) {
-        formats.push({
-          start,
-          end: value.length,
-          ...token.style.bold ? { bold: true } : {},
-          ...token.style.italic ? { italic: true } : {},
-          ...token.style.underline ? { underline: true } : {}
-        });
-      }
-      continue;
-    }
-    if (token.kind === "cite") {
-      value += citeTokenLatex(token.keys);
-      continue;
-    }
-    if (token.kind === "ref") {
-      value += refTokenLatex(token.keys, token.refCommand);
-      continue;
-    }
-    value += token.source;
-    if (!token.math || token.sourceOwner === "raw") {
-      if (token.labelEnabled !== void 0 || token.label !== void 0) {
-        hasPersistedMath = true;
-        mathObjects.push({
-          node_type: "RawMathObject",
-          ...token.labelEnabled !== void 0 ? { label_enabled: token.labelEnabled } : {},
-          ...token.label !== void 0 ? { label: token.label } : {}
-        });
-      } else {
-        mathObjects.push(null);
-      }
-      continue;
-    }
-    hasPersistedMath = true;
-    mathObjects.push({
-      ...toMathObjectJson(token.math),
-      ...token.sourceSide ? { source_side: token.sourceSide } : {},
-      source_owner: token.sourceOwner,
-      ...token.labelEnabled !== void 0 ? { label_enabled: token.labelEnabled } : {},
-      ...token.label !== void 0 ? { label: token.label } : {}
-    });
-  }
-  return { value, formats, mathObjects, hasPersistedMath };
-}
-function fieldJson(field) {
-  const serialized = serializeField(field);
-  return {
-    value: serialized.value,
-    ...serialized.formats.length > 0 ? { formats: serialized.formats } : {},
-    ...serialized.hasPersistedMath ? { math_objects: serialized.mathObjects } : {}
-  };
-}
-function listItemJson(item) {
-  const field = fieldJson(item.field);
-  return {
-    value: field.value ?? "",
-    ...field.formats ? { formats: field.formats } : {},
-    ...field.math_objects ? { math_objects: field.math_objects } : {},
-    ...item.blocks.length > 0 ? { blocks: item.blocks.map(blockJson) } : {}
-  };
-}
-function blockJson(block) {
-  if (block.kind === "textBlock") {
-    return {
-      command: block.command,
-      ...fieldJson(block.field),
-      ...block.command === "\\paragraph" ? { centered: block.centered === true } : {}
-    };
-  }
-  if (block.kind === "list") {
-    return {
-      command: block.command,
-      closing: block.closing,
-      items: block.items.map(listItemJson)
-    };
-  }
-  if (block.kind === "table") {
-    const fields = block.rows.map((row) => row.map(serializeField));
-    const hasPersistedMath = fields.some((row) => row.some((field) => field.hasPersistedMath));
-    return {
-      command: block.command,
-      closing: block.closing,
-      columns: block.columns,
-      rows: fields.map((row) => row.map((field) => field.value)),
-      ...fields.some((row) => row.some((field) => field.formats.length > 0)) ? { cell_formats: fields.map((row) => row.map((field) => field.formats)) } : {},
-      ...hasPersistedMath ? { math_objects: fields.flatMap((row) => row.flatMap((field) => field.mathObjects)) } : {},
-      centered: block.centered,
-      caption_enabled: block.captionEnabled,
-      caption: block.caption,
-      label_enabled: block.labelEnabled,
-      label: block.label
-    };
-  }
-  if (block.kind === "image") {
-    return {
-      command: block.command,
-      value: block.value,
-      ...block.assetId !== void 0 ? { asset_id: block.assetId } : {},
-      options: { ...block.options },
-      centered: block.centered,
-      caption_enabled: block.captionEnabled,
-      caption: block.caption,
-      label_enabled: block.labelEnabled,
-      label: block.label
-    };
-  }
-  if (block.kind === "bibliography") {
-    return { command: block.command, closing: block.closing };
-  }
-  return { command: block.command, value: block.value };
-}
-function referenceJson(reference) {
-  return {
-    key: reference.key,
-    authors: reference.authors,
-    title: reference.title,
-    year: reference.year,
-    url: reference.url,
-    venue: reference.venue,
-    field_separator: reference.fieldSeparator
-  };
-}
-function toDocumentJson2(document2) {
-  if (document2.nodeType !== "DocumentObject" || !Array.isArray(document2.blocks)) {
-    throw new Error("toDocumentJson2 requires a live Document2Node");
-  }
-  return {
-    node_type: "DocumentObject",
-    meta: {
-      title: document2.meta.title,
-      authors: document2.meta.authors,
-      date: { ...document2.meta.date },
-      abstract: document2.meta.abstract
-    },
-    references: document2.references.map(referenceJson),
-    blocks: document2.blocks.map(blockJson)
-  };
-}
-
 // src/document2/history.ts
 var DEFAULT_DOCUMENT2_HISTORY_MAX_DEPTH = 100;
 function createDocument2History(maxDepth = DEFAULT_DOCUMENT2_HISTORY_MAX_DEPTH) {
@@ -6122,6 +6488,7 @@ export {
   DEFAULT_DOCUMENT2_HISTORY_MAX_DEPTH,
   DEFAULT_HIJRI_DATE,
   DEFAULT_REFERENCE_FIELD_SEPARATOR,
+  Document2CommandError,
   HIJRI_MONTH_IDS,
   HIJRI_YEAR_MAX,
   HIJRI_YEAR_MIN,
@@ -6132,6 +6499,7 @@ export {
   addDocument2Reference,
   addDocument2TableBlock,
   addDocument2TextBlock,
+  applyDocument2Command,
   applyFloatMetaPatch,
   arabicXeLatexPreambleCmd,
   arabicXeLatexPreambleFont,
@@ -6147,6 +6515,7 @@ export {
   butexMaghribiDisplayLatex,
   butexMaghribiDisplayTex,
   citeTokenLatex,
+  clearDocument2ImageAsset,
   cloneDocument2Meta,
   cloneDocument2Node,
   collectDocument2Labels,
@@ -6166,6 +6535,7 @@ export {
   document2HistoryCanUndo,
   document2KeyError,
   document2Latex,
+  document2Outline,
   document2Preview,
   emptyBlockSelection,
   emptyDocument2Meta,
@@ -6232,6 +6602,7 @@ export {
   toggleBlockInSelection,
   toggleTextTokenStyle,
   updateCiteTokenKeys,
+  updateDocument2ImageAsset,
   updateDocument2ImageMeta,
   updateDocument2ImageValue,
   updateDocument2Meta,