@sametalmdr/word-editor 0.2.0-alpha → 0.3.0-alpha

package/dist/io/ooxml/numbering.js

@@ -1,290 +1,290 @@
-// word/numbering.xml -> a resolved marker per numbered paragraph OCCURRENCE.
-// Import-time only: import.js's internPPrRef calls createNumberingCounter's
-// next() once per numPr paragraph, in document order, and bakes the result
-// into that paragraph's own pPr props — the renderer never needs this module
-// or numbering.xml itself.
-//
-// SCOPE (measured 2026-08-30, 46/46 real corpus): 30/46 documents carry
-// word/numbering.xml; 4,266 w:lvl definitions, 4,239 bullet / 27 ordinal
-// (14 decimal, 10 lowerLetter, 2 lowerRoman, 1 upperLetter). w:lvlOverride:
-// 0/474 w:num entries -- not implemented, nothing in this corpus needs it.
-// w:lvlRestart: 0/474 -- not implemented; the DEFAULT OOXML restart rule
-// (a level's count resets whenever a SHALLOWER level of the SAME numId is
-// encountered) is implemented instead, unconditionally, matching the corpus.
-//
-// REBUILD NOTE (2026-08-31): v1 of this module returned a STATIC per-level
-// placeholder for ordinal formats ("1.", "a.", ...) -- deliberately, per that
-// turn's own explicit scope exclusion ("real list counting is NOT written").
-// Measured against real Word ground truth (user screenshot): consecutive
-// paragraphs at the same (numId, ilvl) all showed the identical letter/roman
-// numeral instead of incrementing, and a list continued numbering across a
-// container/page boundary in Word but not here. Root cause was NOT a wrong
-// counter key or a container-scoped reset -- there was no counter variable
-// anywhere in this module or in import.js's internPPrRef; resolveMarker was a
-// pure function of (numFmt, lvlText) alone, with no paragraph-occurrence
-// input at all. This version adds one.
-//
-// One thing this module still deliberately does NOT do (ADR-0006-class line:
-// pagination/reflow logic is the browser's job, not ours):
-//  - Wingdings/Symbol GLYPH SUBSTITUTION for bullets. A bullet level whose
-//    w:lvlText is a Private Use Area codepoint (measured: 387/4,239 bullet
-//    levels, e.g. U+F076) means the true glyph lives in a font this importer
-//    never loads/reads (ADR-0020 DOĞRULANMALI #6, theme1.xml is deliberately
-//    not opened). Falls back to a default bullet character, flagged
-//    unresolved -- unrelated to counting, unchanged from v1.
-
-import { findChild, findChildren, getAttr } from "./xml-scan.js";
-import { W_NS } from "./ns.js";
-
-export const DEFAULT_BULLET = "•";
-
-const PUA_START = 0xe000;
-const PUA_END = 0xf8ff;
-
-/**
- * Word's lowerLetter/upperLetter sequencing: the letter itself cycles a..z
- * (NOT spreadsheet-column base-26 positional notation), and past z the
- * letter REPEATS -- 27 is "aa" meaning "a" twice, not "aa" as a two-digit
- * base-26 number. n is 1-based.
- * @param {number} n
- * @returns {string}
- */
-function lowerLetterOf(n) {
-  const letter = String.fromCharCode(97 + ((n - 1) % 26));
-  const repeat = Math.floor((n - 1) / 26) + 1;
-  return letter.repeat(repeat);
-}
-
-/** @type {ReadonlyArray<[number, string]>} */
-const ROMAN_TABLE = Object.freeze([
-  [1000, "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"],
-]);
-
-/**
- * @param {number} n  1-based, positive
- * @returns {string}
- */
-function lowerRomanOf(n) {
-  let out = "";
-  let remaining = n;
-  for (const [value, symbol] of ROMAN_TABLE) {
-    while (remaining >= value) {
-      out += symbol;
-      remaining -= value;
-    }
-  }
-  return out;
-}
-
-/**
- * @param {string} numFmt
- * @param {number} n  1-based
- * @returns {string | null}  null for a numFmt this module does not format
- */
-function formatOrdinal(numFmt, n) {
-  switch (numFmt) {
-    case "decimal":
-      return String(n);
-    case "lowerLetter":
-      return lowerLetterOf(n);
-    case "upperLetter":
-      return lowerLetterOf(n).toUpperCase();
-    case "lowerRoman":
-      return lowerRomanOf(n);
-    case "upperRoman":
-      return lowerRomanOf(n).toUpperCase();
-    default:
-      return null;
-  }
-}
-
-/**
- * @typedef {
- *   | {kind: "bullet", bulletMarker: string, bulletResolved: boolean}
- *   | {kind: "ordinal", numFmt: string, lvlText: string, start: number}
- *   | {kind: "unresolved"}
- * } LevelDef
- */
-
-/**
- * @param {string | null} numFmt
- * @param {string | null} lvlText
- * @returns {{bulletMarker: string, bulletResolved: boolean} | null}  null if
- *   numFmt is not "bullet" (an ordinal level, resolved per-occurrence instead)
- */
-function resolveBullet(numFmt, lvlText) {
-  if (numFmt !== "bullet") return null;
-  if (lvlText !== null && lvlText.length > 0) {
-    const cp = lvlText.codePointAt(0);
-    if (cp !== undefined && (cp < PUA_START || cp > PUA_END)) {
-      return { bulletMarker: lvlText, bulletResolved: true };
-    }
-  }
-  // Missing lvlText, or a PUA codepoint this importer cannot map to a real
-  // glyph without loading the level's font (not implemented, see header).
-  return { bulletMarker: DEFAULT_BULLET, bulletResolved: false };
-}
-
-/**
- * `word/numbering.xml`'s root -> `Map<numId, Map<ilvl, LevelDef>>`. Every
- * numId/ilvl pair the document *declares* is captured once here; counting
- * itself happens later, per paragraph occurrence, via `createNumberingCounter`.
- * @param {import("./xml-scan.js").XmlElement} numberingRoot
- * @returns {Map<string, Map<string, LevelDef>>}
- */
-export function parseNumbering(numberingRoot) {
-  /** @type {Map<string, string>} numId -> abstractNumId */
-  const numToAbstract = new Map();
-  for (const numEl of findChildren(numberingRoot, W_NS, "num")) {
-    const numId = getAttr(numEl, W_NS, "numId");
-    // w:lvlOverride (whose own children can include w:startOverride, a
-    // per-INSTANCE start value that would silently outrank the abstract
-    // level's own w:start below) -- measured 0/474 real corpus w:num
-    // entries (and, independently, 0/30 word/numbering.xml-carrying
-    // documents for w:startOverride specifically, 2026-08-31). Not
-    // implemented: rather than silently using the abstract default and
-    // producing a WRONG start count for a corpus-external document that
-    // does carry one, this throws loudly the moment it is seen.
-    if (findChild(numEl, W_NS, "lvlOverride") !== undefined) {
-      throw new Error(
-        `numbering.js: w:num[numId=${numId ?? "?"}] carries a w:lvlOverride ` +
-          "(possibly w:startOverride) -- not implemented (measured 0/474 real corpus " +
-          "w:num entries carry one); the counter would silently use the abstract " +
-          "level's own w:start instead of this instance's override, producing a wrong count",
-      );
-    }
-    const abstractIdEl = findChild(numEl, W_NS, "abstractNumId");
-    const abstractId = abstractIdEl ? getAttr(abstractIdEl, W_NS, "val") : undefined;
-    if (numId !== undefined && abstractId !== undefined) {
-      numToAbstract.set(numId, abstractId);
-    }
-  }
-
-  /** @type {Map<string, Map<string, LevelDef>>} abstractNumId -> ilvl -> LevelDef */
-  const abstractLevels = new Map();
-  for (const absEl of findChildren(numberingRoot, W_NS, "abstractNum")) {
-    const absId = getAttr(absEl, W_NS, "abstractNumId");
-    if (absId === undefined) continue;
-    /** @type {Map<string, LevelDef>} */
-    const levels = new Map();
-    for (const lvlEl of findChildren(absEl, W_NS, "lvl")) {
-      const ilvl = getAttr(lvlEl, W_NS, "ilvl");
-      if (ilvl === undefined) continue;
-      const numFmtEl = findChild(lvlEl, W_NS, "numFmt");
-      const numFmt = numFmtEl ? (getAttr(numFmtEl, W_NS, "val") ?? null) : null;
-      const lvlTextEl = findChild(lvlEl, W_NS, "lvlText");
-      const lvlText = lvlTextEl ? (getAttr(lvlTextEl, W_NS, "val") ?? null) : null;
-
-      const bullet = resolveBullet(numFmt, lvlText);
-      if (bullet !== null) {
-        levels.set(ilvl, { kind: "bullet", ...bullet });
-        continue;
-      }
-      if (numFmt !== null && formatOrdinal(numFmt, 1) !== null) {
-        const startEl = findChild(lvlEl, W_NS, "start");
-        const startVal = startEl ? Number.parseInt(getAttr(startEl, W_NS, "val") ?? "1", 10) : 1;
-        levels.set(ilvl, {
-          kind: "ordinal",
-          numFmt,
-          lvlText: lvlText !== null && lvlText.length > 0 ? lvlText : "%1.",
-          start: Number.isFinite(startVal) ? startVal : 1,
-        });
-        continue;
-      }
-      // An unrecognized numFmt (none observed in the corpus -- e.g.
-      // chineseCounting, ordinalText). Do not guess a glyph or a counter for it.
-      levels.set(ilvl, { kind: "unresolved" });
-    }
-    abstractLevels.set(absId, levels);
-  }
-
-  /** @type {Map<string, Map<string, LevelDef>>} */
-  const markersByNumId = new Map();
-  for (const [numId, absId] of numToAbstract) {
-    const levels = abstractLevels.get(absId);
-    if (levels !== undefined) {
-      markersByNumId.set(numId, levels);
-    }
-  }
-  return markersByNumId;
-}
-
-/**
- * A running counter over (numId, ilvl), advanced once per paragraph
- * OCCURRENCE by calling `next` in DOCUMENT ORDER -- the only order this
- * makes sense in, since "the next item in this list" is a document-order
- * concept, not a per-container or per-page one (measured against real Word:
- * a list continues across a container/page boundary). Scope is therefore the
- * WHOLE document: one counter instance is created per `convertDocument` call
- * (import.js) and threaded through every anchor/container/paragraph that
- * call processes, in the single sequential pass `collectAnchors` + the
- * anchor loop already walk the document in.
- *
- * Multi-level restart (OOXML default, w:lvlRestart not implemented -- 0/474
- * real corpus w:num entries carry it): encountering ANY level of a numId
- * resets every DEEPER level's counter for that SAME numId, so a fresh "a."
- * at ilvl 0 restarts a sub-list's "i., ii., ..." at ilvl 1 back to "i.".
- * Encountering ilvl 1 again with NO intervening ilvl 0 (e.g. across a
- * container boundary) does NOT reset it -- it continues.
- *
- * @param {Map<string, Map<string, import("./numbering.js").LevelDef>>} numDefs
- */
-export function createNumberingCounter(numDefs) {
-  /** @type {Map<string, Map<string, number>>} numId -> ilvl -> current count */
-  const counts = new Map();
-
-  /**
-   * @param {string} numId
-   * @param {string} ilvl
-   * @returns {{marker: string, resolved: boolean} | undefined}  undefined if
-   *   this (numId, ilvl) has no numbering.xml definition at all -- the
-   *   caller (import.js) falls back to DEFAULT_BULLET, this module never guesses
-   */
-  function next(numId, ilvl) {
-    const level = numDefs.get(numId)?.get(ilvl);
-    if (level === undefined || level.kind === "unresolved") {
-      return undefined;
-    }
-    if (level.kind === "bullet") {
-      // Bullets are not counted, but encountering ANY level (bullet or
-      // ordinal) still restarts deeper ordinal levels of the same numId --
-      // the restart rule is about level hierarchy, not format.
-      resetDeeperLevels(numId, ilvl);
-      return { marker: level.bulletMarker, resolved: level.bulletResolved };
-    }
-
-    let byIlvl = counts.get(numId);
-    if (byIlvl === undefined) {
-      byIlvl = new Map();
-      counts.set(numId, byIlvl);
-    }
-    const current = byIlvl.get(ilvl);
-    const n = current === undefined ? level.start : current + 1;
-    byIlvl.set(ilvl, n);
-    resetDeeperLevels(numId, ilvl);
-
-    const formatted = formatOrdinal(level.numFmt, n);
-    // formatOrdinal cannot fail here: parseNumbering only assigns kind:
-    // "ordinal" when formatOrdinal(numFmt, 1) already returned non-null.
-    const marker = level.lvlText.replace(/%\d/g, formatted ?? "");
-    return { marker, resolved: true };
-  }
-
-  /**
-   * @param {string} numId
-   * @param {string} ilvl
-   */
-  function resetDeeperLevels(numId, ilvl) {
-    const byIlvl = counts.get(numId);
-    if (byIlvl === undefined) return;
-    const thisDepth = Number.parseInt(ilvl, 10);
-    for (const trackedIlvl of [...byIlvl.keys()]) {
-      if (Number.parseInt(trackedIlvl, 10) > thisDepth) {
-        byIlvl.delete(trackedIlvl);
-      }
-    }
-  }
-
-  return { next };
-}
+// word/numbering.xml -> a resolved marker per numbered paragraph OCCURRENCE.
+// Import-time only: import.js's internPPrRef calls createNumberingCounter's
+// next() once per numPr paragraph, in document order, and bakes the result
+// into that paragraph's own pPr props — the renderer never needs this module
+// or numbering.xml itself.
+//
+// SCOPE (measured 2026-08-30, 46/46 real corpus): 30/46 documents carry
+// word/numbering.xml; 4,266 w:lvl definitions, 4,239 bullet / 27 ordinal
+// (14 decimal, 10 lowerLetter, 2 lowerRoman, 1 upperLetter). w:lvlOverride:
+// 0/474 w:num entries -- not implemented, nothing in this corpus needs it.
+// w:lvlRestart: 0/474 -- not implemented; the DEFAULT OOXML restart rule
+// (a level's count resets whenever a SHALLOWER level of the SAME numId is
+// encountered) is implemented instead, unconditionally, matching the corpus.
+//
+// REBUILD NOTE (2026-08-31): v1 of this module returned a STATIC per-level
+// placeholder for ordinal formats ("1.", "a.", ...) -- deliberately, per that
+// turn's own explicit scope exclusion ("real list counting is NOT written").
+// Measured against real Word ground truth (user screenshot): consecutive
+// paragraphs at the same (numId, ilvl) all showed the identical letter/roman
+// numeral instead of incrementing, and a list continued numbering across a
+// container/page boundary in Word but not here. Root cause was NOT a wrong
+// counter key or a container-scoped reset -- there was no counter variable
+// anywhere in this module or in import.js's internPPrRef; resolveMarker was a
+// pure function of (numFmt, lvlText) alone, with no paragraph-occurrence
+// input at all. This version adds one.
+//
+// One thing this module still deliberately does NOT do (ADR-0006-class line:
+// pagination/reflow logic is the browser's job, not ours):
+//  - Wingdings/Symbol GLYPH SUBSTITUTION for bullets. A bullet level whose
+//    w:lvlText is a Private Use Area codepoint (measured: 387/4,239 bullet
+//    levels, e.g. U+F076) means the true glyph lives in a font this importer
+//    never loads/reads (ADR-0020 DOĞRULANMALI #6, theme1.xml is deliberately
+//    not opened). Falls back to a default bullet character, flagged
+//    unresolved -- unrelated to counting, unchanged from v1.
+
+import { findChild, findChildren, getAttr } from "./xml-scan.js";
+import { W_NS } from "./ns.js";
+
+export const DEFAULT_BULLET = "•";
+
+const PUA_START = 0xe000;
+const PUA_END = 0xf8ff;
+
+/**
+ * Word's lowerLetter/upperLetter sequencing: the letter itself cycles a..z
+ * (NOT spreadsheet-column base-26 positional notation), and past z the
+ * letter REPEATS -- 27 is "aa" meaning "a" twice, not "aa" as a two-digit
+ * base-26 number. n is 1-based.
+ * @param {number} n
+ * @returns {string}
+ */
+function lowerLetterOf(n) {
+  const letter = String.fromCharCode(97 + ((n - 1) % 26));
+  const repeat = Math.floor((n - 1) / 26) + 1;
+  return letter.repeat(repeat);
+}
+
+/** @type {ReadonlyArray<[number, string]>} */
+const ROMAN_TABLE = Object.freeze([
+  [1000, "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"],
+]);
+
+/**
+ * @param {number} n  1-based, positive
+ * @returns {string}
+ */
+function lowerRomanOf(n) {
+  let out = "";
+  let remaining = n;
+  for (const [value, symbol] of ROMAN_TABLE) {
+    while (remaining >= value) {
+      out += symbol;
+      remaining -= value;
+    }
+  }
+  return out;
+}
+
+/**
+ * @param {string} numFmt
+ * @param {number} n  1-based
+ * @returns {string | null}  null for a numFmt this module does not format
+ */
+function formatOrdinal(numFmt, n) {
+  switch (numFmt) {
+    case "decimal":
+      return String(n);
+    case "lowerLetter":
+      return lowerLetterOf(n);
+    case "upperLetter":
+      return lowerLetterOf(n).toUpperCase();
+    case "lowerRoman":
+      return lowerRomanOf(n);
+    case "upperRoman":
+      return lowerRomanOf(n).toUpperCase();
+    default:
+      return null;
+  }
+}
+
+/**
+ * @typedef {
+ *   | {kind: "bullet", bulletMarker: string, bulletResolved: boolean}
+ *   | {kind: "ordinal", numFmt: string, lvlText: string, start: number}
+ *   | {kind: "unresolved"}
+ * } LevelDef
+ */
+
+/**
+ * @param {string | null} numFmt
+ * @param {string | null} lvlText
+ * @returns {{bulletMarker: string, bulletResolved: boolean} | null}  null if
+ *   numFmt is not "bullet" (an ordinal level, resolved per-occurrence instead)
+ */
+function resolveBullet(numFmt, lvlText) {
+  if (numFmt !== "bullet") return null;
+  if (lvlText !== null && lvlText.length > 0) {
+    const cp = lvlText.codePointAt(0);
+    if (cp !== undefined && (cp < PUA_START || cp > PUA_END)) {
+      return { bulletMarker: lvlText, bulletResolved: true };
+    }
+  }
+  // Missing lvlText, or a PUA codepoint this importer cannot map to a real
+  // glyph without loading the level's font (not implemented, see header).
+  return { bulletMarker: DEFAULT_BULLET, bulletResolved: false };
+}
+
+/**
+ * `word/numbering.xml`'s root -> `Map<numId, Map<ilvl, LevelDef>>`. Every
+ * numId/ilvl pair the document *declares* is captured once here; counting
+ * itself happens later, per paragraph occurrence, via `createNumberingCounter`.
+ * @param {import("./xml-scan.js").XmlElement} numberingRoot
+ * @returns {Map<string, Map<string, LevelDef>>}
+ */
+export function parseNumbering(numberingRoot) {
+  /** @type {Map<string, string>} numId -> abstractNumId */
+  const numToAbstract = new Map();
+  for (const numEl of findChildren(numberingRoot, W_NS, "num")) {
+    const numId = getAttr(numEl, W_NS, "numId");
+    // w:lvlOverride (whose own children can include w:startOverride, a
+    // per-INSTANCE start value that would silently outrank the abstract
+    // level's own w:start below) -- measured 0/474 real corpus w:num
+    // entries (and, independently, 0/30 word/numbering.xml-carrying
+    // documents for w:startOverride specifically, 2026-08-31). Not
+    // implemented: rather than silently using the abstract default and
+    // producing a WRONG start count for a corpus-external document that
+    // does carry one, this throws loudly the moment it is seen.
+    if (findChild(numEl, W_NS, "lvlOverride") !== undefined) {
+      throw new Error(
+        `numbering.js: w:num[numId=${numId ?? "?"}] carries a w:lvlOverride ` +
+          "(possibly w:startOverride) -- not implemented (measured 0/474 real corpus " +
+          "w:num entries carry one); the counter would silently use the abstract " +
+          "level's own w:start instead of this instance's override, producing a wrong count",
+      );
+    }
+    const abstractIdEl = findChild(numEl, W_NS, "abstractNumId");
+    const abstractId = abstractIdEl ? getAttr(abstractIdEl, W_NS, "val") : undefined;
+    if (numId !== undefined && abstractId !== undefined) {
+      numToAbstract.set(numId, abstractId);
+    }
+  }
+
+  /** @type {Map<string, Map<string, LevelDef>>} abstractNumId -> ilvl -> LevelDef */
+  const abstractLevels = new Map();
+  for (const absEl of findChildren(numberingRoot, W_NS, "abstractNum")) {
+    const absId = getAttr(absEl, W_NS, "abstractNumId");
+    if (absId === undefined) continue;
+    /** @type {Map<string, LevelDef>} */
+    const levels = new Map();
+    for (const lvlEl of findChildren(absEl, W_NS, "lvl")) {
+      const ilvl = getAttr(lvlEl, W_NS, "ilvl");
+      if (ilvl === undefined) continue;
+      const numFmtEl = findChild(lvlEl, W_NS, "numFmt");
+      const numFmt = numFmtEl ? (getAttr(numFmtEl, W_NS, "val") ?? null) : null;
+      const lvlTextEl = findChild(lvlEl, W_NS, "lvlText");
+      const lvlText = lvlTextEl ? (getAttr(lvlTextEl, W_NS, "val") ?? null) : null;
+
+      const bullet = resolveBullet(numFmt, lvlText);
+      if (bullet !== null) {
+        levels.set(ilvl, { kind: "bullet", ...bullet });
+        continue;
+      }
+      if (numFmt !== null && formatOrdinal(numFmt, 1) !== null) {
+        const startEl = findChild(lvlEl, W_NS, "start");
+        const startVal = startEl ? Number.parseInt(getAttr(startEl, W_NS, "val") ?? "1", 10) : 1;
+        levels.set(ilvl, {
+          kind: "ordinal",
+          numFmt,
+          lvlText: lvlText !== null && lvlText.length > 0 ? lvlText : "%1.",
+          start: Number.isFinite(startVal) ? startVal : 1,
+        });
+        continue;
+      }
+      // An unrecognized numFmt (none observed in the corpus -- e.g.
+      // chineseCounting, ordinalText). Do not guess a glyph or a counter for it.
+      levels.set(ilvl, { kind: "unresolved" });
+    }
+    abstractLevels.set(absId, levels);
+  }
+
+  /** @type {Map<string, Map<string, LevelDef>>} */
+  const markersByNumId = new Map();
+  for (const [numId, absId] of numToAbstract) {
+    const levels = abstractLevels.get(absId);
+    if (levels !== undefined) {
+      markersByNumId.set(numId, levels);
+    }
+  }
+  return markersByNumId;
+}
+
+/**
+ * A running counter over (numId, ilvl), advanced once per paragraph
+ * OCCURRENCE by calling `next` in DOCUMENT ORDER -- the only order this
+ * makes sense in, since "the next item in this list" is a document-order
+ * concept, not a per-container or per-page one (measured against real Word:
+ * a list continues across a container/page boundary). Scope is therefore the
+ * WHOLE document: one counter instance is created per `convertDocument` call
+ * (import.js) and threaded through every anchor/container/paragraph that
+ * call processes, in the single sequential pass `collectAnchors` + the
+ * anchor loop already walk the document in.
+ *
+ * Multi-level restart (OOXML default, w:lvlRestart not implemented -- 0/474
+ * real corpus w:num entries carry it): encountering ANY level of a numId
+ * resets every DEEPER level's counter for that SAME numId, so a fresh "a."
+ * at ilvl 0 restarts a sub-list's "i., ii., ..." at ilvl 1 back to "i.".
+ * Encountering ilvl 1 again with NO intervening ilvl 0 (e.g. across a
+ * container boundary) does NOT reset it -- it continues.
+ *
+ * @param {Map<string, Map<string, import("./numbering.js").LevelDef>>} numDefs
+ */
+export function createNumberingCounter(numDefs) {
+  /** @type {Map<string, Map<string, number>>} numId -> ilvl -> current count */
+  const counts = new Map();
+
+  /**
+   * @param {string} numId
+   * @param {string} ilvl
+   * @returns {{marker: string, resolved: boolean} | undefined}  undefined if
+   *   this (numId, ilvl) has no numbering.xml definition at all -- the
+   *   caller (import.js) falls back to DEFAULT_BULLET, this module never guesses
+   */
+  function next(numId, ilvl) {
+    const level = numDefs.get(numId)?.get(ilvl);
+    if (level === undefined || level.kind === "unresolved") {
+      return undefined;
+    }
+    if (level.kind === "bullet") {
+      // Bullets are not counted, but encountering ANY level (bullet or
+      // ordinal) still restarts deeper ordinal levels of the same numId --
+      // the restart rule is about level hierarchy, not format.
+      resetDeeperLevels(numId, ilvl);
+      return { marker: level.bulletMarker, resolved: level.bulletResolved };
+    }
+
+    let byIlvl = counts.get(numId);
+    if (byIlvl === undefined) {
+      byIlvl = new Map();
+      counts.set(numId, byIlvl);
+    }
+    const current = byIlvl.get(ilvl);
+    const n = current === undefined ? level.start : current + 1;
+    byIlvl.set(ilvl, n);
+    resetDeeperLevels(numId, ilvl);
+
+    const formatted = formatOrdinal(level.numFmt, n);
+    // formatOrdinal cannot fail here: parseNumbering only assigns kind:
+    // "ordinal" when formatOrdinal(numFmt, 1) already returned non-null.
+    const marker = level.lvlText.replace(/%\d/g, formatted ?? "");
+    return { marker, resolved: true };
+  }
+
+  /**
+   * @param {string} numId
+   * @param {string} ilvl
+   */
+  function resetDeeperLevels(numId, ilvl) {
+    const byIlvl = counts.get(numId);
+    if (byIlvl === undefined) return;
+    const thisDepth = Number.parseInt(ilvl, 10);
+    for (const trackedIlvl of [...byIlvl.keys()]) {
+      if (Number.parseInt(trackedIlvl, 10) > thisDepth) {
+        byIlvl.delete(trackedIlvl);
+      }
+    }
+  }
+
+  return { next };
+}