web-doc 0.6.2 → 0.8.0

package/dist/edit/ooxml/package.d.ts

@@ -0,0 +1,82 @@
+import type { ResourceLimits } from "../../contracts.js";
+import { type XmlPart } from "./xml.js";
+import { type ContentTypes, type RelationshipSet } from "./opc.js";
+import { PackageTransaction } from "./transaction.js";
+import { type ZipArchive, type ZipEntry } from "./zip.js";
+export interface SaveOptions {
+    /** How changed and new entries are written; default "store". */
+    readonly compression?: "store" | "deflate";
+}
+/** The overlay at a point in time; opaque to callers, O(1) to take and restore. */
+export interface PackageSnapshot {
+    readonly revision: number;
+}
+export interface OpenOptions {
+    readonly limits: ResourceLimits;
+    readonly signal?: AbortSignal;
+}
+export declare const CONTENT_TYPES_PART = "/[Content_Types].xml";
+export declare class OoxmlPackage {
+    #private;
+    /** The original bytes, never mutated. */
+    readonly original: Uint8Array;
+    /** Absolute part names in archive order; directory markers are left out. */
+    readonly partNames: readonly string[];
+    private constructor();
+    /** Parses the central directory; parts are inflated on first use. */
+    static open(bytes: Uint8Array, options: OpenOptions): Promise<OoxmlPackage>;
+    /** The archive behind the package, for the writer. */
+    get archive(): ZipArchive;
+    get limits(): ResourceLimits;
+    /** Whether a part exists in the current state, overlay included. */
+    has(name: string): boolean;
+    /** Part names in the current state: archive order, then additions. */
+    get currentPartNames(): readonly string[];
+    /** Names of the parts that differ from the original: changed, added and removed. */
+    get changedParts(): readonly string[];
+    get revision(): number;
+    /** From [Content_Types].xml: an Override, else the Default for the extension. */
+    contentTypeOf(name: string): Promise<string | undefined>;
+    /** The content-type model of the current state. */
+    contentTypes(): Promise<ContentTypes>;
+    /** The relationships of a part, or of the package for "/". */
+    relationships(name: string, signal?: AbortSignal): Promise<RelationshipSet>;
+    /** Resolves a relationship target against its source part to an absolute name. */
+    resolve(sourcePart: string, target: string): string;
+    transaction(): PackageTransaction;
+    /** The ZIP entry behind a part. */
+    entry(name: string): ZipEntry | undefined;
+    /** The current bytes of a part: the overlay's when changed, else the original's. */
+    part(name: string, signal?: AbortSignal): Promise<Uint8Array>;
+    /**
+     * A part decoded and scanned, cached until the part changes. A part that
+     * is not UTF-8 is `unsupported-part`; one that does not parse is
+     * `malformed-xml`.
+     */
+    xml(name: string, signal?: AbortSignal): Promise<XmlPart>;
+    /** The original bytes of a part, inflated once and cached; ignores the overlay. */
+    originalPart(name: string, signal?: AbortSignal): Promise<Uint8Array>;
+    /**
+     * Replaces the overlay with one that has `changes` applied: replaced parts
+     * (existing names) and added parts (new names) in `set`, and `remove`.
+     * Used by transactions; the previous overlay stays reachable through its
+     * snapshot.
+     */
+    applyOverlay(changes: {
+        readonly set: ReadonlyMap<string, Uint8Array>;
+        readonly remove: ReadonlySet<string>;
+    }): PackageSnapshot;
+    /** The overlay as it is now, by reference; restore it later in O(1). */
+    snapshot(): PackageSnapshot;
+    /**
+     * Swaps the overlay back. Parts scanned after the snapshot describe a
+     * state that is gone (and a later commit could reach the same revision
+     * number with other content), so the scan cache is dropped. Other
+     * snapshots stay: a caller may restore a later one again.
+     */
+    restore(snapshot: PackageSnapshot): void;
+    /** Forgets a snapshot that will not be restored, so its overlay can be collected. */
+    release(snapshot: PackageSnapshot): void;
+    /** The package bytes: the original (copied) when nothing changed. */
+    save(options?: SaveOptions, signal?: AbortSignal): Promise<Uint8Array>;
+}

package/dist/edit/ooxml/package.js

@@ -0,0 +1,233 @@
+import { ViewerError } from "../../errors.js";
+import { isDirectoryEntry, partKey, partNameOf } from "./names.js";
+import { writeZip } from "./writer.js";
+import { decodePart, scanXml } from "./xml.js";
+import { parseContentTypes, parseRelationships, } from "./opc.js";
+import { PackageTransaction } from "./transaction.js";
+import { relationshipsPartOf, resolveTarget } from "./names.js";
+import { inflateEntry, parseZip, } from "./zip.js";
+export const CONTENT_TYPES_PART = "/[Content_Types].xml";
+export class OoxmlPackage {
+    /** The original bytes, never mutated. */
+    original;
+    /** Absolute part names in archive order; directory markers are left out. */
+    partNames;
+    #archive;
+    #limits;
+    #entries = new Map();
+    #parts = new Map();
+    #overlay = {
+        revision: 0,
+        changed: new Map(),
+        added: new Map(),
+        removed: new Set(),
+    };
+    #snapshots = new Map();
+    /** Scanned parts by key, valid for the overlay revision they were scanned at. */
+    #xml = new Map();
+    constructor(archive, limits) {
+        this.original = archive.bytes;
+        this.#archive = archive;
+        this.#limits = limits;
+        const names = [];
+        for (const entry of archive.entries) {
+            if (isDirectoryEntry(entry.name))
+                continue;
+            const name = partNameOf(entry.name);
+            const key = partKey(name);
+            if (this.#entries.has(key))
+                throw new ViewerError("invalid-file", `Duplicate package part ${name}`);
+            this.#entries.set(key, entry);
+            names.push(name);
+        }
+        this.partNames = Object.freeze(names);
+        if (!this.has(CONTENT_TYPES_PART))
+            throw new ViewerError("invalid-file", "The package has no [Content_Types].xml");
+    }
+    /** Parses the central directory; parts are inflated on first use. */
+    static async open(bytes, options) {
+        if (options.signal?.aborted)
+            throw new ViewerError("aborted", "Opening the package was aborted");
+        return new OoxmlPackage(parseZip(bytes, options.limits), options.limits);
+    }
+    /** The archive behind the package, for the writer. */
+    get archive() {
+        return this.#archive;
+    }
+    get limits() {
+        return this.#limits;
+    }
+    /** Whether a part exists in the current state, overlay included. */
+    has(name) {
+        const key = partKey(name);
+        if (this.#overlay.removed.has(key))
+            return false;
+        return this.#entries.has(key) || this.#overlay.added.has(key);
+    }
+    /** Part names in the current state: archive order, then additions. */
+    get currentPartNames() {
+        const names = this.partNames.filter((name) => this.has(name));
+        for (const [, change] of this.#overlay.added)
+            names.push(change.name);
+        return names;
+    }
+    /** Names of the parts that differ from the original: changed, added and removed. */
+    get changedParts() {
+        return [
+            ...[...this.#overlay.changed.values()].map((change) => change.name),
+            ...[...this.#overlay.added.values()].map((change) => change.name),
+            ...[...this.#overlay.removed]
+                .map((key) => this.#entries.get(key)?.name ?? key)
+                .map(partNameOf),
+        ];
+    }
+    get revision() {
+        return this.#overlay.revision;
+    }
+    /** From [Content_Types].xml: an Override, else the Default for the extension. */
+    async contentTypeOf(name) {
+        return (await this.contentTypes()).typeOf(name);
+    }
+    /** The content-type model of the current state. */
+    async contentTypes() {
+        return parseContentTypes(await this.xml(CONTENT_TYPES_PART));
+    }
+    /** The relationships of a part, or of the package for "/". */
+    async relationships(name, signal) {
+        const source = name === "/" || name === "" ? "/" : partNameOf(name);
+        const relsName = relationshipsPartOf(source);
+        if (!this.has(relsName))
+            return parseRelationships(source, undefined, undefined);
+        return parseRelationships(source, relsName, await this.xml(relsName, signal));
+    }
+    /** Resolves a relationship target against its source part to an absolute name. */
+    resolve(sourcePart, target) {
+        return resolveTarget(sourcePart, target);
+    }
+    transaction() {
+        return new PackageTransaction(this);
+    }
+    /** The ZIP entry behind a part. */
+    entry(name) {
+        return this.#entries.get(partKey(name));
+    }
+    /** The current bytes of a part: the overlay's when changed, else the original's. */
+    part(name, signal) {
+        const key = partKey(name);
+        if (this.#overlay.removed.has(key))
+            return Promise.reject(this.#missing(name));
+        const change = this.#overlay.changed.get(key) ?? this.#overlay.added.get(key);
+        if (change)
+            return Promise.resolve(change.bytes.slice());
+        return this.originalPart(name, signal);
+    }
+    /**
+     * A part decoded and scanned, cached until the part changes. A part that
+     * is not UTF-8 is `unsupported-part`; one that does not parse is
+     * `malformed-xml`.
+     */
+    xml(name, signal) {
+        const key = partKey(name);
+        const revision = this.#overlay.revision;
+        const cached = this.#xml.get(key);
+        if (cached)
+            return cached.then((part) => part.revision === revision
+                ? part
+                : this.#rescan(name, key, revision, signal));
+        return this.#rescan(name, key, revision, signal);
+    }
+    #rescan(name, key, revision, signal) {
+        const pending = this.part(name, signal).then((bytes) => {
+            const partName = partNameOf(name);
+            const { text } = decodePart(partName, bytes);
+            return scanXml(partName, text, revision);
+        });
+        this.#xml.set(key, pending);
+        pending.catch(() => this.#xml.delete(key));
+        return pending;
+    }
+    /** The original bytes of a part, inflated once and cached; ignores the overlay. */
+    originalPart(name, signal) {
+        const key = partKey(name);
+        const entry = this.#entries.get(key);
+        if (!entry)
+            return Promise.reject(this.#missing(name));
+        let pending = this.#parts.get(key);
+        if (!pending) {
+            pending = inflateEntry(this.#archive, entry, this.#limits, signal);
+            this.#parts.set(key, pending);
+            pending.catch(() => this.#parts.delete(key));
+        }
+        return pending.then((bytes) => bytes.slice());
+    }
+    /**
+     * Replaces the overlay with one that has `changes` applied: replaced parts
+     * (existing names) and added parts (new names) in `set`, and `remove`.
+     * Used by transactions; the previous overlay stays reachable through its
+     * snapshot.
+     */
+    applyOverlay(changes) {
+        const changed = new Map(this.#overlay.changed);
+        const added = new Map(this.#overlay.added);
+        const removed = new Set(this.#overlay.removed);
+        for (const name of changes.remove) {
+            const key = partKey(name);
+            changed.delete(key);
+            added.delete(key);
+            if (this.#entries.has(key))
+                removed.add(key);
+        }
+        for (const [name, bytes] of changes.set) {
+            const key = partKey(name);
+            removed.delete(key);
+            const change = { name: partNameOf(name), bytes: bytes.slice() };
+            if (this.#entries.has(key))
+                changed.set(key, change);
+            else
+                added.set(key, change);
+        }
+        const revision = this.#overlay.revision + 1;
+        this.#overlay = Object.freeze({ revision, changed, added, removed });
+        return { revision };
+    }
+    /** The overlay as it is now, by reference; restore it later in O(1). */
+    snapshot() {
+        this.#snapshots.set(this.#overlay.revision, this.#overlay);
+        return { revision: this.#overlay.revision };
+    }
+    /**
+     * Swaps the overlay back. Parts scanned after the snapshot describe a
+     * state that is gone (and a later commit could reach the same revision
+     * number with other content), so the scan cache is dropped. Other
+     * snapshots stay: a caller may restore a later one again.
+     */
+    restore(snapshot) {
+        const overlay = this.#snapshots.get(snapshot.revision);
+        if (!overlay)
+            throw new ViewerError("lifecycle-error", "Unknown package snapshot", {
+                details: { revision: snapshot.revision },
+            });
+        this.#overlay = overlay;
+        this.#xml.clear();
+    }
+    /** Forgets a snapshot that will not be restored, so its overlay can be collected. */
+    release(snapshot) {
+        if (this.#overlay.revision !== snapshot.revision)
+            this.#snapshots.delete(snapshot.revision);
+    }
+    /** The package bytes: the original (copied) when nothing changed. */
+    async save(options = {}, signal) {
+        const { changed, added, removed } = this.#overlay;
+        if (changed.size === 0 && added.size === 0 && removed.size === 0)
+            return this.original.slice();
+        return writeZip(this.#archive, this.#overlay, {
+            ...(options.compression ? { compression: options.compression } : {}),
+            ...(signal ? { signal } : {}),
+        });
+    }
+    #missing(name) {
+        return new ViewerError("invalid-file", `No part ${partNameOf(name)}`, {
+            details: { part: partNameOf(name) },
+        });
+    }
+}

package/dist/edit/ooxml/patch.d.ts

@@ -0,0 +1,51 @@
+import { escapeAttribute, escapeText, type XmlElement, type XmlPart } from "./xml.js";
+export type PatchExpectation = {
+    readonly kind: "element";
+}
+/** The element starting at `at` (in the unpatched text) has this content afterwards. */
+ | {
+    readonly kind: "content";
+    readonly at: number;
+} | {
+    readonly kind: "attribute";
+    readonly at: number;
+    readonly name: string;
+    readonly value: string | undefined;
+} | {
+    readonly kind: "removed";
+    /** Where the parent starts, how many element children it has without the element, and the element's own text. */
+    readonly parentAt: number;
+    readonly count: number;
+    readonly xml: string;
+} | {
+    readonly kind: "none";
+};
+export interface XmlPatch {
+    /** Half-open range in the part's text; patches of one part must not overlap. */
+    readonly start: number;
+    readonly end: number;
+    readonly text: string;
+    readonly expect: PatchExpectation;
+}
+export declare const patches: {
+    /** Replaces the content between the tags; a self-closing element is opened. */
+    replaceContent(part: XmlPart, node: XmlElement, xml: string): XmlPatch;
+    /** Replaces the whole element with one element. */
+    replaceElement(part: XmlPart, node: XmlElement, xml: string): XmlPatch;
+    /** Removes the element and nothing around it. */
+    removeElement(part: XmlPart, node: XmlElement): XmlPatch;
+    insertBefore(part: XmlPart, node: XmlElement, xml: string): XmlPatch;
+    insertAfter(part: XmlPart, node: XmlElement, xml: string): XmlPatch;
+    /** Appends one element at the end of the content; a self-closing element is opened. */
+    appendChild(part: XmlPart, node: XmlElement, xml: string): XmlPatch;
+    setAttribute(part: XmlPart, node: XmlElement, name: string, value: string): XmlPatch;
+    removeAttribute(part: XmlPart, node: XmlElement, name: string): XmlPatch;
+    text: typeof escapeText;
+    attr: typeof escapeAttribute;
+};
+/**
+ * Applies the patches to the part's text, re-scans it and checks every
+ * expectation; returns the new part scanned at `revision`. Throws
+ * `invalid-patch` and leaves nothing behind when anything is wrong.
+ */
+export declare function applyPatches(part: XmlPart, items: readonly XmlPatch[], revision: number): XmlPart;

package/dist/edit/ooxml/patch.js

@@ -0,0 +1,250 @@
+import { ViewerError } from "../../errors.js";
+import { escapeAttribute, escapeText, scanXml, } from "./xml.js";
+export const patches = {
+    /** Replaces the content between the tags; a self-closing element is opened. */
+    replaceContent(part, node, xml) {
+        if (node.selfClosing)
+            return {
+                start: node.end - 2,
+                end: node.end,
+                text: `>${xml}</${node.name}>`,
+                expect: { kind: "content", at: node.start },
+            };
+        return {
+            start: node.contentStart,
+            end: node.contentEnd,
+            text: xml,
+            expect: { kind: "content", at: node.start },
+        };
+    },
+    /** Replaces the whole element with one element. */
+    replaceElement(part, node, xml) {
+        return {
+            start: node.start,
+            end: node.end,
+            text: xml,
+            expect: { kind: "element" },
+        };
+    },
+    /** Removes the element and nothing around it. */
+    removeElement(part, node) {
+        if (!node.parent)
+            throw new ViewerError("invalid-patch", `Part ${part.name}: the root element cannot be removed`, { details: { part: part.name } });
+        return {
+            start: node.start,
+            end: node.end,
+            text: "",
+            expect: {
+                kind: "removed",
+                parentAt: node.parent.start,
+                count: node.parent.children.length - 1,
+                xml: part.text.slice(node.start, node.end),
+            },
+        };
+    },
+    insertBefore(part, node, xml) {
+        return {
+            start: node.start,
+            end: node.start,
+            text: xml,
+            expect: { kind: "element" },
+        };
+    },
+    insertAfter(part, node, xml) {
+        return {
+            start: node.end,
+            end: node.end,
+            text: xml,
+            expect: { kind: "element" },
+        };
+    },
+    /** Appends one element at the end of the content; a self-closing element is opened. */
+    appendChild(part, node, xml) {
+        if (node.selfClosing)
+            return {
+                start: node.end - 2,
+                end: node.end,
+                text: `>${xml}</${node.name}>`,
+                expect: { kind: "content", at: node.start },
+            };
+        return {
+            start: node.contentEnd,
+            end: node.contentEnd,
+            text: xml,
+            expect: { kind: "element" },
+        };
+    },
+    setAttribute(part, node, name, value) {
+        const existing = node.attributes.find((attribute) => attribute.name === name);
+        const expect = {
+            kind: "attribute",
+            at: node.start,
+            name,
+            value,
+        };
+        if (existing)
+            return {
+                start: existing.start,
+                end: existing.end,
+                text: `${name}=${escapeAttribute(value)}`,
+                expect,
+            };
+        const at = startTagClose(part, node);
+        return {
+            start: at,
+            end: at,
+            text: ` ${name}=${escapeAttribute(value)}`,
+            expect,
+        };
+    },
+    removeAttribute(part, node, name) {
+        const existing = node.attributes.find((attribute) => attribute.name === name);
+        const expect = {
+            kind: "attribute",
+            at: node.start,
+            name,
+            value: undefined,
+        };
+        if (!existing)
+            return { start: node.start, end: node.start, text: "", expect };
+        // Take the whitespace before the attribute with it.
+        let start = existing.start;
+        while (start > node.start && /\s/.test(part.text[start - 1]))
+            start -= 1;
+        return { start, end: existing.end, text: "", expect };
+    },
+    text: escapeText,
+    attr: escapeAttribute,
+};
+/** Where the start tag's ">" or "/>" begins. */
+function startTagClose(part, node) {
+    if (node.selfClosing)
+        return node.end - 2;
+    const last = node.attributes.at(-1);
+    const from = last ? last.end : node.start + 1 + node.name.length;
+    const close = part.text.indexOf(">", from);
+    if (close < 0 || close >= node.contentStart)
+        throw new ViewerError("internal", `Start tag of ${node.name} has no close`);
+    return close;
+}
+/**
+ * Applies the patches to the part's text, re-scans it and checks every
+ * expectation; returns the new part scanned at `revision`. Throws
+ * `invalid-patch` and leaves nothing behind when anything is wrong.
+ */
+export function applyPatches(part, items, revision) {
+    const sorted = [...items].sort((a, b) => a.start - b.start || a.end - b.end);
+    let cursor = 0;
+    for (const patch of sorted) {
+        if (!Number.isInteger(patch.start) ||
+            !Number.isInteger(patch.end) ||
+            patch.start < 0 ||
+            patch.end < patch.start ||
+            patch.end > part.text.length)
+            throw invalid(part, patch, "the range is outside the part");
+        if (patch.start < cursor)
+            throw invalid(part, patch, "the ranges overlap");
+        cursor = patch.end;
+    }
+    // Build the new text from the front, remembering where each patch lands.
+    let out = "";
+    let from = 0;
+    const landed = [];
+    for (const patch of sorted) {
+        out += part.text.slice(from, patch.start);
+        landed.push(out.length);
+        out += patch.text;
+        from = patch.end;
+    }
+    out += part.text.slice(from);
+    let rescanned;
+    try {
+        rescanned = scanXml(part.name, out, revision);
+    }
+    catch (error) {
+        throw new ViewerError("invalid-patch", `Part ${part.name}: the patched part is not well-formed`, {
+            cause: error,
+            details: {
+                part: part.name,
+                reason: error instanceof Error ? error.message : String(error),
+            },
+        });
+    }
+    const byStart = new Map();
+    const stack = [rescanned.root];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        byStart.set(node.start, node);
+        for (const child of node.children)
+            stack.push(child);
+    }
+    /** Where an unpatched offset lands: shifted by every patch that ends at or before it. */
+    const mapped = (offset) => {
+        let delta = 0;
+        for (const patch of sorted) {
+            if (patch.end > offset)
+                break;
+            delta += patch.text.length - (patch.end - patch.start);
+        }
+        return offset + delta;
+    };
+    sorted.forEach((patch, index) => {
+        const at = landed[index];
+        const { expect } = patch;
+        switch (expect.kind) {
+            case "element": {
+                const node = byStart.get(at);
+                if (!node || node.end !== at + patch.text.length)
+                    throw invalid(part, patch, "the fragment does not read back as one element", rescanned.text.slice(at, at + patch.text.length));
+                break;
+            }
+            case "content": {
+                const node = byStart.get(mapped(expect.at));
+                if (!node)
+                    throw invalid(part, patch, "the patched element is gone");
+                const content = rescanned.text.slice(node.contentStart, node.contentEnd);
+                const wanted = node.selfClosing
+                    ? ""
+                    : patch.text.startsWith(">") && patch.text.endsWith(`</${node.name}>`)
+                        ? patch.text.slice(1, -(node.name.length + 3))
+                        : patch.text;
+                if (content !== wanted)
+                    throw invalid(part, patch, "the content does not read back", content);
+                break;
+            }
+            case "attribute": {
+                const node = byStart.get(mapped(expect.at));
+                if (!node)
+                    throw invalid(part, patch, "the patched element is gone");
+                const read = rescanned.attribute(node, expect.name);
+                if (read !== expect.value)
+                    throw invalid(part, patch, `attribute ${expect.name} reads back differently`, read);
+                break;
+            }
+            case "removed": {
+                const parent = byStart.get(mapped(expect.parentAt));
+                if (!parent)
+                    throw invalid(part, patch, "the removed element's parent is gone");
+                // Another patch may have put a sibling in the same place; then the
+                // removed element's own text must at least be gone from there.
+                if (parent.children.length !== expect.count &&
+                    rescanned.text.startsWith(expect.xml, at))
+                    throw invalid(part, patch, "the element is still there", String(parent.children.length));
+                break;
+            }
+            case "none":
+                break;
+        }
+    });
+    return rescanned;
+}
+function invalid(part, patch, reason, read) {
+    return new ViewerError("invalid-patch", `Part ${part.name}: ${reason}`, {
+        details: {
+            part: part.name,
+            range: [patch.start, patch.end],
+            reason,
+            ...(read === undefined ? {} : { read: read.slice(0, 200) }),
+        },
+    });
+}

package/dist/edit/ooxml/transaction.d.ts

@@ -0,0 +1,39 @@
+import type { ViewerWarning } from "../../contracts.js";
+import { CONTENT_TYPES_NAMESPACE } from "./opc.js";
+import type { OoxmlPackage } from "./package.js";
+import { type XmlPatch } from "./patch.js";
+import { type XmlPart } from "./xml.js";
+export interface CommittedChange {
+    readonly changedParts: readonly string[];
+    readonly addedParts: readonly string[];
+    readonly removedParts: readonly string[];
+    /** One per relationship whose internal target no longer exists. */
+    readonly warnings: readonly ViewerWarning[];
+}
+export declare class PackageTransaction {
+    #private;
+    constructor(pkg: OoxmlPackage);
+    /** Patches of one scanned part; the scan must be of the current revision. */
+    patch(part: XmlPart, items: readonly XmlPatch[]): void;
+    /** Adds or replaces a part; `contentType` registers it unless a Default covers the extension. */
+    setPart(name: string, bytes: Uint8Array, contentType?: string): void;
+    removePart(name: string): void;
+    /** Allocates the next free rId of the source's .rels part, pending adds included. */
+    addRelationship(sourcePart: string, type: string, target: string, mode?: "Internal" | "External"): Promise<string>;
+    removeRelationship(sourcePart: string, id: string): void;
+    /**
+     * Stores media once per distinct content under `folder`, registers the
+     * extension's content type when missing, and relates it to `sourcePart`.
+     */
+    addMedia(sourcePart: string, folder: string, bytes: Uint8Array, mimeType: string, relationshipType?: string): Promise<{
+        readonly part: string;
+        readonly rId: string;
+    }>;
+    /** A part name that does not exist yet, in the package or in this transaction. */
+    uniquePartName(prefix: string, extension: string): string;
+    /** Applies everything or nothing; returns what changed. */
+    commit(signal?: AbortSignal): Promise<CommittedChange>;
+}
+/** "../media/image1.png" for a target seen from a source part. */
+export declare function relativeTarget(sourcePart: string, targetPart: string): string;
+export { CONTENT_TYPES_NAMESPACE };