@poe-platform/safe-bash 0.1.812 → 0.1.814

package/dist/safe-bash-presentation-engine/properties.js

@@ -7,22 +7,23 @@ import {
   readProperties,
   sanitizeProperties,
   validatePropertyValue
-} from "../safe-bash/command-chunks/chunk-6M6TM5Z5.js";
-import "../safe-bash/command-chunks/chunk-56NYSX65.js";
-import "../safe-bash/command-chunks/chunk-DM2CPMB4.js";
-import "../safe-bash/command-chunks/chunk-X7FA7ZD5.js";
-import "../safe-bash/command-chunks/chunk-XPD636C4.js";
-import "../safe-bash/command-chunks/chunk-PNGDJA6M.js";
-import "../safe-bash/command-chunks/chunk-RNSKXOG3.js";
-import "../safe-bash/command-chunks/chunk-QC5RMGSA.js";
-import "../safe-bash/command-chunks/chunk-2ZFLMWOX.js";
-import "../safe-bash/command-chunks/chunk-554Z6IKP.js";
-import "../safe-bash/command-chunks/chunk-WJCN2IXI.js";
-import "../safe-bash/command-chunks/chunk-ZMHEGDU2.js";
-import "../safe-bash/command-chunks/chunk-36XGIPOG.js";
+} from "../safe-bash/command-chunks/chunk-DBNJEXHK.js";
+import "../safe-bash/command-chunks/chunk-ADHFF2IM.js";
+import "../safe-bash/command-chunks/chunk-KBAQHE5Y.js";
+import "../safe-bash/command-chunks/chunk-W3ZSWK76.js";
+import "../safe-bash/command-chunks/chunk-IWHNRYER.js";
+import "../safe-bash/command-chunks/chunk-NFII726L.js";
+import "../safe-bash/command-chunks/chunk-3GRMU7TM.js";
+import "../safe-bash/command-chunks/chunk-AWPI4DZR.js";
+import "../safe-bash/command-chunks/chunk-FWKLBDMK.js";
+import "../safe-bash/command-chunks/chunk-XTEIT5CI.js";
+import "../safe-bash/command-chunks/chunk-DBLQUZGN.js";
+import "../safe-bash/command-chunks/chunk-ZQM37BGE.js";
+import "../safe-bash/command-chunks/chunk-LNTEV56A.js";
+import "../safe-bash/command-chunks/chunk-WTVJLHMG.js";
 import "../safe-bash/command-chunks/chunk-ZITBS2EB.js";
-import "../safe-bash/command-chunks/chunk-S6R3IB36.js";
-import "../safe-bash/command-chunks/chunk-Q73EMLLZ.js";
+import "../safe-bash/command-chunks/chunk-JUHOL5KB.js";
+import "../safe-bash/command-chunks/chunk-CXME4YHU.js";
 import "../safe-bash/command-chunks/chunk-37XCUS43.js";
 import "../safe-bash/command-chunks/chunk-IOEUZ4EA.js";
 import "../safe-bash/command-chunks/chunk-E6SK3OU2.js";

package/dist/safe-bash-presentation-engine/relationships.js

@@ -3,11 +3,11 @@ import {
   parseRelationships,
   readRelationshipGraph,
   relationshipGraph
-} from "../safe-bash/command-chunks/chunk-ZMHEGDU2.js";
-import "../safe-bash/command-chunks/chunk-36XGIPOG.js";
+} from "../safe-bash/command-chunks/chunk-LNTEV56A.js";
+import "../safe-bash/command-chunks/chunk-WTVJLHMG.js";
 import "../safe-bash/command-chunks/chunk-ZITBS2EB.js";
-import "../safe-bash/command-chunks/chunk-S6R3IB36.js";
-import "../safe-bash/command-chunks/chunk-Q73EMLLZ.js";
+import "../safe-bash/command-chunks/chunk-JUHOL5KB.js";
+import "../safe-bash/command-chunks/chunk-CXME4YHU.js";
 import "../safe-bash/command-chunks/chunk-IOEUZ4EA.js";
 import "../safe-bash/command-chunks/chunk-E6SK3OU2.js";
 import "../safe-bash/command-chunks/chunk-65DS4IOB.js";

package/dist/safe-bash-presentation-engine/resource-limits.js

@@ -1,7 +1,7 @@
 import "../safe-bash/command-chunks/chunk-ZITBS2EB.js";
 import {
   resolveOfficeResources
-} from "../safe-bash/command-chunks/chunk-Q73EMLLZ.js";
+} from "../safe-bash/command-chunks/chunk-CXME4YHU.js";
 import "../safe-bash/command-chunks/chunk-IOEUZ4EA.js";
 import "../safe-bash/command-chunks/chunk-E6SK3OU2.js";
 import "../safe-bash/command-chunks/chunk-65DS4IOB.js";

package/dist/safe-bash-presentation-engine/retained-archive-staging.d.ts

@@ -0,0 +1,19 @@
+import type { ByteSource } from './contracts.js';
+import type { RetainedPackageArchive, RetainedPackageContext } from './retained-package.js';
+export interface RetainedMutationSource {
+    readonly size: number;
+    read(position: number, maximum: number, options: {
+        readonly signal: AbortSignal;
+    }): Promise<Uint8Array>;
+    stream(): ByteSource;
+}
+/** Borrow the admitted archive, replacement view and immutable input; own only output pages. */
+export declare function stageRetainedArchive(input: RetainedMutationSource, originalFingerprint: string, archive: RetainedPackageArchive, mutation: {
+    readonly changed: boolean;
+    replacement(part: string): Promise<ByteSource | undefined>;
+}, settings: RetainedPackageContext): Promise<Readonly<{
+    bytes: () => ByteSource;
+    size: number;
+    fingerprint: string;
+    close: () => Promise<void>;
+}>>;

package/dist/safe-bash-presentation-engine/retained-extraction-output.d.ts

@@ -0,0 +1,18 @@
+import type { ByteSink } from './contracts.js';
+import type { RetainedPackageContext } from './retained-package.js';
+import type { RetainedPackageExtraction } from './retained-package-extraction.js';
+/** Store manifest fragments and prefix boundaries before publication. Diagnostic
+ * storage survives publication cancellation so completed files can be reported. */
+export declare function stageRetainedExtractionOutput(extraction: RetainedPackageExtraction, settings: RetainedPackageContext, output: {
+    readonly directory: string;
+    readonly json: boolean;
+    readonly maxOutputBytes: number;
+    readonly allowPartialOutput: boolean;
+}): Promise<Readonly<{
+    close: () => Promise<void>;
+    path: (name: string) => string;
+    write(sink: ByteSink, failure?: {
+        readonly code: string;
+        readonly published: number;
+    }): Promise<void>;
+}>>;

package/dist/safe-bash-presentation-engine/retained-frame-formatting.d.ts

@@ -0,0 +1,14 @@
+import type { RetainedXmlDocument, RetainedXmlNode } from './retained-xml-document.js';
+/** Admit properties without materializing arbitrarily padded integer tokens. */
+export declare function readRetainedFrameFormatting(document: RetainedXmlDocument, body: RetainedXmlNode): Promise<{
+    marginLeft: number | null;
+    marginRight: number | null;
+    marginTop: number | null;
+    marginBottom: number | null;
+    verticalAnchor: string | null;
+    columns: number | null;
+    wrap: boolean | null;
+    verticalText: string | null;
+    rotation: number | null;
+    autofit: "text" | "none" | "shape" | null;
+}>;

package/dist/safe-bash-presentation-engine/retained-inspection.js

@@ -1,19 +1,21 @@
 import {
   openRetainedPresentationIndex,
   stageRetainedInspection
-} from "../safe-bash/command-chunks/chunk-L5MCW6CM.js";
-import "../safe-bash/command-chunks/chunk-X7FA7ZD5.js";
-import "../safe-bash/command-chunks/chunk-XPD636C4.js";
-import "../safe-bash/command-chunks/chunk-PNGDJA6M.js";
-import "../safe-bash/command-chunks/chunk-QC5RMGSA.js";
-import "../safe-bash/command-chunks/chunk-2ZFLMWOX.js";
-import "../safe-bash/command-chunks/chunk-554Z6IKP.js";
-import "../safe-bash/command-chunks/chunk-WJCN2IXI.js";
-import "../safe-bash/command-chunks/chunk-ZMHEGDU2.js";
-import "../safe-bash/command-chunks/chunk-36XGIPOG.js";
+} from "../safe-bash/command-chunks/chunk-4EHY6J2Z.js";
+import "../safe-bash/command-chunks/chunk-NQINS4XY.js";
+import "../safe-bash/command-chunks/chunk-W3ZSWK76.js";
+import "../safe-bash/command-chunks/chunk-IWHNRYER.js";
+import "../safe-bash/command-chunks/chunk-NFII726L.js";
+import "../safe-bash/command-chunks/chunk-AWPI4DZR.js";
+import "../safe-bash/command-chunks/chunk-FWKLBDMK.js";
+import "../safe-bash/command-chunks/chunk-XTEIT5CI.js";
+import "../safe-bash/command-chunks/chunk-DBLQUZGN.js";
+import "../safe-bash/command-chunks/chunk-ZQM37BGE.js";
+import "../safe-bash/command-chunks/chunk-LNTEV56A.js";
+import "../safe-bash/command-chunks/chunk-WTVJLHMG.js";
 import "../safe-bash/command-chunks/chunk-ZITBS2EB.js";
-import "../safe-bash/command-chunks/chunk-S6R3IB36.js";
-import "../safe-bash/command-chunks/chunk-Q73EMLLZ.js";
+import "../safe-bash/command-chunks/chunk-JUHOL5KB.js";
+import "../safe-bash/command-chunks/chunk-CXME4YHU.js";
 import "../safe-bash/command-chunks/chunk-IOEUZ4EA.js";
 import "../safe-bash/command-chunks/chunk-E6SK3OU2.js";
 import "../safe-bash/command-chunks/chunk-65DS4IOB.js";

package/dist/safe-bash-presentation-engine/retained-package-extraction.d.ts

@@ -0,0 +1,22 @@
+import type { ByteSource } from './contracts.js';
+import { type RetainedPackageContext } from './retained-package.js';
+import type { RetainedMutationSource } from './retained-archive-staging.js';
+export interface RetainedExtractedPackageMember {
+    readonly part: string;
+    readonly name: string;
+    readonly sha256: string;
+    readonly size: number;
+    contentType(): ByteSource;
+    bytes(): ByteSource;
+}
+export interface RetainedPackageExtraction {
+    readonly count: number;
+    members(): AsyncGenerator<RetainedExtractedPackageMember>;
+    close(): Promise<void>;
+}
+/** Admit the complete selection before exposing members. Borrows immutable input,
+ * owns archive and descriptor storage; it never opens output paths. Selection
+ * arrays are borrowed until admission settles and must remain immutable. */
+export declare function openRetainedPackageExtraction(input: RetainedMutationSource, settings: RetainedPackageContext, options?: {
+    readonly parts?: readonly string[];
+}): Promise<RetainedPackageExtraction>;

package/dist/safe-bash-presentation-engine/retained-package-packing.d.ts

@@ -0,0 +1,19 @@
+import type { ByteSource } from './contracts.js';
+import type { PresentationKind } from './content-types.js';
+import { type RetainedPackageContext } from './retained-package.js';
+export interface RetainedPackMember {
+    readonly part: string;
+    readonly sha256: string;
+}
+/** Persist and admit all descriptors before opening members. Each source is
+ * consumed once; neither the caller's descriptors nor its chunks are retained.
+ * The returned archive owns caller-backed pages and must be closed. */
+export declare function stageRetainedPackage(members: AsyncIterable<RetainedPackMember>, openMember: (part: string) => ByteSource, settings: RetainedPackageContext, options?: {
+    readonly kind?: PresentationKind;
+}): Promise<Readonly<{
+    count: number;
+    size: number;
+    fingerprint: string;
+    bytes: () => ByteSource;
+    close: () => Promise<void>;
+}>>;

package/dist/safe-bash-presentation-engine/retained-package.d.ts

@@ -14,6 +14,8 @@ export interface RetainedPackageContext extends ResourceContext {
 }
 export interface PackageRewriteOptions {
     readonly compression?: "store" | "auto";
+    /** Order existing members by JavaScript name comparison; additions follow them. */
+    readonly sourceOrder?: "name";
     /** Undefined retains compressed bytes and ZIP metadata; null removes a part.
      * Replacement sources are borrowed until rewrite settles. */
     readonly replace?: (part: string, original: ByteSource) => Promise<ByteSource | null | undefined>;

package/dist/safe-bash-presentation-engine/retained-package.js

@@ -1,10 +1,12 @@
 import {
   openPackageArchive
-} from "../safe-bash/command-chunks/chunk-ZXR6LXV5.js";
-import "../safe-bash/command-chunks/chunk-36XGIPOG.js";
+} from "../safe-bash/command-chunks/chunk-3ZRCL756.js";
+import "../safe-bash/command-chunks/chunk-NQINS4XY.js";
+import "../safe-bash/command-chunks/chunk-FWKLBDMK.js";
+import "../safe-bash/command-chunks/chunk-WTVJLHMG.js";
 import "../safe-bash/command-chunks/chunk-ZITBS2EB.js";
-import "../safe-bash/command-chunks/chunk-S6R3IB36.js";
-import "../safe-bash/command-chunks/chunk-Q73EMLLZ.js";
+import "../safe-bash/command-chunks/chunk-JUHOL5KB.js";
+import "../safe-bash/command-chunks/chunk-CXME4YHU.js";
 import "../safe-bash/command-chunks/chunk-37XCUS43.js";
 import "../safe-bash/command-chunks/chunk-IOEUZ4EA.js";
 import "../safe-bash/command-chunks/chunk-E6SK3OU2.js";

package/dist/safe-bash-presentation-engine/retained-text.d.ts

@@ -1,3 +1,4 @@
+import { readRetainedFrameFormatting } from './retained-frame-formatting.js';
 import { type StagedOutput } from './retained-output.js';
 import type { ByteSource, Location } from './contracts.js';
 import type { RetainedPackageArchive, RetainedPackageContext } from './retained-package.js';
@@ -37,17 +38,23 @@ export interface RetainedField {
     readonly fieldType: (() => ByteSource) | null;
     cachedText(): ByteSource;
 }
+export interface RetainedTextFrame {
+    readonly location: Location;
+    readonly formatting: Awaited<ReturnType<typeof readRetainedFrameFormatting>>;
+}
 export interface RetainedPresentationText {
+    readonly frameCount: number;
+    frames(): AsyncGenerator<RetainedTextFrame>;
     readonly fieldCount: number;
     fields(): AsyncGenerator<RetainedField>;
     text(): ByteSource;
     segments(): AsyncGenerator<RetainedTextSegment>;
     close(): Promise<void>;
 }
-export declare function openRetainedText(archive: Pick<RetainedPackageArchive, 'parts' | 'has' | 'read' | 'byteLength'>, fingerprint: string, options: ReadPresentationTextOptions, settings: RetainedPackageContext): Promise<RetainedPresentationText>;
+export declare function openRetainedText(archive: Pick<RetainedPackageArchive, 'parts' | 'has' | 'read' | 'byteLength'>, fingerprint: string, options: ReadPresentationTextOptions, settings: RetainedPackageContext, readingMode?: 'text' | 'frames'): Promise<RetainedPresentationText>;
 /** Stages both CLI formats after complete text admission. */
 export declare function stageRetainedText(archive: Pick<RetainedPackageArchive, 'parts' | 'has' | 'read' | 'byteLength'>, fingerprint: string, options: ReadPresentationTextOptions, settings: RetainedPackageContext, output: {
     readonly json: boolean;
     readonly maxOutputBytes: number;
-    readonly operation?: 'text.get' | 'fields.list' | 'fields.get';
+    readonly operation?: 'text.get' | 'fields.list' | 'fields.get' | 'text.frames.list' | 'text.frames.get';
 }): Promise<StagedOutput>;

package/dist/safe-bash-presentation-engine/retained-text.js

@@ -1,35 +1,52 @@
 import {
   fieldTypeKinds
-} from "../safe-bash/command-chunks/chunk-YORJDX4V.js";
+} from "../safe-bash/command-chunks/chunk-WZRFS5OY.js";
 import {
   openRetainedPresentationIndex,
   stageRetainedOutput,
   streamJson
-} from "../safe-bash/command-chunks/chunk-L5MCW6CM.js";
+} from "../safe-bash/command-chunks/chunk-4EHY6J2Z.js";
+import "../safe-bash/command-chunks/chunk-NQINS4XY.js";
+import {
+  readFramePropertyValues,
+  textVerticalModes
+} from "../safe-bash/command-chunks/chunk-TKCUGMRZ.js";
+import "../safe-bash/command-chunks/chunk-K2WOMJOQ.js";
+import "../safe-bash/command-chunks/chunk-XNGM3W5R.js";
+import "../safe-bash/command-chunks/chunk-Q7TVCBU2.js";
+import "../safe-bash/command-chunks/chunk-UJERQEJB.js";
+import "../safe-bash/command-chunks/chunk-FYYFV6PW.js";
 import {
   validateTextReadingOptions
-} from "../safe-bash/command-chunks/chunk-33YCKZZX.js";
-import "../safe-bash/command-chunks/chunk-56NYSX65.js";
-import "../safe-bash/command-chunks/chunk-DM2CPMB4.js";
+} from "../safe-bash/command-chunks/chunk-KSBNZTAZ.js";
+import "../safe-bash/command-chunks/chunk-PLMF35XK.js";
+import "../safe-bash/command-chunks/chunk-Z2WNYEPD.js";
+import "../safe-bash/command-chunks/chunk-CCMAHM3I.js";
+import "../safe-bash/command-chunks/chunk-TJLXSENN.js";
+import "../safe-bash/command-chunks/chunk-2VVJRVYM.js";
+import "../safe-bash/command-chunks/chunk-HR2Y6YEP.js";
+import "../safe-bash/command-chunks/chunk-ADHFF2IM.js";
+import "../safe-bash/command-chunks/chunk-KBAQHE5Y.js";
 import {
   SelectionError
-} from "../safe-bash/command-chunks/chunk-X7FA7ZD5.js";
-import "../safe-bash/command-chunks/chunk-XPD636C4.js";
-import "../safe-bash/command-chunks/chunk-PNGDJA6M.js";
-import "../safe-bash/command-chunks/chunk-RNSKXOG3.js";
+} from "../safe-bash/command-chunks/chunk-W3ZSWK76.js";
+import "../safe-bash/command-chunks/chunk-IWHNRYER.js";
+import "../safe-bash/command-chunks/chunk-NFII726L.js";
+import "../safe-bash/command-chunks/chunk-3GRMU7TM.js";
 import {
   dialects,
   openRetainedCompatibility
-} from "../safe-bash/command-chunks/chunk-QC5RMGSA.js";
+} from "../safe-bash/command-chunks/chunk-AWPI4DZR.js";
+import "../safe-bash/command-chunks/chunk-FWKLBDMK.js";
 import {
   equationOpaqueElements
-} from "../safe-bash/command-chunks/chunk-2ZFLMWOX.js";
-import "../safe-bash/command-chunks/chunk-554Z6IKP.js";
-import "../safe-bash/command-chunks/chunk-WJCN2IXI.js";
-import "../safe-bash/command-chunks/chunk-ZMHEGDU2.js";
-import "../safe-bash/command-chunks/chunk-36XGIPOG.js";
+} from "../safe-bash/command-chunks/chunk-XTEIT5CI.js";
+import "../safe-bash/command-chunks/chunk-DBLQUZGN.js";
+import "../safe-bash/command-chunks/chunk-ZQM37BGE.js";
+import "../safe-bash/command-chunks/chunk-LNTEV56A.js";
+import "../safe-bash/command-chunks/chunk-WTVJLHMG.js";
 import "../safe-bash/command-chunks/chunk-ZITBS2EB.js";
-import "../safe-bash/command-chunks/chunk-S6R3IB36.js";
+import "../safe-bash/command-chunks/chunk-JUHOL5KB.js";
 import {
   OfficeError,
   RetainedValues,
@@ -39,15 +56,75 @@ import {
   literal,
   openRetainedXmlDocument,
   resolveOfficeResources
-} from "../safe-bash/command-chunks/chunk-Q73EMLLZ.js";
+} from "../safe-bash/command-chunks/chunk-CXME4YHU.js";
 import "../safe-bash/command-chunks/chunk-37XCUS43.js";
 import "../safe-bash/command-chunks/chunk-IOEUZ4EA.js";
 import "../safe-bash/command-chunks/chunk-E6SK3OU2.js";
 import "../safe-bash/command-chunks/chunk-65DS4IOB.js";
 
+// packages/safe-bash-presentation-engine/src/retained-frame-formatting.ts
+async function readRetainedFrameFormatting(document, body) {
+  const malformed = () => {
+    throw new OfficeError("invalid-xml", "Invalid text frame properties.", "parse");
+  };
+  let properties;
+  for await (const node of document.children(body)) {
+    if (node.kind !== "element" || !await equal(document.raw(node.localName), literal("bodyPr"))) continue;
+    let drawing = false;
+    for (const dialect of dialects) if (await equal(document.namespace(node), literal(dialect.a))) drawing = true;
+    if (drawing) {
+      if (properties) malformed();
+      properties = node;
+    }
+  }
+  const attributes = {};
+  const enums = { wrap: ["square", "none"], anchor: ["t", "ctr", "b", "just", "dist"], vert: textVerticalModes };
+  const numbers = ["lIns", "rIns", "tIns", "bIns", "numCol", "rot"];
+  if (properties) for await (const attribute of document.attributes(properties)) {
+    if (!await equal(document.namespace(attribute), literal(""))) continue;
+    for (const key of [...numbers, ...Object.keys(enums)]) {
+      if (!await equal(document.raw(attribute.localName), literal(key))) continue;
+      if (enums[key]) {
+        let value;
+        for (const token of enums[key]) if (await equal(document.text(attribute), literal(token))) value = token;
+        if (value === void 0) malformed();
+        attributes[key] = value;
+      } else {
+        let phase = "leading", negative = false, digits = false, value = 0;
+        for await (const character of characters(document.text(attribute))) {
+          if (character.trim() === "") {
+            if (phase === "sign") malformed();
+            if (phase === "digits") phase = "trailing";
+          } else if (phase === "leading" && (character === "+" || character === "-")) {
+            negative = character === "-";
+            phase = "sign";
+          } else if (phase !== "trailing" && character >= "0" && character <= "9") {
+            phase = "digits";
+            digits = true;
+            value = value * 10 + Number(character);
+            if (!Number.isSafeInteger(value)) malformed();
+          } else malformed();
+        }
+        if (!digits) malformed();
+        attributes[key] = `${negative ? "-" : ""}${value}`;
+      }
+      break;
+    }
+  }
+  const fits = [];
+  if (properties) for await (const child of document.children(properties)) {
+    if (child.kind !== "element" || !await equal(document.namespace(child), document.namespace(properties))) continue;
+    for (const name of ["noAutofit", "normAutofit", "spAutoFit"]) if (await equal(document.raw(child.localName), literal(name))) {
+      if (fits.length) malformed();
+      fits.push(name);
+    }
+  }
+  return readFramePropertyValues((key) => attributes[key] ?? null, fits);
+}
+
 // packages/safe-bash-presentation-engine/src/retained-text.ts
 import { PagedStorage } from "@poe-platform/safe-fs/storage";
-async function openRetainedText(archive, fingerprint, options, settings) {
+async function openRetainedText(archive, fingerprint, options, settings, readingMode = "text") {
   validateTextReadingOptions(options);
   const selection = options.select === void 0 ? void 0 : { ...options.select, ...options.select.position ? { position: { ...options.select.position } } : {} };
   const scope = options.scope ?? "slides", shape = options.shape;
@@ -55,7 +132,7 @@ async function openRetainedText(archive, fingerprint, options, settings) {
   const index = await openRetainedPresentationIndex(archive, fingerprint, { ...context, workingStorage: working });
   const pages = new PagedStorage({ fs: working.fs, cwd: working.directory, env: {}, signal }, (working.cacheBytes ?? 1024 * 1024) / 16384);
   const traversal = new PagedStorage({ fs: working.fs, cwd: working.directory, env: {}, signal }, (working.cacheBytes ?? 1024 * 1024) / 16384);
-  let closed = false, closing, firstBody = 0, lastBody = 0, firstOwner = 0, lastOwner = 0, fieldCount = 0;
+  let closed = false, closing, firstBody = 0, lastBody = 0, firstOwner = 0, lastOwner = 0, fieldCount = 0, frameCount = 0;
   const check = () => {
     if (closed) throw new OfficeError("invalid-handle", "Text is closed.", "select");
     if (signal.aborted) throw new OfficeError("cancelled", "Operation cancelled.", "select");
@@ -214,9 +291,13 @@ async function openRetainedText(archive, fingerprint, options, settings) {
           }
         }
         async function body(node, id, cellRow = -1, cellColumn = -1) {
-          const bodyPointer = pages.allocate(8 /* Count */ * 8), bodyRow = [0, ownerPart.start, ownerPart.length, id, 0, 0, cellRow, cellColumn];
+          if (readingMode === "frames" && cellRow >= 0) return;
+          const formatting = readingMode === "frames" ? await values.store(literal(JSON.stringify(await readRetainedFrameFormatting(document, node), (_key, value) => Object.is(value, -0) ? "-0" : value))) : { start: 0, length: 0 };
+          if (readingMode === "frames") frameCount++;
+          const bodyPointer = pages.allocate(10 /* Count */ * 8), bodyRow = [0, ownerPart.start, ownerPart.length, id, 0, 0, cellRow, cellColumn, formatting.start, formatting.length];
           let paragraphIndex = 0;
           for await (const paragraph of children(node, "p", drawing)) {
+            if (readingMode === "frames") break;
             const paragraphPointer = pages.allocate(4 /* Count */ * 8), paragraphRow = [0, 0, 0, paragraphIndex++];
             let fieldInline = 0;
             for await (const inline of view.children(paragraph)) {
@@ -335,14 +416,25 @@ async function openRetainedText(archive, fingerprint, options, settings) {
     }
     async function* segments() {
       try {
-        for await (const body of rows(firstBody, 8 /* Count */)) yield { location: { fingerprint, scope, owner: await name(range(body, 1 /* Owner */)), objectId: String(body[3 /* Id */]), coordinateSystem: "identity" }, text: () => bodyText(body[4 /* Paragraphs */]), paragraphs: paragraphs(body[4 /* Paragraphs */]), ...body[6 /* Row */] < 0 ? {} : { cell: { coordinateSystem: "zero-based", row: body[6 /* Row */], column: body[7 /* Column */] } } };
+        for await (const body of rows(firstBody, 10 /* Count */)) yield { location: { fingerprint, scope, owner: await name(range(body, 1 /* Owner */)), objectId: String(body[3 /* Id */]), coordinateSystem: "identity" }, text: () => bodyText(body[4 /* Paragraphs */]), paragraphs: paragraphs(body[4 /* Paragraphs */]), ...body[6 /* Row */] < 0 ? {} : { cell: { coordinateSystem: "zero-based", row: body[6 /* Row */], column: body[7 /* Column */] } } };
+      } catch (error) {
+        throw failure(error);
+      }
+    }
+    async function* frames() {
+      try {
+        for await (const body of rows(firstBody, 10 /* Count */)) if (body[8 /* Format */]) yield {
+          location: { fingerprint, scope, owner: await name(range(body, 1 /* Owner */)), objectId: String(body[3 /* Id */]), coordinateSystem: "identity" },
+          // Fixed-schema scalars; the numeric -0 marker cannot collide with valid enums.
+          formatting: JSON.parse(await name(range(body, 8 /* Format */)), (_key, value) => value === "-0" ? -0 : value)
+        };
       } catch (error) {
         throw failure(error);
       }
     }
     async function* fields() {
       try {
-        for await (const body of rows(firstBody, 8 /* Count */)) {
+        for await (const body of rows(firstBody, 10 /* Count */)) {
           const location = { fingerprint, scope, owner: await name(range(body, 1 /* Owner */)), objectId: String(body[3 /* Id */]), coordinateSystem: "identity" };
           for await (const paragraph of rows(body[4 /* Paragraphs */], 4 /* Count */)) for await (const inline of rows(paragraph[1 /* Inlines */], 11 /* Count */)) if (inline[1 /* Kind */] === 2 && inline[8 /* FieldIndex */] >= 0) {
             const fieldType = inline[6 /* FieldType */] === -1 ? null : () => values.read(range(inline, 6 /* FieldType */));
@@ -369,7 +461,7 @@ async function openRetainedText(archive, fingerprint, options, settings) {
         throw failure(error);
       }
     }
-    return Object.freeze({ close, segments, fields, fieldCount, async *text() {
+    return Object.freeze({ close, segments, fields, fieldCount, frames, frameCount, async *text() {
       let separator = false;
       for await (const segment of segments()) {
         if (separator) yield* literal("\n");
@@ -385,11 +477,18 @@ async function openRetainedText(archive, fingerprint, options, settings) {
 }
 async function stageRetainedText(archive, fingerprint, options, settings, output) {
   const format = { ...output }, operation = format.operation ?? "text.get";
-  if (!["text.get", "fields.list", "fields.get"].includes(operation)) throw new OfficeError("invalid-value", "Invalid retained text operation.", "usage");
-  const text = await openRetainedText(archive, fingerprint, options, settings), fields = operation !== "text.get";
+  if (!["text.get", "fields.list", "fields.get", "text.frames.list", "text.frames.get"].includes(operation)) throw new OfficeError("invalid-value", "Invalid retained text operation.", "usage");
+  const frames = operation.startsWith("text.frames."), fields = operation.startsWith("fields.");
+  const text = await openRetainedText(archive, fingerprint, options, settings, frames ? "frames" : "text").catch((error) => {
+    if (frames && error instanceof SelectionError && error.code === "missing-selection") return void 0;
+    throw error;
+  });
+  async function* frameRecords() {
+    if (text) yield* text.frames();
+  }
   let staged;
   async function* locations() {
-    for await (const item of fields ? text.fields() : text.segments()) yield item.location;
+    for await (const item of frames ? frameRecords() : fields ? text.fields() : text.segments()) yield item.location;
   }
   async function* items() {
     for await (const field of text.fields()) yield {
@@ -407,18 +506,20 @@ async function stageRetainedText(archive, fingerprint, options, settings, output
   }
   async function* render() {
     if (format.json) {
-      yield* streamJson({ version: 1, operation, ok: true, data: fields ? { items: items() } : { text: text.text, order: "structural", segments: text.segments() }, warnings: [], errors: [], affected: 0, locations: locations() });
+      yield* streamJson({ version: 1, operation, ok: true, data: frames ? { frames: frameRecords() } : fields ? { items: items() } : { text: text.text, order: "structural", segments: text.segments() }, warnings: [], errors: [], affected: 0, locations: locations() });
       yield* literal("\n");
-    } else if (fields) yield* streamJson(text.fields());
+    } else if (frames) yield* streamJson(frameRecords());
+    else if (fields) yield* streamJson(text.fields());
     else yield* text.text();
   }
   try {
     if (operation === "fields.get" && text.fieldCount !== 1) throw new SelectionError(text.fieldCount ? "ambiguous-selection" : "missing-selection");
+    if (operation === "text.frames.get" && text?.frameCount !== 1) throw new SelectionError(text?.frameCount ? "ambiguous-selection" : "missing-selection");
     staged = await stageRetainedOutput(render(), settings, format.maxOutputBytes);
-    await text.close();
+    await text?.close();
     return staged;
   } catch (error) {
-    await Promise.allSettled([text.close(), staged?.close()]);
+    await Promise.allSettled([text?.close(), staged?.close()]);
     throw error;
   }
 }

package/dist/safe-bash-presentation-engine/retained-xml-document.d.ts

@@ -0,0 +1 @@
+export * from "../office-xml/retained-xml-document.js";

package/dist/safe-bash-presentation-engine/retained-xml-parts.d.ts

@@ -1,5 +1,5 @@
 import type { ValidationLimits } from './validation.js';
-import type { ByteSource } from './contracts.js';
+import type { ByteSource, Location } from './contracts.js';
 import type { RetainedPackageArchive, RetainedPackageContext } from './retained-package.js';
 import { type StagedOutput } from './retained-output.js';
 import { type RetainedInspectionSelection } from './retained-inspection.js';
@@ -18,6 +18,10 @@ export interface RetainedXmlPart {
 export declare function openRetainedXmlPart(archive: Archive, requested: string, settings: RetainedXmlPartContext, options?: {
     readonly pretty?: boolean;
 }): Promise<RetainedXmlPart>;
+export declare function selectRetainedXmlPart(archive: Archive, fingerprint: string, selection: RetainedInspectionSelection, settings: RetainedXmlPartContext, allowMetadata?: boolean): Promise<{
+    part: string;
+    location: Location;
+}>;
 export declare function stageRetainedXmlPart(archive: Archive, fingerprint: string, selection: RetainedInspectionSelection, settings: RetainedXmlPartContext, output: {
     readonly json: boolean;
     readonly pretty?: boolean;

package/dist/safe-bash-presentation-engine/retained-xml-publication.d.ts

@@ -0,0 +1,18 @@
+import type { ByteSource } from './contracts.js';
+import { type RetainedMutationSource } from './retained-archive-staging.js';
+import { type RetainedXmlPartContext } from './retained-xml-parts.js';
+import type { RetainedInspectionSelection } from './retained-inspection.js';
+import { type StagedOutput } from './retained-output.js';
+/** Stage an admitted XML replacement and its response before publishing anything. Input sources are borrowed. */
+export declare function stageRetainedXmlReplacement(input: RetainedMutationSource, replacement: ByteSource, selection: RetainedInspectionSelection, settings: RetainedXmlPartContext, output: {
+    readonly json: boolean;
+    readonly dryRun: boolean;
+    readonly destination?: string;
+    readonly maxOutputBytes: number;
+}): Promise<Readonly<{
+    bytes: () => ByteSource;
+    size: number;
+    fingerprint: string;
+    output: StagedOutput;
+    close: () => Promise<void>;
+}>>;

package/dist/safe-bash-presentation-engine/retained-xml-replacement.d.ts

@@ -0,0 +1,13 @@
+import type { ByteSource } from './contracts.js';
+import type { RetainedPackageArchive } from './retained-package.js';
+import type { RetainedXmlPartContext } from './retained-xml-parts.js';
+type Archive = Pick<RetainedPackageArchive, 'parts' | 'has' | 'read' | 'byteLength'>;
+export interface RetainedXmlReplacement extends Archive {
+    readonly changed: boolean;
+    replacement(part: string): Promise<ByteSource | undefined>;
+    close(): Promise<void>;
+}
+/** Admits the complete existing XML replacement subset. Archive ownership stays
+ * with the caller; replacement bytes, comparison queues and maps use caller pages. */
+export declare function openRetainedXmlReplacement(archive: Archive, requested: string, source: ByteSource, settings: RetainedXmlPartContext): Promise<RetainedXmlReplacement>;
+export {};

package/dist/safe-bash-presentation-engine/sanitize.js

@@ -1,22 +1,23 @@
 import {
   sanitize
-} from "../safe-bash/command-chunks/chunk-M7QE2MN7.js";
-import "../safe-bash/command-chunks/chunk-6M6TM5Z5.js";
-import "../safe-bash/command-chunks/chunk-56NYSX65.js";
-import "../safe-bash/command-chunks/chunk-DM2CPMB4.js";
-import "../safe-bash/command-chunks/chunk-X7FA7ZD5.js";
-import "../safe-bash/command-chunks/chunk-XPD636C4.js";
-import "../safe-bash/command-chunks/chunk-PNGDJA6M.js";
-import "../safe-bash/command-chunks/chunk-RNSKXOG3.js";
-import "../safe-bash/command-chunks/chunk-QC5RMGSA.js";
-import "../safe-bash/command-chunks/chunk-2ZFLMWOX.js";
-import "../safe-bash/command-chunks/chunk-554Z6IKP.js";
-import "../safe-bash/command-chunks/chunk-WJCN2IXI.js";
-import "../safe-bash/command-chunks/chunk-ZMHEGDU2.js";
-import "../safe-bash/command-chunks/chunk-36XGIPOG.js";
+} from "../safe-bash/command-chunks/chunk-4YLACJHE.js";
+import "../safe-bash/command-chunks/chunk-DBNJEXHK.js";
+import "../safe-bash/command-chunks/chunk-ADHFF2IM.js";
+import "../safe-bash/command-chunks/chunk-KBAQHE5Y.js";
+import "../safe-bash/command-chunks/chunk-W3ZSWK76.js";
+import "../safe-bash/command-chunks/chunk-IWHNRYER.js";
+import "../safe-bash/command-chunks/chunk-NFII726L.js";
+import "../safe-bash/command-chunks/chunk-3GRMU7TM.js";
+import "../safe-bash/command-chunks/chunk-AWPI4DZR.js";
+import "../safe-bash/command-chunks/chunk-FWKLBDMK.js";
+import "../safe-bash/command-chunks/chunk-XTEIT5CI.js";
+import "../safe-bash/command-chunks/chunk-DBLQUZGN.js";
+import "../safe-bash/command-chunks/chunk-ZQM37BGE.js";
+import "../safe-bash/command-chunks/chunk-LNTEV56A.js";
+import "../safe-bash/command-chunks/chunk-WTVJLHMG.js";
 import "../safe-bash/command-chunks/chunk-ZITBS2EB.js";
-import "../safe-bash/command-chunks/chunk-S6R3IB36.js";
-import "../safe-bash/command-chunks/chunk-Q73EMLLZ.js";
+import "../safe-bash/command-chunks/chunk-JUHOL5KB.js";
+import "../safe-bash/command-chunks/chunk-CXME4YHU.js";
 import "../safe-bash/command-chunks/chunk-37XCUS43.js";
 import "../safe-bash/command-chunks/chunk-IOEUZ4EA.js";
 import "../safe-bash/command-chunks/chunk-E6SK3OU2.js";