web-doc 0.6.2 → 0.7.0

package/dist/edit/session.js

@@ -0,0 +1,701 @@
+import { linkedAbortController } from "../abort.js";
+import { abortError, ViewerError } from "../errors.js";
+import { assetIdOf, AssetStore, binaryFields, isAssetReference, } from "./assets.js";
+import { EditHistory } from "./history.js";
+import { assertBatchSize, checkOperations, freezeOperations, invalidOperationError, parseReference, } from "./operations.js";
+/**
+ * The format-independent editing session: validation, history, revisions,
+ * saving and the viewer refresh. Format modules wrap it to add typed methods.
+ * Calls run one at a time in call order.
+ */
+export class EditSessionController {
+    format;
+    schemas;
+    #engine;
+    #host;
+    #history;
+    #original;
+    #originalPageCount;
+    #ending = new AbortController();
+    sessionId = newSessionId();
+    /** Bytes of the last committed state; what the viewer shows and what a broken session saves. */
+    #committedBytes;
+    /** Materialized bytes of some committed states, by state id, so restores replay less. */
+    #checkpoints = new Map();
+    #checkpointBytes = 0;
+    /** Binary payloads of this session's batches, by content id. */
+    #assets = new AssetStore();
+    #state;
+    #queue = Promise.resolve();
+    #revision = 0;
+    #savedStateId = 0;
+    #ended = false;
+    /** Set when a rollback failed: the engine no longer matches the history. */
+    #broken = false;
+    constructor(engine, host, original, originalPageCount) {
+        this.format = host.format;
+        this.schemas = engine.schemas;
+        this.#engine = engine;
+        this.#host = host;
+        this.#original = original;
+        this.#committedBytes = original;
+        this.#originalPageCount = originalPageCount;
+        this.#history = new EditHistory(host.limits.maxEditHistory, originalPageCount);
+        this.#state = this.#snapshot();
+    }
+    get state() {
+        return this.#state;
+    }
+    applyJson(operations, options = {}) {
+        return this.apply(operations, options);
+    }
+    apply(operations, options = {}) {
+        // Copied before the call is queued, so what the engine sees is what the
+        // caller passed, whatever it does to its objects while waiting.
+        const batch = Array.isArray(operations)
+            ? freezeOperations(operations)
+            : operations;
+        return this.#enqueue(options.signal, async (signal) => {
+            this.#assertRevision(options);
+            assertBatchSize(batch, this.#host.limits.maxEditOperations);
+            const shapeIssues = checkOperations(batch, this.schemas);
+            if (shapeIssues.length > 0)
+                throw invalidOperationError(shapeIssues);
+            const referenceIssues = checkBatchReferences(batch);
+            if (referenceIssues.length > 0)
+                throw invalidOperationError(referenceIssues);
+            const interned = await this.#intern(batch, signal);
+            const engineIssues = await this.#engine.validate(interned, signal);
+            throwIfAborted(signal);
+            if (engineIssues.length > 0)
+                throw invalidOperationError(engineIssues);
+            // The id the history will give this state; a dry run uses the same one,
+            // so its receipt names the ids a real apply would.
+            const engineBatch = {
+                stateId: this.#history.nextStateId,
+                operations: interned,
+            };
+            if (options.dryRun) {
+                const change = await this.#transaction(signal, "apply", async () => {
+                    const result = await this.#engine.apply(engineBatch, signal);
+                    // Producing the bytes catches what only saving would; then the
+                    // working copy goes back to the current state.
+                    await this.#engine.materialize("save", {}, signal);
+                    await this.#engine.restore(this.#restoreTarget(), signal);
+                    return result;
+                });
+                return this.#receipt(true, batch.length, change.createdIds, {
+                    ...change,
+                    pageCount: change.pageCount ?? this.#history.pageCount,
+                });
+            }
+            const before = this.#history.pageCount;
+            const { change, shown } = await this.#transaction(signal, "apply", async () => {
+                const result = await this.#engine.apply(engineBatch, signal);
+                return {
+                    change: result,
+                    shown: await this.#show(signal, this.#pagesOf(result.changedPages, result.reflowFrom)),
+                };
+            });
+            this.#history.push({
+                operations: interned,
+                ...(options.label === undefined ? {} : { label: options.label }),
+                createdIds: change.createdIds,
+                removedIds: change.removedIds,
+                changedPages: shown.changedPages,
+                ...(change.reflowFrom === undefined
+                    ? {}
+                    : { reflowFrom: change.reflowFrom }),
+                pageCountBefore: before,
+                pageCountAfter: shown.pageCount,
+            });
+            this.#commit("apply", shown.changedPages, shown);
+            return this.#receipt(false, batch.length, change.createdIds, {
+                ...change,
+                changedPages: shown.changedPages,
+                pageCount: shown.pageCount,
+                warnings: [...change.warnings, ...pageCountWarning(change, shown)],
+            });
+        });
+    }
+    undo(options = {}) {
+        return this.#enqueue(options.signal, async (signal) => {
+            this.#assertRevision(options);
+            const entry = this.#history.undoEntry;
+            if (!entry)
+                return this.#noop();
+            const shown = await this.#moveTo(this.#history.position - 1, this.#pagesOf(pagesTouched(entry, entry.pageCountBefore), entry.reflowFrom), signal);
+            this.#history.undo();
+            this.#commit("undo", shown.changedPages, shown);
+            return this.#receipt(false, entry.operations.length, [], {
+                removedIds: entry.createdIds,
+                changedPages: shown.changedPages,
+                pageCount: shown.pageCount,
+                warnings: [],
+            });
+        });
+    }
+    redo(options = {}) {
+        return this.#enqueue(options.signal, async (signal) => {
+            this.#assertRevision(options);
+            const entry = this.#history.redoEntry;
+            if (!entry)
+                return this.#noop();
+            const shown = await this.#moveTo(this.#history.position + 1, this.#pagesOf(pagesTouched(entry, entry.pageCountAfter), entry.reflowFrom), signal);
+            this.#history.redo();
+            this.#commit("redo", shown.changedPages, shown);
+            return this.#receipt(false, entry.operations.length, entry.createdIds, {
+                removedIds: entry.removedIds,
+                changedPages: shown.changedPages,
+                pageCount: shown.pageCount,
+                warnings: [],
+            });
+        });
+    }
+    reset(options = {}) {
+        return this.#enqueue(options.signal, async (signal) => {
+            this.#assertRevision(options);
+            const applied = this.#history.entriesAt(this.#history.position);
+            if (this.#history.stateId === 0 && this.#history.isPristine)
+                return this.#noop();
+            const changedPages = allPages(Math.max(this.#originalPageCount, this.#history.pageCount));
+            const shown = await this.#transaction(signal, "apply", async () => {
+                await this.#engine.restore({ batches: [] }, signal);
+                return this.#show(signal, changedPages);
+            });
+            this.#history.clear();
+            this.#commit("reset", changedPages, shown);
+            return this.#receipt(false, applied.reduce((count, entry) => count + entry.operations.length, 0), [], {
+                removedIds: applied.flatMap((entry) => entry.createdIds),
+                changedPages,
+                pageCount: shown.pageCount,
+                warnings: [],
+            });
+        });
+    }
+    save(options = {}) {
+        // Format fields (the PDF save mode) travel to the engine; the signal stays.
+        const { signal: own, ...format } = options;
+        return this.#enqueue(own, async (signal) => {
+            // A session whose recovery failed still hands out what it last
+            // showed; the history state matches those bytes.
+            const { bytes, warnings } = this.#broken
+                ? { bytes: this.#committedBytes.slice(), warnings: [] }
+                : this.#history.stateId === 0
+                    ? { bytes: this.#original.slice(), warnings: [] }
+                    : await this.#materialize("save", format, signal);
+            throwIfAborted(signal);
+            return Object.freeze({
+                bytes,
+                stateToken: this.#stateToken(this.#history.stateId),
+                sessionId: this.sessionId,
+                revision: this.#revision,
+                warnings: Object.freeze([...warnings]),
+            });
+        }, { allowBroken: true });
+    }
+    /** Records that the host persisted the state a `save()` token names. */
+    markSaved(stateToken) {
+        const stateId = this.#parseStateToken(stateToken);
+        if (stateId === undefined) {
+            reportError(new ViewerError("edit-conflict", "The save token belongs to another session", { details: { stateToken, sessionId: this.sessionId } }));
+            return;
+        }
+        const wasDirty = this.#state.dirty;
+        this.#savedStateId = stateId;
+        this.#state = this.#snapshot();
+        if (wasDirty !== this.#state.dirty)
+            this.#emitState();
+    }
+    getElements(query = {}, options = {}) {
+        return this.#enqueue(options.signal, async (signal) => this.#items(await this.#engine.getElements(query, signal)));
+    }
+    getElement(id, options = {}) {
+        return this.#enqueue(options.signal, async (signal) => {
+            const item = this.#engine.getElement
+                ? await this.#engine.getElement(id, signal)
+                : (await this.#engine.getElements({}, signal)).find((element) => element.id === id);
+            return Object.freeze({
+                sessionId: this.sessionId,
+                revision: this.#revision,
+                item,
+            });
+        });
+    }
+    elementsAt(pageIndex, point, options = {}) {
+        return this.#enqueue(options.signal, async (signal) => this.#items(await this.#engine.elementsAt(pageIndex, point, signal)));
+    }
+    findText(query, options = {}) {
+        // The signal stays on this side; the rest may cross to a worker.
+        const { signal: own, ...engineOptions } = options;
+        return this.#enqueue(own, async (signal) => this.#items(await this.#engine.findText(query, engineOptions, signal)));
+    }
+    readItem(options, task) {
+        return this.#enqueue(options?.signal, async (signal) => Object.freeze({
+            sessionId: this.sessionId,
+            revision: this.#revision,
+            item: await task(this.#engine, signal),
+        }));
+    }
+    readItems(options, task) {
+        return this.#enqueue(options?.signal, async (signal) => this.#items(await task(this.#engine, signal)));
+    }
+    /** Stamps a read with the state it describes: the revision at its queue position. */
+    #items(items) {
+        return Object.freeze({
+            sessionId: this.sessionId,
+            revision: this.#revision,
+            items: Object.freeze([...items]),
+        });
+    }
+    /**
+     * Ends the session: pending calls reject with `aborted`, later calls with
+     * `lifecycle-error`, the engine is disposed and `active: false` is emitted.
+     */
+    async end() {
+        if (this.#ended)
+            return;
+        this.#ended = true;
+        this.#ending.abort(abortError());
+        await this.#queue.catch(() => undefined);
+        try {
+            await this.#engine.dispose();
+        }
+        finally {
+            this.#emitState(false);
+        }
+    }
+    get ended() {
+        return this.#ended;
+    }
+    /** False once the session ended or a failed recovery left it inconsistent. */
+    get usable() {
+        return !this.#ended && !this.#broken;
+    }
+    /** Runs `task` after every earlier call, with a signal bounded by `maxOperationMs`. */
+    #enqueue(signal, task, options = {}) {
+        // Calls made after the session ended fail at once; calls still queued
+        // when it ends are cancelled, like any other pending work.
+        if (this.#ended)
+            return Promise.reject(new ViewerError("lifecycle-error", "The edit session has ended"));
+        const run = async () => {
+            if (this.#ending.signal.aborted)
+                throw abortError();
+            if (!options.allowBroken)
+                this.#assertAlive();
+            if (signal?.aborted)
+                throw abortError();
+            const controller = linkedAbortController(signal, this.#ending.signal);
+            let timedOut = false;
+            const timer = setTimeout(() => {
+                timedOut = true;
+                controller.abort(abortError());
+            }, this.#host.limits.maxOperationMs);
+            try {
+                return await task(controller.signal);
+            }
+            catch (error) {
+                // A dead engine worker cannot be recovered; the next edit() starts anew.
+                if (error instanceof ViewerError && error.code === "worker-crashed")
+                    this.#broken = true;
+                if (timedOut)
+                    throw new ViewerError("resource-limit", "Edit operation exceeded maxOperationMs", { details: { timeoutMs: this.#host.limits.maxOperationMs } });
+                throw error;
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        };
+        const result = this.#queue.then(run, run);
+        this.#queue = result.catch(() => undefined);
+        return result;
+    }
+    /**
+     * Runs `work` against the engine and the viewer. On any failure the engine
+     * goes back to the current history state and the viewer is left untouched,
+     * so a failed call never leaks a partial change.
+     */
+    async #transaction(signal, stage, work) {
+        let failedStage = stage;
+        try {
+            return await work();
+        }
+        catch (error) {
+            if (error instanceof ViewerError && error.code === "edit-failed")
+                failedStage = error.details?.stage ?? stage;
+            await this.#rollback();
+            if (signal.aborted)
+                throw abortError();
+            if (error instanceof ViewerError &&
+                (error.code === "edit-failed" || error.code === "invalid-operation"))
+                throw error;
+            throw new ViewerError("edit-failed", `Editing failed while ${describe(failedStage)}; the document is unchanged`, { cause: error, details: { stage: failedStage } });
+        }
+    }
+    /**
+     * Materializes the working copy and shows it in the viewer in two phases:
+     * the preparation may fail or be aborted and is then discarded; the commit
+     * is synchronous and cannot fail, so once it ran the call completes
+     * whatever its signal says.
+     */
+    /** The engine's bytes with their warnings; an engine without the richer form warns of nothing. */
+    async #materialize(purpose, options, signal) {
+        if (this.#engine.materializeDocument)
+            return this.#engine.materializeDocument(purpose, options, signal);
+        return {
+            bytes: await this.#engine.materialize(purpose, options, signal),
+            warnings: [],
+        };
+    }
+    /**
+     * The pages a change repaints: the engine's list, or for a reflow every
+     * page from the paragraph's first page (asked of the host before the
+     * document is replaced) to the end of the shown document.
+     */
+    #pagesOf(changedPages, reflowFrom) {
+        if (reflowFrom === undefined)
+            return changedPages;
+        // Everything from the reflowed paragraph's page on, and the pages
+        // the batch names before it (an undo that moves a paragraph back).
+        const first = Math.min(this.#host.pageOf?.(reflowFrom) ?? 0, changedPages[0] ?? Number.POSITIVE_INFINITY);
+        return (pageCount) => Array.from({ length: Math.max(0, pageCount - first) }, (_, index) => first + index);
+    }
+    async #show(signal, changedPages) {
+        let bytes;
+        try {
+            ({ bytes } = await this.#materialize("show", {}, signal));
+        }
+        catch (error) {
+            throw stageError("materialize", error);
+        }
+        throwIfAborted(signal);
+        let prepared;
+        try {
+            prepared = await this.#host.prepareDocument(bytes, signal);
+        }
+        catch (error) {
+            throw stageError("reopen", error);
+        }
+        if (signal.aborted) {
+            this.#host.discardDocument(prepared);
+            throw abortError();
+        }
+        const pages = Object.freeze(typeof changedPages === "function"
+            ? [...changedPages(prepared.pageCount)]
+            : [...changedPages]);
+        return {
+            bytes,
+            pageCount: this.#host.commitDocument(prepared, pages),
+            changedPages: pages,
+        };
+    }
+    async #moveTo(position, changedPages, signal) {
+        return this.#transaction(signal, "apply", async () => {
+            await this.#engine.restore(this.#restoreTarget(position), signal);
+            return this.#show(signal, changedPages);
+        });
+    }
+    async #rollback() {
+        // Recovery must finish even when the caller's signal is gone, so it gets
+        // a fresh budget of its own.
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(abortError()), this.#host.limits.maxOperationMs);
+        try {
+            await this.#engine.restore(this.#restoreTarget(), controller.signal);
+        }
+        catch {
+            this.#broken = true;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    #commit(reason, changedPages, shown) {
+        this.#committedBytes = shown.bytes;
+        if (reason === "apply")
+            this.#keepCheckpoint(shown.bytes);
+        else if (reason === "reset")
+            this.#dropCheckpoints();
+        this.#revision += 1;
+        this.#state = this.#snapshot();
+        this.#emitState();
+        this.#emit("documentchange", {
+            sessionId: this.sessionId,
+            revision: this.#revision,
+            reason,
+            changedPages: Object.freeze([...changedPages]),
+            pageCount: shown.pageCount,
+        });
+    }
+    /** Hands an event to the host; a throwing listener is reported, never propagated. */
+    #emit(type, event) {
+        try {
+            this.#host.emit(type, event);
+        }
+        catch (error) {
+            reportError(error);
+        }
+    }
+    addAsset(data, options = {}) {
+        return this.#enqueue(options.signal, async (signal) => {
+            if (data.byteLength > this.#host.limits.maxInputBytes)
+                throw new ViewerError("resource-limit", "Asset exceeds maxInputBytes", {
+                    details: {
+                        actual: data.byteLength,
+                        limit: this.#host.limits.maxInputBytes,
+                    },
+                });
+            return this.#register(data.slice(), signal);
+        });
+    }
+    /** Stores bytes under their content id and hands them to the engine once. */
+    async #register(bytes, signal) {
+        const id = await assetIdOf(bytes);
+        if (!this.#assets.has(id)) {
+            this.#assets.set(id, bytes);
+            await this.#engine.putAsset(id, bytes, signal);
+        }
+        return id;
+    }
+    /**
+     * Replaces inline binary payloads by asset references, so the history
+     * holds references only; unknown references are reported like any issue.
+     */
+    async #intern(batch, signal) {
+        const issues = [];
+        const result = [];
+        for (const [operationIndex, operation] of batch.entries()) {
+            const fields = binaryFields(this.schemas.operations[operation.op]);
+            if (fields.length === 0) {
+                result.push(operation);
+                continue;
+            }
+            const patched = { ...operation };
+            for (const field of fields) {
+                const value = patched[field];
+                if (value === undefined)
+                    continue;
+                if (isAssetReference(value)) {
+                    if (!this.#assets.has(value))
+                        issues.push({
+                            operationIndex,
+                            path: `/${field}`,
+                            code: "unknown-asset",
+                            message: `Unknown asset ${value}`,
+                        });
+                    continue;
+                }
+                const bytes = value instanceof Uint8Array
+                    ? value
+                    : Uint8Array.from(atob(value), (c) => c.charCodeAt(0));
+                patched[field] = await this.#register(bytes, signal);
+            }
+            result.push(Object.freeze(patched));
+        }
+        if (issues.length > 0)
+            throw invalidOperationError(issues);
+        return Object.freeze(result);
+    }
+    /** Keeps every stride-th committed state's bytes within the memory budget. */
+    #keepCheckpoint(bytes) {
+        const stride = Math.max(1, Math.floor(this.#host.limits.maxEditHistory / 4));
+        const stateId = this.#history.stateId;
+        // Entries dropped by a new change after an undo can never be restored.
+        const reachable = new Set(this.#history.stateIds);
+        for (const [id, kept] of this.#checkpoints)
+            if (!reachable.has(id))
+                this.#forgetCheckpoint(id, kept);
+        if (stateId % stride !== 0)
+            return;
+        const budget = this.#host.limits.maxEditCheckpointBytes;
+        if (bytes.byteLength > budget)
+            return;
+        const oldestFirst = [...this.#checkpoints.keys()].sort((a, b) => a - b);
+        while (this.#checkpointBytes + bytes.byteLength > budget &&
+            oldestFirst.length > 0) {
+            const id = oldestFirst.shift();
+            this.#forgetCheckpoint(id, this.#checkpoints.get(id));
+        }
+        this.#checkpoints.set(stateId, bytes);
+        this.#checkpointBytes += bytes.byteLength;
+    }
+    #forgetCheckpoint(id, bytes) {
+        this.#checkpoints.delete(id);
+        this.#checkpointBytes -= bytes.byteLength;
+    }
+    #dropCheckpoints() {
+        this.#checkpoints.clear();
+        this.#checkpointBytes = 0;
+    }
+    /**
+     * The cheapest way to rebuild the state at `position`: the newest
+     * checkpoint at or before it, plus the batches after that checkpoint.
+     */
+    #restoreTarget(position = this.#history.position) {
+        const entries = this.#history.entriesAt(position);
+        let last = entries.length - 1;
+        while (last >= 0 && !this.#checkpoints.has(entries[last].stateId))
+            last -= 1;
+        const batches = entries.slice(last + 1).map((entry) => ({
+            stateId: entry.stateId,
+            operations: entry.operations,
+        }));
+        return last >= 0
+            ? { base: this.#checkpoints.get(entries[last].stateId), batches }
+            : { batches };
+    }
+    #stateToken(stateId) {
+        return `${this.sessionId}:${stateId}`;
+    }
+    #parseStateToken(token) {
+        const prefix = `${this.sessionId}:`;
+        if (!token.startsWith(prefix))
+            return undefined;
+        const stateId = Number(token.slice(prefix.length));
+        return Number.isSafeInteger(stateId) && stateId >= 0 ? stateId : undefined;
+    }
+    #snapshot() {
+        return Object.freeze({
+            sessionId: this.sessionId,
+            revision: this.#revision,
+            dirty: this.#history.stateId !== this.#savedStateId,
+            canUndo: this.#history.canUndo,
+            canRedo: this.#history.canRedo,
+            pageCount: this.#history.pageCount,
+        });
+    }
+    #emitState(active = true) {
+        this.#emit("editstatechange", {
+            ...this.#state,
+            active,
+            format: this.format,
+        });
+    }
+    #receipt(dryRun, operationCount, createdIds, change) {
+        return Object.freeze({
+            sessionId: this.sessionId,
+            revision: this.#revision,
+            dryRun,
+            operationCount,
+            createdIds: Object.freeze([...createdIds]),
+            removedIds: Object.freeze([...(change.removedIds ?? [])]),
+            ...(change.remappedIds
+                ? { remappedIds: Object.freeze({ ...change.remappedIds }) }
+                : {}),
+            changedPages: Object.freeze([...change.changedPages]),
+            pageCount: change.pageCount,
+            warnings: Object.freeze(change.warnings.map((warning) => Object.freeze({ ...warning }))),
+        });
+    }
+    #noop() {
+        return this.#receipt(false, 0, [], {
+            changedPages: [],
+            pageCount: this.#history.pageCount,
+            warnings: [],
+        });
+    }
+    #assertRevision(options) {
+        const { expectedRevision, expectedSessionId } = options;
+        const staleSession = expectedSessionId !== undefined && expectedSessionId !== this.sessionId;
+        const staleRevision = expectedRevision !== undefined && expectedRevision !== this.#revision;
+        if (staleSession || staleRevision)
+            throw new ViewerError("edit-conflict", staleSession
+                ? "The session the caller read from has ended"
+                : "The document changed since it was read", {
+                details: {
+                    ...(expectedRevision === undefined ? {} : { expectedRevision }),
+                    revision: this.#revision,
+                    ...(expectedSessionId === undefined ? {} : { expectedSessionId }),
+                    sessionId: this.sessionId,
+                },
+            });
+    }
+    #assertAlive() {
+        if (this.#ended)
+            throw new ViewerError("lifecycle-error", "The edit session has ended");
+        if (this.#broken)
+            throw new ViewerError("edit-failed", "The edit session is unusable after a failed recovery", { details: { stage: "apply", recovered: false } });
+    }
+}
+function stageError(stage, cause) {
+    if (cause instanceof ViewerError && cause.code === "aborted")
+        return cause;
+    return new ViewerError("edit-failed", `Editing failed while ${describe(stage)}; the document is unchanged`, { cause, details: { stage } });
+}
+function describe(stage) {
+    switch (stage) {
+        case "apply":
+            return "applying the change";
+        case "materialize":
+            return "producing the edited file";
+        case "reopen":
+            return "reopening the edited file";
+    }
+}
+function throwIfAborted(signal) {
+    if (signal.aborted)
+        throw abortError();
+}
+/** Pages to re-render when an entry is undone or redone. */
+function pagesTouched(entry, pageCount) {
+    return entry.pageCountBefore === entry.pageCountAfter
+        ? [...entry.changedPages]
+        : allPages(pageCount);
+}
+function allPages(pageCount) {
+    return Array.from({ length: pageCount }, (_, index) => index);
+}
+/**
+ * Same-batch references: `"$<n>"` names the first element created by
+ * operation `n` of the batch, which must come earlier. The engine resolves
+ * them while applying; here only the form is checked.
+ */
+function checkBatchReferences(operations) {
+    const issues = [];
+    operations.forEach((operation, operationIndex) => {
+        const target = operation.target;
+        const reference = typeof target === "string" ? parseReference(target) : undefined;
+        if (reference === undefined)
+            return;
+        if (reference >= operationIndex)
+            issues.push({
+                operationIndex,
+                path: "/target",
+                code: "unknown-target",
+                message: `"$${reference}" must name an earlier operation of the batch`,
+            });
+    });
+    return issues;
+}
+/** The renderer owns the page count; an engine that disagrees is reported, not trusted. */
+function pageCountWarning(change, shown) {
+    if (change.pageCount === undefined || change.pageCount === shown.pageCount)
+        return [];
+    return [
+        {
+            code: "fidelity-degraded",
+            message: `The engine reports ${change.pageCount} pages but the renderer shows ${shown.pageCount}`,
+            details: { engine: change.pageCount, renderer: shown.pageCount },
+        },
+    ];
+}
+/** 128 random bits as URL-safe base64; unique across sessions and reloads. */
+function newSessionId() {
+    const bytes = globalThis.crypto.getRandomValues(new Uint8Array(16));
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary)
+        .replaceAll("+", "-")
+        .replaceAll("/", "_")
+        .replace(/=+$/, "");
+}
+/** Surfaces a listener's exception without failing the call that emitted the event. */
+export function reportError(error) {
+    const report = globalThis
+        .reportError;
+    if (report)
+        report(error);
+    else
+        console.error(error);
+}