@pptx-studio/writer 0.1.0

package/dist/index.js

@@ -0,0 +1,1165 @@
+import { CONTENT_TYPES_PART, PartStore, ROOT_RELS_PART, deflatedEntry, isContentTypesStreamName, isRelationshipPartName, isXmlContentType, normalizePartName, passthroughEntry, readZip, relsPartNameFor, sha256Hex, sha256HexOfText, sourcePartNameForRels, writeZip } from "@pptx-studio/opc";
+import { assertValid } from "@pptx-studio/validate";
+import { NS, canonicalXml, encodeXmlSource, excerpt, firstDifference, isXmlError, parseXml } from "@pptx-studio/xml";
+//#region src/errors.ts
+/**
+* The writer's own failures.
+*
+* There are only three, and the smallness is deliberate. Almost everything that
+* can go wrong on an export already has an owner: `OpcError` for the container
+* (a part with no content type, a relationship pointing at nothing), and
+* `ValidateError` for the twenty-nine rules. Re-wrapping either would throw away
+* the detail a caller needs - `ValidateError` carries the whole `Report` on its
+* `detail` - in exchange for a uniform class name nobody dispatches on.
+*
+* So this file holds what is genuinely the writer's: a hook that threw, a
+* garbage collection that could not be shown to be safe, and the one assertion
+* the writer makes on its own output.
+*/
+const WRITER_ERROR_CODES = [
+	"ERR_PREPARE_FAILED",
+	"ERR_COLLECTION_UNSAFE",
+	"ERR_PRESERVATION_BROKEN"
+];
+var WriterError = class extends Error {
+	name = "WriterError";
+	code;
+	detail;
+	constructor(code, message, detail = {}, options = {}) {
+		super(message, options);
+		this.code = code;
+		this.detail = detail;
+	}
+};
+function isWriterError(value) {
+	return value instanceof WriterError;
+}
+//#endregion
+//#region src/gc/reachability.ts
+/** Every part reachable by following relationships from the package root. */
+function reachableParts(store) {
+	const reachable = /* @__PURE__ */ new Set();
+	const blockedBy = [];
+	const queue = [];
+	const mark = (partName) => {
+		const key = normalizePartName(partName);
+		if (reachable.has(key)) return;
+		reachable.add(key);
+		queue.push(partName);
+		const rels = relsPartNameFor(partName);
+		if (store.has(rels)) reachable.add(normalizePartName(rels));
+	};
+	const follow = (rels) => {
+		for (const rel of rels.all) {
+			if (rel.targetMode === "External") continue;
+			let target;
+			try {
+				target = rels.resolve(rel);
+			} catch {
+				continue;
+			}
+			if (store.has(target)) mark(target);
+		}
+	};
+	let root;
+	try {
+		root = store.rootRelationships();
+	} catch {
+		return {
+			reachable,
+			complete: false,
+			blockedBy: [ROOT_RELS_PART]
+		};
+	}
+	if (root.size === 0) return {
+		reachable,
+		complete: false,
+		blockedBy: [ROOT_RELS_PART]
+	};
+	if (store.has(ROOT_RELS_PART)) reachable.add(normalizePartName(ROOT_RELS_PART));
+	follow(root);
+	for (let part = queue.pop(); part !== void 0; part = queue.pop()) try {
+		follow(store.relationships(part));
+	} catch {
+		blockedBy.push(relsPartNameFor(part));
+	}
+	return {
+		reachable,
+		complete: blockedBy.length === 0,
+		blockedBy
+	};
+}
+/**
+* Parts nothing in the package can get to.
+*
+* Relationship parts are excluded by construction rather than by filter - see
+* the header. `[Content_Types].xml` never appears because it is not a part.
+*/
+function orphanedParts(store, walk) {
+	return store.partNames.filter((name) => !walk.reachable.has(normalizePartName(name)));
+}
+//#endregion
+//#region src/gc/collect.ts
+/** `/ppt/media/...` - the default sweep set. */
+function isMediaPart(partName) {
+	return /^\/ppt\/media\//i.test(partName);
+}
+/**
+* Plan and apply in one pass.
+*
+* Not split into a pure plan and a separate apply, and the reason is the fixed
+* point below: removing a part can orphan the parts *it* referenced, and the
+* only way to observe that is to remove and look again. A pure planner would
+* have to simulate the store to find the second round, which is a second
+* implementation of the store.
+*
+* Never throws. A package too broken to reason about yields a plan that
+* collects nothing and says why - refusing would make a deck with one
+* unparseable `.rels` permanently unsaveable, and that `.rels` may well have
+* arrived that way. `collectGarbage` is the variant that refuses, for callers
+* who asked for a sweep and would misread silence as "nothing to do".
+*/
+function planCollection(options) {
+	const policy = options.policy ?? "orphaned-here";
+	if (policy === "none") return {
+		collect: [],
+		kept: [],
+		safe: true,
+		blockedBy: []
+	};
+	const sweepable = options.sweepable ?? isMediaPart;
+	const store = options.store;
+	let before = null;
+	if (policy === "orphaned-here") {
+		const baseline = options.baseline ?? null;
+		if (baseline === null) {
+			const now = reachableParts(store);
+			return {
+				collect: [],
+				kept: candidateOrphans(store, now, sweepable).map((part) => ({
+					part,
+					why: "it is unreferenced, but with no baseline to compare against there is no way to tell whether this session orphaned it or it arrived that way."
+				})),
+				safe: now.complete,
+				blockedBy: now.blockedBy
+			};
+		}
+		before = reachableParts(baseline);
+		if (!before.complete) return {
+			collect: [],
+			kept: [],
+			safe: false,
+			blockedBy: before.blockedBy
+		};
+	}
+	const collect = [];
+	const kept = [];
+	const decided = /* @__PURE__ */ new Set();
+	for (;;) {
+		const now = reachableParts(store);
+		if (!now.complete) return {
+			collect,
+			kept,
+			safe: false,
+			blockedBy: now.blockedBy
+		};
+		const found = candidateOrphans(store, now, sweepable).filter((part) => !decided.has(normalizePartName(part)));
+		if (found.length === 0) break;
+		const removing = [];
+		for (const part of found) {
+			decided.add(normalizePartName(part));
+			if (before !== null && !before.reachable.has(normalizePartName(part))) {
+				kept.push({
+					part,
+					why: "it was already unreferenced when this package was opened, so it is not ours to remove."
+				});
+				continue;
+			}
+			removing.push(part);
+		}
+		if (removing.length === 0) break;
+		for (const part of removing) {
+			store.removePart(part);
+			collect.push(part);
+		}
+	}
+	return {
+		collect,
+		kept,
+		safe: true,
+		blockedBy: []
+	};
+}
+function candidateOrphans(store, walk, sweepable) {
+	if (!walk.complete) return [];
+	return orphanedParts(store, walk).filter(sweepable);
+}
+/**
+* Collect, and refuse rather than guess.
+*
+* The entry point for a deliberate clean-up: a user asking for one, or a
+* command that knows it has just orphaned something. It throws when the graph
+* could not be walked completely, because a caller who asked for a sweep and
+* got silence would reasonably conclude there had been nothing to sweep.
+*
+* `exportPackage` deliberately does not use this. An export that failed because
+* some unrelated `.rels` will not parse would be refusing to save a file over a
+* defect it did not cause and cannot fix.
+*/
+function collectGarbage(options) {
+	const plan = planCollection(options);
+	if (plan.safe) return plan;
+	throw new WriterError("ERR_COLLECTION_UNSAFE", "refusing to collect: " + String(plan.blockedBy.length) + " relationship part(s) would not parse, so no part in this package can be shown to be unreferenced. First: " + (plan.blockedBy[0] ?? "(unknown)") + ". An unreadable edge is an invisible edge, and an invisible edge makes its target look like garbage.", { blockedBy: plan.blockedBy });
+}
+//#endregion
+//#region src/export/prepare.ts
+/**
+* Run the hooks in the order given.
+*
+* The order is the caller's, not ours, and it is not inferred from anything.
+* Some pairs genuinely depend on each other - autofit must settle before a font
+* pass decides which typefaces are used - and a writer that sorted hooks by
+* some notion of priority would be guessing at a dependency the caller knows
+* for certain.
+*
+* A hook that throws stops the export. That is the point: the alternative is
+* handing over a package with five of the six font artifacts in it, which
+* PowerPoint reports as a problem with the content and no way to find out
+* which.
+*/
+function runPrepare(hooks, store, baseline) {
+	const records = [];
+	for (const hook of hooks) {
+		const notes = [];
+		const context = {
+			store,
+			baseline,
+			note: (message) => notes.push(message)
+		};
+		try {
+			hook.run(context);
+		} catch (error) {
+			throw new WriterError("ERR_PREPARE_FAILED", "the prepare hook " + hook.name + " threw, so nothing was written: " + (error instanceof Error ? error.message : String(error)), { hook: hook.name }, { cause: error });
+		}
+		if (notes.length > 0) records.push({
+			hook: hook.name,
+			notes
+		});
+	}
+	return records;
+}
+//#endregion
+//#region src/export/preserve.ts
+/** The key an entry is matched on across the two archives. */
+function entryKey(entry) {
+	return isContentTypesStreamName(entry.name) ? CONTENT_TYPES_PART : normalizePartName("/" + entry.name);
+}
+/**
+* Compare the emitted archive against the one it came from.
+*
+* Throws `ERR_PRESERVATION_BROKEN` on the first difference, naming the part.
+* There is no "report and continue" mode: one part quietly re-serialised is the
+* whole category of failure this package is built to make impossible, and every
+* later one is likely the same cause.
+*/
+function assertPreserved(output, original, rewritten, zip = {}) {
+	if (original === void 0) return {
+		checked: 0,
+		rewritten: rewritten.size,
+		skipped: "the bytes this package was opened from were not supplied, so there is nothing to compare the output against."
+	};
+	let before, after;
+	try {
+		before = readZip(original, zip);
+		after = readZip(output, zip);
+	} catch (error) {
+		return {
+			checked: 0,
+			rewritten: rewritten.size,
+			skipped: "one of the two archives could not be read: " + (error instanceof Error ? error.message : String(error))
+		};
+	}
+	const source = /* @__PURE__ */ new Map();
+	for (const entry of before.entries) {
+		if (entry.isDirectory) continue;
+		source.set(entryKey(entry), entry);
+	}
+	let checked = 0;
+	for (const entry of after.entries) {
+		const key = entryKey(entry);
+		if (rewritten.has(key)) continue;
+		const was = source.get(key);
+		if (was === void 0) continue;
+		const now = after.raw(entry);
+		const then = before.raw(was);
+		if (entry.method === was.method && entry.crc32 === was.crc32 && entry.uncompressedSize === was.uncompressedSize && sameBytes(now, then)) {
+			checked++;
+			continue;
+		}
+		throw new WriterError("ERR_PRESERVATION_BROKEN", entry.name + " was not edited and came out different anyway (" + describe(was) + " in, " + describe(entry) + " out). An untouched part is streamed through still compressed and is never re-serialised: the moment that stops being true, every feature we cannot parse is a feature we can lose.", { part: "/" + entry.name });
+	}
+	return {
+		checked,
+		rewritten: rewritten.size,
+		skipped: null
+	};
+}
+function describe(entry) {
+	return String(entry.compressedSize) + "B method " + String(entry.method) + " crc " + entry.crc32.toString(16);
+}
+function sameBytes(a, b) {
+	if (a.byteLength !== b.byteLength) return false;
+	for (let i = 0; i < a.byteLength; i++) if (a[i] !== b[i]) return false;
+	return true;
+}
+//#endregion
+//#region src/export/export.ts
+/** Open a package for editing, with the baseline an export will need. */
+function openPackage(bytes, options = {}) {
+	return {
+		store: PartStore.open(bytes, options),
+		baseline: PartStore.open(bytes, options),
+		baselineBytes: bytes
+	};
+}
+function exportPackage(options) {
+	const store = options.store;
+	const baseline = options.baseline ?? null;
+	const prepared = runPrepare(options.prepare ?? [], store, baseline);
+	const collection = planCollection({
+		store,
+		baseline,
+		...options.collect === void 0 ? {} : { policy: options.collect },
+		...options.sweepable === void 0 ? {} : { sweepable: options.sweepable }
+	});
+	store.materializeRelationships();
+	const rewritten = store.rewrittenParts();
+	const streamed = store.partNames.length - rewritten.length;
+	const bytes = store.write({
+		...options.normalizeEntryOrder === void 0 ? {} : { normalizeEntryOrder: options.normalizeEntryOrder },
+		...options.deflateLevel === void 0 ? {} : { deflateLevel: options.deflateLevel }
+	});
+	const preservation = options.verifyPreservation === false ? {
+		checked: 0,
+		rewritten: rewritten.length,
+		skipped: "turned off by the caller."
+	} : assertPreserved(bytes, options.baselineBytes, rewrittenKeys(store, rewritten), options.zip);
+	return {
+		bytes,
+		report: options.validate === false ? null : assertValid({
+			store,
+			bytes,
+			...baseline === null ? {} : { baseline },
+			...options.baselineBytes === void 0 ? {} : { baselineBytes: options.baselineBytes },
+			...options.rules === void 0 ? {} : { rules: options.rules },
+			...options.zip === void 0 ? {} : { zip: options.zip }
+		}),
+		prepared,
+		collection,
+		rewritten,
+		streamed,
+		preservation
+	};
+}
+/**
+* The parts the preservation check must not compare, in its own key space.
+*
+* `[Content_Types].xml` is in the set whenever the map changed, and only then:
+* it is passed through untouched when nothing altered it, which is what lets a
+* deck that spells it `[content_types].xml` round-trip its original bytes under
+* the canonical entry name.
+*/
+function rewrittenKeys(store, rewritten) {
+	const keys = new Set(rewritten.map((name) => normalizePartName(name)));
+	if (store.contentTypes.dirty) keys.add(CONTENT_TYPES_PART);
+	return keys;
+}
+//#endregion
+//#region src/oracle/bisect.ts
+/** Every change in the forest, parents before children. */
+function flattenChanges(changes) {
+	const out = [];
+	const stack = [...changes].reverse();
+	while (stack.length > 0) {
+		const change = stack.pop();
+		out.push(change);
+		for (let i = change.children.length - 1; i >= 0; i -= 1) stack.push(change.children[i]);
+	}
+	return out;
+}
+/** The leaves: the finest changes this delta can express. */
+function leafChanges(changes) {
+	return flattenChanges(changes).filter((change) => change.children.length === 0);
+}
+function index(archive) {
+	const map = /* @__PURE__ */ new Map();
+	for (const entry of archive.entries) {
+		if (entry.isDirectory) continue;
+		map.set(entry.name, {
+			archive,
+			entry
+		});
+	}
+	return map;
+}
+function equalBytes(a, b) {
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i += 1) if (a[i] !== b[i]) return false;
+	return true;
+}
+/**
+* The package with exactly this subset of the changes applied to the original.
+*
+* Entries no change touches are passed through still compressed rather than
+* re-deflated - the same trick `PartStore.write` uses, and it matters more
+* here, because this runs once per oracle call rather than once per export.
+*/
+function buildPackage(context, selected) {
+	const applied = /* @__PURE__ */ new Map();
+	for (const [name, changes] of context.byEntry) {
+		const chosen = changes.filter((change) => selected.has(change.id));
+		if (chosen.length > 0) applied.set(name, chosen);
+	}
+	const entries = [];
+	for (const name of context.order) {
+		const source = context.original.get(name);
+		const chosen = applied.get(name);
+		if (chosen === void 0) {
+			if (source !== void 0) entries.push(passthroughEntry(source.archive, source.entry));
+			continue;
+		}
+		const whole = chosen.find((change) => change.span === null);
+		if (whole !== void 0) {
+			if (whole.kind === "entry-removed") continue;
+			const target = context.broken.get(name);
+			entries.push(passthroughEntry(target.archive, target.entry));
+			continue;
+		}
+		let text = context.text.get(name);
+		const ordered = [...chosen].sort((a, b) => b.span.start - a.span.start);
+		for (const change of ordered) text = text.slice(0, change.span.start) + change.text + text.slice(change.span.end);
+		entries.push(deflatedEntry(name, encodeXmlSource(text)));
+	}
+	return writeZip(entries);
+}
+function atom(builder, entry, kind, where, depth, span, was, text, children = []) {
+	return {
+		id: builder.next(),
+		entry,
+		kind,
+		where,
+		depth,
+		span,
+		text,
+		was,
+		children
+	};
+}
+function slice(source, node) {
+	return source.slice(node.start, node.end);
+}
+function nameOf(node) {
+	switch (node.type) {
+		case "element": return node.qname;
+		case "text": return "text()";
+		case "cdata": return "cdata()";
+		case "comment": return "comment()";
+		case "processingInstruction": return "processing-instruction()";
+		case "declaration": return "xml-declaration()";
+	}
+}
+/** `/p:sld/p:cSld/p:spTree/p:sp[3]` - one-based, and indexed only where it must be. */
+function pathTo(parent, siblings, at) {
+	const name = nameOf(siblings[at]);
+	let position = 1;
+	let total = 0;
+	for (let i = 0; i < siblings.length; i += 1) {
+		if (nameOf(siblings[i]) !== name) continue;
+		total += 1;
+		if (i < at) position += 1;
+	}
+	return parent + "/" + name + (total > 1 ? "[" + String(position) + "]" : "");
+}
+/**
+* Attributes paired by position, or null when they do not line up.
+*
+* Null whenever anything outside the attributes themselves differs - the
+* element name, the number or order of attributes, the whitespace before `/>`.
+* Otherwise the attribute spans would not cover the whole difference, and
+* reverting every one of them would not reproduce the original tag, which is
+* the single property the descent is allowed to assume.
+*/
+function pairAttributes(a, b) {
+	if (a.attributes.length === 0 || a.attributes.length !== b.attributes.length) return null;
+	if (a.nameEnd - a.start !== b.nameEnd - b.start) return null;
+	if (a.attributes[0].start - a.start !== b.attributes[0].start - b.start) return null;
+	if (a.attributes.at(-1).end !== a.trailingSpaceStart) return null;
+	if (b.attributes.at(-1).end !== b.trailingSpaceStart) return null;
+	if (a.openTagEnd - a.trailingSpaceStart !== b.openTagEnd - b.trailingSpaceStart) return null;
+	const pairs = [];
+	for (let i = 0; i < a.attributes.length; i += 1) {
+		const left = a.attributes[i];
+		const right = b.attributes[i];
+		if (left.qname !== right.qname) return null;
+		pairs.push([left, right]);
+	}
+	return pairs;
+}
+/** The start tag, decomposed into attributes when the two tags line up. */
+function tagChange(builder, entry, where, depth, a, b, ao, bo) {
+	const children = [];
+	const pairs = pairAttributes(a, b);
+	if (pairs !== null) for (const [left, right] of pairs) {
+		const was = ao.slice(left.start, left.end);
+		const text = bo.slice(right.start, right.end);
+		if (was === text) continue;
+		children.push(atom(builder, entry, "attribute", where + "/@" + left.qname, depth + 1, {
+			start: left.start,
+			end: left.end
+		}, was, text));
+	}
+	return atom(builder, entry, "tag", where, depth, {
+		start: a.start,
+		end: a.openTagEnd
+	}, ao.slice(a.start, a.openTagEnd), bo.slice(b.start, b.openTagEnd), children);
+}
+/**
+* Line up two lists of children and describe the difference between them.
+*
+* The two lists are matched from both ends first, and only what is left in the
+* middle is treated as changed. That is what makes an insertion or a deletion
+* nameable: without it, any change to the *number* of children shifts every
+* position after it, nothing pairs, and the answer degrades to "something in
+* this element". The case that forced it is the headline one - a missing
+* `<Default Extension="fntdata"/>` reduces `<Types>` from seventeen children to
+* sixteen, and positional pairing reported the whole content-type stream.
+*
+* When the middles are the same length they pair off one to one, which is the
+* ordinary edit-in-place case. When they are not, the whole middle is one
+* change: a run of children replaced by another run. That is coarse if a part
+* had several separate insertions, and it is exact in the common case of one -
+* which is what a writer produces.
+*/
+function pairChildren(builder, entry, where, depth, a, b, ao, bo) {
+	const left = a.children;
+	const right = b.children;
+	let lo = 0;
+	while (lo < left.length && lo < right.length && slice(ao, left[lo]) === slice(bo, right[lo])) lo += 1;
+	let hiA = left.length;
+	let hiB = right.length;
+	while (hiA > lo && hiB > lo && slice(ao, left[hiA - 1]) === slice(bo, right[hiB - 1])) {
+		hiA -= 1;
+		hiB -= 1;
+	}
+	if (hiA === lo && hiB === lo) return [];
+	const changes = [];
+	if (hiA - lo === hiB - lo) {
+		for (let i = lo; i < hiA; i += 1) {
+			builder.budget.left -= 1;
+			changes.push(pairNodes(builder, entry, pathTo(where, left, i), depth + 1, left[i], right[i], ao, bo));
+		}
+		return changes;
+	}
+	const start = lo < hiA ? left[lo].start : left[hiA]?.start ?? a.closeTagStart;
+	const end = lo < hiA ? left[hiA - 1].end : start;
+	const text = lo < hiB ? bo.slice(right[lo].start, right[hiB - 1].end) : "";
+	const at = lo < hiA ? pathTo(where, left, lo) : where;
+	builder.budget.left -= 1;
+	changes.push(atom(builder, entry, "children", at, depth + 1, {
+		start,
+		end
+	}, ao.slice(start, end), text));
+	return changes;
+}
+/** One change turning the original's node into the broken package's node. */
+function pairNodes(builder, entry, where, depth, a, b, ao, bo) {
+	const span = {
+		start: a.start,
+		end: a.end
+	};
+	const was = slice(ao, a);
+	const text = slice(bo, b);
+	if (!(a.type === "element" && b.type === "element" && a.qname === b.qname && a.selfClosing === b.selfClosing)) return atom(builder, entry, a.type === "element" ? "element" : "node", where, depth, span, was, text);
+	if (builder.budget.left <= 0) {
+		builder.truncated.yes = true;
+		return atom(builder, entry, "element", where, depth, span, was, text);
+	}
+	const element = a;
+	const other = b;
+	const children = [];
+	if (ao.slice(element.start, element.openTagEnd) !== bo.slice(other.start, other.openTagEnd)) {
+		builder.budget.left -= 1;
+		children.push(tagChange(builder, entry, where, depth + 1, element, other, ao, bo));
+	}
+	children.push(...pairChildren(builder, entry, where, depth, element, other, ao, bo));
+	if (children.length === 0) return atom(builder, entry, "element", where, depth, span, was, text);
+	return atom(builder, entry, "element", where, depth, span, was, text, children);
+}
+function deltaForEntry(builder, name, originalBytes, brokenBytes, text) {
+	const whole = () => atom(builder, name, "entry", "/", 0, null, null, null);
+	let a;
+	let b;
+	try {
+		a = parseXml(originalBytes);
+		b = parseXml(brokenBytes);
+	} catch {
+		return whole();
+	}
+	if (a.children.length !== b.children.length) return whole();
+	const children = [];
+	for (let i = 0; i < a.children.length; i += 1) {
+		const left = a.children[i];
+		const right = b.children[i];
+		if (slice(a.source, left) === slice(b.source, right)) continue;
+		builder.budget.left -= 1;
+		children.push(pairNodes(builder, name, pathTo("", a.children, i), 1, left, right, a.source, b.source));
+	}
+	if (children.length === 0) return whole();
+	text.set(name, a.source);
+	return atom(builder, name, "entry", "/", 0, null, null, null, children);
+}
+/** The forest of changes between two packages. One root per differing entry. */
+function collectDelta(original, broken, maxChanges = 2e4) {
+	let counter = 0;
+	const builder = {
+		next: () => counter++,
+		budget: { left: maxChanges },
+		truncated: { yes: false }
+	};
+	const left = index(original);
+	const right = index(broken);
+	const text = /* @__PURE__ */ new Map();
+	const changes = [];
+	for (const [name, source] of left) {
+		const target = right.get(name);
+		if (target === void 0) {
+			changes.push(atom(builder, name, "entry-removed", "/", 0, null, null, null));
+			continue;
+		}
+		const a = source.archive.read(source.entry);
+		const b = target.archive.read(target.entry);
+		if (equalBytes(a, b)) continue;
+		changes.push(deltaForEntry(builder, name, a, b, text));
+	}
+	for (const name of right.keys()) {
+		if (left.has(name)) continue;
+		changes.push(atom(builder, name, "entry-added", "/", 0, null, null, null));
+	}
+	return {
+		changes,
+		text,
+		truncated: builder.truncated.yes
+	};
+}
+/** Internal. Never escapes `bisectPackages`; see the `maxRuns` handling there. */
+var Exhausted = class extends Error {};
+/**
+* `ddmin`, reducing a set of changes to a 1-minimal failing subset.
+*
+* 1-minimal means every change left in the answer is load-bearing: drop any one
+* and the package stops failing. It does **not** mean no smaller failing set
+* exists - two changes may only fail together, and neither alone - and the
+* difference is worth keeping straight, because a report claiming a minimality
+* it does not have sends someone looking in the wrong place.
+*/
+function ddmin(items, test, record = () => {}) {
+	let current = items;
+	let n = 2;
+	while (current.length >= 2) {
+		const size = Math.ceil(current.length / n);
+		const subsets = [];
+		for (let i = 0; i < current.length; i += size) subsets.push(current.slice(i, i + size));
+		const failing = subsets.find((subset) => test(subset) === "fails");
+		if (failing !== void 0) {
+			current = failing;
+			record(current);
+			n = 2;
+			continue;
+		}
+		let dropped = false;
+		for (const subset of subsets) {
+			const complement = current.filter((change) => !subset.includes(change));
+			if (complement.length === 0 || complement.length === current.length) continue;
+			if (test(complement) !== "fails") continue;
+			current = complement;
+			record(current);
+			n = Math.max(n - 1, 2);
+			dropped = true;
+			break;
+		}
+		if (dropped) continue;
+		if (n >= current.length) break;
+		n = Math.min(current.length, n * 2);
+	}
+	return current;
+}
+function bisectPackages(originalBytes, brokenBytes, options) {
+	const original = readZip(originalBytes, options.zip ?? {});
+	const broken = readZip(brokenBytes, options.zip ?? {});
+	const { changes, text, truncated } = collectDelta(original, broken, options.maxChanges);
+	const order = [];
+	for (const entry of original.entries) if (!entry.isDirectory) order.push(entry.name);
+	for (const entry of broken.entries) {
+		if (entry.isDirectory || order.includes(entry.name)) continue;
+		order.push(entry.name);
+	}
+	const byEntry = /* @__PURE__ */ new Map();
+	for (const change of flattenChanges(changes)) {
+		const list = byEntry.get(change.entry);
+		if (list === void 0) byEntry.set(change.entry, [change]);
+		else list.push(change);
+	}
+	const context = {
+		order,
+		original: index(original),
+		broken: index(broken),
+		text,
+		byEntry
+	};
+	const maxRuns = options.maxRuns ?? 2e3;
+	let runs = 0;
+	let cached = 0;
+	let unresolved = 0;
+	let exhausted = false;
+	const seen = /* @__PURE__ */ new Map();
+	const test = (subset) => {
+		const ids = new Set(subset.map((change) => change.id));
+		const key = [...ids].sort((a, b) => a - b).join(",");
+		const remembered = seen.get(key);
+		if (remembered !== void 0) {
+			cached += 1;
+			return remembered;
+		}
+		if (runs >= maxRuns) throw new Exhausted();
+		runs += 1;
+		const label = String(subset.length) + "/" + String(changes.length) + " change(s)";
+		options.onRun?.({
+			run: runs,
+			applied: subset.length,
+			total: changes.length,
+			label
+		});
+		const verdict = options.oracle(buildPackage(context, ids), label);
+		if (verdict === "unresolved") unresolved += 1;
+		seen.set(key, verdict);
+		return verdict;
+	};
+	const done = (outcome, minimal) => ({
+		outcome,
+		changes,
+		minimal,
+		bytes: buildPackage(context, new Set(minimal.map((change) => change.id))),
+		runs,
+		cached,
+		unresolved,
+		exhausted,
+		truncated
+	});
+	if (changes.length === 0) return done("identical", []);
+	let best = changes;
+	try {
+		if (test([]) === "fails") return done("original-fails", []);
+		if (test(changes) !== "fails") return done("broken-passes", changes);
+		let level = changes;
+		for (;;) {
+			best = ddmin(level, test, (current) => {
+				best = current;
+			});
+			const expanded = best.flatMap((change) => change.children.length > 0 ? [...change.children] : [change]);
+			if (expanded.length === best.length && expanded.every((c, i) => c === best[i])) break;
+			level = expanded;
+		}
+	} catch (error) {
+		if (!(error instanceof Exhausted)) throw error;
+		exhausted = true;
+	}
+	return done("localized", best);
+}
+/** One line naming a change, without its text. */
+function describeChange(change) {
+	const where = change.where === "/" ? "" : " " + change.where;
+	switch (change.kind) {
+		case "entry-added": return "added    /" + change.entry;
+		case "entry-removed": return "removed  /" + change.entry;
+		case "entry": return "entry    /" + change.entry;
+		case "element": return "element  /" + change.entry + where;
+		case "node": return "node     /" + change.entry + where;
+		case "children":
+			if (change.was === "") return "added    /" + change.entry + where;
+			if (change.text === "") return "removed  /" + change.entry + where;
+			return "children /" + change.entry + where;
+		case "tag": return "tag      /" + change.entry + where;
+		case "attribute": return "attr     /" + change.entry + where;
+	}
+}
+/** `2 change(s) in 1 entry(s), from a delta of 91, in 37 oracle run(s)`. */
+function summarizeBisect(result) {
+	const entries = new Set(result.minimal.map((change) => change.entry));
+	return String(result.minimal.length) + " change(s) in " + String(entries.size) + " entry(s), from a delta of " + String(flattenChanges(result.changes).length) + ", in " + String(result.runs) + " oracle run(s)";
+}
+//#endregion
+//#region src/oracle/roundtrip.ts
+/** The relationships namespace: every attribute in it is a relationship id. */
+const R = NS.r;
+/**
+* What a relationship points at, as a string that does not mention its id.
+*
+* An internal target resolves to an absolute part name, so that `../media/a.png`
+* from a slide and `/ppt/media/a.png` written absolutely are one target. An
+* external one is compared verbatim: it is a URI, we do not own it, and
+* normalising somebody's `http://Example.COM/` would be inventing a rule.
+*/
+function targetKey(rels, rel) {
+	if (rel.targetMode === "External") return "External " + rel.target;
+	try {
+		return "Internal " + normalizePartName(rels.resolve(rel));
+	} catch {
+		return "Internal? " + rel.target;
+	}
+}
+function relationshipKey(rels, rel) {
+	return rel.type + " -> " + targetKey(rels, rel);
+}
+/**
+* Match two relationship collections by what they point at.
+*
+* Duplicates are legal - a part may relate to the same target twice under two
+* ids, and `a03-fills` in the corpus has eight fills on one image - so this
+* matches within a key group by document order rather than assuming one
+* relationship per key. Order inside a group is arbitrary in principle; it is
+* the only tiebreak available, and picking the wrong pairing among identical
+* relationships cannot change the answer, because the two ids resolve to the
+* same place.
+*/
+function matchGraphs(source, before, after) {
+	const groupsBefore = /* @__PURE__ */ new Map();
+	const groupsAfter = /* @__PURE__ */ new Map();
+	const collect = (rels, into) => {
+		const keys = [];
+		for (const rel of rels.all) {
+			const key = relationshipKey(rels, rel);
+			keys.push(key);
+			const bucket = into.get(key);
+			if (bucket === void 0) into.set(key, [rel]);
+			else bucket.push(rel);
+		}
+		return keys.sort();
+	};
+	const signature = collect(before, groupsBefore).join("\n");
+	const writtenSignature = collect(after, groupsAfter).join("\n");
+	const relabel = /* @__PURE__ */ new Map();
+	const relabelled = [];
+	const differences = [];
+	for (const [key, mine] of groupsBefore) {
+		const theirs = groupsAfter.get(key) ?? [];
+		const shared = Math.min(mine.length, theirs.length);
+		for (let i = 0; i < shared; i++) {
+			const from = mine[i].id;
+			const to = theirs[i].id;
+			relabel.set(from, to);
+			if (from !== to) relabelled.push({
+				source,
+				from,
+				to,
+				target: key
+			});
+		}
+		for (let i = shared; i < mine.length; i++) differences.push({
+			kind: "relationship",
+			part: source,
+			detail: "the relationship " + mine[i].id + " (" + key + ") is in the original and not in what was written"
+		});
+	}
+	for (const [key, theirs] of groupsAfter) {
+		const mine = groupsBefore.get(key) ?? [];
+		for (let i = mine.length; i < theirs.length; i++) differences.push({
+			kind: "relationship",
+			part: source,
+			detail: "the relationship " + theirs[i].id + " (" + key + ") was written and is not in the original"
+		});
+	}
+	return {
+		relabel,
+		relabelled,
+		differences,
+		signature,
+		writtenSignature
+	};
+}
+/**
+* Every part that could own relationships, in either package, plus the root.
+*
+* Every part, and not only the ones with a `.rels` in `partNames` - which is
+* the shorter, faster and wrong version of this function, and the same trap
+* `reachability.ts` documents. A relationship collection created in this
+* session exists as a parsed object until `PartStore.write` materialises it, so
+* keying on existing relationship parts makes exactly the edges an editing
+* session added invisible. `PartStore.relationships` returns an empty
+* collection for a part that has none, so asking every part costs a lookup and
+* removes the whole class of miss.
+*/
+function relationshipSources(original, written) {
+	const sources = /* @__PURE__ */ new Set(["/"]);
+	for (const store of [original, written]) for (const partName of store.partNames) {
+		if (!isRelationshipPartName(partName)) {
+			sources.add(partName);
+			continue;
+		}
+		try {
+			sources.add(sourcePartNameForRels(partName));
+		} catch {}
+	}
+	return [...sources].sort();
+}
+function readRelationships(store, source) {
+	try {
+		return store.relationships(source);
+	} catch (error) {
+		return error instanceof Error ? error : new Error(String(error));
+	}
+}
+/** The content types are the same type if they differ only in case or spacing. */
+function sameContentType(a, b) {
+	return (a ?? "").trim().toLowerCase() === (b ?? "").trim().toLowerCase();
+}
+/**
+* Compare two packages.
+*
+* Never throws. Every failure - a part that will not parse, a `.rels` that will
+* not read - is a difference with a reason, because the caller of a comparison
+* wants the whole list and not the first item on it.
+*/
+function comparePackages(original, written, options = {}) {
+	const differences = [];
+	const parts = [];
+	const relabelled = [];
+	const relabelBySource = /* @__PURE__ */ new Map();
+	const graphs = /* @__PURE__ */ new Map();
+	for (const source of relationshipSources(original, written)) {
+		const before = readRelationships(original, source);
+		const after = readRelationships(written, source);
+		if (before instanceof Error || after instanceof Error) {
+			const which = before instanceof Error ? "the original" : "what was written";
+			const error = before instanceof Error ? before : after;
+			differences.push({
+				kind: "unreadable",
+				part: source,
+				detail: "the relationships of " + which + " would not parse: " + error.message
+			});
+			continue;
+		}
+		const match = matchGraphs(source, before, after);
+		graphs.set(normalizePartName(source), match);
+		relabelBySource.set(normalizePartName(source), match.relabel);
+		differences.push(...match.differences);
+		relabelled.push(...match.relabelled);
+	}
+	const names = /* @__PURE__ */ new Map();
+	for (const store of [original, written]) for (const partName of store.partNames) names.set(normalizePartName(partName), partName);
+	let xmlCount = 0;
+	let binaryCount = 0;
+	let relsCount = 0;
+	for (const key of [...names.keys()].sort()) {
+		const part = names.get(key);
+		const inOriginal = original.has(part);
+		const inWritten = written.has(part);
+		if (!inOriginal || !inWritten) {
+			differences.push({
+				kind: inOriginal ? "part-removed" : "part-added",
+				part,
+				detail: inOriginal ? "the original has this part and what was written does not" : "this part was written and the original does not have it"
+			});
+			continue;
+		}
+		const typeBefore = original.contentTypeOf(part);
+		const typeAfter = written.contentTypeOf(part);
+		if (!sameContentType(typeBefore, typeAfter)) differences.push({
+			kind: "content-type",
+			part,
+			detail: "the content type was " + (typeBefore ?? "(none)") + " and is now " + (typeAfter ?? "(none)")
+		});
+		if (isRelationshipPartName(part)) {
+			relsCount++;
+			parts.push(relationshipComparison(part, graphs));
+			continue;
+		}
+		if (isXmlContentType(typeBefore) && isXmlContentType(typeAfter)) {
+			xmlCount++;
+			parts.push(compareXmlPart(part, original, written, relabelBySource, differences, options.limits));
+			continue;
+		}
+		binaryCount++;
+		parts.push(compareBinaryPart(part, original, written, differences));
+	}
+	const same = parts.filter((entry) => entry.same).length;
+	return {
+		ok: differences.length === 0,
+		parts,
+		differences,
+		relabelled,
+		counts: {
+			xml: xmlCount,
+			binary: binaryCount,
+			relationships: relsCount,
+			same
+		}
+	};
+}
+/**
+* A relationship part's verdict, taken from the graph pass rather than from its
+* bytes.
+*
+* The digest is over the graph with the ids omitted, so it is the same on both
+* sides of a renumbering. That is the whole claim of this comparison stated as
+* a single value: two `.rels` with one digest describe one package.
+*/
+function relationshipComparison(part, graphs) {
+	let source;
+	try {
+		source = sourcePartNameForRels(part);
+	} catch {
+		return {
+			part,
+			how: "relationships",
+			same: true,
+			digest: "",
+			writtenDigest: ""
+		};
+	}
+	const match = graphs.get(normalizePartName(source));
+	if (match === void 0) return {
+		part,
+		how: "relationships",
+		same: false,
+		digest: "",
+		writtenDigest: ""
+	};
+	const digest = sha256HexOfText(match.signature);
+	const writtenDigest = sha256HexOfText(match.writtenSignature);
+	return {
+		part,
+		how: "relationships",
+		same: digest === writtenDigest,
+		digest,
+		writtenDigest
+	};
+}
+function compareXmlPart(part, original, written, relabelBySource, differences, limits) {
+	const relabel = relabelBySource.get(normalizePartName(part));
+	const rewriteAttributeValue = relabel === void 0 || relabel.size === 0 ? void 0 : (value, namespaceUri) => namespaceUri === R ? relabel.get(value) ?? value : value;
+	const canonical = (store, which, relabelThis) => {
+		try {
+			const document = parseXml(store.read(part), limits);
+			return canonicalXml(document, relabelThis && rewriteAttributeValue !== void 0 ? { rewriteAttributeValue } : {});
+		} catch (error) {
+			return {
+				kind: "unreadable",
+				part,
+				detail: which + " would not parse as XML: " + (isXmlError(error) ? error.code + " - " + error.message : String(error))
+			};
+		}
+	};
+	const before = canonical(original, "the original", true);
+	const after = canonical(written, "what was written", false);
+	if (typeof before !== "string" || typeof after !== "string") {
+		if (typeof before !== "string") differences.push(before);
+		if (typeof after !== "string") differences.push(after);
+		return {
+			part,
+			how: "xml",
+			same: false,
+			digest: "",
+			writtenDigest: ""
+		};
+	}
+	const digest = sha256HexOfText(before);
+	const writtenDigest = sha256HexOfText(after);
+	if (digest !== writtenDigest) {
+		const at = firstDifference(before, after);
+		differences.push({
+			kind: "xml",
+			part,
+			detail: "the canonical XML differs at character " + String(at) + "\n    original: " + excerpt(before, at) + "\n    written:  " + excerpt(after, at)
+		});
+	}
+	return {
+		part,
+		how: "xml",
+		same: digest === writtenDigest,
+		digest,
+		writtenDigest
+	};
+}
+function compareBinaryPart(part, original, written, differences) {
+	let digest;
+	let writtenDigest;
+	try {
+		digest = sha256Hex(original.read(part));
+		writtenDigest = sha256Hex(written.read(part));
+	} catch (error) {
+		differences.push({
+			kind: "unreadable",
+			part,
+			detail: "the part could not be read: " + (error instanceof Error ? error.message : "")
+		});
+		return {
+			part,
+			how: "binary",
+			same: false,
+			digest: "",
+			writtenDigest: ""
+		};
+	}
+	if (digest !== writtenDigest) differences.push({
+		kind: "binary",
+		part,
+		detail: "the bytes differ: sha256 was " + digest.slice(0, 12) + ", is now " + writtenDigest.slice(0, 12) + " (" + String(original.read(part).length) + " bytes then, " + String(written.read(part).length) + " now)"
+	});
+	return {
+		part,
+		how: "binary",
+		same: digest === writtenDigest,
+		digest,
+		writtenDigest
+	};
+}
+/** A one-line summary, for a CLI and for a test failure message. */
+function summarizeRoundTrip(report) {
+	const { xml, binary, relationships, same } = report.counts;
+	const total = xml + binary + relationships;
+	return String(same) + "/" + String(total) + " parts identical (" + String(xml) + " xml, " + String(relationships) + " rels, " + String(binary) + " binary)" + (report.relabelled.length === 0 ? "" : ", " + String(report.relabelled.length) + " relationship id(s) renamed") + (report.ok ? "" : ", " + String(report.differences.length) + " difference(s)");
+}
+/**
+* Read a package, write it back, and compare the two.
+*
+* The whole of sub-phase 1.4 in one call, and the shape `cli roundtrip` and the
+* corpus gate both want. Every option `exportPackage` takes is accepted, so a
+* caller can round-trip through a different deflate level or a normalised entry
+* order - which is the point of a comparison that is not byte equality, and
+* worth having a test do deliberately.
+*
+* Throws whatever `exportPackage` throws. A package the firewall refuses is not
+* a package with a round-trip difference; it is one that never got written, and
+* flattening the two into one verdict would lose the distinction exactly where
+* it matters.
+*/
+function roundTripPackage(bytes, options = {}) {
+	const { limits, ...exportOptions } = options;
+	const opened = openPackage(bytes, options.zip ?? {});
+	const exported = exportPackage({
+		...exportOptions,
+		...opened
+	});
+	const written = PartStore.open(exported.bytes, options.zip ?? {});
+	const comparison = comparePackages(opened.baseline, written, limits === void 0 ? {} : { limits });
+	return {
+		exported,
+		written,
+		comparison,
+		ok: comparison.ok
+	};
+}
+//#endregion
+export { WRITER_ERROR_CODES, WriterError, assertPreserved, bisectPackages, collectDelta, collectGarbage, comparePackages, describeChange, exportPackage, flattenChanges, isMediaPart, isWriterError, leafChanges, openPackage, orphanedParts, planCollection, reachableParts, roundTripPackage, runPrepare, summarizeBisect, summarizeRoundTrip };
+
+//# sourceMappingURL=index.js.map