@poe-platform/safe-bash 0.1.806 → 0.1.807

package/dist/safe-bash/command-chunks/chunk-LHDB4QO5.js

@@ -0,0 +1,479 @@
+import {
+  readTextSegments
+} from "./chunk-LWVDJB5S.js";
+import {
+  DocumentArchiveEditor
+} from "./chunk-MAHX3IW3.js";
+import {
+  validateDocxInvocation
+} from "./chunk-DE66JRWJ.js";
+import {
+  LocationIndex,
+  addressKey,
+  documentScopes,
+  pathContains
+} from "./chunk-IR6ZKAUH.js";
+import {
+  readDocumentArchive
+} from "./chunk-GLPIFP7N.js";
+import {
+  UnsupportedEditError
+} from "./chunk-YPVBU7QF.js";
+import {
+  docxOperationSchemas
+} from "./chunk-R4TYL2G6.js";
+import {
+  SelectionError,
+  closedRecord,
+  createGeneratedLocation,
+  decodeLocation,
+  safeOrdinal
+} from "./chunk-LQOKYG3O.js";
+import {
+  InputTypeError,
+  InvalidValueError,
+  ResourceLimitError,
+  archiveSettings,
+  documentSession
+} from "./chunk-IQFRPIXH.js";
+
+// packages/safe-bash-docx-engine/src/simple-selection.ts
+var resourceKinds = {
+  lists: "paragraph",
+  paragraphs: "paragraph",
+  runs: "run",
+  tables: "table",
+  images: "image",
+  headers: "story",
+  footers: "story",
+  comments: "story",
+  text: "paragraph",
+  lorem: "paragraph",
+  shapes: "shape",
+  links: "link",
+  bookmarks: "bookmark",
+  fields: "field",
+  toc: "field",
+  captions: "field"
+};
+function resolveDocxSelection(document, value) {
+  closedRecord(value, ["operation", "inputs", "options", "sources"]);
+  const invocation = validateDocxInvocation({ operation: value.operation, inputs: value.inputs, options: value.options }, docxLocationBudgets.get(document));
+  const { operation, options: options2 } = invocation;
+  const resource = operation.split(".")[0];
+  const inserting = operation.endsWith(".add") && !operation.startsWith("tables.rows.") && !operation.startsWith("tables.columns.");
+  const targetKind = operation === "images.add" ? options2.paragraph !== void 0 ? "paragraph" : "story" : inserting && ["runs", "links", "bookmarks", "comments", "fields", "toc", "captions"].includes(resource) ? "paragraph" : inserting && ["paragraphs", "tables", "lists"].includes(resource) ? "story" : operation === "text.get" && options2.section === void 0 ? "story" : resourceKinds[resource];
+  if (!targetKind || ["control", "revision", "shape", "field", "bookmark"].some((key) => options2[key] !== void 0 && !(key === "shape" && ["text", "shapes"].includes(resource)) && !(key === "bookmark" && ["links", "bookmarks"].includes(resource)) && !(key === "field" && ["fields", "toc", "captions"].includes(resource))) || resource !== "links" && options2.link !== void 0)
+    throw new UnsupportedEditError("This resource selector is not implemented.");
+  const mutable = docxOperationSchemas[operation].mutates;
+  const text = resource === "text" || resource === "lorem";
+  const query = {
+    scope: resource === "headers" || resource === "footers" ? resource : options2.scope ?? "body",
+    ...options2.section !== void 0 ? { section: options2.section } : {},
+    ...resource === "headers" || resource === "footers" ? { variant: options2.variant ?? "default" } : {}
+  };
+  let selected;
+  if (typeof options2.select === "string") {
+    let location = document.resolve(options2.select, resource === "bookmarks" ? inserting ? "paragraph" : "bookmark" : void 0);
+    if (text && location.kind === "shape") location = document.shapeStory(location.token);
+    const acceptable = operation === "images.add" ? ["story", "cell", "paragraph"] : text ? ["story", "paragraph", "run", "table", "cell"] : inserting && ["paragraphs", "tables", "lists"].includes(resource) ? ["story", "cell", "paragraph"] : ["runs.set", "runs.remove"].includes(operation) && location.value.range !== null ? ["run", "paragraph"] : resource === "tables" ? ["table", "cell"] : [targetKind];
+    if (!text && !["runs.set", "runs.remove", "paragraphs.remove", "runs.add", "paragraphs.add", "tables.add", "bookmarks.add", "comments.add"].includes(operation) && location.value.range !== null) throw new InvalidValueError("Whole resource operations require a resource token, not a text range.");
+    if (!acceptable.includes(location.kind)) throw new SelectionError("missing-selection");
+    if ((resource === "headers" || resource === "footers") && !document.list("story", { scope: resource }).some((story) => story.token === location.token))
+      throw new SelectionError("missing-selection");
+    if (operation === "tables.set" && options2.text !== void 0 && location.kind !== "cell")
+      throw new InvalidValueError("Scalar table text requires a logical cell selection.");
+    selected = [location];
+  } else {
+    let owner;
+    const stories = options2.note !== void 0 || options2.comment !== void 0;
+    if (stories) {
+      const scope = options2.comment !== void 0 ? "comments" : options2.scope;
+      if (scope !== "comments" && scope !== "footnotes" && scope !== "endnotes")
+        throw new InvalidValueError("Note selection requires an explicit footnotes or endnotes scope.");
+      owner = document.at("story", options2.comment ?? options2.note, { scope });
+    }
+    for (const kind of ["table", "cell", "paragraph", "run", "image", "shape", "link", "bookmark", "field"]) {
+      if (options2[kind] === void 0 || kind === "bookmark" && resource === "links") continue;
+      if (kind === "cell") owner = document.cell(owner.token, options2.cell);
+      else owner = document.at(kind, options2[kind], owner ? { owner: owner.token } : query);
+    }
+    if (text && owner?.kind === "shape") owner = document.shapeStory(owner.token);
+    if (owner) {
+      if (text || inserting || owner.kind === targetKind || resource === "tables" && owner.kind === "cell") selected = [owner];
+      else selected = document.list(targetKind, { owner: owner.token });
+    } else selected = document.list(targetKind, query);
+  }
+  if (!text) {
+    const local = new Map(selected.map((location) => [location.token, location]));
+    selected = document.select(selected, {
+      ...options2.all !== void 0 ? { all: options2.all } : {},
+      ...mutable && options2.allowEmpty !== void 0 ? { allowEmpty: options2.allowEmpty } : {}
+    }, mutable || operation.endsWith(".get") ? "mutation" : "read").map((location) => local.get(location.token));
+  }
+  const unlinkSection = (resource === "headers" || resource === "footers") && options2.linkToPrevious === false && options2.section !== void 0;
+  if (!text && mutable && options2.shared !== true && !unlinkSection && selected.some((location) => document.references(location.token).length > 1))
+    throw new SelectionError("ambiguous-selection", selected.map((location) => location.token));
+  if (resource === "images" && options2.shared === true) {
+    const expanded = /* @__PURE__ */ new Map();
+    for (const location of selected) for (const occurrence of document.sharedImages(location.token)) expanded.set(occurrence.token, occurrence);
+    selected = [...expanded.values()];
+  }
+  return Object.freeze([...selected]);
+}
+
+// packages/safe-bash-docx-engine/src/locations.ts
+var docxLocationBudgets = /* @__PURE__ */ new WeakMap();
+function options(value, mode) {
+  closedRecord(value, ["first", "all", "occurrence", "allowEmpty"]);
+  for (const key of ["first", "all", "allowEmpty"])
+    if (value[key] !== void 0 && typeof value[key] !== "boolean") throw new InvalidValueError("Expected boolean selection switches.");
+  if (value.occurrence !== void 0) safeOrdinal(value.occurrence);
+  const count = Number(value.first === true) + Number(value.all === true) + Number(value.occurrence !== void 0);
+  if (count > 1 || mode === "text" && count !== 1) throw new InvalidValueError("Expected one explicit match cardinality.");
+  if (mode === "read" && value.allowEmpty !== void 0) throw new InvalidValueError("allowEmpty is a mutation option.");
+}
+async function openDocumentLocations(input, context, mode = "editing") {
+  if (mode !== "editing" && mode !== "inventory") throw new InvalidValueError("Expected an editing or read-only inventory location view.");
+  const settings = archiveSettings(context);
+  const { limits, budget } = settings;
+  if (!(input instanceof Uint8Array)) throw new InputTypeError("Expected archive bytes.");
+  if (input.length > limits.maxArchiveBytes) throw new ResourceLimitError("Document input limit exceeded.");
+  budget.charge("retainedBytes", input.length);
+  budget.charge("work", input.length);
+  const owned = new Uint8Array(input);
+  const archive = await readDocumentArchive(owned, settings);
+  const hash = new Uint8Array(await crypto.subtle.digest("SHA-256", owned));
+  budget.check("work", 0);
+  const sourceSha256 = [...hash].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+  return new DocumentLocations(archive, sourceSha256, settings, mode);
+}
+var DocumentLocations = class {
+  #archive;
+  #index;
+  #generation = 0;
+  #mutating = false;
+  #sourceSha256;
+  #admission;
+  #context;
+  #budget;
+  #inventory;
+  #wholeLocations = /* @__PURE__ */ new WeakMap();
+  #locationBytes = /* @__PURE__ */ new WeakMap();
+  constructor(archive, sourceSha256, context, mode, index) {
+    const settings = archiveSettings(context);
+    this.#context = settings;
+    this.#generation = settings[documentSession]?.generation ?? 0;
+    this.#budget = settings.budget;
+    docxLocationBudgets.set(this, this.#budget);
+    this.#sourceSha256 = sourceSha256;
+    this.#admission = { mainPart: archive.mainPart, dialect: archive.dialect };
+    this.#inventory = mode === "inventory";
+    this.#archive = this.#inventory ? index ? archive : this.#copyArchive(archive) : new DocumentArchiveEditor(archive, {}, void 0, this.#budget).snapshot();
+    this.#index = index ?? new LocationIndex(this.#archive, settings.limits, archive.mainPart, archive.dialect, this.#budget);
+  }
+  get generation() {
+    return this.#generation;
+  }
+  text(options2 = {}) {
+    const selected = resolveDocxSelection(this, { operation: "text.get", inputs: ["document"], options: options2 });
+    const budget = this.#budget.lower(Object.fromEntries((options2.limit ?? []).map((item) => [item.name, item.value])));
+    return readTextSegments(
+      this.#index,
+      selected,
+      options2.view ?? "final",
+      (entry) => this.#location(entry),
+      budget,
+      (location) => this.#locationBytes.get(location)
+    );
+  }
+  #location(entry, range = null) {
+    const cached = range === null ? this.#wholeLocations.get(entry) : void 0;
+    if (cached?.value.generation === this.#generation) {
+      this.#budget.charge("retainedBytes", cached.token.length * 4);
+      this.#budget.charge("work", cached.token.length);
+      return cached;
+    }
+    const value = {
+      version: 1,
+      sourceSha256: this.#sourceSha256,
+      generation: this.#generation,
+      part: entry.part,
+      story: entry.story,
+      path: entry.path,
+      range
+    };
+    const generated = createGeneratedLocation(value), token = generated.token;
+    this.#budget.charge("retainedBytes", token.length * 4);
+    this.#budget.charge("work", token.length);
+    const result = Object.freeze({ kind: entry.kind, token, value: generated.value, positions: Object.freeze({ ...entry.positions }) });
+    this.#budget.charge("retainedBytes", 64);
+    const metadata = new TextEncoder().encode(JSON.stringify({ kind: result.kind, token: "", value: null, positions: result.positions })).length;
+    this.#budget.charge("work", metadata);
+    this.#locationBytes.set(result, metadata + token.length + generated.bytes - 4);
+    if (range === null) {
+      this.#budget.charge("retainedBytes", 64);
+      this.#wholeLocations.set(entry, result);
+    }
+    return result;
+  }
+  #entry(value, kind) {
+    this.#budget.charge("work", value.path.length + 1);
+    if (value.sourceSha256 !== this.#sourceSha256 || value.generation !== this.#generation)
+      throw new SelectionError("stale-selection");
+    const entry = this.#index.byAddress.get(addressKey(value))?.find((entry2) => kind === void 0 || entry2.kind === kind);
+    if (!entry || value.range !== null && !this.#index.validRange(entry, value.range.start, value.range.end))
+      throw new SelectionError("stale-selection");
+    return entry;
+  }
+  resolve(token, kind) {
+    const value = decodeLocation(token);
+    return this.#location(this.#entry(value, kind), value.range);
+  }
+  shapeStory(token) {
+    const value = decodeLocation(token);
+    const shape = this.#entry(value, "shape");
+    if (value.range !== null) throw new InvalidValueError("A shape owner requires a whole occurrence token.");
+    const bodies = this.list("story", { owner: token });
+    if (bodies.length > 1 || !bodies.length && (this.#index.shapeCarriers.get(shape.node)?.refusalReasons.length ?? 0) > 0)
+      throw new UnsupportedEditError("The shape has no unambiguous supported text body.");
+    if (!bodies[0]) throw new SelectionError("missing-selection");
+    return bodies[0];
+  }
+  shapeCarrier(token) {
+    const value = decodeLocation(token);
+    const entry = this.#entry(value, "shape");
+    if (value.range !== null) throw new InvalidValueError("A shape requires a whole occurrence token.");
+    const carrier = this.#index.shapeCarriers.get(entry.node);
+    if (!carrier) throw new SelectionError("missing-selection");
+    return carrier;
+  }
+  *#query(kind, query) {
+    closedRecord(query, ["scope", "owner", "section", "variant"]);
+    if (query.section !== void 0) safeOrdinal(query.section);
+    if (query.variant !== void 0 && !["default", "first", "even"].includes(query.variant))
+      throw new InvalidValueError("Unknown story variant.");
+    if (query.variant !== void 0 && query.scope !== "headers" && query.scope !== "footers")
+      throw new InvalidValueError("Story variants require header or footer scope.");
+    if (query.section !== void 0 && (kind === "part" || query.scope !== void 0 && !["body", "headers", "footers", "all-stories"].includes(query.scope)))
+      throw new InvalidValueError("Section selection requires body, header or footer scope.");
+    if (!["section", "part", "story", "paragraph", "run", "table", "cell", "image", "shape", "link", "bookmark", "field", "annotation", "control"].includes(kind))
+      throw new InvalidValueError("Unknown location kind.");
+    if (query.scope !== void 0 && (!documentScopes.includes(query.scope) || kind === "part"))
+      throw new InvalidValueError("Unknown or inapplicable story scope.");
+    if (query.owner !== void 0 && (query.scope !== void 0 || query.section !== void 0 || query.variant !== void 0)) throw new InvalidValueError("An owner token cannot be combined with scope.");
+    const owner = query.owner === void 0 ? void 0 : decodeLocation(query.owner);
+    let shapeStories;
+    if (owner) {
+      if (owner.range) throw new InvalidValueError("A resource owner cannot be a text range.");
+      const entry = this.#entry(owner);
+      if (kind === "shape" && !["story", "table", "cell", "paragraph", "run"].includes(entry.kind))
+        throw new InvalidValueError("Shape occurrences require an admitted story, table, cell, paragraph or run owner; sections use an explicit numeric query.");
+      if (kind === "story" && entry.kind === "shape") shapeStories = this.#index.shapeBodies.get(entry.node) ?? [];
+      if (kind === "part" || kind === "run" && entry.kind !== "paragraph" || kind === "cell" && entry.kind !== "table" || ["paragraph", "table"].includes(kind) && !["story", "cell"].includes(entry.kind))
+        throw new InvalidValueError("Invalid location owner chain.");
+    }
+    const scope = query.scope ?? "body";
+    const referencedStories = new Set(this.#index.references.filter((ref) => (query.section === void 0 || ref.section === query.section) && (query.variant === void 0 || ref.variant === query.variant)).map((ref) => ref.story));
+    this.#budget.charge("work", this.#index.references.length);
+    let count = 0;
+    const shapeOrdinals = /* @__PURE__ */ new Map();
+    for (const entry of this.#index.entries) {
+      this.#budget.charge("work", 1);
+      if (entry.kind !== kind) continue;
+      if (owner ? entry.part !== owner.part || (shapeStories ? !shapeStories.includes(entry.node) : entry.story !== owner.story || !pathContains(owner.path, entry.path)) : kind !== "part" && scope !== "all-stories" && entry.scope !== scope) continue;
+      if (query.section !== void 0 || query.variant !== void 0) {
+        const storyScoped = entry.scope === "headers" || entry.scope === "footers";
+        if (storyScoped ? !referencedStories.has(entry.story) : query.section !== void 0 && entry.positions.section !== query.section) continue;
+      }
+      const shapeOrdinal = kind === "shape" ? (shapeOrdinals.get(entry.story) ?? 0) + 1 : void 0;
+      if (shapeOrdinal !== void 0) {
+        if (!shapeOrdinals.has(entry.story)) this.#budget.charge("retainedBytes", 32);
+        shapeOrdinals.set(entry.story, shapeOrdinal);
+      }
+      const position = shapeOrdinal !== void 0 ? { shape: shapeOrdinal } : ["paragraph", "run", "table", "image", "link", "bookmark", "field", "control"].includes(kind) ? { [kind]: count + 1 } : {};
+      count++;
+      yield { ...entry, positions: { ...entry.positions, ...position, ...query.section !== void 0 ? { section: query.section } : {} } };
+    }
+  }
+  list(kind, query = {}) {
+    const result = [];
+    for (const entry of this.#query(kind, query)) {
+      this.#budget.check("matches", result.length + 1);
+      result.push(this.#location(entry));
+    }
+    return Object.freeze(result);
+  }
+  at(kind, position, query = {}) {
+    safeOrdinal(position);
+    if (kind === "run" && query.owner === void 0) throw new InvalidValueError("Run positions require a paragraph owner.");
+    const candidates = [];
+    let ordinal = 0;
+    for (const entry of this.#query(kind, query)) {
+      if (kind === "shape" ? entry.positions.shape !== position : ++ordinal !== position) continue;
+      this.#budget.check("matches", candidates.length + 1);
+      candidates.push(this.#location(entry));
+      if (kind !== "shape") return candidates[0];
+    }
+    if (kind === "shape") {
+      if (candidates.length > 1) {
+        this.#budget.charge("diagnosticBytes", candidates.reduce((sum, location) => sum + location.token.length, 0));
+        throw new SelectionError("ambiguous-selection", candidates.map((location) => location.token));
+      }
+      if (!candidates[0]) throw new SelectionError("missing-selection");
+      return candidates[0];
+    }
+    throw new SelectionError("missing-selection");
+  }
+  cell(tableToken, coordinate) {
+    const value = decodeLocation(tableToken);
+    const entry = this.#entry(value, "table");
+    if (value.range !== null) throw new InvalidValueError("A cell owner must be a table.");
+    return this.#location(this.#index.cell(entry, coordinate));
+  }
+  range(token, start, end) {
+    if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 0 || end < start)
+      throw new InvalidValueError("Expected a half-open Unicode scalar range.");
+    const value = decodeLocation(token);
+    const entry = this.#entry(value);
+    if (!this.#index.validRange(entry, start, end)) throw new SelectionError("missing-selection");
+    return this.#location(entry, { start, end });
+  }
+  select(candidates, selection = {}, mode = "read") {
+    if (!["read", "mutation", "text"].includes(mode)) throw new InvalidValueError("Unknown selection mode.");
+    options(selection, mode);
+    if (!Array.isArray(candidates)) throw new InputTypeError("Expected candidate locations.");
+    this.#budget.check("matches", candidates.length);
+    const seen = /* @__PURE__ */ new Set();
+    const resolved = [];
+    for (const candidate of candidates) {
+      if (!candidate || typeof candidate.token !== "string") throw new InputTypeError("Expected a location token.");
+      const item = this.resolve(candidate.token, candidate.kind);
+      if (!seen.has(item.token)) {
+        seen.add(item.token);
+        resolved.push(item);
+      }
+    }
+    if (selection.occurrence !== void 0 && selection.occurrence > resolved.length)
+      throw new SelectionError("missing-selection");
+    if (!resolved.length) {
+      if (mode === "read" || selection.allowEmpty === true) return Object.freeze([]);
+      throw new SelectionError("missing-selection");
+    }
+    if (selection.first) return Object.freeze(resolved.slice(0, 1));
+    if (selection.occurrence !== void 0) return Object.freeze([resolved[selection.occurrence - 1]]);
+    if (selection.all || mode === "read") return Object.freeze(resolved);
+    if (resolved.length > 1) {
+      const tokens = resolved.map((item) => item.token);
+      this.#budget.charge("diagnosticBytes", tokens.reduce((sum, token) => sum + token.length, 0));
+      throw new SelectionError("ambiguous-selection", tokens);
+    }
+    return Object.freeze(resolved);
+  }
+  sharedImages(token) {
+    const entry = this.#entry(decodeLocation(token), "image");
+    const target = this.#index.imageTargets.get(entry.node);
+    if (!target) throw new InvalidValueError("Shared replacement requires an embedded image resource.");
+    const result = [];
+    for (const candidate of this.#index.entries) {
+      this.#budget.charge("work", 1);
+      if (candidate.kind !== "image" || this.#index.imageTargets.get(candidate.node) !== target) continue;
+      this.#budget.check("matches", result.length + 1);
+      result.push(this.#location(candidate));
+    }
+    return Object.freeze(result);
+  }
+  references(token) {
+    const value = decodeLocation(token);
+    this.#entry(value);
+    this.#budget.charge("work", this.#index.references.length);
+    const references = this.#index.references.filter((ref) => ref.part === value.part);
+    this.#budget.check("matches", references.length);
+    return Object.freeze(references);
+  }
+  mutate(candidates, selection, stage) {
+    if (this.#inventory) throw new InvalidValueError("Read-only inventory locations cannot mutate the document.");
+    if (this.#mutating) throw new InvalidValueError("A location mutation is already in progress.");
+    closedRecord(selection, ["first", "all", "occurrence", "allowEmpty", "shared"]);
+    if (selection.shared !== void 0 && typeof selection.shared !== "boolean") throw new InvalidValueError("Expected a boolean shared switch.");
+    const { shared, ...cardinality } = selection;
+    const selected = this.select(candidates, cardinality, "mutation");
+    if (!shared && selected.some((location) => this.references(location.token).length > 1))
+      throw new SelectionError("ambiguous-selection");
+    if (typeof stage !== "function") throw new InputTypeError("Expected an engine staging callback.");
+    if (!selected.length) return Object.freeze({ affected: 0, locations: [], changes: [] });
+    if (this.#generation === Number.MAX_SAFE_INTEGER) throw new ResourceLimitError("Document generation limit exceeded.");
+    this.#budget.charge("batchOperations", 1);
+    this.#mutating = true;
+    try {
+      const editor = new DocumentArchiveEditor(this.#archive, {}, void 0, this.#budget);
+      const updates = stage(editor, selected);
+      if (!Array.isArray(updates)) throw new InvalidValueError("Staging must return synchronous location updates.");
+      this.#budget.check("matches", updates.length);
+      const beforeByToken = new Map(selected.map((location) => [location.token, location]));
+      const changed = /* @__PURE__ */ new Set();
+      for (const update of updates) {
+        closedRecord(update, ["before", "after"]);
+        if (typeof update.before !== "string" || !beforeByToken.has(update.before) || changed.has(update.before))
+          throw new InvalidValueError("Mutation updates must refer to distinct selected locations.");
+        changed.add(update.before);
+      }
+      const candidate = editor.snapshot();
+      let dirty = false;
+      for (let i = 0; i < candidate.members.length; i++) {
+        const before = this.#archive.members[i].bytes;
+        const after = candidate.members[i].bytes;
+        this.#budget.charge("work", Math.max(before.length, after.length));
+        if (before.length !== after.length || before.some((byte, i2) => byte !== after[i2])) dirty = true;
+      }
+      if (!dirty) {
+        if (updates.length) throw new InvalidValueError("An unchanged mutation cannot report changed locations.");
+        return Object.freeze({ affected: 0, locations: [], changes: [] });
+      }
+      if (!updates.length) throw new InvalidValueError("Changed documents require location update receipts.");
+      const next = new LocationIndex(candidate, this.#context.limits, this.#admission.mainPart, this.#admission.dialect, this.#budget);
+      const previous = this.#index;
+      this.#index = next;
+      this.#generation++;
+      try {
+        const changes = updates.map((update) => {
+          const before = beforeByToken.get(update.before);
+          let after = null;
+          if (update.after === null && before.value.range === null && next.byAddress.get(addressKey(before.value))?.some((entry) => entry.kind === before.kind))
+            throw new InvalidValueError("A surviving location cannot be reported as deleted.");
+          if (update.after !== null) {
+            const value = createGeneratedLocation({ ...update.after, version: 1, sourceSha256: this.#sourceSha256, generation: this.#generation }).value;
+            after = this.#location(this.#entry(value, before.kind), value.range);
+          }
+          return Object.freeze({ before, after });
+        });
+        const locations = changes.flatMap((change) => change.after ? [change.after] : []);
+        const result = Object.freeze({ affected: changes.length, locations: Object.freeze(locations), changes: Object.freeze(changes) });
+        this.#archive = candidate;
+        return result;
+      } catch (error) {
+        this.#index = previous;
+        this.#generation--;
+        throw error;
+      }
+    } finally {
+      this.#mutating = false;
+    }
+  }
+  snapshot() {
+    return this.#copyArchive(this.#archive);
+  }
+  #copyArchive(archive) {
+    const bytes = archive.comment.length + archive.members.reduce((total, member) => total + member.bytes.length, 0);
+    this.#budget.charge("retainedBytes", bytes + archive.members.length * 96);
+    this.#budget.charge("work", bytes + archive.members.length);
+    return { comment: new Uint8Array(archive.comment), members: archive.members.map((member) => ({ ...member, bytes: new Uint8Array(member.bytes), modified: new Date(member.modified.getTime()) })) };
+  }
+};
+
+export {
+  resolveDocxSelection,
+  docxLocationBudgets,
+  openDocumentLocations,
+  DocumentLocations
+};