doc-codec 2.6.0 → 2.7.0

package/dist/pictures-write.cjs

@@ -0,0 +1,85 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_base64 = require("./base64.cjs");
+const require_errors = require("./errors.cjs");
+//#region src/pictures-write.ts
+const PICF_SIZE = 68;
+const PICF_MM_OFFSET = 6;
+const PICF_DXA_GOAL_OFFSET = 28;
+const PICF_DYA_GOAL_OFFSET = 30;
+const PICF_MX_OFFSET = 32;
+const PICF_MY_OFFSET = 34;
+/** MFPF.mm's MM_SHAPE value, [MS-DOC] 2.9.181 -- the plain, no-source-filename form; this writer never emits MM_SHAPEFILE's own cchPicName/stPicName pair, matching what pictures.ts's own reader treats as the common case. */
+const MM_SHAPE = 100;
+const RECORD_HEADER_SIZE = 8;
+/** OfficeArtBlipJPEG / OfficeArtBlipPNG record types, [MS-ODRAW] 2.2.27/2.2.28. */
+const BLIP_JPEG = 61469;
+const BLIP_PNG = 61470;
+/** rh.recInstance for the single-rgbUid (16-byte) form of each blip -- [MS-ODRAW] 2.2.27's own table for JPEG (RGB), 2.2.28's for PNG; the identical values pictures.ts's own ONE_UID_INSTANCES set already recognises on read. */
+const BLIP_INSTANCE_JPEG = 1130;
+const BLIP_INSTANCE_PNG = 1760;
+const BLIP_UID_SIZE = 16;
+/** The one byte following rgbUid in every OfficeArtBlip variant pictures.ts reads -- [MS-ODRAW]'s own BLIPFileTag, 0xFF for a non-metafile blip (PNG/JPEG are never compressed the way a WMF/EMF metafile blip's own tag byte would state). */
+const BLIP_FILE_TAG = 255;
+const BLIP_TAG_SIZE = 1;
+const TWIPS_PER_POINT = 20;
+/** PICMID.mx/my, [MS-DOC]: "the ratio, measured in tenths of a percent, between the final display width/height and the initial picture width/height" -- this writer always states dxaGoal/dyaGoal as the image's own real size and mx/my as "no scaling" (1000, one thousand tenths-of-a-percent = 100%), matching pictures.ts's own read-side arithmetic (dxaGoal * mx / 1000) exactly at mx = 1000. */
+const NO_SCALING = 1e3;
+/** PICMID.dxaGoal/dyaGoal are a signed 16-bit FieldFormatting value in twips -- [MS-DOC] states no narrower bound than that field width itself. */
+const MAX_INT16 = 32767;
+function recordHeaderBytes(recType, recInstance, recLen) {
+	const bytes = new Uint8Array(RECORD_HEADER_SIZE);
+	const view = new DataView(bytes.buffer);
+	view.setUint16(0, recInstance << 4, true);
+	view.setUint16(2, recType, true);
+	view.setUint32(4, recLen, true);
+	return bytes;
+}
+function twipsFromPt(pt, field) {
+	const twips = Math.round(pt * TWIPS_PER_POINT);
+	if (twips < 0 || twips > MAX_INT16) throw new require_errors.DocFormatError(`an image's ${field} of ${String(pt)}pt is ${String(twips)} twips, outside the 0..${String(MAX_INT16)} range PICMID.dxaGoal/dyaGoal (a signed 16-bit field) can hold`);
+	return twips;
+}
+/** Builds one inline picture's own PICFAndOfficeArtData bytes -- everything pictures.ts's readInlinePicture needs given the Data-stream offset it will end up placed at, which this function does not itself decide (see WrittenInlinePicture's own comment). */
+function buildInlinePicture(image) {
+	const recType = image.format === "png" ? BLIP_PNG : image.format === "jpeg" ? BLIP_JPEG : void 0;
+	if (recType === void 0) throw new require_errors.DocUnsupportedError(`doc-codec's writer can only write a 'png' or 'jpeg' inline picture -- the two raster formats its own reader decodes from a real OfficeArtBlip; got '${image.format}'`);
+	const recInstance = image.format === "png" ? BLIP_INSTANCE_PNG : BLIP_INSTANCE_JPEG;
+	const payload = require_base64.base64ToBytes(image.base64);
+	const picf = new Uint8Array(PICF_SIZE);
+	const picfView = new DataView(picf.buffer);
+	picfView.setUint16(PICF_MM_OFFSET, MM_SHAPE, true);
+	picfView.setInt16(PICF_DXA_GOAL_OFFSET, twipsFromPt(image.widthPt, "widthPt"), true);
+	picfView.setInt16(PICF_DYA_GOAL_OFFSET, twipsFromPt(image.heightPt, "heightPt"), true);
+	picfView.setUint16(PICF_MX_OFFSET, NO_SCALING, true);
+	picfView.setUint16(PICF_MY_OFFSET, NO_SCALING, true);
+	const shapeHeader = recordHeaderBytes(61444, 0, 0);
+	const uid = new Uint8Array(BLIP_UID_SIZE);
+	const blipHeader = recordHeaderBytes(recType, recInstance, uid.length + BLIP_TAG_SIZE + payload.length);
+	const data = new Uint8Array(picf.length + shapeHeader.length + blipHeader.length + uid.length + BLIP_TAG_SIZE + payload.length);
+	let cursor = 0;
+	data.set(picf, cursor);
+	cursor += picf.length;
+	data.set(shapeHeader, cursor);
+	cursor += shapeHeader.length;
+	data.set(blipHeader, cursor);
+	cursor += blipHeader.length;
+	data.set(uid, cursor);
+	cursor += uid.length;
+	data[cursor] = BLIP_FILE_TAG;
+	cursor += 1;
+	data.set(payload, cursor);
+	return {
+		data,
+		buildGrpprl: buildPicLocationGrpprl
+	};
+}
+/** sprmCPicLocation, [MS-DOC] 2.6.1 -- a signed 32-bit offset into the Data stream, little-endian. */
+function buildPicLocationGrpprl(dataStreamOffset) {
+	const grpprl = [3, 106];
+	const operand = /* @__PURE__ */ new Uint8Array(4);
+	new DataView(operand.buffer).setInt32(0, dataStreamOffset, true);
+	grpprl.push(...operand);
+	return grpprl;
+}
+//#endregion
+exports.buildInlinePicture = buildInlinePicture;

package/dist/pictures-write.d.cts

@@ -0,0 +1,12 @@
+import { ContentImageBlock } from "document-schema.js";
+//#region src/pictures-write.d.ts
+interface WrittenInlinePicture {
+  /** The whole PICFAndOfficeArtData byte blob to append to the Data stream at whatever offset it ends up placed. */
+  readonly data: Uint8Array<ArrayBuffer>;
+  /** sprmCPicLocation's own grpprl bytes, complete except for its 4-byte operand, which the caller fills in with wherever `data` was actually placed (buildPicLocationGrpprl below) -- the two are split because only the caller (write.ts's own Data-stream accumulator) knows that offset before `data` is placed. */
+  readonly buildGrpprl: (dataStreamOffset: number) => number[];
+}
+/** Builds one inline picture's own PICFAndOfficeArtData bytes -- everything pictures.ts's readInlinePicture needs given the Data-stream offset it will end up placed at, which this function does not itself decide (see WrittenInlinePicture's own comment). */
+declare function buildInlinePicture(image: ContentImageBlock): WrittenInlinePicture;
+//#endregion
+export { WrittenInlinePicture, buildInlinePicture };

package/dist/pictures-write.d.ts

@@ -0,0 +1,12 @@
+import { ContentImageBlock } from "document-schema.js";
+//#region src/pictures-write.d.ts
+interface WrittenInlinePicture {
+  /** The whole PICFAndOfficeArtData byte blob to append to the Data stream at whatever offset it ends up placed. */
+  readonly data: Uint8Array<ArrayBuffer>;
+  /** sprmCPicLocation's own grpprl bytes, complete except for its 4-byte operand, which the caller fills in with wherever `data` was actually placed (buildPicLocationGrpprl below) -- the two are split because only the caller (write.ts's own Data-stream accumulator) knows that offset before `data` is placed. */
+  readonly buildGrpprl: (dataStreamOffset: number) => number[];
+}
+/** Builds one inline picture's own PICFAndOfficeArtData bytes -- everything pictures.ts's readInlinePicture needs given the Data-stream offset it will end up placed at, which this function does not itself decide (see WrittenInlinePicture's own comment). */
+declare function buildInlinePicture(image: ContentImageBlock): WrittenInlinePicture;
+//#endregion
+export { WrittenInlinePicture, buildInlinePicture };

package/dist/pictures-write.js

@@ -0,0 +1,84 @@
+import { base64ToBytes } from "./base64.js";
+import { DocFormatError, DocUnsupportedError } from "./errors.js";
+//#region src/pictures-write.ts
+const PICF_SIZE = 68;
+const PICF_MM_OFFSET = 6;
+const PICF_DXA_GOAL_OFFSET = 28;
+const PICF_DYA_GOAL_OFFSET = 30;
+const PICF_MX_OFFSET = 32;
+const PICF_MY_OFFSET = 34;
+/** MFPF.mm's MM_SHAPE value, [MS-DOC] 2.9.181 -- the plain, no-source-filename form; this writer never emits MM_SHAPEFILE's own cchPicName/stPicName pair, matching what pictures.ts's own reader treats as the common case. */
+const MM_SHAPE = 100;
+const RECORD_HEADER_SIZE = 8;
+/** OfficeArtBlipJPEG / OfficeArtBlipPNG record types, [MS-ODRAW] 2.2.27/2.2.28. */
+const BLIP_JPEG = 61469;
+const BLIP_PNG = 61470;
+/** rh.recInstance for the single-rgbUid (16-byte) form of each blip -- [MS-ODRAW] 2.2.27's own table for JPEG (RGB), 2.2.28's for PNG; the identical values pictures.ts's own ONE_UID_INSTANCES set already recognises on read. */
+const BLIP_INSTANCE_JPEG = 1130;
+const BLIP_INSTANCE_PNG = 1760;
+const BLIP_UID_SIZE = 16;
+/** The one byte following rgbUid in every OfficeArtBlip variant pictures.ts reads -- [MS-ODRAW]'s own BLIPFileTag, 0xFF for a non-metafile blip (PNG/JPEG are never compressed the way a WMF/EMF metafile blip's own tag byte would state). */
+const BLIP_FILE_TAG = 255;
+const BLIP_TAG_SIZE = 1;
+const TWIPS_PER_POINT = 20;
+/** PICMID.mx/my, [MS-DOC]: "the ratio, measured in tenths of a percent, between the final display width/height and the initial picture width/height" -- this writer always states dxaGoal/dyaGoal as the image's own real size and mx/my as "no scaling" (1000, one thousand tenths-of-a-percent = 100%), matching pictures.ts's own read-side arithmetic (dxaGoal * mx / 1000) exactly at mx = 1000. */
+const NO_SCALING = 1e3;
+/** PICMID.dxaGoal/dyaGoal are a signed 16-bit FieldFormatting value in twips -- [MS-DOC] states no narrower bound than that field width itself. */
+const MAX_INT16 = 32767;
+function recordHeaderBytes(recType, recInstance, recLen) {
+	const bytes = new Uint8Array(RECORD_HEADER_SIZE);
+	const view = new DataView(bytes.buffer);
+	view.setUint16(0, recInstance << 4, true);
+	view.setUint16(2, recType, true);
+	view.setUint32(4, recLen, true);
+	return bytes;
+}
+function twipsFromPt(pt, field) {
+	const twips = Math.round(pt * TWIPS_PER_POINT);
+	if (twips < 0 || twips > MAX_INT16) throw new DocFormatError(`an image's ${field} of ${String(pt)}pt is ${String(twips)} twips, outside the 0..${String(MAX_INT16)} range PICMID.dxaGoal/dyaGoal (a signed 16-bit field) can hold`);
+	return twips;
+}
+/** Builds one inline picture's own PICFAndOfficeArtData bytes -- everything pictures.ts's readInlinePicture needs given the Data-stream offset it will end up placed at, which this function does not itself decide (see WrittenInlinePicture's own comment). */
+function buildInlinePicture(image) {
+	const recType = image.format === "png" ? BLIP_PNG : image.format === "jpeg" ? BLIP_JPEG : void 0;
+	if (recType === void 0) throw new DocUnsupportedError(`doc-codec's writer can only write a 'png' or 'jpeg' inline picture -- the two raster formats its own reader decodes from a real OfficeArtBlip; got '${image.format}'`);
+	const recInstance = image.format === "png" ? BLIP_INSTANCE_PNG : BLIP_INSTANCE_JPEG;
+	const payload = base64ToBytes(image.base64);
+	const picf = new Uint8Array(PICF_SIZE);
+	const picfView = new DataView(picf.buffer);
+	picfView.setUint16(PICF_MM_OFFSET, MM_SHAPE, true);
+	picfView.setInt16(PICF_DXA_GOAL_OFFSET, twipsFromPt(image.widthPt, "widthPt"), true);
+	picfView.setInt16(PICF_DYA_GOAL_OFFSET, twipsFromPt(image.heightPt, "heightPt"), true);
+	picfView.setUint16(PICF_MX_OFFSET, NO_SCALING, true);
+	picfView.setUint16(PICF_MY_OFFSET, NO_SCALING, true);
+	const shapeHeader = recordHeaderBytes(61444, 0, 0);
+	const uid = new Uint8Array(BLIP_UID_SIZE);
+	const blipHeader = recordHeaderBytes(recType, recInstance, uid.length + BLIP_TAG_SIZE + payload.length);
+	const data = new Uint8Array(picf.length + shapeHeader.length + blipHeader.length + uid.length + BLIP_TAG_SIZE + payload.length);
+	let cursor = 0;
+	data.set(picf, cursor);
+	cursor += picf.length;
+	data.set(shapeHeader, cursor);
+	cursor += shapeHeader.length;
+	data.set(blipHeader, cursor);
+	cursor += blipHeader.length;
+	data.set(uid, cursor);
+	cursor += uid.length;
+	data[cursor] = BLIP_FILE_TAG;
+	cursor += 1;
+	data.set(payload, cursor);
+	return {
+		data,
+		buildGrpprl: buildPicLocationGrpprl
+	};
+}
+/** sprmCPicLocation, [MS-DOC] 2.6.1 -- a signed 32-bit offset into the Data stream, little-endian. */
+function buildPicLocationGrpprl(dataStreamOffset) {
+	const grpprl = [3, 106];
+	const operand = /* @__PURE__ */ new Uint8Array(4);
+	new DataView(operand.buffer).setInt32(0, dataStreamOffset, true);
+	grpprl.push(...operand);
+	return grpprl;
+}
+//#endregion
+export { buildInlinePicture };

package/dist/pictures.cjs

@@ -1,4 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_base64 = require("./base64.cjs");
 const require_bytes = require("./bytes.cjs");
 //#region src/pictures.ts
 const PICF_SIZE = 68;
@@ -59,10 +60,11 @@ function readInlinePicture(dataStream, picLocation) {
 	if (uidBytes === void 0) return void 0;
 	const blipDataStart = cursor + RECORD_HEADER_SIZE + uidBytes + BLIP_TAG_SIZE;
 	const blipDataLength = blipHeader.recLen - uidBytes - BLIP_TAG_SIZE;
+	const blipBytes = require_bytes.slice(dataStream, blipDataStart, blipDataLength, "OfficeArtBlip file data in the Data stream");
 	return {
 		kind: "image",
 		format,
-		base64: bytesToBase64(require_bytes.slice(dataStream, blipDataStart, blipDataLength, "OfficeArtBlip file data in the Data stream")),
+		base64: require_base64.bytesToBase64(blipBytes),
 		widthPt: dxaGoal * mx / SCALE_DENOMINATOR / TWIPS_PER_POINT,
 		heightPt: dyaGoal * my / SCALE_DENOMINATOR / TWIPS_PER_POINT
 	};
@@ -74,20 +76,5 @@ function blipFormat(recType) {
 		default: return;
 	}
 }
-const BASE64_TABLE = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
-function bytesToBase64(bytes) {
-	let out = "";
-	const len = bytes.length;
-	for (let index = 0; index < len; index += 3) {
-		const b0 = bytes[index] ?? 0;
-		const b1 = index + 1 < len ? bytes[index + 1] ?? 0 : 0;
-		const b2 = index + 2 < len ? bytes[index + 2] ?? 0 : 0;
-		out += BASE64_TABLE.charAt(b0 >> 2);
-		out += BASE64_TABLE.charAt((b0 & 3) << 4 | b1 >> 4);
-		out += index + 1 < len ? BASE64_TABLE.charAt((b1 & 15) << 2 | b2 >> 6) : "=";
-		out += index + 2 < len ? BASE64_TABLE.charAt(b2 & 63) : "=";
-	}
-	return out;
-}
 //#endregion
 exports.readInlinePicture = readInlinePicture;

package/dist/pictures.js

@@ -1,3 +1,4 @@
+import { bytesToBase64 } from "./base64.js";
 import { readInt16LE, readUint16LE, readUint32LE, readUint8, slice } from "./bytes.js";
 //#region src/pictures.ts
 const PICF_SIZE = 68;
@@ -58,10 +59,11 @@ function readInlinePicture(dataStream, picLocation) {
 	if (uidBytes === void 0) return void 0;
 	const blipDataStart = cursor + RECORD_HEADER_SIZE + uidBytes + BLIP_TAG_SIZE;
 	const blipDataLength = blipHeader.recLen - uidBytes - BLIP_TAG_SIZE;
+	const blipBytes = slice(dataStream, blipDataStart, blipDataLength, "OfficeArtBlip file data in the Data stream");
 	return {
 		kind: "image",
 		format,
-		base64: bytesToBase64(slice(dataStream, blipDataStart, blipDataLength, "OfficeArtBlip file data in the Data stream")),
+		base64: bytesToBase64(blipBytes),
 		widthPt: dxaGoal * mx / SCALE_DENOMINATOR / TWIPS_PER_POINT,
 		heightPt: dyaGoal * my / SCALE_DENOMINATOR / TWIPS_PER_POINT
 	};
@@ -73,20 +75,5 @@ function blipFormat(recType) {
 		default: return;
 	}
 }
-const BASE64_TABLE = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
-function bytesToBase64(bytes) {
-	let out = "";
-	const len = bytes.length;
-	for (let index = 0; index < len; index += 3) {
-		const b0 = bytes[index] ?? 0;
-		const b1 = index + 1 < len ? bytes[index + 1] ?? 0 : 0;
-		const b2 = index + 2 < len ? bytes[index + 2] ?? 0 : 0;
-		out += BASE64_TABLE.charAt(b0 >> 2);
-		out += BASE64_TABLE.charAt((b0 & 3) << 4 | b1 >> 4);
-		out += index + 1 < len ? BASE64_TABLE.charAt((b1 & 15) << 2 | b2 >> 6) : "=";
-		out += index + 2 < len ? BASE64_TABLE.charAt(b2 & 63) : "=";
-	}
-	return out;
-}
 //#endregion
 export { readInlinePicture };

package/dist/prop/sep-write.cjs

@@ -45,16 +45,23 @@ function buildSepx(grpprl) {
 	bytes.set(grpprl, 2);
 	return bytes;
 }
-/** PlcfSed for exactly one section: two CPs (0 and ccpText) bracketing the single Sed ([MS-DOC] 2.9.269) this writer ever emits, whose fcSepx names where buildSepx's own bytes were placed in the WordDocument stream and whose fn/fnMpr/fcMpr fields carry the values [MS-DOC] states are ignored. */
-function buildPlcfSed(ccpText, fcSepx) {
-	const bytes = /* @__PURE__ */ new Uint8Array(20);
+/** PlcfSed for `startCps.length` sections, [MS-DOC] 2.9.269/2.8.26: `startCps` (each section's own PlcfSed.aCp[i], "the beginning of a range of text ... that constitutes a section") plus a trailing `ccpText` -- the "last CP does not begin a new section" terminator -- bracketing one 12-byte Sed per section, each naming where that section's own buildSepx bytes were placed in the WordDocument stream (`fcSepxList`, the same order as `startCps`) and whose fn/fnMpr/fcMpr fields carry the values [MS-DOC] states are ignored. A single-section document is simply the `startCps.length === 1` case. */
+function buildPlcfSed(startCps, ccpText, fcSepxList) {
+	if (startCps.length !== fcSepxList.length) throw new require_errors.DocFormatError(`internal defect: buildPlcfSed was given ${String(startCps.length)} section start CPs but ${String(fcSepxList.length)} Sepx offsets -- these must be the same length`);
+	const keys = [...startCps, ccpText];
+	const keyBytes = keys.length * 4;
+	const bytes = new Uint8Array(keyBytes + fcSepxList.length * 12);
 	const view = new DataView(bytes.buffer);
-	view.setUint32(0, 0, true);
-	view.setUint32(4, ccpText, true);
-	view.setUint16(8, 0, true);
-	view.setUint32(10, fcSepx, true);
-	view.setUint16(14, 0, true);
-	view.setUint32(16, 4294967295, true);
+	keys.forEach((cp, index) => {
+		view.setUint32(index * 4, cp, true);
+	});
+	fcSepxList.forEach((fcSepx, index) => {
+		const base = keyBytes + index * 12;
+		view.setUint16(base, 0, true);
+		view.setUint32(base + 2, fcSepx, true);
+		view.setUint16(base + 6, 0, true);
+		view.setUint32(base + 8, 4294967295, true);
+	});
 	return bytes;
 }
 //#endregion

package/dist/prop/sep-write.d.cts

@@ -3,7 +3,7 @@ import { ContentSection } from "document-schema.js";
 declare function encodeSectionGrpprl(section: Pick<ContentSection, "pageSize" | "margins">): number[];
 /** Sepx, [MS-DOC] 2.9.279: a 2-byte cb (grpprl's own length) followed by the grpprl itself. */
 declare function buildSepx(grpprl: readonly number[]): Uint8Array<ArrayBuffer>;
-/** PlcfSed for exactly one section: two CPs (0 and ccpText) bracketing the single Sed ([MS-DOC] 2.9.269) this writer ever emits, whose fcSepx names where buildSepx's own bytes were placed in the WordDocument stream and whose fn/fnMpr/fcMpr fields carry the values [MS-DOC] states are ignored. */
-declare function buildPlcfSed(ccpText: number, fcSepx: number): Uint8Array<ArrayBuffer>;
+/** PlcfSed for `startCps.length` sections, [MS-DOC] 2.9.269/2.8.26: `startCps` (each section's own PlcfSed.aCp[i], "the beginning of a range of text ... that constitutes a section") plus a trailing `ccpText` -- the "last CP does not begin a new section" terminator -- bracketing one 12-byte Sed per section, each naming where that section's own buildSepx bytes were placed in the WordDocument stream (`fcSepxList`, the same order as `startCps`) and whose fn/fnMpr/fcMpr fields carry the values [MS-DOC] states are ignored. A single-section document is simply the `startCps.length === 1` case. */
+declare function buildPlcfSed(startCps: readonly number[], ccpText: number, fcSepxList: readonly number[]): Uint8Array<ArrayBuffer>;
 //#endregion
 export { buildPlcfSed, buildSepx, encodeSectionGrpprl };

package/dist/prop/sep-write.d.ts

@@ -3,7 +3,7 @@ import { ContentSection } from "document-schema.js";
 declare function encodeSectionGrpprl(section: Pick<ContentSection, "pageSize" | "margins">): number[];
 /** Sepx, [MS-DOC] 2.9.279: a 2-byte cb (grpprl's own length) followed by the grpprl itself. */
 declare function buildSepx(grpprl: readonly number[]): Uint8Array<ArrayBuffer>;
-/** PlcfSed for exactly one section: two CPs (0 and ccpText) bracketing the single Sed ([MS-DOC] 2.9.269) this writer ever emits, whose fcSepx names where buildSepx's own bytes were placed in the WordDocument stream and whose fn/fnMpr/fcMpr fields carry the values [MS-DOC] states are ignored. */
-declare function buildPlcfSed(ccpText: number, fcSepx: number): Uint8Array<ArrayBuffer>;
+/** PlcfSed for `startCps.length` sections, [MS-DOC] 2.9.269/2.8.26: `startCps` (each section's own PlcfSed.aCp[i], "the beginning of a range of text ... that constitutes a section") plus a trailing `ccpText` -- the "last CP does not begin a new section" terminator -- bracketing one 12-byte Sed per section, each naming where that section's own buildSepx bytes were placed in the WordDocument stream (`fcSepxList`, the same order as `startCps`) and whose fn/fnMpr/fcMpr fields carry the values [MS-DOC] states are ignored. A single-section document is simply the `startCps.length === 1` case. */
+declare function buildPlcfSed(startCps: readonly number[], ccpText: number, fcSepxList: readonly number[]): Uint8Array<ArrayBuffer>;
 //#endregion
 export { buildPlcfSed, buildSepx, encodeSectionGrpprl };

package/dist/prop/sep-write.js

@@ -44,16 +44,23 @@ function buildSepx(grpprl) {
 	bytes.set(grpprl, 2);
 	return bytes;
 }
-/** PlcfSed for exactly one section: two CPs (0 and ccpText) bracketing the single Sed ([MS-DOC] 2.9.269) this writer ever emits, whose fcSepx names where buildSepx's own bytes were placed in the WordDocument stream and whose fn/fnMpr/fcMpr fields carry the values [MS-DOC] states are ignored. */
-function buildPlcfSed(ccpText, fcSepx) {
-	const bytes = /* @__PURE__ */ new Uint8Array(20);
+/** PlcfSed for `startCps.length` sections, [MS-DOC] 2.9.269/2.8.26: `startCps` (each section's own PlcfSed.aCp[i], "the beginning of a range of text ... that constitutes a section") plus a trailing `ccpText` -- the "last CP does not begin a new section" terminator -- bracketing one 12-byte Sed per section, each naming where that section's own buildSepx bytes were placed in the WordDocument stream (`fcSepxList`, the same order as `startCps`) and whose fn/fnMpr/fcMpr fields carry the values [MS-DOC] states are ignored. A single-section document is simply the `startCps.length === 1` case. */
+function buildPlcfSed(startCps, ccpText, fcSepxList) {
+	if (startCps.length !== fcSepxList.length) throw new DocFormatError(`internal defect: buildPlcfSed was given ${String(startCps.length)} section start CPs but ${String(fcSepxList.length)} Sepx offsets -- these must be the same length`);
+	const keys = [...startCps, ccpText];
+	const keyBytes = keys.length * 4;
+	const bytes = new Uint8Array(keyBytes + fcSepxList.length * 12);
 	const view = new DataView(bytes.buffer);
-	view.setUint32(0, 0, true);
-	view.setUint32(4, ccpText, true);
-	view.setUint16(8, 0, true);
-	view.setUint32(10, fcSepx, true);
-	view.setUint16(14, 0, true);
-	view.setUint32(16, 4294967295, true);
+	keys.forEach((cp, index) => {
+		view.setUint32(index * 4, cp, true);
+	});
+	fcSepxList.forEach((fcSepx, index) => {
+		const base = keyBytes + index * 12;
+		view.setUint16(base, 0, true);
+		view.setUint32(base + 2, fcSepx, true);
+		view.setUint16(base + 6, 0, true);
+		view.setUint32(base + 8, 4294967295, true);
+	});
 	return bytes;
 }
 //#endregion

package/dist/table/write.cjs

@@ -1,7 +1,9 @@
 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");
 const require_table_tap_write = require("./tap-write.cjs");
 //#region src/table/write.ts
 /** sprmPFInTable (0x2416): a Bool8, "MUST be 1 any time the table depth is greater than zero". */
@@ -9,6 +11,12 @@ const SPRM_P_F_IN_TABLE = 9238;
 /** sprmPFTtp (0x2417): a Bool8 marking a cell mark as the row's own Table Terminating Paragraph mark. */
 const SPRM_P_F_TTP = 9239;
 const TWIPS_PER_POINT = 20;
+function plainRuns(runs) {
+	return runs.map((run) => ({
+		run,
+		extraGrpprl: []
+	}));
+}
 function pushSprm(bytes, opcode, operand) {
 	bytes.push(opcode & 255, opcode >> 8 & 255, ...operand);
 }
@@ -33,7 +41,7 @@ function cellParagraphs(blocks) {
 	return blocks.map((block, index) => {
 		if (block.kind !== "paragraph") throw new require_errors.DocUnsupportedError(`doc-codec's writer does not support a '${block.kind}' block inside a table cell (only paragraphs are; nested tables are a separately-tracked gap -- see the README's scope note)`);
 		return {
-			runs: block.runs,
+			runs: plainRuns(block.runs),
 			properties: block,
 			extraGrpprl: inTableGrpprl(),
 			terminator: index === blocks.length - 1 ? 7 : 13
@@ -189,12 +197,25 @@ function flattenTable(table, blockIndex, onWarning) {
 	});
 	return output;
 }
-function flattenSectionBlocks(blocks, onWarning) {
+function imageParagraph(image, dataStream) {
+	const { data, buildGrpprl } = require_pictures_write.buildInlinePicture(image);
+	const offset = dataStream.append(data);
+	return {
+		runs: [{
+			run: { text: String.fromCharCode(1) },
+			extraGrpprl: buildGrpprl(offset)
+		}],
+		properties: {},
+		extraGrpprl: [],
+		terminator: 13
+	};
+}
+function flattenSectionBlocks(blocks, dataStream, onWarning) {
 	const output = [];
 	blocks.forEach((block, blockIndex) => {
 		if (block.kind === "paragraph") {
 			output.push({
-				runs: block.runs,
+				runs: plainRuns(block.runs),
 				properties: block,
 				extraGrpprl: [],
 				terminator: 13
@@ -205,6 +226,10 @@ function flattenSectionBlocks(blocks, onWarning) {
 			output.push(...flattenTable(block, blockIndex, onWarning));
 			return;
 		}
+		if (block.kind === "image") {
+			output.push(imageParagraph(block, dataStream));
+			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.d.cts

@@ -1,2 +1,2 @@
-import { n as WriteWarning, r as flattenSectionBlocks, t as WriteParagraph } from "../write-SN_aIwyF.cjs";
-export { WriteParagraph, WriteWarning, flattenSectionBlocks };
+import { i as flattenSectionBlocks, n as WriteRun, r as WriteWarning, t as WriteParagraph } from "../write-CMB3qF4i.cjs";
+export { WriteParagraph, WriteRun, WriteWarning, flattenSectionBlocks };

package/dist/table/write.d.ts

@@ -1,2 +1,2 @@
-import { n as WriteWarning, r as flattenSectionBlocks, t as WriteParagraph } from "../write-SN_aIwyF.js";
-export { WriteParagraph, WriteWarning, flattenSectionBlocks };
+import { i as flattenSectionBlocks, n as WriteRun, r as WriteWarning, t as WriteParagraph } from "../write-t4rFgnA-.js";
+export { WriteParagraph, WriteRun, WriteWarning, flattenSectionBlocks };

package/dist/table/write.js

@@ -1,6 +1,8 @@
 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";
 import { encodeTableRowGrpprl } from "./tap-write.js";
 //#region src/table/write.ts
 /** sprmPFInTable (0x2416): a Bool8, "MUST be 1 any time the table depth is greater than zero". */
@@ -8,6 +10,12 @@ const SPRM_P_F_IN_TABLE = 9238;
 /** sprmPFTtp (0x2417): a Bool8 marking a cell mark as the row's own Table Terminating Paragraph mark. */
 const SPRM_P_F_TTP = 9239;
 const TWIPS_PER_POINT = 20;
+function plainRuns(runs) {
+	return runs.map((run) => ({
+		run,
+		extraGrpprl: []
+	}));
+}
 function pushSprm(bytes, opcode, operand) {
 	bytes.push(opcode & 255, opcode >> 8 & 255, ...operand);
 }
@@ -32,7 +40,7 @@ function cellParagraphs(blocks) {
 	return blocks.map((block, index) => {
 		if (block.kind !== "paragraph") throw new DocUnsupportedError(`doc-codec's writer does not support a '${block.kind}' block inside a table cell (only paragraphs are; nested tables are a separately-tracked gap -- see the README's scope note)`);
 		return {
-			runs: block.runs,
+			runs: plainRuns(block.runs),
 			properties: block,
 			extraGrpprl: inTableGrpprl(),
 			terminator: index === blocks.length - 1 ? 7 : 13
@@ -188,12 +196,25 @@ function flattenTable(table, blockIndex, onWarning) {
 	});
 	return output;
 }
-function flattenSectionBlocks(blocks, onWarning) {
+function imageParagraph(image, dataStream) {
+	const { data, buildGrpprl } = buildInlinePicture(image);
+	const offset = dataStream.append(data);
+	return {
+		runs: [{
+			run: { text: String.fromCharCode(1) },
+			extraGrpprl: buildGrpprl(offset)
+		}],
+		properties: {},
+		extraGrpprl: [],
+		terminator: 13
+	};
+}
+function flattenSectionBlocks(blocks, dataStream, onWarning) {
 	const output = [];
 	blocks.forEach((block, blockIndex) => {
 		if (block.kind === "paragraph") {
 			output.push({
-				runs: block.runs,
+				runs: plainRuns(block.runs),
 				properties: block,
 				extraGrpprl: [],
 				terminator: 13
@@ -204,6 +225,10 @@ function flattenSectionBlocks(blocks, onWarning) {
 			output.push(...flattenTable(block, blockIndex, onWarning));
 			return;
 		}
+		if (block.kind === "image") {
+			output.push(imageParagraph(block, dataStream));
+			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-SN_aIwyF.d.ts → write-CMB3qF4i.d.cts}

@@ -1,15 +1,21 @@
+import { t as DataStreamBuilder } from "./data-stream-BLCj4-V1.cjs";
 import { ContentBlock, ContentParagraph, ContentRun } from "document-schema.js";
 //#region src/table/write.d.ts
 /** Reports a non-fatal write-time degradation -- this package's own analogue of byte-codec's/pdf-codec's `onWarning`, adopted here rather than a new shape of its own so a caller already handling one already handles the other. */
 type WriteWarning = (message: string) => void;
+/** One run to write, alongside grpprl bytes appended after encodeCharacterGrpprl's own output for it -- the run-level analogue of WriteParagraph.extraGrpprl below. Every ordinary run carries none (its whole grpprl comes from its own ContentRun fields); imageParagraph's own picture-anchor run is the one exception, since sprmCPicLocation is not a ContentRun field encodeCharacterGrpprl could ever derive on its own. */
+interface WriteRun {
+  readonly run: ContentRun;
+  readonly extraGrpprl: readonly number[];
+}
 interface WriteParagraph {
-  readonly runs: readonly ContentRun[];
+  readonly runs: readonly WriteRun[];
   readonly properties: Pick<ContentParagraph, "alignment" | "indentLeftPt" | "indentRightPt" | "indentFirstLinePt" | "spacingBeforePt" | "spacingAfterPt" | "lineSpacing" | "pageBreakBefore" | "list" | "styleId" | "headingLevel">;
   /** Extra grpprl bytes appended after encodeParagraphGrpprl's own output -- sprmPFInTable on every table paragraph, plus sprmPFTtp and the row's own TAP on a row's trailing mark. */
   readonly extraGrpprl: readonly number[];
   /** The character terminating this paragraph in the text stream: PARAGRAPH_MARK normally, CELL_MARK for a table cell or row mark. */
   readonly terminator: number;
 }
-declare function flattenSectionBlocks(blocks: readonly ContentBlock[], onWarning?: WriteWarning): WriteParagraph[];
+declare function flattenSectionBlocks(blocks: readonly ContentBlock[], dataStream: DataStreamBuilder, onWarning?: WriteWarning): WriteParagraph[];
 //#endregion
-export { WriteWarning as n, flattenSectionBlocks as r, WriteParagraph as t };
+export { flattenSectionBlocks as i, WriteRun as n, WriteWarning as r, WriteParagraph as t };

package/dist/{write-SN_aIwyF.d.cts → write-t4rFgnA-.d.ts}

@@ -1,15 +1,21 @@
+import { t as DataStreamBuilder } from "./data-stream-BLCj4-V1.js";
 import { ContentBlock, ContentParagraph, ContentRun } from "document-schema.js";
 //#region src/table/write.d.ts
 /** Reports a non-fatal write-time degradation -- this package's own analogue of byte-codec's/pdf-codec's `onWarning`, adopted here rather than a new shape of its own so a caller already handling one already handles the other. */
 type WriteWarning = (message: string) => void;
+/** One run to write, alongside grpprl bytes appended after encodeCharacterGrpprl's own output for it -- the run-level analogue of WriteParagraph.extraGrpprl below. Every ordinary run carries none (its whole grpprl comes from its own ContentRun fields); imageParagraph's own picture-anchor run is the one exception, since sprmCPicLocation is not a ContentRun field encodeCharacterGrpprl could ever derive on its own. */
+interface WriteRun {
+  readonly run: ContentRun;
+  readonly extraGrpprl: readonly number[];
+}
 interface WriteParagraph {
-  readonly runs: readonly ContentRun[];
+  readonly runs: readonly WriteRun[];
   readonly properties: Pick<ContentParagraph, "alignment" | "indentLeftPt" | "indentRightPt" | "indentFirstLinePt" | "spacingBeforePt" | "spacingAfterPt" | "lineSpacing" | "pageBreakBefore" | "list" | "styleId" | "headingLevel">;
   /** Extra grpprl bytes appended after encodeParagraphGrpprl's own output -- sprmPFInTable on every table paragraph, plus sprmPFTtp and the row's own TAP on a row's trailing mark. */
   readonly extraGrpprl: readonly number[];
   /** The character terminating this paragraph in the text stream: PARAGRAPH_MARK normally, CELL_MARK for a table cell or row mark. */
   readonly terminator: number;
 }
-declare function flattenSectionBlocks(blocks: readonly ContentBlock[], onWarning?: WriteWarning): WriteParagraph[];
+declare function flattenSectionBlocks(blocks: readonly ContentBlock[], dataStream: DataStreamBuilder, onWarning?: WriteWarning): WriteParagraph[];
 //#endregion
-export { WriteWarning as n, flattenSectionBlocks as r, WriteParagraph as t };
+export { flattenSectionBlocks as i, WriteRun as n, WriteWarning as r, WriteParagraph as t };