@cj-tech-master/excelts 9.6.1 → 10.0.0

package/dist/browser/modules/word/advanced/math-convert.js

@@ -79,20 +79,98 @@ function convertNodeToMathML(node) {
     }
 }
 function convertMathRunToMathML(node) {
-    const text = xmlEncode(node.text);
-    // Operators and special characters
-    if (isOperator(node.text)) {
-        return `<mo>${text}</mo>`;
+    const raw = node.text;
+    // A single OMML run can hold a mix of letters, digits, operators and
+    // whitespace (e.g. "a + b = "). MathML presentation markup expects each
+    // token to be wrapped in the element matching its semantic category:
+    // <mi> for identifiers, <mn> for numbers, <mo> for operators and <mtext>
+    // for runs of whitespace / other text. Tokenize the run and emit one
+    // element per token so a mixed run is no longer flattened into a single
+    // (incorrect) <mi>.
+    const normalVariant = node.properties?.italic === false;
+    const tokens = tokenizeMathRun(raw);
+    // Fast path / backwards-compatibility: a run that is a single token keeps
+    // producing exactly one element (e.g. "x" -> <mi>x</mi>, "42" -> <mn>42</mn>,
+    // "+" -> <mo>+</mo>), matching the historical output.
+    return tokens.map(tok => emitMathToken(tok, normalVariant)).join("");
+}
+function classifyMathChar(ch) {
+    if (/\s/.test(ch)) {
+        return "text";
+    }
+    if (isOperator(ch)) {
+        return "operator";
+    }
+    if (/[0-9.]/.test(ch)) {
+        return "number";
+    }
+    if (/[A-Za-z]/.test(ch)) {
+        return "identifier";
+    }
+    // Letters outside ASCII (Greek, CJK, etc.) and any other symbol fall back to
+    // identifier — this matches how OMML treats variable names.
+    return "identifier";
+}
+function tokenizeMathRun(text) {
+    const tokens = [];
+    // Use code points so astral / combined characters are not split mid-symbol.
+    const chars = Array.from(text);
+    for (const ch of chars) {
+        const kind = classifyMathChar(ch);
+        const last = tokens[tokens.length - 1];
+        // Operators are always emitted as their own token (each operator is a
+        // distinct <mo>). Numbers, identifiers and text coalesce with the
+        // previous token of the same kind so "42" stays a single <mn> and a run
+        // of spaces stays a single <mtext>.
+        if (last && last.kind === kind && kind !== "operator") {
+            last.value += ch;
+        }
+        else {
+            tokens.push({ kind, value: ch });
+        }
     }
-    // Numbers
-    if (/^\d+(\.\d+)?$/.test(node.text)) {
-        return `<mn>${text}</mn>`;
+    return mergeDecimalPoints(tokens);
+}
+/**
+ * A "." between two digit groups is a decimal point, not an operator. The
+ * char classifier sees "." as an operator (it is a valid math operator on its
+ * own, e.g. function composition), so stitch `<number> "." <number>` back into
+ * a single number token here.
+ */
+function mergeDecimalPoints(tokens) {
+    const out = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const tok = tokens[i];
+        const prev = out[out.length - 1];
+        const next = tokens[i + 1];
+        if (tok.kind === "operator" &&
+            tok.value === "." &&
+            prev &&
+            prev.kind === "number" &&
+            next &&
+            next.kind === "number") {
+            prev.value += "." + next.value;
+            i++; // consume the following number token
+            continue;
+        }
+        out.push(tok);
     }
-    // Identifiers
-    if (node.properties?.italic === false) {
-        return `<mi mathvariant="normal">${text}</mi>`;
+    return out;
+}
+function emitMathToken(tok, normalVariant) {
+    const text = xmlEncode(tok.value);
+    switch (tok.kind) {
+        case "operator":
+            return `<mo>${text}</mo>`;
+        case "number":
+            // A lone "." is not a number; treat it as an operator/text fallback.
+            return /\d/.test(tok.value) ? `<mn>${text}</mn>` : `<mo>${text}</mo>`;
+        case "text":
+            return `<mtext>${text}</mtext>`;
+        case "identifier":
+        default:
+            return normalVariant ? `<mi mathvariant="normal">${text}</mi>` : `<mi>${text}</mi>`;
     }
-    return `<mi>${text}</mi>`;
 }
 function convertFractionToMathML(node) {
     const num = childrenToMathML(node.numerator);
@@ -254,7 +332,11 @@ function convertMMLElement(el) {
         }
         case "msqrt": {
             const content = convertMMLChildren(el.children);
-            return { type: "mathRadical", content };
+            // A bare square root has no degree. OOXML still emits an (empty)
+            // <m:deg/>, so we must set hideDegree → <m:degHide m:val="1"/>;
+            // otherwise Word treats the empty degree as visible and draws an empty
+            // degree box (a small square) at the radical's upper-left.
+            return { type: "mathRadical", content, hideDegree: true };
         }
         case "mroot": {
             const children = getElementChildren(el);

package/dist/browser/modules/word/advanced/ole-objects.d.ts

@@ -81,6 +81,8 @@ export interface OleEmbeddingResult {
     readonly olePart: OpaquePart;
     /** Suggested rId to use for the OLE binary in the document model. */
     readonly oleRId: string;
+    /** OLE ProgId the embedding was created with (e.g. "Excel.Sheet.12"). */
+    readonly progId: string;
     /** Preview image media part (only when `options.previewImage` was supplied). */
     readonly previewPart?: OpaquePart;
     /** Suggested rId for the preview image. */
@@ -113,3 +115,29 @@ export declare function createOleEmbedding(data: Uint8Array, progId: string, opt
     /** Override preview file name. Defaults to `image<N>.<ext>` from previewContentType. */
     previewFileName?: string;
 }): OleEmbeddingResult;
+/**
+ * Wire an {@link OleEmbeddingResult} into a document so the OLE object is
+ * actually rendered and resolvable, returning a new {@link DocxDocument}.
+ *
+ * Unlike just stuffing the part into `opaqueParts` (which leaves the binary
+ * dangling — no relationship, no body reference), this:
+ *
+ *  - registers the OLE binary (and optional preview) on
+ *    `doc.oleObjects` so the packager emits a `word/_rels/document.xml.rels`
+ *    relationship with the exact rId and a `[Content_Types].xml` override;
+ *  - appends a body paragraph carrying a `<w:object>` / `<o:OLEObject>`
+ *    that references the same rId and embeds the ProgId, so the object is
+ *    visible in Word and round-trips through `readDocx`.
+ *
+ * @param doc - The document to add the OLE object to.
+ * @param embedding - Result from {@link createOleEmbedding}.
+ * @param options - Display geometry (defaults to a 2"×2" icon box).
+ */
+export declare function addOleObject(doc: DocxDocument, embedding: OleEmbeddingResult, options?: {
+    /** Display width in points (default 96 = 2 inches at 48pt/in icon). */
+    widthPt?: number;
+    /** Display height in points (default 96). */
+    heightPt?: number;
+    /** Display mode. Default "icon". */
+    displayAs?: OleDisplayAs;
+}): DocxDocument;

package/dist/browser/modules/word/advanced/ole-objects.js

@@ -13,6 +13,8 @@
  * This module focuses on preservation (round-trip) and metadata extraction,
  * not full OLE compound document manipulation.
  */
+import { xmlEncodeAttr } from "../../xml/encode.js";
+import { ContentType } from "../constants.js";
 import { getFileName } from "../core/opc-paths.js";
 // =============================================================================
 // OLE Object Extraction
@@ -28,14 +30,33 @@ import { getFileName } from "../core/opc-paths.js";
 export function extractOleObjects(doc) {
     const objects = [];
     const summary = {};
-    // Scan opaque parts for OLE embeddings
+    const pushObject = (obj) => {
+        objects.push(obj);
+        summary[obj.progId] = (summary[obj.progId] ?? 0) + 1;
+    };
+    // Structured OLE objects wired on document.xml.rels (preferred form —
+    // these carry the real rId and, when available, the round-tripped progId).
+    if (doc.oleObjects) {
+        for (const ole of doc.oleObjects) {
+            pushObject({
+                rId: ole.rId,
+                progId: ole.progId ?? detectProgIdFromData(ole.data),
+                objectType: "embedded",
+                displayAs: "icon",
+                imageRId: ole.previewRId,
+                fileName: getFileName(ole.path),
+                data: ole.data
+            });
+        }
+    }
+    // Scan opaque parts for OLE embeddings (legacy / hand-built documents that
+    // did not go through the structured oleObjects channel).
     if (doc.opaqueParts) {
         for (const part of doc.opaqueParts) {
             if (isOleEmbedding(part.path)) {
                 const obj = parseOlePartMetadata(part);
                 if (obj) {
-                    objects.push(obj);
-                    summary[obj.progId] = (summary[obj.progId] ?? 0) + 1;
+                    pushObject(obj);
                 }
             }
         }
@@ -45,11 +66,10 @@ export function extractOleObjects(doc) {
         if (element.type === "opaqueDrawing") {
             const oleFromDrawing = extractOleFromRawXml(element.rawXml);
             if (oleFromDrawing) {
-                // Check if we already have this object from opaque parts
-                const exists = objects.some(o => o.rId === oleFromDrawing.rId);
+                // Check if we already have this object (by rId)
+                const exists = objects.some(o => o.rId === oleFromDrawing.rId && o.rId !== "");
                 if (!exists) {
-                    objects.push(oleFromDrawing);
-                    summary[oleFromDrawing.progId] = (summary[oleFromDrawing.progId] ?? 0) + 1;
+                    pushObject(oleFromDrawing);
                 }
             }
         }
@@ -60,6 +80,9 @@ export function extractOleObjects(doc) {
  * Check if a document contains any OLE embedded objects.
  */
 export function hasOleObjects(doc) {
+    if (doc.oleObjects && doc.oleObjects.length > 0) {
+        return true;
+    }
     if (doc.opaqueParts) {
         for (const part of doc.opaqueParts) {
             if (isOleEmbedding(part.path)) {
@@ -74,6 +97,14 @@ export function hasOleObjects(doc) {
  * Returns undefined if not found.
  */
 export function getOleObjectData(doc, rId) {
+    // Structured OLE objects carry the exact rId used on document.xml.rels.
+    if (doc.oleObjects) {
+        for (const ole of doc.oleObjects) {
+            if (ole.rId === rId) {
+                return ole.data;
+            }
+        }
+    }
     if (!doc.opaqueParts) {
         return undefined;
     }
@@ -126,16 +157,14 @@ export function createOleEmbedding(data, progId, options) {
     const olePart = {
         path: `word/embeddings/${fileName}`,
         data,
-        contentType: "application/vnd.openxmlformats-officedocument.oleObject",
+        contentType: ContentType.OleObject,
         relationships: undefined
     };
     const oleRId = `rIdOle${oleSeq}`;
-    // progId is metadata for downstream consumers — not stored on
-    // OpaquePart but accepted in the signature so callers can pass it
-    // alongside without a separate channel. We don't need it here.
-    void progId;
+    // progId is carried back on the result so addOleObject() can persist it
+    // into the body `<o:OLEObject ProgID="…">` markup for round-trip.
     if (!options?.previewImage) {
-        return { olePart, oleRId };
+        return { olePart, oleRId, progId };
     }
     if (!options.previewContentType) {
         throw new Error("createOleEmbedding: options.previewImage requires options.previewContentType");
@@ -150,7 +179,78 @@ export function createOleEmbedding(data, progId, options) {
         relationships: undefined
     };
     const previewRId = `rIdOleImg${previewSeq}`;
-    return { olePart, oleRId, previewPart, previewRId };
+    return { olePart, oleRId, progId, previewPart, previewRId };
+}
+/**
+ * Wire an {@link OleEmbeddingResult} into a document so the OLE object is
+ * actually rendered and resolvable, returning a new {@link DocxDocument}.
+ *
+ * Unlike just stuffing the part into `opaqueParts` (which leaves the binary
+ * dangling — no relationship, no body reference), this:
+ *
+ *  - registers the OLE binary (and optional preview) on
+ *    `doc.oleObjects` so the packager emits a `word/_rels/document.xml.rels`
+ *    relationship with the exact rId and a `[Content_Types].xml` override;
+ *  - appends a body paragraph carrying a `<w:object>` / `<o:OLEObject>`
+ *    that references the same rId and embeds the ProgId, so the object is
+ *    visible in Word and round-trips through `readDocx`.
+ *
+ * @param doc - The document to add the OLE object to.
+ * @param embedding - Result from {@link createOleEmbedding}.
+ * @param options - Display geometry (defaults to a 2"×2" icon box).
+ */
+export function addOleObject(doc, embedding, options) {
+    const widthPt = options?.widthPt ?? 96;
+    const heightPt = options?.heightPt ?? 96;
+    const drawAspect = (options?.displayAs ?? "icon") === "icon" ? "Icon" : "Content";
+    const olePartEntry = {
+        path: embedding.olePart.path,
+        data: embedding.olePart.data,
+        rId: embedding.oleRId,
+        progId: embedding.progId,
+        contentType: embedding.olePart.contentType,
+        ...(embedding.previewPart && embedding.previewRId
+            ? {
+                previewPath: embedding.previewPart.path,
+                previewData: embedding.previewPart.data,
+                previewRId: embedding.previewRId,
+                previewContentType: embedding.previewPart.contentType
+            }
+            : {})
+    };
+    // Build the VML-hosted <w:object>. The o:OLEObject carries ProgID + the
+    // r:id of the binary; the v:shape provides geometry and (when present) the
+    // preview image fill via v:imagedata. This is the canonical OOXML shape for
+    // an embedded OLE object (ECMA-376 §17.3.3.19 + VML).
+    const shapeId = `_ole_${embedding.oleRId}`;
+    const styleWidth = widthPt.toFixed(0);
+    const styleHeight = heightPt.toFixed(0);
+    const imageData = embedding.previewRId != null
+        ? `<v:imagedata r:id="${xmlEncodeAttr(embedding.previewRId)}" o:title=""/>`
+        : "";
+    const rawXml = `<w:object>` +
+        `<v:shape id="${xmlEncodeAttr(shapeId)}" type="#_x0000_t75" ` +
+        `style="width:${styleWidth}pt;height:${styleHeight}pt">` +
+        imageData +
+        `</v:shape>` +
+        `<o:OLEObject Type="Embed" ProgID="${xmlEncodeAttr(embedding.progId)}" ` +
+        `ShapeID="${xmlEncodeAttr(shapeId)}" DrawAspect="${drawAspect}" ` +
+        `r:id="${xmlEncodeAttr(embedding.oleRId)}"/>` +
+        `</w:object>`;
+    const referencedRIds = [embedding.oleRId];
+    if (embedding.previewRId != null) {
+        referencedRIds.push(embedding.previewRId);
+    }
+    const drawing = {
+        type: "opaqueDrawing",
+        rawXml,
+        referencedRIds
+    };
+    return {
+        ...doc,
+        body: [...doc.body, drawing],
+        oleObjects: [...(doc.oleObjects ?? []), olePartEntry]
+    };
 }
 /** Module-level counters used to allocate unique file names per call. */
 let _oleSeq = 0;
@@ -242,17 +342,20 @@ function tryDecodeAscii(data) {
     return str;
 }
 function extractOleFromRawXml(rawXml) {
-    // Parse OLE object info from raw XML using regex (lightweight)
-    const progIdMatch = rawXml.match(/ProgID="([^"]+)"/i) ?? rawXml.match(/progId="([^"]+)"/i);
-    const rIdMatch = rawXml.match(/r:id="([^"]+)"/i);
-    const typeMatch = rawXml.match(/Type="([^"]+)"/i);
+    // Pull metadata from the <o:OLEObject> element specifically, so a preview
+    // image's <v:imagedata r:id="…"> earlier in the markup is not mistaken for
+    // the OLE binary's relationship id.
+    const oleTag = rawXml.match(/<o:OLEObject\b[^>]*>/i)?.[0] ?? rawXml;
+    const progIdMatch = oleTag.match(/ProgID="([^"]+)"/i) ?? oleTag.match(/progId="([^"]+)"/i);
+    const rIdMatch = oleTag.match(/r:id="([^"]+)"/i);
+    const typeMatch = oleTag.match(/Type="([^"]+)"/i);
     if (!progIdMatch) {
         return null;
     }
     const progId = progIdMatch[1];
     const rId = rIdMatch ? rIdMatch[1] : "";
     const objectType = typeMatch && typeMatch[1].toLowerCase().includes("link") ? "linked" : "embedded";
-    // Extract dimensions
+    // Extract dimensions (from the surrounding shape, hence full rawXml)
     const widthMatch = rawXml.match(/(?:cx|width)="(\d+)"/i);
     const heightMatch = rawXml.match(/(?:cy|height)="(\d+)"/i);
     return {

package/dist/browser/modules/word/advanced/style-map.js

@@ -139,14 +139,8 @@ export const DEFAULT_STYLE_MAP = {
  * ```
  */
 export function parseStyleMap(dsl, options) {
-    const rules = [];
-    // Include defaults if requested
-    if (options?.includeDefaults !== false && options?.base) {
-        rules.push(...options.base.rules);
-    }
-    else if (options?.includeDefaults !== false && !options?.base) {
-        rules.push(...DEFAULT_STYLE_MAP.rules);
-    }
+    // User-defined rules from the DSL.
+    const userRules = [];
     const lines = dsl
         .split("\n")
         .map(l => l.trim())
@@ -154,10 +148,37 @@ export function parseStyleMap(dsl, options) {
     for (const line of lines) {
         const rule = parseRule(line);
         if (rule) {
-            rules.push(rule);
+            userRules.push(rule);
         }
     }
-    // Sort by priority (highest first)
+    // Default / base rules requested via `includeDefaults`.
+    const defaultRules = [];
+    if (options?.includeDefaults !== false && options?.base) {
+        defaultRules.push(...options.base.rules);
+    }
+    else if (options?.includeDefaults !== false && !options?.base) {
+        defaultRules.push(...DEFAULT_STYLE_MAP.rules);
+    }
+    // An explicit DSL rule should always win over a default rule for the same
+    // element — that is the whole point of providing one. Default rules,
+    // however, carry their own priorities (e.g. "Heading 1" => h1 has priority
+    // 10) that can exceed the fixed priority `parseRule` assigns to user rules.
+    // To guarantee user intent wins while preserving the relative priority
+    // ordering *within* each group, lift every user rule above the highest
+    // default priority. When there are no defaults this offset is 0 and user
+    // priorities are untouched.
+    const maxDefaultPriority = defaultRules.reduce((m, r) => Math.max(m, r.priority ?? 0), 0);
+    const userOffset = defaultRules.length > 0 ? maxDefaultPriority + 1 : 0;
+    const liftedUserRules = userOffset === 0
+        ? userRules
+        : userRules.map(r => ({ ...r, priority: (r.priority ?? 0) + userOffset }));
+    // User rules come first so that, after a stable sort, an explicit DSL rule
+    // also wins over any default rule that happens to share its (lifted)
+    // priority. The sort below only reorders by priority; equal priorities
+    // preserve this user-before-default ordering.
+    const rules = [...liftedUserRules, ...defaultRules];
+    // Sort by priority (highest first). Array.prototype.sort is stable, so
+    // rules of equal priority keep their relative order (user rules first).
     rules.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
     return { rules };
 }

package/dist/browser/modules/word/builder/run-builders.d.ts

@@ -263,7 +263,13 @@ export declare function mathSubScript(base: MathContent[], subScript: MathConten
 export declare function mathSubSuperScript(base: MathContent[], subScript: MathContent[], superScript: MathContent[]): MathContent;
 /** Create a math pre-sub-superscript (subscript/superscript before the base). */
 export declare function mathPreSubSuperScript(base: MathContent[], preSubScript: MathContent[], preSuperScript: MathContent[]): MathContent;
-/** Create a math phantom (invisible expression that takes up space). */
+/**
+ * Create a math phantom (an expression that takes up space).
+ *
+ * Note: in OOXML the phantom base is *shown* by default. To make the classic
+ * "occupies space but invisible" phantom pass `{ show: false }`; passing only
+ * `transparent: true` is not sufficient to hide the base in Word.
+ */
 export declare function mathPhantom(content: MathContent[], options?: {
     show?: boolean;
     zeroWidth?: boolean;

package/dist/browser/modules/word/builder/run-builders.js

@@ -449,7 +449,13 @@ export function mathSubSuperScript(base, subScript, superScript) {
 export function mathPreSubSuperScript(base, preSubScript, preSuperScript) {
     return { type: "mathPreSubSuperScript", base, preSubScript, preSuperScript };
 }
-/** Create a math phantom (invisible expression that takes up space). */
+/**
+ * Create a math phantom (an expression that takes up space).
+ *
+ * Note: in OOXML the phantom base is *shown* by default. To make the classic
+ * "occupies space but invisible" phantom pass `{ show: false }`; passing only
+ * `transparent: true` is not sufficient to hide the base in Word.
+ */
 export function mathPhantom(content, options) {
     return { type: "mathPhantom", content, ...options };
 }

package/dist/browser/modules/word/constants.d.ts

@@ -168,6 +168,10 @@ export declare const ContentType: {
     readonly Xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
     readonly CustomXml: "application/xml";
     readonly VbaProject: "application/vnd.ms-office.vbaProject";
+    /** Glossary (Building Blocks) document part. */
+    readonly Glossary: "application/vnd.openxmlformats-officedocument.wordprocessingml.document.glossary+xml";
+    /** OLE embedded object binary. */
+    readonly OleObject: "application/vnd.openxmlformats-officedocument.oleObject";
 };
 /** Map from image file extension to content type. */
 export declare const IMAGE_CONTENT_TYPES: Record<string, string>;

package/dist/browser/modules/word/constants.js

@@ -268,7 +268,11 @@ export const ContentType = {
     ChartEx: "application/vnd.ms-office.chartEx+xml",
     Xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
     CustomXml: "application/xml",
-    VbaProject: "application/vnd.ms-office.vbaProject"
+    VbaProject: "application/vnd.ms-office.vbaProject",
+    /** Glossary (Building Blocks) document part. */
+    Glossary: "application/vnd.openxmlformats-officedocument.wordprocessingml.document.glossary+xml",
+    /** OLE embedded object binary. */
+    OleObject: "application/vnd.openxmlformats-officedocument.oleObject"
 };
 /** Map from image file extension to content type. */
 export const IMAGE_CONTENT_TYPES = {

package/dist/browser/modules/word/convert/docx-to-semantic.d.ts

@@ -11,7 +11,8 @@
  * - Hyperlink extraction
  * - Image registration into ConversionContext
  * - Table structure with merge (colSpan/rowSpan)
- * - List/numbering detection (basic)
+ * - List/numbering detection: consecutive numbered paragraphs are aggregated
+ *   into ordered/unordered `list` blocks with nested sub-lists by level
  * - Footnote/endnote reference and content
  * - Math content (text fallback)
  */

package/dist/browser/modules/word/convert/docx-to-semantic.js

@@ -11,7 +11,8 @@
  * - Hyperlink extraction
  * - Image registration into ConversionContext
  * - Table structure with merge (colSpan/rowSpan)
- * - List/numbering detection (basic)
+ * - List/numbering detection: consecutive numbered paragraphs are aggregated
+ *   into ordered/unordered `list` blocks with nested sub-lists by level
  * - Footnote/endnote reference and content
  * - Math content (text fallback)
  */
@@ -93,6 +94,26 @@ function convertBodyContent(body, doc, ctx, imageMap) {
         const item = body[bodyIndex];
         switch (item.type) {
             case "paragraph":
+                // A run of consecutive list-item paragraphs (each carrying a
+                // numbering reference, and not a heading) is aggregated into a single
+                // semantic `list` block with nested sub-lists driven by the numbering
+                // level. This is what turns Word numbering into real <ul>/<ol> in
+                // HTML and `-`/`1.` markers in Markdown when downstream renderers
+                // consume the IR.
+                if (isListItemParagraph(item)) {
+                    let end = bodyIndex;
+                    while (end < body.length) {
+                        const next = body[end];
+                        if (next.type !== "paragraph" || !isListItemParagraph(next)) {
+                            break;
+                        }
+                        end++;
+                    }
+                    const listParas = body.slice(bodyIndex, end);
+                    blocks.push(...buildListBlocks(listParas, doc, ctx, imageMap));
+                    bodyIndex = end - 1; // loop's ++ advances past the consumed run
+                    break;
+                }
                 blocks.push(convertParagraph(item, doc, ctx, imageMap));
                 break;
             case "table":
@@ -240,6 +261,119 @@ function convertBodyContent(body, doc, ctx, imageMap) {
     return blocks;
 }
 // =============================================================================
+// Internal: List Aggregation
+// =============================================================================
+/**
+ * Whether a body paragraph should render as a list item: it carries a
+ * numbering reference and is not itself a heading (a numbered heading stays a
+ * heading, mirroring the markdown/html renderers).
+ */
+function isListItemParagraph(item) {
+    if (item.type !== "paragraph") {
+        return false;
+    }
+    return item.properties?.numbering !== undefined && detectHeadingLevel(item) === null;
+}
+/**
+ * Resolve a numbering reference to its number format string (e.g. "decimal",
+ * "bullet"). Mirrors the lookup in the markdown/html renderers so the three
+ * surfaces classify ordered vs. unordered lists identically. Defaults to
+ * "bullet" when the numbering definition can't be resolved.
+ */
+function getNumberingFormat(doc, numId, level) {
+    const instance = doc.numberingInstances?.find(n => n.numId === numId);
+    if (!instance) {
+        return "bullet";
+    }
+    const abstractNum = doc.abstractNumberings?.find(a => a.abstractNumId === instance.abstractNumId);
+    if (!abstractNum) {
+        return "bullet";
+    }
+    const levelDef = abstractNum.levels.find(l => l.level === level);
+    return levelDef?.format ?? "bullet";
+}
+/** A number format other than "bullet"/"none" denotes an ordered list. */
+function isOrderedFormat(format) {
+    return format !== "bullet" && format !== "none";
+}
+/**
+ * Build one or more semantic `list` blocks from a contiguous run of list-item
+ * paragraphs. Paragraphs are nested by their numbering `level`; a deeper level
+ * becomes a `subList` of the preceding shallower item. Adjacent items that
+ * switch between ordered and unordered at the same level start a new sibling
+ * list so the ordered/unordered distinction is preserved.
+ */
+function buildListBlocks(paras, doc, ctx, imageMap) {
+    const { blocks } = buildListLevel(paras, 0, 0, doc, ctx, imageMap);
+    return blocks;
+}
+/**
+ * Consume paragraphs starting at `start` that belong to `level` (or deeper),
+ * emitting sibling lists for this level. Deeper-level paragraphs are folded
+ * into the current item's `subList` via recursion. Returns the produced blocks
+ * and the index of the first paragraph that no longer belongs to this level.
+ */
+function buildListLevel(paras, start, level, doc, ctx, imageMap) {
+    const blocks = [];
+    let i = start;
+    let currentOrdered = null;
+    let items = [];
+    const flush = () => {
+        if (items.length > 0 && currentOrdered !== null) {
+            blocks.push({ type: "list", ordered: currentOrdered, items });
+            items = [];
+        }
+    };
+    while (i < paras.length) {
+        const para = paras[i];
+        const num = para.properties?.numbering;
+        // Defensive: callers only pass list-item paragraphs, but guard anyway.
+        if (!num) {
+            break;
+        }
+        if (num.level < level) {
+            // Belongs to a shallower list — let the caller handle it.
+            break;
+        }
+        if (num.level > level) {
+            // Deeper item with no shallower parent at this position: descend and
+            // attach the nested list to the most recent item, or synthesise an
+            // empty item to host it when there is no parent.
+            const { blocks: subBlocks, next } = buildListLevel(paras, i, num.level, doc, ctx, imageMap);
+            const subList = subBlocks[0];
+            if (items.length > 0) {
+                const last = items[items.length - 1];
+                items[items.length - 1] = { ...last, subList };
+            }
+            else if (subList) {
+                // Promote the deeper list to this level when there is no parent item.
+                if (currentOrdered === null && subList.type === "list") {
+                    currentOrdered = subList.ordered;
+                }
+                items.push({ children: [], subList });
+            }
+            i = next;
+            continue;
+        }
+        // num.level === level
+        const format = getNumberingFormat(doc, num.numId, num.level);
+        const ordered = isOrderedFormat(format);
+        if (currentOrdered === null) {
+            currentOrdered = ordered;
+        }
+        else if (ordered !== currentOrdered) {
+            // Ordered/unordered switch at the same level → start a new sibling list.
+            flush();
+            currentOrdered = ordered;
+        }
+        const children = convertParagraphChildren(para.children, doc, ctx, imageMap);
+        items.push({ children });
+        i++;
+    }
+    flush();
+    return { blocks, next: i };
+}
+// =============================================================================
 // Internal: Paragraph Conversion
 // =============================================================================
 function convertParagraph(para, doc, ctx, imageMap) {