@portone/docx-editor 0.4.0 → 0.5.1

package/dist/docx/comments/writing.js

@@ -1,5 +1,5 @@
 // src/docx/comments/writing.ts
-import { elementXml } from "../../ooxml/element.js";
+import { attrsText } from "../../ooxml/element.js";
 import { NAMESPACES, wName, xmlnsDecl } from "../../ooxml/names.js";
 import {
   ensureRootDeclarations,
@@ -7,10 +7,18 @@ import {
   splicePart
 } from "../../ooxml/partSplice.js";
 import { encodeUtf8 } from "../../ooxml/xml.js";
+import { sameSource } from "../../schema/sourceEquality.js";
+import { NO_EXPORT_REFS } from "../exportRefs.js";
 import { directoryOf } from "../relationships.js";
+import { serializeStory } from "../serializeStory.js";
+import {
+  storyFromText,
+  storyKey,
+  storyOf,
+  withThreadKeyOn
+} from "../story.js";
 import {
   arrivedEntries,
-  renderCommentBody,
   renderCommentExtension,
   withThreadKey
 } from "./grammar.js";
@@ -20,7 +28,26 @@ import {
 import { commentsExtendedPart, commentsPart, peoplePart } from "./parts.js";
 import { planPeoplePart } from "./people.js";
 function needsThreadKey(id, comment, session) {
-  return comment.imported && carriesThreadMetadata(comment) && (session.comments.byId.get(id)?.paraId ?? null) === null;
+  return session.comments.byId.has(id) && carriesThreadMetadata(comment) && (session.comments.byId.get(id)?.paraId ?? null) === null;
+}
+function bodyStory(doc, id) {
+  return storyOf(doc, storyKey("comment", id));
+}
+function importedBody(session, id) {
+  return session.stories.get(storyKey("comment", id)) ?? null;
+}
+function importedEntry(comment, session) {
+  const arrived = session.comments.byId.get(comment.id);
+  if (arrived === void 0 || arrived.author !== comment.author || arrived.date !== comment.date || arrived.initials !== comment.initials) {
+    return null;
+  }
+  return importedBody(session, comment.id);
+}
+function bodyKept(doc, comment, session) {
+  const imported = importedEntry(comment, session);
+  if (imported === null) return null;
+  const current = bodyStory(doc, comment.id);
+  return current === null || sameSource(current, imported.doc) ? imported : null;
 }
 function commentsChanged(doc, session) {
   const current = commentReferencesIn(doc);
@@ -34,12 +61,8 @@ function commentsChanged(doc, session) {
   for (const id of originalBodies) {
     if (!currentBodies.has(id)) return true;
   }
-  for (const id of session.commentReferenceIds) {
-    const comment = current.get(id);
-    if (!comment?.imported) return true;
-  }
-  for (const comment of current.values()) {
-    if (comment.replies.some((reply) => !reply.imported)) return true;
+  for (const comment of currentBodies.values()) {
+    if (bodyKept(doc, comment, session) === null) return true;
   }
   for (const [id, comment] of current) {
     if (needsThreadKey(id, comment, session)) return true;
@@ -111,27 +134,34 @@ function carriesThreadMetadata(comment) {
 function keyedEntry(comment, arrivedKeyed) {
   return carriesThreadMetadata(comment) || arrivedKeyed.has(comment.id);
 }
-function renderedComment(comment, arrivedKeyed, arrived) {
-  if (comment.imported && comment.commentXml !== null) {
-    return carriesThreadMetadata(comment) ? withThreadKey(
-      comment.commentXml,
-      comment.paraId,
-      arrived.get(comment.id) ?? null
-    ) : comment.commentXml;
-  }
+function writtenContainer(comment) {
   const attrs = [
     [wName("id"), comment.id],
     comment.author === null ? null : [wName("author"), comment.author],
     comment.date === null ? null : [wName("date"), comment.date],
     comment.initials === null ? null : [wName("initials"), comment.initials]
   ];
-  const paraId = keyedEntry(comment, arrivedKeyed) ? comment.paraId : null;
-  const body = renderCommentBody(comment.text, paraId);
-  return elementXml(
-    wName("comment"),
-    attrs.filter((attr) => attr !== null),
-    [body]
+  const text = attrsText(
+    attrs.filter((attr) => attr !== null)
   );
+  return {
+    open: text === "" ? `<${wName("comment")}>` : `<${wName("comment")} ${text}>`,
+    close: `</${wName("comment")}>`
+  };
+}
+function renderedComment(comment, arrivedKeyed, arrived, doc, session) {
+  const kept = bodyKept(doc, comment, session);
+  if (kept !== null) {
+    return carriesThreadMetadata(comment) ? withThreadKey(kept.xml, comment.paraId, arrived.get(comment.id) ?? null) : kept.xml;
+  }
+  const paraId = keyedEntry(comment, arrivedKeyed) ? comment.paraId : null;
+  const entry = importedEntry(comment, session);
+  const said = bodyStory(doc, comment.id) ?? storyFromText("");
+  const body = paraId === null ? said : withThreadKeyOn(said, paraId);
+  return serializeStory(body, null, entry ?? writtenContainer(comment), {
+    ...NO_EXPORT_REFS,
+    session
+  });
 }
 var COMMENT_MARKUP = { namespaces: { w: NAMESPACES.w } };
 var THREAD_MARKUP = {
@@ -160,7 +190,8 @@ function originalThreadIds(comments, rootIds) {
   }
   return ids;
 }
-function commentsXml(references, comments, originallyReferenced) {
+function commentsXml(doc, session, references, originallyReferenced) {
+  const comments = session.comments;
   const currentBodies = currentCommentBodies(references);
   const arrivedKeyed = new Set(
     Array.from(comments.byId.values()).flatMap(
@@ -175,20 +206,26 @@ function commentsXml(references, comments, originallyReferenced) {
   const pieces = [];
   const written = /* @__PURE__ */ new Set();
   for (const original of comments.ordered) {
+    if (written.has(original.id)) continue;
     const current = currentBodies.get(original.id);
     if (current) {
-      pieces.push(renderedComment(current, arrivedKeyed, arrived));
+      pieces.push(
+        renderedComment(current, arrivedKeyed, arrived, doc, session)
+      );
       written.add(original.id);
       continue;
     }
     if (!originalThreads.has(original.id)) {
-      pieces.push(original.xml);
+      const story = importedBody(session, original.id);
+      if (story !== null) pieces.push(story.xml);
       written.add(original.id);
     }
   }
   for (const [id, comment] of currentBodies) {
     if (!written.has(id)) {
-      pieces.push(renderedComment(comment, arrivedKeyed, arrived));
+      pieces.push(
+        renderedComment(comment, arrivedKeyed, arrived, doc, session)
+      );
     }
   }
   if (comments.xml === null) {
@@ -221,7 +258,7 @@ function planCommentParts(doc, session, context) {
     parts.set(
       partPath,
       encodeUtf8(
-        commentsXml(references, session.comments, session.commentReferenceIds),
+        commentsXml(doc, session, references, session.commentReferenceIds),
         session.comments.hadBom
       )
     );

package/dist/docx/exportDocx.js

@@ -10,12 +10,12 @@ import {
   W_NS,
   withXmlParser
 } from "../ooxml/xml.js";
-import { sameSource } from "../schema/sourceEquality.js";
 import { commentsPlanner } from "./comments.js";
 import { repackParts } from "./container.js";
 import {
   fidelityNotesOf
 } from "./fidelity.js";
+import { headerFooterPlanner } from "./headersFooters.js";
 import { hyperlinkRefs } from "./hyperlink.js";
 import { withUniqueIdentities } from "./identities.js";
 import { problemsOf } from "./invariants.js";
@@ -31,21 +31,15 @@ import {
   relationshipWriter,
   relsPathOf
 } from "./relationships.js";
-import { serializeBlock } from "./serializeBlock.js";
-import {
-  originalBlock,
-  sessionOf
-} from "./session.js";
-function blockXml(node, session, refs) {
-  const imported = originalBlock(node, session);
-  if (imported && sameSource(node, imported.node)) return imported.xml;
-  return serializeBlock(node, session, refs);
-}
+import { blockXml } from "./serializeBlock.js";
+import { sessionOf } from "./session.js";
 function buildDocumentXml(doc, session, refs) {
   const pieces = [session.documentPrefix];
   withUniqueIdentities(doc).forEach((child) => {
-    pieces.push(blockXml(child, session, refs));
+    pieces.push(blockXml(child, refs, doc.childCount === 1));
   });
+  const sectPr = doc.attrs.sectPr;
+  if (typeof sectPr === "string") pieces.push(sectPr);
   pieces.push(session.documentSuffix);
   return pieces.join("");
 }
@@ -113,7 +107,8 @@ function assertMainPart(documentXml, wroteLinks) {
 var LINK_MARKUP = { namespaces: { r: R_NS } };
 var PART_PLANNERS = [
   numberingPlanner,
-  commentsPlanner
+  commentsPlanner,
+  headerFooterPlanner
 ];
 function exportDocx(doc, session, options) {
   return exportDocxReport(doc, session, options).bytes;
@@ -153,7 +148,8 @@ function writeDocx(doc, store, notes, planners) {
   const body = buildDocumentXml(doc, store, {
     images: media?.refs ?? NO_IMAGE_REFS,
     links,
-    notes
+    notes,
+    session: store
   });
   const documentXml = links.addedRelId() ? ensureRootDeclarations(body, LINK_MARKUP) : body;
   assertMainPart(documentXml, links.addedRelId());

package/dist/docx/exportRefs.d.ts

@@ -1,19 +1,24 @@
 /**
  * What the serializers need from the rest of the package while a body is being written: which
  * relationship an inserted image ended up on (`docx/media`), which one each link's address lives
- * on (`docx/hyperlink`), and where to record an approximation a writer had to make
- * (`docx/fidelity`).
+ * on (`docx/hyperlink`), where to record an approximation a writer had to make (`docx/fidelity`),
+ * and the fragments the document was opened from (`docx/session`).
  *
  * They travel as one value so that a serializer taking a body apart passes on everything the
- * pieces of it may need, whatever a later kind of content turns out to require.
+ * pieces of it may need, whatever a later kind of content turns out to require. The session is
+ * among them because a preserved block names the fragment it stands for wherever it ends up: an
+ * edit may move one into a table cell, and the cell writer has no other way to reach the original.
  */
 import { type FidelityCollector } from "./fidelity";
 import { type LinkRefs } from "./hyperlink";
 import { type ImageRefs } from "./media";
+import type { SessionStore } from "./session";
 export interface ExportRefs {
     images: ImageRefs;
     links: LinkRefs;
     notes: FidelityCollector;
+    /** null for a serializer called on a document nobody opened */
+    session: SessionStore | null;
 }
 /** What a serializer called on its own, outside an export, has to work with */
 export declare const NO_EXPORT_REFS: ExportRefs;

package/dist/docx/exportRefs.js

@@ -5,7 +5,8 @@ import { NO_IMAGE_REFS } from "./media.js";
 var NO_EXPORT_REFS = {
   images: NO_IMAGE_REFS,
   links: NO_LINK_REFS,
-  notes: NO_FIDELITY_COLLECTOR
+  notes: NO_FIDELITY_COLLECTOR,
+  session: null
 };
 export {
   NO_EXPORT_REFS

package/dist/docx/fidelity.js

@@ -13,31 +13,45 @@ function elementOf(node) {
   return stringAttr(node.attrs.name) ?? elementNameOf(stringAttr(node.attrs.xml) ?? "");
 }
 function demotedBlock(element) {
-  const name = element === null ? null : localPart(element);
+  const name = localNameOf(element);
   if (name === "tbl") return { severity: "placeholder", code: "table-demoted" };
   if (name === "p") {
     return { severity: "placeholder", code: "paragraph-demoted" };
   }
   return { severity: "placeholder", code: "preserved-block" };
 }
+function severityOf(display) {
+  return display === "chip" ? "placeholder" : "hidden";
+}
 function preservedBy(node, element) {
   switch (node.type.name) {
-    case "docxRaw":
-      return demotedBlock(element);
     case "rawBlock":
-      return { severity: "placeholder", code: "preserved-block" };
-    case "bookmarkBlock":
-      return { severity: "hidden", code: "range-marker" };
+      return preservedBlockNote(node, element);
+    case "rawRunContent":
+      return {
+        severity: severityOf(node.attrs.display),
+        code: "preserved-run-content"
+      };
     case "rawInline":
-      return preservedInline(element);
+      return preservedInline(node, element);
     default:
       return null;
   }
 }
-function preservedInline(element) {
-  const name = element === null ? null : localPart(element);
+function preservedBlockNote(node, element) {
+  if (severityOf(node.attrs.display) === "placeholder") {
+    return demotedBlock(element);
+  }
+  return node.attrs.guarded === true ? { severity: "hidden", code: "range-marker" } : { severity: "hidden", code: "preserved-block" };
+}
+function preservedInline(node, element) {
+  const name = stringAttr(node.attrs.element) ?? localNameOf(element);
   if (name === "r") return null;
-  return name === "bookmarkStart" || name === "bookmarkEnd" ? { severity: "hidden", code: "range-marker" } : { severity: "hidden", code: "preserved-inline" };
+  const severity = severityOf(node.attrs.display);
+  return severity === "hidden" && node.attrs.guarded === true ? { severity, code: "range-marker" } : { severity, code: "preserved-inline" };
+}
+function localNameOf(element) {
+  return element === null ? null : localPart(element);
 }
 function blockNumberOf(node) {
   const srcId = stringAttr(node.attrs.srcId);

package/dist/docx/fields.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Where the fields of a paragraph stand, read back off the fragments the editor keeps as they came.
+ *
+ * A complex field is not one element. It is a begin character, the instruction text, an optional
+ * separate character, the result its producer cached, and an end character, all standing loose
+ * among the runs of the paragraph in that order (§17.16.18). Nothing in the model pairs them up, so
+ * anything that wants to know what a field was told to print has to read the characters back. A
+ * simple field says the same in one element and carries its instruction as an attribute (§17.16.19).
+ *
+ * What a field means, and how to work it out again, belongs to the fields feature. This answers the
+ * one question a projection has: where each field stands and what its instruction says.
+ */
+import type { Node as PMNode } from "prosemirror-model";
+export interface FieldSpan {
+    /** The instruction text between begin and separate (or end), whitespace-trimmed */
+    instr: string;
+    /** Where the begin character stands, and the simple field itself for one written as a single element */
+    begin: number;
+    /** Where the separate character stands, and null for a field that cached no result */
+    separate: number | null;
+    /** Where the end character stands, which is `begin` again for a simple field */
+    end: number;
+    /** The half-open range of positions the cached result covers, and null for a field carrying none */
+    result: [number, number] | null;
+}
+/**
+ * Whether the node is one of the pieces a complex field is written out of rather than something
+ * the field prints. A projection drops these whether or not they pair up into a field.
+ */
+export declare function isFieldCharacter(node: PMNode): boolean;
+/**
+ * The fields this paragraph holds, in the order they begin, each position offset by `offset`.
+ *
+ * Positions are counted inside the paragraph's content, so `offset` is where that content starts:
+ * a caller reading a paragraph standing on its own passes 0, and one reading a paragraph of a
+ * document passes the position just inside it.
+ *
+ * A begin character with no end is no field: the file says a field starts there and never says
+ * what it prints, so there is nothing to pair it with and it is passed over. `documentFidelity`
+ * still reports the characters themselves as content kept rather than modelled.
+ */
+export declare function fieldSpans(paragraph: PMNode, offset: number): FieldSpan[];

package/dist/docx/fields.js

@@ -0,0 +1,76 @@
+// src/docx/fields.ts
+import { parsePropsXml } from "../ooxml/props.js";
+import { attributeByLocalName } from "../ooxml/xml.js";
+var FIELD_CHARACTER = "fldChar";
+var INSTRUCTION = "instrText";
+var SIMPLE_FIELD = "fldSimple";
+function attributeOf(node, name) {
+  const xml = node.attrs.xml;
+  if (typeof xml !== "string") return null;
+  const el = parsePropsXml(xml);
+  return el === null ? null : attributeByLocalName(el, name);
+}
+function chipText(node) {
+  const text = node.attrs.text;
+  return typeof text === "string" ? text : "";
+}
+var DELETED_INSTRUCTION = "delInstrText";
+var FIELD_PLUMBING = /* @__PURE__ */ new Set([
+  FIELD_CHARACTER,
+  INSTRUCTION,
+  DELETED_INSTRUCTION
+]);
+function isFieldCharacter(node) {
+  const element = node.attrs.element;
+  return node.type.name === "rawRunContent" && typeof element === "string" && FIELD_PLUMBING.has(element);
+}
+function fieldSpans(paragraph, offset) {
+  const spans = [];
+  const open = [];
+  paragraph.forEach((child, at) => {
+    const pos = offset + at;
+    const element = child.attrs.element;
+    if (child.type.name === "rawInline" && element === SIMPLE_FIELD) {
+      spans.push({
+        instr: (attributeOf(child, "instr") ?? "").trim(),
+        begin: pos,
+        separate: null,
+        end: pos,
+        result: null
+      });
+      return;
+    }
+    if (child.type.name !== "rawRunContent") return;
+    if (element === INSTRUCTION) {
+      const active2 = open.at(-1);
+      if (active2 && active2.separate === null) active2.instr += chipText(child);
+      return;
+    }
+    if (element !== FIELD_CHARACTER) return;
+    const kind = attributeOf(child, "fldCharType");
+    if (kind === "begin") {
+      open.push({ instr: "", begin: pos, separate: null });
+      return;
+    }
+    const active = open.at(-1);
+    if (active === void 0) return;
+    if (kind === "separate") {
+      if (active.separate === null) active.separate = pos;
+      return;
+    }
+    if (kind !== "end") return;
+    open.pop();
+    spans.push({
+      instr: active.instr.trim(),
+      begin: active.begin,
+      separate: active.separate,
+      end: pos,
+      result: active.separate === null ? null : [active.separate + 1, pos]
+    });
+  });
+  return spans.sort((a, b) => a.begin - b.begin);
+}
+export {
+  fieldSpans,
+  isFieldCharacter
+};

package/dist/docx/formatting/styles.d.ts

@@ -75,8 +75,6 @@ export interface ParagraphStyleOption {
  * `defaultParagraphStyleIdOf` reads them by.
  */
 export declare function readParagraphStyles(styles: Document): ParagraphStyleOption[];
-/** The style name the paragraph formatting XML points at. null if it points at none */
-export declare function styleIdOf(pPr: unknown): string | null;
 /**
  * The values the style a paragraph wears lays down.
  *

package/dist/docx/formatting/styles.js

@@ -5,7 +5,7 @@ import {
   toRunFormat,
   toTableFormat
 } from "../../model/format.js";
-import { parsePropsXml } from "../../ooxml/props.js";
+import { styleIdOf } from "../../ooxml/props.js";
 import { ST_OnOff } from "../../ooxml/simpleTypes.js";
 import { childValue, isOn, wAttr } from "../../ooxml/units.js";
 import { childByLocalName, elementChildren } from "../../ooxml/xml.js";
@@ -201,18 +201,6 @@ function readParagraphStyles(styles) {
   }
   return options;
 }
-var styleIdsByPPr = /* @__PURE__ */ new Map();
-var STYLE_ID_CACHE_LIMIT = 2e3;
-function styleIdOf(pPr) {
-  if (typeof pPr !== "string" || !pPr.includes("pStyle")) return null;
-  const known = styleIdsByPPr.get(pPr);
-  if (known !== void 0) return known;
-  const el = parsePropsXml(pPr);
-  const id = el ? childValue(el, "pStyle") : null;
-  if (styleIdsByPPr.size >= STYLE_ID_CACHE_LIMIT) styleIdsByPPr.clear();
-  styleIdsByPPr.set(pPr, id);
-  return id;
-}
 function paragraphStyleFormat(pPr, styles, defaultStyleId = null) {
   const id = styleIdOf(pPr) ?? defaultStyleId;
   return id === null ? void 0 : styles.get(id);
@@ -241,6 +229,5 @@ export {
   numberingStyleLinks,
   paragraphStyleFormat,
   readParagraphStyles,
-  readStyles,
-  styleIdOf
+  readStyles
 };

package/dist/docx/headersFooters.d.ts

@@ -1,17 +1,25 @@
-/** Reads the first section's header and footer stories for the page preview. */
-import type { ParagraphAlign } from "../model/format";
-export type HeaderFooterVariant = "default" | "first" | "even";
-export type PageField = "PAGE" | "NUMPAGES";
-export type HeaderFooterSegment = {
-    kind: "text";
-    value: string;
-} | {
-    kind: "field";
-    field: PageField;
-};
-/** A display-only projection. The original part remains untouched in the package. */
+/**
+ * The header and footer stories of a document: where each one is written, which section shows it,
+ * what it reads as on a given page, and where an edited one goes back out.
+ *
+ * A header part is a story of the same schema as the body (`./story`): its blocks are read by the
+ * same readers and sliced verbatim by the same scanner, so an edit to one rides a transaction and
+ * the part it stands in goes back out as the bytes it arrived as until somebody changes it. What
+ * the page preview draws is a projection of that story rather than a reading of its own.
+ *
+ * Which story a section shows is the section's question (`./sections`): every section names its own
+ * variants, so the second section of a document draws its own header and not the first section's.
+ */
+import type { Node as PMNode } from "prosemirror-model";
+import { type ParagraphAlign } from "../model/format";
+import { type StoryKey } from "../schema/stories";
+import type { PartPlanner } from "./partPlan";
+import { type DocumentSection } from "./sections";
+import { type ImportedStory, type StoryDeps } from "./story";
+/** One story a section may show, as the document currently says it */
 export interface HeaderFooterContent {
-    segments: readonly HeaderFooterSegment[];
+    story: PMNode;
+    /** What the first paragraph of the story is aligned to, which is what the preview is drawn with */
     align: ParagraphAlign | null;
 }
 export interface HeaderFooterVariants {
@@ -26,11 +34,72 @@ export interface HeadersFooters {
     evenAndOdd: boolean;
     pageNumberStart: number;
 }
-export declare const NO_HEADERS_FOOTERS: HeadersFooters;
-/** Reads the first section's display stories and section-level selection switches. */
-export declare function readHeadersFooters(parts: Map<string, Uint8Array>, mainPartPath: string, body: Element): HeadersFooters;
+/**
+ * What picking one section's stories takes beyond the section itself.
+ *
+ * A section names a relationship, a relationship names a part, and a part is where a story stands,
+ * so the two ends are joined once when the document is opened. `w:evenAndOddHeaders` is a
+ * document-wide setting rather than a section's own (§17.15.1.29), so it rides along here.
+ */
+export interface HeaderFooterStories {
+    /**
+     * The story each header or footer relationship of the main part names. The key says which of the
+     * two kinds it is, so a `w:headerReference` naming a footer relationship names no story.
+     */
+    readonly keyByRelId: ReadonlyMap<string, StoryKey>;
+    readonly evenAndOdd: boolean;
+}
+/**
+ * Every header and footer part a section of the document names, read as a story apiece, and the
+ * relationship each one answers to.
+ *
+ * A part is read once however many relationships point at it, and a part whose root is not the
+ * element its relationship promises is passed over: the reference names nothing this can draw, and
+ * the bytes stay where they are. A part no section names is not read at all, so an orphan a
+ * producer left behind - which may hold anything, a document this one never draws included - is
+ * neither a story of this document nor a reason to refuse the file, and its bytes go back out as
+ * they came.
+ */
+export declare function readHeaderFooterStories(parts: Map<string, Uint8Array>, mainPartPath: string, referenced: ReadonlySet<string>, depsFor: (partPath: string) => StoryDeps): {
+    stories: readonly ImportedStory[];
+    refs: HeaderFooterStories;
+};
+/**
+ * The stories this section shows and the switches that pick between them.
+ *
+ * `storyOf` answers with what the document currently says rather than what the package arrived
+ * holding, so a header the editor rewrote is the one the preview draws.
+ */
+export declare function variantsFor(section: DocumentSection, refs: HeaderFooterStories, storyOf: (key: StoryKey) => PMNode | null): HeadersFooters;
+/**
+ * The number this visual page shows, counted from the start its section declares.
+ *
+ * `page` is the page's place in the whole document: the count is not restarted at a section
+ * boundary, which is what the editor's documented page numbering says.
+ */
 export declare function displayPageNumber(headersFooters: HeadersFooters, page: number): number;
-/** Resolves the section variant and evaluates PAGE and NUMPAGES for one visual page. */
-export declare function headerFooterText(variants: HeaderFooterVariants, headersFooters: HeadersFooters, page: number, totalPages: number): string | null;
-/** Resolves the direct alignment of the first paragraph in the selected story. */
-export declare function headerFooterAlign(variants: HeaderFooterVariants, headersFooters: HeadersFooters, page: number): ParagraphAlign | null;
+/**
+ * The story this page of a section shows, and null where the section declares none for it.
+ *
+ * `pageInSection` is the page's place within its own section rather than in the document:
+ * `w:titlePg` selects the `first` story for the first page of every section it is written in
+ * (§17.10.1), and the odd or even story follows the number that page would carry counting from
+ * the section's own start (§17.10.6), so a second section opening halfway down a document draws
+ * its own first page as a first page.
+ */
+export declare function headerFooterOn(variants: HeaderFooterVariants, headersFooters: HeadersFooters, pageInSection: number): HeaderFooterContent | null;
+/**
+ * What the story reads as on one visual page: its paragraphs joined by newlines, with `PAGE` and
+ * `NUMPAGES` replaced by the numbers this page actually carries.
+ *
+ * `page` is the number the page shows rather than its place on the sheet, since that is what a
+ * `PAGE` field prints (§17.16.5.45).
+ */
+export declare function headerFooterText(story: PMNode, page: number, totalPages: number): string;
+/**
+ * Writes back the header and footer parts an edit changed, and no others.
+ *
+ * A story nobody touched is not written at all, so a document opened and exported hands every
+ * header part back as the bytes it arrived as, and editing one header leaves the rest untouched.
+ */
+export declare const headerFooterPlanner: PartPlanner;