@pptx-studio/writer 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,818 @@
+import { PartStore, ReadZipOptions, ZipArchive } from "@pptx-studio/opc";
+import { Report, RuleId } from "@pptx-studio/validate";
+import { XmlParseLimits } from "@pptx-studio/xml";
+//#region src/errors.d.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.
+ */
+declare const WRITER_ERROR_CODES: readonly ["ERR_PREPARE_FAILED", "ERR_COLLECTION_UNSAFE", "ERR_PRESERVATION_BROKEN"];
+type WriterErrorCode = (typeof WRITER_ERROR_CODES)[number];
+interface WriterErrorDetail {
+  /** The prepare hook that threw, for `ERR_PREPARE_FAILED`. */
+  readonly hook?: string;
+  /** The part the failure is about, when it is about one. */
+  readonly part?: string;
+  /** Relationship parts that would not parse, for `ERR_COLLECTION_UNSAFE`. */
+  readonly blockedBy?: readonly string[];
+}
+declare class WriterError extends Error {
+  readonly name = "WriterError";
+  readonly code: WriterErrorCode;
+  readonly detail: WriterErrorDetail;
+  constructor(code: WriterErrorCode, message: string, detail?: WriterErrorDetail, options?: {
+    cause?: unknown;
+  });
+}
+declare function isWriterError(value: unknown): value is WriterError;
+//#endregion
+//#region src/gc/reachability.d.ts
+/**
+ * Which parts anything can still get to, and - the part that matters - whether
+ * we are sure.
+ *
+ * `@pptx-studio/census` has a walk of its own and this is deliberately not it.
+ * The two answer the same question with opposite failure modes, and the census
+ * says so in its own comment: it swallows a relationship part it cannot parse
+ * and carries on, because a census must never refuse. That is exactly right for
+ * a report and exactly wrong here. A swallowed parse error means some edges are
+ * invisible, invisible edges make their targets look unreferenced, and
+ * unreferenced is what this walk is used to justify deleting. The census's
+ * worst case is an inaccurate line of output; ours is a user's image gone.
+ *
+ * So every failure is recorded rather than skipped, and `complete` is false if
+ * there was one. `collect.ts` does nothing at all unless it is true.
+ *
+ * ## Relationship parts are reachable when their source is
+ *
+ * Nothing ever *relates* to a `.rels` - the spec forbids it and PowerPoint
+ * refuses a package that tries, which is one of the assertions in `PartStore`.
+ * They are found by naming convention instead. Walking edges alone would
+ * therefore report every relationship part in the package as unreachable, which
+ * is true of the graph and false of the container. They are marked alongside
+ * their source, so that "unreachable" keeps meaning "nothing can find this".
+ */
+interface Reachability {
+  /** Normalised names of every part something can still get to, including `.rels` parts. */
+  readonly reachable: ReadonlySet<string>;
+  /**
+   * False when at least one relationship part could not be read.
+   *
+   * A caller that deletes on the strength of an incomplete walk is deleting on
+   * the strength of a parse error.
+   */
+  readonly complete: boolean;
+  /** The relationship parts that would not parse, and the root if it was unusable. */
+  readonly blockedBy: readonly string[];
+}
+/** Every part reachable by following relationships from the package root. */
+declare function reachableParts(store: PartStore): Reachability;
+/**
+ * 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.
+ */
+declare function orphanedParts(store: PartStore, walk: Reachability): string[];
+//#endregion
+//#region src/gc/collect.d.ts
+/**
+ * Mark and sweep, for media.
+ *
+ * ## What it collects, and why so little
+ *
+ * The sweep set is `/ppt/media/` and nothing else. Not layouts, not masters,
+ * not themes, not `ppt/embeddings/*.bin`, whatever the relationship graph says
+ * about them. PowerPoint keeps slide layouts that no slide uses - that is how
+ * the layout picker has anything to offer - so a package where an unused layout
+ * has been tidied away is a package where "change layout" has quietly lost
+ * options the user had a moment ago. There is no upside to weigh against that:
+ * the layout part is a few kilobytes and the media is the megabytes.
+ *
+ * ## Where the walk is rooted is the same rule, made twice
+ *
+ * The obvious implementation asks "which images do the slides use?" and roots
+ * the walk at the slide list. It is wrong, and wrong in the way that only shows
+ * up weeks later: a layout no slide currently uses still has its background
+ * picture, and switching a slide onto that layout has to still work. Rooting at
+ * the package root instead gets this right with no special case - layouts hang
+ * off the master, the master off `presentation.xml` - so every image a layout
+ * or master references is live whether or not a slide has ever used it.
+ *
+ * ## It cannot break a relationship
+ *
+ * Worth stating as a property rather than a hope, because it is what makes this
+ * safe to run without supervision. A part is collected only when **no**
+ * relationship anywhere in the package resolves to it. So there is no edge left
+ * to dangle - and the case that kills naive implementations, two slides sharing
+ * one image with one of them deleted, cannot arise: the surviving slide's
+ * relationship still resolves and still marks the image live.
+ *
+ * The corollary is a division of labour. This collects nothing until something
+ * else has removed the relationship, and removing it is part of deleting a
+ * picture, which is a document operation and belongs to Phase 5's command
+ * layer rather than to the writer.
+ *
+ * ## By default it collects only what we orphaned
+ *
+ * The question `@pptx-studio/validate` asks about findings, asked about parts:
+ * not "is this unreferenced" but "did *we* leave it unreferenced". A deck can
+ * arrive with an orphaned image - decks that have been through several editors
+ * often do - and collecting it would mean that merely opening and saving a file
+ * changes it. That breaks the property the whole of Phase 1 exists to
+ * establish, and it breaks it in the direction where nobody notices for months.
+ *
+ * So the default policy differences the reachability of the package we are
+ * about to write against the package as it was opened, and collects only what
+ * moved from reachable to unreachable. With no baseline there is no "we", and
+ * it collects nothing.
+ *
+ * Measured, for scale: across the fifty-two committed decks there are 1474
+ * parts, 24 of them under `/ppt/media/`, and every part of every deck is
+ * reachable from the package root. On this corpus the two policies are the same
+ * policy. The difference is a promise about the decks we have not seen.
+ */
+type CollectionPolicy =
+/** Only parts this session left unreferenced. The default. */
+'orphaned-here' |
+/** Every unreferenced part in the sweep set, however it got that way. */
+'every-orphan' |
+/** Collect nothing. */
+'none';
+/** `/ppt/media/...` - the default sweep set. */
+declare function isMediaPart(partName: string): boolean;
+interface CollectOptions {
+  /** The package about to be written. */
+  readonly store: PartStore;
+  /** The package as it was opened. Required by `orphaned-here`, ignored otherwise. */
+  readonly baseline?: PartStore | null;
+  /** Defaults to `orphaned-here`. */
+  readonly policy?: CollectionPolicy;
+  /**
+   * Which parts the sweep may touch at all. Defaults to `isMediaPart`.
+   *
+   * Sub-phase 8.7 will pass one of its own, to collect a `ppt/fonts/*.fntdata`
+   * whose typeface no run uses any more - PowerPoint requires every listed
+   * embedded font to be in use. Anything wider than that wants the header above
+   * read first.
+   */
+  readonly sweepable?: (partName: string) => boolean;
+}
+/** An orphan the sweep declined to collect, and why. */
+interface KeptPart {
+  readonly part: string;
+  readonly why: string;
+}
+interface CollectionPlan {
+  /** Parts removed, in the order they were found. */
+  readonly collect: readonly string[];
+  /** Orphans left in place, each with a reason. Empty is the normal case. */
+  readonly kept: readonly KeptPart[];
+  /**
+   * False when the relationship graph could not be walked completely.
+   *
+   * A caller that deletes on the strength of an incomplete walk is deleting on
+   * the strength of a parse error.
+   */
+  readonly safe: boolean;
+  /** Relationship parts that would not parse. Empty when `safe`. */
+  readonly blockedBy: readonly string[];
+}
+/**
+ * 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".
+ */
+declare function planCollection(options: CollectOptions): CollectionPlan;
+/**
+ * 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.
+ */
+declare function collectGarbage(options: CollectOptions): CollectionPlan;
+//#endregion
+//#region src/export/prepare.d.ts
+/**
+ * Work that has to happen at save time, contributed by whoever owns it.
+ *
+ * Several later sub-phases need to touch the package on the way out, and each
+ * of them is somebody else's subject:
+ *
+ * - **8.7, embedded fonts.** Six artifacts that must all be present or
+ *   PowerPoint reports a problem: the `fntdata` parts, the `fntdata` content-type
+ *   `Default`, the font relationships on `presentation.xml`, the
+ *   `p:embeddedFont` entries, their PANOSE and charset attributes, and
+ *   `@embedTrueTypeFonts`. Plus a collection pass, because PowerPoint requires
+ *   every listed typeface to actually be used.
+ * - **3.4, autofit.** A `txBody` whose text changed needs its computed
+ *   `@fontScale` and `@lnSpcReduction` written back - and one whose text did
+ *   not must be left exactly alone, or a view-only deck stops round-tripping.
+ * - **10.8, media.** The `p14:media` and `a:videoFile` relationships are a
+ *   deliberate pair in the file and a duplicate on the way out.
+ *
+ * None of that is the writer's subject. Written inline it would become a list
+ * of special cases in `export.ts` that grows by one every phase, that the
+ * writer's own tests would have to know about, and that could not be tested
+ * without standing up a font stack or a text engine. As hooks, each lands in
+ * the package that owns it, ships with the sub-phase that needs it, and this
+ * package keeps knowing nothing about fonts.
+ *
+ * ## Where they run, and why there
+ *
+ * Before collection and before validation, both deliberately.
+ *
+ * Before collection, because a hook is exactly the thing that changes what is
+ * referenced - 8.7 both adds font parts and drops the ones nothing uses - and a
+ * sweep that ran first would be answering a question about the wrong package.
+ *
+ * Before validation, because a hook writes markup, and markup this session
+ * wrote is precisely what the twenty-nine rules exist to check. A hook that ran
+ * after validation would be the one part of an export nothing checked, which is
+ * the opposite of how it should be: it is newly synthesized markup, the
+ * riskiest kind there is.
+ */
+interface PrepareContext {
+  /** The package being exported. Hooks mutate this. */
+  readonly store: PartStore;
+  /** The package as it was opened, when there is one. Read only; never mutate it. */
+  readonly baseline: PartStore | null;
+  /**
+   * Record something worth reporting.
+   *
+   * Surfaced on `ExportResult.prepared`. A hook that did nothing should say
+   * nothing - the common case for every hook on most exports is silence, and a
+   * note per hook per save would bury the one that mattered.
+   */
+  note(message: string): void;
+}
+interface PrepareHook {
+  /** Short and stable. It appears in `ExportResult` and in the error if this hook throws. */
+  readonly name: string;
+  run(context: PrepareContext): void;
+}
+interface PrepareRecord {
+  readonly hook: string;
+  readonly notes: readonly string[];
+}
+/**
+ * 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.
+ */
+declare function runPrepare(hooks: readonly PrepareHook[], store: PartStore, baseline: PartStore | null): PrepareRecord[];
+//#endregion
+//#region src/export/preserve.d.ts
+/**
+ * The one assertion the writer makes about its own output.
+ *
+ * A part nobody edited must come out with the same bytes it went in with. That
+ * is the first architectural bet stated as a testable sentence, and it is worth
+ * a check of its own even though `V027` is nominally about the same thing,
+ * because the two are looking at different objects.
+ *
+ * `V027` asks the **store**: it compares what the store would hand you for a
+ * part against what the baseline store would hand you, and for an untouched
+ * part both answers come from the same archive. So it can catch a part that was
+ * replaced without being marked edited, and it cannot - even in principle -
+ * catch a writer that re-serialised a clean part on the way out, because by the
+ * time the bytes exist the rule has already run against a store that knows
+ * nothing about them.
+ *
+ * This check reads the archive we actually emitted. It compares the **stored**
+ * bytes, still compressed, against the stored bytes of the source archive:
+ * same DEFLATE stream, same CRC, same declared sizes. Comparing compressed
+ * bytes is both cheaper - nothing is inflated on either side - and stricter,
+ * because two different DEFLATE encodings of identical content would pass an
+ * inflate-and-compare and fail this. Stricter is what is wanted: any difference
+ * at all means something re-compressed, and re-compressing is the failure.
+ *
+ * It needs the bytes the package was opened from. Without them there is nothing
+ * to compare against and the check reports itself as not run, which is not the
+ * same as reporting that it passed.
+ */
+interface PreservationCheck {
+  /** Entries compared and found identical. */
+  readonly checked: number;
+  /** Entries deliberately not compared, because this session wrote them. */
+  readonly rewritten: number;
+  /** Why the check did not run, or `null` when it did. */
+  readonly skipped: string | null;
+}
+/**
+ * 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.
+ */
+declare function assertPreserved(output: Uint8Array, original: Uint8Array | undefined, rewritten: ReadonlySet<string>, zip?: ReadZipOptions): PreservationCheck;
+//#endregion
+//#region src/export/export.d.ts
+/**
+ * Handing the package back.
+ *
+ * Four things happen, in an order that is load-bearing rather than tidy:
+ *
+ * 1. **Prepare hooks**, so that whatever later phases owe the file is in it.
+ * 2. **Collect**, because a hook is the thing most likely to have orphaned
+ *    something.
+ * 3. **Write**, which streams every untouched part still compressed.
+ * 4. **Check**, twice: that nothing we did not edit changed, and that the
+ *    twenty-nine rules pass. Only then do the bytes leave the function.
+ *
+ * The check comes after the write and not before it, which is the one ordering
+ * that might look backwards. It is the right way round because a check that
+ * runs first is checking an intention, and what a user opens is an archive. All
+ * three of `V003`, the duplicate half of `V002`, and the preservation check
+ * below are questions about the emitted container that no amount of inspecting
+ * the store can answer. Bytes are produced, then judged, then either returned
+ * or thrown away - never returned unjudged.
+ */
+interface ExportOptions {
+  /** The package to write, with whatever edits have been made to it. */
+  readonly store: PartStore;
+  /**
+   * The package as it was opened.
+   *
+   * Optional, and the three things it costs to leave out are worth knowing
+   * before deciding to. Without it the three preservation rules are skipped
+   * rather than passed; the media sweep collects nothing, because there is no
+   * way to tell what this session orphaned; and `origin` is unavailable, so
+   * every fatal finding counts as one we introduced. `openPackage` produces a
+   * correct one in a line.
+   */
+  readonly baseline?: PartStore;
+  /** The archive the baseline was opened from. Needed by `V003` and the preservation check. */
+  readonly baselineBytes?: Uint8Array;
+  /** Run in the order given, before everything else. See `prepare.ts`. */
+  readonly prepare?: readonly PrepareHook[];
+  /** Media garbage collection. Defaults to `orphaned-here`. See `collect.ts`. */
+  readonly collect?: CollectionPolicy;
+  /** Which parts the sweep may touch. Defaults to `/ppt/media/`. */
+  readonly sweepable?: (partName: string) => boolean;
+  /**
+   * Set false to write without the firewall.
+   *
+   * There is no legitimate production use. It exists so that a test can build a
+   * deliberately broken package and look at it, and so that `cli bisect` in 1.5
+   * can emit the intermediate packages whose whole purpose is to be rejected.
+   */
+  readonly validate?: boolean;
+  /** A subset of rules to run. Defaults to all twenty-nine. */
+  readonly rules?: readonly RuleId[];
+  /** Set false to skip comparing the output against the source archive. */
+  readonly verifyPreservation?: boolean;
+  /** Passed through to `PartStore.write`. */
+  readonly normalizeEntryOrder?: boolean;
+  /** Passed through to `PartStore.write`. */
+  readonly deflateLevel?: number;
+  /** Passed to `readZip` wherever this package re-opens an archive. */
+  readonly zip?: ReadZipOptions;
+}
+interface ExportResult {
+  /** The package. Only ever returned when every check above passed. */
+  readonly bytes: Uint8Array;
+  /** `null` when validation was turned off. */
+  readonly report: Report | null;
+  /** Hooks that had something to say. Silent hooks are not listed. */
+  readonly prepared: readonly PrepareRecord[];
+  readonly collection: CollectionPlan;
+  /** Parts serialised afresh. Empty on a no-op export - that is the point. */
+  readonly rewritten: readonly string[];
+  /** Parts streamed out of the source archive without being decompressed. */
+  readonly streamed: number;
+  readonly preservation: PreservationCheck;
+}
+/**
+ * A package and the untouched twin every check compares it against.
+ *
+ * Two independent `PartStore.open` calls over the same bytes. Independent
+ * matters: the baseline has to keep answering questions about the file as it
+ * arrived no matter what happens to the other one, and sharing anything mutable
+ * between them would make it a record of the present rather than the past.
+ *
+ * Neither call inflates anything but `[Content_Types].xml`, so the second is
+ * two central-directory parses and a small XML read. They do carry separate
+ * inflation budgets, which means an adversarial archive gets two budgets rather
+ * than one; that is the correct trade at the size these budgets are set to, and
+ * it is written down here so it is a decision rather than an oversight.
+ */
+interface OpenPackage {
+  readonly store: PartStore;
+  readonly baseline: PartStore;
+  readonly baselineBytes: Uint8Array;
+}
+/** Open a package for editing, with the baseline an export will need. */
+declare function openPackage(bytes: Uint8Array, options?: ReadZipOptions): OpenPackage;
+declare function exportPackage(options: ExportOptions): ExportResult;
+//#endregion
+//#region src/oracle/bisect.d.ts
+/**
+ * Narrowing a package PowerPoint refuses down to the change that causes it.
+ *
+ * ## Why this is the debugger for this project
+ *
+ * PowerPoint emits no diagnostic log. A file it will not open produces one
+ * sentence - "PowerPoint found a problem with content in deck.pptx" - naming no
+ * part, no element and no reason, and a file it *repairs* produces a sentence
+ * that does not even say what was repaired. `@pptx-studio/validate` covers the
+ * twenty-nine failures we know how to describe; this covers the rest, which is
+ * the interesting ones. The plan's own caveat: passing the rules is necessary
+ * and not sufficient, because PowerPoint rejects some schema-legal markup for
+ * reasons nobody has written down.
+ *
+ * So the only way to find out what a refusal is about is to ask PowerPoint
+ * again with less of the change present, and keep asking. That is delta
+ * debugging: Zeller and Hildebrandt's `ddmin` over a set of changes
+ * (*Simplifying and Isolating Failure-Inducing Input*, IEEE TSE 2002), applied
+ * level by level down a tree, which is Misherghi and Su's HDD (*HDD:
+ * Hierarchical Delta Debugging*, ICSE 2006).
+ *
+ * ## This is the isolation problem, not the simplification one
+ *
+ * The distinction is Zeller's and it decides the whole design. Simplification
+ * starts from one failing input and cuts it down; it has to guess what a
+ * smaller input looks like, and most of its guesses are not even well formed.
+ * Isolation starts from a **passing** configuration and a **failing** one and
+ * reduces the *difference* between them.
+ *
+ * We are always in the second case. A deck that PowerPoint repairs came from a
+ * deck that it opened, and we have both. So the atoms here are not elements of
+ * the document: they are the **changes** between the two packages, and a
+ * configuration is a subset of them applied to the original. That buys three
+ * things a simplifier cannot have:
+ *
+ *   - Every configuration is well formed by construction. The splice unit is a
+ *     whole node replaced by the whole node the other package has in that
+ *     position, so no configuration can invent unbalanced markup.
+ *   - The empty configuration is known to pass and the full one to fail, which
+ *     is exactly `ddmin`'s precondition - and both are *checked* here rather
+ *     than assumed, because when they do not hold the reason is the most useful
+ *     thing this command can say.
+ *   - The answer is "these two changes, out of ninety-one", which is a sentence
+ *     about your edit rather than about PowerPoint's file format.
+ *
+ * ## Entries, not parts
+ *
+ * The delta is taken over **ZIP entries**, not over `PartStore` parts, and the
+ * difference is not academic: `[Content_Types].xml` is not a part. It is a
+ * package-level stream, `PartStore.partNames` deliberately excludes it, and a
+ * missing `<Default Extension="fntdata"/>` in it is the canonical cause of
+ * "PowerPoint found a problem with content" - the one this project's own plan
+ * cites. A bisector that could only vary parts would be blind to the single
+ * best-documented repair prompt there is.
+ *
+ * Working at the entry level also means nothing has to know what an entry
+ * holds. Anything that parses as XML is descended into - parts, `.rels`,
+ * `docProps` and the content-type stream alike - and anything that does not is
+ * one atom, whether it is a PNG, an OLE2 compound file, or markup too damaged
+ * to read. There is no content-type table to keep in step.
+ */
+interface Span {
+  readonly start: number;
+  readonly end: number;
+}
+type ChangeKind =
+/** The entry exists only in the broken package. */
+'entry-added' |
+/** The entry exists only in the original. */
+'entry-removed' |
+/** A whole entry. Binary, or markup whose two sides do not line up. */
+'entry' |
+/** One element and everything under it. */
+'element' |
+/** One text, CDATA, comment, PI or declaration node. */
+'node' |
+/**
+ * A run of children replaced by another run of a different length.
+ *
+ * What an insertion or a deletion looks like. `was` empty means children were
+ * added; `text` empty means they were taken away.
+ */
+'children' |
+/** One element's start tag: its name, its attributes and their spacing. */
+'tag' |
+/** One attribute, including the whitespace in front of it. */
+'attribute';
+interface Change {
+  readonly id: number;
+  /** ZIP entry name, without a leading slash: `ppt/slides/slide1.xml`. */
+  readonly entry: string;
+  readonly kind: ChangeKind;
+  /**
+   * Where in the entry, for a person to read.
+   *
+   * An XPath-ish path for markup - `/p:sld/p:cSld/p:spTree/p:sp[3]/@name` -
+   * built from qualified names exactly as the file writes them, because a path
+   * that renamed prefixes could not be pasted back into a search.
+   */
+  readonly where: string;
+  /** Distance from the entry, so a report can indent. */
+  readonly depth: number;
+  /** Where this sits in the **original** entry's text. Null for a whole entry. */
+  readonly span: Span | null;
+  /** What the broken package has there. Null when the entry is only original. */
+  readonly text: string | null;
+  /** What the original has there. Null when the entry is only in the broken one. */
+  readonly was: string | null;
+  /**
+   * Finer changes that together reproduce this one exactly.
+   *
+   * The exactness is what makes descending free: the regions between the
+   * children are the regions that compared equal, so applying every child is
+   * the same package as applying the parent. HDD relies on it to move down a
+   * level without spending a run to re-establish that the configuration fails.
+   */
+  readonly children: readonly Change[];
+}
+/** Every change in the forest, parents before children. */
+declare function flattenChanges(changes: readonly Change[]): Change[];
+/** The leaves: the finest changes this delta can express. */
+declare function leafChanges(changes: readonly Change[]): Change[];
+/**
+ * What the oracle says about one candidate package.
+ *
+ * Three values rather than two, and the third is Zeller's. `unresolved` is a
+ * run that answered neither question - PowerPoint timed out, the harness would
+ * not start, a subprocess was killed. Treating it as "passes" would let the
+ * reducer discard the change that matters and then blame an innocent one;
+ * treating it as "fails" would let it keep everything. It is counted and
+ * reported instead, and never reduced towards.
+ */
+type Verdict = 'fails' | 'passes' | 'unresolved';
+/**
+ * Does this package still show the problem?
+ *
+ * Synchronous on purpose. Every oracle we have is either pure computation - the
+ * twenty-nine rules, the round-trip comparison - or a subprocess the caller
+ * blocks on anyway, and `spawnSync` blocks perfectly well. Making the reducer
+ * asynchronous to serve a caller that does not exist would put a Promise in the
+ * middle of a browser package for nothing.
+ */
+type Oracle = (bytes: Uint8Array, label: string) => Verdict;
+interface RunEvent {
+  readonly run: number;
+  readonly applied: number;
+  readonly total: number;
+  readonly label: string;
+}
+interface BisectOptions {
+  readonly oracle: Oracle;
+  /**
+   * Ceiling on oracle runs.
+   *
+   * `ddmin` is quadratic in the worst case and the interesting oracle takes
+   * about a second and a half, so a run against a large delta can take a long
+   * time. When the ceiling is hit the result carries `exhausted: true` and the
+   * smallest failing configuration found so far - never a truncated answer
+   * presented as a minimal one.
+   */
+  readonly maxRuns?: number;
+  /** Called before each oracle run, for a progress line. */
+  readonly onRun?: (run: RunEvent) => void;
+  readonly zip?: ReadZipOptions;
+  /**
+   * Ceiling on the size of the delta tree.
+   *
+   * Two packages that share nothing produce a tree the size of the document.
+   * Past this, subtrees stop being decomposed and stay atomic, which costs
+   * precision and not correctness; `truncated` says when it happened.
+   */
+  readonly maxChanges?: number;
+}
+type BisectOutcome =
+/** A minimal failing set was found. */
+'localized' |
+/** The two packages hold the same entries, byte for byte. */
+'identical' |
+/** The broken package passes the oracle. There is nothing to look for. */
+'broken-passes' |
+/** The original fails too, so the cause is not in the difference. */
+'original-fails';
+interface BisectResult {
+  readonly outcome: BisectOutcome;
+  /** The whole delta, as a forest. One root per differing entry. */
+  readonly changes: readonly Change[];
+  /** The 1-minimal failing subset: drop any one of these and it passes. */
+  readonly minimal: readonly Change[];
+  /** The smallest package still showing the problem. Ready to open, or to keep. */
+  readonly bytes: Uint8Array;
+  /** Oracle runs actually performed. */
+  readonly runs: number;
+  /** Configurations answered from the cache instead of the oracle. */
+  readonly cached: number;
+  /** Runs that answered neither question. */
+  readonly unresolved: number;
+  /** True when `maxRuns` stopped the reduction early. */
+  readonly exhausted: boolean;
+  /** True when `maxChanges` stopped the delta being decomposed further. */
+  readonly truncated: boolean;
+}
+/** The forest of changes between two packages. One root per differing entry. */
+declare function collectDelta(original: ZipArchive, broken: ZipArchive, maxChanges?: number): {
+  changes: Change[];
+  text: Map<string, string>;
+  truncated: boolean;
+};
+declare function bisectPackages(originalBytes: Uint8Array, brokenBytes: Uint8Array, options: BisectOptions): BisectResult;
+/** One line naming a change, without its text. */
+declare function describeChange(change: Change): string;
+/** `2 change(s) in 1 entry(s), from a delta of 91, in 37 oracle run(s)`. */
+declare function summarizeBisect(result: BisectResult): string;
+//#endregion
+//#region src/oracle/roundtrip.d.ts
+/**
+ * Is the deck we wrote the deck we read?
+ *
+ * ## Why this is not a byte comparison
+ *
+ * The plan is explicit that raw ZIP byte equality is the wrong test and says
+ * why in one line: entry order, deflate level, DOS timestamps and attribute
+ * order all legitimately differ, so a byte-equality round-trip test is red on
+ * day one and disabled on day two. A test nobody trusts is worse than no test,
+ * because it also stops anyone writing the one that would have worked.
+ *
+ * `assertPreserved` in this same package *does* compare bytes, and the two are
+ * not in competition. It asks a narrow question - did the entries we said we
+ * would not touch come out with the identical stored bytes - and it is the
+ * right question for a no-op export. This module asks the wide one: for a
+ * package we edited, or one a different producer wrote, do the two archives
+ * hold the same document? That question has to survive an entry moving, a rId
+ * being renumbered, and a `Default` becoming an `Override`, none of which
+ * changes anything a reader can observe.
+ *
+ * ## Three comparisons, because a package has three kinds of content
+ *
+ * **XML parts** compare by canonical form - see `canonicalXml` in
+ * `@pptx-studio/xml` for what it normalises and, more importantly, what it
+ * refuses to. Whitespace and prefixes are meaning, not formatting.
+ *
+ * **Relationship parts** compare as a graph with the ids treated as opaque
+ * labels. Two `.rels` that disagree only about whether the theme is `rId1` or
+ * `rId7` describe the same package, and PowerPoint renumbers on every save, so
+ * a comparator that could not see past that would be useless the first time it
+ * was pointed at a file PowerPoint had written. Ids are matched by what they
+ * point at, and the resulting mapping is then applied to the referring markup:
+ * an `r:embed="rId3"` on one side and `r:embed="rId7"` on the other are the
+ * same reference exactly when rId3 and rId7 resolve to the same part.
+ *
+ * That relabelling is keyed on the **namespace** of the attribute rather than
+ * on a list of names. Every attribute in the relationships namespace is a
+ * relationship reference - `r:id`, `r:embed`, `r:link`, `r:pict`, `r:dm`,
+ * `r:lo`, `r:qs`, `r:cs` - and a list would be a list that is one entry short
+ * the first time we meet a part type nobody thought about.
+ *
+ * **Everything else** compares by SHA-256. The bytes are in hand on both sides
+ * so the digest is not needed to decide equality; it is needed to *report*, and
+ * to give `cli bisect` in 1.5 something to name a part by. CRC-32, which this
+ * package already has for the archive, is a 32-bit error-detecting code and not
+ * evidence that two files are the same.
+ *
+ * ## What it does not compare, and why that is not a hole
+ *
+ * `[Content_Types].xml` is never compared as a document. It is a map, and the
+ * same map has many spellings: a `Default` for an extension and an `Override`
+ * on every part with that extension mean the identical thing, and PowerPoint
+ * chooses between them differently from us. What is compared instead is the
+ * resolved content type of every part, which is the only thing the map is for.
+ */
+type DifferenceKind =
+/** A part is in the original and not in what was written. */
+'part-removed' |
+/** A part is in what was written and not in the original. */
+'part-added' |
+/** Both have the part; the content types disagree. */
+'content-type' |
+/** Both have the part; the canonical XML disagrees. */
+'xml' |
+/** Both have the part; the bytes disagree. */
+'binary' |
+/** The relationship graphs of one source part disagree. */
+'relationship' |
+/** A part could not be read on one side or the other, so nothing can be said. */
+'unreadable';
+interface Difference {
+  readonly kind: DifferenceKind;
+  /** The part it is about. For a relationship difference, the *source* part. */
+  readonly part: string;
+  readonly detail: string;
+}
+type CompareHow = 'xml' | 'binary' | 'relationships';
+interface PartComparison {
+  readonly part: string;
+  readonly how: CompareHow;
+  readonly same: boolean;
+  /**
+   * The digest of the compared form on the original side: the canonical XML for
+   * an XML part, the bytes for anything else, and the relationship graph with
+   * the ids left out for a `.rels`.
+   *
+   * Two parts with the same digest are the same part in the sense this module
+   * means. That is the value worth writing into a report.
+   */
+  readonly digest: string;
+  /** The same digest on the written side. Equal to `digest` whenever `same`. */
+  readonly writtenDigest: string;
+}
+/** One relationship id that means the same thing under a different name. */
+interface Relabelling {
+  /** The part whose `.rels` this is - `/` for the package root. */
+  readonly source: string;
+  readonly from: string;
+  readonly to: string;
+  /** What both ids point at, which is why they are the same label. */
+  readonly target: string;
+}
+interface RoundTripReport {
+  readonly ok: boolean;
+  readonly parts: readonly PartComparison[];
+  readonly differences: readonly Difference[];
+  /**
+   * Ids that moved. Empty for anything this package wrote, and the interesting
+   * field when the comparison is against a file PowerPoint saved.
+   */
+  readonly relabelled: readonly Relabelling[];
+  readonly counts: {
+    readonly xml: number;
+    readonly binary: number;
+    readonly relationships: number;
+    readonly same: number;
+  };
+}
+interface CompareOptions {
+  /** Passed to `parseXml` for both sides. */
+  readonly limits?: XmlParseLimits;
+}
+/**
+ * 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.
+ */
+declare function comparePackages(original: PartStore, written: PartStore, options?: CompareOptions): RoundTripReport;
+/** A one-line summary, for a CLI and for a test failure message. */
+declare function summarizeRoundTrip(report: RoundTripReport): string;
+/**
+ * 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.
+ */
+declare function roundTripPackage(bytes: Uint8Array, options?: RoundTripOptions): RoundTripResult;
+interface RoundTripOptions extends Omit<ExportOptions, 'store' | 'baseline' | 'baselineBytes'>, CompareOptions {}
+interface RoundTripResult {
+  readonly exported: ExportResult;
+  /** The package as re-opened from the bytes that were written. */
+  readonly written: PartStore;
+  readonly comparison: RoundTripReport;
+  readonly ok: boolean;
+}
+//#endregion
+export { type BisectOptions, type BisectOutcome, type BisectResult, type Change, type ChangeKind, type CollectOptions, type CollectionPlan, type CollectionPolicy, type CompareHow, type CompareOptions, type Difference, type DifferenceKind, type ExportOptions, type ExportResult, type KeptPart, type OpenPackage, type Oracle, type PartComparison, type PrepareContext, type PrepareHook, type PrepareRecord, type PreservationCheck, type Reachability, type Relabelling, type RoundTripOptions, type RoundTripReport, type RoundTripResult, type RunEvent, type Span, type Verdict, WRITER_ERROR_CODES, WriterError, type WriterErrorCode, type WriterErrorDetail, assertPreserved, bisectPackages, collectDelta, collectGarbage, comparePackages, describeChange, exportPackage, flattenChanges, isMediaPart, isWriterError, leafChanges, openPackage, orphanedParts, planCollection, reachableParts, roundTripPackage, runPrepare, summarizeBisect, summarizeRoundTrip };
+//# sourceMappingURL=index.d.ts.map