@forevka/wordcanvas 0.7.0 → 0.7.1

package/dist-lib/builder.js

@@ -1,18 +1,19 @@
-import { d as P, B as u } from "./blockFactory-Bcy0U40y.js";
-import { d as p, D as k, a as w } from "./lists-BegzmTmD.js";
-import { B as x } from "./browser-5Sv4CuNy.js";
-import { runImport as S } from "./import.js";
-function B(s) {
+import { d as v, B as k, s as B } from "./blockFactory-CUI4Rqiq.js";
+import { d as y, D as C, a as R, b as I, n as F, m as A } from "./lists-Sc5I40JO.js";
+import { b as L, g as D } from "./toc-B6VpkJge.js";
+import { t as x, B as w } from "./browser-DkKxreJM.js";
+import { b as E, e as T, r as H } from "./pipeline-CbxmCE84.js";
+function N(a) {
   let t = "";
-  for (let i = 0; i < s.length; i += 32768)
-    t += String.fromCharCode(...s.subarray(i, i + 32768));
+  for (let i = 0; i < a.length; i += 32768)
+    t += String.fromCharCode(...a.subarray(i, i + 32768));
   return btoa(t);
 }
-function m(s, t) {
-  const e = s instanceof ArrayBuffer ? new Uint8Array(s) : s;
-  return `data:${t};base64,${B(e)}`;
+function S(a, t) {
+  const e = a instanceof ArrayBuffer ? new Uint8Array(a) : a;
+  return `data:${t};base64,${N(e)}`;
 }
-class v {
+class O {
   constructor(t, e, i) {
     this.parent = t, this.ctx = e, this.para = i;
   }
@@ -29,10 +30,14 @@ class v {
     for (const i of this.para.runs) Object.assign(i.style, e.char);
     return Object.assign(this.charPatch, e.char), this;
   }
+  /** Append a run, swapping out the empty placeholder a textless paragraph holds.
+   *  Shared by text() and every inline-content emitter (field/sdt/footnote/…). */
+  pushRun(t) {
+    return this.para.runs.length === 1 && this.para.runs[0].text === "" ? this.para.runs[0] = t : this.para.runs.push(t), this;
+  }
   /** Append a run. Inherits the scope's accrued char formatting; `style` wins. */
   text(t, e) {
-    const i = this.ctx.run(t, { ...this.charPatch, ...e });
-    return this.para.runs.length === 1 && this.para.runs[0].text === "" ? this.para.runs[0] = i : this.para.runs.push(i), this;
+    return this.pushRun(this.ctx.run(t, { ...this.charPatch, ...e }));
   }
   applyChar(t) {
     Object.assign(this.charPatch, t);
@@ -67,6 +72,123 @@ class v {
   link(t) {
     return this.applyChar({ link: t });
   }
+  /** Remove a char property from the scope default AND every existing run (the
+   *  exactOptional-safe way to toggle an optional CharStyle field off). */
+  clearChar(t) {
+    delete this.charPatch[t];
+    for (const e of this.para.runs) delete e.style[t];
+    return this;
+  }
+  superscript(t = !0) {
+    return t ? this.applyChar({ verticalAlign: "super" }) : this.clearChar("verticalAlign");
+  }
+  subscript(t = !0) {
+    return t ? this.applyChar({ verticalAlign: "sub" }) : this.clearChar("verticalAlign");
+  }
+  letterSpacing(t) {
+    return this.applyChar({ letterSpacingPx: t });
+  }
+  /** Hidden text — kept in the model + .docx, never laid out/painted. */
+  hidden(t = !0) {
+    return t ? this.applyChar({ hidden: !0 }) : this.clearChar("hidden");
+  }
+  // ---- inline fields -------------------------------------------------------
+  /** Register a built-in field def and append its (fieldId-tagged) result run.
+   *  PAGE/NUMPAGES emit a live `{page}`/`{pages}` token; DATE/TIME/IF materialize
+   *  via the shared evaluator so the builder agrees with the editor. */
+  emitField(t, e) {
+    const i = this.ctx.doc.fields ??= {}, s = this.ctx.ids.next();
+    i[s] = { id: s, instruction: E(t), name: t.type, kind: "builtin", spec: t };
+    const r = T(t, this.ctx.charDefault, { now: e?.now ?? /* @__PURE__ */ new Date() }), n = r.kind === "token" ? r.token : r.runs.map((o) => o.text).join("");
+    return this.pushRun(this.ctx.run(n, { ...this.charPatch, ...e?.style, fieldId: s }));
+  }
+  /** Insert any built-in field from its typed spec. */
+  field(t, e) {
+    return this.emitField(t, e);
+  }
+  pageField(t) {
+    return this.emitField(t ? { type: "PAGE", numFmt: t } : { type: "PAGE" });
+  }
+  numPagesField(t) {
+    return this.emitField(t ? { type: "NUMPAGES", numFmt: t } : { type: "NUMPAGES" });
+  }
+  dateField(t = "M/d/yyyy", e) {
+    return this.emitField({ type: "DATE", format: t }, e);
+  }
+  timeField(t = "h:mm AM/PM", e) {
+    return this.emitField({ type: "TIME", format: t }, e);
+  }
+  /** Conditional field. Branch results are plain text (matching the editor's
+   *  field constructor — rich branch content stays raw-model only). */
+  ifField(t, e, i, s, r) {
+    return this.emitField({
+      type: "IF",
+      operandA: t,
+      op: e,
+      operandB: i,
+      trueRuns: [this.ctx.run(s)],
+      falseRuns: [this.ctx.run(r)]
+    });
+  }
+  /** A non-built-in (host-resolved) field: verbatim instruction + cached result.
+   *  The escape hatch for PAGEREF/REF/SEQ/STYLEREF/etc. (see crossReference). */
+  customField(t, e, i) {
+    const s = this.ctx.doc.fields ??= {}, r = this.ctx.ids.next(), n = i?.name ?? t.trim().split(/\s+/)[0]?.toUpperCase() ?? "FIELD";
+    return s[r] = { id: r, instruction: t, name: n, kind: "custom" }, this.pushRun(this.ctx.run(e, { ...this.charPatch, ...i?.style, fieldId: r }));
+  }
+  /** A cross-reference to a bookmark, as a REF/PAGEREF field over customField. */
+  crossReference(t, e) {
+    const i = e?.kind ?? "ref", s = i === "pageRef" ? ` PAGEREF ${t} \\h ` : ` REF ${t} \\h `, r = e?.resultText ?? (i === "pageRef" ? "1" : t);
+    return this.customField(s, r, { name: i === "pageRef" ? "PAGEREF" : "REF" });
+  }
+  // ---- inline content controls (SDT) ---------------------------------------
+  emitSdt(t, e, i) {
+    const s = this.ctx.doc.sdts ??= {}, r = this.ctx.ids.next();
+    return s[r] = t, this.pushRun(this.ctx.run(e, { ...this.charPatch, ...i, sdtId: r }));
+  }
+  /** Insert any content control from its props. */
+  contentControl(t, e, i) {
+    return this.emitSdt(t, e, i);
+  }
+  richTextControl(t, e) {
+    return this.emitSdt({ type: "richText", ...e }, t);
+  }
+  plainTextControl(t, e) {
+    return this.emitSdt({ type: "plainText", ...e }, t);
+  }
+  checkbox(t, e) {
+    return this.emitSdt({ type: "checkbox", checked: t, ...e }, t ? "☒" : "☐");
+  }
+  dropDown(t, e, i) {
+    return this.emitSdt({ type: "dropDown", listItems: e, ...i }, t);
+  }
+  comboBox(t, e, i) {
+    return this.emitSdt({ type: "comboBox", listItems: e, ...i }, t);
+  }
+  dateControl(t, e = "M/d/yyyy", i) {
+    return this.emitSdt({ type: "date", dateFormat: e, ...i }, t);
+  }
+  // ---- footnotes + bookmarks -----------------------------------------------
+  /** Append an auto-numbered footnote reference; the note body is a string (one
+   *  paragraph) or a StoryBuilder callback (rich, multi-paragraph). */
+  footnote(t) {
+    const e = this.ctx.doc.footnotes ??= {}, i = this.ctx.nextFootnoteNumber(), s = this.ctx.ids.next();
+    let r;
+    if (typeof t == "string")
+      r = [this.ctx.paragraph([this.ctx.run(t, { fontSizePx: 12 })], { spaceAfterPx: 0 })];
+    else {
+      const n = [];
+      t(new f(this.ctx, n)), r = n.filter((o) => o.kind === "paragraph"), r.length < n.length && this.ctx.warn("footnote-non-paragraph", "Footnote bodies hold paragraphs only — non-paragraph blocks were dropped."), r.length === 0 && (r = [this.ctx.paragraph([])]);
+    }
+    return e[s] = r, this.pushRun(this.ctx.run(String(i), { footnoteRef: s, verticalAlign: "super", fontSizePx: 11 }));
+  }
+  /** Append `text` and bookmark exactly that run's range in this paragraph. */
+  bookmark(t, e, i) {
+    const s = this.ctx.doc.bookmarks ??= {}, r = x(this.para.runs).length;
+    this.pushRun(this.ctx.run(e, { ...this.charPatch, ...i }));
+    const n = x(this.para.runs).length;
+    return s[t] = { start: { blockId: this.para.id, offset: r }, end: { blockId: this.para.id, offset: n } }, this;
+  }
   align(t) {
     return this.para.style.align = t, this;
   }
@@ -106,6 +228,12 @@ class v {
   pageBreak() {
     return this.parent.pageBreak();
   }
+  columnBreak() {
+    return this.parent.columnBreak();
+  }
+  bookmarkRange(t, e) {
+    return this.parent.bookmarkRange(t, e);
+  }
   // ---- document-level delegators (only when the parent is the root builder) -
   header(t, e) {
     return this.parent.header(t, e);
@@ -122,16 +250,31 @@ class v {
   build() {
     return this.parent.build();
   }
+  tableOfContents(t) {
+    return this.parent.tableOfContents(t);
+  }
+  sectionBreak(t) {
+    return this.parent.sectionBreak(t);
+  }
+  defaultStyle(t) {
+    return this.parent.defaultStyle(t);
+  }
+  listDefinition(t, e) {
+    return this.parent.listDefinition(t, e);
+  }
+  tableStylePreset(t, e) {
+    return this.parent.tableStylePreset(t, e);
+  }
 }
-const g = { spaceAfterPx: 0, lineHeight: 1.35 };
-class L {
+const P = { spaceAfterPx: 0, lineHeight: 1.35 };
+class W {
   constructor(t, e = {}) {
     this.ctx = t, this.opts = e, this.fractions = e.colFractions;
   }
   tableRows = [];
   fractions;
   row(t) {
-    const e = new C(this.ctx);
+    const e = new U(this.ctx);
     if (typeof t == "function") t(e);
     else for (const i of t) e.cell(i);
     return this.tableRows.push({ cells: e.cells }), this;
@@ -145,82 +288,104 @@ class L {
   }
   /** Materialize the TableBlock (called by the owning scope's .table()). */
   toBlock() {
-    if (this.tableRows.length === 0 && (this.ctx.warn("table-empty", "A table was built with no rows — a single empty cell was inserted."), this.row([""])), this.opts.headerRow) {
-      for (const e of this.tableRows[0].cells)
-        for (const i of e.blocks)
-          if (i.kind === "paragraph") for (const r of i.runs) r.style.bold = !0;
-    }
-    const t = { kind: "table", id: this.ctx.ids.next(), revision: 0, rows: this.tableRows };
+    this.tableRows.length === 0 && (this.ctx.warn("table-empty", "A table was built with no rows — a single empty cell was inserted."), this.row([""]));
+    const t = this.opts.style ? this.ctx.tableStyle(this.opts.style) : void 0, e = this.opts.headerRow ?? t?.headerRow ?? !1;
+    this.tableRows.forEach((s, r) => {
+      const n = e && r === 0;
+      for (const o of s.cells) {
+        if (n) {
+          const h = { bold: !0, ...t?.headerChar };
+          for (const l of o.blocks)
+            if (l.kind === "paragraph") for (const u of l.runs) Object.assign(u.style, h);
+        }
+        if (o.shading === void 0) {
+          const h = n ? t?.headerShading : (r % 2 === 1 ? t?.stripeShading : void 0) ?? t?.shading;
+          h !== void 0 && (o.shading = h);
+        }
+        o.borders === void 0 && t?.borders && (o.borders = t.borders);
+      }
+    });
+    const i = { kind: "table", id: this.ctx.ids.next(), revision: 0, rows: this.tableRows };
     if (this.fractions && this.fractions.length > 0) {
-      const e = this.fractions.reduce((i, r) => i + r, 0);
-      e > 0 && (t.colFractions = this.fractions.map((i) => i / e));
+      const s = this.fractions.reduce((r, n) => r + n, 0);
+      s > 0 && (i.colFractions = this.fractions.map((r) => r / s));
     }
-    return t;
+    return i;
   }
 }
-class C {
+class U {
   constructor(t) {
     this.ctx = t;
   }
   cells = [];
   cell(t, e) {
     const i = [];
-    let r;
+    let s;
     if (typeof t == "function")
-      t(new f(this.ctx, i)), r = e ?? {};
+      t(new f(this.ctx, i)), s = e ?? {};
     else {
-      r = typeof t == "string" ? { ...e, text: t } : { ...t, ...e };
-      const a = { ...g };
-      r.align !== void 0 && (a.align = r.align), i.push(this.ctx.paragraph([this.ctx.run(r.text ?? "", r.style ?? {})], a));
+      s = typeof t == "string" ? { ...e, text: t } : { ...t, ...e };
+      const n = { ...P };
+      s.align !== void 0 && (n.align = s.align), i.push(this.ctx.paragraph([this.ctx.run(s.text ?? "", s.style ?? {})], n));
     }
-    i.length === 0 && i.push(this.ctx.paragraph([], g));
-    const n = { id: this.ctx.ids.next(), blocks: i };
-    return r.colSpan !== void 0 && r.colSpan > 1 && (n.colSpan = r.colSpan), r.rowSpan !== void 0 && r.rowSpan > 1 && (n.rowSpan = r.rowSpan), r.shading !== void 0 && (n.shading = r.shading), r.borders !== void 0 && (n.borders = r.borders), r.margin !== void 0 && (n.margin = r.margin), this.cells.push(n), this;
+    i.length === 0 && i.push(this.ctx.paragraph([], P));
+    const r = { id: this.ctx.ids.next(), blocks: i };
+    return s.colSpan !== void 0 && s.colSpan > 1 && (r.colSpan = s.colSpan), s.rowSpan !== void 0 && s.rowSpan > 1 && (r.rowSpan = s.rowSpan), s.shading !== void 0 && (r.shading = s.shading), s.borders !== void 0 && (r.borders = s.borders), s.margin !== void 0 && (r.margin = s.margin), this.cells.push(r), this;
   }
 }
 class f {
   ctx;
   blocks;
   pendingPageBreak = !1;
+  pendingColumnBreak = !1;
   constructor(t, e) {
     this.ctx = t, this.blocks = e;
   }
-  /** Append a block, honoring a pending pageBreak(). Only paragraphs carry
-   *  pageBreakBefore, so a break before a table/image lands on an injected
+  /** Append a block, honoring a pending page/column break(). Only paragraphs
+   *  carry the break flag, so a break before a table/image lands on an injected
    *  empty paragraph (same trick as the docx import mapper). */
   push(t) {
-    this.pendingPageBreak && (t.kind === "paragraph" ? t.style.pageBreakBefore = !0 : this.blocks.push(this.ctx.paragraph([], { pageBreakBefore: !0 })), this.pendingPageBreak = !1), this.blocks.push(t);
+    if (this.pendingPageBreak || this.pendingColumnBreak) {
+      if (t.kind === "paragraph")
+        this.pendingPageBreak && (t.style.pageBreakBefore = !0), this.pendingColumnBreak && (t.style.columnBreakBefore = !0);
+      else {
+        const e = {};
+        this.pendingPageBreak && (e.pageBreakBefore = !0), this.pendingColumnBreak && (e.columnBreakBefore = !0), this.blocks.push(this.ctx.paragraph([], e));
+      }
+      this.pendingPageBreak = !1, this.pendingColumnBreak = !1;
+    }
+    this.blocks.push(t);
   }
   /** Start a paragraph. The returned scope styles THIS paragraph and delegates
    *  block-starting calls back here, so the chain continues seamlessly. */
   paragraph(t, e) {
-    const i = t !== void 0 ? [this.ctx.run(t, e ?? {})] : [], r = this.ctx.paragraph(i);
-    return this.push(r), new v(this, this.ctx, r);
+    const i = t !== void 0 ? [this.ctx.run(t, e ?? {})] : [], s = this.ctx.paragraph(i);
+    return this.push(s), new O(this, this.ctx, s);
   }
   table(t, e) {
-    const i = new L(this.ctx, e);
+    const i = new W(this.ctx, e);
     return typeof t == "function" ? t(i) : i.rows(t), this.push(i.toBlock()), this;
   }
   /** Insert an image from a URL (https:/data:) or raw bytes (inlined as data:). */
   image(t, e) {
     if (!Number.isFinite(e?.widthPx) || !Number.isFinite(e?.heightPx) || e.widthPx <= 0 || e.heightPx <= 0)
       throw new TypeError("image() requires positive widthPx and heightPx (no DOM to auto-measure in Node).");
-    const i = typeof t == "string" ? t : m(t.data, t.mime);
+    const i = typeof t == "string" ? t : S(t.data, t.mime);
     return this.push(this.ctx.image(i, e.widthPx, e.heightPx, e.align ?? "left", e.wrap)), this;
   }
   /** One paragraph per item, marked as list members. Definitions resolve to the
    *  template's (via listId), or the editor-default bullet/number definitions
    *  registered on demand. */
   list(t, e = {}) {
-    const i = e.kind ?? "bullet", r = this.ctx.doc.lists ??= {};
-    let n = e.listId;
-    n !== void 0 ? r[n] || (this.ctx.warn(
-      `list-missing:${n}`,
-      `List definition "${n}" is not in the document — a default ${i} definition was registered under that id.`
-    ), r[n] = { ...p(i === "number" ? "decimal" : "bullet"), id: n }) : (n = i === "number" ? k : w, r[n] || (r[n] = p(i === "number" ? "decimal" : "bullet")));
-    for (const a of t) {
-      const o = typeof a == "string" ? { text: a } : a, h = Math.max(0, Math.min(8, o.level ?? e.level ?? 0));
-      this.push(this.ctx.paragraph([this.ctx.run(o.text, o.style ?? {})], { list: { listId: n, level: h } }));
+    const i = e.kind ?? "bullet", s = this.ctx.doc.lists ??= {};
+    let r = e.listId;
+    r !== void 0 ? s[r] || (this.ctx.warn(
+      `list-missing:${r}`,
+      `List definition "${r}" is not in the document — a default ${i} definition was registered under that id.`
+    ), s[r] = { ...y(i === "number" ? "decimal" : "bullet"), id: r }) : (r = i === "number" ? C : R, s[r] || (s[r] = y(i === "number" ? "decimal" : "bullet")));
+    for (const n of t) {
+      const o = typeof n == "string" ? { text: n } : n, h = Math.max(0, Math.min(8, o.level ?? e.level ?? 0));
+      this.push(this.ctx.paragraph([this.ctx.run(o.text, o.style ?? {})], { list: { listId: r, level: h } }));
     }
     return this;
   }
@@ -234,81 +399,104 @@ class f {
   pageBreak() {
     return this.pendingPageBreak = !0, this;
   }
+  /** The NEXT block starts a new newspaper column (Ctrl+Shift+Enter). A trailing
+   *  column break with no following block is a no-op, matching Word. */
+  columnBreak() {
+    return this.pendingColumnBreak = !0, this;
+  }
+  /** Bookmark everything the callback appends to this story (multi-paragraph
+   *  span). For a precise inline span use ParagraphBuilder.bookmark(name, text). */
+  bookmarkRange(t, e) {
+    const i = this.blocks.length;
+    e(this);
+    const s = this.blocks.slice(i).filter((h) => h.kind === "paragraph");
+    if (s.length === 0)
+      return this.ctx.warn(`bookmark-empty:${t}`, `bookmarkRange("${t}") wrapped no paragraphs — no bookmark was recorded.`), this;
+    const r = s[0], n = s[s.length - 1], o = this.ctx.doc.bookmarks ??= {};
+    return o[t] = {
+      start: { blockId: r.id, offset: 0 },
+      end: { blockId: n.id, offset: x(n.runs).length }
+    }, this;
+  }
   /** A trailing pageBreak() with no following block still needs to exist —
-   *  materialize it as an empty page-broken paragraph (called by build()). */
+   *  materialize it as an empty page-broken paragraph (called by build()). A
+   *  pending column break alone is dropped (Word ignores a trailing one). */
   flushPendingPageBreak() {
-    this.pendingPageBreak && (this.blocks.push(this.ctx.paragraph([], { pageBreakBefore: !0 })), this.pendingPageBreak = !1);
+    this.pendingPageBreak && (this.blocks.push(this.ctx.paragraph([], { pageBreakBefore: !0 })), this.pendingPageBreak = !1, this.pendingColumnBreak = !1);
   }
 }
-function A(s, t) {
-  const e = s instanceof Uint8Array ? s : new Uint8Array(s), i = S(e, void 0, { collectMediaBytes: !0 }), r = i.doc, n = new Map(i.media.map((a) => [a.src, m(a.bytes, a.mime)]));
-  if (n.size > 0) {
-    const a = (o) => {
+function M(a, t) {
+  const e = a instanceof Uint8Array ? a : new Uint8Array(a), i = H(e, void 0, { collectMediaBytes: !0 }), s = i.doc, r = new Map(i.media.map((n) => [n.src, S(n.bytes, n.mime)]));
+  if (r.size > 0) {
+    const n = (o) => {
       for (const h of o ?? [])
         if (h.kind === "image") {
-          const l = n.get(h.src);
+          const l = r.get(h.src);
           l && (h.src = l);
         } else if (h.kind === "table")
-          for (const l of h.rows) for (const y of l.cells) a(y.blocks);
+          for (const l of h.rows) for (const u of l.cells) n(u.blocks);
     };
-    a(r.blocks);
-    for (const o of x) a(r.section[o]);
+    n(s.blocks);
+    for (const o of w) n(s.section[o]);
   }
-  return t || (r.blocks = [], delete r.footnotes, H(r)), { doc: r, warnings: i.warnings };
+  return t || (s.blocks = [], delete s.footnotes, $(s)), { doc: s, warnings: i.warnings };
 }
-function H(s) {
-  const t = /* @__PURE__ */ new Set(), e = /* @__PURE__ */ new Set(), i = (r) => {
-    for (const n of r ?? [])
-      if (t.add(n.id), n.kind === "paragraph")
-        for (const a of n.runs) a.style.sdtId && e.add(a.style.sdtId);
-      else if (n.kind === "table")
-        for (const a of n.rows) for (const o of a.cells) i(o.blocks);
+function $(a) {
+  const t = /* @__PURE__ */ new Set(), e = /* @__PURE__ */ new Set(), i = (s) => {
+    for (const r of s ?? [])
+      if (t.add(r.id), r.kind === "paragraph")
+        for (const n of r.runs) n.style.sdtId && e.add(n.style.sdtId);
+      else if (r.kind === "table")
+        for (const n of r.rows) for (const o of n.cells) i(o.blocks);
   };
-  i(s.blocks);
-  for (const r of x) i(s.section[r]);
-  if (s.bookmarks) {
-    for (const [r, n] of Object.entries(s.bookmarks))
-      (!t.has(n.start.blockId) || !t.has(n.end.blockId)) && delete s.bookmarks[r];
-    Object.keys(s.bookmarks).length === 0 && delete s.bookmarks;
-  }
-  if (s.sdts) {
-    for (const r of Object.keys(s.sdts))
-      e.has(r) || delete s.sdts[r];
-    Object.keys(s.sdts).length === 0 && delete s.sdts;
+  i(a.blocks);
+  for (const s of w) i(a.section[s]);
+  if (a.bookmarks) {
+    for (const [s, r] of Object.entries(a.bookmarks))
+      (!t.has(r.start.blockId) || !t.has(r.end.blockId)) && delete a.bookmarks[s];
+    Object.keys(a.bookmarks).length === 0 && delete a.bookmarks;
+  }
+  if (a.sdts) {
+    for (const s of Object.keys(a.sdts))
+      e.has(s) || delete a.sdts[s];
+    Object.keys(a.sdts).length === 0 && delete a.sdts;
   }
 }
-const R = (s) => s * 96, U = (s) => s * 96 / 2.54, E = (s) => s * 96 / 72, F = (s) => s / 15, I = {
+const Z = (a) => a * 96, J = (a) => a * 96 / 2.54, Q = (a) => a * 96 / 72, V = (a) => a / 15, z = {
   Letter: { pageWidthPx: 816, pageHeightPx: 1056 },
   Legal: { pageWidthPx: 816, pageHeightPx: 1344 },
   A4: { pageWidthPx: 794, pageHeightPx: 1123 },
   A3: { pageWidthPx: 1123, pageHeightPx: 1587 },
   Tabloid: { pageWidthPx: 1056, pageHeightPx: 1632 }
-}, c = 96;
-function b(s) {
-  return typeof s == "string" ? I[s] : s;
+}, p = 96;
+function g(a) {
+  return typeof a == "string" ? z[a] : a;
 }
-class d extends f {
+class b extends f {
   /** Start from a blank document (default stylesheet, US Letter, 1in margins). */
   static create(t = {}) {
-    const e = b(t.pageSize ?? "Letter"), i = {
+    const e = g(t.pageSize ?? "Letter"), i = {
       section: {
         pageWidthPx: e.pageWidthPx,
         pageHeightPx: e.pageHeightPx,
-        marginPx: { top: c, right: c, bottom: c, left: c, ...t.margins }
+        marginPx: { top: p, right: p, bottom: p, left: p, ...t.margins }
       },
       blocks: [],
-      stylesheet: t.stylesheet ?? P()
+      stylesheet: t.stylesheet ?? v()
     };
-    return new d(new u(i, t.idSeed));
+    return new b(new k(i, t.idSeed));
   }
   /** Start from a .docx template: its stylesheet, list definitions, page setup,
    *  and header/footer bands carry over (body content is discarded unless
    *  keepBody). Import warnings surface on `builder.warnings`. */
   static async fromTemplate(t, e = {}) {
-    const { doc: i, warnings: r } = A(t, e.keepBody ?? !1), n = new d(new u(i, e.idSeed));
-    for (const a of r) n.ctx.warn(a.code, a.message);
-    return n;
+    const { doc: i, warnings: s } = M(t, e.keepBody ?? !1), r = new b(new k(i, e.idSeed));
+    for (const n of s) r.ctx.warn(n.code, n.message);
+    return r;
   }
+  /** Set when .tableOfContents() ran — build() splices entries at the anchor. */
+  tocRequested = !1;
+  tocOpts = {};
   constructor(t) {
     super(t, t.doc.blocks);
   }
@@ -327,46 +515,113 @@ class d extends f {
     return this.band("footer", t, e);
   }
   band(t, e, i) {
-    const r = i.variant ?? "default", n = r === "default" ? t : `${t}${r === "first" ? "First" : "Even"}`, a = [];
-    return e(new f(this.ctx, a)), a.length === 0 && a.push(this.ctx.paragraph([])), this.ctx.doc.section[n] = a, this;
+    const s = i.variant ?? "default", r = s === "default" ? t : `${t}${s === "first" ? "First" : "Even"}`, n = [];
+    return e(new f(this.ctx, n)), n.length === 0 && n.push(this.ctx.paragraph([])), this.ctx.doc.section[r] = n, this;
   }
   /** Merge page geometry onto the section (template values are the base). */
   pageSetup(t) {
     const e = this.ctx.doc.section;
     if (t.pageSize !== void 0) {
-      const i = b(t.pageSize);
+      const i = g(t.pageSize);
       e.pageWidthPx = i.pageWidthPx, e.pageHeightPx = i.pageHeightPx;
     }
     if (t.orientation !== void 0) {
-      const i = t.orientation === "landscape", [r, n] = [e.pageWidthPx, e.pageHeightPx];
-      i !== r > n && (e.pageWidthPx = n, e.pageHeightPx = r);
+      const i = t.orientation === "landscape", [s, r] = [e.pageWidthPx, e.pageHeightPx];
+      i !== s > r && (e.pageWidthPx = r, e.pageHeightPx = s);
     }
     return t.margins !== void 0 && (e.marginPx = { ...e.marginPx, ...t.margins }), t.columns !== void 0 && (e.columns = { count: t.columns.count, gapPx: t.columns.gapPx ?? 48 }), t.headerDistancePx !== void 0 && (e.headerDistancePx = t.headerDistancePx), t.footerDistancePx !== void 0 && (e.footerDistancePx = t.footerDistancePx), t.pageNumberStart !== void 0 && (e.pageNumberStart = t.pageNumberStart), this;
   }
   /** Register (or override) a named style. Register BEFORE applying it —
    *  withStyle() resolves at call time, not at build(). */
   style(t) {
-    const e = this.ctx.stylesheet(), i = e.styles.findIndex((r) => r.id === t.id);
+    const e = this.ctx.stylesheet(), i = e.styles.findIndex((s) => s.id === t.id);
     return i >= 0 ? e.styles[i] = t : e.styles.push(t), this;
   }
+  /** Make `id` the document's default style and refresh the run/paragraph
+   *  defaults from it. Call EARLY — only content added afterwards inherits it. */
+  defaultStyle(t) {
+    const e = this.ctx.stylesheet();
+    return B(e, t) ? (e.defaultStyleId = t, this.ctx.refreshDefaults(), this) : (this.ctx.warn(`style-missing:${t}`, `.defaultStyle("${t}") — no such style in the stylesheet; default unchanged.`), this);
+  }
+  /** Register a custom list definition; reference it via .list(items,{listId:id}). */
+  listDefinition(t, e) {
+    const i = this.ctx.doc.lists ??= {};
+    return "levels" in e ? i[t] = { id: t, levels: e.levels } : e.kind === "bullet" ? i[t] = I(t, e.char) : e.kind === "number" ? i[t] = F(t, e.format, e.suffix ?? ".") : i[t] = { ...A(), id: t }, this;
+  }
+  /** Register (or override) a builder-only table-style preset — reusable cell
+   *  formatting applied via .table(rows, { style: name }). Resolved to concrete
+   *  cell properties at build time; nothing style-id-like enters the model. */
+  tableStylePreset(t, e) {
+    return this.ctx.tableStyles.set(t, e), this;
+  }
+  /** Insert a table of contents, built from the document's headings at build()
+   *  time (so headings added AFTER this call are still included). Pushes a
+   *  placeholder anchor now; build() replaces it with the entries. */
+  tableOfContents(t = {}) {
+    this.tocRequested = !0, this.tocOpts = t;
+    const e = {
+      useOutlineLevels: !0,
+      hyperlinks: t.hyperlink ?? !0,
+      hideInWeb: !0,
+      outlineRange: { from: 1, to: t.maxLevel ?? 3 }
+    };
+    this.ctx.doc.tocInstruction = L(e);
+    const i = this.ctx.paragraph([]);
+    return this.push(i), this.ctx.doc.tocAnchorBlockId = i.id, this;
+  }
+  /** End the current section and start a new one on the next page, with the
+   *  given per-section overrides (page size/orientation/margins, newspaper
+   *  columns, page-number restart, and its own header/footer bands). */
+  sectionBreak(t = {}) {
+    const e = this.compileSectionPatch(t), i = this.ctx.doc.blocks, s = i[i.length - 1];
+    return s && s.kind === "paragraph" ? s.style.sectionBreak = { type: "nextPage", props: e } : i.push(this.ctx.paragraph([], { sectionBreak: { type: "nextPage", props: e } })), this;
+  }
+  compileSectionPatch(t) {
+    const e = {}, i = this.ctx.doc.section;
+    if (t.pageSize !== void 0 || t.orientation !== void 0) {
+      let d = i.pageWidthPx, c = i.pageHeightPx;
+      if (t.pageSize !== void 0) {
+        const m = g(t.pageSize);
+        d = m.pageWidthPx, c = m.pageHeightPx;
+      }
+      t.orientation !== void 0 && t.orientation === "landscape" != d > c && ([d, c] = [c, d]), e.pageWidthPx = d, e.pageHeightPx = c;
+    }
+    t.margins !== void 0 && (e.marginPx = { ...i.marginPx, ...t.margins }), t.columns !== void 0 && (e.columns = t.columns === null ? null : { count: t.columns.count, gapPx: t.columns.gapPx ?? 48 }), t.pageNumberStart !== void 0 && (e.pageNumberStart = t.pageNumberStart);
+    const s = (d) => {
+      if (!d) return;
+      const c = [];
+      return d(new f(this.ctx, c)), c.length === 0 && c.push(this.ctx.paragraph([])), c;
+    }, r = s(t.header);
+    r && (e.header = r);
+    const n = s(t.footer);
+    n && (e.footer = n);
+    const o = s(t.headerFirst);
+    o && (e.headerFirst = o);
+    const h = s(t.footerFirst);
+    h && (e.footerFirst = h);
+    const l = s(t.headerEven);
+    l && (e.headerEven = l);
+    const u = s(t.footerEven);
+    return u && (e.footerEven = u), e;
+  }
   /** Snapshot the document: deep clone, guaranteed at least one paragraph.
    *  The builder remains usable (and unaffected by mutations of the result). */
   build() {
     this.flushPendingPageBreak();
-    const t = structuredClone(this.ctx.doc);
-    return t.blocks.length === 0 && t.blocks.push(this.ctx.paragraph([])), t;
+    let t = structuredClone(this.ctx.doc);
+    return this.tocRequested && t.tocAnchorBlockId !== void 0 && (t = D(t, this.tocOpts).doc), t.blocks.length === 0 && t.blocks.push(this.ctx.paragraph([])), t;
   }
 }
 export {
-  d as DocumentBuilder,
-  I as PAGE_SIZES,
-  v as ParagraphBuilder,
-  C as RowBuilder,
+  b as DocumentBuilder,
+  z as PAGE_SIZES,
+  O as ParagraphBuilder,
+  U as RowBuilder,
   f as StoryBuilder,
-  L as TableBuilder,
-  m as bytesToDataUrl,
-  U as cm,
-  R as inches,
-  E as pt,
-  F as twips
+  W as TableBuilder,
+  S as bytesToDataUrl,
+  J as cm,
+  Z as inches,
+  Q as pt,
+  V as twips
 };