@stll/folio-core 0.21.0 → 0.22.0

package/dist/docx/rezip.js

@@ -6,7 +6,7 @@ import { assertValidFolioDocumentModel } from "./modelValidation.js";
 import { isNewDataUrlDrawing } from "./newImage.js";
 import { parseNumbering } from "./numberingParser.js";
 import { RELATIONSHIP_TYPES, parseRelationships, resolveRelativePath } from "./relsParser.js";
-import { buildParagraphOffsetIndex, buildPatchedNoteXml, buildPatchedNumberingXml, collectChangedNumberingDefs, collectParaIds } from "./selectiveXmlPatch.js";
+import { appendNumberingDefs, buildParagraphOffsetIndex, buildPatchedNoteXml, buildPatchedNumberingXml, collectAddedNumberingDefs, collectChangedNumberingDefs, collectParaIds } from "./selectiveXmlPatch.js";
 import { ensureThreadedCommentParaIds, serializeComments, serializeCommentsExtended } from "./serializer/commentSerializer.js";
 import { serializeDocument } from "./serializer/documentSerializer.js";
 import { serializeFontTableXml } from "./serializer/fontTableSerializer.js";
@@ -14,7 +14,7 @@ import { serializeHeaderFooter } from "./serializer/headerFooterSerializer.js";
 import { serializeEndnotes, serializeFootnotes, serializeNewEndnotesPart, serializeNewFootnotesPart } from "./serializer/noteSerializer.js";
 import { serializeNumberingXml } from "./serializer/numberingSerializer.js";
 import { serializeSettingsXml } from "./serializer/settingsSerializer.js";
-import { serializeStylesXml } from "./serializer/stylesSerializer.js";
+import { serializeStyle, serializeStylesXml } from "./serializer/stylesSerializer.js";
 import { serializeThemeXml } from "./serializer/themeSerializer.js";
 import { escapeXml } from "./serializer/xmlUtils.js";
 import { isPreservableDocxEntry } from "./unzip.js";
@@ -450,6 +450,7 @@ const finishRepack = async ({ document, originalZip, outputZip, originalDocument
 	serializeHeadersFootersToZip(document, outputZip, compressionLevel);
 	await serializeNotesToZip(document, originalZip, outputZip, compressionLevel);
 	await serializeNumberingIntoZip(document, originalZip, outputZip, compressionLevel);
+	await serializeAddedStylesIntoZip(document, originalZip, outputZip, compressionLevel);
 	await serializeCommentsToZip(document, outputZip, compressionLevel);
 	if (updateModifiedDate && originalCorePropertiesXml) {
 		const updatedCoreProperties = updateCoreProperties(originalCorePropertiesXml, {
@@ -530,6 +531,7 @@ async function repackDocxFromRaw(doc, rawContent, options = {}) {
 	serializeHeadersFootersToZip(exportDocument, newZip, compressionLevel);
 	await serializeNotesToZip(exportDocument, rawContent.originalZip, newZip, compressionLevel);
 	await serializeNumberingIntoZip(exportDocument, rawContent.originalZip, newZip, compressionLevel);
+	await serializeAddedStylesIntoZip(exportDocument, rawContent.originalZip, newZip, compressionLevel);
 	await serializeCommentsToZip(exportDocument, newZip, compressionLevel);
 	if (updateModifiedDate && rawContent.corePropsXml) {
 		const updatedCoreProps = updateCoreProperties(rawContent.corePropsXml, {
@@ -1081,14 +1083,56 @@ async function serializeNumberingIntoZip(doc, originalZip, newZip, compressionLe
 	}
 	const currentXml = serializeNumberingXml(numbering);
 	const changed = collectChangedNumberingDefs(baseline.serializedXml, currentXml);
-	if (changed.abstractNums.size === 0 && changed.nums.size === 0) return;
-	const patched = buildPatchedNumberingXml(baseline.originalXml, currentXml, changed);
+	const added = collectAddedNumberingDefs(baseline.serializedXml, currentXml);
+	const hasChanged = changed.abstractNums.size > 0 || changed.nums.size > 0;
+	const hasAdded = added.abstractNums.size > 0 || added.nums.size > 0;
+	if (!hasChanged && !hasAdded) return;
+	const spliced = buildPatchedNumberingXml(baseline.originalXml, currentXml, changed);
+	if (spliced === null) return;
+	const patched = appendNumberingDefs(spliced, currentXml, added);
 	if (patched === null) return;
 	newZip.file(file.name, patched, {
 		compression: "DEFLATE",
 		compressionOptions: { level: compressionLevel }
 	});
 }
+const STYLES_PART_PATH = "word/styles.xml";
+const STYLES_CLOSE_ROOT = "</w:styles>";
+const STYLE_ID_PATTERN = /<w:style\b[^>]*?\bw:styleId="(?<id>[^"]+)"/gu;
+/**
+* Append styles the model defines but the original `word/styles.xml` lacks.
+* Existing styles stay byte-exact (edits to them are not written here, the
+* part is otherwise preserved verbatim); only minted definitions, such as the
+* per-language clones a bilingual transform adds, are emitted before the root
+* close so paragraphs referencing them resolve on reopen.
+*/
+async function serializeAddedStylesIntoZip(doc, originalZip, newZip, compressionLevel) {
+	const styles = doc.package.styles;
+	if (!styles || styles.styles.length === 0) return;
+	const file = findNotePartEntry(originalZip, STYLES_PART_PATH);
+	const originalXml = file ? await file.async("text") : null;
+	const rootClose = originalXml?.lastIndexOf(STYLES_CLOSE_ROOT) ?? -1;
+	if (file === null || originalXml === null || rootClose < 0) {
+		await materializeNewNotePart({
+			contentType: "application/vnd.openxmlformats-officedocument.wordprocessingml.styles+xml",
+			newZip,
+			partPath: STYLES_PART_PATH,
+			relationshipType: RELATIONSHIP_TYPES.styles,
+			serializedPart: serializeStylesXml(styles),
+			compressionLevel
+		});
+		return;
+	}
+	const existing = /* @__PURE__ */ new Set();
+	for (const match of originalXml.matchAll(STYLE_ID_PATTERN)) existing.add(match.groups["id"]);
+	const added = styles.styles.filter((style) => !existing.has(style.styleId));
+	if (added.length === 0) return;
+	const patched = originalXml.slice(0, rootClose) + added.map(serializeStyle).join("") + originalXml.slice(rootClose);
+	newZip.file(file.name, patched, {
+		compression: "DEFLATE",
+		compressionOptions: { level: compressionLevel }
+	});
+}
 async function patchNotePartIntoZip(conventionalLowerPath, currentXml, baselineFrom, originalZip, newZip, compressionLevel) {
 	const file = findNotePartEntry(originalZip, conventionalLowerPath);
 	if (!file) return;

package/dist/docx/selectiveXmlPatch.d.ts

@@ -129,5 +129,23 @@ declare function collectChangedNumberingDefs(baselineXml: string, currentXml: st
  * in either input (so the caller preserves the original part verbatim).
  */
 declare function buildPatchedNumberingXml(originalXml: string, currentXml: string, changed: ChangedNumberingDefs): string | null;
+/**
+ * Numbering definitions present in `currentXml` (the model's serialization)
+ * but absent from `baselineXml` (the re-parsed original): definitions a
+ * transform minted. `collectChangedNumberingDefs` deliberately skips these
+ * because they cannot be spliced by id; they are appended instead.
+ */
+declare function collectAddedNumberingDefs(baselineXml: string, currentXml: string): ChangedNumberingDefs;
+/**
+ * Append added `w:abstractNum` / `w:num` definitions from `currentXml` to
+ * `xml`. ECMA-376 §17.9 orders every `w:abstractNum` before the first `w:num`,
+ * so abstract definitions go right before the first `<w:num ` (or the root
+ * close when the part has none) and instances before the root close. A
+ * synthetic numFmt in an added abstract is restored from the original
+ * definition it was cloned from (the one with an identical body), so a custom
+ * format survives cloning. Returns null when an added id cannot be extracted
+ * or the part has no `</w:numbering>`.
+ */
+declare function appendNumberingDefs(xml: string, currentXml: string, added: ChangedNumberingDefs): string | null;
 //#endregion
-export { ChangedNumberingDefs, ParagraphOffsets, PatchSafetyOptions, PatchValidationResult, buildParagraphOffsetIndex, buildPatchedDocumentXml, buildPatchedNoteXml, buildPatchedNumberingXml, collectChangedNumberingDefs, collectParaIds, countParagraphElements, extractParagraphXml, findParagraphOffsets, isXmlNameBoundary, validatePatchSafety };
+export { ChangedNumberingDefs, ParagraphOffsets, PatchSafetyOptions, PatchValidationResult, appendNumberingDefs, buildParagraphOffsetIndex, buildPatchedDocumentXml, buildPatchedNoteXml, buildPatchedNumberingXml, collectAddedNumberingDefs, collectChangedNumberingDefs, collectParaIds, countParagraphElements, extractParagraphXml, findParagraphOffsets, isXmlNameBoundary, validatePatchSafety };

package/dist/docx/selectiveXmlPatch.js

@@ -552,8 +552,79 @@ function buildPatchedNumberingXml(originalXml, currentXml, changed) {
 	for (const { start, end, newXml } of replacements) result = result.slice(0, start) + newXml + result.slice(end);
 	return result;
 }
+/**
+* Numbering definitions present in `currentXml` (the model's serialization)
+* but absent from `baselineXml` (the re-parsed original): definitions a
+* transform minted. `collectChangedNumberingDefs` deliberately skips these
+* because they cannot be spliced by id; they are appended instead.
+*/
+function collectAddedNumberingDefs(baselineXml, currentXml) {
+	const addedForKind = (kind) => {
+		const added = /* @__PURE__ */ new Set();
+		const baselineIndex = buildNumberingElementOffsetIndex(baselineXml, kind);
+		const currentIndex = buildNumberingElementOffsetIndex(currentXml, kind);
+		for (const [id, range] of currentIndex) if (range && !baselineIndex.has(id)) added.add(id);
+		return added;
+	};
+	return {
+		abstractNums: addedForKind("abstractNum"),
+		nums: addedForKind("num")
+	};
+}
+const NUMBERING_CLOSE_ROOT = "</w:numbering>";
+/**
+* Append added `w:abstractNum` / `w:num` definitions from `currentXml` to
+* `xml`. ECMA-376 §17.9 orders every `w:abstractNum` before the first `w:num`,
+* so abstract definitions go right before the first `<w:num ` (or the root
+* close when the part has none) and instances before the root close. A
+* synthetic numFmt in an added abstract is restored from the original
+* definition it was cloned from (the one with an identical body), so a custom
+* format survives cloning. Returns null when an added id cannot be extracted
+* or the part has no `</w:numbering>`.
+*/
+function appendNumberingDefs(xml, currentXml, added) {
+	if (added.abstractNums.size === 0 && added.nums.size === 0) return xml;
+	const rootClose = xml.lastIndexOf(NUMBERING_CLOSE_ROOT);
+	if (rootClose < 0) return null;
+	const abstractXmls = [];
+	for (const id of added.abstractNums) {
+		const def = extractNumberingElementXml(currentXml, "abstractNum", id);
+		if (def === null) return null;
+		abstractXmls.push(restoreClonedLevelNumFmts(xml, currentXml, def, id));
+	}
+	const numXmls = [];
+	for (const id of added.nums) {
+		const def = extractNumberingElementXml(currentXml, "num", id);
+		if (def === null) return null;
+		numXmls.push(def);
+	}
+	const firstNum = findFirstElement(xml, NUMBERING_OPEN_LITERAL.num, NUMBERING_CLOSE_TAG.num);
+	const abstractInsertAt = firstNum ? firstNum.start : rootClose;
+	const head = xml.slice(0, abstractInsertAt);
+	const middle = xml.slice(abstractInsertAt, rootClose);
+	const tail = xml.slice(rootClose);
+	return head + abstractXmls.join("") + middle + numXmls.join("") + tail;
+}
+/**
+* For an added abstract definition that still carries a synthetic numFmt, find
+* the original abstract it was cloned from (same serialized body apart from the
+* id) and restore the level formats from it.
+*/
+function restoreClonedLevelNumFmts(originalXml, currentXml, addedDefXml, addedId) {
+	if (!SYNTHETIC_NUM_FMT_PATTERN.test(addedDefXml)) return addedDefXml;
+	const addedBody = stripAbstractNumId(addedDefXml, addedId);
+	const originalIds = collectElementIds(originalXml, NUMBERING_OPEN_LITERAL.abstractNum, NUMBERING_ID_ATTR.abstractNum);
+	for (const [id] of originalIds) {
+		const candidate = extractNumberingElementXml(currentXml, "abstractNum", id);
+		if (candidate === null || stripAbstractNumId(candidate, id) !== addedBody) continue;
+		const originalDef = extractNumberingElementXml(originalXml, "abstractNum", id);
+		if (originalDef !== null) return restoreLevelNumFmts(originalDef, addedDefXml);
+	}
+	return restoreLevelNumFmts("", addedDefXml);
+}
+const stripAbstractNumId = (defXml, id) => defXml.replace(`${NUMBERING_ID_ATTR.abstractNum}="${id}"`, "");
 function escapeRegExp(str) {
 	return str.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 }
 //#endregion
-export { buildParagraphOffsetIndex, buildPatchedDocumentXml, buildPatchedNoteXml, buildPatchedNumberingXml, collectChangedNumberingDefs, collectParaIds, countParagraphElements, extractParagraphXml, findParagraphOffsets, isXmlNameBoundary, validatePatchSafety };
+export { appendNumberingDefs, buildParagraphOffsetIndex, buildPatchedDocumentXml, buildPatchedNoteXml, buildPatchedNumberingXml, collectAddedNumberingDefs, collectChangedNumberingDefs, collectParaIds, countParagraphElements, extractParagraphXml, findParagraphOffsets, isXmlNameBoundary, validatePatchSafety };

package/dist/docx/serializer/stylesSerializer.d.ts

@@ -1,5 +1,6 @@
 import { document_d_exports } from "../../types/document.js";
 //#region src/docx/serializer/stylesSerializer.d.ts
 declare const serializeStylesXml: (definitions: document_d_exports.StyleDefinitions) => string;
+declare const serializeStyle: (style: document_d_exports.Style) => string;
 //#endregion
-export { serializeStylesXml };
+export { serializeStyle, serializeStylesXml };

package/dist/docx/serializer/stylesSerializer.js

@@ -53,4 +53,4 @@ const pushBooleanAttr = (attrs, name, value) => {
 	if (value !== void 0) attrs.push(`${name}="${value ? 1 : 0}"`);
 };
 //#endregion
-export { serializeStylesXml };
+export { serializeStyle, serializeStylesXml };

package/dist/docx/server/createBilingualDocument.d.ts

@@ -0,0 +1,62 @@
+import { document_d_exports } from "../../types/document.js";
+//#region src/docx/server/createBilingualDocument.d.ts
+type BilingualRowKind = "paragraph" | "heading" | "listItem";
+/** One translatable unit: a source paragraph and its right-column copy. */
+type BilingualParagraphRef = {
+  /** `paraId` of the untouched source paragraph (left column). */
+  sourceParaId: string | undefined;
+  /** `paraId` minted for the right-column copy; stable across re-runs. */
+  targetParaId: string;
+  /** Plain text of the source paragraph. */
+  sourceText: string;
+};
+type BilingualRow = ({
+  kind: BilingualRowKind;
+  /** Equals `targetParaId`; the handle callers use to address the row. */
+  rowId: string;
+} & BilingualParagraphRef) | {
+  kind: "table";
+  rowId: string;
+  /**
+   * Every paragraph inside the table, in document order. The table is not
+   * copied, so these are the paragraphs to translate in place.
+   */
+  paragraphs: BilingualTableParagraphRef[];
+};
+type BilingualTableParagraphRef = {
+  paraId: string | undefined;
+  sourceText: string;
+};
+type BilingualBorders = "none" | "grid";
+type CreateBilingualDocumentOptions = {
+  /**
+   * Suffix for cloned style ids and names (for example `"en"` turns
+   * `Heading1` into `Heading1-en`). Must be a non-empty token of letters,
+   * digits, or `-`.
+   */
+  targetStyleSuffix: string;
+  /** Table borders; legal practice is usually `"none"`. Default `"none"`. */
+  borders?: BilingualBorders;
+};
+type CreateBilingualDocumentResult = {
+  document: document_d_exports.Document;
+  rows: BilingualRow[];
+  /** Non-fatal fidelity notes (for example an unresolvable numbering style link). */
+  warnings: string[];
+};
+declare const InvalidBilingualDocumentOptionsError_base: import("better-result").TaggedErrorClass<"InvalidBilingualDocumentOptionsError", {
+  message: string;
+  option: "targetStyleSuffix";
+}>;
+declare class InvalidBilingualDocumentOptionsError extends InvalidBilingualDocumentOptionsError_base {}
+declare function createBilingualDocument(source: document_d_exports.Document, options: CreateBilingualDocumentOptions): CreateBilingualDocumentResult;
+/**
+ * Re-derive the row manifest from a document produced by
+ * {@link createBilingualDocument}. Detection is structural: a top-level table
+ * whose rows are all either a left | right pair of single-paragraph cells or
+ * one cell spanning both columns. Rows are returned in document order; the
+ * right paragraph's `paraId` is the row handle, as at creation.
+ */
+declare function readBilingualDocument(document: document_d_exports.Document): BilingualRow[];
+//#endregion
+export { BilingualBorders, BilingualParagraphRef, BilingualRow, BilingualRowKind, BilingualTableParagraphRef, CreateBilingualDocumentOptions, CreateBilingualDocumentResult, InvalidBilingualDocumentOptionsError, createBilingualDocument, readBilingualDocument };

package/dist/docx/server/createBilingualDocument.js

@@ -0,0 +1,511 @@
+import { deterministicHexId } from "../../utils/hexId.js";
+import { getParagraphText } from "../paragraphParser.js";
+import { TaggedError } from "better-result";
+//#region src/docx/server/createBilingualDocument.ts
+/**
+* Bilingual document transform: body -> two-column table, one row per block.
+*
+* The left column keeps every source block untouched; the right column holds a
+* copy of the same block whose numbering and numbered paragraph styles are
+* cloned per language, so both columns count independently (1. / 1. instead of
+* 1. / 2.) and stay live in Word. Right-column paragraphs receive fresh
+* `paraId`s so callers can address each row later (for example to replace the
+* placeholder copy with a translation by block id).
+*
+* Section breaks cannot live inside a table cell, so the body is split at
+* paragraphs carrying `sectionProperties`: each section becomes its own table
+* and the break paragraph stays between the tables. A source table (parties,
+* signature block) is kept once, in a row spanning both columns: it is signed
+* and read once, and its labels are translated inline rather than duplicated.
+*/
+const STYLE_SUFFIX_PATTERN = /^[A-Za-z0-9-]+$/u;
+var InvalidBilingualDocumentOptionsError = class extends TaggedError("InvalidBilingualDocumentOptionsError")() {};
+const FULL_WIDTH_PCT = 5e3;
+const HALF_WIDTH_PCT = 2500;
+const A4_TEXT_WIDTH_TWIPS = 9072;
+const ROW_ID_NAMESPACE = "folio-bilingual";
+const GRID_BORDER = {
+	style: "single",
+	size: 4,
+	space: 0
+};
+const TABLE_BORDERS = {
+	none: {
+		top: { style: "nil" },
+		bottom: { style: "nil" },
+		left: { style: "nil" },
+		right: { style: "nil" },
+		insideH: { style: "nil" },
+		insideV: { style: "nil" }
+	},
+	grid: {
+		top: GRID_BORDER,
+		bottom: GRID_BORDER,
+		left: GRID_BORDER,
+		right: GRID_BORDER,
+		insideH: GRID_BORDER,
+		insideV: GRID_BORDER
+	}
+};
+function createBilingualDocument(source, options) {
+	if (!STYLE_SUFFIX_PATTERN.test(options.targetStyleSuffix)) throw new InvalidBilingualDocumentOptionsError({
+		message: `targetStyleSuffix must match ${STYLE_SUFFIX_PATTERN}; received ${JSON.stringify(options.targetStyleSuffix)}`,
+		option: "targetStyleSuffix"
+	});
+	const borders = options.borders ?? "none";
+	const warnings = [];
+	const styles = source.package.styles;
+	const numbering = source.package.numbering;
+	const styleById = new Map((styles?.styles ?? []).map((style) => [style.styleId, style]));
+	const blocks = flattenBlocks(source.package.document.content);
+	const cloner = createNumberingCloner({
+		numbering,
+		styleById,
+		warnings
+	});
+	const styleCloner = createStyleCloner({
+		styleById,
+		suffix: options.targetStyleSuffix,
+		cloner
+	});
+	const paraIds = createParaIdMinter(collectPackageParaIds(source.package));
+	const rows = [];
+	const content = [];
+	let sectionRows = [];
+	const textWidth = resolveTextWidthTwips(source);
+	const flushSection = () => {
+		if (sectionRows.length > 0) content.push(buildTable(sectionRows, borders, textWidth));
+		sectionRows = [];
+	};
+	const copyParagraph = (paragraph) => {
+		const targetParaId = paraIds.mint(paragraph.paraId);
+		return {
+			copy: cloneParagraphForTarget(paragraph, targetParaId, styleCloner, cloner),
+			ref: {
+				sourceParaId: paragraph.paraId,
+				targetParaId,
+				sourceText: getParagraphText(paragraph)
+			}
+		};
+	};
+	for (const block of blocks) {
+		if (block.type === "paragraph" && block.sectionProperties) {
+			flushSection();
+			content.push(block);
+			continue;
+		}
+		if (block.type === "paragraph") {
+			if (isEmptyParagraph(block)) continue;
+			const { copy, ref } = copyParagraph(block);
+			rows.push({
+				kind: classifyParagraph(block, styleById),
+				rowId: ref.targetParaId,
+				...ref
+			});
+			sectionRows.push(buildRow(block, copy));
+			continue;
+		}
+		const paragraphs = collectTableParagraphs(block).map((paragraph) => ({
+			paraId: paragraph.paraId,
+			sourceText: getParagraphText(paragraph)
+		}));
+		rows.push({
+			kind: "table",
+			rowId: paragraphs.at(0)?.paraId ?? tableRowHandle(rows.length),
+			paragraphs
+		});
+		sectionRows.push(buildSpanningRow(block));
+	}
+	flushSection();
+	return {
+		document: {
+			...source,
+			package: {
+				...source.package,
+				document: {
+					...source.package.document,
+					content
+				},
+				...cloner.hasClones() && { numbering: cloner.toDefinitions() },
+				...styleCloner.hasClones() && styles && { styles: styleCloner.toDefinitions(styles) }
+			}
+		},
+		rows,
+		warnings
+	};
+}
+/** Handle for a table row whose paragraphs carry no `paraId`: its position in
+*  the manifest, which creation and reading derive identically. */
+const tableRowHandle = (index) => `table-${index}`;
+/** Top-level body blocks with content controls flattened to their children. */
+const flattenBlocks = (content) => {
+	const out = [];
+	const visit = (block) => {
+		if (block.type === "paragraph" || block.type === "table") {
+			out.push(block);
+			return;
+		}
+		for (const child of block.content) visit(child);
+	};
+	for (const block of content) visit(block);
+	return out;
+};
+const isEmptyParagraph = (paragraph) => {
+	if (getParagraphText(paragraph).trim().length > 0) return false;
+	return paragraph.content.every((item) => item.type === "run" && item.content.every((part) => part.type === "text"));
+};
+/** Heading style families across Word UI languages (en, cs/sk, de, fr, pl). */
+const HEADING_STYLE_PATTERN = /heading|nadpis|berschrift|titre|nag[łl]/iu;
+const classifyParagraph = (paragraph, styleById) => {
+	const formatting = paragraph.formatting;
+	const style = formatting?.styleId ? styleById.get(formatting.styleId) : void 0;
+	const outlineLevel = formatting?.outlineLevel ?? resolveInheritedOutlineLevel(style, styleById);
+	if (outlineLevel !== void 0 && outlineLevel < 9) return "heading";
+	if (style && (HEADING_STYLE_PATTERN.test(style.styleId) || HEADING_STYLE_PATTERN.test(style.name ?? ""))) return "heading";
+	if (effectiveNumPr(paragraph, styleById) !== void 0) return "listItem";
+	return "paragraph";
+};
+const resolveInheritedOutlineLevel = (style, styleById) => {
+	const seen = /* @__PURE__ */ new Set();
+	let current = style;
+	while (current && !seen.has(current.styleId)) {
+		seen.add(current.styleId);
+		if (current.pPr?.outlineLevel !== void 0) return current.pPr.outlineLevel;
+		current = current.basedOn ? styleById.get(current.basedOn) : void 0;
+	}
+};
+/** The numbering a paragraph renders with: direct `numPr`, else the style chain's. */
+const effectiveNumPr = (paragraph, styleById) => {
+	const direct = paragraph.formatting?.numPr;
+	if (direct?.numId !== void 0) return direct.numId === 0 ? void 0 : direct;
+	const styleId = paragraph.formatting?.styleId;
+	return styleId ? styleNumPr(styleById.get(styleId), styleById) : void 0;
+};
+const styleNumPr = (style, styleById) => {
+	const seen = /* @__PURE__ */ new Set();
+	let current = style;
+	while (current && !seen.has(current.styleId)) {
+		seen.add(current.styleId);
+		const numPr = current.pPr?.numPr;
+		if (numPr?.numId !== void 0) return numPr.numId === 0 ? void 0 : numPr;
+		current = current.basedOn ? styleById.get(current.basedOn) : void 0;
+	}
+};
+const createNumberingCloner = ({ numbering, styleById, warnings }) => {
+	const abstractNums = numbering?.abstractNums ?? [];
+	const nums = numbering?.nums ?? [];
+	const abstractById = new Map(abstractNums.map((item) => [item.abstractNumId, item]));
+	const numById = new Map(nums.map((item) => [item.numId, item]));
+	let nextAbstractNumId = Math.max(0, ...abstractNums.map((item) => item.abstractNumId)) + 1;
+	let nextNumId = Math.max(0, ...nums.map((item) => item.numId)) + 1;
+	const clonedAbstract = /* @__PURE__ */ new Map();
+	const clonedNum = /* @__PURE__ */ new Map();
+	/**
+	* Word keys list counters by the abstract definition a `w:num` points at;
+	* two instances sharing one abstract continue the same sequence. A clone
+	* therefore needs its own abstract, and an abstract that only links to a
+	* numbering style must be materialized from that style's levels, otherwise
+	* both clones resolve to the same linked definition and share counters.
+	*/
+	const cloneAbstract = (sourceId) => {
+		const existing = clonedAbstract.get(sourceId);
+		if (existing) return existing;
+		const source = abstractById.get(sourceId);
+		if (!source) return;
+		const resolved = resolveLinkedAbstract(source);
+		const { numStyleLink: _numStyleLink, styleLink: _styleLink, ...rest } = resolved;
+		const clone = {
+			...rest,
+			abstractNumId: nextAbstractNumId,
+			levels: structuredClone(resolved.levels)
+		};
+		nextAbstractNumId += 1;
+		clonedAbstract.set(sourceId, clone);
+		return clone;
+	};
+	const resolveLinkedAbstract = (abstract) => {
+		const seen = /* @__PURE__ */ new Set();
+		let current = abstract;
+		while (current.numStyleLink && !seen.has(current.abstractNumId)) {
+			seen.add(current.abstractNumId);
+			const linkedNumId = styleById.get(current.numStyleLink)?.pPr?.numPr?.numId;
+			const linkedNum = linkedNumId === void 0 ? void 0 : numById.get(linkedNumId);
+			const linkedAbstract = linkedNum ? abstractById.get(linkedNum.abstractNumId) : void 0;
+			if (!linkedAbstract) {
+				warnings.push(`Numbering style link "${current.numStyleLink}" on abstractNum ${current.abstractNumId} could not be resolved; the clone keeps the link.`);
+				return current;
+			}
+			current = linkedAbstract;
+		}
+		return current;
+	};
+	const cloneNumId = (numId) => {
+		const existing = clonedNum.get(numId);
+		if (existing) return existing.numId;
+		const source = numById.get(numId);
+		if (!source) {
+			warnings.push(`Numbering instance ${numId} is not defined; paragraphs using it keep the source instance.`);
+			return numId;
+		}
+		const abstract = cloneAbstract(source.abstractNumId);
+		if (!abstract) warnings.push(`Numbering instance ${numId} references abstractNum ${source.abstractNumId}, which is not defined; its copy shares the source counters.`);
+		const clone = {
+			...source,
+			numId: nextNumId,
+			abstractNumId: abstract ? abstract.abstractNumId : source.abstractNumId
+		};
+		nextNumId += 1;
+		clonedNum.set(numId, clone);
+		return clone.numId;
+	};
+	return {
+		cloneNumId,
+		clonedAbstractNumId: (abstractNumId) => clonedAbstract.get(abstractNumId)?.abstractNumId,
+		hasClones: () => clonedNum.size > 0,
+		toDefinitions: () => ({
+			abstractNums: [...abstractNums, ...clonedAbstract.values()],
+			nums: [...nums, ...clonedNum.values()]
+		})
+	};
+};
+/**
+* A paragraph style is cloned only when its chain carries numbering. The clone
+* keeps `basedOn` and every other property; only `pPr.numPr` is rewritten to
+* the cloned instance, so indent precedence stays "style-sourced" exactly as
+* in the source (see `ParagraphFormatting.numPrFromStyle`).
+*/
+const createStyleCloner = ({ styleById, suffix, cloner }) => {
+	const clones = /* @__PURE__ */ new Map();
+	const styleIdFor = (styleId) => {
+		const existing = clones.get(styleId);
+		if (existing) return existing.styleId;
+		const style = styleById.get(styleId);
+		if (!style || style.type !== "paragraph") return styleId;
+		const numPr = styleNumPr(style, styleById);
+		if (numPr?.numId === void 0) return styleId;
+		const cloneId = `${styleId}-${suffix}`;
+		if (styleById.has(cloneId)) return cloneId;
+		const clone = {
+			...style,
+			styleId: cloneId,
+			name: `${style.name ?? style.styleId} (${suffix})`,
+			...style.next !== void 0 && { next: style.next === styleId ? cloneId : style.next },
+			default: false,
+			pPr: {
+				...style.pPr,
+				numPr: {
+					...numPr,
+					numId: cloner.cloneNumId(numPr.numId)
+				}
+			}
+		};
+		clones.set(styleId, clone);
+		return cloneId;
+	};
+	return {
+		styleIdFor,
+		hasClones: () => clones.size > 0,
+		toDefinitions: (styles) => ({
+			...styles,
+			styles: [...styles.styles, ...clones.values()]
+		})
+	};
+};
+const cloneParagraphForTarget = (paragraph, targetParaId, styleCloner, cloner) => {
+	const { textId: _textId, sectionProperties: _sectionProperties, ...rest } = paragraph;
+	const formatting = paragraph.formatting;
+	const nextFormatting = formatting && {
+		...formatting,
+		...formatting.styleId !== void 0 && { styleId: styleCloner.styleIdFor(formatting.styleId) },
+		...formatting.numPr?.numId !== void 0 && formatting.numPr.numId !== 0 && { numPr: {
+			...formatting.numPr,
+			numId: cloner.cloneNumId(formatting.numPr.numId)
+		} },
+		...formatting.numPrFromStyle?.numId !== void 0 && formatting.numPrFromStyle.numId !== 0 && { numPrFromStyle: {
+			...formatting.numPrFromStyle,
+			numId: cloner.cloneNumId(formatting.numPrFromStyle.numId)
+		} }
+	};
+	return {
+		...rest,
+		content: structuredClone(paragraph.content),
+		paraId: targetParaId,
+		...nextFormatting && { formatting: nextFormatting },
+		...paragraph.listRendering && { listRendering: remapListRendering(paragraph.listRendering, cloner) }
+	};
+};
+const remapListRendering = (rendering, cloner) => {
+	const clonedAbstract = rendering.abstractNumId === void 0 ? void 0 : cloner.clonedAbstractNumId(rendering.abstractNumId);
+	return {
+		...rendering,
+		numId: cloner.cloneNumId(rendering.numId),
+		...clonedAbstract !== void 0 && { abstractNumId: clonedAbstract }
+	};
+};
+const collectTableParagraphs = (table) => {
+	const out = [];
+	for (const row of table.rows) for (const cell of row.cells) for (const item of cell.content) if (item.type === "paragraph") out.push(item);
+	else out.push(...collectTableParagraphs(item));
+	return out;
+};
+const buildRow = (left, right) => ({
+	type: "tableRow",
+	formatting: { cantSplit: true },
+	cells: [buildCell(left), buildCell(right)]
+});
+const buildCell = (paragraph) => ({
+	type: "tableCell",
+	formatting: {
+		width: {
+			value: HALF_WIDTH_PCT,
+			type: "pct"
+		},
+		verticalAlign: "top"
+	},
+	content: [paragraph]
+});
+/** A source table kept once, across both columns. */
+const buildSpanningRow = (table) => ({
+	type: "tableRow",
+	formatting: { cantSplit: true },
+	cells: [{
+		type: "tableCell",
+		formatting: {
+			width: {
+				value: FULL_WIDTH_PCT,
+				type: "pct"
+			},
+			gridSpan: 2,
+			verticalAlign: "top"
+		},
+		content: [table, {
+			type: "paragraph",
+			content: []
+		}]
+	}]
+});
+const buildTable = (rows, borders, textWidth) => ({
+	type: "table",
+	formatting: {
+		width: {
+			value: FULL_WIDTH_PCT,
+			type: "pct"
+		},
+		layout: "fixed",
+		borders: TABLE_BORDERS[borders],
+		look: {
+			firstRow: false,
+			firstColumn: false,
+			noHBand: true,
+			noVBand: true
+		}
+	},
+	columnWidths: [Math.floor(textWidth / 2), Math.ceil(textWidth / 2)],
+	rows
+});
+const resolveTextWidthTwips = (doc) => {
+	const section = doc.package.document.finalSectionProperties ?? doc.package.document.sections?.at(0)?.properties;
+	if (!section?.pageWidth) return A4_TEXT_WIDTH_TWIPS;
+	const width = section.pageWidth - (section.marginLeft ?? 0) - (section.marginRight ?? 0);
+	return width > 0 ? width : A4_TEXT_WIDTH_TWIPS;
+};
+/**
+* Every `paraId` anywhere in the package (body, headers, footers, notes,
+* comments), so a minted id cannot collide with a part the body never sees.
+* Walks the model generically: any object with `type: "paragraph"` and a
+* string `paraId` counts.
+*/
+const collectPackageParaIds = (pkg) => {
+	const ids = /* @__PURE__ */ new Set();
+	const seen = /* @__PURE__ */ new Set();
+	const visit = (value) => {
+		if (typeof value !== "object" || value === null || seen.has(value)) return;
+		seen.add(value);
+		if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) return;
+		if (Array.isArray(value)) {
+			for (const item of value) visit(item);
+			return;
+		}
+		if (value instanceof Map) {
+			for (const item of value.values()) visit(item);
+			return;
+		}
+		if (isParagraphWithId(value)) ids.add(value.paraId);
+		for (const child of Object.values(value)) visit(child);
+	};
+	visit(pkg);
+	return ids;
+};
+/**
+* Fresh ids derived from the source id (so re-running on the same source
+* yields the same handles), salted past any id already in the document.
+*/
+const createParaIdMinter = (taken) => {
+	let ordinal = 0;
+	return { mint: (sourceParaId) => {
+		ordinal += 1;
+		const seed = `${ROW_ID_NAMESPACE}:${sourceParaId ?? `ordinal-${ordinal}`}`;
+		let id = deterministicHexId(seed);
+		for (let salt = 1; taken.has(id); salt += 1) id = deterministicHexId(`${seed}:${salt}`);
+		taken.add(id);
+		return id;
+	} };
+};
+/**
+* Re-derive the row manifest from a document produced by
+* {@link createBilingualDocument}. Detection is structural: a top-level table
+* whose rows are all either a left | right pair of single-paragraph cells or
+* one cell spanning both columns. Rows are returned in document order; the
+* right paragraph's `paraId` is the row handle, as at creation.
+*/
+function readBilingualDocument(document) {
+	const styleById = new Map((document.package.styles?.styles ?? []).map((style) => [style.styleId, style]));
+	const rows = [];
+	for (const block of flattenBlocks(document.package.document.content)) {
+		if (block.type !== "table" || !isBilingualTable(block)) continue;
+		for (const row of block.rows) {
+			const [left, right] = row.cells;
+			if (!left) continue;
+			if (!right) {
+				const paragraphs = left.content.filter((item) => item.type === "table").flatMap(collectTableParagraphs).map((paragraph) => ({
+					paraId: paragraph.paraId,
+					sourceText: getParagraphText(paragraph)
+				}));
+				rows.push({
+					kind: "table",
+					rowId: paragraphs.at(0)?.paraId ?? tableRowHandle(rows.length),
+					paragraphs
+				});
+				continue;
+			}
+			const source = left.content.at(0);
+			const target = right.content.at(0);
+			if (source?.type !== "paragraph" || target?.type !== "paragraph" || !target.paraId) continue;
+			rows.push({
+				kind: classifyParagraph(source, styleById),
+				rowId: target.paraId,
+				sourceParaId: source.paraId,
+				targetParaId: target.paraId,
+				sourceText: getParagraphText(source)
+			});
+		}
+	}
+	return rows;
+}
+const isBilingualTable = (table) => {
+	let pairs = 0;
+	for (const row of table.rows) {
+		const cells = row.cells;
+		if (cells.length === 2) {
+			if (!cells.every((cell) => cell.content.length === 1 && cell.content[0]?.type === "paragraph")) return false;
+			pairs += 1;
+			continue;
+		}
+		if (cells.length === 1 && cells[0]?.formatting?.gridSpan === 2) continue;
+		return false;
+	}
+	return pairs > 0;
+};
+const isParagraphWithId = (value) => "type" in value && value.type === "paragraph" && "paraId" in value && typeof value.paraId === "string";
+//#endregion
+export { InvalidBilingualDocumentOptionsError, createBilingualDocument, readBilingualDocument };

package/dist/docx/server/createBilingualDocx.d.ts

@@ -0,0 +1,19 @@
+import { BilingualRow, CreateBilingualDocumentOptions } from "./createBilingualDocument.js";
+//#region src/docx/server/createBilingualDocx.d.ts
+type CreateBilingualDocxResult = {
+  buffer: ArrayBuffer;
+  rows: BilingualRow[];
+  warnings: string[];
+};
+/**
+ * Bytes-in / bytes-out form of {@link createBilingualDocument}: stamp every
+ * paragraph with a `paraId` (so left-column rows are addressable later), parse
+ * the DOCX (no font preloading, so it never touches the DOM), lay the body out
+ * as a two-column table, and repack onto the original package so theme, fonts,
+ * media, headers and footers carry over untouched.
+ */
+declare function createBilingualDocx(input: ArrayBuffer | Uint8Array, options: CreateBilingualDocumentOptions): Promise<CreateBilingualDocxResult>;
+/** Bytes-in form of {@link readBilingualDocument}. */
+declare function readBilingualDocx(input: ArrayBuffer | Uint8Array): Promise<BilingualRow[]>;
+//#endregion
+export { CreateBilingualDocxResult, createBilingualDocx, readBilingualDocx };

package/dist/docx/server/createBilingualDocx.js

@@ -0,0 +1,26 @@
+import { ensureParaIds } from "../ensureParaIds.js";
+import { parseDocx } from "../parser.js";
+import { createDocx } from "../rezip.js";
+import { createBilingualDocument, readBilingualDocument } from "./createBilingualDocument.js";
+//#region src/docx/server/createBilingualDocx.ts
+/**
+* Bytes-in / bytes-out form of {@link createBilingualDocument}: stamp every
+* paragraph with a `paraId` (so left-column rows are addressable later), parse
+* the DOCX (no font preloading, so it never touches the DOM), lay the body out
+* as a two-column table, and repack onto the original package so theme, fonts,
+* media, headers and footers carry over untouched.
+*/
+async function createBilingualDocx(input, options) {
+	const { document, rows, warnings } = createBilingualDocument(await parseDocx((await ensureParaIds(input)).docx, { preloadFonts: false }), options);
+	return {
+		buffer: await createDocx(document),
+		rows,
+		warnings
+	};
+}
+/** Bytes-in form of {@link readBilingualDocument}. */
+async function readBilingualDocx(input) {
+	return readBilingualDocument(await parseDocx(input, { preloadFonts: false }));
+}
+//#endregion
+export { createBilingualDocx, readBilingualDocx };

package/dist/server.d.ts

@@ -19,9 +19,11 @@ import { EvaluateDocxXmlPatchProposalArgs, FOLIO_DOCX_XML_PATCH_PROPOSAL_DEFAULT
 import { FOLIO_DOCX_CONFORMANCE_CHECKS, FOLIO_DOCX_CONFORMANCE_ISSUE_CODES, FOLIO_DOCX_CONFORMANCE_PROFILE, FOLIO_DOCX_CONFORMANCE_REPORT_VERSION, FolioDocxConformanceCheck, FolioDocxConformanceCheckId, FolioDocxConformanceCheckStatus, FolioDocxConformanceIssue, FolioDocxConformanceIssueCode, FolioDocxConformanceReport, FolioDocxConformanceStatus, ValidateDocxConformanceOptions, validateDocxConformance } from "./docx/server/validateDocxConformance.js";
 import { ApplyDocxXmlPatchProposalArgs, FOLIO_DOCX_XML_PATCH_APPLICATION_PROFILE, FOLIO_DOCX_XML_PATCH_APPLICATION_VERSION, FolioDocxXmlPatchApplication, FolioDocxXmlPatchApplicationError, FolioDocxXmlPatchApplicationReceipt, UnsupportedFolioDocxXmlPatchApplicationProfileError, applyDocxXmlPatchProposal } from "./docx/server/applyDocxXmlPatchProposal.js";
 import { HEADING_LEVELS, HeadingLevel, InvalidFolioReportBuilderOptionsError, TableCellSpec, bookmark, createTableOfContentsField, endnote, heading, hyperlink, pageBreak, paragraph, run, table } from "./docx/server/build.js";
+import { BilingualBorders, BilingualParagraphRef, BilingualRow, BilingualRowKind, BilingualTableParagraphRef, CreateBilingualDocumentOptions, CreateBilingualDocumentResult, InvalidBilingualDocumentOptionsError, createBilingualDocument, readBilingualDocument } from "./docx/server/createBilingualDocument.js";
+import { CreateBilingualDocxResult, createBilingualDocx, readBilingualDocx } from "./docx/server/createBilingualDocx.js";
 import { docxToMarkdown } from "./docx/server/docxToMarkdown.js";
 import { DocxParagraphSource, DocxTableRowKind, DocxTableRowPosition, ExtractedDocxParagraph, ExtractedDocxTableCell, ExtractedDocxTableCellParagraph, ExtractedDocxText, extractDocxText } from "./docx/server/extractDocxText.js";
 import { FOLIO_DOCX_PACKAGE_INSPECTION_DEFAULTS, FOLIO_DOCX_PACKAGE_INSPECTION_ERROR_CODES, FOLIO_DOCX_PACKAGE_INSPECTION_VERSION, FolioDocxInspectedXmlPart, FolioDocxPackageInspection, FolioDocxPackageInspectionError, FolioDocxPackageInspectionErrorCode, FolioDocxPackageInspectionLimits, FolioDocxPackagePart, FolioDocxPackagePartKind, InspectDocxPackageOptions, inspectDocxPackage } from "./docx/server/inspectDocxPackage.js";
 import { GenerateRedlineDocxOptions, GenerateRedlineDocxResult, GenerateRedlineUnprocessedStory, InvalidGenerateRedlineDocxOptionsError, generateRedlineDocx } from "./redline.js";
 import { FOLIO_VERSION_COMPARISON_PRIVACY_TRANSFORMS, FOLIO_VERSION_COMPARISON_SCOPES, FolioBlockDiff, FolioCompareDocxVersionsOptions, FolioDocumentMetadataValue, FolioFormatProperty, FolioMetadataDiff, FolioStoryDiff, FolioVersionBlockHandle, FolioVersionComparisonPrivacyTransform, FolioVersionComparisonScope, FolioVersionDiff, FolioVersionDiffPrivacyOptions, FolioVersionDiffPrivacyReport, FolioVersionDiffSegment, FolioVersionDiffSummaryCounts, InvalidFolioVersionComparisonOptionsError, applyFolioVersionDiffPrivacy, compareDocxVersions, isFolioVersionComparisonPrivacyTransform, isFolioVersionComparisonScope } from "./version-comparison.js";
-export { type ApplyDocxXmlPatchProposalArgs, type ApplyFolioAIEditsToBufferOptions, type ApplyFolioAIEditsToBufferResult, type CreateCommentReplyInput, type CreateEmptyDocumentOptions, DOCUMENT_PRESET_VERSION, DOCUMENT_STYLE_SET_VERSION, type DeriveBlockIdInput, type DocumentPreset, type DocumentStyleCatalog, type DocumentStyleCatalogEntry, type DocumentStyleSet, DocxArchiveError, type DocxArchiveOptions, type DocxParagraphSource, type DocxTableRowKind, type DocxTableRowPosition, EnsureParaIdsError, type EnsureParaIdsOptions, type EnsureParaIdsResult, type EvaluateDocxXmlPatchProposalArgs, type ExtractDocumentStyleSetOptions, type ExtractedDocxParagraph, type ExtractedDocxTableCell, type ExtractedDocxTableCellParagraph, type ExtractedDocxText, FOLIO_DOCUMENT_METADATA_PROPERTIES, FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, FOLIO_DOCUMENT_PRIVACY_TRANSFORMS, FOLIO_DOCX_CONFORMANCE_CHECKS, FOLIO_DOCX_CONFORMANCE_ISSUE_CODES, FOLIO_DOCX_CONFORMANCE_PROFILE, FOLIO_DOCX_CONFORMANCE_REPORT_VERSION, FOLIO_DOCX_PACKAGE_INSPECTION_DEFAULTS, FOLIO_DOCX_PACKAGE_INSPECTION_ERROR_CODES, FOLIO_DOCX_PACKAGE_INSPECTION_VERSION, FOLIO_DOCX_XML_PATCH_APPLICATION_PROFILE, FOLIO_DOCX_XML_PATCH_APPLICATION_VERSION, FOLIO_DOCX_XML_PATCH_PROPOSAL_DEFAULTS, FOLIO_DOCX_XML_PATCH_PROPOSAL_ISSUE_CODES, FOLIO_DOCX_XML_PATCH_PROPOSAL_PROFILE, FOLIO_DOCX_XML_PATCH_PROPOSAL_VERSION, FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, FOLIO_VERSION_COMPARISON_PRIVACY_TRANSFORMS, FOLIO_VERSION_COMPARISON_SCOPES, type FolioAIBlock, type FolioAIBlockAnchor, type FolioAIBlockKind, type FolioAIBlockPreviewRun, type FolioAIComment, type FolioAIEditApplyMode, type FolioAIEditApplyResult, type FolioAIEditOperation, type FolioAIEditPrecondition, type FolioAIEditSnapshot, type FolioAIInlineFormatting, type FolioAITextRangeHandle, type FolioApplyDocumentOperationsOptions, type FolioApplyDocumentOperationsToStoryOptions, type FolioApplyOperationsOptions, type FolioBlockDiff, type FolioBlockId, type FolioCompareDocxVersionsOptions, type FolioDocumentMetadataProperty, type FolioDocumentMetadataValue, type FolioDocumentNavigationTarget, type FolioDocumentOperation, type FolioDocumentOperationAffectedTarget, type FolioDocumentOperationBatch, type FolioDocumentOperationCapabilities, type FolioDocumentOperationIssue, type FolioDocumentOperationMode, type FolioDocumentOperationPrecondition, type FolioDocumentOperationReceipt, type FolioDocumentOperationRecovery, type FolioDocumentOperationResult, type FolioDocumentOperationStatus, type FolioDocumentOperationStory, type FolioDocumentOperationType, type FolioDocumentOperationUndoFailureReason, type FolioDocumentOperationUndoHandle, type FolioDocumentOperationUndoResult, type FolioDocumentOutline, type FolioDocumentOutlineEntry, FolioDocumentPrivacyArchiveError, type FolioDocumentPrivacyOptions, type FolioDocumentPrivacyReport, type FolioDocumentPrivacyTransform, type FolioDocumentSection, type FolioDocumentSectionHandle, type FolioDocumentSectionReadResult, type FolioDocumentStory, type FolioDocumentStoryHandle, FolioDocumentStoryNotFoundError, type FolioDocxConformanceCheck, type FolioDocxConformanceCheckId, type FolioDocxConformanceCheckStatus, type FolioDocxConformanceIssue, type FolioDocxConformanceIssueCode, type FolioDocxConformanceReport, type FolioDocxConformanceStatus, type FolioDocxInspectedXmlPart, type FolioDocxPackageInspection, FolioDocxPackageInspectionError, type FolioDocxPackageInspectionErrorCode, type FolioDocxPackageInspectionLimits, type FolioDocxPackagePart, type FolioDocxPackagePartKind, type FolioDocxPreparedXmlReplacement, FolioDocxReviewer, type FolioDocxReviewerOptions, type FolioDocxXmlPatchApplication, FolioDocxXmlPatchApplicationError, type FolioDocxXmlPatchApplicationReceipt, type FolioDocxXmlPatchProposal, type FolioDocxXmlPatchProposalEvaluation, type FolioDocxXmlPatchProposalIssue, type FolioDocxXmlPatchProposalIssueCode, type FolioDocxXmlPatchProposalLimits, type FolioDocxXmlReplacement, type FolioEditableDocumentStoryHandle, type FolioFormatProperty, type FolioMetadataDiff, type FolioReadReviewedStoryOptions, type FolioResolveReviewedStoryOptions, type FolioResolvedReviewedView, type FolioReviewChange, type FolioReviewChangeFilter, type FolioReviewChangeKind, type FolioReviewComment, type FolioReviewCommentFilter, type FolioReviewCommentReply, type FolioReviewReplyInput, type FolioReviewedStory, type FolioReviewedView, type FolioStoryDiff, type FolioVersionBlockHandle, type FolioVersionComparisonPrivacyTransform, type FolioVersionComparisonScope, type FolioVersionDiff, type FolioVersionDiffPrivacyOptions, type FolioVersionDiffPrivacyReport, type FolioVersionDiffSegment, type FolioVersionDiffSummaryCounts, type GenerateRedlineDocxOptions, type GenerateRedlineDocxResult, type GenerateRedlineUnprocessedStory, HEADING_LEVELS, type HeadingLevel, type InspectDocxPackageOptions, InvalidFolioDocumentOperationBatchError, InvalidFolioDocumentPrivacyOptionsError, InvalidFolioDocxXmlPatchProposalError, InvalidFolioDocxXmlPatchProposalOptionsError, InvalidFolioReportBuilderOptionsError, InvalidFolioVersionComparisonOptionsError, InvalidGenerateRedlineDocxOptionsError, type ParseOptions, type RewriteDocxMetadataPrivacyResult, STELLA_STYLE_SET_NAME, type TableCellSpec, UnsupportedFolioDocumentOperationVersionError, UnsupportedFolioDocxXmlPatchApplicationProfileError, UnsupportedFolioReviewedViewError, type ValidateDocxConformanceOptions, applyDocxXmlPatchProposal, applyFolioAIEditsToBuffer, applyFolioVersionDiffPrivacy, assertSupportedFolioDocumentOperationVersion, bookmark, compareDocxVersions, createDocx, createEmptyDocument, createFolioAITextRangeHandle, createStellaStyleDocumentPreset, createStellaStyleSet, createTableOfContentsField, deriveBlockId, docxToMarkdown, endnote, ensureParaIds, evaluateDocxXmlPatchProposal, extractDocumentStyleSet, extractDocumentStyleSetFromDocx, extractDocxText, generateRedlineDocx, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioDocumentOutline, getFolioParaIdFromBlockId, hashFolioAIBlockText, heading, hyperlink, inspectDocumentStyles, inspectDocumentStylesFromDocx, inspectDocxPackage, isFolioBlockId, isFolioDocumentOperationModeSupported, isFolioDocumentPrivacyTransform, isFolioResolvedReviewedView, isFolioReviewedView, isFolioVersionComparisonPrivacyTransform, isFolioVersionComparisonScope, isSequentialFolioBlockId, isSupportedFolioDocumentOperationVersion, normalizeFolioAIBlockText, pageBreak, paragraph, parseDocx, parseFolioDocumentOperationBatch, parseFolioDocxXmlPatchProposal, readFolioDocumentSection, replyToComment, rewriteDocxMetadataPrivacy, run, table, validateDocxConformance };
+export { type ApplyDocxXmlPatchProposalArgs, type ApplyFolioAIEditsToBufferOptions, type ApplyFolioAIEditsToBufferResult, type BilingualBorders, type BilingualParagraphRef, type BilingualRow, type BilingualRowKind, type BilingualTableParagraphRef, type CreateBilingualDocumentOptions, type CreateBilingualDocumentResult, type CreateBilingualDocxResult, type CreateCommentReplyInput, type CreateEmptyDocumentOptions, DOCUMENT_PRESET_VERSION, DOCUMENT_STYLE_SET_VERSION, type DeriveBlockIdInput, type DocumentPreset, type DocumentStyleCatalog, type DocumentStyleCatalogEntry, type DocumentStyleSet, DocxArchiveError, type DocxArchiveOptions, type DocxParagraphSource, type DocxTableRowKind, type DocxTableRowPosition, EnsureParaIdsError, type EnsureParaIdsOptions, type EnsureParaIdsResult, type EvaluateDocxXmlPatchProposalArgs, type ExtractDocumentStyleSetOptions, type ExtractedDocxParagraph, type ExtractedDocxTableCell, type ExtractedDocxTableCellParagraph, type ExtractedDocxText, FOLIO_DOCUMENT_METADATA_PROPERTIES, FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, FOLIO_DOCUMENT_PRIVACY_TRANSFORMS, FOLIO_DOCX_CONFORMANCE_CHECKS, FOLIO_DOCX_CONFORMANCE_ISSUE_CODES, FOLIO_DOCX_CONFORMANCE_PROFILE, FOLIO_DOCX_CONFORMANCE_REPORT_VERSION, FOLIO_DOCX_PACKAGE_INSPECTION_DEFAULTS, FOLIO_DOCX_PACKAGE_INSPECTION_ERROR_CODES, FOLIO_DOCX_PACKAGE_INSPECTION_VERSION, FOLIO_DOCX_XML_PATCH_APPLICATION_PROFILE, FOLIO_DOCX_XML_PATCH_APPLICATION_VERSION, FOLIO_DOCX_XML_PATCH_PROPOSAL_DEFAULTS, FOLIO_DOCX_XML_PATCH_PROPOSAL_ISSUE_CODES, FOLIO_DOCX_XML_PATCH_PROPOSAL_PROFILE, FOLIO_DOCX_XML_PATCH_PROPOSAL_VERSION, FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, FOLIO_VERSION_COMPARISON_PRIVACY_TRANSFORMS, FOLIO_VERSION_COMPARISON_SCOPES, type FolioAIBlock, type FolioAIBlockAnchor, type FolioAIBlockKind, type FolioAIBlockPreviewRun, type FolioAIComment, type FolioAIEditApplyMode, type FolioAIEditApplyResult, type FolioAIEditOperation, type FolioAIEditPrecondition, type FolioAIEditSnapshot, type FolioAIInlineFormatting, type FolioAITextRangeHandle, type FolioApplyDocumentOperationsOptions, type FolioApplyDocumentOperationsToStoryOptions, type FolioApplyOperationsOptions, type FolioBlockDiff, type FolioBlockId, type FolioCompareDocxVersionsOptions, type FolioDocumentMetadataProperty, type FolioDocumentMetadataValue, type FolioDocumentNavigationTarget, type FolioDocumentOperation, type FolioDocumentOperationAffectedTarget, type FolioDocumentOperationBatch, type FolioDocumentOperationCapabilities, type FolioDocumentOperationIssue, type FolioDocumentOperationMode, type FolioDocumentOperationPrecondition, type FolioDocumentOperationReceipt, type FolioDocumentOperationRecovery, type FolioDocumentOperationResult, type FolioDocumentOperationStatus, type FolioDocumentOperationStory, type FolioDocumentOperationType, type FolioDocumentOperationUndoFailureReason, type FolioDocumentOperationUndoHandle, type FolioDocumentOperationUndoResult, type FolioDocumentOutline, type FolioDocumentOutlineEntry, FolioDocumentPrivacyArchiveError, type FolioDocumentPrivacyOptions, type FolioDocumentPrivacyReport, type FolioDocumentPrivacyTransform, type FolioDocumentSection, type FolioDocumentSectionHandle, type FolioDocumentSectionReadResult, type FolioDocumentStory, type FolioDocumentStoryHandle, FolioDocumentStoryNotFoundError, type FolioDocxConformanceCheck, type FolioDocxConformanceCheckId, type FolioDocxConformanceCheckStatus, type FolioDocxConformanceIssue, type FolioDocxConformanceIssueCode, type FolioDocxConformanceReport, type FolioDocxConformanceStatus, type FolioDocxInspectedXmlPart, type FolioDocxPackageInspection, FolioDocxPackageInspectionError, type FolioDocxPackageInspectionErrorCode, type FolioDocxPackageInspectionLimits, type FolioDocxPackagePart, type FolioDocxPackagePartKind, type FolioDocxPreparedXmlReplacement, FolioDocxReviewer, type FolioDocxReviewerOptions, type FolioDocxXmlPatchApplication, FolioDocxXmlPatchApplicationError, type FolioDocxXmlPatchApplicationReceipt, type FolioDocxXmlPatchProposal, type FolioDocxXmlPatchProposalEvaluation, type FolioDocxXmlPatchProposalIssue, type FolioDocxXmlPatchProposalIssueCode, type FolioDocxXmlPatchProposalLimits, type FolioDocxXmlReplacement, type FolioEditableDocumentStoryHandle, type FolioFormatProperty, type FolioMetadataDiff, type FolioReadReviewedStoryOptions, type FolioResolveReviewedStoryOptions, type FolioResolvedReviewedView, type FolioReviewChange, type FolioReviewChangeFilter, type FolioReviewChangeKind, type FolioReviewComment, type FolioReviewCommentFilter, type FolioReviewCommentReply, type FolioReviewReplyInput, type FolioReviewedStory, type FolioReviewedView, type FolioStoryDiff, type FolioVersionBlockHandle, type FolioVersionComparisonPrivacyTransform, type FolioVersionComparisonScope, type FolioVersionDiff, type FolioVersionDiffPrivacyOptions, type FolioVersionDiffPrivacyReport, type FolioVersionDiffSegment, type FolioVersionDiffSummaryCounts, type GenerateRedlineDocxOptions, type GenerateRedlineDocxResult, type GenerateRedlineUnprocessedStory, HEADING_LEVELS, type HeadingLevel, type InspectDocxPackageOptions, InvalidBilingualDocumentOptionsError, InvalidFolioDocumentOperationBatchError, InvalidFolioDocumentPrivacyOptionsError, InvalidFolioDocxXmlPatchProposalError, InvalidFolioDocxXmlPatchProposalOptionsError, InvalidFolioReportBuilderOptionsError, InvalidFolioVersionComparisonOptionsError, InvalidGenerateRedlineDocxOptionsError, type ParseOptions, type RewriteDocxMetadataPrivacyResult, STELLA_STYLE_SET_NAME, type TableCellSpec, UnsupportedFolioDocumentOperationVersionError, UnsupportedFolioDocxXmlPatchApplicationProfileError, UnsupportedFolioReviewedViewError, type ValidateDocxConformanceOptions, applyDocxXmlPatchProposal, applyFolioAIEditsToBuffer, applyFolioVersionDiffPrivacy, assertSupportedFolioDocumentOperationVersion, bookmark, compareDocxVersions, createBilingualDocument, createBilingualDocx, createDocx, createEmptyDocument, createFolioAITextRangeHandle, createStellaStyleDocumentPreset, createStellaStyleSet, createTableOfContentsField, deriveBlockId, docxToMarkdown, endnote, ensureParaIds, evaluateDocxXmlPatchProposal, extractDocumentStyleSet, extractDocumentStyleSetFromDocx, extractDocxText, generateRedlineDocx, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioDocumentOutline, getFolioParaIdFromBlockId, hashFolioAIBlockText, heading, hyperlink, inspectDocumentStyles, inspectDocumentStylesFromDocx, inspectDocxPackage, isFolioBlockId, isFolioDocumentOperationModeSupported, isFolioDocumentPrivacyTransform, isFolioResolvedReviewedView, isFolioReviewedView, isFolioVersionComparisonPrivacyTransform, isFolioVersionComparisonScope, isSequentialFolioBlockId, isSupportedFolioDocumentOperationVersion, normalizeFolioAIBlockText, pageBreak, paragraph, parseDocx, parseFolioDocumentOperationBatch, parseFolioDocxXmlPatchProposal, readBilingualDocument, readBilingualDocx, readFolioDocumentSection, replyToComment, rewriteDocxMetadataPrivacy, run, table, validateDocxConformance };

package/dist/server.js

@@ -10,6 +10,8 @@ import { createDocx } from "./docx/rezip.js";
 import { FOLIO_DOCX_XML_PATCH_APPLICATION_PROFILE, FOLIO_DOCX_XML_PATCH_APPLICATION_VERSION, FolioDocxXmlPatchApplicationError, UnsupportedFolioDocxXmlPatchApplicationProfileError, applyDocxXmlPatchProposal } from "./docx/server/applyDocxXmlPatchProposal.js";
 import { DocxArchiveError } from "./docx/server/boundedArchive.js";
 import { HEADING_LEVELS, InvalidFolioReportBuilderOptionsError, bookmark, createTableOfContentsField, endnote, heading, hyperlink, pageBreak, paragraph, run, table } from "./docx/server/build.js";
+import { InvalidBilingualDocumentOptionsError, createBilingualDocument, readBilingualDocument } from "./docx/server/createBilingualDocument.js";
+import { createBilingualDocx, readBilingualDocx } from "./docx/server/createBilingualDocx.js";
 import { docxToMarkdown } from "./docx/server/docxToMarkdown.js";
 import { FOLIO_DOCX_XML_PATCH_PROPOSAL_DEFAULTS, FOLIO_DOCX_XML_PATCH_PROPOSAL_ISSUE_CODES, FOLIO_DOCX_XML_PATCH_PROPOSAL_PROFILE, FOLIO_DOCX_XML_PATCH_PROPOSAL_VERSION, InvalidFolioDocxXmlPatchProposalError, InvalidFolioDocxXmlPatchProposalOptionsError, evaluateDocxXmlPatchProposal, parseFolioDocxXmlPatchProposal } from "./docx/server/evaluateDocxXmlPatchProposal.js";
 import { extractDocxText } from "./docx/server/extractDocxText.js";
@@ -22,4 +24,4 @@ import { DOCUMENT_PRESET_VERSION, DOCUMENT_STYLE_SET_VERSION } from "./style-set
 import { deriveBlockId, getFolioParaIdFromBlockId, isFolioBlockId, isSequentialFolioBlockId } from "./types/block-id.js";
 import { createEmptyDocument } from "./utils/createDocument.js";
 import { FOLIO_VERSION_COMPARISON_PRIVACY_TRANSFORMS, FOLIO_VERSION_COMPARISON_SCOPES, InvalidFolioVersionComparisonOptionsError, applyFolioVersionDiffPrivacy, compareDocxVersions, isFolioVersionComparisonPrivacyTransform, isFolioVersionComparisonScope } from "./version-comparison.js";
-export { DOCUMENT_PRESET_VERSION, DOCUMENT_STYLE_SET_VERSION, DocxArchiveError, EnsureParaIdsError, FOLIO_DOCUMENT_METADATA_PROPERTIES, FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, FOLIO_DOCUMENT_PRIVACY_TRANSFORMS, FOLIO_DOCX_CONFORMANCE_CHECKS, FOLIO_DOCX_CONFORMANCE_ISSUE_CODES, FOLIO_DOCX_CONFORMANCE_PROFILE, FOLIO_DOCX_CONFORMANCE_REPORT_VERSION, FOLIO_DOCX_PACKAGE_INSPECTION_DEFAULTS, FOLIO_DOCX_PACKAGE_INSPECTION_ERROR_CODES, FOLIO_DOCX_PACKAGE_INSPECTION_VERSION, FOLIO_DOCX_XML_PATCH_APPLICATION_PROFILE, FOLIO_DOCX_XML_PATCH_APPLICATION_VERSION, FOLIO_DOCX_XML_PATCH_PROPOSAL_DEFAULTS, FOLIO_DOCX_XML_PATCH_PROPOSAL_ISSUE_CODES, FOLIO_DOCX_XML_PATCH_PROPOSAL_PROFILE, FOLIO_DOCX_XML_PATCH_PROPOSAL_VERSION, FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, FOLIO_VERSION_COMPARISON_PRIVACY_TRANSFORMS, FOLIO_VERSION_COMPARISON_SCOPES, FolioDocumentPrivacyArchiveError, FolioDocumentStoryNotFoundError, FolioDocxPackageInspectionError, FolioDocxReviewer, FolioDocxXmlPatchApplicationError, HEADING_LEVELS, InvalidFolioDocumentOperationBatchError, InvalidFolioDocumentPrivacyOptionsError, InvalidFolioDocxXmlPatchProposalError, InvalidFolioDocxXmlPatchProposalOptionsError, InvalidFolioReportBuilderOptionsError, InvalidFolioVersionComparisonOptionsError, InvalidGenerateRedlineDocxOptionsError, STELLA_STYLE_SET_NAME, UnsupportedFolioDocumentOperationVersionError, UnsupportedFolioDocxXmlPatchApplicationProfileError, UnsupportedFolioReviewedViewError, applyDocxXmlPatchProposal, applyFolioAIEditsToBuffer, applyFolioVersionDiffPrivacy, assertSupportedFolioDocumentOperationVersion, bookmark, compareDocxVersions, createDocx, createEmptyDocument, createFolioAITextRangeHandle, createStellaStyleDocumentPreset, createStellaStyleSet, createTableOfContentsField, deriveBlockId, docxToMarkdown, endnote, ensureParaIds, evaluateDocxXmlPatchProposal, extractDocumentStyleSet, extractDocumentStyleSetFromDocx, extractDocxText, generateRedlineDocx, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioDocumentOutline, getFolioParaIdFromBlockId, hashFolioAIBlockText, heading, hyperlink, inspectDocumentStyles, inspectDocumentStylesFromDocx, inspectDocxPackage, isFolioBlockId, isFolioDocumentOperationModeSupported, isFolioDocumentPrivacyTransform, isFolioResolvedReviewedView, isFolioReviewedView, isFolioVersionComparisonPrivacyTransform, isFolioVersionComparisonScope, isSequentialFolioBlockId, isSupportedFolioDocumentOperationVersion, normalizeFolioAIBlockText, pageBreak, paragraph, parseDocx, parseFolioDocumentOperationBatch, parseFolioDocxXmlPatchProposal, readFolioDocumentSection, replyToComment, rewriteDocxMetadataPrivacy, run, table, validateDocxConformance };
+export { DOCUMENT_PRESET_VERSION, DOCUMENT_STYLE_SET_VERSION, DocxArchiveError, EnsureParaIdsError, FOLIO_DOCUMENT_METADATA_PROPERTIES, FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, FOLIO_DOCUMENT_PRIVACY_TRANSFORMS, FOLIO_DOCX_CONFORMANCE_CHECKS, FOLIO_DOCX_CONFORMANCE_ISSUE_CODES, FOLIO_DOCX_CONFORMANCE_PROFILE, FOLIO_DOCX_CONFORMANCE_REPORT_VERSION, FOLIO_DOCX_PACKAGE_INSPECTION_DEFAULTS, FOLIO_DOCX_PACKAGE_INSPECTION_ERROR_CODES, FOLIO_DOCX_PACKAGE_INSPECTION_VERSION, FOLIO_DOCX_XML_PATCH_APPLICATION_PROFILE, FOLIO_DOCX_XML_PATCH_APPLICATION_VERSION, FOLIO_DOCX_XML_PATCH_PROPOSAL_DEFAULTS, FOLIO_DOCX_XML_PATCH_PROPOSAL_ISSUE_CODES, FOLIO_DOCX_XML_PATCH_PROPOSAL_PROFILE, FOLIO_DOCX_XML_PATCH_PROPOSAL_VERSION, FOLIO_RESOLVED_REVIEWED_VIEWS, FOLIO_REVIEWED_VIEWS, FOLIO_VERSION_COMPARISON_PRIVACY_TRANSFORMS, FOLIO_VERSION_COMPARISON_SCOPES, FolioDocumentPrivacyArchiveError, FolioDocumentStoryNotFoundError, FolioDocxPackageInspectionError, FolioDocxReviewer, FolioDocxXmlPatchApplicationError, HEADING_LEVELS, InvalidBilingualDocumentOptionsError, InvalidFolioDocumentOperationBatchError, InvalidFolioDocumentPrivacyOptionsError, InvalidFolioDocxXmlPatchProposalError, InvalidFolioDocxXmlPatchProposalOptionsError, InvalidFolioReportBuilderOptionsError, InvalidFolioVersionComparisonOptionsError, InvalidGenerateRedlineDocxOptionsError, STELLA_STYLE_SET_NAME, UnsupportedFolioDocumentOperationVersionError, UnsupportedFolioDocxXmlPatchApplicationProfileError, UnsupportedFolioReviewedViewError, applyDocxXmlPatchProposal, applyFolioAIEditsToBuffer, applyFolioVersionDiffPrivacy, assertSupportedFolioDocumentOperationVersion, bookmark, compareDocxVersions, createBilingualDocument, createBilingualDocx, createDocx, createEmptyDocument, createFolioAITextRangeHandle, createStellaStyleDocumentPreset, createStellaStyleSet, createTableOfContentsField, deriveBlockId, docxToMarkdown, endnote, ensureParaIds, evaluateDocxXmlPatchProposal, extractDocumentStyleSet, extractDocumentStyleSetFromDocx, extractDocxText, generateRedlineDocx, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioDocumentOutline, getFolioParaIdFromBlockId, hashFolioAIBlockText, heading, hyperlink, inspectDocumentStyles, inspectDocumentStylesFromDocx, inspectDocxPackage, isFolioBlockId, isFolioDocumentOperationModeSupported, isFolioDocumentPrivacyTransform, isFolioResolvedReviewedView, isFolioReviewedView, isFolioVersionComparisonPrivacyTransform, isFolioVersionComparisonScope, isSequentialFolioBlockId, isSupportedFolioDocumentOperationVersion, normalizeFolioAIBlockText, pageBreak, paragraph, parseDocx, parseFolioDocumentOperationBatch, parseFolioDocxXmlPatchProposal, readBilingualDocument, readBilingualDocx, readFolioDocumentSection, replyToComment, rewriteDocxMetadataPrivacy, run, table, validateDocxConformance };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stll/folio-core",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Headless, framework-neutral core of folio: the OOXML (.docx) parser, document model, ProseMirror integration, and page-layout engine. No React.",
   "keywords": [
     "document-model",