@forevka/wordcanvas 0.7.0 → 0.7.1

package/dist-node/generate-toc.js

@@ -6,7 +6,7 @@ const __filename = __fileURLToPath(import.meta.url);
 const __dirname = __pathDirname(__filename);
 import {
   runImport
-} from "./chunk-GXFDF7UY.js";
+} from "./chunk-22JHAERT.js";
 import {
   el,
   escapeText,
@@ -16,10 +16,10 @@ import {
 } from "./chunk-4PDVRJF6.js";
 import {
   findMainDocumentPart
-} from "./chunk-2RCPB7UZ.js";
+} from "./chunk-6AJJMHKY.js";
 import {
   pageOfBlockMap
-} from "./chunk-TBSXA2I4.js";
+} from "./chunk-EGSAVPCC.js";
 import {
   strFromU8,
   strToU8,
@@ -28,14 +28,14 @@ import {
 } from "./chunk-5PUCGN47.js";
 import {
   createLayoutEngine
-} from "./chunk-IJLL6IFJ.js";
+} from "./chunk-RNB336F3.js";
 import {
   detectTocHeadings,
   inRange,
   parseTocInstruction,
   textOfRuns,
   tocEntryStyle
-} from "./chunk-XDUDPPJW.js";
+} from "./chunk-CDN6WU2P.js";
 import "./chunk-4ICCHZX4.js";
 import "./chunk-XSRSBST2.js";
 

package/dist-node/import.js

@@ -6,10 +6,10 @@ const __filename = __fileURLToPath(import.meta.url);
 const __dirname = __pathDirname(__filename);
 import {
   runImport
-} from "./chunk-GXFDF7UY.js";
-import "./chunk-2RCPB7UZ.js";
+} from "./chunk-22JHAERT.js";
+import "./chunk-6AJJMHKY.js";
 import "./chunk-5PUCGN47.js";
-import "./chunk-XDUDPPJW.js";
+import "./chunk-CDN6WU2P.js";
 import "./chunk-XSRSBST2.js";
 export {
   runImport

package/dist-node/recalc-docx.js

@@ -6,10 +6,10 @@ const __filename = __fileURLToPath(import.meta.url);
 const __dirname = __pathDirname(__filename);
 import {
   findMainDocumentPart
-} from "./chunk-2RCPB7UZ.js";
+} from "./chunk-6AJJMHKY.js";
 import {
   pageOfBlockMap
-} from "./chunk-TBSXA2I4.js";
+} from "./chunk-EGSAVPCC.js";
 import {
   strFromU8,
   strToU8,
@@ -18,8 +18,8 @@ import {
 } from "./chunk-5PUCGN47.js";
 import {
   createLayoutEngine
-} from "./chunk-IJLL6IFJ.js";
-import "./chunk-XDUDPPJW.js";
+} from "./chunk-RNB336F3.js";
+import "./chunk-CDN6WU2P.js";
 import "./chunk-4ICCHZX4.js";
 import "./chunk-XSRSBST2.js";
 

package/dist-node/recalc-docx.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/recalc/patchTocDocx.ts"],
-  "sourcesContent": ["// Patch a .docx's TOC page numbers IN PLACE \u2014 the faithful path for fixing an\n// externally-authored document (e.g. a C# render pipeline that emits a real Word\n// TOC field but can't compute page numbers). We import only to RUN THE LAYOUT and\n// learn each heading's page; we then surgically rewrite the cached PAGEREF result\n// digits in the ORIGINAL document.xml and re-zip. Everything else \u2014 the live TOC\n// field, PAGEREF/HYPERLINK fields, footer PAGE/NUMPAGES, styles, and any OOXML our\n// model doesn't represent \u2014 survives byte-for-byte. Because we never regenerate the\n// file through the export writer, there is no import\u2194export pagination drift.\n//\n// Limitation (documented, intentional): only arabic (\\d+) cached page numbers are\n// recalculated. A roman/alpha cached value is left untouched and counted in\n// `skipped` rather than being overwritten with a wrong arabic number.\n\nimport { strFromU8, strToU8, unzipSync, zipSync, type Unzipped } from \"fflate\";\nimport type { Document } from \"@cw/shared\";\nimport { findMainDocumentPart } from \"../import/docx/contentTypes\";\nimport { createLayoutEngine } from \"../layout/engine\";\nimport type { LayoutTree } from \"../layout/layoutTree\";\nimport { pageOfBlockMap } from \"./recalcToc\";\n\n/** bookmark name \u2192 displayed page number (as a string) of the block it starts at.\n *  The PAGEREF instruction in the XML references the same bookmark name, so this is\n *  how the layout's per-block page maps onto the document's fields. */\nexport function pageByBookmark(doc: Document, tree: LayoutTree): Record<string, string> {\n  const pageOfBlock = pageOfBlockMap(tree);\n  const out: Record<string, string> = {};\n  for (const [name, range] of Object.entries(doc.bookmarks ?? {})) {\n    const page = pageOfBlock.get(range.start.blockId);\n    if (page !== undefined) out[name] = String(page);\n  }\n  return out;\n}\n\nexport interface PatchResult {\n  bytes: Uint8Array;\n  /** PAGEREF cached numbers rewritten to a new value. */\n  changed: number;\n  /** PAGEREF results left untouched because the cached value was non-arabic. */\n  skipped: number;\n}\n\nconst PAGEREF_RE = /\\bPAGEREF\\s+(\"[^\"]+\"|\\S+)/;\n\n// fldChar (begin|separate|end) | instrText(content) | w:t(open)(content)(close)\nconst TOKEN_RE =\n  /<w:fldChar\\b[^>]*?w:fldCharType=\"(begin|separate|end)\"[^>]*?\\/?>|<w:instrText\\b[^>]*?>([\\s\\S]*?)<\\/w:instrText>|(<w:t\\b[^>]*?>)([\\s\\S]*?)(<\\/w:t>)/g;\n\ninterface Frame {\n  instr: string;\n  anchor?: string; // set when the field is a PAGEREF\n  sawSeparate: boolean;\n  done: boolean; // first result run handled\n  replaced: boolean; // we rewrote the number \u2192 blank any split remainder\n}\n\n/** Rewrite cached PAGEREF result digits in one document-part XML string. */\nfunction patchXml(xml: string, pages: Record<string, string>): { xml: string; changed: number; skipped: number } {\n  const stack: Frame[] = [];\n  let out = \"\";\n  let cursor = 0;\n  let changed = 0;\n  let skipped = 0;\n  TOKEN_RE.lastIndex = 0;\n  let m: RegExpExecArray | null;\n  while ((m = TOKEN_RE.exec(xml)) !== null) {\n    const top = stack[stack.length - 1];\n    let replacement: string | null = null; // non-null \u2192 replace this match's slice\n\n    if (m[1] !== undefined) {\n      // w:fldChar\n      if (m[1] === \"begin\") stack.push({ instr: \"\", sawSeparate: false, done: false, replaced: false });\n      else if (m[1] === \"separate\") {\n        if (top) top.sawSeparate = true;\n      } else stack.pop(); // \"end\"\n    } else if (m[2] !== undefined) {\n      // w:instrText\n      if (top) {\n        top.instr += m[2];\n        const pm = top.instr.match(PAGEREF_RE);\n        if (pm) top.anchor = pm[1]!.replace(/^\"|\"$/g, \"\");\n      }\n    } else {\n      // w:t \u2014 group 3 open, 4 content, 5 close\n      if (top?.anchor && top.sawSeparate) {\n        if (!top.done) {\n          top.done = true;\n          const num = pages[top.anchor];\n          if (num !== undefined && /^\\d+$/.test(m[4]!)) {\n            if (m[4] !== num) {\n              replacement = m[3]! + num + m[5]!;\n              changed++;\n              top.replaced = true;\n            }\n          } else if (num !== undefined && !/^\\d+$/.test(m[4]!.trim()) && m[4]!.trim().length > 0) {\n            skipped++; // non-arabic cached value \u2014 leave it (unsupported)\n          }\n        } else if (top.replaced && m[4] !== \"\") {\n          // Split number (\"1\",\"2\"): the full value went into the first run; blank the rest.\n          replacement = m[3]! + m[5]!;\n        }\n      }\n    }\n\n    if (replacement !== null) {\n      out += xml.slice(cursor, m.index) + replacement;\n      cursor = m.index + m[0].length;\n    }\n  }\n  out += xml.slice(cursor);\n  return { xml: out, changed, skipped };\n}\n\n/** Patch the cached TOC/cross-reference page numbers in a .docx, preserving every\n *  field and every other part. `pages` maps bookmark name \u2192 new page number. */\nexport function patchTocPageNumbers(docxBytes: Uint8Array, pages: Record<string, string>): PatchResult {\n  const parts: Unzipped = unzipSync(docxBytes);\n  const ctXml = parts[\"[Content_Types].xml\"];\n  const mainPart =\n    (ctXml ? findMainDocumentPart(strFromU8(ctXml)) : undefined) ?? \"word/document.xml\";\n  const docPart = parts[mainPart];\n  if (!docPart) return { bytes: docxBytes, changed: 0, skipped: 0 };\n\n  const { xml, changed, skipped } = patchXml(strFromU8(docPart), pages);\n  if (changed === 0) return { bytes: docxBytes, changed: 0, skipped };\n\n  parts[mainPart] = strToU8(xml);\n  return { bytes: zipSync(parts), changed, skipped };\n}\n\n/** Convenience: lay the doc out and patch the original bytes from it. The caller\n *  MUST have awaited installMeasureHost() first (layout measures text). */\nexport function patchTocFromLayout(docxBytes: Uint8Array, doc: Document): PatchResult {\n  const tree = createLayoutEngine().layout(doc);\n  return patchTocPageNumbers(docxBytes, pageByBookmark(doc, tree));\n}\n"],
+  "sourcesContent": ["// Patch a .docx's TOC page numbers IN PLACE \u2014 the faithful path for fixing an\r\n// externally-authored document (e.g. a C# render pipeline that emits a real Word\r\n// TOC field but can't compute page numbers). We import only to RUN THE LAYOUT and\r\n// learn each heading's page; we then surgically rewrite the cached PAGEREF result\r\n// digits in the ORIGINAL document.xml and re-zip. Everything else \u2014 the live TOC\r\n// field, PAGEREF/HYPERLINK fields, footer PAGE/NUMPAGES, styles, and any OOXML our\r\n// model doesn't represent \u2014 survives byte-for-byte. Because we never regenerate the\r\n// file through the export writer, there is no import\u2194export pagination drift.\r\n//\r\n// Limitation (documented, intentional): only arabic (\\d+) cached page numbers are\r\n// recalculated. A roman/alpha cached value is left untouched and counted in\r\n// `skipped` rather than being overwritten with a wrong arabic number.\r\n\r\nimport { strFromU8, strToU8, unzipSync, zipSync, type Unzipped } from \"fflate\";\r\nimport type { Document } from \"@cw/shared\";\r\nimport { findMainDocumentPart } from \"../import/docx/contentTypes\";\r\nimport { createLayoutEngine } from \"../layout/engine\";\r\nimport type { LayoutTree } from \"../layout/layoutTree\";\r\nimport { pageOfBlockMap } from \"./recalcToc\";\r\n\r\n/** bookmark name \u2192 displayed page number (as a string) of the block it starts at.\r\n *  The PAGEREF instruction in the XML references the same bookmark name, so this is\r\n *  how the layout's per-block page maps onto the document's fields. */\r\nexport function pageByBookmark(doc: Document, tree: LayoutTree): Record<string, string> {\r\n  const pageOfBlock = pageOfBlockMap(tree);\r\n  const out: Record<string, string> = {};\r\n  for (const [name, range] of Object.entries(doc.bookmarks ?? {})) {\r\n    const page = pageOfBlock.get(range.start.blockId);\r\n    if (page !== undefined) out[name] = String(page);\r\n  }\r\n  return out;\r\n}\r\n\r\nexport interface PatchResult {\r\n  bytes: Uint8Array;\r\n  /** PAGEREF cached numbers rewritten to a new value. */\r\n  changed: number;\r\n  /** PAGEREF results left untouched because the cached value was non-arabic. */\r\n  skipped: number;\r\n}\r\n\r\nconst PAGEREF_RE = /\\bPAGEREF\\s+(\"[^\"]+\"|\\S+)/;\r\n\r\n// fldChar (begin|separate|end) | instrText(content) | w:t(open)(content)(close)\r\nconst TOKEN_RE =\r\n  /<w:fldChar\\b[^>]*?w:fldCharType=\"(begin|separate|end)\"[^>]*?\\/?>|<w:instrText\\b[^>]*?>([\\s\\S]*?)<\\/w:instrText>|(<w:t\\b[^>]*?>)([\\s\\S]*?)(<\\/w:t>)/g;\r\n\r\ninterface Frame {\r\n  instr: string;\r\n  anchor?: string; // set when the field is a PAGEREF\r\n  sawSeparate: boolean;\r\n  done: boolean; // first result run handled\r\n  replaced: boolean; // we rewrote the number \u2192 blank any split remainder\r\n}\r\n\r\n/** Rewrite cached PAGEREF result digits in one document-part XML string. */\r\nfunction patchXml(xml: string, pages: Record<string, string>): { xml: string; changed: number; skipped: number } {\r\n  const stack: Frame[] = [];\r\n  let out = \"\";\r\n  let cursor = 0;\r\n  let changed = 0;\r\n  let skipped = 0;\r\n  TOKEN_RE.lastIndex = 0;\r\n  let m: RegExpExecArray | null;\r\n  while ((m = TOKEN_RE.exec(xml)) !== null) {\r\n    const top = stack[stack.length - 1];\r\n    let replacement: string | null = null; // non-null \u2192 replace this match's slice\r\n\r\n    if (m[1] !== undefined) {\r\n      // w:fldChar\r\n      if (m[1] === \"begin\") stack.push({ instr: \"\", sawSeparate: false, done: false, replaced: false });\r\n      else if (m[1] === \"separate\") {\r\n        if (top) top.sawSeparate = true;\r\n      } else stack.pop(); // \"end\"\r\n    } else if (m[2] !== undefined) {\r\n      // w:instrText\r\n      if (top) {\r\n        top.instr += m[2];\r\n        const pm = top.instr.match(PAGEREF_RE);\r\n        if (pm) top.anchor = pm[1]!.replace(/^\"|\"$/g, \"\");\r\n      }\r\n    } else {\r\n      // w:t \u2014 group 3 open, 4 content, 5 close\r\n      if (top?.anchor && top.sawSeparate) {\r\n        if (!top.done) {\r\n          top.done = true;\r\n          const num = pages[top.anchor];\r\n          if (num !== undefined && /^\\d+$/.test(m[4]!)) {\r\n            if (m[4] !== num) {\r\n              replacement = m[3]! + num + m[5]!;\r\n              changed++;\r\n              top.replaced = true;\r\n            }\r\n          } else if (num !== undefined && !/^\\d+$/.test(m[4]!.trim()) && m[4]!.trim().length > 0) {\r\n            skipped++; // non-arabic cached value \u2014 leave it (unsupported)\r\n          }\r\n        } else if (top.replaced && m[4] !== \"\") {\r\n          // Split number (\"1\",\"2\"): the full value went into the first run; blank the rest.\r\n          replacement = m[3]! + m[5]!;\r\n        }\r\n      }\r\n    }\r\n\r\n    if (replacement !== null) {\r\n      out += xml.slice(cursor, m.index) + replacement;\r\n      cursor = m.index + m[0].length;\r\n    }\r\n  }\r\n  out += xml.slice(cursor);\r\n  return { xml: out, changed, skipped };\r\n}\r\n\r\n/** Patch the cached TOC/cross-reference page numbers in a .docx, preserving every\r\n *  field and every other part. `pages` maps bookmark name \u2192 new page number. */\r\nexport function patchTocPageNumbers(docxBytes: Uint8Array, pages: Record<string, string>): PatchResult {\r\n  const parts: Unzipped = unzipSync(docxBytes);\r\n  const ctXml = parts[\"[Content_Types].xml\"];\r\n  const mainPart =\r\n    (ctXml ? findMainDocumentPart(strFromU8(ctXml)) : undefined) ?? \"word/document.xml\";\r\n  const docPart = parts[mainPart];\r\n  if (!docPart) return { bytes: docxBytes, changed: 0, skipped: 0 };\r\n\r\n  const { xml, changed, skipped } = patchXml(strFromU8(docPart), pages);\r\n  if (changed === 0) return { bytes: docxBytes, changed: 0, skipped };\r\n\r\n  parts[mainPart] = strToU8(xml);\r\n  return { bytes: zipSync(parts), changed, skipped };\r\n}\r\n\r\n/** Convenience: lay the doc out and patch the original bytes from it. The caller\r\n *  MUST have awaited installMeasureHost() first (layout measures text). */\r\nexport function patchTocFromLayout(docxBytes: Uint8Array, doc: Document): PatchResult {\r\n  const tree = createLayoutEngine().layout(doc);\r\n  return patchTocPageNumbers(docxBytes, pageByBookmark(doc, tree));\r\n}\r\n"],
   "mappings": "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",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forevka/wordcanvas",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "type": "module",
   "description": "Open-source embeddable Word-style document editor: canvas-rendered, with live collaboration, track changes & comments, and DOCX/PDF import & export. A lightweight alternative to Syncfusion, OnlyOffice, and DevExpress document editors. Self-contained, zero runtime dependencies.",
   "license": "MIT",

package/types/model.d.ts

@@ -1,225 +1,231 @@
-// Public document-model types for @forevka/wordcanvas. Hand-written (like
-// wordcanvas.d.ts) so the published surface stays self-contained and stable;
-// mirrors shared/src/model — the editor, builder, and exporters all consume
-// this same plain-data shape.
-
-export interface CharStyle {
-  fontFamily: string;
-  fontSizePx: number;
-  bold: boolean;
-  italic: boolean;
-  underline: boolean;
-  strikethrough: boolean;
-  /** CSS color, e.g. "#202124". */
-  color: string;
-  /** Hidden text (OOXML w:vanish) — preserved but never laid out or painted. */
-  hidden?: boolean;
-  letterSpacingPx?: number;
-  /** Background highlight (Word's text highlight). */
-  highlightColor?: string | undefined;
-  /** Sub/superscript. */
-  verticalAlign?: "sub" | "super" | undefined;
-  /** Hyperlink target; linked runs paint blue+underlined. */
-  link?: string | undefined;
-  /** Footnote reference id — this run is the marker. */
-  footnoteRef?: string | undefined;
-  /** Content-control membership (properties live in Document.sdts). */
-  sdtId?: string | undefined;
-}
-
-export interface TabStop {
-  /** Position from the left content edge, px. */
-  posPx: number;
-  align?: "left" | "center" | "right" | "decimal";
-  leader?: "none" | "dot" | "dash" | "underscore";
-}
-
-export interface ParaStyle {
-  align: "left" | "center" | "right" | "justify";
-  /** Line height multiplier. */
-  lineHeight: number;
-  spaceBeforePx: number;
-  spaceAfterPx: number;
-  indentFirstLinePx: number;
-  indentLeftPx: number;
-  indentRightPx?: number;
-  keepWithNext?: boolean;
-  keepLinesTogether?: boolean;
-  /** This paragraph starts a new page. */
-  pageBreakBefore?: boolean;
-  /** List membership: definition id + level 0..8. */
-  list?: { listId: string; level: number } | undefined;
-  /** Named style reference into Document.stylesheet (e.g. "Heading1"). */
-  namedStyle?: string;
-  columnBreakBefore?: boolean;
-  tabStops?: TabStop[];
-}
-
-/** Style-homogeneous span of text. */
-export interface Run {
-  text: string;
-  style: CharStyle;
-}
-
-export interface Paragraph {
-  kind: "paragraph";
-  /** Stable unique id. */
-  id: string;
-  revision: number;
-  runs: Run[];
-  style: ParaStyle;
-}
-
-export interface ImageBlock {
-  kind: "image";
-  id: string;
-  revision: number;
-  /** Image URL — use data: URLs for portable documents. */
-  src: string;
-  /** Content address of the bytes (sha256 hex), when registered. */
-  mediaId?: string;
-  widthPx: number;
-  heightPx: number;
-  align: "left" | "center" | "right";
-  /** 'block' (default): own line. 'square': floats per align, text wraps. */
-  wrap?: "block" | "square";
-}
-
-export interface CellBorder {
-  color: string;
-  widthPx: number;
-  style?: "single" | "double" | "dashed" | "dotted";
-}
-
-export interface CellBorders {
-  top?: CellBorder;
-  right?: CellBorder;
-  bottom?: CellBorder;
-  left?: CellBorder;
-}
-
-export interface CellMargin {
-  top: number;
-  right: number;
-  bottom: number;
-  left: number;
-}
-
-export interface TableCell {
-  id: string;
-  blocks: Block[];
-  colSpan?: number;
-  rowSpan?: number;
-  /** Background fill (CSS color). */
-  shading?: string;
-  borders?: CellBorders;
-  margin?: CellMargin;
-}
-
-export interface TableRow {
-  cells: TableCell[];
-}
-
-export interface TableBlock {
-  kind: "table";
-  id: string;
-  revision: number;
-  rows: TableRow[];
-  /** Column widths as fractions of content width (sum = 1). Absent = equal. */
-  colFractions?: number[];
-}
-
-export type Block = Paragraph | ImageBlock | TableBlock;
-
-export type BandContainer = "header" | "footer" | "headerFirst" | "headerEven" | "footerFirst" | "footerEven";
-
-export interface SectionProps {
-  pageWidthPx: number;
-  pageHeightPx: number;
-  marginPx: { top: number; right: number; bottom: number; left: number };
-  /** Newspaper columns. Absent = single column. */
-  columns?: { count: number; gapPx: number };
-  pageNumberStart?: number;
-  headerDistancePx?: number;
-  footerDistancePx?: number;
-  /** Header/footer block stories. {page}/{pages} tokens in run text are
-   *  substituted per page at layout time. */
-  header?: Block[];
-  footer?: Block[];
-  headerFirst?: Block[];
-  headerEven?: Block[];
-  footerFirst?: Block[];
-  footerEven?: Block[];
-}
-
-export interface NamedStyle {
-  /** Shares the docx styleId space ("Normal", "Heading1", …). */
-  id: string;
-  /** Display name. */
-  name: string;
-  basedOn?: string;
-  char: Partial<CharStyle>;
-  para: Partial<ParaStyle>;
-}
-
-export interface Stylesheet {
-  styles: NamedStyle[];
-  defaultStyleId: string;
-}
-
-export type ListNumberFormat = "bullet" | "decimal" | "lowerLetter" | "upperLetter" | "lowerRoman" | "upperRoman";
-
-export interface ListLevel {
-  format: ListNumberFormat;
-  /** Marker pattern; %N is level N-1's counter (e.g. "%1."). Ignored for bullets. */
-  text: string;
-  bulletChar?: string;
-  indentLeftPx: number;
-  hangingPx: number;
-  start: number;
-  markerStyle?: Partial<CharStyle>;
-}
-
-export interface ListDefinition {
-  id: string;
-  /** Up to 9 levels (0..8). */
-  levels: ListLevel[];
-}
-
-export interface DocPosition {
-  blockId: string;
-  offset: number;
-}
-
-export interface BookmarkRange {
-  start: DocPosition;
-  end: DocPosition;
-}
-
-export type SdtType = "richText" | "plainText" | "checkbox" | "dropDown" | "comboBox" | "date";
-
-export interface SdtProps {
-  type: SdtType;
-  alias?: string;
-  tag?: string;
-  placeholder?: boolean;
-  listItems?: { display: string; value: string }[];
-  dateFormat?: string;
-  checked?: boolean;
-  lockContent?: boolean;
-  lockControl?: boolean;
-}
-
-export interface Document {
-  section: SectionProps;
-  blocks: Block[];
-  stylesheet?: Stylesheet;
-  /** List definitions keyed by id. */
-  lists?: Record<string, ListDefinition>;
-  /** Footnote bodies keyed by ref id. */
-  footnotes?: Record<string, Paragraph[]>;
-  /** Content-control properties keyed by sdtId. */
-  sdts?: Record<string, SdtProps>;
-  /** Bookmark name → character range. */
-  bookmarks?: Record<string, BookmarkRange>;
-}
+// Public document-model types for @forevka/wordcanvas. Hand-written (like
+// wordcanvas.d.ts) so the published surface stays self-contained and stable;
+// mirrors shared/src/model — the editor, builder, and exporters all consume
+// this same plain-data shape.
+
+export interface CharStyle {
+  fontFamily: string;
+  fontSizePx: number;
+  bold: boolean;
+  italic: boolean;
+  underline: boolean;
+  strikethrough: boolean;
+  /** CSS color, e.g. "#202124". */
+  color: string;
+  /** Hidden text (OOXML w:vanish) — preserved but never laid out or painted. */
+  hidden?: boolean;
+  letterSpacingPx?: number;
+  /** Background highlight (Word's text highlight). */
+  highlightColor?: string | undefined;
+  /** Sub/superscript. */
+  verticalAlign?: "sub" | "super" | undefined;
+  /** Hyperlink target; linked runs paint blue+underlined. */
+  link?: string | undefined;
+  /** Footnote reference id — this run is the marker. */
+  footnoteRef?: string | undefined;
+  /** Content-control membership (properties live in Document.sdts). */
+  sdtId?: string | undefined;
+}
+
+export interface TabStop {
+  /** Position from the left content edge, px. */
+  posPx: number;
+  align?: "left" | "center" | "right" | "decimal";
+  leader?: "none" | "dot" | "dash" | "underscore";
+}
+
+export interface ParaStyle {
+  align: "left" | "center" | "right" | "justify";
+  /** Line height multiplier. */
+  lineHeight: number;
+  spaceBeforePx: number;
+  spaceAfterPx: number;
+  indentFirstLinePx: number;
+  indentLeftPx: number;
+  indentRightPx?: number;
+  keepWithNext?: boolean;
+  keepLinesTogether?: boolean;
+  /** This paragraph starts a new page. */
+  pageBreakBefore?: boolean;
+  /** List membership: definition id + level 0..8. */
+  list?: { listId: string; level: number } | undefined;
+  /** Named style reference into Document.stylesheet (e.g. "Heading1"). */
+  namedStyle?: string;
+  columnBreakBefore?: boolean;
+  tabStops?: TabStop[];
+}
+
+/** Style-homogeneous span of text. */
+export interface Run {
+  text: string;
+  style: CharStyle;
+}
+
+export interface Paragraph {
+  kind: "paragraph";
+  /** Stable unique id. */
+  id: string;
+  revision: number;
+  runs: Run[];
+  style: ParaStyle;
+}
+
+export interface ImageBlock {
+  kind: "image";
+  id: string;
+  revision: number;
+  /** Image URL — use data: URLs for portable documents. */
+  src: string;
+  /** Content address of the bytes (sha256 hex), when registered. */
+  mediaId?: string;
+  widthPx: number;
+  heightPx: number;
+  align: "left" | "center" | "right";
+  /** 'block' (default): own line. 'square': floats per align, text wraps. */
+  wrap?: "block" | "square";
+}
+
+export interface CellBorder {
+  color: string;
+  widthPx: number;
+  style?: "single" | "double" | "dashed" | "dotted";
+}
+
+export interface CellBorders {
+  top?: CellBorder;
+  right?: CellBorder;
+  bottom?: CellBorder;
+  left?: CellBorder;
+}
+
+export interface CellMargin {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+export interface TableCell {
+  id: string;
+  blocks: Block[];
+  colSpan?: number;
+  rowSpan?: number;
+  /** Background fill (CSS color). */
+  shading?: string;
+  borders?: CellBorders;
+  margin?: CellMargin;
+}
+
+export interface TableRow {
+  cells: TableCell[];
+}
+
+export interface TableBlock {
+  kind: "table";
+  id: string;
+  revision: number;
+  rows: TableRow[];
+  /** Column widths as fractions of content width (sum = 1). Absent = equal. */
+  colFractions?: number[];
+}
+
+export type Block = Paragraph | ImageBlock | TableBlock;
+
+export type BandContainer = "header" | "footer" | "headerFirst" | "headerEven" | "footerFirst" | "footerEven";
+
+export interface SectionProps {
+  pageWidthPx: number;
+  pageHeightPx: number;
+  marginPx: { top: number; right: number; bottom: number; left: number };
+  /** Newspaper columns. Absent = single column. */
+  columns?: { count: number; gapPx: number };
+  pageNumberStart?: number;
+  headerDistancePx?: number;
+  footerDistancePx?: number;
+  /** Header/footer block stories. {page}/{pages} tokens in run text are
+   *  substituted per page at layout time. */
+  header?: Block[];
+  footer?: Block[];
+  headerFirst?: Block[];
+  headerEven?: Block[];
+  footerFirst?: Block[];
+  footerEven?: Block[];
+}
+
+export interface NamedStyle {
+  /** Shares the docx styleId space ("Normal", "Heading1", …). */
+  id: string;
+  /** Display name. */
+  name: string;
+  basedOn?: string;
+  char: Partial<CharStyle>;
+  para: Partial<ParaStyle>;
+}
+
+export interface Stylesheet {
+  styles: NamedStyle[];
+  defaultStyleId: string;
+}
+
+export type ListNumberFormat = "bullet" | "decimal" | "lowerLetter" | "upperLetter" | "lowerRoman" | "upperRoman";
+
+export interface ListLevel {
+  format: ListNumberFormat;
+  /** Marker pattern; %N is level N-1's counter (e.g. "%1."). Ignored for bullets. */
+  text: string;
+  bulletChar?: string;
+  indentLeftPx: number;
+  hangingPx: number;
+  start: number;
+  markerStyle?: Partial<CharStyle>;
+}
+
+export interface ListDefinition {
+  id: string;
+  /** Up to 9 levels (0..8). */
+  levels: ListLevel[];
+}
+
+export interface DocPosition {
+  blockId: string;
+  offset: number;
+}
+
+export interface BookmarkRange {
+  start: DocPosition;
+  end: DocPosition;
+}
+
+export type SdtType = "richText" | "plainText" | "checkbox" | "dropDown" | "comboBox" | "date";
+
+export interface SdtProps {
+  type: SdtType;
+  alias?: string;
+  tag?: string;
+  placeholder?: boolean;
+  listItems?: { display: string; value: string }[];
+  dateFormat?: string;
+  checked?: boolean;
+  lockContent?: boolean;
+  lockControl?: boolean;
+}
+
+export interface Document {
+  section: SectionProps;
+  blocks: Block[];
+  stylesheet?: Stylesheet;
+  /** List definitions keyed by id. */
+  lists?: Record<string, ListDefinition>;
+  /** Footnote bodies keyed by ref id. */
+  footnotes?: Record<string, Paragraph[]>;
+  /** Content-control properties keyed by sdtId. */
+  sdts?: Record<string, SdtProps>;
+  /** Bookmark name → character range. */
+  bookmarks?: Record<string, BookmarkRange>;
+  /** The document's `TOC` field instruction (e.g. ` TOC \o "1-3" \h `), captured
+   *  on import. Absent when the document has no TOC field. */
+  tocInstruction?: string;
+  /** Block id of the paragraph holding the (empty/placeholder) `TOC` field, captured
+   *  on import so a headless render can build the entries at the right spot. */
+  tocAnchorBlockId?: string;
+}

package/types/recalc-docx.d.ts

@@ -1,27 +1,27 @@
-// Public types for @forevka/wordcanvas/recalc-docx — patch a .docx's cached TOC /
-// cross-reference page numbers IN PLACE (drift-free: the file is never re-exported,
-// so every field and unmodeled byte survives). Hand-written + self-contained.
-// Await installMeasureHost() (from "@forevka/wordcanvas/export/measure") first —
-// the layout pass measures text.
-
-import type { Document } from "./model";
-
-export type { Document } from "./model";
-
-export interface PatchResult {
-  bytes: Uint8Array;
-  /** PAGEREF cached numbers rewritten to a new value. */
-  changed: number;
-  /** PAGEREF results left untouched because the cached value was non-arabic. */
-  skipped: number;
-}
-
-/** Rewrite cached PAGEREF page numbers from a bookmark → page-number map,
- *  preserving every field and other part. */
-export declare function patchTocPageNumbers(
-  docxBytes: Uint8Array,
-  pages: Record<string, string>,
-): PatchResult;
-
-/** Lay `doc` out and patch the original `docxBytes` from the resulting page map. */
-export declare function patchTocFromLayout(docxBytes: Uint8Array, doc: Document): PatchResult;
+// Public types for @forevka/wordcanvas/recalc-docx — patch a .docx's cached TOC /
+// cross-reference page numbers IN PLACE (drift-free: the file is never re-exported,
+// so every field and unmodeled byte survives). Hand-written + self-contained.
+// Await installMeasureHost() (from "@forevka/wordcanvas/export/measure") first —
+// the layout pass measures text.
+
+import type { Document } from "./model";
+
+export type { Document } from "./model";
+
+export interface PatchResult {
+  bytes: Uint8Array;
+  /** PAGEREF cached numbers rewritten to a new value. */
+  changed: number;
+  /** PAGEREF results left untouched because the cached value was non-arabic. */
+  skipped: number;
+}
+
+/** Rewrite cached PAGEREF page numbers from a bookmark → page-number map,
+ *  preserving every field and other part. */
+export declare function patchTocPageNumbers(
+  docxBytes: Uint8Array,
+  pages: Record<string, string>,
+): PatchResult;
+
+/** Lay `doc` out and patch the original `docxBytes` from the resulting page map. */
+export declare function patchTocFromLayout(docxBytes: Uint8Array, doc: Document): PatchResult;