doc-codec 0.0.0 → 1.0.0

package/dist/read.js

@@ -0,0 +1,169 @@
+import { DocFormatError } from "./errors.js";
+import { slice } from "./bytes.js";
+import { WORD_DOCUMENT_STREAM } from "./detect.js";
+import { parseFib, tableStreamName } from "./fib/fib.js";
+import { parseClx } from "./text/piece-table.js";
+import { readTextRange } from "./text/characters.js";
+import { endsParagraph, isAnchorOnly } from "./text/special.js";
+import { readGrpprl } from "./prop/sprm.js";
+import { PropertyBinTable } from "./prop/fkp.js";
+import { applyCharacterSprms } from "./prop/chp.js";
+import { applyParagraphSprms } from "./prop/pap.js";
+import { headingLevelFromIstd, parseStsh } from "./style/stsh.js";
+import { readCompoundFile } from "archive-codec";
+//#region src/read.ts
+/** The page geometry every section is given, because this reader does not yet read a document's own. US Letter with one-inch margins is Word's own default for a new document; a document that states otherwise is not yet consulted, so this is a placeholder the schema requires rather than a fact read from the file. */
+const DEFAULT_PAGE_SIZE = {
+	widthPt: 612,
+	heightPt: 792
+};
+const DEFAULT_MARGINS = {
+	topPt: 72,
+	rightPt: 72,
+	bottomPt: 72,
+	leftPt: 72
+};
+function readDocStreams(bytes) {
+	const streams = readCompoundFile(bytes);
+	const wordDocument = streams.find((stream) => stream.path === WORD_DOCUMENT_STREAM);
+	if (wordDocument === void 0) throw new DocFormatError(`this compound file has no "${WORD_DOCUMENT_STREAM}" stream, so it is not a Word Binary File (it holds: ${streams.map((stream) => stream.path).join(", ")})`);
+	const fib = parseFib(wordDocument.bytes);
+	const wanted = tableStreamName(fib);
+	const table = streams.find((stream) => stream.path === wanted);
+	if (table === void 0) throw new DocFormatError(`FibBase.fWhichTblStm selects the "${wanted}" stream, which this compound file does not contain`);
+	return {
+		wordDocument: wordDocument.bytes,
+		table: table.bytes,
+		fib
+	};
+}
+function readDocContent(bytes) {
+	const { wordDocument, table, fib } = readDocStreams(bytes);
+	const pieceTable = parseClx(slice(table, fib.fcClx, fib.lcbClx, "Clx in the Table stream"));
+	const styles = fib.lcbStshf > 0 ? parseStsh(slice(table, fib.fcStshf, fib.lcbStshf, "STSH in the Table stream")) : void 0;
+	const chpxTable = new PropertyBinTable(wordDocument, slice(table, fib.fcPlcfBteChpx, fib.lcbPlcfBteChpx, "PlcBteChpx in the Table stream"), "PlcBteChpx");
+	const papxTable = new PropertyBinTable(wordDocument, slice(table, fib.fcPlcfBtePapx, fib.lcbPlcfBtePapx, "PlcBtePapx in the Table stream"), "PlcBtePapx");
+	const range = readTextRange(wordDocument, pieceTable, 0, fib.ccpText);
+	const blocks = readParagraphs(range.text, range.fcs, {
+		chpxTable,
+		papxTable,
+		styles,
+		characterProperties: /* @__PURE__ */ new Map()
+	});
+	return {
+		kind: "wordprocessing",
+		metadata: {},
+		sections: [{
+			pageSize: DEFAULT_PAGE_SIZE,
+			margins: DEFAULT_MARGINS,
+			blocks
+		}]
+	};
+}
+function readParagraphs(text, fcs, context) {
+	const blocks = [];
+	let start = 0;
+	for (let index = 0; index < text.length; index += 1) {
+		const code = text.charCodeAt(index);
+		if (!endsParagraph(code)) continue;
+		const markFc = fcs[index];
+		if (markFc === void 0) throw new DocFormatError(`character ${index} has no byte offset, so its paragraph's properties cannot be located`);
+		blocks.push(buildParagraph(text.slice(start, index), fcs.slice(start, index), markFc, context));
+		start = index + 1;
+	}
+	if (start < text.length) {
+		const firstFc = fcs[start];
+		if (firstFc === void 0) throw new DocFormatError(`character ${start} has no byte offset, so the trailing paragraph's properties cannot be located`);
+		blocks.push(buildParagraph(text.slice(start), fcs.slice(start), firstFc, context));
+	}
+	return blocks;
+}
+function buildParagraph(text, fcs, propertyFc, context) {
+	const papx = context.papxTable.papx(propertyFc);
+	const properties = {};
+	if (papx !== void 0) {
+		properties.istd = papx.istd;
+		applyParagraphSprms(readGrpprl(papx.grpprl), properties);
+	}
+	return {
+		kind: "paragraph",
+		runs: buildRuns(text, fcs, context),
+		...paragraphAttributes(properties, context)
+	};
+}
+function paragraphAttributes(properties, context) {
+	const attributes = {};
+	const istd = properties.istd;
+	if (istd !== void 0) {
+		const style = context.styles?.styles[istd];
+		if (style !== void 0 && style.name !== "") attributes.styleId = style.name;
+		const headingLevel = headingLevelFromIstd(istd);
+		if (headingLevel !== void 0) attributes.headingLevel = headingLevel;
+	}
+	if (attributes.headingLevel === void 0 && properties.outlineLevel !== void 0) attributes.headingLevel = properties.outlineLevel + 1;
+	if (properties.alignment !== void 0) attributes.alignment = properties.alignment;
+	if (properties.spacingBeforePt !== void 0) attributes.spacingBeforePt = properties.spacingBeforePt;
+	if (properties.spacingAfterPt !== void 0) attributes.spacingAfterPt = properties.spacingAfterPt;
+	if (properties.lineSpacing !== void 0) attributes.lineSpacing = properties.lineSpacing;
+	if (properties.indentLeftPt !== void 0) attributes.indentLeftPt = properties.indentLeftPt;
+	if (properties.indentFirstLinePt !== void 0) attributes.indentFirstLinePt = properties.indentFirstLinePt;
+	if (properties.pageBreakBefore === true) attributes.pageBreakBefore = true;
+	if (properties.listId !== void 0) attributes.list = {
+		numId: String(properties.listId),
+		level: properties.listLevel ?? 0
+	};
+	return attributes;
+}
+function buildRuns(text, fcs, context) {
+	const runs = [];
+	let currentKey;
+	let currentText = "";
+	let currentProperties = {};
+	const enclosingInstruction = [];
+	let inInstruction = false;
+	const flush = () => {
+		if (currentText !== "") runs.push({
+			text: currentText,
+			...currentProperties
+		});
+		currentText = "";
+	};
+	for (let index = 0; index < text.length; index += 1) {
+		const code = text.charCodeAt(index);
+		if (code === 19) {
+			flush();
+			enclosingInstruction.push(inInstruction);
+			inInstruction = true;
+			continue;
+		}
+		if (code === 20) {
+			inInstruction = false;
+			continue;
+		}
+		if (code === 21) {
+			inInstruction = enclosingInstruction.pop() ?? inInstruction;
+			continue;
+		}
+		if (inInstruction || isAnchorOnly(code)) continue;
+		const fc = fcs[index];
+		if (fc === void 0) throw new DocFormatError(`character ${index} of a paragraph has no byte offset, so its formatting cannot be located`);
+		const grpprl = context.chpxTable.chpxGrpprl(fc);
+		const key = grpprl === void 0 ? "none" : `${grpprl.byteOffset}:${grpprl.byteLength}`;
+		if (key !== currentKey) {
+			flush();
+			currentKey = key;
+			let properties = context.characterProperties.get(key);
+			if (properties === void 0) {
+				properties = {};
+				if (grpprl !== void 0) applyCharacterSprms(readGrpprl(grpprl), properties);
+				context.characterProperties.set(key, properties);
+			}
+			currentProperties = properties;
+		}
+		currentText += String.fromCharCode(code === 11 ? 10 : code);
+	}
+	flush();
+	return runs;
+}
+//#endregion
+export { readDocContent, readDocStreams };

package/dist/style/stsh.cjs

@@ -0,0 +1,65 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_errors = require("../errors.cjs");
+const require_bytes = require("../bytes.cjs");
+//#region src/style/stsh.ts
+/** Stshif is a fixed 18 bytes: cstd, cbSTDBaseInFile, a bit field, stiMaxWhenSaved, istdMaxFixedWhenSaved, nVerBuiltInNamesWhenSaved, and the three default font indexes. */
+const STSHIF_SIZE = 18;
+/** Stshif.cbSTDBaseInFile "MUST be 0x000A when the Stdf structure does not contain an StdfPost2000 structure and MUST be 0x0012 when [it] does". */
+const STDF_SIZE_WITHOUT_POST_2000 = 10;
+const STDF_SIZE_WITH_POST_2000 = 18;
+/** StdfBase.sti's "0x0FFE for user-defined styles"; anything else is an application-defined style whose sti identifies it. */
+const STI_USER_DEFINED = 4094;
+/** StdfBase.stk, [MS-DOC] 2.9.269 -- which of ECMA-376's ST_StyleType values this style is. */
+const STK = {
+	paragraph: 1,
+	character: 2,
+	table: 3,
+	numbering: 4
+};
+/** StdfBase.istdBase's "0x0FFF if this style does not inherit from any other style". */
+const ISTD_BASE_NONE = 4095;
+function parseStsh(stsh) {
+	const cbStshi = require_bytes.readUint16LE(stsh, 0);
+	const stshi = require_bytes.slice(stsh, 2, cbStshi, "STSH.lpstshi.stshi");
+	if (stshi.length < STSHIF_SIZE) throw new require_errors.DocFormatError(`STSHI is ${stshi.length} bytes, shorter than the fixed ${STSHIF_SIZE}-byte Stshif it must begin with`);
+	const cstd = require_bytes.readUint16LE(stshi, 0);
+	const cbStdBaseInFile = require_bytes.readUint16LE(stshi, 2);
+	if (cbStdBaseInFile !== STDF_SIZE_WITHOUT_POST_2000 && cbStdBaseInFile !== STDF_SIZE_WITH_POST_2000) throw new require_errors.DocFormatError(`Stshif.cbSTDBaseInFile is 0x${cbStdBaseInFile.toString(16)}, neither of the two sizes [MS-DOC] permits for an Stdf (0x000A without an StdfPost2000, 0x0012 with one)`);
+	const styles = [];
+	let cursor = 2 + cbStshi;
+	for (let istd = 0; istd < cstd; istd += 1) {
+		const cbStd = require_bytes.readInt16LE(stsh, cursor);
+		if (cbStd < 0) throw new require_errors.DocFormatError(`LPStd for istd ${istd} declares cbStd ${cbStd}; [MS-DOC] requires it not to be less than 0`);
+		const std = require_bytes.slice(stsh, cursor + 2, cbStd, `STD for istd ${istd}`);
+		styles.push(cbStd === 0 ? void 0 : parseStd(std, istd, cbStdBaseInFile));
+		cursor += 2 + cbStd + cbStd % 2;
+	}
+	return { styles };
+}
+function parseStd(std, istd, cbStdBaseInFile) {
+	const word0 = require_bytes.readUint16LE(std, 0);
+	const word1 = require_bytes.readUint16LE(std, 2);
+	const istdBase = word1 >> 4 & 4095;
+	return {
+		istd,
+		sti: word0 & 4095,
+		stk: word1 & 15,
+		istdBase: istdBase === ISTD_BASE_NONE ? void 0 : istdBase,
+		name: readXstz(std, cbStdBaseInFile, `name of the style at istd ${istd}`)
+	};
+}
+function readXstz(bytes, offset, what) {
+	const cch = require_bytes.readUint16LE(bytes, offset);
+	const chars = require_bytes.slice(bytes, offset + 2, cch * 2, what);
+	let out = "";
+	for (let index = 0; index < cch; index += 1) out += String.fromCharCode(require_bytes.readUint16LE(chars, index * 2));
+	return out;
+}
+function headingLevelFromIstd(istd) {
+	return istd >= 1 && istd <= 9 ? istd : void 0;
+}
+//#endregion
+exports.STI_USER_DEFINED = STI_USER_DEFINED;
+exports.STK = STK;
+exports.headingLevelFromIstd = headingLevelFromIstd;
+exports.parseStsh = parseStsh;

package/dist/style/stsh.d.cts

@@ -0,0 +1,29 @@
+//#region src/style/stsh.d.ts
+/** StdfBase.sti's "0x0FFE for user-defined styles"; anything else is an application-defined style whose sti identifies it. */
+declare const STI_USER_DEFINED = 4094;
+/** StdfBase.stk, [MS-DOC] 2.9.269 -- which of ECMA-376's ST_StyleType values this style is. */
+declare const STK: {
+  readonly paragraph: 1;
+  readonly character: 2;
+  readonly table: 3;
+  readonly numbering: 4;
+};
+interface Style {
+  /** The style's index in STSH.rglpstd, which is what sprmPIstd and sprmCIstd name. */
+  readonly istd: number;
+  /** The invariant application-defined style identifier, or STI_USER_DEFINED for a style the document itself defines. */
+  readonly sti: number;
+  readonly stk: number;
+  /** The istd this style inherits from, or undefined when StdfBase.istdBase is 0x0FFF ("this style does not inherit from any other style"). */
+  readonly istdBase: number | undefined;
+  /** The style's primary name, from the STD's own Xstz. */
+  readonly name: string;
+}
+interface StyleSheet {
+  /** Indexed by istd; a hole is a slot [MS-DOC] permits to be empty ("A style definition can be empty, in which case cbStd MUST be 0"). */
+  readonly styles: readonly (Style | undefined)[];
+}
+declare function parseStsh(stsh: Uint8Array): StyleSheet;
+declare function headingLevelFromIstd(istd: number): number | undefined;
+//#endregion
+export { STI_USER_DEFINED, STK, Style, StyleSheet, headingLevelFromIstd, parseStsh };

package/dist/style/stsh.d.ts

@@ -0,0 +1,29 @@
+//#region src/style/stsh.d.ts
+/** StdfBase.sti's "0x0FFE for user-defined styles"; anything else is an application-defined style whose sti identifies it. */
+declare const STI_USER_DEFINED = 4094;
+/** StdfBase.stk, [MS-DOC] 2.9.269 -- which of ECMA-376's ST_StyleType values this style is. */
+declare const STK: {
+  readonly paragraph: 1;
+  readonly character: 2;
+  readonly table: 3;
+  readonly numbering: 4;
+};
+interface Style {
+  /** The style's index in STSH.rglpstd, which is what sprmPIstd and sprmCIstd name. */
+  readonly istd: number;
+  /** The invariant application-defined style identifier, or STI_USER_DEFINED for a style the document itself defines. */
+  readonly sti: number;
+  readonly stk: number;
+  /** The istd this style inherits from, or undefined when StdfBase.istdBase is 0x0FFF ("this style does not inherit from any other style"). */
+  readonly istdBase: number | undefined;
+  /** The style's primary name, from the STD's own Xstz. */
+  readonly name: string;
+}
+interface StyleSheet {
+  /** Indexed by istd; a hole is a slot [MS-DOC] permits to be empty ("A style definition can be empty, in which case cbStd MUST be 0"). */
+  readonly styles: readonly (Style | undefined)[];
+}
+declare function parseStsh(stsh: Uint8Array): StyleSheet;
+declare function headingLevelFromIstd(istd: number): number | undefined;
+//#endregion
+export { STI_USER_DEFINED, STK, Style, StyleSheet, headingLevelFromIstd, parseStsh };

package/dist/style/stsh.js

@@ -0,0 +1,61 @@
+import { DocFormatError } from "../errors.js";
+import { readInt16LE, readUint16LE, slice } from "../bytes.js";
+//#region src/style/stsh.ts
+/** Stshif is a fixed 18 bytes: cstd, cbSTDBaseInFile, a bit field, stiMaxWhenSaved, istdMaxFixedWhenSaved, nVerBuiltInNamesWhenSaved, and the three default font indexes. */
+const STSHIF_SIZE = 18;
+/** Stshif.cbSTDBaseInFile "MUST be 0x000A when the Stdf structure does not contain an StdfPost2000 structure and MUST be 0x0012 when [it] does". */
+const STDF_SIZE_WITHOUT_POST_2000 = 10;
+const STDF_SIZE_WITH_POST_2000 = 18;
+/** StdfBase.sti's "0x0FFE for user-defined styles"; anything else is an application-defined style whose sti identifies it. */
+const STI_USER_DEFINED = 4094;
+/** StdfBase.stk, [MS-DOC] 2.9.269 -- which of ECMA-376's ST_StyleType values this style is. */
+const STK = {
+	paragraph: 1,
+	character: 2,
+	table: 3,
+	numbering: 4
+};
+/** StdfBase.istdBase's "0x0FFF if this style does not inherit from any other style". */
+const ISTD_BASE_NONE = 4095;
+function parseStsh(stsh) {
+	const cbStshi = readUint16LE(stsh, 0);
+	const stshi = slice(stsh, 2, cbStshi, "STSH.lpstshi.stshi");
+	if (stshi.length < STSHIF_SIZE) throw new DocFormatError(`STSHI is ${stshi.length} bytes, shorter than the fixed ${STSHIF_SIZE}-byte Stshif it must begin with`);
+	const cstd = readUint16LE(stshi, 0);
+	const cbStdBaseInFile = readUint16LE(stshi, 2);
+	if (cbStdBaseInFile !== STDF_SIZE_WITHOUT_POST_2000 && cbStdBaseInFile !== STDF_SIZE_WITH_POST_2000) throw new DocFormatError(`Stshif.cbSTDBaseInFile is 0x${cbStdBaseInFile.toString(16)}, neither of the two sizes [MS-DOC] permits for an Stdf (0x000A without an StdfPost2000, 0x0012 with one)`);
+	const styles = [];
+	let cursor = 2 + cbStshi;
+	for (let istd = 0; istd < cstd; istd += 1) {
+		const cbStd = readInt16LE(stsh, cursor);
+		if (cbStd < 0) throw new DocFormatError(`LPStd for istd ${istd} declares cbStd ${cbStd}; [MS-DOC] requires it not to be less than 0`);
+		const std = slice(stsh, cursor + 2, cbStd, `STD for istd ${istd}`);
+		styles.push(cbStd === 0 ? void 0 : parseStd(std, istd, cbStdBaseInFile));
+		cursor += 2 + cbStd + cbStd % 2;
+	}
+	return { styles };
+}
+function parseStd(std, istd, cbStdBaseInFile) {
+	const word0 = readUint16LE(std, 0);
+	const word1 = readUint16LE(std, 2);
+	const istdBase = word1 >> 4 & 4095;
+	return {
+		istd,
+		sti: word0 & 4095,
+		stk: word1 & 15,
+		istdBase: istdBase === ISTD_BASE_NONE ? void 0 : istdBase,
+		name: readXstz(std, cbStdBaseInFile, `name of the style at istd ${istd}`)
+	};
+}
+function readXstz(bytes, offset, what) {
+	const cch = readUint16LE(bytes, offset);
+	const chars = slice(bytes, offset + 2, cch * 2, what);
+	let out = "";
+	for (let index = 0; index < cch; index += 1) out += String.fromCharCode(readUint16LE(chars, index * 2));
+	return out;
+}
+function headingLevelFromIstd(istd) {
+	return istd >= 1 && istd <= 9 ? istd : void 0;
+}
+//#endregion
+export { STI_USER_DEFINED, STK, headingLevelFromIstd, parseStsh };

package/dist/text/characters.cjs

@@ -0,0 +1,69 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_errors = require("../errors.cjs");
+const require_bytes = require("../bytes.cjs");
+const require_plc = require("../plc.cjs");
+const require_text_piece_table = require("./piece-table.cjs");
+//#region src/text/characters.ts
+const COMPRESSED_CHARACTER_MAP = /* @__PURE__ */ new Map([
+	[130, 8218],
+	[131, 402],
+	[132, 8222],
+	[133, 8230],
+	[134, 8224],
+	[135, 8225],
+	[136, 710],
+	[137, 8240],
+	[138, 352],
+	[139, 8249],
+	[140, 338],
+	[145, 8216],
+	[146, 8217],
+	[147, 8220],
+	[148, 8221],
+	[149, 8226],
+	[150, 8211],
+	[151, 8212],
+	[152, 732],
+	[153, 8482],
+	[154, 353],
+	[155, 8250],
+	[156, 339],
+	[159, 376]
+]);
+function readTextRange(wordDocument, table, cpStart, cpEnd) {
+	if (!Number.isInteger(cpStart) || !Number.isInteger(cpEnd) || cpStart < 0) throw new require_errors.DocFormatError(`text range [${cpStart}, ${cpEnd}) is not a pair of non-negative integer character positions`);
+	if (cpEnd < cpStart) throw new require_errors.DocFormatError(`text range [${cpStart}, ${cpEnd}) ends before it begins`);
+	if (cpEnd > table.lastCp) throw new require_errors.DocFormatError(`text range [${cpStart}, ${cpEnd}) extends past character position ${table.lastCp}, the last the piece table defines`);
+	const codeUnits = [];
+	const fcs = [];
+	let cp = cpStart;
+	while (cp < cpEnd) {
+		const index = require_plc.findLargestAtMost(table.cpKeys, cp);
+		if (index === void 0) throw new require_errors.DocFormatError(`character position ${cp} falls outside every piece in the piece table`);
+		const piece = table.pieces[index];
+		if (piece === void 0) throw new require_errors.DocFormatError(`piece ${index} is absent from a piece table of ${table.pieces.length} pieces`);
+		const stop = Math.min(cpEnd, piece.cpEnd);
+		for (; cp < stop; cp += 1) {
+			const fc = require_text_piece_table.characterOffset(piece, cp);
+			fcs.push(fc);
+			if (piece.compressed) {
+				const byte = require_bytes.readUint8(wordDocument, fc);
+				codeUnits.push(COMPRESSED_CHARACTER_MAP.get(byte) ?? byte);
+			} else codeUnits.push(require_bytes.readUint16LE(wordDocument, fc));
+		}
+	}
+	return {
+		text: fromCodeUnits(codeUnits),
+		fcs,
+		cpStart
+	};
+}
+const FROM_CHAR_CODE_CHUNK = 4096;
+function fromCodeUnits(codeUnits) {
+	let out = "";
+	for (let start = 0; start < codeUnits.length; start += FROM_CHAR_CODE_CHUNK) out += String.fromCharCode(...codeUnits.slice(start, start + FROM_CHAR_CODE_CHUNK));
+	return out;
+}
+//#endregion
+exports.COMPRESSED_CHARACTER_MAP = COMPRESSED_CHARACTER_MAP;
+exports.readTextRange = readTextRange;

package/dist/text/characters.d.cts

@@ -0,0 +1,14 @@
+import { PieceTable } from "./piece-table.cjs";
+//#region src/text/characters.d.ts
+declare const COMPRESSED_CHARACTER_MAP: ReadonlyMap<number, number>;
+interface TextRange {
+  /** The reconstructed characters, one UTF-16 code unit per character position. */
+  readonly text: string;
+  /** The WordDocument byte offset of each character, parallel to `text`. This is the key every formatting lookup is performed on. */
+  readonly fcs: readonly number[];
+  /** The character position `text[0]` and `fcs[0]` correspond to, so a caller can convert an index in this range back to a document-wide CP. */
+  readonly cpStart: number;
+}
+declare function readTextRange(wordDocument: Uint8Array, table: PieceTable, cpStart: number, cpEnd: number): TextRange;
+//#endregion
+export { COMPRESSED_CHARACTER_MAP, TextRange, readTextRange };

package/dist/text/characters.d.ts

@@ -0,0 +1,14 @@
+import { PieceTable } from "./piece-table.js";
+//#region src/text/characters.d.ts
+declare const COMPRESSED_CHARACTER_MAP: ReadonlyMap<number, number>;
+interface TextRange {
+  /** The reconstructed characters, one UTF-16 code unit per character position. */
+  readonly text: string;
+  /** The WordDocument byte offset of each character, parallel to `text`. This is the key every formatting lookup is performed on. */
+  readonly fcs: readonly number[];
+  /** The character position `text[0]` and `fcs[0]` correspond to, so a caller can convert an index in this range back to a document-wide CP. */
+  readonly cpStart: number;
+}
+declare function readTextRange(wordDocument: Uint8Array, table: PieceTable, cpStart: number, cpEnd: number): TextRange;
+//#endregion
+export { COMPRESSED_CHARACTER_MAP, TextRange, readTextRange };

package/dist/text/characters.js

@@ -0,0 +1,67 @@
+import { DocFormatError } from "../errors.js";
+import { readUint16LE, readUint8 } from "../bytes.js";
+import { findLargestAtMost } from "../plc.js";
+import { characterOffset } from "./piece-table.js";
+//#region src/text/characters.ts
+const COMPRESSED_CHARACTER_MAP = /* @__PURE__ */ new Map([
+	[130, 8218],
+	[131, 402],
+	[132, 8222],
+	[133, 8230],
+	[134, 8224],
+	[135, 8225],
+	[136, 710],
+	[137, 8240],
+	[138, 352],
+	[139, 8249],
+	[140, 338],
+	[145, 8216],
+	[146, 8217],
+	[147, 8220],
+	[148, 8221],
+	[149, 8226],
+	[150, 8211],
+	[151, 8212],
+	[152, 732],
+	[153, 8482],
+	[154, 353],
+	[155, 8250],
+	[156, 339],
+	[159, 376]
+]);
+function readTextRange(wordDocument, table, cpStart, cpEnd) {
+	if (!Number.isInteger(cpStart) || !Number.isInteger(cpEnd) || cpStart < 0) throw new DocFormatError(`text range [${cpStart}, ${cpEnd}) is not a pair of non-negative integer character positions`);
+	if (cpEnd < cpStart) throw new DocFormatError(`text range [${cpStart}, ${cpEnd}) ends before it begins`);
+	if (cpEnd > table.lastCp) throw new DocFormatError(`text range [${cpStart}, ${cpEnd}) extends past character position ${table.lastCp}, the last the piece table defines`);
+	const codeUnits = [];
+	const fcs = [];
+	let cp = cpStart;
+	while (cp < cpEnd) {
+		const index = findLargestAtMost(table.cpKeys, cp);
+		if (index === void 0) throw new DocFormatError(`character position ${cp} falls outside every piece in the piece table`);
+		const piece = table.pieces[index];
+		if (piece === void 0) throw new DocFormatError(`piece ${index} is absent from a piece table of ${table.pieces.length} pieces`);
+		const stop = Math.min(cpEnd, piece.cpEnd);
+		for (; cp < stop; cp += 1) {
+			const fc = characterOffset(piece, cp);
+			fcs.push(fc);
+			if (piece.compressed) {
+				const byte = readUint8(wordDocument, fc);
+				codeUnits.push(COMPRESSED_CHARACTER_MAP.get(byte) ?? byte);
+			} else codeUnits.push(readUint16LE(wordDocument, fc));
+		}
+	}
+	return {
+		text: fromCodeUnits(codeUnits),
+		fcs,
+		cpStart
+	};
+}
+const FROM_CHAR_CODE_CHUNK = 4096;
+function fromCodeUnits(codeUnits) {
+	let out = "";
+	for (let start = 0; start < codeUnits.length; start += FROM_CHAR_CODE_CHUNK) out += String.fromCharCode(...codeUnits.slice(start, start + FROM_CHAR_CODE_CHUNK));
+	return out;
+}
+//#endregion
+export { COMPRESSED_CHARACTER_MAP, readTextRange };

package/dist/text/piece-table.cjs

@@ -0,0 +1,68 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_errors = require("../errors.cjs");
+const require_bytes = require("../bytes.cjs");
+const require_plc = require("../plc.cjs");
+//#region src/text/piece-table.ts
+/** A Clx's leading Prc marker byte, [MS-DOC] 2.9.20: "This value MUST be 0x01." */
+const CLXT_PRC = 1;
+/** A Clx's Pcdt marker byte, [MS-DOC] 2.9.19: "This value MUST be 0x02." */
+const CLXT_PCDT = 2;
+/** Pcd is 8 bytes: a 2-byte bit field, a 4-byte FcCompressed, and a 2-byte Prm. */
+const PCD_SIZE = 8;
+/** FcCompressed's low 30 bits hold the offset; bit 30 is fCompressed and bit 31 a reserved bit the spec says MUST be zero and MUST be ignored. */
+const FC_MASK = 1073741823;
+const FC_COMPRESSED_BIT = 1073741824;
+/** PrcData.cbGrpprl is a signed integer that "MUST be less than or equal to 0x3FA2". */
+const MAX_CB_GRPPRL = 16290;
+function parseClx(clx) {
+	let cursor = 0;
+	for (;;) {
+		const clxt = require_bytes.readUint8(clx, cursor);
+		if (clxt === CLXT_PCDT) break;
+		if (clxt !== CLXT_PRC) throw new require_errors.DocFormatError(`Clx element at offset ${cursor} begins with clxt 0x${clxt.toString(16).padStart(2, "0")}, which is neither a Prc (0x01) nor the Pcdt (0x02)`);
+		const cbGrpprl = require_bytes.readInt16LE(clx, cursor + 1);
+		if (cbGrpprl < 0 || cbGrpprl > MAX_CB_GRPPRL) throw new require_errors.DocFormatError(`Clx Prc at offset ${cursor} declares cbGrpprl ${cbGrpprl}, outside the 0..0x3FA2 range [MS-DOC] permits`);
+		cursor += 3 + cbGrpprl;
+		if (cursor > clx.length) throw new require_errors.DocFormatError(`Clx Prc at offset ${cursor - 3 - cbGrpprl} declares a ${cbGrpprl}-byte GrpPrl that runs past the end of the ${clx.length}-byte Clx`);
+	}
+	const lcb = require_bytes.readUint32LE(clx, cursor + 1);
+	const plcPcd = require_bytes.slice(clx, cursor + 5, lcb, "Clx Pcdt PlcPcd");
+	const plc = require_plc.parsePlc(plcPcd, PCD_SIZE, "PlcPcd");
+	const pieces = [];
+	for (let index = 0; index < plc.count; index += 1) {
+		const element = plc.element(index);
+		const bits = require_bytes.readUint16LE(element, 0);
+		const fcCompressed = require_bytes.readUint32LE(element, 2);
+		const cpStart = plc.keys[index];
+		const cpEnd = plc.keys[index + 1];
+		if (cpStart === void 0 || cpEnd === void 0) throw new require_errors.DocFormatError(`PlcPcd element ${index} has no bracketing character positions, so its text range is undefined`);
+		pieces.push({
+			cpStart,
+			cpEnd,
+			fc: fcCompressed & FC_MASK,
+			compressed: (fcCompressed & FC_COMPRESSED_BIT) !== 0,
+			noParaLast: (bits & 1) !== 0,
+			prm: require_bytes.readUint16LE(element, 6)
+		});
+	}
+	const lastCp = plc.keys[plc.keys.length - 1];
+	if (lastCp === void 0) throw new require_errors.DocFormatError("PlcPcd carries no character positions at all");
+	return {
+		pieces,
+		cpKeys: plc.keys,
+		lastCp
+	};
+}
+function characterOffset(piece, cp) {
+	if (!Number.isInteger(cp) || cp < piece.cpStart || cp >= piece.cpEnd) throw new require_errors.DocFormatError(`character position ${cp} is outside the piece covering [${piece.cpStart}, ${piece.cpEnd})`);
+	const delta = cp - piece.cpStart;
+	return piece.compressed ? Math.floor(piece.fc / 2) + delta : piece.fc + 2 * delta;
+}
+/** The number of bytes one character occupies in this piece: one for a compressed (8-bit) piece, two for an uncompressed (16-bit) one. */
+function characterSize(piece) {
+	return piece.compressed ? 1 : 2;
+}
+//#endregion
+exports.characterOffset = characterOffset;
+exports.characterSize = characterSize;
+exports.parseClx = parseClx;

package/dist/text/piece-table.d.cts

@@ -0,0 +1,28 @@
+//#region src/text/piece-table.d.ts
+interface Piece {
+  /** The first character position this piece supplies, PlcPcd.aCp[i]. */
+  readonly cpStart: number;
+  /** One past the last character position this piece supplies, PlcPcd.aCp[i + 1]. */
+  readonly cpEnd: number;
+  /** FcCompressed's 30-bit offset field as stored -- NOT yet halved for a compressed piece. Use characterOffset() rather than this directly. */
+  readonly fc: number;
+  /** True when the piece's characters occupy one byte each and its real byte offset is `fc / 2`. */
+  readonly compressed: boolean;
+  /** Pcd's fNoParaLast: "If this bit is 1, the text MUST NOT contain a paragraph mark." */
+  readonly noParaLast: boolean;
+  /** Pcd.Prm, [MS-DOC] 2.8.36 -- further property modifications for this piece's text, carried verbatim and not yet applied (see README's scope note). */
+  readonly prm: number;
+}
+interface PieceTable {
+  readonly pieces: readonly Piece[];
+  /** PlcPcd.aCp itself: one more entry than there are pieces, so a lookup can bracket every piece and terminate at the document's end. */
+  readonly cpKeys: readonly number[];
+  /** The final aCp entry, one past the last character position the document defines. */
+  readonly lastCp: number;
+}
+declare function parseClx(clx: Uint8Array): PieceTable;
+declare function characterOffset(piece: Piece, cp: number): number;
+/** The number of bytes one character occupies in this piece: one for a compressed (8-bit) piece, two for an uncompressed (16-bit) one. */
+declare function characterSize(piece: Piece): 1 | 2;
+//#endregion
+export { Piece, PieceTable, characterOffset, characterSize, parseClx };

package/dist/text/piece-table.d.ts

@@ -0,0 +1,28 @@
+//#region src/text/piece-table.d.ts
+interface Piece {
+  /** The first character position this piece supplies, PlcPcd.aCp[i]. */
+  readonly cpStart: number;
+  /** One past the last character position this piece supplies, PlcPcd.aCp[i + 1]. */
+  readonly cpEnd: number;
+  /** FcCompressed's 30-bit offset field as stored -- NOT yet halved for a compressed piece. Use characterOffset() rather than this directly. */
+  readonly fc: number;
+  /** True when the piece's characters occupy one byte each and its real byte offset is `fc / 2`. */
+  readonly compressed: boolean;
+  /** Pcd's fNoParaLast: "If this bit is 1, the text MUST NOT contain a paragraph mark." */
+  readonly noParaLast: boolean;
+  /** Pcd.Prm, [MS-DOC] 2.8.36 -- further property modifications for this piece's text, carried verbatim and not yet applied (see README's scope note). */
+  readonly prm: number;
+}
+interface PieceTable {
+  readonly pieces: readonly Piece[];
+  /** PlcPcd.aCp itself: one more entry than there are pieces, so a lookup can bracket every piece and terminate at the document's end. */
+  readonly cpKeys: readonly number[];
+  /** The final aCp entry, one past the last character position the document defines. */
+  readonly lastCp: number;
+}
+declare function parseClx(clx: Uint8Array): PieceTable;
+declare function characterOffset(piece: Piece, cp: number): number;
+/** The number of bytes one character occupies in this piece: one for a compressed (8-bit) piece, two for an uncompressed (16-bit) one. */
+declare function characterSize(piece: Piece): 1 | 2;
+//#endregion
+export { Piece, PieceTable, characterOffset, characterSize, parseClx };