@portone/docx-editor 0.6.0 → 0.6.2

package/dist/docx/notes/newNote.js

@@ -0,0 +1,122 @@
+// src/docx/notes/newNote.ts
+import { Fragment } from "prosemirror-model";
+import { elementXml } from "../../ooxml/element.js";
+import { wName } from "../../ooxml/names.js";
+import { docxSchema } from "../../schema/index.js";
+import {
+  NOTE_KINDS,
+  storiesOf,
+  storyKey
+} from "../../schema/stories.js";
+import { CLONE_POLICIES } from "../cloning.js";
+import { originalBlock } from "../session.js";
+import { withStyleFormats } from "../story.js";
+var NOTE_MARKUP = {
+  footnote: {
+    textStyle: "FootnoteText",
+    referenceStyle: "FootnoteReference",
+    numberElement: "footnoteRef"
+  },
+  endnote: {
+    textStyle: "EndnoteText",
+    referenceStyle: "EndnoteReference",
+    numberElement: "endnoteRef"
+  }
+};
+var NOTE_NUMBER_ELEMENTS = NOTE_KINDS.map(
+  (kind) => NOTE_MARKUP[kind].numberElement
+);
+function noteNumberRunProps(kind, formatting) {
+  const { referenceStyle } = NOTE_MARKUP[kind];
+  const property = formatting.styles.get(referenceStyle)?.type === "character" ? elementXml(wName("rStyle"), [[wName("val"), referenceStyle]]) : elementXml(wName("vertAlign"), [[wName("val"), "superscript"]]);
+  return elementXml(wName("rPr"), [], [property]);
+}
+function noteTextProps(kind, formatting) {
+  const { textStyle } = NOTE_MARKUP[kind];
+  return formatting.styles.get(textStyle)?.type === "paragraph" ? elementXml(
+    wName("pPr"),
+    [],
+    [elementXml(wName("pStyle"), [[wName("val"), textStyle]])]
+  ) : null;
+}
+function newNoteStory(kind, formatting) {
+  const { numberElement } = NOTE_MARKUP[kind];
+  const number = docxSchema.nodes.rawRunContent.create(
+    {
+      xml: elementXml(wName(numberElement), []),
+      element: numberElement,
+      display: "chip",
+      text: null,
+      guarded: false
+    },
+    null,
+    [
+      docxSchema.marks.run.create({
+        rPr: noteNumberRunProps(kind, formatting)
+      })
+    ]
+  );
+  const paragraph = docxSchema.nodes.paragraph.create(
+    { pPr: noteTextProps(kind, formatting) },
+    number
+  );
+  return withStyleFormats(
+    docxSchema.nodes.doc.create(null, [paragraph]),
+    formatting
+  );
+}
+var DECIMAL = /^-?\d+$/;
+function takenNoteIds(doc, kind, reserved) {
+  const prefix = storyKey(kind, "");
+  const ids = new Set(
+    [...reserved, ...Object.keys(storiesOf(doc))].flatMap(
+      (key) => key.startsWith(prefix) ? [key.slice(prefix.length)] : []
+    )
+  );
+  doc.descendants((node) => {
+    const id = node.attrs.id;
+    if (node.type === docxSchema.nodes.noteReference && node.attrs.kind === kind && typeof id === "string") {
+      ids.add(id);
+    }
+    return true;
+  });
+  return ids;
+}
+function nextNoteId(taken) {
+  const largest = Array.from(taken).filter((id) => DECIMAL.test(id)).map((id) => BigInt(id)).reduce((max, id) => id > max ? id : max, 0n);
+  return (largest + 1n).toString();
+}
+function copiedBlock(node, session) {
+  if (node.isInline) return node;
+  if (node.type === docxSchema.nodes.paragraph) {
+    return node.type.create(
+      CLONE_POLICIES.paragraph.attrs(node, "copy"),
+      node.content,
+      node.marks
+    );
+  }
+  if (node.type === docxSchema.nodes.rawBlock) {
+    const held = node.attrs.xml;
+    const xml = typeof held === "string" ? held : session === null ? void 0 : originalBlock(node, session)?.xml;
+    return xml === void 0 ? node : node.type.create({ ...node.attrs, xml, srcId: null }, null, node.marks);
+  }
+  const attrs = node.attrs.srcId === void 0 || node.attrs.srcId === null ? node.attrs : { ...node.attrs, srcId: null };
+  return node.type.create(
+    attrs,
+    Fragment.fromArray(
+      node.children.map((child) => copiedBlock(child, session))
+    ),
+    node.marks
+  );
+}
+function copiedNoteStory(story, session) {
+  return copiedBlock(story, session);
+}
+export {
+  NOTE_NUMBER_ELEMENTS,
+  copiedNoteStory,
+  newNoteStory,
+  nextNoteId,
+  noteNumberRunProps,
+  takenNoteIds
+};

package/dist/docx/notes/numbering.d.ts

@@ -0,0 +1,27 @@
+import { type Node as PMNode } from "prosemirror-model";
+import { type StoryKey } from "../../schema/stories";
+import { type NoteNumbering } from "./reading";
+/**
+ * The label each note reference of the body is drawn with, by position.
+ *
+ * Each kind is counted on its own, in the order its references stand: a repeated id takes the
+ * label of its first reference since the count last started, a reference whose custom mark follows
+ * takes neither a label nor a number (§17.11.14), and one calling a separator entry is no note to
+ * count. A section's own properties lay over the settings, and a section that restarts each section
+ * counts from its start again (§17.11.19, §17.11.20), so a note referred to in an earlier section
+ * and again in this one is drawn with this section's own number, as Word draws it. A restart on
+ * each page is counted straight through, since the label would then depend on the pages, which
+ * depend in turn on how wide the labels are drawn.
+ *
+ * It reads the document and what it is handed and nothing else, so the file an edited document
+ * exports opens with the labels the editor drew.
+ */
+export declare function noteLabelsIn(doc: PMNode, numbering: NoteNumbering, special: ReadonlySet<StoryKey>): ReadonlyMap<number, string>;
+/**
+ * What `noteLabelsIn` reads off the document, as one string: the kind, id, and custom mark of each
+ * reference, which section it stands in, and what each section lays over the settings. Two
+ * documents with the same signature are labelled alike under the same numbering.
+ */
+export declare function noteLabelSignature(doc: PMNode): string;
+/** The document with every note reference labelled, and the same node where every label already stood */
+export declare function withNoteLabels(doc: PMNode, numbering: NoteNumbering, special: ReadonlySet<StoryKey>): PMNode;

package/dist/docx/notes/numbering.js

@@ -0,0 +1,113 @@
+// src/docx/notes/numbering.ts
+import { Fragment } from "prosemirror-model";
+import { spellNumber } from "../../numbering/spellers.js";
+import {
+  NOTE_KINDS,
+  storyKey
+} from "../../schema/stories.js";
+import { sectionsOf } from "../sections.js";
+import {
+  withNoteProps
+} from "./reading.js";
+import { eachNoteReference } from "./references.js";
+var MAX_LABEL_CHARS = 64;
+function referencesBySection(doc) {
+  const found = [];
+  eachNoteReference(doc, ({ node, pos, block }) => {
+    found.push({ block, reference: { pos, node } });
+  });
+  if (found.length === 0) return [];
+  const sections = sectionsOf(doc);
+  const references = sections.map(() => []);
+  let at = 0;
+  for (const { block, reference } of found) {
+    while (block > sections[at].lastBlock) at += 1;
+    references[at].push(reference);
+  }
+  return sections.map((section, index) => ({
+    section,
+    references: references[index]
+  }));
+}
+function kindOf(node) {
+  return node.attrs.kind === "endnote" ? "endnote" : "footnote";
+}
+function idOf(node) {
+  const id = node.attrs.id;
+  return typeof id === "string" ? id : null;
+}
+function propsIn(section, numbering) {
+  return {
+    footnote: withNoteProps(numbering.footnote, section.props.footnotePr),
+    endnote: withNoteProps(numbering.endnote, section.props.endnotePr)
+  };
+}
+function restarted(count, props) {
+  count.next = props.start;
+  count.taken.clear();
+}
+function labelOf(node, count, props, special) {
+  if (node.attrs.customMarkFollows === true) return "";
+  const id = idOf(node);
+  if (id === null || special.has(storyKey(kindOf(node), id))) return "?";
+  const taken = count.taken.get(id);
+  if (taken !== void 0) return taken;
+  const label = spellNumber(count.next, props.format, MAX_LABEL_CHARS);
+  count.next += 1;
+  count.taken.set(id, label);
+  return label;
+}
+function noteLabelsIn(doc, numbering, special) {
+  const labels = /* @__PURE__ */ new Map();
+  const counts = {
+    footnote: { next: 1, taken: /* @__PURE__ */ new Map() },
+    endnote: { next: 1, taken: /* @__PURE__ */ new Map() }
+  };
+  referencesBySection(doc).forEach(({ section, references }, index) => {
+    const props = propsIn(section, numbering);
+    for (const kind of NOTE_KINDS) {
+      if (index === 0 || props[kind].restart === "eachSect") {
+        restarted(counts[kind], props[kind]);
+      }
+    }
+    for (const { pos, node } of references) {
+      const kind = kindOf(node);
+      labels.set(pos, labelOf(node, counts[kind], props[kind], special));
+    }
+  });
+  return labels;
+}
+function noteLabelSignature(doc) {
+  return JSON.stringify(
+    referencesBySection(doc).map(({ section, references }) => [
+      section.props.footnotePr,
+      section.props.endnotePr,
+      references.map(({ node }) => [
+        kindOf(node),
+        idOf(node),
+        node.attrs.customMarkFollows === true
+      ])
+    ])
+  );
+}
+function relabelled(node, contentStart, labels) {
+  const children = [];
+  let changed = false;
+  node.forEach((child, offset) => {
+    const at = contentStart + offset;
+    const label = labels.get(at);
+    const next = label !== void 0 && child.attrs.label !== label ? child.type.create({ ...child.attrs, label }, null, child.marks) : child.isLeaf ? child : relabelled(child, at + 1, labels);
+    changed ||= next !== child;
+    children.push(next);
+  });
+  return changed ? node.copy(Fragment.from(children)) : node;
+}
+function withNoteLabels(doc, numbering, special) {
+  const labels = noteLabelsIn(doc, numbering, special);
+  return labels.size === 0 ? doc : relabelled(doc, 0, labels);
+}
+export {
+  noteLabelSignature,
+  noteLabelsIn,
+  withNoteLabels
+};

package/dist/docx/notes/reading.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Reads the footnotes and endnotes parts the main part relates to: the entry each holds, which of
+ * them lays the page out rather than says anything, and how each kind is numbered.
+ *
+ * What a note says is a story of its own, read by `docx/story` out of the same part text.
+ */
+import { type NumberFormat } from "../../numbering/spellers";
+import { type NoteKind, type StoryKey } from "../../schema/stories";
+export type { NoteKind } from "../../schema/stories";
+/**
+ * One entry of a notes part as it arrived. What the note says is a story of its own, held on the
+ * document node under `footnote:<id>` or `endnote:<id>` (`docx/story`).
+ */
+export interface ImportedNote {
+    kind: NoteKind;
+    id: string;
+    type: string | null;
+}
+export interface ImportedNotePart {
+    partPath: string | null;
+    /** The raw text of the part, which is what the note stories are sliced out of. null for none */
+    xml: string | null;
+    ordered: readonly ImportedNote[];
+    byId: ReadonlyMap<string, ImportedNote>;
+}
+export interface ImportedNotes {
+    footnotes: ImportedNotePart;
+    endnotes: ImportedNotePart;
+}
+/** Reads both note parts without modifying their original package bytes. */
+export declare function readNotes(parts: Map<string, Uint8Array>, mainPartPath: string): ImportedNotes;
+/**
+ * The entries a notes part lays the page out with rather than numbers - a separator, a
+ * continuation separator, a continuation notice (§17.11.1, §17.11.23) - as the keys their stories
+ * stand under.
+ */
+export declare function specialNotesOf(notes: ImportedNotes): ReadonlySet<StoryKey>;
+/** Where the count of one kind of note goes back to its start (§17.18.74) */
+export type NoteRestart = "continuous" | "eachSect" | "eachPage";
+/** How one kind of note is counted (§17.11.17-20) */
+export interface NoteNumberingProps {
+    readonly format: NumberFormat;
+    readonly start: number;
+    readonly restart: NoteRestart;
+}
+export type NoteNumbering = Readonly<Record<NoteKind, NoteNumberingProps>>;
+export declare const DEFAULT_NOTE_NUMBERING: NoteNumbering;
+/**
+ * What one `w:footnotePr` or `w:endnotePr` names, leaving out every property it does not, and null
+ * for no element at all.
+ *
+ * A format this editor has no speller for is counted in decimal, as a list marker is.
+ */
+export declare function readNoteProps(props: Element | null): Partial<NoteNumberingProps> | null;
+/** The properties with whatever an override names laid over them (§17.11.5, §17.11.11) */
+export declare function withNoteProps(base: NoteNumberingProps, override: Partial<NoteNumberingProps> | null): NoteNumberingProps;
+/** The document-wide note properties settings.xml names (§17.11.4, §17.11.12) */
+export declare function readNoteNumbering(settings: Document | null): NoteNumbering;

package/dist/docx/notes/reading.js

@@ -0,0 +1,98 @@
+// src/docx/notes/reading.ts
+import { isNumberFormat } from "../../numbering/spellers.js";
+import { ST_DecimalNumber } from "../../ooxml/simpleTypes.js";
+import {
+  attributeByLocalName,
+  childByLocalName,
+  decodeUtf8,
+  elementChildren,
+  parseXml,
+  R_NS
+} from "../../ooxml/xml.js";
+import { storyKey } from "../../schema/stories.js";
+import { relatedPartPath } from "../packageParts.js";
+var EMPTY_PART = {
+  partPath: null,
+  xml: null,
+  ordered: [],
+  byId: /* @__PURE__ */ new Map()
+};
+function notePart(parts, mainPartPath, kind) {
+  const partPath = relatedPartPath(parts, mainPartPath, `${R_NS}/${kind}s`);
+  if (partPath === null) return EMPTY_PART;
+  const bytes = parts.get(partPath);
+  if (!bytes) return { ...EMPTY_PART, partPath };
+  const xml = decodeUtf8(bytes).text;
+  const root = parseXml(xml).documentElement;
+  const elements = elementChildren(root).filter((el) => el.localName === kind);
+  const ordered = elements.flatMap((el) => {
+    const id = attributeByLocalName(el, "id");
+    if (id === null) return [];
+    return [{ kind, id, type: attributeByLocalName(el, "type") }];
+  });
+  const byId = /* @__PURE__ */ new Map();
+  for (const note of ordered) {
+    if (!byId.has(note.id)) byId.set(note.id, note);
+  }
+  return { partPath, xml, ordered, byId };
+}
+function readNotes(parts, mainPartPath) {
+  return {
+    footnotes: notePart(parts, mainPartPath, "footnote"),
+    endnotes: notePart(parts, mainPartPath, "endnote")
+  };
+}
+function isSpecial(note) {
+  return note.type !== null && note.type !== "normal";
+}
+function specialNotesOf(notes) {
+  return new Set(
+    [...notes.footnotes.byId.values(), ...notes.endnotes.byId.values()].filter(isSpecial).map((note) => storyKey(note.kind, note.id))
+  );
+}
+var UNNAMED_PROPS = {
+  format: "decimal",
+  start: 1,
+  restart: "continuous"
+};
+var DEFAULT_NOTE_NUMBERING = {
+  footnote: UNNAMED_PROPS,
+  endnote: UNNAMED_PROPS
+};
+var RESTARTS = ["continuous", "eachSect", "eachPage"];
+function valOf(props, name) {
+  const child = childByLocalName(props, name);
+  return child === null ? null : attributeByLocalName(child, "val");
+}
+function readNoteProps(props) {
+  if (props === null) return null;
+  const format = valOf(props, "numFmt");
+  const start = ST_DecimalNumber.parse(valOf(props, "numStart"));
+  const restart = RESTARTS.find(
+    (known) => known === valOf(props, "numRestart")
+  );
+  return {
+    ...format === null ? {} : { format: isNumberFormat(format) ? format : "decimal" },
+    ...start === null ? {} : { start },
+    ...restart === void 0 ? {} : { restart }
+  };
+}
+function withNoteProps(base, override) {
+  return override === null ? base : { ...base, ...override };
+}
+function readNoteNumbering(settings) {
+  const root = settings?.documentElement ?? null;
+  const named = (name) => readNoteProps(root === null ? null : childByLocalName(root, name));
+  return {
+    footnote: withNoteProps(UNNAMED_PROPS, named("footnotePr")),
+    endnote: withNoteProps(UNNAMED_PROPS, named("endnotePr"))
+  };
+}
+export {
+  DEFAULT_NOTE_NUMBERING,
+  readNoteNumbering,
+  readNoteProps,
+  readNotes,
+  specialNotesOf,
+  withNoteProps
+};

package/dist/docx/notes/references.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Where the body refers to its notes.
+ *
+ * Three readers ask: the notes writers collect the ids each part is referred to by, the numbering
+ * counts the references section by section (`./numbering`), and the export invariants look up the
+ * first reference to one note, which is where a problem about a note's own text is reported
+ * (`docx/invariants`). One walk here is what keeps the three reading the same nodes in the same
+ * order.
+ */
+import type { Node as PMNode } from "prosemirror-model";
+import { type NoteKey } from "../../schema/stories";
+/** One reference the body makes to a note */
+export interface PlacedNoteReference {
+    readonly node: PMNode;
+    /** Where the reference stands in the document */
+    readonly pos: number;
+    /** The top-level block it stands in, by index, which is what a section covers a run of */
+    readonly block: number;
+    /** The note it names, and null where it names no kind of note or carries no id */
+    readonly key: NoteKey | null;
+}
+/**
+ * Every `noteReference` of the body in document order, until `visit` answers false.
+ *
+ * Only the document node is walked: WordprocessingML puts a reference in the body and a note's own
+ * text in a part of its own, so a side story holds none.
+ */
+export declare function eachNoteReference(doc: PMNode, visit: (reference: PlacedNoteReference) => boolean | void): void;
+/**
+ * Where the body first refers to each of these notes, and nothing for one it refers to nowhere.
+ * The walk stops as soon as every note asked about has been placed.
+ */
+export declare function firstNoteReferences(doc: PMNode, wanted: ReadonlySet<NoteKey>): ReadonlyMap<NoteKey, number>;

package/dist/docx/notes/references.js

@@ -0,0 +1,37 @@
+// src/docx/notes/references.ts
+import { NOTE_KINDS, storyKey } from "../../schema/stories.js";
+function keyOf(node) {
+  const kind = NOTE_KINDS.find((candidate) => candidate === node.attrs.kind);
+  const id = node.attrs.id;
+  return kind === void 0 || typeof id !== "string" ? null : storyKey(kind, id);
+}
+function eachNoteReference(doc, visit) {
+  let running = true;
+  doc.forEach((block, offset, index) => {
+    if (!running) return;
+    block.descendants((node, pos) => {
+      if (!running) return false;
+      if (node.type.name !== "noteReference") return true;
+      running = visit({
+        node,
+        pos: offset + 1 + pos,
+        block: index,
+        key: keyOf(node)
+      }) !== false;
+      return false;
+    });
+  });
+}
+function firstNoteReferences(doc, wanted) {
+  const first = /* @__PURE__ */ new Map();
+  if (wanted.size === 0) return first;
+  eachNoteReference(doc, ({ key, pos }) => {
+    if (key !== null && wanted.has(key) && !first.has(key)) first.set(key, pos);
+    return first.size < wanted.size;
+  });
+  return first;
+}
+export {
+  eachNoteReference,
+  firstNoteReferences
+};

package/dist/docx/notes/writing.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Writes an edited, added, or removed note back into the part of its kind, one entry per story
+ * (`docx/storyParts`).
+ *
+ * The two parts differ in nothing but the names they are written under, so both are laid out by
+ * one description read off the kind: a `w:footnotes` part holds a `w:footnote` apiece and a
+ * `w:endnotes` part a `w:endnote` (§17.11.15, §17.11.16).
+ *
+ * A part this writer creates opens with the separator and continuation-separator entries Word lays
+ * the line above the notes out with (§17.11.1, §17.11.23). `settings.xml` is left alone: the
+ * `w:footnote` and `w:endnote` references there are optional (`CT_FtnDocProps`, `CT_EdnDocProps`),
+ * and a Google Docs export writes none.
+ */
+import type { PartPlanner } from "../partPlan";
+import { type StoryEntriesPart } from "../storyParts";
+export declare const FOOTNOTES_PART: StoryEntriesPart;
+export declare const ENDNOTES_PART: StoryEntriesPart;
+export declare const footnotesPlanner: PartPlanner;
+export declare const endnotesPlanner: PartPlanner;

package/dist/docx/notes/writing.js

@@ -0,0 +1,95 @@
+// src/docx/notes/writing.ts
+import { elementXml } from "../../ooxml/element.js";
+import { wName } from "../../ooxml/names.js";
+import { R_NS } from "../../ooxml/xml.js";
+import { noteKeyOf } from "../../schema/stories.js";
+import { storyEntriesPlanner } from "../storyParts.js";
+import { eachNoteReference } from "./references.js";
+var NOTE_CONTENT_TYPES = {
+  footnote: "application/vnd.openxmlformats-officedocument.wordprocessingml.footnotes+xml",
+  endnote: "application/vnd.openxmlformats-officedocument.wordprocessingml.endnotes+xml"
+};
+var SEPARATORS = [
+  { type: "separator", id: -1 },
+  { type: "continuationSeparator", id: 0 }
+];
+var DECIMAL = /^-?\d+$/;
+function separatorIds(taken) {
+  const held = Array.from(taken).filter((id) => DECIMAL.test(id)).map(Number);
+  return SEPARATORS.reduce((chosen, { id }) => {
+    const used = [...held, ...chosen];
+    return [...chosen, used.includes(id) ? Math.min(0, ...used) - 1 : id];
+  }, []);
+}
+function separatorXml(kind, type, id) {
+  const paragraph = elementXml(
+    wName("p"),
+    [],
+    [
+      elementXml(
+        wName("pPr"),
+        [],
+        [
+          elementXml(wName("spacing"), [
+            [wName("after"), "0"],
+            [wName("line"), "240"],
+            [wName("lineRule"), "auto"]
+          ])
+        ]
+      ),
+      elementXml(wName("r"), [], [elementXml(wName(type), [])])
+    ]
+  );
+  return elementXml(
+    wName(kind),
+    [
+      [wName("type"), type],
+      [wName("id"), String(id)]
+    ],
+    [paragraph]
+  );
+}
+function separatorsXml(kind, taken) {
+  const ids = separatorIds(taken);
+  return SEPARATORS.map(
+    ({ type }, at) => separatorXml(kind, type, ids[at] ?? 0)
+  ).join("");
+}
+function frozenNotes(session, kind) {
+  return new Set(
+    Array.from(session.specialNotes).filter((key) => key.startsWith(`${kind}:`))
+  );
+}
+function referenceIds(doc, kind) {
+  const ids = /* @__PURE__ */ new Set();
+  eachNoteReference(doc, ({ key }) => {
+    const note = key === null ? null : noteKeyOf(key);
+    if (note?.kind === kind) ids.add(note.id);
+  });
+  return ids;
+}
+function notesPart(kind) {
+  const plural = `${kind}s`;
+  return {
+    name: plural,
+    kind,
+    relType: `${R_NS}/${plural}`,
+    contentType: NOTE_CONTENT_TYPES[kind],
+    stem: plural,
+    root: plural,
+    entry: kind,
+    referencedIds: (doc) => referenceIds(doc, kind),
+    frozenEntries: (session) => frozenNotes(session, kind),
+    prelude: (taken) => separatorsXml(kind, taken)
+  };
+}
+var FOOTNOTES_PART = notesPart("footnote");
+var ENDNOTES_PART = notesPart("endnote");
+var footnotesPlanner = storyEntriesPlanner(FOOTNOTES_PART);
+var endnotesPlanner = storyEntriesPlanner(ENDNOTES_PART);
+export {
+  ENDNOTES_PART,
+  FOOTNOTES_PART,
+  endnotesPlanner,
+  footnotesPlanner
+};

package/dist/docx/partPlan.d.ts

@@ -7,12 +7,15 @@
  * for, so no planner writes either of them itself and none can write over what another declared.
  */
 import type { Node as PMNode } from "prosemirror-model";
+import type { FidelityCollector } from "./fidelity";
 import { type ContentTypeWriter } from "./packageParts";
 import { type RelationshipWriter } from "./relationships";
 import type { SessionStore } from "./session";
 export interface PartPlanContext {
     readonly relationships: RelationshipWriter;
     readonly contentTypes: ContentTypeWriter;
+    /** Where a story writer records an approximation it had to make, beside the body writer's */
+    readonly notes: FidelityCollector;
 }
 export interface PartPlanner {
     readonly name: string;

package/dist/docx/partPlanners.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The parts written beside the body, and what each of their planners carries into the file.
+ *
+ * `docx/exportDocx` runs these planners and `docx/invariants` reads what they write off the same
+ * list, so the two cannot disagree about which change has a writer.
+ */
+import type { PartPlanner } from "./partPlan";
+import { type StoryEntriesPart, type StoryWriting } from "./storyParts";
+export declare const PART_PLANNERS: readonly PartPlanner[];
+/** What every planner writes back of the side stories the document holds */
+export declare const STORY_WRITINGS: readonly StoryWriting[];
+/** The parts written one entry per story, which the identity pass walks as one part apiece */
+export declare const STORY_ENTRIES_PARTS: readonly StoryEntriesPart[];

package/dist/docx/partPlanners.js

@@ -0,0 +1,48 @@
+// src/docx/partPlanners.ts
+import { HEADER_FOOTER_KINDS } from "../schema/stories.js";
+import { commentsPlanner } from "./comments.js";
+import { headerFooterPlanner } from "./headersFooters.js";
+import {
+  ENDNOTES_PART,
+  endnotesPlanner,
+  FOOTNOTES_PART,
+  footnotesPlanner
+} from "./notes/writing.js";
+import { numberingPlanner } from "./numberingPlanner.js";
+import {
+  EVERY_STORY_CHANGE,
+  storyEntriesWriting,
+  storyWriting
+} from "./storyParts.js";
+function entriesWriter(planner, part) {
+  return { planner, writes: [storyEntriesWriting(part)], entriesPart: part };
+}
+var PART_WRITERS = [
+  { planner: numberingPlanner, writes: [], entriesPart: null },
+  {
+    planner: commentsPlanner,
+    writes: [storyWriting("comment", EVERY_STORY_CHANGE)],
+    entriesPart: null
+  },
+  {
+    planner: headerFooterPlanner,
+    writes: HEADER_FOOTER_KINDS.map((kind) => storyWriting(kind, ["edited"])),
+    entriesPart: null
+  },
+  entriesWriter(footnotesPlanner, FOOTNOTES_PART),
+  entriesWriter(endnotesPlanner, ENDNOTES_PART)
+];
+var PART_PLANNERS = PART_WRITERS.map(
+  ({ planner }) => planner
+);
+var STORY_WRITINGS = PART_WRITERS.flatMap(
+  ({ writes }) => writes
+);
+var STORY_ENTRIES_PARTS = PART_WRITERS.flatMap(
+  ({ entriesPart }) => entriesPart === null ? [] : [entriesPart]
+);
+export {
+  PART_PLANNERS,
+  STORY_ENTRIES_PARTS,
+  STORY_WRITINGS
+};