@json-to-office/core-docx 0.36.1 → 0.37.0

package/dist/index.js

@@ -383,9 +383,6 @@ var init_minimal_docx_theme = __esm({
         },
         section: {
           pageBreak: false
-        },
-        heading: {
-          numbering: false
         }
       }
     };
@@ -508,9 +505,6 @@ var init_corporate_docx_theme = __esm({
         },
         section: {
           pageBreak: false
-        },
-        heading: {
-          numbering: false
         }
       }
     };
@@ -753,9 +747,6 @@ var init_apex_docx_theme = __esm({
         },
         section: {
           pageBreak: false
-        },
-        heading: {
-          numbering: false
         }
       }
     };
@@ -889,9 +880,6 @@ var init_devportal_docx_theme = __esm({
         },
         section: {
           pageBreak: false
-        },
-        heading: {
-          numbering: false
         }
       }
     };
@@ -3752,8 +3740,51 @@ import {
   InternalHyperlink,
   FootnoteReferenceRun,
   EndnoteReferenceRun,
+  NumberedItemReference,
+  NumberedItemReferenceFormat,
   Tab
 } from "docx";
+
+// src/utils/numberedItemsRegistry.ts
+import { AsyncLocalStorage as AsyncLocalStorage2 } from "async_hooks";
+var NumberedItemsRegistry = class {
+  fallback = {
+    items: /* @__PURE__ */ new Map(),
+    seeded: false
+  };
+  scopes = new AsyncLocalStorage2();
+  get state() {
+    return this.scopes.getStore() ?? this.fallback;
+  }
+  /** Run work with an isolated registry that follows its async call chain. */
+  runScoped(callback) {
+    return this.scopes.run({ items: /* @__PURE__ */ new Map(), seeded: false }, callback);
+  }
+  /** Replace the contents with the pre-pass result. */
+  seed(items) {
+    const state = this.state;
+    state.items = new Map(items);
+    state.seeded = true;
+  }
+  /**
+   * False outside a render (a unit test calling `createText` directly). An
+   * unresolved reference is then expected rather than an authoring mistake, so
+   * the caller stays quiet about it.
+   */
+  isSeeded() {
+    return this.state.seeded;
+  }
+  get(id) {
+    return this.state.items.get(id);
+  }
+  clear() {
+    this.state.items.clear();
+    this.state.seeded = false;
+  }
+};
+var globalNumberedItemsRegistry = new NumberedItemsRegistry();
+
+// src/utils/textParser.ts
 var FOOTNOTE_MARKER_REGEX = /\[\^([^\]\s]+)\]/;
 function escapeRegExp(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -3969,13 +4000,59 @@ function splitNoteMarkers(text, noteRef, runs) {
   if (trailing) out.push(...runs(trailing));
   return out;
 }
+var CROSS_REFERENCE_PATTERN = "\\[@([^\\]\\s:]+)(?::(relative|no_context|full_context|none))?\\]";
+var INLINE_TOKEN_REGEX = `\\[([^\\]]+)\\]\\(([^)]+)\\)|${CROSS_REFERENCE_PATTERN}`;
+function hasCrossReference(text) {
+  return new RegExp(CROSS_REFERENCE_PATTERN).test(text);
+}
+var REFERENCE_FORMATS = {
+  relative: NumberedItemReferenceFormat.RELATIVE,
+  no_context: NumberedItemReferenceFormat.NO_CONTEXT,
+  full_context: NumberedItemReferenceFormat.FULL_CONTEXT,
+  none: NumberedItemReferenceFormat.NONE
+};
+function createCrossReference(id, format2, token, baseStyle, options) {
+  const info = globalNumberedItemsRegistry.get(id);
+  if (!info) {
+    if (globalNumberedItemsRegistry.isSeeded()) {
+      console.warn(
+        `[core-docx] Cross-reference ${token} has no target: no heading or list item declares the id "${id}". Rendering the token as literal text.`
+      );
+    }
+    return buildTextRuns(
+      token,
+      buildRunCommonProps(baseStyle, { boldColor: options.boldColor }),
+      { noProof: baseStyle.noProof, noProofWords: options.noProofWords }
+    );
+  }
+  if (format2 === "none") {
+    return [
+      new NumberedItemReference(id, info.text, {
+        hyperlink: true,
+        referenceFormat: REFERENCE_FORMATS.none
+      })
+    ];
+  }
+  const cachedValue = format2 === "no_context" ? info.own : info.full;
+  if (cachedValue === void 0) {
+    console.warn(
+      `[core-docx] Cross-reference ${token} targets an unnumbered ${info.kind} ("${id}"), so the field carries no cached number and reads blank until the reader updates fields. Use [@${id}:none] to reference its text instead.`
+    );
+  }
+  return [
+    new NumberedItemReference(id, cachedValue, {
+      hyperlink: true,
+      referenceFormat: REFERENCE_FORMATS[format2]
+    })
+  ];
+}
 function parseTextWithHyperlinks(text, baseStyle = {}, options = {}) {
   const normalizedText = normalizeUnicodeText(text);
   const runs = [];
-  const hyperlinkRegex = /\[([^\]]+)\]\(([^)]+)\)/g;
+  const tokenRegex = new RegExp(INLINE_TOKEN_REGEX, "g");
   let lastIndex = 0;
   let match;
-  while ((match = hyperlinkRegex.exec(normalizedText)) !== null) {
+  while ((match = tokenRegex.exec(normalizedText)) !== null) {
     if (match.index > lastIndex) {
       const plainText = normalizedText.substring(lastIndex, match.index);
       if (plainText) {
@@ -3987,6 +4064,19 @@ function parseTextWithHyperlinks(text, baseStyle = {}, options = {}) {
         runs.push(...plainRuns);
       }
     }
+    lastIndex = match.index + match[0].length;
+    if (match[1] === void 0) {
+      runs.push(
+        ...createCrossReference(
+          match[3],
+          match[4] ?? "relative",
+          match[0],
+          baseStyle,
+          options
+        )
+      );
+      continue;
+    }
     const linkText = match[1];
     const linkUrl = match[2];
     const isInternal = linkUrl.startsWith("#");
@@ -4013,7 +4103,6 @@ function parseTextWithHyperlinks(text, baseStyle = {}, options = {}) {
         })
       );
     }
-    lastIndex = match.index + match[0].length;
   }
   if (lastIndex < normalizedText.length) {
     const remainingText = normalizedText.substring(lastIndex);
@@ -4222,7 +4311,7 @@ function initializeBuiltinPlaceholders() {
 initializeBuiltinPlaceholders();
 
 // src/utils/revisionUtils.ts
-import { AsyncLocalStorage as AsyncLocalStorage2 } from "async_hooks";
+import { AsyncLocalStorage as AsyncLocalStorage3 } from "async_hooks";
 
 // src/utils/componentAnnotations.ts
 function isRecord(value) {
@@ -4273,7 +4362,7 @@ var DEFAULT_REVISION_AUTHOR = "json-to-office";
 var DEFAULT_REVISION_DATE = "1970-01-01T00:00:00Z";
 var RevisionIdRegistry = class {
   fallbackCounter = 0;
-  scopes = new AsyncLocalStorage2();
+  scopes = new AsyncLocalStorage3();
   runScoped(callback) {
     return this.scopes.run({ counter: 0 }, callback);
   }
@@ -4555,10 +4644,21 @@ init_styles();
 init_defaults();
 
 // src/utils/bookmarkRegistry.ts
-import { AsyncLocalStorage as AsyncLocalStorage3 } from "async_hooks";
+import { AsyncLocalStorage as AsyncLocalStorage4 } from "async_hooks";
+function slugifyBookmarkText(text) {
+  return text.toLowerCase().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "").substring(0, 40);
+}
+function dedupeBookmarkId(base, taken) {
+  let id = base;
+  let attempt = 0;
+  while (taken(id) && attempt < 100) {
+    id = `${base}-${++attempt}`;
+  }
+  return id;
+}
 var BookmarkRegistry = class {
   fallback = { bookmarks: /* @__PURE__ */ new Map() };
-  scopes = new AsyncLocalStorage3();
+  scopes = new AsyncLocalStorage4();
   get state() {
     return this.scopes.getStore() ?? this.fallback;
   }
@@ -4582,13 +4682,10 @@ var BookmarkRegistry = class {
    * Converts text to a URL-friendly format
    */
   generateId(text, _type = "bookmark") {
-    const baseId = text.toLowerCase().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "").substring(0, 40);
-    let id = baseId;
-    let attempt = 0;
-    while (this.state.bookmarks.has(id) && attempt < 100) {
-      id = `${baseId}-${++attempt}`;
-    }
-    return id;
+    return dedupeBookmarkId(
+      slugifyBookmarkText(text),
+      (id) => this.state.bookmarks.has(id)
+    );
   }
   /**
    * Check if a bookmark exists
@@ -4640,7 +4737,7 @@ import {
 
 // src/utils/commentRegistry.ts
 import { Paragraph, TextRun as TextRun4 } from "docx";
-import { AsyncLocalStorage as AsyncLocalStorage4 } from "async_hooks";
+import { AsyncLocalStorage as AsyncLocalStorage5 } from "async_hooks";
 var DEFAULT_COMMENT_AUTHOR = "json-to-office";
 var DEFAULT_COMMENT_DATE = "1970-01-01T00:00:00Z";
 function createState() {
@@ -4655,7 +4752,7 @@ function bodyParagraphs(text) {
 }
 var CommentRegistry = class {
   fallback = createState();
-  scopes = new AsyncLocalStorage4();
+  scopes = new AsyncLocalStorage5();
   get state() {
     return this.scopes.getStore() ?? this.fallback;
   }
@@ -4750,7 +4847,7 @@ function closeCommentRange(ids) {
 
 // src/utils/noteRegistry.ts
 import { Paragraph as Paragraph2, TextRun as TextRun6 } from "docx";
-import { AsyncLocalStorage as AsyncLocalStorage5 } from "async_hooks";
+import { AsyncLocalStorage as AsyncLocalStorage6 } from "async_hooks";
 function createState2() {
   return {
     footnoteCounter: 0,
@@ -4769,7 +4866,7 @@ function bodyParagraphs2(text, style) {
 }
 var NoteRegistry = class {
   fallback = createState2();
-  scopes = new AsyncLocalStorage5();
+  scopes = new AsyncLocalStorage6();
   get state() {
     return this.scopes.getStore() ?? this.fallback;
   }
@@ -5125,7 +5222,7 @@ function createHeading(text, level, theme, _themeName, options = {}) {
   if (commentAnchor) {
     children.push(...commentAnchor.start);
   }
-  const hasDecorators = /(\*\*\*|___|(\*\*|__)|(\*|_))/.test(normalizedText);
+  const hasInlineSyntax = /(\*\*\*|___|(\*\*|__)|(\*|_))/.test(normalizedText) || hasCrossReference(normalizedText);
   const headingHasWeightRequest = options.fontWeight != null || options.bold === true;
   const headingEffectiveFamily = options.fontFamily ?? (headingHasWeightRequest ? resolveFontFamily(theme, "heading") : void 0);
   const headingWeighted = applyFontWeightAlias({
@@ -5192,7 +5289,7 @@ function createHeading(text, level, theme, _themeName, options = {}) {
       "heading"
     );
     const headingTextChildren = [];
-    if (hasDecorators) {
+    if (hasInlineSyntax) {
       const textRuns = parseTextWithDecorators(normalizedText, baseTextStyle, {
         boldColor: options.boldColor ? resolveColor(options.boldColor, theme) : void 0,
         enableHyperlinks: true,
@@ -5209,7 +5306,7 @@ function createHeading(text, level, theme, _themeName, options = {}) {
       })
     );
   } else {
-    if (hasDecorators) {
+    if (hasInlineSyntax) {
       const textRuns = parseTextWithDecorators(normalizedText, baseTextStyle, {
         boldColor: options.boldColor ? resolveColor(options.boldColor, theme) : void 0,
         enableHyperlinks: true,
@@ -5231,7 +5328,10 @@ function createHeading(text, level, theme, _themeName, options = {}) {
     spacing: hasExplicitSpacing ? spacing : void 0,
     ...options.keepNext !== void 0 && { keepNext: options.keepNext },
     ...options.keepLines !== void 0 && { keepLines: options.keepLines },
-    ...options.indent && { indent: options.indent }
+    ...options.indent && { indent: options.indent },
+    // docx creates the concrete numbering instance for the reference itself,
+    // in ParagraphProperties.prepForXml.
+    ...options.numbering !== void 0 && { numbering: options.numbering }
   });
 }
 async function createImage(path4, theme, themeName, options = {}) {
@@ -5391,9 +5491,17 @@ function createList(items, _theme, _themeName, options = {}) {
     } else if (options.spacing?.item) {
       spacing.after = pointsToTwips(options.spacing.item);
     }
+    const itemId = typeof item === "object" ? item.id : void 0;
+    let itemContent = textRuns;
+    if (itemId) {
+      globalBookmarkRegistry.register(itemId, itemText, "list-item");
+      itemContent = [
+        new Bookmark({ id: itemId, children: textRuns })
+      ];
+    }
     const paragraphChildren = [
       ...commentAnchor && index === firstRendered ? commentAnchor.start : [],
-      ...textRuns,
+      ...itemContent,
       ...commentAnchor && index === lastRendered ? closeCommentRange(commentAnchor.ids) : []
     ];
     const paragraph = new Paragraph3({
@@ -6236,54 +6344,14 @@ function createFooterElement(children, _options) {
   });
 }
 
-// src/components/heading.ts
-function renderHeadingComponent(component, theme, themeName) {
-  if (!isHeadingComponent(component)) return [];
-  const config = component.props;
-  const bookmarkId = component.id || globalBookmarkRegistry.generateId(config.text, "heading");
-  const header = createHeading(
-    config.text,
-    config.level || 1,
-    theme,
-    themeName,
-    {
-      alignment: config.alignment,
-      spacing: config.spacing,
-      lineSpacing: config.lineSpacing,
-      columnBreak: config.columnBreak,
-      // Local font overrides
-      fontFamily: config.font?.family,
-      fontSize: config.font?.size,
-      fontColor: config.font?.color,
-      bold: config.font?.bold,
-      fontWeight: config.font?.fontWeight,
-      italic: config.font?.italic,
-      underline: config.font?.underline,
-      scale: config.font?.scale,
-      characterSpacing: config.font?.characterSpacing,
-      // Proofing: local language override + no-proof toggle + known-words list
-      language: config.language,
-      noProof: config.noProof,
-      noProofWords: config.noProofWords,
-      // Pagination control
-      keepNext: config.keepNext,
-      keepLines: config.keepLines,
-      // Paragraph indentation (w:ind) in twips
-      indent: config.indent,
-      // Bookmark ID for internal linking
-      bookmarkId,
-      // Tracked-change segments (rendered as native Word revisions)
-      revision: config.revision,
-      // Review comment anchored to this heading's text
-      comment: config.comment
-    }
-  );
-  return [header];
-}
-
 // src/utils/numberingConfig.ts
-import { AlignmentType as AlignmentType3, convertInchesToTwip, LevelFormat } from "docx";
-import { AsyncLocalStorage as AsyncLocalStorage6 } from "async_hooks";
+import {
+  AlignmentType as AlignmentType3,
+  convertInchesToTwip,
+  LevelFormat,
+  LevelSuffix
+} from "docx";
+import { AsyncLocalStorage as AsyncLocalStorage7 } from "async_hooks";
 var LEVEL_FORMAT_MAP = {
   decimal: LevelFormat.DECIMAL,
   upperRoman: LevelFormat.UPPER_ROMAN,
@@ -6411,12 +6479,37 @@ function createNumberingConfig(config) {
     levels
   };
 }
+var HEADING_NUMBERING_REFERENCE = "jto-heading-numbering";
+function createHeadingNumberingConfig() {
+  const levels = [];
+  for (let level = 0; level < 6; level++) {
+    const text = Array.from({ length: level + 1 }, (_, i) => `%${i + 1}`).join(".") + ".";
+    levels.push({
+      level,
+      format: LevelFormat.DECIMAL,
+      text,
+      alignment: AlignmentType3.LEFT,
+      start: 1,
+      // A space, not the default tab: a tab would push the heading text to the
+      // next tab stop and misalign it against unnumbered headings.
+      suffix: LevelSuffix.SPACE,
+      style: {
+        paragraph: { indent: { left: 0, hanging: 0 } },
+        style: `Heading${level + 1}`
+      }
+    });
+  }
+  return { reference: HEADING_NUMBERING_REFERENCE, levels };
+}
+function headingNumberLabel(number) {
+  return `${number}.`;
+}
 var NumberingRegistry = class {
   fallback = {
     configs: /* @__PURE__ */ new Map(),
     counter: 0
   };
-  scopes = new AsyncLocalStorage6();
+  scopes = new AsyncLocalStorage7();
   get state() {
     return this.scopes.getStore() ?? this.fallback;
   }
@@ -6466,6 +6559,63 @@ var NumberingRegistry = class {
 };
 var globalNumberingRegistry = new NumberingRegistry();
 
+// src/components/heading.ts
+var MAX_HEADING_LEVEL = 6;
+function headingNumbering(numbering, level) {
+  if (numbering === false) return false;
+  if (numbering !== true) return void 0;
+  if (!globalNumberingRegistry.has(HEADING_NUMBERING_REFERENCE)) {
+    globalNumberingRegistry.register(createHeadingNumberingConfig());
+  }
+  const styleLevel = level >= 1 && level <= MAX_HEADING_LEVEL ? level : 1;
+  return { reference: HEADING_NUMBERING_REFERENCE, level: styleLevel - 1 };
+}
+function renderHeadingComponent(component, theme, themeName) {
+  if (!isHeadingComponent(component)) return [];
+  const config = component.props;
+  const bookmarkId = component.id || globalBookmarkRegistry.generateId(config.text, "heading");
+  const header = createHeading(
+    config.text,
+    config.level || 1,
+    theme,
+    themeName,
+    {
+      alignment: config.alignment,
+      spacing: config.spacing,
+      lineSpacing: config.lineSpacing,
+      columnBreak: config.columnBreak,
+      // Local font overrides
+      fontFamily: config.font?.family,
+      fontSize: config.font?.size,
+      fontColor: config.font?.color,
+      bold: config.font?.bold,
+      fontWeight: config.font?.fontWeight,
+      italic: config.font?.italic,
+      underline: config.font?.underline,
+      scale: config.font?.scale,
+      characterSpacing: config.font?.characterSpacing,
+      // Proofing: local language override + no-proof toggle + known-words list
+      language: config.language,
+      noProof: config.noProof,
+      noProofWords: config.noProofWords,
+      // Pagination control
+      keepNext: config.keepNext,
+      keepLines: config.keepLines,
+      // Paragraph indentation (w:ind) in twips
+      indent: config.indent,
+      // Bookmark ID for internal linking
+      bookmarkId,
+      // Auto-numbering (1., 1.1., …) through the shared heading definition
+      numbering: headingNumbering(config.numbering, config.level || 1),
+      // Tracked-change segments (rendered as native Word revisions)
+      revision: config.revision,
+      // Review comment anchored to this heading's text
+      comment: config.comment
+    }
+  );
+  return [header];
+}
+
 // src/components/paragraph.ts
 function parseMarkdownList(text) {
   const lines = text.split("\n");
@@ -6605,8 +6755,7 @@ function renderParagraphComponent(component, theme, themeName) {
   return [text];
 }
 
-// src/components/list.ts
-init_colorUtils();
+// src/utils/listLevels.ts
 function createLevelsFromSimplifiedProps(props) {
   const levels = [];
   let format2;
@@ -6653,18 +6802,8 @@ function createLevelsFromSimplifiedProps(props) {
   }
   return levels;
 }
-function resolveMarkerFonts(levels, theme) {
-  return levels.map((level) => {
-    const font = level.font;
-    if (!font?.color) return level;
-    return {
-      ...level,
-      font: { ...font, color: resolveColor(font.color, theme) }
-    };
-  });
-}
 function applyListStart(levels, start) {
-  if (start === void 0) return levels;
+  if (start === void 0) return [...levels];
   return levels.map(
     (level) => level.level === 0 && level.start === void 0 ? { ...level, start } : level
   );
@@ -6722,28 +6861,37 @@ function fillMissingLevels(levels, maxLevel) {
   }
   return result;
 }
+function resolveListLevels(props) {
+  const maxLevel = getMaxLevelFromItems(props.items);
+  if (props.levels && props.levels.length > 0) {
+    return fillMissingLevels(
+      applyListStart(props.levels, props.start),
+      maxLevel
+    );
+  }
+  return fillMissingLevels(createLevelsFromSimplifiedProps(props), maxLevel);
+}
+
+// src/components/list.ts
+init_colorUtils();
+function resolveMarkerFonts(levels, theme) {
+  return levels.map((level) => {
+    const font = level.font;
+    if (!font?.color) return level;
+    return {
+      ...level,
+      font: { ...font, color: resolveColor(font.color, theme) }
+    };
+  });
+}
 function renderListComponent(component, theme, themeName) {
   if (!isListComponent(component)) return [];
   const resolvedConfig = component.props;
-  const maxLevel = getMaxLevelFromItems(resolvedConfig.items);
   const reference = resolvedConfig.reference || globalNumberingRegistry.generateReference("list");
   if (!globalNumberingRegistry.has(reference)) {
-    let levels;
-    if (resolvedConfig.levels && resolvedConfig.levels.length > 0) {
-      levels = fillMissingLevels(
-        applyListStart(
-          resolvedConfig.levels,
-          resolvedConfig.start
-        ),
-        maxLevel
-      );
-    } else {
-      const baseLevels = createLevelsFromSimplifiedProps(resolvedConfig);
-      levels = fillMissingLevels(baseLevels, maxLevel);
-    }
     const config = {
       reference,
-      levels: resolveMarkerFonts(levels, theme)
+      levels: resolveMarkerFonts(resolveListLevels(resolvedConfig), theme)
     };
     const numberingConfig = createNumberingConfig(config);
     globalNumberingRegistry.register(numberingConfig);
@@ -6783,6 +6931,7 @@ async function renderImageComponent(component, theme, themeName) {
 
 // src/components/text-box.ts
 import {
+  Paragraph as Paragraph5,
   Table as Table3,
   TableRow as TableRow2,
   TableCell as TableCell2,
@@ -6791,7 +6940,8 @@ import {
   RelativeHorizontalPosition,
   RelativeVerticalPosition,
   OverlapType,
-  TableLayoutType as TableLayoutType2
+  TableLayoutType as TableLayoutType2,
+  WpsShapeRun
 } from "docx";
 
 // src/styles/utils/borderUtils.ts
@@ -6868,6 +7018,8 @@ function buildCellOptions(children, styleCfg, theme) {
 }
 
 // src/components/text-box.ts
+init_colorUtils();
+init_docxImagePositioning();
 init_widthUtils();
 function mapTableFloatOptions(floating, theme, themeName) {
   if (!floating) return void 0;
@@ -6923,26 +7075,23 @@ function mapTableFloatOptions(floating, theme, themeName) {
   opt.overlap = OverlapType.OVERLAP;
   return opt;
 }
-async function renderTextBoxComponent(component, theme, themeName, _context) {
-  if (!isTextBoxComponent(component)) return [];
-  const tb = component;
+async function renderTextBoxChildren(tb, theme, themeName, context) {
+  const childContext = {
+    ...context,
+    parent: tb
+  };
+  const rendered = [];
+  for (const child of tb.children || []) {
+    rendered.push(
+      ...await renderComponent(child, theme, themeName, childContext)
+    );
+  }
+  return rendered;
+}
+async function renderTextBoxAsTable(tb, theme, themeName, _context, prerendered) {
   const isInline = !tb.props.floating;
-  const childComponents = tb.children || [];
   if (isInline) {
-    const cellChildren2 = [];
-    const childContext2 = {
-      ..._context,
-      parent: tb
-    };
-    for (const child of childComponents) {
-      const rendered = await renderComponent(
-        child,
-        theme,
-        themeName,
-        childContext2
-      );
-      cellChildren2.push(...rendered);
-    }
+    const cellChildren2 = prerendered ?? await renderTextBoxChildren(tb, theme, themeName, _context);
     const styleCfg2 = tb.props.style;
     const cellOpts2 = buildCellOptions(cellChildren2, styleCfg2, theme);
     const row2 = new TableRow2({ children: [new TableCell2(cellOpts2)] });
@@ -6955,20 +7104,7 @@ async function renderTextBoxComponent(component, theme, themeName, _context) {
     });
     return [table2];
   }
-  const cellChildren = [];
-  const childContext = {
-    ..._context,
-    parent: tb
-  };
-  for (const child of childComponents) {
-    const rendered = await renderComponent(
-      child,
-      theme,
-      themeName,
-      childContext
-    );
-    cellChildren.push(...rendered);
-  }
+  const cellChildren = prerendered ?? await renderTextBoxChildren(tb, theme, themeName, _context);
   const styleCfg = tb.props.style;
   const cellOpts = buildCellOptions(cellChildren, styleCfg, theme);
   const row = new TableRow2({
@@ -7000,6 +7136,162 @@ async function renderTextBoxComponent(component, theme, themeName, _context) {
   });
   return [table];
 }
+var PIXELS_TO_EMU = 9525;
+var TWIPS_PER_PIXEL = 15;
+function resolveShapeSize(value, axis, theme, themeName) {
+  if (typeof value === "number") {
+    return { pixels: Math.round(value), resolvedPercentage: false };
+  }
+  if (typeof value !== "string") return { resolvedPercentage: false };
+  const fraction = parseFloat(value) / 100;
+  if (!Number.isFinite(fraction) || fraction <= 0) {
+    return { resolvedPercentage: false };
+  }
+  const availableTwips = axis === "width" ? getAvailableWidthTwips(theme, themeName) : getAvailableHeightTwips(theme, themeName);
+  return {
+    pixels: Math.round(availableTwips * fraction / TWIPS_PER_PIXEL),
+    resolvedPercentage: true
+  };
+}
+function shapeColor(value, theme) {
+  return resolveColor(value, theme).replace(/^#/, "");
+}
+function shapeOutline(style, theme) {
+  const border = style?.border;
+  if (!border) return { ignoredSides: [], unsupportedStyles: [] };
+  const order = [
+    "top",
+    "left",
+    "bottom",
+    "right"
+  ];
+  const declared = order.map((side) => [side, border[side]]).filter(
+    (entry) => Boolean(entry[1])
+  );
+  if (declared.length === 0) return { ignoredSides: [], unsupportedStyles: [] };
+  const unsupportedStyles = [
+    ...new Set(
+      declared.map(([, config]) => config.style).filter(
+        (value) => value === "dashed" || value === "dotted" || value === "double"
+      )
+    )
+  ];
+  if (unsupportedStyles.length > 0) {
+    return { ignoredSides: [], unsupportedStyles };
+  }
+  const [, used] = declared[0];
+  const differs = ({ style: s, width, color }) => s !== used.style || width !== used.width || color !== used.color;
+  const ignoredSides = declared.slice(1).filter(([, config]) => differs(config)).map(([side]) => side);
+  if (used.style === "none") return { ignoredSides, unsupportedStyles };
+  return {
+    outline: {
+      type: "solidFill",
+      solidFillType: "rgb",
+      value: used.color ? shapeColor(used.color, theme) : "000000",
+      ...used.width !== void 0 && {
+        width: Math.round(used.width * PIXELS_TO_EMU)
+      }
+    },
+    ignoredSides,
+    unsupportedStyles
+  };
+}
+function shapeBodyProperties(style) {
+  const padding = style?.padding;
+  if (!padding) return void 0;
+  const toEmu = (value) => value === void 0 ? void 0 : Math.round(value * PIXELS_TO_EMU);
+  return {
+    margins: {
+      ...padding.top !== void 0 && { top: toEmu(padding.top) },
+      ...padding.bottom !== void 0 && { bottom: toEmu(padding.bottom) },
+      ...padding.left !== void 0 && { left: toEmu(padding.left) },
+      ...padding.right !== void 0 && { right: toEmu(padding.right) }
+    }
+  };
+}
+async function renderTextBoxAsShape(tb, theme, themeName, context) {
+  const width = resolveShapeSize(tb.props.width, "width", theme, themeName);
+  const height = resolveShapeSize(tb.props.height, "height", theme, themeName);
+  if (width.pixels === void 0 || height.pixels === void 0) {
+    console.warn(
+      '[core-docx] text-box renderAs "shape" needs an explicit width and height (a shape has no autofit); falling back to table rendering.'
+    );
+    return { kind: "fallback" };
+  }
+  const style = tb.props.style;
+  const { outline, ignoredSides, unsupportedStyles } = shapeOutline(
+    style,
+    theme
+  );
+  if (unsupportedStyles.length > 0) {
+    console.warn(
+      `[core-docx] text-box renderAs "shape" cannot draw a ${unsupportedStyles.join("/")} border (a shape outline has no dash pattern); falling back to table rendering, which draws it.`
+    );
+    return { kind: "fallback" };
+  }
+  const rendered = await renderTextBoxChildren(tb, theme, themeName, context);
+  if (rendered.some((element) => !(element instanceof Paragraph5))) {
+    console.warn(
+      '[core-docx] text-box renderAs "shape" requires paragraph-only content; falling back to table rendering.'
+    );
+    return { kind: "fallback", rendered };
+  }
+  const children = rendered;
+  if (width.resolvedPercentage || height.resolvedPercentage) {
+    console.warn(
+      '[core-docx] text-box renderAs "shape" resolves percentage sizes at generation time, against the current page content box; the shape will not reflow if the page size changes.'
+    );
+  }
+  const fill = style?.shading?.fill;
+  if (ignoredSides.length > 0) {
+    console.warn(
+      `[core-docx] text-box renderAs "shape" has one uniform outline; using the first declared border side and ignoring ${ignoredSides.join(", ")}.`
+    );
+  }
+  const dropOutline = Boolean(fill) && Boolean(outline);
+  if (dropOutline) {
+    console.warn(
+      '[core-docx] text-box renderAs "shape" cannot carry a fill and a border at once (docx emits invalid shape properties); keeping the fill and dropping the border.'
+    );
+  }
+  const bodyProperties = shapeBodyProperties(style);
+  const run = new WpsShapeRun({
+    type: "wps",
+    children,
+    transformation: { width: width.pixels, height: height.pixels },
+    ...fill && {
+      solidFill: { type: "rgb", value: shapeColor(fill, theme) }
+    },
+    ...outline && !dropOutline && { outline },
+    ...bodyProperties && { bodyProperties },
+    // Absent `floating` makes it a `wp:inline` drawing.
+    ...tb.props.floating && {
+      floating: mapFloatingOptions(tb.props.floating, theme, themeName)
+    }
+  });
+  return {
+    kind: "shape",
+    paragraphs: [
+      new Paragraph5({ children: [run], spacing: { before: 0, after: 0 } })
+    ]
+  };
+}
+async function renderTextBoxComponent(component, theme, themeName, context) {
+  if (!isTextBoxComponent(component)) return [];
+  const tb = component;
+  if (tb.props.renderAs === "shape") {
+    const attempt = await renderTextBoxAsShape(tb, theme, themeName, context);
+    if (attempt.kind === "shape") return attempt.paragraphs;
+    return renderTextBoxAsTable(
+      tb,
+      theme,
+      themeName,
+      context,
+      attempt.rendered
+    );
+  }
+  return renderTextBoxAsTable(tb, theme, themeName, context);
+}
 
 // src/components/table.ts
 async function renderTableComponent(component, theme, themeName) {
@@ -7053,14 +7345,14 @@ async function renderTableComponent(component, theme, themeName) {
 import { Paragraph as Paragraph6, BookmarkStart, BookmarkEnd } from "docx";
 
 // src/core/sectionBookmarks.ts
-import { AsyncLocalStorage as AsyncLocalStorage7 } from "async_hooks";
+import { AsyncLocalStorage as AsyncLocalStorage8 } from "async_hooks";
 var NESTED_LINK_ID_BASE = 1e6;
 function createState3() {
   return { nextNested: 1, resolved: /* @__PURE__ */ new WeakMap() };
 }
 var SectionBookmarkRegistry = class {
   fallback = createState3();
-  scopes = new AsyncLocalStorage7();
+  scopes = new AsyncLocalStorage8();
   get state() {
     return this.scopes.getStore() ?? this.fallback;
   }
@@ -7318,7 +7610,10 @@ function selectCachedEntries(collected, options) {
       continue;
     }
     if (entry.level < depthStart || entry.level > depthEnd) continue;
-    entries.push({ title: entry.title, level: entry.level });
+    entries.push({
+      title: entry.number ? `${headingNumberLabel(entry.number)} ${entry.title}` : entry.title,
+      level: entry.level
+    });
   }
   return entries;
 }
@@ -8077,6 +8372,61 @@ function computeSectionOrdinals(sections) {
 
 // src/core/collectTocHeadings.ts
 import { getStandardComponent } from "@json-to-office/shared-docx";
+
+// src/utils/numberFormatting.ts
+var ROMAN_NUMERALS = [
+  [1e3, "m"],
+  [900, "cm"],
+  [500, "d"],
+  [400, "cd"],
+  [100, "c"],
+  [90, "xc"],
+  [50, "l"],
+  [40, "xl"],
+  [10, "x"],
+  [9, "ix"],
+  [5, "v"],
+  [4, "iv"],
+  [1, "i"]
+];
+function toRoman(value) {
+  let remaining = value;
+  let out = "";
+  for (const [amount, glyph] of ROMAN_NUMERALS) {
+    while (remaining >= amount) {
+      out += glyph;
+      remaining -= amount;
+    }
+  }
+  return out;
+}
+function toLetters(value) {
+  const index = (value - 1) % 26;
+  const repeats = Math.floor((value - 1) / 26) + 1;
+  return String.fromCharCode(97 + index).repeat(repeats);
+}
+function formatNumberForLevel(value, format2) {
+  if (!Number.isFinite(value) || value < 1) return void 0;
+  const n = Math.floor(value);
+  switch (format2) {
+    case "decimal":
+      return String(n);
+    case "lowerLetter":
+      return toLetters(n);
+    case "upperLetter":
+      return toLetters(n).toUpperCase();
+    case "lowerRoman":
+      return toRoman(n);
+    case "upperRoman":
+      return toRoman(n).toUpperCase();
+    default:
+      return void 0;
+  }
+}
+
+// src/core/collectTocHeadings.ts
+var MAX_HEADING_LEVEL2 = 6;
+var MAX_LIST_LEVEL = 9;
 function normalizeEntryTitle(text) {
   return normalizeUnicodeText(text).replace(/(\*\*\*|___)([\s\S]*?)\1/g, "$2").replace(/(\*\*|__)([\s\S]*?)\1/g, "$2").replace(/(\*|_)([\s\S]*?)\1/g, "$2").trim();
 }
@@ -8095,9 +8445,97 @@ function styleEntryKey(props) {
   }
   return themeStyle;
 }
-function collectTocHeadings(sections) {
+function levelStart(levels, level) {
+  return levels[level]?.start ?? 1;
+}
+function collectDocumentOutline(sections) {
   const entries = [];
+  const numberedItems = /* @__PURE__ */ new Map();
   const ordinals = computeSectionOrdinals(sections);
+  const takenIds = /* @__PURE__ */ new Set();
+  const headingCounters = new Array(MAX_HEADING_LEVEL2).fill(0);
+  const listCounters = /* @__PURE__ */ new Map();
+  const visitHeading = (component, props, sectionBookmarkId) => {
+    const text = typeof props.text === "string" ? props.text : "";
+    const title = normalizeEntryTitle(text);
+    const level = typeof props.level === "number" ? props.level : 1;
+    const styleLevel = level >= 1 && level <= MAX_HEADING_LEVEL2 ? level : 1;
+    let full;
+    let own;
+    if (props.numbering === true) {
+      headingCounters[styleLevel - 1] += 1;
+      for (let deeper = styleLevel; deeper < MAX_HEADING_LEVEL2; deeper++) {
+        headingCounters[deeper] = 0;
+      }
+      full = headingCounters.slice(0, styleLevel).join(".");
+      own = String(headingCounters[styleLevel - 1]);
+    }
+    const explicitId = component.id;
+    const bookmarkId = typeof explicitId === "string" && explicitId ? explicitId : dedupeBookmarkId(slugifyBookmarkText(text), (id) => takenIds.has(id));
+    takenIds.add(bookmarkId);
+    numberedItems.set(bookmarkId, {
+      kind: "heading",
+      text: title,
+      ...full !== void 0 && { full, own }
+    });
+    if (title) {
+      entries.push({
+        title,
+        level,
+        sectionBookmarkId,
+        ...full !== void 0 && { number: full }
+      });
+    }
+  };
+  const visitList = (props) => {
+    const items = Array.isArray(props.items) ? props.items : [];
+    if (items.length === 0) return;
+    const reference = typeof props.reference === "string" && props.reference ? props.reference : void 0;
+    const freshState = () => {
+      const levels = resolveListLevels(
+        props
+      );
+      return {
+        levels,
+        counters: Array.from(
+          { length: MAX_LIST_LEVEL },
+          (_, level) => levelStart(levels, level) - 1
+        )
+      };
+    };
+    let state;
+    if (reference === void 0) {
+      state = freshState();
+    } else {
+      state = listCounters.get(reference) ?? freshState();
+      listCounters.set(reference, state);
+    }
+    for (const item of items) {
+      const isObject = typeof item === "object" && item !== null;
+      const raw = isObject ? item.text : item;
+      const text = typeof raw === "string" ? raw : "";
+      if (!text.trim() && !(isObject && item.revision)) continue;
+      const rawLevel = isObject ? item.level : void 0;
+      const level = typeof rawLevel === "number" && rawLevel >= 0 ? rawLevel : 0;
+      if (level >= MAX_LIST_LEVEL) continue;
+      state.counters[level] += 1;
+      for (let deeper = level + 1; deeper < MAX_LIST_LEVEL; deeper++) {
+        state.counters[deeper] = levelStart(state.levels, deeper) - 1;
+      }
+      const id = isObject ? item.id : void 0;
+      if (typeof id !== "string" || !id) continue;
+      takenIds.add(id);
+      const number = formatNumberForLevel(
+        state.counters[level],
+        state.levels[level]?.format
+      );
+      numberedItems.set(id, {
+        kind: "list-item",
+        text: normalizeUnicodeText(text).trim(),
+        ...number !== void 0 && { full: number, own: number }
+      });
+    }
+  };
   sections.forEach((section, index) => {
     const ordinal = ordinals[index]?.ordinal;
     const sectionBookmarkId = ordinal ? globalSectionBookmarkRegistry.forLayoutSection(ordinal).id : void 0;
@@ -8105,15 +8543,11 @@ function collectTocHeadings(sections) {
       if (!isEnabled(component)) return;
       const props = component.props ?? {};
       if (component.name === "heading") {
-        const text = typeof props.text === "string" ? props.text : "";
-        const title = normalizeEntryTitle(text);
-        if (title) {
-          const level = typeof props.level === "number" ? props.level : 1;
-          entries.push({ title, level, sectionBookmarkId });
-        }
+        visitHeading(component, props, sectionBookmarkId);
         return;
       }
       if (component.name === "paragraph") {
+        if (typeof props.id === "string" && props.id) takenIds.add(props.id);
         const styleId = styleEntryKey(props);
         const text = typeof props.text === "string" ? props.text : "";
         const title = normalizeEntryTitle(text);
@@ -8122,13 +8556,17 @@ function collectTocHeadings(sections) {
         }
         return;
       }
+      if (component.name === "list") {
+        visitList(props);
+        return;
+      }
       if (!isContainer(component.name)) return;
       const children = component.children;
       if (Array.isArray(children)) children.forEach(visit);
     };
     section.components.forEach(visit);
   });
-  return entries;
+  return { entries, numberedItems };
 }
 
 // src/core/render.ts
@@ -8181,7 +8619,13 @@ async function renderDocument(structure, layout, options) {
                       // Footnote ids are document-scoped too: a reference resolved
                       // against another render's counter points at the wrong body.
                       globalNoteRegistry.runScoped(
-                        () => renderDocumentScoped(structure, layout, options)
+                        () => (
+                          // Cross-reference targets are keyed by bookmark id, which
+                          // is only unique within one document.
+                          globalNumberedItemsRegistry.runScoped(
+                            () => renderDocumentScoped(structure, layout, options)
+                          )
+                        )
                       )
                     )
                   )
@@ -8224,13 +8668,14 @@ async function renderDocumentScoped(structure, layout, options) {
     );
   }
   try {
-    const tocHeadings = collectTocHeadings(layout.sections);
-    if (tocHeadings.length > 0) {
-      context.tocHeadings = tocHeadings;
+    const outline = collectDocumentOutline(layout.sections);
+    if (outline.entries.length > 0) {
+      context.tocHeadings = outline.entries;
     }
+    globalNumberedItemsRegistry.seed(outline.numberedItems);
   } catch (error) {
     console.warn(
-      "[core-docx] TOC entry collection failed; the TOC field will rely on the reader refreshing it:",
+      "[core-docx] Document outline collection failed; the TOC field will rely on the reader refreshing it:",
       error instanceof Error ? error.message : error
     );
   }