@poe-platform/safe-bash 0.1.806 → 0.1.807

package/dist/safe-bash/command-chunks/chunk-2B6XWO6A.js

@@ -0,0 +1,730 @@
+import {
+  assertOutsideFields,
+  parseFields
+} from "./chunk-6EHVFKM7.js";
+import {
+  openDocumentLocations
+} from "./chunk-LHDB4QO5.js";
+import {
+  DocumentArchiveEditor
+} from "./chunk-MAHX3IW3.js";
+import {
+  validateDocxInvocation
+} from "./chunk-DE66JRWJ.js";
+import {
+  pathContains
+} from "./chunk-IR6ZKAUH.js";
+import {
+  assertDocumentEditable,
+  publishDocumentArchive
+} from "./chunk-HPKUFWHW.js";
+import {
+  DocumentPackage
+} from "./chunk-GLPIFP7N.js";
+import {
+  UnsupportedEditError,
+  activeXmlChildren,
+  assertOutsideRevisionRanges,
+  containsRevision,
+  nativeElementSourceTokens,
+  nativeScalarTextSource,
+  nativeXmlTriviaSource,
+  xmlValue
+} from "./chunk-YPVBU7QF.js";
+import {
+  parseStoredDateTime,
+  storedBooleanValue
+} from "./chunk-VEUQWV2V.js";
+import {
+  SelectionError,
+  closedRecord,
+  encodeGeneratedLocation
+} from "./chunk-LQOKYG3O.js";
+import {
+  relativePartTarget
+} from "./chunk-WAKYUXVQ.js";
+import {
+  InvalidValueError,
+  archiveSettings
+} from "./chunk-IQFRPIXH.js";
+import {
+  crc32
+} from "./chunk-XIC45QAG.js";
+import {
+  createCompressionCodec
+} from "./chunk-GEDRBQGT.js";
+
+// packages/safe-bash-docx-engine/src/control-picture.ts
+function unsupported(message = "The picture control has no verified occurrence structure.") {
+  throw new UnsupportedEditError(message);
+}
+function u32(bytes, offset) {
+  return new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(offset);
+}
+function adler(bytes) {
+  let a = 1, b = 0;
+  for (const byte of bytes) {
+    a = (a + byte) % 65521;
+    b = (b + a) % 65521;
+  }
+  return (b << 16 | a) >>> 0;
+}
+async function admitControlPng(input, context, profile = "picture-control") {
+  const { limits, signal, budget } = archiveSettings(context);
+  if (!(input instanceof Uint8Array) || input.length > limits.maxEntryBytes) throw new InvalidValueError("Expected bounded PNG bytes.");
+  budget.charge("work", input.length);
+  budget.charge("retainedBytes", input.length);
+  const bytes = new Uint8Array(input);
+  if (bytes.length < 57 || ![137, 80, 78, 71, 13, 10, 26, 10].every((byte, i) => bytes[i] === byte)) unsupported("Expected an admitted PNG picture.");
+  let offset = 8, width = 0, height = 0, channels = 0, depth = 0, interlace = 0, ended = false, sawData = false, closedData = false, sawPalette = false;
+  const data = [];
+  let compressedLength = 0;
+  while (offset < bytes.length) {
+    budget.charge("work", 1);
+    if (offset + 12 > bytes.length) unsupported("Truncated PNG chunk.");
+    const length = u32(bytes, offset);
+    if (length > bytes.length - offset - 12) unsupported("Invalid PNG chunk length.");
+    const type = String.fromCharCode(...bytes.subarray(offset + 4, offset + 8));
+    if ([...type].some((c) => !(c >= "A" && c <= "Z") && !(c >= "a" && c <= "z")) || type[2] >= "a" || crc32(bytes.subarray(offset + 4, offset + 8 + length)) !== u32(bytes, offset + 8 + length)) unsupported("Invalid PNG chunk type or checksum.");
+    const payload2 = bytes.subarray(offset + 8, offset + 8 + length);
+    if (type === "IHDR") {
+      if (offset !== 8 || length !== 13) unsupported("Invalid PNG header order.");
+      width = u32(payload2, 0);
+      height = u32(payload2, 4);
+      depth = payload2[8];
+      interlace = payload2[12];
+      const color = payload2[9], depths = { 0: [1, 2, 4, 8, 16], 2: [8, 16], 3: [1, 2, 4, 8], 4: [8, 16], 6: [8, 16] };
+      channels = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 }[color] ?? 0;
+      if (!width || !height || !depths[color]?.includes(depth) || payload2[10] !== 0 || payload2[11] !== 0 || ![0, 1].includes(interlace) || profile === "picture-control" && (depth !== 8 || ![2, 6].includes(color) || interlace !== 0)) unsupported("Unsupported PNG pixel profile.");
+    } else if (!width) unsupported("Missing PNG header.");
+    else if (type === "IDAT") {
+      if (closedData) unsupported("PNG data chunks must be contiguous.");
+      data.push(payload2);
+      compressedLength += payload2.length;
+      sawData = true;
+    } else if (type === "IEND") {
+      if (length !== 0 || !sawData || offset + 12 !== bytes.length) unsupported("Invalid PNG end marker.");
+      ended = true;
+    } else {
+      if (sawData) closedData = true;
+      if (type[0] >= "A" && type[0] <= "Z" && type !== "PLTE") unsupported("Unsupported PNG critical chunk.");
+      if (type === "PLTE") {
+        if (sawPalette || sawData || length === 0 || length > 768 || length % 3 !== 0) unsupported("Invalid PNG palette.");
+        sawPalette = true;
+      }
+    }
+    offset += length + 12;
+  }
+  if (!ended || compressedLength < 6) unsupported("Incomplete PNG payload.");
+  const passes = interlace ? [[0, 0, 8, 8], [4, 0, 8, 8], [0, 4, 4, 8], [2, 0, 4, 4], [0, 2, 2, 4], [1, 0, 2, 2], [0, 1, 1, 2]] : [[0, 0, 1, 1]];
+  const scanlines = passes.map(([x, y, dx, dy]) => {
+    const columns = Math.max(0, Math.ceil((width - x) / dx)), rows = Math.max(0, Math.ceil((height - y) / dy));
+    return { rows: columns ? rows : 0, stride: 1 + Math.ceil(columns * channels * depth / 8) };
+  });
+  const expected = scanlines.reduce((total, pass) => total + pass.rows * pass.stride, 0);
+  if (!Number.isSafeInteger(expected) || expected > limits.maxEntryBytes) unsupported("PNG expanded pixel limit exceeded.");
+  budget.check("expandedPackage", expected);
+  budget.charge("retainedBytes", compressedLength + expected);
+  budget.charge("work", expected);
+  const compressed = new Uint8Array(compressedLength);
+  offset = 0;
+  for (const chunk of data) {
+    compressed.set(chunk, offset);
+    offset += chunk.length;
+  }
+  if ((compressed[0] & 15) !== 8 || compressed[0] >> 4 > 7 || (compressed[0] * 256 + compressed[1]) % 31 !== 0 || compressed[1] & 32) unsupported("Invalid PNG zlib header.");
+  const payload = compressed.subarray(2, -4);
+  const codec = createCompressionCodec();
+  const reader = new codec.CodecReader({ async *[Symbol.asyncIterator]() {
+    yield payload;
+  } }, signal);
+  const raw = new Uint8Array(expected);
+  offset = 0;
+  try {
+    for await (const chunk of codec.codec(reader, { mode: "inflate-raw", chunkSize: limits.chunkSize }, signal)) {
+      budget.check("work", 0);
+      if (chunk.length > expected - offset) unsupported("PNG expanded pixel length exceeded.");
+      raw.set(chunk, offset);
+      offset += chunk.length;
+    }
+    if (await reader.chunk() !== void 0) unsupported("Trailing PNG compressed pixel data.");
+  } catch (error) {
+    budget.check("work", 0);
+    if (error instanceof UnsupportedEditError) throw error;
+    unsupported("Invalid PNG compressed pixels.");
+  } finally {
+    await reader.close();
+  }
+  if (offset !== expected || adler(raw) !== u32(compressed, compressed.length - 4)) unsupported("PNG pixel length or checksum mismatch.");
+  offset = 0;
+  for (const pass of scanlines) for (let row = 0; row < pass.rows; row++) {
+    if (raw[offset] > 4) unsupported("Invalid PNG row filter.");
+    offset += pass.stride;
+  }
+  return bytes;
+}
+async function acquireControlPng(input, context) {
+  const { limits, signal, budget } = archiveSettings(context);
+  let bytes;
+  const maxBytes = Math.min(limits.maxEntryBytes, budget.limits.embeddedMediaBytes - budget.usage.embeddedMediaBytes);
+  if (input.kind === "bytes") {
+    const base64 = input.base64;
+    if (typeof base64 !== "string" || base64.length > Math.ceil(limits.maxEntryBytes / 3) * 4 || base64.length % 4 !== 0 || [...base64].some((c) => !"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=".includes(c))) throw new InvalidValueError("Expected bounded canonical base64 picture.");
+    const padding = base64.endsWith("==") ? 2 : base64.endsWith("=") ? 1 : 0, length = base64.length / 4 * 3 - padding;
+    if (length > limits.maxEntryBytes) throw new InvalidValueError("Picture input exceeds the entry limit.");
+    budget.check("embeddedMediaBytes", budget.usage.embeddedMediaBytes + length);
+    budget.charge("retainedBytes", length * 3);
+    budget.charge("work", base64.length);
+    let binary;
+    try {
+      binary = atob(base64);
+      if (btoa(binary) !== base64) throw new Error();
+    } catch {
+      throw new InvalidValueError("Expected canonical base64 picture.");
+    }
+    bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0));
+  } else if (input.kind === "vfs") {
+    const resolver = context.binaryResolver;
+    if (!resolver || resolver.capability !== input.capability) unsupported("Picture VFS input requires a matching explicit capability.");
+    if (maxBytes === 0) budget.check("embeddedMediaBytes", budget.usage.embeddedMediaBytes + 1);
+    const source = await resolver.open(input.path, { signal, maxBytes });
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of source) {
+      budget.check("work", 0);
+      if (!(chunk instanceof Uint8Array)) throw new InvalidValueError("Expected picture byte fragments.");
+      total += chunk.length;
+      if (total > limits.maxEntryBytes) unsupported("Picture input exceeds the entry limit.");
+      budget.check("embeddedMediaBytes", budget.usage.embeddedMediaBytes + total);
+      budget.charge("retainedBytes", chunk.length ? chunk.length + 64 : 0);
+      budget.charge("work", chunk.length + 1);
+      if (chunk.length) chunks.push(new Uint8Array(chunk));
+    }
+    budget.check("work", 0);
+    budget.charge("retainedBytes", total);
+    bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+      bytes.set(chunk, offset);
+      offset += chunk.length;
+    }
+  } else throw new InvalidValueError("Expected explicit picture binary input.");
+  budget.charge("embeddedMediaBytes", bytes.length);
+  return admitControlPng(bytes, { limits, signal, budget });
+}
+function occurrence(content, budget) {
+  let drawing, blip;
+  let drawings = 0, blips = 0, forbidden = false;
+  const chain = [];
+  budget.charge("retainedBytes", 32);
+  const stack = [{ node: content, next: 0 }];
+  while (stack.length) {
+    const frame = stack[stack.length - 1], node2 = frame.node;
+    if (frame.next === 0) {
+      budget.charge("work", 1);
+      if (node2.namespace === content.namespace && node2.localName === "drawing") {
+        drawings++;
+        drawing = node2;
+      }
+      if (["http://schemas.openxmlformats.org/drawingml/2006/main", "http://purl.oclc.org/ooxml/drawingml/main"].includes(node2.namespace) && node2.localName === "blip") {
+        blips++;
+        if (blips === 1) {
+          blip = node2;
+          budget.charge("retainedBytes", Math.min(7, stack.length) * 8);
+          for (let i = Math.max(0, stack.length - 7); i < stack.length; i++) chain.push(stack[i].node);
+        }
+      }
+      if (["AlternateContent", "imagedata", "object", "pict"].includes(node2.localName)) forbidden = true;
+    }
+    if (frame.next < node2.children.length) {
+      budget.charge("retainedBytes", 32);
+      stack.push({ node: node2.children[frame.next++], next: 0 });
+    } else stack.pop();
+  }
+  if (drawings !== 1 || blips !== 1 || forbidden) unsupported();
+  const node = blip;
+  budget.charge("work", node.attributes.length);
+  budget.charge("retainedBytes", node.attributes.length * 8);
+  const embeds = node.attributes.filter((attribute) => ["http://schemas.openxmlformats.org/officeDocument/2006/relationships", "http://purl.oclc.org/ooxml/officeDocument/relationships"].includes(attribute.namespace) && attribute.localName === "embed");
+  if (chain.length !== 7 || chain[0] !== drawing || !["inline", "anchor"].includes(chain[1].localName) || !["http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing", "http://purl.oclc.org/ooxml/drawingml/wordprocessingDrawing"].includes(chain[1].namespace) || chain[2].namespace !== node.namespace || chain[2].localName !== "graphic" || chain[3].namespace !== node.namespace || chain[3].localName !== "graphicData" || !["http://schemas.openxmlformats.org/drawingml/2006/picture", "http://purl.oclc.org/ooxml/drawingml/picture"].includes(chain[4].namespace) || chain[4].localName !== "pic" || chain[5].namespace !== chain[4].namespace || chain[5].localName !== "blipFill" || chain[3].attributes.find((attribute) => attribute.localName === "uri" && attribute.namespace === "")?.value !== chain[4].namespace || ["extent", "docPr"].some((name) => chain[1].children.filter((child) => child.namespace === chain[1].namespace && child.localName === name).length !== 1)) unsupported();
+  if (embeds.length !== 1 || node.children.length || node.attributes.some((attribute) => attribute.localName === "link")) unsupported();
+  return { node, id: embeds[0].value, namespace: embeds[0].namespace };
+}
+function readControlPicture(archive, owner, content, context) {
+  const { limits, budget } = archiveSettings(context);
+  const target = occurrence(content, budget);
+  const pkg = new DocumentPackage(archive, limits, budget);
+  const edge = pkg.relationships(owner).find((edge2) => edge2.rId === target.id);
+  if (!edge || !edge.reltype.endsWith("/image")) unsupported();
+  return { relationshipId: edge.rId, target: edge.is_external ? edge.target_ref : edge.target_part.partname, external: edge.is_external, contentType: edge.is_external ? null : edge.target_part.content_type };
+}
+var staged = /* @__PURE__ */ new WeakMap();
+function replaceControlPicture(editor, archive, owner, content, bytes, context) {
+  const { limits, budget } = archiveSettings(context);
+  const pkg = new DocumentPackage(archive, limits, budget);
+  const target = occurrence(content, budget);
+  const edge = pkg.relationships(owner).find((edge2) => edge2.rId === target.id);
+  if (!edge || edge.is_external || !edge.reltype.endsWith("/image") || !edge.target_part.content_type.toLowerCase().startsWith("image/")) unsupported();
+  const additions = staged.get(editor) ?? [];
+  let ordinal = 1;
+  let media;
+  do {
+    media = `/word/media/control-picture-${ordinal++}.png`;
+  } while (pkg.parts.some((part) => part.partname === media) || additions.some((item) => item.media === media));
+  const taken = /* @__PURE__ */ new Set([...pkg.relationships(owner).map((edge2) => edge2.rId), ...additions.filter((item) => item.owner === owner).map((item) => item.id)]);
+  ordinal = 1;
+  while (taken.has(`rId${ordinal}`)) ordinal++;
+  const id = `rId${ordinal}`;
+  editor.xml(owner.slice(1)).setAttribute(target.node, { namespace: target.namespace, localName: "embed" }, id);
+  additions.push({ owner, id, media, bytes, reltype: edge.reltype });
+  staged.set(editor, additions);
+}
+function finishControlPictures(editor, archive, context) {
+  const additions = staged.get(editor) ?? [];
+  if (!additions.length) return editor.snapshot();
+  const { budget } = archiveSettings(context);
+  for (const owner of new Set(additions.map((item) => item.owner))) {
+    const slash = owner.lastIndexOf("/");
+    const relname = owner.slice(1, slash + 1) + "_rels/" + owner.slice(slash + 1) + ".rels";
+    const xml = editor.xml(relname);
+    const prefix2 = xml.root.name.includes(":") ? xml.root.name.slice(0, xml.root.name.indexOf(":") + 1) : "";
+    for (const item of additions.filter((item2) => item2.owner === owner)) xml.insertChildren(xml.root, `<${prefix2}Relationship Id="${item.id}" Type="${xmlValue(item.reltype)}" Target="${xmlValue(relativePartTarget(owner, item.media))}"/>`);
+  }
+  const types = editor.xml("[Content_Types].xml");
+  const prefix = types.root.name.includes(":") ? types.root.name.slice(0, types.root.name.indexOf(":") + 1) : "";
+  for (const item of additions) types.insertChildren(types.root, `<${prefix}Override PartName="${item.media}" ContentType="image/png"/>`);
+  budget.charge("retainedBytes", additions.reduce((n, item) => n + item.bytes.length, 0));
+  const dirty = new Set(editor.dirtyParts);
+  return { comment: new Uint8Array(archive.comment), members: [
+    ...archive.members.map((member) => ({ ...member, bytes: dirty.has(member.name) ? editor.xml(member.name).serialize() : new Uint8Array(member.bytes), modified: new Date(member.modified) })),
+    ...additions.map((item) => ({ name: item.media.slice(1), bytes: new Uint8Array(item.bytes), directory: false, modified: new Date(archive.members[0].modified) }))
+  ] };
+}
+
+// packages/safe-bash-docx-engine/src/controls.ts
+var w14 = "http://schemas.microsoft.com/office/word/2010/wordml";
+var w15 = "http://schemas.microsoft.com/office/word/2012/wordml";
+function attr(node, name, namespace = node?.namespace) {
+  return node?.attributes.find((attribute) => attribute.namespace === namespace && attribute.localName === name)?.value ?? null;
+}
+function controlChildren(xml, budget) {
+  const all = activeXmlChildren(xml, budget);
+  return { all, one(node, name, namespace = node.namespace) {
+    const result = all(node).filter((element) => element.namespace === namespace && element.localName === name);
+    if (result.length > 1) throw new UnsupportedEditError("Repeated control properties are unsupported.");
+    return result[0];
+  } };
+}
+function walk(node, budget) {
+  budget.charge("retainedBytes", 192);
+  const result = [], pending = [node];
+  while (pending.length) {
+    const current = pending.pop();
+    budget.charge("work", 1);
+    budget.charge("retainedBytes", 8);
+    result.push(current);
+    budget.charge("retainedBytes", current.children.length * 8);
+    for (let index = current.children.length - 1; index >= 0; index--) pending.push(current.children[index]);
+  }
+  return result;
+}
+function owners(root, path) {
+  const result = [root];
+  for (const index of path) result.push(result.at(-1).children[index]);
+  return result;
+}
+function logicalText(content, children, budget) {
+  budget.charge("retainedBytes", 192);
+  const pending = [content], chunks = [];
+  let length = 0;
+  while (pending.length) {
+    const node = pending.pop();
+    const text = typeof node === "string" ? node : node.namespace !== content.namespace ? void 0 : node.localName === "t" ? node.text : node.localName === "tab" ? "	" : ["br", "cr"].includes(node.localName) ? "\n" : void 0;
+    if (text !== void 0) {
+      budget.charge("work", text.length);
+      budget.charge("retainedBytes", 8);
+      chunks.push(text);
+      length += text.length;
+      continue;
+    }
+    const nested = children(node);
+    const separated = node.localName === "sdtContent" && nested.every((n) => n.localName === "p");
+    budget.charge("retainedBytes", nested.length * (separated ? 16 : 8));
+    for (let index = nested.length - 1; index >= 0; index--) {
+      pending.push(nested[index]);
+      if (separated && index > 0) pending.push("\n");
+    }
+  }
+  budget.charge("retainedBytes", length * 2);
+  return chunks.join("");
+}
+function inspectControlSnapshot(node, location, archive, context, xml) {
+  const budget = archiveSettings(context).budget;
+  const { one: child, all: children } = controlChildren(xml, budget);
+  let kind = "unsupported", value = null, reason = null;
+  let properties, content;
+  const choices = [];
+  try {
+    properties = child(node, "sdtPr");
+    content = child(node, "sdtContent");
+    if (!properties || !content) throw new UnsupportedEditError("A control requires one properties and content owner.");
+    if (children(properties).some((owner) => owner.namespace === node.namespace && ["docPartObj", "docPartList", "citation", "bibliography", "equation", "group"].includes(owner.localName) || owner.namespace === w14 && ["repeatingSection", "repeatingSectionItem"].includes(owner.localName))) throw new UnsupportedEditError("This stored control type has no verified scalar semantics.");
+    const kinds = children(properties).filter((n) => n.namespace === node.namespace && ["text", "richText", "dropDownList", "comboBox", "date", "picture"].includes(n.localName) || n.namespace === w14 && n.localName === "checkbox" || n.namespace === w15 && ["repeatingSection", "repeatingSectionItem"].includes(n.localName));
+    if (kinds.length > 1) throw new UnsupportedEditError("Conflicting control types are unsupported.");
+    const type = kinds[0];
+    const names = { text: "plain-text", checkbox: "checkbox", dropDownList: "dropdown", comboBox: "combo-box", date: "date", picture: "picture", richText: "rich-text", repeatingSection: "repeating-section", repeatingSectionItem: "repeating-item" };
+    kind = type ? names[type.localName] : "rich-text";
+    value = logicalText(content, children, budget);
+    if (["repeating-section", "repeating-item"].includes(kind)) value = null;
+    if (kind === "checkbox") {
+      value = null;
+      const checked = attr(child(type, "checked", w14), "val", w14);
+      if (!["0", "1", "true", "false"].includes(checked ?? "")) throw new UnsupportedEditError("Malformed checkbox state.");
+      value = checked === "1" || checked === "true";
+    }
+    if (kind === "dropdown" || kind === "combo-box") {
+      for (const item of children(type)) {
+        if (item.namespace !== node.namespace || item.localName !== "listItem") throw new UnsupportedEditError("Unsupported choice declaration.");
+        const stored = attr(item, "value"), label = attr(item, "displayText");
+        if (stored === null || label === null || choices.some((choice) => choice.value === stored)) throw new UnsupportedEditError("Choice values must be distinct declared values.");
+        choices.push({ value: stored, label });
+      }
+    }
+    if (kind === "date") value = attr(type, "fullDate");
+    if (kind === "picture") {
+      value = null;
+      value = readControlPicture(archive, location.value.part, content, context);
+    }
+  } catch (error) {
+    if (!(error instanceof UnsupportedEditError)) throw error;
+    reason = error.message;
+  }
+  const metadata = { id: null, tag: null, alias: null, lock: "unknown" };
+  let placeholder = false, binding = null;
+  if (properties) for (const field of ["id", "tag", "alias", "lock", "dataBinding", "showingPlcHdr"]) {
+    try {
+      const descriptor = child(properties, field);
+      if (field === "dataBinding") {
+        if (descriptor) binding = { storeItemId: attr(descriptor, "storeItemID"), xpath: attr(descriptor, "xpath"), prefixMappings: attr(descriptor, "prefixMappings") };
+      } else if (field === "showingPlcHdr") {
+        const stored = attr(descriptor, "val"), state = descriptor ? stored === null ? true : storedBooleanValue(stored) : false;
+        if (state === null) throw new UnsupportedEditError("Malformed control placeholder state.");
+        placeholder = state;
+      } else if (field === "lock") metadata.lock = attr(descriptor, "val") ?? "unlocked";
+      else metadata[field] = attr(descriptor, "val");
+    } catch (error) {
+      if (!(error instanceof UnsupportedEditError)) throw error;
+      reason ??= error.message;
+    }
+  }
+  return {
+    location,
+    kind,
+    ...metadata,
+    placeholder,
+    binding,
+    value,
+    choices,
+    support: reason === null ? "supported" : "unsupported",
+    reason
+  };
+}
+async function openControlInventory(input, options, context) {
+  const settings = archiveSettings(context);
+  const document = await openDocumentLocations(input, settings);
+  const archive = document.snapshot();
+  const query = { ...options.scope ? { scope: options.scope } : {}, ...options.section ? { section: options.section } : {} };
+  let owner = options.select ? document.resolve(options.select) : void 0;
+  if (owner?.value.range) throw new UnsupportedEditError("Control selection requires a whole owner.");
+  if (options.comment !== void 0 || options.note !== void 0) owner = document.at("story", options.comment ?? options.note, { scope: options.comment !== void 0 ? "comments" : options.scope });
+  for (const kind of ["table", "cell", "paragraph", "run", "image", "link", "bookmark", "field"]) if (options[kind] !== void 0) {
+    if (kind === "cell") owner = document.cell(owner.token, options.cell);
+    else owner = document.at(kind, options[kind], owner ? { owner: owner.token } : query);
+  }
+  let selected = document.list("control", owner ? { owner: owner.token } : query);
+  if (options.control !== void 0) {
+    const item = selected[options.control - 1];
+    if (!item) throw new SelectionError("missing-selection");
+    selected = [item];
+  }
+  if (options.select && !selected.length) throw new SelectionError("missing-selection");
+  const editor = new DocumentArchiveEditor(archive, {}, void 0, settings.budget);
+  return { document, archive, editor, items: selected.map((location) => {
+    const xml = editor.xml(location.value.part.slice(1));
+    return inspectControlSnapshot(owners(xml.root, location.value.path).at(-1), location, archive, settings, xml);
+  }) };
+}
+async function inspectDocumentControls(input, options = {}, context) {
+  const settings = archiveSettings(context);
+  const invocation = validateDocxInvocation({ operation: "controls.list", inputs: ["document"], options }, settings.budget);
+  const opts = invocation.options;
+  const budget = settings.budget.lower(Object.fromEntries((opts.limit ?? []).map((item) => [item.name, item.value])));
+  const result = await openControlInventory(input, opts, { ...settings, budget });
+  return { items: result.items };
+}
+function opening(node) {
+  return `<${node.name}${node.attributes.map((a) => ` ${a.name}="${xmlValue(a.value)}"`).join("")}>`;
+}
+function retainedControlTrivia(xml, node, budget) {
+  budget.charge("retainedBytes", 192);
+  const pending = [node], chunks = [];
+  while (pending.length) {
+    const token = pending.pop();
+    budget.charge("work", 1);
+    if (token.kind === "element") {
+      budget.charge("retainedBytes", token.content.length * 8);
+      for (let index = token.content.length - 1; index >= 0; index--) pending.push(token.content[index]);
+    } else if (token.kind === "comment" || token.kind === "processing-instruction") {
+      budget.charge("retainedBytes", 8);
+      chunks.push(xml[nativeXmlTriviaSource](token));
+    }
+  }
+  return chunks.join("");
+}
+function textReplacement(xml, content, text, budget, font) {
+  const { one: child } = controlChildren(xml, budget);
+  const w = content.namespace;
+  const nodes = walk(content, budget);
+  if (nodes.some((node) => node.namespace !== w || !["sdtContent", "p", "pPr", "r", "rPr", "t", "tab", "br", "cr"].includes(node.localName) && !nodes.some((owner) => ["pPr", "rPr"].includes(owner.localName) && walk(owner, budget).includes(node)))) throw new UnsupportedEditError("Only ordinary text containers support scalar filling.");
+  if (content.children.some((n) => !["r", "p"].includes(n.localName)) || content.children.some((n) => n.localName === "p") && content.children.some((n) => n.localName !== "p")) throw new UnsupportedEditError("Mixed text containers are unsupported.");
+  const first = nodes.find((n) => n.namespace === w && n.localName === "r");
+  const prefix = content.name.includes(":") ? content.name.slice(0, content.name.indexOf(":") + 1) : "";
+  const name = (local) => prefix + local;
+  const properties = first && child(first, "rPr");
+  let propertyXml = properties ? xml.sourceXml(properties) : "";
+  if (font) {
+    const fonts = properties && child(properties, "rFonts");
+    const fontName = fonts?.name ?? name("rFonts");
+    const retained = fonts?.attributes.filter((attribute) => attribute.namespace !== w || !["ascii", "hAnsi", "eastAsia", "cs", "asciiTheme", "hAnsiTheme", "eastAsiaTheme", "cstheme"].includes(attribute.localName)).map((attribute) => ` ${attribute.name}="${xmlValue(attribute.value)}"`).join("") ?? "";
+    const inner2 = fonts ? xml.sourceXml(fonts, /* @__PURE__ */ new Map(), true) : "";
+    const fontXml = `<${fontName}${retained}${["ascii", "hAnsi", "eastAsia", "cs"].map((local) => ` ${prefix}${local}="${xmlValue(font)}"`).join("")}${inner2 ? ">" + inner2 + `</${fontName}>` : "/>"}`;
+    propertyXml = properties ? opening(properties) + xml.sourceXml(properties, fonts ? /* @__PURE__ */ new Map([[fonts, fontXml]]) : /* @__PURE__ */ new Map(), true) + (fonts ? "" : fontXml) + `</${properties.name}>` : `<${name("rPr")}>${fontXml}</${name("rPr")}>`;
+  }
+  const firstLeaf = first?.children.find((node) => node.localName === "t") ?? first?.children.find((node) => node !== properties);
+  const textLeaf = firstLeaf?.localName === "t" ? firstLeaf : void 0;
+  const textName = textLeaf?.name ?? name("t");
+  const textAttributes = textLeaf?.attributes.filter((attribute) => !(attribute.namespace === "http://www.w3.org/XML/1998/namespace" && attribute.localName === "space")).map((attribute) => ` ${attribute.name}="${xmlValue(attribute.value)}"`).join("") ?? "";
+  let value = "", fragment = "", firstText, firstTextMarkup = "";
+  const flush = () => {
+    if (fragment) {
+      const markup = `<${textName}${textAttributes} xml:space="preserve">${xmlValue(fragment)}</${textName}>`;
+      if (!value) {
+        firstText = fragment;
+        firstTextMarkup = markup;
+      }
+      value += markup;
+      fragment = "";
+    }
+  };
+  for (const char of text) {
+    if (char === "	" || char === "\n") {
+      flush();
+      value += `<${name(char === "	" ? "tab" : "br")}/>`;
+    } else fragment += char;
+  }
+  flush();
+  let firstOpening = first ? opening(first) : "";
+  if (first) {
+    const inheritance = /* @__PURE__ */ new Map();
+    const collect = (owner, inherited) => {
+      const next = new Map(inherited);
+      for (const attribute of owner.attributes) if (attribute.namespace === "http://www.w3.org/XML/1998/namespace") {
+        if (!["lang", "space"].includes(attribute.localName) && owner !== content && owner !== first) throw new UnsupportedEditError("Moving a run with unsupported inherited XML semantics is unsupported.");
+        if (["lang", "space"].includes(attribute.localName)) next.set(attribute.localName, attribute.value);
+      }
+      if (owner === first) {
+        for (const [key, value2] of next) inheritance.set(key, value2);
+        return true;
+      }
+      return owner.children.some((child2) => collect(child2, next));
+    };
+    collect(content, /* @__PURE__ */ new Map());
+    const namespaces = [...first.namespaces].filter(([prefix2]) => prefix2 !== "xml" && !first.attributes.some((attribute) => attribute.namespace === "http://www.w3.org/2000/xmlns/" && (prefix2 ? attribute.localName === prefix2 : attribute.name === "xmlns"))).map(([prefix2, uri]) => ` ${prefix2 ? "xmlns:" + prefix2 : "xmlns"}="${xmlValue(uri)}"`).join("");
+    const lifted = [...inheritance].filter(([name2]) => !first.attributes.some((attribute) => attribute.namespace === "http://www.w3.org/XML/1998/namespace" && attribute.localName === name2)).map(([name2, value2]) => ` xml:${name2}="${xmlValue(value2)}"`).join("");
+    firstOpening = firstOpening.slice(0, -1) + namespaces + lifted + ">";
+  }
+  let run;
+  if (first) {
+    const replacements2 = /* @__PURE__ */ new Map();
+    let filled = false;
+    for (const node of first.children) {
+      if (node === properties) replacements2.set(node, propertyXml);
+      else if (node === firstLeaf) {
+        replacements2.set(node, node === textLeaf ? xml[nativeScalarTextSource](node, firstText ?? "", { preserveSpace: true }) + value.slice(firstTextMarkup.length) : value + retainedControlTrivia(xml, node, budget));
+        filled = true;
+      } else replacements2.set(node, retainedControlTrivia(xml, node, budget));
+    }
+    run = firstOpening + (properties ? "" : propertyXml) + xml.sourceXml(first, replacements2, true) + (filled ? "" : value) + `</${first.name}>`;
+  } else run = `<${name("r")}>${propertyXml}${value}</${name("r")}>`;
+  const paragraph = content.children[0]?.localName === "p" ? content.children[0] : void 0;
+  const pPr = paragraph && child(paragraph, "pPr");
+  const replacements = /* @__PURE__ */ new Map();
+  for (const node of content.children) {
+    if (node.localName === "p") {
+      const nested = new Map(node.children.map((element) => [element, element === first ? run : element === pPr ? xml.sourceXml(element) : retainedControlTrivia(xml, element, budget)]));
+      replacements.set(node, xml.sourceXml(node, nested, true));
+    } else replacements.set(node, node === first ? run : retainedControlTrivia(xml, node, budget));
+  }
+  const inner = xml.sourceXml(content, replacements, true) + (first ? "" : run);
+  return opening(content) + (paragraph ? opening(paragraph) + inner + `</${paragraph.name}>` : inner) + `</${content.name}>`;
+}
+function prepareControlPlaceholder(xml, node, item, context) {
+  const { budget } = archiveSettings(context), { one: child } = controlChildren(xml, budget);
+  const properties = child(node, "sdtPr"), content = child(node, "sdtContent");
+  if (!properties || !content || item.support !== "supported" || !["plain-text", "rich-text", "checkbox", "dropdown", "combo-box", "date"].includes(item.kind)) throw new UnsupportedEditError("A placeholder requires an admitted scalar control.");
+  let scalar;
+  if (item.kind === "checkbox") scalar = prepareControlValue(xml, node, item, { checked: false }, context, false);
+  else {
+    if (item.kind === "date") prepareControlValue(xml, node, item, { date: "2000-01-01" }, context);
+    const replacement = textReplacement(xml, content, "", budget);
+    scalar = () => xml.replaceElement(content, replacement);
+  }
+  const current = item.kind === "date" ? child(properties, "date") : item.kind === "dropdown" ? child(properties, "dropDownList") : item.kind === "combo-box" ? child(properties, "comboBox") : void 0;
+  let currentXml;
+  if (current && current.attributes.some((attribute) => attribute.namespace === node.namespace && ["fullDate", "lastValue"].includes(attribute.localName))) currentXml = `<${current.name}${current.attributes.filter((attribute) => attribute.namespace !== node.namespace || !["fullDate", "lastValue"].includes(attribute.localName)).map((attribute) => ` ${attribute.name}="${xmlValue(attribute.value)}"`).join("")}>${xml.sourceXml(current, /* @__PURE__ */ new Map(), true)}</${current.name}>`;
+  const existing = child(properties, "showingPlcHdr");
+  const prefix = properties.name.includes(":") ? properties.name.slice(0, properties.name.indexOf(":") + 1) : "";
+  const replacements = /* @__PURE__ */ new Map();
+  if (current && currentXml !== void 0) replacements.set(current, currentXml);
+  if (existing && !item.placeholder && item.kind !== "checkbox") {
+    const state = existing.attributes.find((attribute) => attribute.namespace === node.namespace && attribute.localName === "val");
+    const [head, tail] = xml[nativeElementSourceTokens](existing, state);
+    replacements.set(existing, head + xml.sourceXml(existing, /* @__PURE__ */ new Map(), true) + tail);
+  }
+  const propertyXml = opening(properties) + xml.sourceXml(properties, replacements, true) + (existing ? "" : `<${prefix}showingPlcHdr/>`) + `</${properties.name}>`;
+  return () => {
+    scalar();
+    if (item.kind !== "checkbox" && (!existing || currentXml !== void 0 || !item.placeholder)) xml.replaceElement(properties, propertyXml);
+  };
+}
+function prepareControlValue(xml, node, item, values, context, clearPlaceholder = true) {
+  const { budget } = archiveSettings(context);
+  const { text, checked, choice, date } = values;
+  const { one: child } = controlChildren(xml, budget);
+  const properties = child(node, "sdtPr"), content = child(node, "sdtContent");
+  if (!properties || !content || item.support !== "supported" || walk(content, budget).some((n) => n.namespace === node.namespace && n.localName === "sdt")) throw new UnsupportedEditError("Scalar filling requires an admitted leaf control.");
+  for (const owner of walk(content, budget)) {
+    budget.charge("work", owner.children.length + owner.attributes.length + 1);
+    if (!xml.compatibility.canEdit(owner) || owner.attributes.some((attribute) => attribute.namespace !== "http://www.w3.org/2000/xmlns/" && !xml.compatibility.canEdit(attribute))) throw new UnsupportedEditError("Affected control content is opaque.");
+  }
+  const stages = [];
+  const placeholder = child(properties, "showingPlcHdr");
+  let value, font;
+  if (["plain-text", "rich-text"].includes(item.kind) && text !== void 0) value = text;
+  else if (["dropdown", "combo-box"].includes(item.kind) && choice !== void 0) {
+    const declaration = item.choices.find((item2) => item2.value === choice);
+    if (!declaration) throw new InvalidValueError("Expected a declared control choice value.");
+    value = declaration.label;
+  } else if (item.kind === "checkbox" && checked !== void 0) {
+    const checkbox = child(properties, "checkbox", w14);
+    if (walk(checkbox, budget).some((owner) => !xml.compatibility.canEdit(owner) || owner.attributes.some((attribute) => attribute.namespace !== "http://www.w3.org/2000/xmlns/" && !xml.compatibility.canEdit(attribute)))) throw new UnsupportedEditError("Checkbox metadata includes unsupported elements or attributes.");
+    for (const name of ["checkedState", "uncheckedState"]) {
+      const state2 = child(checkbox, name, w14), glyph2 = attr(state2, "val", w14), font2 = attr(state2, "font", w14);
+      if (!glyph2 || glyph2.length > 6 || [...glyph2].some((c) => !"0123456789abcdefABCDEF".includes(c)) || !font2 || font2.trim() !== font2 || [...font2].some((c) => c.codePointAt(0) < 32)) throw new UnsupportedEditError("Checkbox requires both declared glyph and font mappings.");
+      const code2 = Number.parseInt(glyph2, 16);
+      if (code2 === 0 || code2 > 1114111 || code2 >= 55296 && code2 <= 57343) throw new UnsupportedEditError("Invalid checkbox Unicode glyph.");
+    }
+    const state = child(checkbox, checked ? "checkedState" : "uncheckedState", w14);
+    const glyph = attr(state, "val", w14);
+    font = attr(state, "font", w14) ?? void 0;
+    if (!glyph || glyph.length > 6 || [...glyph].some((c) => !"0123456789abcdefABCDEF".includes(c)) || !font || font.trim() !== font) throw new UnsupportedEditError("Checkbox requires a declared glyph and font.");
+    const code = Number.parseInt(glyph, 16);
+    if (code === 0 || code > 1114111 || code >= 55296 && code <= 57343) throw new UnsupportedEditError("Invalid checkbox Unicode glyph.");
+    value = String.fromCodePoint(code);
+    const current = child(checkbox, "checked", w14);
+    stages.push(() => xml.setAttribute(current, { namespace: w14, localName: "val" }, checked ? "1" : "0"));
+  } else if (item.kind === "date" && date !== void 0) {
+    const stored = child(properties, "date");
+    const format = attr(child(stored, "dateFormat"), "val") ?? "yyyy-MM-dd", language = attr(child(stored, "lid"), "val"), calendar = attr(child(stored, "calendar"), "val");
+    if (!["yyyy-MM-dd", "MM-dd-yyyy", "dd/MM/yyyy"].includes(format) || language !== null && !["en-US", "en-GB"].includes(language) || calendar !== null && calendar !== "gregorian") throw new UnsupportedEditError("Stored date formatting has no deterministic support.");
+    if (date.length !== 10 || date[4] !== "-" || date[7] !== "-" || [...date].some((c, index) => index !== 4 && index !== 7 && !"0123456789".includes(c))) throw new InvalidValueError("Expected a Gregorian date yyyy-MM-dd.");
+    const canonical = date + "T00:00:00Z";
+    parseStoredDateTime(canonical, "xsd");
+    value = format === "MM-dd-yyyy" ? date.slice(5, 7) + "-" + date.slice(8) + "-" + date.slice(0, 4) : format === "dd/MM/yyyy" ? date.slice(8) + "/" + date.slice(5, 7) + "/" + date.slice(0, 4) : date;
+    if (attr(stored, "fullDate") !== null) stages.push(() => xml.setAttribute(stored, { namespace: node.namespace, localName: "fullDate" }, canonical));
+    else {
+      const prefix = stored.name.includes(":") ? stored.name.slice(0, stored.name.indexOf(":") + 1) : "";
+      const replacement = opening(stored).slice(0, -1) + ` ${prefix}fullDate="${canonical}">` + xml.sourceXml(stored, /* @__PURE__ */ new Map(), true) + `</${stored.name}>`;
+      stages.push(() => xml.replaceElement(stored, replacement));
+    }
+  } else throw new UnsupportedEditError("The explicit value does not match the control type.");
+  if (value !== void 0) {
+    const replacement = textReplacement(xml, content, value, budget, font);
+    stages.push(() => xml.replaceElement(content, replacement));
+  }
+  if (placeholder && clearPlaceholder) {
+    const trivia = retainedControlTrivia(xml, placeholder, budget);
+    stages.push(() => xml.replaceElement(placeholder, trivia));
+  }
+  return () => {
+    for (const stage of stages) stage();
+  };
+}
+async function editDocumentControls(input, options, context) {
+  const settings = archiveSettings(context);
+  const { input: identity, ...args } = options;
+  closedRecord(options, [...Object.keys(args), "input"]);
+  const invocation = validateDocxInvocation({ operation: "controls.set", inputs: [identity?.path ?? "document"], options: args }, settings.budget);
+  const opts = invocation.options;
+  const budget = settings.budget.lower(Object.fromEntries((opts.limit ?? []).map((item) => [item.name, item.value])));
+  const { output, inPlace, force, dryRun, json, all, allowEmpty, text, checked, choice, date, file, ...selectors } = opts;
+  delete selectors.limit;
+  const result = await openControlInventory(input, selectors, { ...settings, budget });
+  assertDocumentEditable(result.archive, { ...settings, budget }, result.archive);
+  const chosen = result.document.select(result.items.map((item) => item.location), { ...all === void 0 ? {} : { all }, ...allowEmpty === void 0 ? {} : { allowEmpty } }, "mutation");
+  const stages = [];
+  let picture;
+  for (const location of chosen) {
+    budget.charge("work", 1);
+    const item = result.items.find((item2) => item2.location.token === location.token);
+    const xml = result.editor.xml(location.value.part.slice(1));
+    const ancestors = owners(xml.root, location.value.path);
+    const node = ancestors.at(-1);
+    const { one: child } = controlChildren(xml, budget);
+    if (item.support !== "supported" || item.binding || item.lock !== "unlocked" || result.document.references(location.token).length > 1) throw new UnsupportedEditError("This control is unsupported, bound, locked or shared.");
+    for (const owner of ancestors.slice(0, -1)) if (owner.namespace === node.namespace && owner.localName === "sdt") {
+      const ancestor = inspectControlSnapshot(owner, item.location, result.archive, { ...settings, budget }, xml);
+      if (ancestor.support !== "supported" || ancestor.kind === "unsupported") throw new UnsupportedEditError("Control ancestors require verified admission.");
+      const ancestorPr = child(owner, "sdtPr");
+      if (!ancestorPr || attr(child(ancestorPr, "lock"), "val") && attr(child(ancestorPr, "lock"), "val") !== "unlocked" || child(ancestorPr, "dataBinding")) throw new UnsupportedEditError("Control ancestors must be admitted, unlocked and unbound.");
+    }
+    const properties = child(node, "sdtPr"), content = child(node, "sdtContent");
+    if (containsRevision(node) || ancestors.slice(0, -1).some((owner) => ["ins", "del", "moveFrom", "moveTo"].includes(owner.localName))) throw new UnsupportedEditError("Control filling cannot cross revision owners.");
+    const story = result.document.list("story", { scope: "all-stories" }).filter((owner) => owner.value.story === location.value.story && pathContains(owner.value.path, location.value.path)).sort((a, b) => b.value.path.length - a.value.path.length)[0];
+    if (!story) throw new UnsupportedEditError("Controls require an admitted story owner.");
+    assertOutsideFields(parseFields(ancestors[story.value.path.length], story.value.path, budget, xml.compatibility.content), location.value.path);
+    assertOutsideRevisionRanges(xml.root, node, budget, xml.compatibility.branches);
+    if (walk(content, budget).some((n) => n.namespace === node.namespace && n.localName === "sdt")) throw new UnsupportedEditError("Scalar filling cannot erase nested controls.");
+    if (item.kind === "picture" && file !== void 0) {
+      if (!item.value || typeof item.value !== "object" || item.value.external || !item.value.contentType?.toLowerCase().startsWith("image/")) throw new UnsupportedEditError("Only an existing internal picture occurrence supports filling.");
+      picture ??= await acquireControlPng(file, { ...context, budget });
+      stages.push(() => replaceControlPicture(result.editor, result.archive, location.value.part, content, picture, { ...settings, budget }));
+    } else stages.push(prepareControlValue(xml, node, item, { ...text === void 0 ? {} : { text }, ...checked === void 0 ? {} : { checked }, ...choice === void 0 ? {} : { choice }, ...date === void 0 ? {} : { date } }, { ...settings, budget }));
+    if (item.kind === "picture") {
+      const placeholder = child(properties, "showingPlcHdr");
+      if (placeholder) {
+        const trivia = retainedControlTrivia(xml, placeholder, budget);
+        stages.push(() => xml.replaceElement(placeholder, trivia));
+      }
+    }
+  }
+  const changes = chosen.map((before) => {
+    const value = { ...before.value, generation: 1 };
+    return { kind: "replace", before, after: { ...before, value, token: encodeGeneratedLocation(value) } };
+  });
+  const prospective = { changed: chosen.length > 0, changes, output: dryRun ? null : { path: inPlace ? identity?.path ?? null : output ?? null, bytes: Math.min(settings.limits.maxArchiveBytes, Number.MAX_SAFE_INTEGER), sha256: "0".repeat(64) }, dryRun: dryRun ?? false };
+  budget.check("serializedOutput", new TextEncoder().encode(JSON.stringify({ version: 1, operation: "controls.set", ok: true, data: prospective, affected: changes.length, locations: changes.map((change) => change.after), warnings: [], errors: [] }) + "\n").length);
+  for (const stage of stages) stage();
+  const published = await publishDocumentArchive(finishControlPictures(result.editor, result.archive, { ...settings, budget }), { ...identity ? { input: identity } : {}, ...output === void 0 ? {} : { output }, ...inPlace === void 0 ? {} : { inPlace }, ...force === void 0 ? {} : { force }, ...dryRun === void 0 ? {} : { dryRun }, ...json === void 0 ? {} : { json } }, { ...context, budget }, result.archive);
+  return { ...prospective, output: published.published.length ? { path: published.published[0].path, bytes: published.published[0].bytes, sha256: published.archiveSha256 } : null };
+}
+
+export {
+  admitControlPng,
+  inspectControlSnapshot,
+  openControlInventory,
+  inspectDocumentControls,
+  prepareControlPlaceholder,
+  prepareControlValue,
+  editDocumentControls
+};