doc-codec 2.8.6 → 2.9.0

package/dist/index.js

@@ -15,7 +15,7 @@ import { readParagraphs, splitEntriesByBoundaries } from "./text/paragraphs.js";
 import { characterOffset, characterSize, parseClx } from "./text/piece-table.js";
 import { COMPRESSED_CHARACTER_MAP, readTextRange } from "./text/characters.js";
 import { readSubdocumentStories, storyText } from "./subdocument.js";
-import { readHeaderFooterStories } from "./headers-footers.js";
+import { FIXED_SEPARATOR_STORY_COUNT, SLOT_ORDER, readHeaderFooterStories } from "./headers-footers.js";
 import { parseFib, peekFibBaseFlags, tableStreamName } from "./fib/fib.js";
 import { buildFib } from "./fib/write.js";
 import { layoutMetadataToSummaryInformation } from "./metadata.js";
@@ -27,7 +27,8 @@ import { applySectionSprms, readAllSectionProperties } from "./prop/sep.js";
 import { buildPlcfSed, buildSepx, encodeSectionGrpprl } from "./prop/sep-write.js";
 import { buildFontTable, parseFontTable } from "./style/fonts.js";
 import { NUMBER_FORMAT_BY_NFC, readNumberingDefinitions } from "./list/numbering.js";
+import { buildHeaderSubdocument, buildNoteSubdocument, buildStorySubdocuments, paragraphCharacters } from "./subdocument-write.js";
 import { readNoteBodies } from "./notes.js";
 import { readDocContent, readDocStreams } from "./read.js";
 import { writeDocContent } from "./write.js";
-export { ANNOTATION_REFERENCE, CELL_MARK, COMPRESSED_CHARACTER_MAP, DATA_STREAM, DRAWN_OBJECT, DataStreamBuilder, DocFormatError, DocUnsupportedError, FC_LCB_VALUE_INDEX, FIB_BASE_FLAG, FIB_BASE_SIZE, FIB_CB_RG_FC_LCB_OFFSET, FIB_CSLW_OFFSET, FIB_CSLW_REQUIRED, FIB_CSW_REQUIRED, FIB_FC_LCB_BLOB_OFFSET, FIB_LKEY_OFFSET, FIB_RG_LW_OFFSET, FIB_RG_LW_SIZE, FIB_RG_W_OFFSET, FIB_RG_W_SIZE, FIB_W_IDENT, FIELD_BEGIN, FIELD_END, FIELD_SEPARATOR, FKP_PAGE_SIZE, FOOTNOTE_REFERENCE, INLINE_PICTURE, LINE_BREAK, LW_OFFSET, NUMBER_FORMAT_BY_NFC, PARAGRAPH_MARK, PropertyBinTable, SECTION_MARK, SGC, STI_USER_DEFINED, STK, SUMMARY_INFORMATION_STREAM, SYMBOL_ANCHOR, WORD_DOCUMENT_STREAM, applyCharacterSprms, applyParagraphSprms, applySectionSprms, base64ToBytes, buildChpxPages, buildFib, buildFontTable, buildPapxPages, buildPlcfSed, buildPropertyBinTable, buildSepx, buildStshForStyles, buildTextClx, bytesToBase64, characterIstdFromGrpprl, characterOffset, characterSize, decodeSprm, encodeCharacterGrpprl, encodeParagraphGrpprl, encodeSectionGrpprl, endsParagraph, findLargestAtMost, firstFcOfPage, fitsAloneOnPapxPage, headingLevelFromIstd, isAnchorOnly, isDocBytes, layoutMetadataToSummaryInformation, operandSize, parseChpxFkp, parseClx, parseFib, parseFontTable, parsePapxFkp, parsePlc, parseStsh, peekFibBaseFlags, readAllSectionProperties, readDocContent, readDocStreams, readGrpprl, readHeaderFooterStories, readInt16LE, readInt32LE, readNoteBodies, readNumberingDefinitions, readParagraphs, readSubdocumentStories, readTextRange, readUint16LE, readUint32LE, readUint8, resolveStyleFormatting, slice, splitEntriesByBoundaries, storyText, tableStreamName, writeDocContent };
+export { ANNOTATION_REFERENCE, CELL_MARK, COMPRESSED_CHARACTER_MAP, DATA_STREAM, DRAWN_OBJECT, DataStreamBuilder, DocFormatError, DocUnsupportedError, FC_LCB_VALUE_INDEX, FIB_BASE_FLAG, FIB_BASE_SIZE, FIB_CB_RG_FC_LCB_OFFSET, FIB_CSLW_OFFSET, FIB_CSLW_REQUIRED, FIB_CSW_REQUIRED, FIB_FC_LCB_BLOB_OFFSET, FIB_LKEY_OFFSET, FIB_RG_LW_OFFSET, FIB_RG_LW_SIZE, FIB_RG_W_OFFSET, FIB_RG_W_SIZE, FIB_W_IDENT, FIELD_BEGIN, FIELD_END, FIELD_SEPARATOR, FIXED_SEPARATOR_STORY_COUNT, FKP_PAGE_SIZE, FOOTNOTE_REFERENCE, INLINE_PICTURE, LINE_BREAK, LW_OFFSET, NUMBER_FORMAT_BY_NFC, PARAGRAPH_MARK, PropertyBinTable, SECTION_MARK, SGC, SLOT_ORDER, STI_USER_DEFINED, STK, SUMMARY_INFORMATION_STREAM, SYMBOL_ANCHOR, WORD_DOCUMENT_STREAM, applyCharacterSprms, applyParagraphSprms, applySectionSprms, base64ToBytes, buildChpxPages, buildFib, buildFontTable, buildHeaderSubdocument, buildNoteSubdocument, buildPapxPages, buildPlcfSed, buildPropertyBinTable, buildSepx, buildStorySubdocuments, buildStshForStyles, buildTextClx, bytesToBase64, characterIstdFromGrpprl, characterOffset, characterSize, decodeSprm, encodeCharacterGrpprl, encodeParagraphGrpprl, encodeSectionGrpprl, endsParagraph, findLargestAtMost, firstFcOfPage, fitsAloneOnPapxPage, headingLevelFromIstd, isAnchorOnly, isDocBytes, layoutMetadataToSummaryInformation, operandSize, paragraphCharacters, parseChpxFkp, parseClx, parseFib, parseFontTable, parsePapxFkp, parsePlc, parseStsh, peekFibBaseFlags, readAllSectionProperties, readDocContent, readDocStreams, readGrpprl, readHeaderFooterStories, readInt16LE, readInt32LE, readNoteBodies, readNumberingDefinitions, readParagraphs, readSubdocumentStories, readTextRange, readUint16LE, readUint32LE, readUint8, resolveStyleFormatting, slice, splitEntriesByBoundaries, storyText, tableStreamName, writeDocContent };

package/dist/read.cjs

@@ -5,6 +5,7 @@ const require_detect = require("./detect.cjs");
 const require_encryption = require("./encryption.cjs");
 const require_prop_fkp = require("./prop/fkp.cjs");
 const require_style_stsh = require("./style/stsh.cjs");
+require("./text/special.cjs");
 const require_text_paragraphs = require("./text/paragraphs.cjs");
 const require_text_piece_table = require("./text/piece-table.cjs");
 const require_text_characters = require("./text/characters.cjs");
@@ -70,7 +71,7 @@ function readDocContent(bytes, password) {
 	const entries = require_text_paragraphs.readParagraphs(range.text, range.fcs, context);
 	const numbering = require_list_numbering.readNumberingDefinitions(table, fib);
 	const sectionProperties = require_prop_sep.readAllSectionProperties(wordDocument, table, fib);
-	const entriesBySection = splitIntoSections(entries, sectionProperties);
+	const entriesBySection = splitIntoSections(markManualPageBreaks(entries, sectionProperties), sectionProperties);
 	const { footnotes, endnotes, comments } = require_notes.readNoteBodies(wordDocument, table, pieceTable, context, fib);
 	const headerFooterStories = require_headers_footers.readHeaderFooterStories(wordDocument, table, pieceTable, context, fib, sectionProperties.length);
 	return {
@@ -96,6 +97,22 @@ function readDocContent(bytes, password) {
 		headerFooterStories
 	};
 }
+/** The single block a manual page break reads as -- no fields of its own, exactly the shape every other codec in this family emits for one. */
+const PAGE_BREAK_BLOCK = { kind: "pageBreak" };
+function markManualPageBreaks(entries, sections) {
+	const sectionEndCps = /* @__PURE__ */ new Set();
+	for (let index = 1; index < sections.length; index += 1) {
+		const startCp = sections[index]?.startCp;
+		if (startCp !== void 0) sectionEndCps.add(startCp);
+	}
+	return entries.map((entry) => {
+		if (entry.terminator !== 12 || sectionEndCps.has(entry.endCp)) return entry;
+		return {
+			...entry,
+			blocks: [...entry.blocks, PAGE_BREAK_BLOCK]
+		};
+	});
+}
 function splitIntoSections(entries, sections) {
 	const groups = sections.map(() => []);
 	let sectionIndex = 0;

package/dist/read.js

@@ -4,6 +4,7 @@ import { DATA_STREAM, SUMMARY_INFORMATION_STREAM, WORD_DOCUMENT_STREAM } from ".
 import { decryptDocStreams } from "./encryption.js";
 import { PropertyBinTable } from "./prop/fkp.js";
 import { parseStsh } from "./style/stsh.js";
+import "./text/special.js";
 import { readParagraphs } from "./text/paragraphs.js";
 import { parseClx } from "./text/piece-table.js";
 import { readTextRange } from "./text/characters.js";
@@ -69,7 +70,7 @@ function readDocContent(bytes, password) {
 	const entries = readParagraphs(range.text, range.fcs, context);
 	const numbering = readNumberingDefinitions(table, fib);
 	const sectionProperties = readAllSectionProperties(wordDocument, table, fib);
-	const entriesBySection = splitIntoSections(entries, sectionProperties);
+	const entriesBySection = splitIntoSections(markManualPageBreaks(entries, sectionProperties), sectionProperties);
 	const { footnotes, endnotes, comments } = readNoteBodies(wordDocument, table, pieceTable, context, fib);
 	const headerFooterStories = readHeaderFooterStories(wordDocument, table, pieceTable, context, fib, sectionProperties.length);
 	return {
@@ -95,6 +96,22 @@ function readDocContent(bytes, password) {
 		headerFooterStories
 	};
 }
+/** The single block a manual page break reads as -- no fields of its own, exactly the shape every other codec in this family emits for one. */
+const PAGE_BREAK_BLOCK = { kind: "pageBreak" };
+function markManualPageBreaks(entries, sections) {
+	const sectionEndCps = /* @__PURE__ */ new Set();
+	for (let index = 1; index < sections.length; index += 1) {
+		const startCp = sections[index]?.startCp;
+		if (startCp !== void 0) sectionEndCps.add(startCp);
+	}
+	return entries.map((entry) => {
+		if (entry.terminator !== 12 || sectionEndCps.has(entry.endCp)) return entry;
+		return {
+			...entry,
+			blocks: [...entry.blocks, PAGE_BREAK_BLOCK]
+		};
+	});
+}
 function splitIntoSections(entries, sections) {
 	const groups = sections.map(() => []);
 	let sectionIndex = 0;

package/dist/subdocument-write.cjs

@@ -0,0 +1,108 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_errors = require("./errors.cjs");
+require("./text/special.cjs");
+const require_headers_footers = require("./headers-footers.cjs");
+const require_table_write = require("./table/write.cjs");
+//#region src/subdocument-write.ts
+/** A plain one-run text run: no character formatting, no extra grpprl -- a note body's own text carries no modelled formatting to state. */
+function textRun(text) {
+	return {
+		run: { text },
+		extraGrpprl: []
+	};
+}
+/** The bare paragraph mark every non-empty story ends with -- no runs, no properties, the "not considered part of the story contents" guard itself. */
+function guardParagraph() {
+	return {
+		runs: [],
+		properties: {},
+		extraGrpprl: [],
+		terminator: 13
+	};
+}
+/** One paragraph's own character footprint in the text stream: every run's own characters plus the paragraph's own terminator. Exported because write.ts counts the main document's own ccpText with the identical arithmetic -- one source, so the two can never disagree about what a paragraph costs. */
+function paragraphCharacters(paragraph) {
+	return 1 + paragraph.runs.reduce((count, run) => count + run.run.text.length, 0);
+}
+/** A CP-only plex (element size 0, [MS-DOC] 2.2.2's own "the data thus has a size of 0 bytes" shape PlcffndTxt/PlcfandTxt/PlcfendTxt/PlcfHdd all share): just the aCP array, one 4-byte little-endian value per key. */
+function buildCpOnlyPlex(keys) {
+	const bytes = new Uint8Array(keys.length * 4);
+	const view = new DataView(bytes.buffer);
+	keys.forEach((key, index) => {
+		view.setUint32(index * 4, key, true);
+	});
+	return bytes;
+}
+function finishSubdocument(paragraphs, storyStarts, characters) {
+	paragraphs.push(guardParagraph());
+	const ccp = characters + 1;
+	return {
+		paragraphs,
+		plex: buildCpOnlyPlex([
+			...storyStarts,
+			characters,
+			ccp
+		]),
+		ccp
+	};
+}
+function buildNoteSubdocument(notes) {
+	const paragraphs = [];
+	const storyStarts = [];
+	let characters = 0;
+	for (const note of notes) {
+		storyStarts.push(characters);
+		const story = note.text.split("\n").map((line) => ({
+			runs: line === "" ? [] : [textRun(line)],
+			properties: {},
+			extraGrpprl: [],
+			terminator: 13
+		}));
+		story.push(guardParagraph());
+		for (const paragraph of story) characters += paragraphCharacters(paragraph);
+		paragraphs.push(...story);
+	}
+	return finishSubdocument(paragraphs, storyStarts, characters);
+}
+function buildHeaderSubdocument(stories, sectionCount, dataStream, onWarning) {
+	const bySlot = /* @__PURE__ */ new Map();
+	for (const story of stories) {
+		if (!Number.isInteger(story.section) || story.section < 0 || story.section >= sectionCount) throw new require_errors.DocFormatError(`a header/footer story names section ${String(story.section)}, but this document has ${String(sectionCount)} sections`);
+		const key = `${String(story.section)}:${story.slot}`;
+		if (bySlot.has(key)) throw new require_errors.DocFormatError(`more than one header/footer story was given for section ${String(story.section)}'s ${story.slot} slot; a slot holds one story`);
+		bySlot.set(key, story);
+	}
+	const paragraphs = [];
+	const storyStarts = [];
+	let characters = 0;
+	for (let count = 0; count < 6; count += 1) storyStarts.push(0);
+	for (let section = 0; section < sectionCount; section += 1) for (const slot of require_headers_footers.SLOT_ORDER) {
+		storyStarts.push(characters);
+		const story = bySlot.get(`${String(section)}:${slot}`);
+		if (story === void 0) continue;
+		let content = require_table_write.flattenSectionBlocks(story.blocks, dataStream, onWarning);
+		if (content.length === 0) content = [{
+			runs: [],
+			properties: {},
+			extraGrpprl: [],
+			terminator: 13
+		}];
+		content.push(guardParagraph());
+		for (const paragraph of content) characters += paragraphCharacters(paragraph);
+		paragraphs.push(...content);
+	}
+	return finishSubdocument(paragraphs, storyStarts, characters);
+}
+function buildStorySubdocuments(document, dataStream, onWarning) {
+	return {
+		footnote: document.footnotes !== void 0 && document.footnotes.length > 0 ? buildNoteSubdocument(document.footnotes) : void 0,
+		header: document.headerFooterStories !== void 0 && document.headerFooterStories.length > 0 ? buildHeaderSubdocument(document.headerFooterStories, document.sections.length, dataStream, onWarning) : void 0,
+		comment: document.comments !== void 0 && document.comments.length > 0 ? buildNoteSubdocument(document.comments) : void 0,
+		endnote: document.endnotes !== void 0 && document.endnotes.length > 0 ? buildNoteSubdocument(document.endnotes) : void 0
+	};
+}
+//#endregion
+exports.buildHeaderSubdocument = buildHeaderSubdocument;
+exports.buildNoteSubdocument = buildNoteSubdocument;
+exports.buildStorySubdocuments = buildStorySubdocuments;
+exports.paragraphCharacters = paragraphCharacters;

package/dist/subdocument-write.d.cts

@@ -0,0 +1,42 @@
+import { t as DataStreamBuilder } from "./data-stream-BLCj4-V1.cjs";
+import { HeaderFooterStory } from "./headers-footers.cjs";
+import { r as WriteWarning, t as WriteParagraph } from "./write-CMB3qF4i.cjs";
+import { ContentDocument } from "document-schema.js";
+//#region src/subdocument-write.d.ts
+/** One written subdocument: its paragraphs (to be appended after the main document's own, in [MS-DOC]'s own subdocument order), the CP-only plex dividing them into stories, and the ccp the FIB states for it. `undefined` never appears here -- a subdocument with no stories is not written at all (write.ts leaves its ccp and fc/lcb pairs zero, exactly what the reader treats as "absent"). */
+interface StorySubdocument {
+  readonly paragraphs: readonly WriteParagraph[];
+  readonly plex: Uint8Array<ArrayBuffer>;
+  readonly ccp: number;
+}
+/** One paragraph's own character footprint in the text stream: every run's own characters plus the paragraph's own terminator. Exported because write.ts counts the main document's own ccpText with the identical arithmetic -- one source, so the two can never disagree about what a paragraph costs. */
+declare function paragraphCharacters(paragraph: WriteParagraph): number;
+declare function buildNoteSubdocument(notes: readonly {
+  readonly text: string;
+}[]): StorySubdocument;
+declare function buildHeaderSubdocument(stories: readonly HeaderFooterStory[], sectionCount: number, dataStream: DataStreamBuilder, onWarning?: WriteWarning): StorySubdocument;
+/** Every story subdocument a document carries, in [MS-DOC]'s own concatenation order (footnote, header, comment, endnote -- the same order notes.ts/read.ts count ccp boundaries in), each undefined when the document carries none of that kind. */
+interface StorySubdocuments {
+  readonly footnote: StorySubdocument | undefined;
+  readonly header: StorySubdocument | undefined;
+  readonly comment: StorySubdocument | undefined;
+  readonly endnote: StorySubdocument | undefined;
+}
+/** The input type's own optional story fields, isolated here so buildStorySubdocuments states its shape once -- writeDocContent's WritableDocContent satisfies it directly. */
+interface StorySources {
+  readonly footnotes?: readonly {
+    readonly text: string;
+  }[];
+  readonly endnotes?: readonly {
+    readonly text: string;
+  }[];
+  readonly comments?: readonly {
+    readonly text: string;
+  }[];
+  readonly headerFooterStories?: readonly HeaderFooterStory[];
+}
+declare function buildStorySubdocuments(document: StorySources & Pick<Extract<ContentDocument, {
+  kind: "wordprocessing";
+}>, "sections">, dataStream: DataStreamBuilder, onWarning?: WriteWarning): StorySubdocuments;
+//#endregion
+export { StorySubdocument, StorySubdocuments, buildHeaderSubdocument, buildNoteSubdocument, buildStorySubdocuments, paragraphCharacters };

package/dist/subdocument-write.d.ts

@@ -0,0 +1,42 @@
+import { t as DataStreamBuilder } from "./data-stream-BLCj4-V1.js";
+import { HeaderFooterStory } from "./headers-footers.js";
+import { r as WriteWarning, t as WriteParagraph } from "./write-t4rFgnA-.js";
+import { ContentDocument } from "document-schema.js";
+//#region src/subdocument-write.d.ts
+/** One written subdocument: its paragraphs (to be appended after the main document's own, in [MS-DOC]'s own subdocument order), the CP-only plex dividing them into stories, and the ccp the FIB states for it. `undefined` never appears here -- a subdocument with no stories is not written at all (write.ts leaves its ccp and fc/lcb pairs zero, exactly what the reader treats as "absent"). */
+interface StorySubdocument {
+  readonly paragraphs: readonly WriteParagraph[];
+  readonly plex: Uint8Array<ArrayBuffer>;
+  readonly ccp: number;
+}
+/** One paragraph's own character footprint in the text stream: every run's own characters plus the paragraph's own terminator. Exported because write.ts counts the main document's own ccpText with the identical arithmetic -- one source, so the two can never disagree about what a paragraph costs. */
+declare function paragraphCharacters(paragraph: WriteParagraph): number;
+declare function buildNoteSubdocument(notes: readonly {
+  readonly text: string;
+}[]): StorySubdocument;
+declare function buildHeaderSubdocument(stories: readonly HeaderFooterStory[], sectionCount: number, dataStream: DataStreamBuilder, onWarning?: WriteWarning): StorySubdocument;
+/** Every story subdocument a document carries, in [MS-DOC]'s own concatenation order (footnote, header, comment, endnote -- the same order notes.ts/read.ts count ccp boundaries in), each undefined when the document carries none of that kind. */
+interface StorySubdocuments {
+  readonly footnote: StorySubdocument | undefined;
+  readonly header: StorySubdocument | undefined;
+  readonly comment: StorySubdocument | undefined;
+  readonly endnote: StorySubdocument | undefined;
+}
+/** The input type's own optional story fields, isolated here so buildStorySubdocuments states its shape once -- writeDocContent's WritableDocContent satisfies it directly. */
+interface StorySources {
+  readonly footnotes?: readonly {
+    readonly text: string;
+  }[];
+  readonly endnotes?: readonly {
+    readonly text: string;
+  }[];
+  readonly comments?: readonly {
+    readonly text: string;
+  }[];
+  readonly headerFooterStories?: readonly HeaderFooterStory[];
+}
+declare function buildStorySubdocuments(document: StorySources & Pick<Extract<ContentDocument, {
+  kind: "wordprocessing";
+}>, "sections">, dataStream: DataStreamBuilder, onWarning?: WriteWarning): StorySubdocuments;
+//#endregion
+export { StorySubdocument, StorySubdocuments, buildHeaderSubdocument, buildNoteSubdocument, buildStorySubdocuments, paragraphCharacters };

package/dist/subdocument-write.js

@@ -0,0 +1,104 @@
+import { DocFormatError } from "./errors.js";
+import "./text/special.js";
+import { SLOT_ORDER } from "./headers-footers.js";
+import { flattenSectionBlocks } from "./table/write.js";
+//#region src/subdocument-write.ts
+/** A plain one-run text run: no character formatting, no extra grpprl -- a note body's own text carries no modelled formatting to state. */
+function textRun(text) {
+	return {
+		run: { text },
+		extraGrpprl: []
+	};
+}
+/** The bare paragraph mark every non-empty story ends with -- no runs, no properties, the "not considered part of the story contents" guard itself. */
+function guardParagraph() {
+	return {
+		runs: [],
+		properties: {},
+		extraGrpprl: [],
+		terminator: 13
+	};
+}
+/** One paragraph's own character footprint in the text stream: every run's own characters plus the paragraph's own terminator. Exported because write.ts counts the main document's own ccpText with the identical arithmetic -- one source, so the two can never disagree about what a paragraph costs. */
+function paragraphCharacters(paragraph) {
+	return 1 + paragraph.runs.reduce((count, run) => count + run.run.text.length, 0);
+}
+/** A CP-only plex (element size 0, [MS-DOC] 2.2.2's own "the data thus has a size of 0 bytes" shape PlcffndTxt/PlcfandTxt/PlcfendTxt/PlcfHdd all share): just the aCP array, one 4-byte little-endian value per key. */
+function buildCpOnlyPlex(keys) {
+	const bytes = new Uint8Array(keys.length * 4);
+	const view = new DataView(bytes.buffer);
+	keys.forEach((key, index) => {
+		view.setUint32(index * 4, key, true);
+	});
+	return bytes;
+}
+function finishSubdocument(paragraphs, storyStarts, characters) {
+	paragraphs.push(guardParagraph());
+	const ccp = characters + 1;
+	return {
+		paragraphs,
+		plex: buildCpOnlyPlex([
+			...storyStarts,
+			characters,
+			ccp
+		]),
+		ccp
+	};
+}
+function buildNoteSubdocument(notes) {
+	const paragraphs = [];
+	const storyStarts = [];
+	let characters = 0;
+	for (const note of notes) {
+		storyStarts.push(characters);
+		const story = note.text.split("\n").map((line) => ({
+			runs: line === "" ? [] : [textRun(line)],
+			properties: {},
+			extraGrpprl: [],
+			terminator: 13
+		}));
+		story.push(guardParagraph());
+		for (const paragraph of story) characters += paragraphCharacters(paragraph);
+		paragraphs.push(...story);
+	}
+	return finishSubdocument(paragraphs, storyStarts, characters);
+}
+function buildHeaderSubdocument(stories, sectionCount, dataStream, onWarning) {
+	const bySlot = /* @__PURE__ */ new Map();
+	for (const story of stories) {
+		if (!Number.isInteger(story.section) || story.section < 0 || story.section >= sectionCount) throw new DocFormatError(`a header/footer story names section ${String(story.section)}, but this document has ${String(sectionCount)} sections`);
+		const key = `${String(story.section)}:${story.slot}`;
+		if (bySlot.has(key)) throw new DocFormatError(`more than one header/footer story was given for section ${String(story.section)}'s ${story.slot} slot; a slot holds one story`);
+		bySlot.set(key, story);
+	}
+	const paragraphs = [];
+	const storyStarts = [];
+	let characters = 0;
+	for (let count = 0; count < 6; count += 1) storyStarts.push(0);
+	for (let section = 0; section < sectionCount; section += 1) for (const slot of SLOT_ORDER) {
+		storyStarts.push(characters);
+		const story = bySlot.get(`${String(section)}:${slot}`);
+		if (story === void 0) continue;
+		let content = flattenSectionBlocks(story.blocks, dataStream, onWarning);
+		if (content.length === 0) content = [{
+			runs: [],
+			properties: {},
+			extraGrpprl: [],
+			terminator: 13
+		}];
+		content.push(guardParagraph());
+		for (const paragraph of content) characters += paragraphCharacters(paragraph);
+		paragraphs.push(...content);
+	}
+	return finishSubdocument(paragraphs, storyStarts, characters);
+}
+function buildStorySubdocuments(document, dataStream, onWarning) {
+	return {
+		footnote: document.footnotes !== void 0 && document.footnotes.length > 0 ? buildNoteSubdocument(document.footnotes) : void 0,
+		header: document.headerFooterStories !== void 0 && document.headerFooterStories.length > 0 ? buildHeaderSubdocument(document.headerFooterStories, document.sections.length, dataStream, onWarning) : void 0,
+		comment: document.comments !== void 0 && document.comments.length > 0 ? buildNoteSubdocument(document.comments) : void 0,
+		endnote: document.endnotes !== void 0 && document.endnotes.length > 0 ? buildNoteSubdocument(document.endnotes) : void 0
+	};
+}
+//#endregion
+export { buildHeaderSubdocument, buildNoteSubdocument, buildStorySubdocuments, paragraphCharacters };

package/dist/subdocument.cjs

@@ -9,7 +9,14 @@ function readSubdocumentStories(wordDocument, table, pieceTable, context, subdoc
 	const range = require_text_characters.readTextRange(wordDocument, pieceTable, subdocStartCp, subdocStartCp + subdocLength);
 	const entries = require_text_paragraphs.readParagraphs(range.text, range.fcs, context);
 	const plc = require_plc.parsePlc(require_bytes.slice(table, boundaryFc, boundaryLcb, `${what} in the Table stream`), 0, what);
-	return require_text_paragraphs.splitEntriesByBoundaries(entries, plc.keys).slice(0, -1).map((story) => story.slice(0, -1));
+	return require_text_paragraphs.splitEntriesByBoundaries(entries, plc.keys).slice(0, -1).map((story) => endsWithGuardParagraph(story) ? story.slice(0, -1) : story);
+}
+function endsWithGuardParagraph(story) {
+	const last = story[story.length - 1];
+	if (last === void 0) return false;
+	if (last.blocks.length !== 1) return false;
+	const only = last.blocks[0];
+	return only?.kind === "paragraph" && only.runs.length === 0;
 }
 /** Joins a story's own paragraphs into plain text -- one line per paragraph, matching how ooxml.js's own Footnote/Comment reading concatenates a footnote or comment body's `w:t` runs rather than preserving paragraph/run structure. A footnote, endnote, or comment in this family is carried as text alone; only a header or footer keeps real block flow (headers-footers.ts). Non-paragraph blocks a story's own entries produced (an inline picture split out of one of its paragraphs) contribute no text of their own here, the same way an image has no plain-text spelling in ooxml.js's own footnote/comment reading either. */
 function storyText(entries) {

package/dist/subdocument.js

@@ -8,7 +8,14 @@ function readSubdocumentStories(wordDocument, table, pieceTable, context, subdoc
 	const range = readTextRange(wordDocument, pieceTable, subdocStartCp, subdocStartCp + subdocLength);
 	const entries = readParagraphs(range.text, range.fcs, context);
 	const plc = parsePlc(slice(table, boundaryFc, boundaryLcb, `${what} in the Table stream`), 0, what);
-	return splitEntriesByBoundaries(entries, plc.keys).slice(0, -1).map((story) => story.slice(0, -1));
+	return splitEntriesByBoundaries(entries, plc.keys).slice(0, -1).map((story) => endsWithGuardParagraph(story) ? story.slice(0, -1) : story);
+}
+function endsWithGuardParagraph(story) {
+	const last = story[story.length - 1];
+	if (last === void 0) return false;
+	if (last.blocks.length !== 1) return false;
+	const only = last.blocks[0];
+	return only?.kind === "paragraph" && only.runs.length === 0;
 }
 /** Joins a story's own paragraphs into plain text -- one line per paragraph, matching how ooxml.js's own Footnote/Comment reading concatenates a footnote or comment body's `w:t` runs rather than preserving paragraph/run structure. A footnote, endnote, or comment in this family is carried as text alone; only a header or footer keeps real block flow (headers-footers.ts). Non-paragraph blocks a story's own entries produced (an inline picture split out of one of its paragraphs) contribute no text of their own here, the same way an image has no plain-text spelling in ooxml.js's own footnote/comment reading either. */
 function storyText(entries) {

package/dist/table/write.cjs

@@ -1,6 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_errors = require("../errors.cjs");
-require("../data-stream.cjs");
 require("../text/special.cjs");
 const require_prop_fkp_write = require("../prop/fkp-write.cjs");
 const require_pictures_write = require("../pictures-write.cjs");
@@ -210,6 +209,22 @@ function imageParagraph(image, dataStream) {
 		terminator: 13
 	};
 }
+function appendPageBreak(output) {
+	const previous = output[output.length - 1];
+	if (previous?.terminator === 13) {
+		output[output.length - 1] = {
+			...previous,
+			terminator: 12
+		};
+		return;
+	}
+	output.push({
+		runs: [],
+		properties: {},
+		extraGrpprl: [],
+		terminator: 12
+	});
+}
 function flattenSectionBlocks(blocks, dataStream, onWarning) {
 	const output = [];
 	blocks.forEach((block, blockIndex) => {
@@ -230,6 +245,10 @@ function flattenSectionBlocks(blocks, dataStream, onWarning) {
 			output.push(imageParagraph(block, dataStream));
 			return;
 		}
+		if (block.kind === "pageBreak") {
+			appendPageBreak(output);
+			return;
+		}
 		throw new require_errors.DocUnsupportedError(`doc-codec's writer does not yet support '${block.kind}' blocks (see README's scope note)`);
 	});
 	return output;

package/dist/table/write.js

@@ -1,5 +1,4 @@
 import { DocFormatError, DocUnsupportedError } from "../errors.js";
-import "../data-stream.js";
 import "../text/special.js";
 import { fitsAloneOnPapxPage } from "../prop/fkp-write.js";
 import { buildInlinePicture } from "../pictures-write.js";
@@ -209,6 +208,22 @@ function imageParagraph(image, dataStream) {
 		terminator: 13
 	};
 }
+function appendPageBreak(output) {
+	const previous = output[output.length - 1];
+	if (previous?.terminator === 13) {
+		output[output.length - 1] = {
+			...previous,
+			terminator: 12
+		};
+		return;
+	}
+	output.push({
+		runs: [],
+		properties: {},
+		extraGrpprl: [],
+		terminator: 12
+	});
+}
 function flattenSectionBlocks(blocks, dataStream, onWarning) {
 	const output = [];
 	blocks.forEach((block, blockIndex) => {
@@ -229,6 +244,10 @@ function flattenSectionBlocks(blocks, dataStream, onWarning) {
 			output.push(imageParagraph(block, dataStream));
 			return;
 		}
+		if (block.kind === "pageBreak") {
+			appendPageBreak(output);
+			return;
+		}
 		throw new DocUnsupportedError(`doc-codec's writer does not yet support '${block.kind}' blocks (see README's scope note)`);
 	});
 	return output;

package/dist/write.cjs

@@ -13,8 +13,9 @@ const require_prop_chp_write = require("./prop/chp-write.cjs");
 const require_prop_pap_write = require("./prop/pap-write.cjs");
 const require_prop_sep_write = require("./prop/sep-write.cjs");
 const require_style_fonts = require("./style/fonts.cjs");
-const require_list_numbering_write = require("./list/numbering-write.cjs");
 const require_table_write = require("./table/write.cjs");
+const require_subdocument_write = require("./subdocument-write.cjs");
+const require_list_numbering_write = require("./list/numbering-write.cjs");
 let archive_codec = require("archive-codec");
 //#region src/write.ts
 /** Where the text is written in the WordDocument stream: past the FIB (which needs under 900 bytes for the fields this writer populates), on a page boundary though not required to be. */
@@ -38,7 +39,16 @@ function writeDocContent(document, options = {}) {
 			runningIndex += paragraphs.length;
 		}
 	}
-	const writeParagraphs = sectionParagraphLists.flat();
+	const mainParagraphs = sectionParagraphLists.flat();
+	const stories = require_subdocument_write.buildStorySubdocuments(document, dataStream, options.onWarning);
+	const ccpText = mainParagraphs.reduce((count, paragraph) => count + require_subdocument_write.paragraphCharacters(paragraph), 0);
+	const writeParagraphs = [
+		...mainParagraphs,
+		...stories.footnote?.paragraphs ?? [],
+		...stories.header?.paragraphs ?? [],
+		...stories.comment?.paragraphs ?? [],
+		...stories.endnote?.paragraphs ?? []
+	];
 	const FIRST_NON_HEADING_ISTD = 10;
 	const MAX_HEADING_ISTD = 9;
 	const styleNames = /* @__PURE__ */ new Map();
@@ -176,7 +186,7 @@ function writeDocContent(document, options = {}) {
 	const papxBinTable = require_prop_fkp_write.buildPropertyBinTable([...papxPages.map(require_prop_fkp_write.firstFcOfPage), textFcLim], papxPages.map((_, index) => papxPageStart + index));
 	const stsh = require_style_stsh.buildStshForStyles(styleNames);
 	const fontTable = fontNames.length > 0 ? require_style_fonts.buildFontTable(fontNames) : void 0;
-	const plcfSed = require_prop_sep_write.buildPlcfSed(sectionStartCps, text.length, fcSepxList);
+	const plcfSed = require_prop_sep_write.buildPlcfSed(sectionStartCps, ccpText, fcSepxList);
 	let cursor = 0;
 	const place = (bytes) => {
 		const offset = cursor;
@@ -191,6 +201,10 @@ function writeDocContent(document, options = {}) {
 	const fcSttbfFfn = fontTable !== void 0 ? place(fontTable) : 0;
 	const fcPlfLst = numberingTables !== void 0 ? place(numberingTables.plfLst) : 0;
 	const fcPlfLfo = numberingTables !== void 0 ? place(numberingTables.plfLfo) : 0;
+	const fcPlcffndTxt = stories.footnote !== void 0 ? place(stories.footnote.plex) : 0;
+	const fcPlcfHdd = stories.header !== void 0 ? place(stories.header.plex) : 0;
+	const fcPlcfandTxt = stories.comment !== void 0 ? place(stories.comment.plex) : 0;
+	const fcPlcfendTxt = stories.endnote !== void 0 ? place(stories.endnote.plex) : 0;
 	const table = new Uint8Array(cursor);
 	table.set(clx, fcClx);
 	table.set(chpxBinTable, fcPlcfBteChpx);
@@ -202,8 +216,12 @@ function writeDocContent(document, options = {}) {
 		table.set(numberingTables.plfLst, fcPlfLst);
 		table.set(numberingTables.plfLfo, fcPlfLfo);
 	}
+	if (stories.footnote !== void 0) table.set(stories.footnote.plex, fcPlcffndTxt);
+	if (stories.header !== void 0) table.set(stories.header.plex, fcPlcfHdd);
+	if (stories.comment !== void 0) table.set(stories.comment.plex, fcPlcfandTxt);
+	if (stories.endnote !== void 0) table.set(stories.endnote.plex, fcPlcfendTxt);
 	const fib = require_fib_write.buildFib({
-		ccpText: text.length,
+		ccpText,
 		cbMac: wordDocument.length,
 		fcClx,
 		lcbClx: clx.length,
@@ -220,7 +238,19 @@ function writeDocContent(document, options = {}) {
 		fcPlfLst,
 		lcbPlfLst: numberingTables?.lcbPlfLst ?? 0,
 		fcPlfLfo,
-		lcbPlfLfo: numberingTables?.plfLfo.length ?? 0
+		lcbPlfLfo: numberingTables?.plfLfo.length ?? 0,
+		ccpFtn: stories.footnote?.ccp ?? 0,
+		fcPlcffndTxt,
+		lcbPlcffndTxt: stories.footnote?.plex.length ?? 0,
+		ccpHdd: stories.header?.ccp ?? 0,
+		fcPlcfHdd,
+		lcbPlcfHdd: stories.header?.plex.length ?? 0,
+		ccpAtn: stories.comment?.ccp ?? 0,
+		fcPlcfandTxt,
+		lcbPlcfandTxt: stories.comment?.plex.length ?? 0,
+		ccpEdn: stories.endnote?.ccp ?? 0,
+		fcPlcfendTxt,
+		lcbPlcfendTxt: stories.endnote?.plex.length ?? 0
 	});
 	wordDocument.set(fib, 0);
 	const streams = [{

package/dist/write.d.cts

@@ -1,10 +1,19 @@
+import { HeaderFooterStory } from "./headers-footers.cjs";
 import { r as WriteWarning } from "./write-CMB3qF4i.cjs";
+import { Comment, Footnote } from "./notes.cjs";
 import { ContentDocument } from "document-schema.js";
 //#region src/write.d.ts
 interface WriteDocContentOptions {
   /** Reports a non-fatal write-time degradation -- today, only table/write.ts's own per-row lost-boundary-budget fallback (ExaDev/documents.js#1013), the same `onWarning` shape byte-codec's PNG decoder and pdf-codec already use for a recoverable, non-fatal defect. Not a guarantee the write itself goes on to succeed: when a row's own assigned lost boundaries can't be trimmed down to a split that fits at all, this still fires once -- reporting that the row's boundaries could not be stated and that its fully-unsplit encoding is being attempted instead -- before writeDocContent can discover, further down the same pipeline, that even that unsplit encoding overflows the row's own byte budget and throws its usual DocFormatError; the warning describes what this fallback could not recover, not a promise that a hard failure won't immediately follow it. It is never called in place of a genuine refusal this writer makes outright (an unsupported block kind, more than one section, and so on) -- those always throw DocFormatError/DocUnsupportedError directly, with no warning first. */
   readonly onWarning?: WriteWarning;
 }
-declare function writeDocContent(document: ContentDocument, options?: WriteDocContentOptions): Uint8Array<ArrayBuffer>;
+/** writeDocContent's own input: a `ContentDocument` widened by the same story fields `readDocContent`'s own `DocContent` output carries (read.ts) -- footnotes, endnotes, comments, and header/footer stories -- each OPTIONAL, exactly the shape ooxml.js's own `DocxContent` input already established for the identical constructs, so a plain `ContentDocument` (none of the four stated) still writes exactly as it always did, while a genuine `DocContent` assigns straight across. A type-alias intersection rather than an interface for the identical reason DocContent is one: ContentDocument is a union of document kinds, and only the intersection spreads its members statically. The stories are written back as genuine subdocuments (subdocument-write.ts); a document that states none writes no subdocument at all, with every story ccp and fc/lcb pair left zero. */
+type WritableDocContent = ContentDocument & {
+  readonly footnotes?: readonly Footnote[];
+  readonly endnotes?: readonly Footnote[];
+  readonly comments?: readonly Comment[];
+  readonly headerFooterStories?: readonly HeaderFooterStory[];
+};
+declare function writeDocContent(document: WritableDocContent, options?: WriteDocContentOptions): Uint8Array<ArrayBuffer>;
 //#endregion
-export { WriteDocContentOptions, writeDocContent };
+export { WritableDocContent, WriteDocContentOptions, writeDocContent };