web-doc 0.6.2 → 0.8.0

package/dist/edit/ooxml/transaction.js

@@ -0,0 +1,316 @@
+import { ViewerError } from "../../errors.js";
+import { extensionOf, partKey, partNameOf, relationshipsPartOf, } from "./names.js";
+import { CONTENT_TYPES_NAMESPACE, extensionForMime, IMAGE_RELATIONSHIP_TYPE, parseContentTypes, parseRelationships, RELATIONSHIPS_NAMESPACE, sourceOfRelationshipsPart, } from "./opc.js";
+import { applyPatches, patches } from "./patch.js";
+import { encodePart, escapeAttribute, scanXml } from "./xml.js";
+const CONTENT_TYPES = "/[Content_Types].xml";
+const XML_HEADER = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n';
+export class PackageTransaction {
+    #pkg;
+    #revision;
+    #patches = new Map();
+    #set = new Map();
+    #removed = new Set();
+    #relationshipAdds = new Map();
+    #relationshipRemoves = new Map();
+    #relationshipSets = new Map();
+    #mediaByHash = new Map();
+    #committed = false;
+    constructor(pkg) {
+        this.#pkg = pkg;
+        this.#revision = pkg.revision;
+    }
+    /** Patches of one scanned part; the scan must be of the current revision. */
+    patch(part, items) {
+        this.#open();
+        if (part.revision !== this.#revision)
+            throw new ViewerError("invalid-patch", `Part ${part.name} was scanned at another revision`, {
+                details: {
+                    part: part.name,
+                    scannedAt: part.revision,
+                    current: this.#revision,
+                },
+            });
+        const key = partKey(part.name);
+        if (this.#set.has(key) || this.#removed.has(key))
+            throw new ViewerError("invalid-patch", `Part ${part.name} is replaced or removed in this transaction`, {
+                details: { part: part.name },
+            });
+        const existing = this.#patches.get(key);
+        if (existing)
+            existing.items.push(...items);
+        else
+            this.#patches.set(key, { part, items: [...items] });
+    }
+    /** Adds or replaces a part; `contentType` registers it unless a Default covers the extension. */
+    setPart(name, bytes, contentType) {
+        this.#open();
+        const partName = partNameOf(name);
+        const key = partKey(partName);
+        if (this.#patches.has(key))
+            throw new ViewerError("invalid-patch", `Part ${partName} is patched in this transaction`, {
+                details: { part: partName },
+            });
+        this.#removed.delete(key);
+        this.#set.set(key, {
+            name: partName,
+            bytes: bytes.slice(),
+            ...(contentType ? { contentType } : {}),
+        });
+    }
+    removePart(name) {
+        this.#open();
+        const key = partKey(name);
+        this.#patches.delete(key);
+        this.#set.delete(key);
+        this.#removed.add(key);
+    }
+    /** Allocates the next free rId of the source's .rels part, pending adds included. */
+    async addRelationship(sourcePart, type, target, mode = "Internal") {
+        this.#open();
+        const source = sourcePart === "/" ? "/" : partNameOf(sourcePart);
+        const set = await this.#relationships(source);
+        const pending = this.#relationshipAdds.get(source) ?? [];
+        const taken = new Set(pending.map((add) => add.id));
+        const id = set.nextId(taken);
+        pending.push({ id, type, target, mode });
+        this.#relationshipAdds.set(source, pending);
+        return id;
+    }
+    removeRelationship(sourcePart, id) {
+        this.#open();
+        const source = sourcePart === "/" ? "/" : partNameOf(sourcePart);
+        const pending = this.#relationshipAdds.get(source);
+        if (pending) {
+            const index = pending.findIndex((add) => add.id === id);
+            if (index >= 0) {
+                pending.splice(index, 1);
+                return;
+            }
+        }
+        const removes = this.#relationshipRemoves.get(source) ?? new Set();
+        removes.add(id);
+        this.#relationshipRemoves.set(source, removes);
+    }
+    /**
+     * Stores media once per distinct content under `folder`, registers the
+     * extension's content type when missing, and relates it to `sourcePart`.
+     */
+    async addMedia(sourcePart, folder, bytes, mimeType, relationshipType = IMAGE_RELATIONSHIP_TYPE) {
+        this.#open();
+        const extension = extensionForMime(mimeType);
+        const hash = `${folder}|${extension}|${await sha256(bytes)}`;
+        let part = this.#mediaByHash.get(hash);
+        if (!part) {
+            part = this.uniquePartName(`${partNameOf(folder).replace(/\/?$/, "/")}image`, `.${extension}`);
+            this.#mediaByHash.set(hash, part);
+            const types = await this.#contentTypes();
+            const needsDefault = !types.defaults.has(extension) &&
+                ![...this.#set.values()].some((entry) => entry.contentType && extensionOf(entry.name) === extension);
+            this.setPart(part, bytes, needsDefault ? mimeType : undefined);
+        }
+        const source = sourcePart === "/" ? "/" : partNameOf(sourcePart);
+        const rId = await this.addRelationship(source, relationshipType, relativeTarget(source, part));
+        return { part, rId };
+    }
+    /** A part name that does not exist yet, in the package or in this transaction. */
+    uniquePartName(prefix, extension) {
+        const base = partNameOf(prefix);
+        for (let n = 1;; n += 1) {
+            const candidate = `${base}${n}${extension}`;
+            const key = partKey(candidate);
+            if (this.#removed.has(key))
+                return candidate;
+            if (!this.#pkg.has(candidate) && !this.#set.has(key))
+                return candidate;
+        }
+    }
+    /** Applies everything or nothing; returns what changed. */
+    async commit(signal) {
+        this.#open();
+        if (signal?.aborted)
+            throw new ViewerError("aborted", "The transaction was aborted");
+        if (this.#pkg.revision !== this.#revision)
+            throw new ViewerError("edit-conflict", "The package changed since the transaction started", {
+                details: { expected: this.#revision, actual: this.#pkg.revision },
+            });
+        const set = new Map();
+        const remove = new Set();
+        const next = this.#revision + 1;
+        // 1. Patched parts, verified by re-scan.
+        for (const { part, items } of this.#patches.values()) {
+            const patched = applyPatches(part, items, next);
+            set.set(part.name, encodePart(patched.text));
+        }
+        // 2. Replaced and added parts; XML parts must scan.
+        for (const entry of this.#set.values()) {
+            if (/\.(xml|rels)$/i.test(entry.name)) {
+                const text = new TextDecoder("utf-8", { fatal: true }).decode(entry.bytes);
+                scanXml(entry.name, text, next);
+            }
+            set.set(entry.name, entry.bytes);
+        }
+        // 3. Removed parts take their own .rels part along.
+        for (const key of this.#removed) {
+            const name = this.#pkg.currentPartNames.find((candidate) => partKey(candidate) === key) ?? key;
+            if (!this.#pkg.has(name))
+                continue;
+            remove.add(name);
+            const rels = relationshipsPartOf(name);
+            if (this.#pkg.has(rels))
+                remove.add(rels);
+        }
+        // 4. Relationship parts, as patches or new parts.
+        const relationshipSources = new Set([
+            ...this.#relationshipAdds.keys(),
+            ...this.#relationshipRemoves.keys(),
+        ]);
+        for (const source of relationshipSources) {
+            const adds = this.#relationshipAdds.get(source) ?? [];
+            const removes = this.#relationshipRemoves.get(source) ?? new Set();
+            if (adds.length === 0 && removes.size === 0)
+                continue;
+            const relsName = relationshipsPartOf(source);
+            const existing = await this.#relationships(source);
+            const fragments = adds.map((add) => `<Relationship Id=${escapeAttribute(add.id)} Type=${escapeAttribute(add.type)} Target=${escapeAttribute(add.target)}${add.mode === "External" ? ' TargetMode="External"' : ""}/>`);
+            if (existing.partName &&
+                this.#pkg.has(existing.partName) &&
+                !remove.has(existing.partName)) {
+                const part = await this.#pkg.xml(existing.partName, signal);
+                const items = [];
+                for (const id of removes) {
+                    const node = existing.byId(id)?.node;
+                    if (!node)
+                        throw new ViewerError("invalid-patch", `No relationship ${id} in ${existing.partName}`, {
+                            details: { part: existing.partName, id },
+                        });
+                    items.push(patches.removeElement(part, node));
+                }
+                // One patch per element: each must read back as one element.
+                for (const fragment of fragments)
+                    items.push(patches.appendChild(part, part.root, fragment));
+                const patched = applyPatches(part, items, next);
+                set.set(existing.partName, encodePart(patched.text));
+            }
+            else {
+                if (removes.size > 0)
+                    throw new ViewerError("invalid-patch", `No relationships part for ${source}`, { details: { part: relsName } });
+                set.set(relsName, encodePart(`${XML_HEADER}<Relationships xmlns="${RELATIONSHIPS_NAMESPACE}">${fragments.join("")}</Relationships>`));
+            }
+        }
+        // 5. Content types: Overrides for new parts with a type, Defaults for media, removals.
+        const types = await this.#contentTypes();
+        const typesPart = await this.#pkg.xml(CONTENT_TYPES, signal);
+        const typeItems = [];
+        const additions = [];
+        const seenDefaults = new Set();
+        for (const entry of this.#set.values()) {
+            if (!entry.contentType)
+                continue;
+            const extension = extensionOf(entry.name);
+            const isMedia = !/\.(xml|rels)$/i.test(entry.name) && extension !== "";
+            if (isMedia &&
+                !types.defaults.has(extension) &&
+                !seenDefaults.has(extension)) {
+                seenDefaults.add(extension);
+                additions.push(`<Default Extension=${escapeAttribute(extension)} ContentType=${escapeAttribute(entry.contentType)}/>`);
+            }
+            else if (!isMedia &&
+                types.defaults.get(extension) !== entry.contentType) {
+                const node = types.overrideNode(entry.name);
+                if (node)
+                    typeItems.push(patches.setAttribute(typesPart, node, "ContentType", entry.contentType));
+                else
+                    additions.push(`<Override PartName=${escapeAttribute(entry.name)} ContentType=${escapeAttribute(entry.contentType)}/>`);
+            }
+        }
+        for (const name of remove) {
+            const node = types.overrideNode(name);
+            if (node)
+                typeItems.push(patches.removeElement(typesPart, node));
+        }
+        for (const addition of additions)
+            typeItems.push(patches.appendChild(typesPart, typesPart.root, addition));
+        if (typeItems.length > 0) {
+            const patched = applyPatches(typesPart, typeItems, next);
+            set.set(CONTENT_TYPES, encodePart(patched.text));
+        }
+        // 6. Dangling relationship targets after the removals, as warnings.
+        const warnings = [];
+        if (remove.size > 0) {
+            const removedKeys = new Set([...remove].map(partKey));
+            for (const name of this.#pkg.currentPartNames) {
+                const source = sourceOfRelationshipsPart(name);
+                if (source === undefined || remove.has(name))
+                    continue;
+                const relsPart = set.has(name)
+                    ? scanXml(name, new TextDecoder().decode(set.get(name)), next)
+                    : await this.#pkg.xml(name, signal);
+                const rels = parseRelationships(source, name, relsPart);
+                for (const item of rels.items)
+                    if (item.targetPart && removedKeys.has(partKey(item.targetPart)))
+                        warnings.push({
+                            code: "fidelity-degraded",
+                            message: `Relationship ${item.id} of ${source} points at the removed part ${item.targetPart}`,
+                            details: {
+                                source,
+                                id: item.id,
+                                target: item.targetPart,
+                                reason: "dangling-relationship",
+                            },
+                        });
+            }
+        }
+        if (signal?.aborted)
+            throw new ViewerError("aborted", "The transaction was aborted");
+        const added = [...set.keys()].filter((name) => !this.#pkg.has(name));
+        const changed = [...set.keys()].filter((name) => this.#pkg.has(name));
+        this.#pkg.applyOverlay({ set, remove });
+        this.#committed = true;
+        return {
+            changedParts: changed,
+            addedParts: added,
+            removedParts: [...remove],
+            warnings,
+        };
+    }
+    #open() {
+        if (this.#committed)
+            throw new ViewerError("lifecycle-error", "The transaction was already committed");
+    }
+    #relationships(source) {
+        let pending = this.#relationshipSets.get(source);
+        if (!pending) {
+            pending = (async () => {
+                const relsName = relationshipsPartOf(source);
+                if (!this.#pkg.has(relsName) || this.#removed.has(partKey(relsName)))
+                    return parseRelationships(source, undefined, undefined);
+                return parseRelationships(source, relsName, await this.#pkg.xml(relsName));
+            })();
+            this.#relationshipSets.set(source, pending);
+        }
+        return pending;
+    }
+    async #contentTypes() {
+        return parseContentTypes(await this.#pkg.xml(CONTENT_TYPES));
+    }
+}
+/** "../media/image1.png" for a target seen from a source part. */
+export function relativeTarget(sourcePart, targetPart) {
+    if (sourcePart === "/")
+        return partNameOf(targetPart).slice(1);
+    const from = partNameOf(sourcePart).split("/").slice(1, -1);
+    const to = partNameOf(targetPart).split("/").slice(1);
+    let common = 0;
+    while (common < from.length &&
+        common < to.length - 1 &&
+        from[common].toLowerCase() === to[common].toLowerCase())
+        common += 1;
+    const up = from.length - common;
+    return [...Array.from({ length: up }, () => ".."), ...to.slice(common)].join("/");
+}
+async function sha256(bytes) {
+    const digest = await crypto.subtle.digest("SHA-256", bytes.slice());
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+export { CONTENT_TYPES_NAMESPACE };

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

@@ -0,0 +1,8 @@
+import type { WorkerLike } from "../../worker-client.js";
+import type { EditEngineContext } from "../engine.js";
+export interface OoxmlEditProviderOptions {
+    readonly workerUrl?: string | URL;
+    /** Test hook: supplies the worker instead of the packaged script. */
+    readonly createWorker?: () => WorkerLike;
+}
+export declare function createOoxmlEditWorker(options: OoxmlEditProviderOptions, context: EditEngineContext): WorkerLike;

package/dist/edit/ooxml/worker.js

@@ -0,0 +1,12 @@
+import { ViewerError } from "../../errors.js";
+import { packageRelativeUrl, resolveAssetUrl } from "../worker-engine.js";
+export function createOoxmlEditWorker(options, context) {
+    if (options.createWorker)
+        return options.createWorker();
+    if (typeof Worker === "undefined")
+        throw new ViewerError("edit-unsupported", `${context.format.toUpperCase()} editing requires a browser module Worker`, { details: { format: context.format, reason: "no-worker" } });
+    const url = resolveAssetUrl(options.workerUrl, context.assetBaseUrl, context.assetBaseUrl
+        ? new URL("workers/ooxml-edit-worker.js", context.assetBaseUrl)
+        : packageRelativeUrl("../../../workers/ooxml-edit-worker.js", import.meta.url));
+    return new Worker(url, { type: "module", name: "web-doc-ooxml-edit" });
+}

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

@@ -0,0 +1,21 @@
+import { type ZipArchive } from "./zip.js";
+export interface PartChange {
+    /** Absolute part name. */
+    readonly name: string;
+    readonly bytes: Uint8Array;
+}
+export interface WriteOverlay {
+    /** Replaced parts by absolute name. */
+    readonly changed: ReadonlyMap<string, PartChange>;
+    /** New parts by absolute name, in insertion order. */
+    readonly added: ReadonlyMap<string, PartChange>;
+    /** Removed parts by absolute name. */
+    readonly removed: ReadonlySet<string>;
+}
+export interface WriteOptions {
+    /** How changed and new entries are written; stored keeps output identical across engines. */
+    readonly compression?: "store" | "deflate";
+    readonly signal?: AbortSignal;
+}
+/** The package bytes for the archive with the overlay applied. */
+export declare function writeZip(archive: ZipArchive, overlay: WriteOverlay, options?: WriteOptions): Promise<Uint8Array>;

package/dist/edit/ooxml/writer.js

@@ -0,0 +1,187 @@
+import { ViewerError } from "../../errors.js";
+import { entryNameOf, partKey } from "./names.js";
+import { crc32, localRecordOf, METHOD_DEFLATED, METHOD_STORED, } from "./zip.js";
+const SIGNATURE_LOCAL = 0x04034b50;
+const SIGNATURE_CENTRAL = 0x02014b50;
+const SIGNATURE_EOCD = 0x06054b50;
+const VERSION_NEEDED = 20;
+const VERSION_MADE_BY = 0x0314; // UNIX, 2.0
+/** 1980-01-01 00:00 in MS-DOS time and date. */
+const FIXED_TIME = 0;
+const FIXED_DATE = 0x0021;
+const MAX_32 = 0xffffffff;
+const MAX_ENTRIES = 0xffff;
+const encoder = new TextEncoder();
+/** The package bytes for the archive with the overlay applied. */
+export async function writeZip(archive, overlay, options = {}) {
+    const compression = options.compression ?? "store";
+    const changed = keyed(overlay.changed);
+    const added = keyed(overlay.added);
+    const removed = new Set([...overlay.removed].map(partKey));
+    const locals = [];
+    const centrals = [];
+    let offset = 0;
+    const seen = new Set();
+    for (const entry of archive.entries) {
+        throwIfAborted(options.signal);
+        const key = partKey(entry.name);
+        seen.add(key);
+        if (removed.has(key))
+            continue;
+        const change = changed.get(key);
+        if (change) {
+            const written = await fresh(entry.name, change.bytes, compression, entry);
+            locals.push([written.local, written.data]);
+            centrals.push(written.central(offset));
+            offset += written.local.byteLength + written.data.byteLength;
+            continue;
+        }
+        const local = localRecordOf(archive, entry);
+        const record = archive.bytes.subarray(local.headerOffset, local.recordEnd);
+        locals.push([record]);
+        centrals.push(centralWithOffset(archive, entry, offset));
+        offset += record.byteLength;
+    }
+    for (const [key, change] of added) {
+        if (seen.has(key) && !removed.has(key))
+            throw new ViewerError("invalid-file", `Part ${key} is added but exists`);
+        throwIfAborted(options.signal);
+        const name = entryNameOf(change.name);
+        const written = await fresh(name, change.bytes, compression);
+        locals.push([written.local, written.data]);
+        centrals.push(written.central(offset));
+        offset += written.local.byteLength + written.data.byteLength;
+    }
+    if (centrals.length > MAX_ENTRIES)
+        throw new ViewerError("unsupported-package", "The package would need ZIP64: more than 65,535 entries");
+    const centralOffset = offset;
+    let centralLength = 0;
+    for (const central of centrals)
+        centralLength += central.byteLength;
+    if (centralOffset + centralLength > MAX_32)
+        throw new ViewerError("unsupported-package", "The package would need ZIP64: it exceeds 4 GiB");
+    const eocd = new Uint8Array(22 + archive.comment.byteLength);
+    const view = new DataView(eocd.buffer);
+    view.setUint32(0, SIGNATURE_EOCD, true);
+    view.setUint16(4, 0, true);
+    view.setUint16(6, 0, true);
+    view.setUint16(8, centrals.length, true);
+    view.setUint16(10, centrals.length, true);
+    view.setUint32(12, centralLength, true);
+    view.setUint32(16, centralOffset, true);
+    view.setUint16(20, archive.comment.byteLength, true);
+    eocd.set(archive.comment, 22);
+    const out = new Uint8Array(centralOffset + centralLength + eocd.byteLength);
+    let at = 0;
+    for (const parts of locals)
+        for (const part of parts) {
+            out.set(part, at);
+            at += part.byteLength;
+        }
+    for (const central of centrals) {
+        out.set(central, at);
+        at += central.byteLength;
+    }
+    out.set(eocd, at);
+    return out;
+}
+function keyed(parts) {
+    const map = new Map();
+    for (const change of parts.values())
+        map.set(partKey(change.name), change);
+    return map;
+}
+/** The central record of an untouched entry with the new local-header offset. */
+function centralWithOffset(archive, entry, localHeaderOffset) {
+    const record = archive.bytes.slice(entry.centralOffset, entry.centralOffset + entry.centralLength);
+    new DataView(record.buffer).setUint32(42, localHeaderOffset, true);
+    return record;
+}
+/** Fresh local and central records around stored or deflated data. */
+async function fresh(name, bytes, compression, previous) {
+    if (bytes.byteLength > MAX_32)
+        throw new ViewerError("unsupported-package", `Part ${name} would need ZIP64: it exceeds 4 GiB`);
+    const nameBytes = previous?.nameBytes ?? encoder.encode(name);
+    const extra = previous?.extra ?? new Uint8Array(0);
+    const comment = previous?.comment ?? new Uint8Array(0);
+    const method = compression === "deflate" ? METHOD_DEFLATED : METHOD_STORED;
+    const data = method === METHOD_DEFLATED ? await deflateRaw(bytes) : bytes;
+    const crc = crc32(bytes);
+    const modTime = previous?.modTime ?? FIXED_TIME;
+    const modDate = previous?.modDate ?? FIXED_DATE;
+    const local = new Uint8Array(30 + nameBytes.byteLength + extra.byteLength);
+    const localView = new DataView(local.buffer);
+    localView.setUint32(0, SIGNATURE_LOCAL, true);
+    localView.setUint16(4, VERSION_NEEDED, true);
+    localView.setUint16(6, 0, true);
+    localView.setUint16(8, method, true);
+    localView.setUint16(10, modTime, true);
+    localView.setUint16(12, modDate, true);
+    localView.setUint32(14, crc, true);
+    localView.setUint32(18, data.byteLength, true);
+    localView.setUint32(22, bytes.byteLength, true);
+    localView.setUint16(26, nameBytes.byteLength, true);
+    localView.setUint16(28, extra.byteLength, true);
+    local.set(nameBytes, 30);
+    local.set(extra, 30 + nameBytes.byteLength);
+    return {
+        local,
+        data,
+        central(localHeaderOffset) {
+            const central = new Uint8Array(46 + nameBytes.byteLength + extra.byteLength + comment.byteLength);
+            const view = new DataView(central.buffer);
+            view.setUint32(0, SIGNATURE_CENTRAL, true);
+            view.setUint16(4, previous?.versionMadeBy ?? VERSION_MADE_BY, true);
+            view.setUint16(6, VERSION_NEEDED, true);
+            view.setUint16(8, 0, true);
+            view.setUint16(10, method, true);
+            view.setUint16(12, modTime, true);
+            view.setUint16(14, modDate, true);
+            view.setUint32(16, crc, true);
+            view.setUint32(20, data.byteLength, true);
+            view.setUint32(24, bytes.byteLength, true);
+            view.setUint16(28, nameBytes.byteLength, true);
+            view.setUint16(30, extra.byteLength, true);
+            view.setUint16(32, comment.byteLength, true);
+            view.setUint16(34, 0, true);
+            view.setUint16(36, previous?.internalAttributes ?? 0, true);
+            view.setUint32(38, previous?.externalAttributes ?? 0, true);
+            view.setUint32(42, localHeaderOffset, true);
+            central.set(nameBytes, 46);
+            central.set(extra, 46 + nameBytes.byteLength);
+            central.set(comment, 46 + nameBytes.byteLength + extra.byteLength);
+            return central;
+        },
+    };
+}
+async function deflateRaw(bytes) {
+    if (typeof CompressionStream !== "function")
+        throw new ViewerError("edit-unsupported", 'This environment has no CompressionStream; save with compression: "store"', { details: { reason: "no-compression-stream" } });
+    const stream = new CompressionStream("deflate-raw");
+    const writer = stream.writable.getWriter();
+    const writing = writer
+        .write(bytes.slice())
+        .then(() => writer.close());
+    const chunks = [];
+    let total = 0;
+    const reader = stream.readable.getReader();
+    for (;;) {
+        const chunk = await reader.read();
+        if (chunk.done)
+            break;
+        chunks.push(chunk.value);
+        total += chunk.value.byteLength;
+    }
+    await writing;
+    const out = new Uint8Array(total);
+    let at = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, at);
+        at += chunk.byteLength;
+    }
+    return out;
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw new ViewerError("aborted", "Writing the package was aborted");
+}

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

@@ -0,0 +1,74 @@
+export interface XmlRange {
+    readonly kind: "declaration" | "comment" | "pi" | "cdata" | "doctype";
+    readonly start: number;
+    readonly end: number;
+}
+export interface XmlAttribute {
+    /** Qualified, as written. */
+    readonly name: string;
+    /** Entities decoded. */
+    readonly value: string;
+    /** As written, without the quotes. */
+    readonly rawValue: string;
+    /** Of the attribute name. */
+    readonly start: number;
+    /** After the closing quote. */
+    readonly end: number;
+}
+export interface XmlElement {
+    /** Qualified, as written: "p:sp". */
+    readonly name: string;
+    readonly prefix: string;
+    readonly local: string;
+    /** Resolved through xmlns declarations in scope, when declared. */
+    readonly namespace?: string;
+    readonly attributes: readonly XmlAttribute[];
+    /** "<" of the start tag. */
+    readonly start: number;
+    /** After ">" of the end tag, or after "/>". */
+    readonly end: number;
+    /** The content between the tags; empty and equal for a self-closing element. */
+    readonly contentStart: number;
+    readonly contentEnd: number;
+    readonly selfClosing: boolean;
+    readonly children: readonly XmlElement[];
+    readonly parent?: XmlElement;
+    /** Index among the parent's element children. */
+    readonly index: number;
+    /** Child-index path from the root. */
+    readonly path: readonly number[];
+}
+export interface XmlPart {
+    readonly name: string;
+    /** The decoded text the ranges index into (UTF-16 code units). */
+    readonly text: string;
+    readonly encoding: "utf-8";
+    readonly hasBom: boolean;
+    /** The overlay revision the part was scanned at; a patch from another revision is stale. */
+    readonly revision: number;
+    readonly declaration: XmlRange | undefined;
+    readonly root: XmlElement;
+    /** Comments, processing instructions, CDATA sections and a DOCTYPE, in document order. */
+    readonly opaque: readonly XmlRange[];
+    find(name: string, under?: XmlElement): XmlElement | undefined;
+    findAll(name: string, under?: XmlElement): readonly XmlElement[];
+    at(path: readonly number[]): XmlElement | undefined;
+    /** Concatenated character data of a subtree, entities decoded, CDATA included. */
+    textOf(node: XmlElement): string;
+    attribute(node: XmlElement, name: string): string | undefined;
+}
+/** Decodes a part as UTF-8; a part that is not UTF-8 cannot be patched. */
+export declare function decodePart(name: string, bytes: Uint8Array): {
+    readonly text: string;
+    readonly hasBom: boolean;
+};
+/** The bytes of a part's text; `decodePart` guarantees they equal the original. */
+export declare function encodePart(text: string): Uint8Array;
+/** Scans a part's text; throws `malformed-xml` for what it cannot read. */
+export declare function scanXml(name: string, text: string, revision?: number): XmlPart;
+/** Escapes character data for element content. */
+export declare function escapeText(value: string): string;
+/** Escapes an attribute value and quotes it with double quotes. */
+export declare function escapeAttribute(value: string): string;
+/** Decodes the predefined and numeric entities; anything else stays as written. */
+export declare function decodeEntities(raw: string): string;