web-doc 0.6.2 → 0.7.0

package/dist/edit/docx/engine.js

@@ -0,0 +1,473 @@
+import { ViewerError } from "../../errors.js";
+import { AssetStore } from "../assets.js";
+import { OoxmlPackage } from "../ooxml/package.js";
+import { patches } from "../ooxml/patch.js";
+import { invalidOperationError, parseReference } from "../operations.js";
+import { NO_PAGE, toElement } from "./elements.js";
+import { docxHandlers } from "./handlers.js";
+import { freshParagraphId, paragraphsOf } from "./ids.js";
+import { DocxModel } from "./model.js";
+import { issueCollector } from "./operations.js";
+import { docxOperationSchemas } from "./schemas.js";
+import { namespacePatches } from "./write.js";
+/*
+ * The DOCX edit engine: the package layer under a block index of the body
+ * story. It runs inside the OOXML edit worker in the browser and directly
+ * in Node tests. It never lays out: elements carry no geometry, and the
+ * session joins the renderer's runs on the main thread.
+ *
+ * Paragraph ids: a paragraph with a `w14:paraId` keeps it; one without is
+ * numbered from its position when the document opens, and the engine then
+ * tracks those ids by document order (`#unauthored`), writing a
+ * `w14:paraId` on every paragraph it rebuilds or creates. The shown copy
+ * carries an id on every paragraph, so the viewer's runs name the same
+ * paragraphs; the saved file carries ids only where the session wrote.
+ */
+/**
+ * The part a shown copy carries with the ids the engine owns, so a copy
+ * restored as a base knows which `w14:paraId` values to leave out of a
+ * saved file. An XML part: its content type is the one every package
+ * declares for the extension, so `[Content_Types].xml` stays untouched.
+ */
+const UNAUTHORED_PART = "/webdoc/unauthored.xml";
+const UNAUTHORED_NS = "urn:web-doc:docx-edit";
+function unauthoredPartXml(ids) {
+    const items = [...ids].map((id) => `<p id="${id}"/>`).join("");
+    return new TextEncoder().encode(`<?xml version="1.0" encoding="UTF-8" standalone="yes"?><unauthored xmlns="${UNAUTHORED_NS}">${items}</unauthored>`);
+}
+function unauthoredIdsOf(bytes) {
+    const text = new TextDecoder().decode(bytes);
+    return [...text.matchAll(/<p id="([0-9A-F]{8})"\/>/g)].map((m) => m[1]);
+}
+export class DocxEditEngine {
+    schemas = docxOperationSchemas;
+    #original;
+    #limits;
+    #assets = new AssetStore();
+    #pkg;
+    #model;
+    /** The styles and theme, read once: no operation changes them. */
+    #styles;
+    /** Ids of the paragraphs without `w14:paraId`, in document order; undefined until read from the bytes. */
+    #unauthored;
+    #disposed = false;
+    #stateId = 0;
+    constructor(original, pkg, limits) {
+        this.#original = original;
+        this.#pkg = pkg;
+        this.#limits = limits;
+    }
+    /** Opens the package and reads the block index, so a broken document fails here. */
+    static async open(bytes, limits, signal) {
+        const pkg = await OoxmlPackage.open(bytes, {
+            limits,
+            ...(signal ? { signal } : {}),
+        });
+        const engine = new DocxEditEngine(bytes, pkg, limits);
+        await engine.model(signal);
+        return engine;
+    }
+    /** The package behind the engine, for tests and the operations. */
+    get package() {
+        return this.#pkg;
+    }
+    /** The engine has no pages of its own; the renderer counts them. */
+    get pageCount() {
+        return 0;
+    }
+    /** The block index at the current revision. */
+    model(signal) {
+        this.#assertAlive();
+        const revision = this.#pkg.revision;
+        if (!this.#model)
+            return this.#startModel(signal);
+        return this.#model.then((current) => current.revision === revision ? current : this.#startModel(signal));
+    }
+    #startModel(signal) {
+        const pending = DocxModel.load(this.#pkg, signal, this.#unauthored, this.#styles).then((model) => {
+            this.#unauthored ??= [...model.unauthoredIds];
+            this.#styles ??= model.styles;
+            return model;
+        });
+        this.#model = pending;
+        pending.catch(() => {
+            if (this.#model === pending)
+                this.#model = undefined;
+        });
+        return pending;
+    }
+    async validate(operations, signal) {
+        const issues = [];
+        const base = await this.#context(0, signal);
+        for (const [index, operation] of operations.entries()) {
+            const context = { ...base, operationIndex: index };
+            const handler = docxHandlers.get(operation.op);
+            if (!handler) {
+                issues.push({
+                    operationIndex: index,
+                    path: "/op",
+                    code: "unknown-operation",
+                    message: `Unknown operation ${operation.op}`,
+                });
+                continue;
+            }
+            // A same-batch reference names an element that does not exist yet:
+            // its target is checked when the batch is applied, the rest now.
+            const referenced = referenceFields(operation);
+            const forward = referenced.find((entry) => entry.reference >= index);
+            if (forward) {
+                issues.push({
+                    operationIndex: index,
+                    path: `/${forward.field}`,
+                    code: "unknown-target",
+                    message: `"${forward.value}" must refer to an earlier operation`,
+                });
+                continue;
+            }
+            const collect = issueCollector(index, issues);
+            const skipped = referenced.map((entry) => `/${entry.field}`);
+            await handler.validate(operation, context, referenced.length === 0
+                ? collect
+                : (path, code, message) => {
+                    if (!skipped.some((prefix) => path === prefix || path.startsWith(`${prefix}/`)) &&
+                        !path.startsWith("/range"))
+                        collect(path, code, message);
+                });
+        }
+        return issues;
+    }
+    /** Plain operation arrays, as the unit tests pass them, become the next batch. */
+    async apply(input, signal) {
+        const batch = Array.isArray(input)
+            ? { stateId: this.#nextStateId(), operations: input }
+            : input;
+        this.#stateId = Math.max(this.#stateId, batch.stateId);
+        const snapshot = this.#pkg.snapshot();
+        const unauthored = this.#unauthored ? [...this.#unauthored] : undefined;
+        const createdIds = [];
+        const removedIds = [];
+        const warnings = [];
+        const createdByOperation = [];
+        const issued = new Set();
+        const remappedIds = {};
+        let reflowFrom;
+        try {
+            for (const [index, raw] of batch.operations.entries()) {
+                throwIfAborted(signal);
+                const operation = resolveReferences(raw, createdByOperation, index);
+                const handler = docxHandlers.get(operation.op);
+                if (!handler)
+                    throw new ViewerError("invalid-operation", `Unknown operation ${operation.op}`);
+                const context = await this.#context(batch.stateId, signal, index, issued);
+                const issues = [];
+                await handler.validate(operation, context, issueCollector(index, issues));
+                if (issues.length > 0)
+                    throw invalidOperationError(issues);
+                const result = await handler.apply(operation, context);
+                this.#model = undefined;
+                const gone = new Set([
+                    ...(result.stamped ?? []),
+                    ...(result.removedParagraphIds ?? []),
+                ]);
+                if (gone.size > 0 && this.#unauthored)
+                    this.#unauthored = this.#unauthored.filter((id) => !gone.has(id));
+                createdByOperation.push([...result.createdIds]);
+                createdIds.push(...result.createdIds);
+                removedIds.push(...(result.removedIds ?? []));
+                warnings.push(...result.warnings);
+                reflowFrom ??= result.reflowFrom;
+                // A table renamed twice in one batch maps its first id to its last.
+                for (const [from, to] of Object.entries(result.remappedIds ?? {})) {
+                    const origin = Object.entries(remappedIds).find(([, value]) => value === from)?.[0] ?? from;
+                    remappedIds[origin] = to;
+                }
+            }
+            // The index after the batch; an inconsistency surfaces here and
+            // rolls the batch back like any other failure.
+            await this.model(signal);
+        }
+        catch (error) {
+            // Everything the batch did, ids included, is undone.
+            this.#pkg.restore(snapshot);
+            this.#unauthored = unauthored;
+            this.#model = undefined;
+            throw error;
+        }
+        this.#pkg.release(snapshot);
+        return {
+            createdIds,
+            removedIds,
+            // A flow document reflows from the first changed paragraph; the host
+            // turns it into pages.
+            changedPages: [],
+            ...(reflowFrom === undefined ? {} : { reflowFrom }),
+            ...(Object.keys(remappedIds).length > 0 ? { remappedIds } : {}),
+            warnings,
+        };
+    }
+    #nextStateId() {
+        this.#stateId += 1;
+        return this.#stateId;
+    }
+    async #context(stateId, signal, operationIndex = 0, issued = new Set()) {
+        const model = await this.model(signal);
+        const taken = new Set([...model.takenIds, ...issued]);
+        let count = 0;
+        return {
+            pkg: this.#pkg,
+            model,
+            limits: this.#limits,
+            assets: this.#assets,
+            stateId,
+            operationIndex,
+            freshParagraphId: () => {
+                const id = freshParagraphId(stateId, operationIndex, count, taken);
+                count += 1;
+                issued.add(id);
+                taken.add(id);
+                return id;
+            },
+        };
+    }
+    async materialize(purposeOrSignal = "show", options = {}, signal = new AbortController().signal) {
+        return (await this.materializeDocument(purposeOrSignal, options, signal))
+            .bytes;
+    }
+    /**
+     * `save` is the package as the session changed it: ids written only on
+     * the paragraphs the session rebuilt or created. `show` also stamps every
+     * other paragraph with the id the engine knows it by, in a copy, so the
+     * display pre-pass and the viewer's runs name the engine's paragraphs
+     * after edits that moved paragraphs around. Without changes both are
+     * the original bytes.
+     */
+    async materializeDocument(purposeOrSignal = "show", _options = {}, signal = new AbortController().signal) {
+        this.#assertAlive();
+        const purpose = purposeOrSignal instanceof AbortSignal ? "show" : purposeOrSignal;
+        const own = purposeOrSignal instanceof AbortSignal ? purposeOrSignal : signal;
+        const bytes = await this.#pkg.save({}, own);
+        const fromShownBase = this.#pkg.has(UNAUTHORED_PART);
+        if (purpose === "save")
+            return {
+                bytes: fromShownBase ? await this.#unstamped(bytes, own) : bytes,
+                warnings: [],
+            };
+        if (this.#pkg.changedParts.length === 0 && !fromShownBase)
+            return { bytes, warnings: [] };
+        return { bytes: await this.#stamped(bytes, own), warnings: [] };
+    }
+    /**
+     * A copy of `bytes` with a `w14:paraId` on every paragraph of the main
+     * part and the engine's own ids listed in a part of their own.
+     */
+    async #stamped(bytes, signal) {
+        const model = await this.model(signal);
+        const copy = await OoxmlPackage.open(bytes, {
+            limits: this.#limits,
+            signal,
+        });
+        const part = await copy.xml(model.mainPart, signal);
+        const owned = this.#unauthored ?? [];
+        // Ids already written (by an edit, or by the shown base this state
+        // came from) stay; the rest go on the unmarked paragraphs in order.
+        const attributed = new Set();
+        for (const paragraph of paragraphsOf(part)) {
+            const id = part.attribute(paragraph, "w14:paraId");
+            if (id)
+                attributed.add(id.toUpperCase());
+        }
+        const queue = owned.filter((id) => !attributed.has(id));
+        const items = [];
+        for (const paragraph of paragraphsOf(part)) {
+            if (part.attribute(paragraph, "w14:paraId"))
+                continue;
+            const id = queue.shift();
+            if (id === undefined)
+                throw new ViewerError("internal", "The document has more unmarked paragraphs than the session knows");
+            items.push(patches.setAttribute(part, paragraph, "w14:paraId", id));
+        }
+        const list = owned.length > 0 ? unauthoredPartXml(owned) : undefined;
+        if (items.length === 0) {
+            // Already the shown form of this state: nothing to write.
+            const current = copy.has(UNAUTHORED_PART)
+                ? await copy.part(UNAUTHORED_PART, signal)
+                : undefined;
+            if (current === undefined
+                ? list === undefined
+                : list !== undefined && sameBytes(current, list))
+                return bytes;
+        }
+        const transaction = copy.transaction();
+        if (items.length > 0)
+            transaction.patch(part, [...namespacePatches(part), ...items]);
+        if (list)
+            transaction.setPart(UNAUTHORED_PART, list, "application/xml");
+        else if (copy.has(UNAUTHORED_PART))
+            transaction.removePart(UNAUTHORED_PART);
+        await transaction.commit(signal);
+        return copy.save({}, signal);
+    }
+    /**
+     * A copy of `bytes` without the ids a shown base brought: the engine's
+     * own `w14:paraId` values go, the ones an edit wrote stay, and the list
+     * part goes with them.
+     */
+    async #unstamped(bytes, signal) {
+        const model = await this.model(signal);
+        const copy = await OoxmlPackage.open(bytes, {
+            limits: this.#limits,
+            signal,
+        });
+        const part = await copy.xml(model.mainPart, signal);
+        const owned = model.unauthoredSet;
+        const items = [];
+        for (const paragraph of paragraphsOf(part)) {
+            const id = part.attribute(paragraph, "w14:paraId")?.toUpperCase();
+            if (id && owned.has(id))
+                items.push(patches.removeAttribute(part, paragraph, "w14:paraId"));
+        }
+        const transaction = copy.transaction();
+        if (items.length > 0)
+            transaction.patch(part, items);
+        if (copy.has(UNAUTHORED_PART))
+            transaction.removePart(UNAUTHORED_PART);
+        await transaction.commit(signal);
+        return copy.save({}, signal);
+    }
+    async restore(input, signal) {
+        const target = Array.isArray(input)
+            ? {
+                batches: input.map((operations, index) => ({ stateId: index + 1, operations })),
+            }
+            : input;
+        this.#assertAlive();
+        this.#pkg = await OoxmlPackage.open(target.base ?? this.#original, {
+            limits: this.#limits,
+            signal,
+        });
+        // The original has the ids its positions give; a base is a shown copy
+        // with every paragraph marked and the engine's own ids listed.
+        this.#unauthored = undefined;
+        if (this.#pkg.has(UNAUTHORED_PART))
+            this.#unauthored = unauthoredIdsOf(await this.#pkg.part(UNAUTHORED_PART, signal));
+        this.#model = undefined;
+        await this.model(signal);
+        for (const batch of target.batches)
+            await this.apply(batch, signal);
+    }
+    async putAsset(id, data, _signal) {
+        this.#assets.set(id, data);
+    }
+    /**
+     * Every element of the body story, in document order, without geometry.
+     * `pageIndex` and `intersects` are the session's to apply once the runs
+     * are joined; `kinds` filters here.
+     */
+    async getElements(query, signal) {
+        const model = await this.model(signal);
+        const out = [];
+        for (const record of model.records) {
+            if (query.kinds && !query.kinds.includes(record.kind))
+                continue;
+            out.push(toElement(model, record));
+        }
+        return out;
+    }
+    async getElement(id, signal) {
+        const record = await this.locate(id, signal);
+        return record ? toElement(await this.model(signal), record) : undefined;
+    }
+    /** The record an element id names, at the current revision. */
+    async locate(id, signal) {
+        return (await this.model(signal)).byId.get(id);
+    }
+    /** Hit-testing needs the renderer's geometry; the session answers it. */
+    async elementsAt(_pageIndex, _point, _signal) {
+        return [];
+    }
+    /**
+     * Matches in paragraph text, in document order, without rectangles or
+     * pages: the session adds those from the renderer's runs.
+     */
+    async findText(query, options, signal) {
+        if (query.length === 0)
+            return [];
+        const model = await this.model(signal);
+        // A case-insensitive regular expression keeps offsets on the original
+        // text, where a lower-cased copy can change length.
+        const needle = new RegExp(query.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), options.caseSensitive ? "g" : "gi");
+        const limit = options.maxResults ?? Number.POSITIVE_INFINITY;
+        const targets = [];
+        for (const record of model.records) {
+            if (record.kind !== "paragraph")
+                continue;
+            const text = record.text.text;
+            if (!text)
+                continue;
+            needle.lastIndex = 0;
+            while (targets.length < limit) {
+                const match = needle.exec(text);
+                if (!match)
+                    break;
+                const at = match.index;
+                const end = at + match[0].length;
+                if (match[0].length === 0)
+                    needle.lastIndex += 1;
+                targets.push({
+                    pageIndex: NO_PAGE,
+                    text: text.slice(at, end),
+                    rects: [],
+                    elementIds: [record.elementId],
+                    ranges: [
+                        {
+                            start: { elementId: record.elementId, offset: at },
+                            end: { elementId: record.elementId, offset: end },
+                        },
+                    ],
+                });
+            }
+            if (targets.length >= limit)
+                break;
+        }
+        return targets;
+    }
+    async dispose() {
+        this.#disposed = true;
+        this.#model = undefined;
+    }
+    #assertAlive() {
+        if (this.#disposed)
+            throw new ViewerError("lifecycle-error", "The DOCX engine was disposed");
+    }
+}
+const REFERENCE_FIELDS = ["target", "before", "after"];
+function referenceFields(operation) {
+    const out = [];
+    for (const field of REFERENCE_FIELDS) {
+        const value = operation[field];
+        if (typeof value !== "string")
+            continue;
+        const reference = parseReference(value);
+        if (reference !== undefined)
+            out.push({ field, value, reference });
+    }
+    return out;
+}
+/** Replaces `"$<n>"` references with the first id operation `n` created. */
+function resolveReferences(operation, created, index) {
+    let resolved = operation;
+    for (const { field, value, reference } of referenceFields(operation)) {
+        const id = reference < index ? created[reference]?.[0] : undefined;
+        if (!id)
+            throw new ViewerError("invalid-operation", `Operation ${index} refers to "${value}", which created nothing`, { details: { operationIndex: index, target: value } });
+        resolved = { ...resolved, [field]: id };
+    }
+    return resolved;
+}
+function sameBytes(a, b) {
+    return a.length === b.length && a.every((byte, index) => byte === b[index]);
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw new ViewerError("aborted", "The operation was aborted");
+}

package/dist/edit/docx/handlers.d.ts

@@ -0,0 +1,3 @@
+import type { DocxOperationHandler } from "./operations.js";
+/** Handlers by operation name; `IMPLEMENTED_OPERATIONS` in schemas.ts lists the same names. */
+export declare const docxHandlers: ReadonlyMap<string, DocxOperationHandler>;

package/dist/edit/docx/handlers.js

@@ -0,0 +1,15 @@
+import { deleteElementHandler, insertImageHandler, insertParagraphHandler, moveElementHandler, } from "./structure-ops.js";
+import { insertTableHandler, setTableCellHandler } from "./table-ops.js";
+import { replaceTextHandler, setParagraphStyleHandler, setTextStyleHandler, } from "./text-ops.js";
+/** Handlers by operation name; `IMPLEMENTED_OPERATIONS` in schemas.ts lists the same names. */
+export const docxHandlers = new Map([
+    ["replaceText", replaceTextHandler],
+    ["setTextStyle", setTextStyleHandler],
+    ["setParagraphStyle", setParagraphStyleHandler],
+    ["insertParagraph", insertParagraphHandler],
+    ["deleteElement", deleteElementHandler],
+    ["moveElement", moveElementHandler],
+    ["insertImage", insertImageHandler],
+    ["insertTable", insertTableHandler],
+    ["setTableCell", setTableCellHandler],
+]);

package/dist/edit/docx/ids.d.ts

@@ -0,0 +1,45 @@
+import type { XmlElement, XmlPart } from "../ooxml/xml.js";
+export declare const W_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
+export declare const W14_NS = "http://schemas.microsoft.com/office/word/2010/wordml";
+export declare const OFFICE_RELATIONSHIPS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/";
+/** Story parts whose paragraphs share the id sequence, in the order they are numbered. */
+export declare const STORY_RELATIONSHIP_TYPES: readonly ["http://schemas.openxmlformats.org/officeDocument/2006/relationships/header", "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footer", "http://schemas.openxmlformats.org/officeDocument/2006/relationships/footnotes", "http://schemas.openxmlformats.org/officeDocument/2006/relationships/endnotes"];
+/** Prefix of the hidden bookmarks that carry paragraph ids. */
+export declare const PARAGRAPH_BOOKMARK_PREFIX = "_wd";
+/** First bookmark id the pre-pass uses, above what Word writes. */
+export declare const BOOKMARK_ID_BASE = 7000000;
+/** Ids and bookmark numbers shared by every story part of one document. */
+export interface DocxIdState {
+    readonly taken: Set<string>;
+    generated: number;
+    bookmarkId: number;
+}
+export declare function newIdState(): DocxIdState;
+/**
+ * The paragraph id generated for the `index`-th paragraph without one, in
+ * document order, skipping ids the document already uses.
+ */
+export declare function generatedParagraphId(index: number, taken: ReadonlySet<string>): string;
+/** Every `w:p` of a part in document order, nested ones included. */
+export declare function paragraphsOf(part: XmlPart): readonly XmlElement[];
+/** Collects the ids and bookmark numbers a part already uses. */
+export declare function collectIds(part: XmlPart, state: DocxIdState): void;
+export interface ParagraphId {
+    readonly paragraph: XmlElement;
+    /** Eight upper-case hex digits. */
+    readonly id: string;
+    /** True when the file carries the id as `w14:paraId`. */
+    readonly authored: boolean;
+}
+/**
+ * The id of every paragraph of a part, numbering the unmarked ones from
+ * where `state` stands. Call it for the parts in numbering order after
+ * `collectIds` has seen all of them.
+ */
+export declare function assignParagraphIds(part: XmlPart, state: DocxIdState): readonly ParagraphId[];
+/**
+ * A fresh id for the `index`-th paragraph an operation creates: derived
+ * from the batch's state id and the operation's position, so a replay of
+ * the same batches issues the same ids, and skipping any id in use.
+ */
+export declare function freshParagraphId(stateId: number, operationIndex: number, index: number, taken: ReadonlySet<string>): string;

package/dist/edit/docx/ids.js

@@ -0,0 +1,101 @@
+/*
+ * Paragraph ids shared by the display pre-pass and the DOCX edit engine.
+ * A paragraph's id is its `w14:paraId` when the file has one; otherwise a
+ * deterministic id from its position among the unmarked paragraphs of the
+ * document, numbered part by part in one sequence (the main part first,
+ * then headers, footers, footnotes and endnotes in relationship order) and
+ * skipping every id the document already uses. Both sides walk the same
+ * paragraphs in the same order, so the pre-pass's bookmarks and the
+ * engine's element ids agree on the original bytes.
+ */
+export const W_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
+export const W14_NS = "http://schemas.microsoft.com/office/word/2010/wordml";
+export const OFFICE_RELATIONSHIPS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/";
+/** Story parts whose paragraphs share the id sequence, in the order they are numbered. */
+export const STORY_RELATIONSHIP_TYPES = [
+    `${OFFICE_RELATIONSHIPS}header`,
+    `${OFFICE_RELATIONSHIPS}footer`,
+    `${OFFICE_RELATIONSHIPS}footnotes`,
+    `${OFFICE_RELATIONSHIPS}endnotes`,
+];
+/** Prefix of the hidden bookmarks that carry paragraph ids. */
+export const PARAGRAPH_BOOKMARK_PREFIX = "_wd";
+/** First bookmark id the pre-pass uses, above what Word writes. */
+export const BOOKMARK_ID_BASE = 7_000_000;
+/** First generated id; Word keeps `w14:paraId` below 0x80000000. */
+const ID_BASE = 0x1a000000;
+const ID_STEP = 0x9e37;
+export function newIdState() {
+    return { taken: new Set(), generated: 0, bookmarkId: BOOKMARK_ID_BASE };
+}
+/**
+ * The paragraph id generated for the `index`-th paragraph without one, in
+ * document order, skipping ids the document already uses.
+ */
+export function generatedParagraphId(index, taken) {
+    let candidate = (ID_BASE + index * ID_STEP) % 0x80000000;
+    for (;;) {
+        const value = candidate.toString(16).toUpperCase().padStart(8, "0");
+        if (!taken.has(value))
+            return value;
+        candidate = (candidate + 1) % 0x80000000;
+    }
+}
+/** Every `w:p` of a part in document order, nested ones included. */
+export function paragraphsOf(part) {
+    return part.findAll("p").filter((node) => node.namespace === W_NS);
+}
+/** Collects the ids and bookmark numbers a part already uses. */
+export function collectIds(part, state) {
+    for (const node of part.findAll("bookmarkStart")) {
+        if (node.namespace !== W_NS)
+            continue;
+        const id = Number(part.attribute(node, "w:id") ?? NaN);
+        if (Number.isInteger(id) && id >= state.bookmarkId)
+            state.bookmarkId = id + 1;
+        const name = part.attribute(node, "w:name") ?? "";
+        if (name.startsWith(PARAGRAPH_BOOKMARK_PREFIX))
+            state.taken.add(name.slice(PARAGRAPH_BOOKMARK_PREFIX.length).toUpperCase());
+    }
+    for (const paragraph of paragraphsOf(part)) {
+        const existing = part.attribute(paragraph, "w14:paraId");
+        if (existing)
+            state.taken.add(existing.toUpperCase());
+    }
+}
+/**
+ * The id of every paragraph of a part, numbering the unmarked ones from
+ * where `state` stands. Call it for the parts in numbering order after
+ * `collectIds` has seen all of them.
+ */
+export function assignParagraphIds(part, state) {
+    const out = [];
+    for (const paragraph of paragraphsOf(part)) {
+        const authored = part.attribute(paragraph, "w14:paraId");
+        if (authored) {
+            out.push({ paragraph, id: authored.toUpperCase(), authored: true });
+            continue;
+        }
+        const id = generatedParagraphId(state.generated, state.taken);
+        state.taken.add(id);
+        state.generated += 1;
+        out.push({ paragraph, id, authored: false });
+    }
+    return out;
+}
+/**
+ * A fresh id for the `index`-th paragraph an operation creates: derived
+ * from the batch's state id and the operation's position, so a replay of
+ * the same batches issues the same ids, and skipping any id in use.
+ */
+export function freshParagraphId(stateId, operationIndex, index, taken) {
+    const base = (0x2a000000 + stateId * 0x10000 + operationIndex * 0x100 + index) %
+        0x80000000;
+    let candidate = base;
+    for (;;) {
+        const value = candidate.toString(16).toUpperCase().padStart(8, "0");
+        if (!taken.has(value))
+            return value;
+        candidate = (candidate + 1) % 0x80000000;
+    }
+}