omni-viewer-core 0.3.0 → 0.5.0

package/dist/viewers/pdf/index.js

@@ -10,12 +10,14 @@
 // alert / confirm — those are blocked inside the VS Code webview, so text
 // annotations use an inline input overlay instead.
 import { MountAbortedError, VIEWER_ROOT_CLASS } from '../types.js';
-import { createPdfController, mergeHighlightRects, PDF_ZOOM_LEVELS } from './controller.js';
-import { buildSavedPdf, mergePdfBytes, parseLayer, savedPdfName, SIDECAR_LAYER_NAME, SIDECAR_BASE_NAME } from './editing.js';
+import { createPdfController, mergeHighlightRects } from './controller.js';
+import { buildEditedPdf, buildSavedPdf, mergePdfBytes, parseLayer, savedPdfName, SIDECAR_LAYER_NAME, SIDECAR_BASE_NAME } from './editing.js';
 import { pdfViewerCss } from './styles.js';
-export { createPdfController, PDF_ZOOM_LEVELS } from './controller.js';
+export { createPdfController, PDF_MAX_ZOOM, PDF_MIN_ZOOM, PDF_ZOOM_LEVELS } from './controller.js';
 export { pdfViewerCss } from './styles.js';
-export { buildEditedPdf, mergePdfBytes, savedPdfName } from './editing.js';
+export { buildEditedPdf, buildSavedPdf, mergePdfBytes, parseLayer, savedPdfName, SIDECAR_BASE_NAME, SIDECAR_LAYER_NAME } from './editing.js';
+/** Asset key passed to `HostContext.assets.resolveAssetUrl` by default. */
+export const PDF_WORKER_ASSET_KEY = 'assets/pdfjs/pdf.worker.min.mjs';
 /** Viewer metadata — single source for the registry codegen (DESIGN.md §7). */
 export const PDF_VIEWER_META = {
     id: 'pdf',
@@ -32,6 +34,13 @@ function isPasswordError(error) {
         error !== null &&
         error.name === 'PasswordException');
 }
+export function containPdfSignatureSize(width, height, maxWidth = 120, maxHeight = 60) {
+    if (!(width > 0) || !(height > 0) || !(maxWidth > 0) || !(maxHeight > 0)) {
+        return { width: 0, height: 0 };
+    }
+    const scale = Math.min(maxWidth / width, maxHeight / height);
+    return { width: width * scale, height: height * scale };
+}
 export async function mountPdfViewer(input, container, ctx, deps, options = {}) {
     if (options.signal?.aborted)
         throw new MountAbortedError();
@@ -81,13 +90,16 @@ export async function mountPdfViewer(input, container, ctx, deps, options = {})
     status.setAttribute('aria-live', 'polite');
     frame.append(header, zoomBar, body, status);
     root.appendChild(frame);
+    const customActionCleanups = [];
     // ------------------------------------------------------------- lifecycle
     let disposed = false;
     let doc;
     let loadingTask;
     let pageObserver;
     let thumbObserver;
+    let thumbTasks = [];
     let records = [];
+    let thumbRecords = [];
     let renderEpoch = 0;
     let currentPage = 1;
     let tool = 'view';
@@ -98,15 +110,27 @@ export async function mountPdfViewer(input, container, ctx, deps, options = {})
     let pageLayout = 'single';
     let matchThemeColors = false;
     let sourceBytes = input.data;
+    const saveMode = options.saveMode ?? 'hybrid';
+    const processingMode = options.processingMode ?? 'auto';
+    const controllerOptions = {
+        ...(options.zoomLevels === undefined ? {} : { zoomLevels: options.zoomLevels }),
+        ...(options.minZoom === undefined ? {} : { minZoom: options.minZoom }),
+        ...(options.maxZoom === undefined ? {} : { maxZoom: options.maxZoom })
+    };
     /** A merge changed the document without going through the edit stack. */
     let mergedSinceSave = false;
     let pdfLib;
     let unsubscribe;
-    let controller = createPdfController(0);
+    let controller = createPdfController(0, undefined, controllerOptions);
+    let operationState = { status: 'idle' };
+    let operationController;
+    let cancelPasswordPrompt;
     /** Layout inputs of the last rebuild — annotation-only changes skip it. */
     let layoutKey = '';
     const abortListener = () => {
-        loadingTask?.destroy();
+        void loadingTask?.destroy();
+        operationController?.abort();
+        cancelPasswordPrompt?.();
     };
     options.signal?.addEventListener('abort', abortListener, { once: true });
     function throwIfAborted() {
@@ -120,14 +144,23 @@ export async function mountPdfViewer(input, container, ctx, deps, options = {})
         document.removeEventListener('keydown', keyHandler);
         document.removeEventListener('selectionchange', syncMarkupAvailability);
         options.signal?.removeEventListener('abort', abortListener);
+        operationController?.abort();
+        operationController = undefined;
+        cancelPasswordPrompt?.();
+        for (const cleanup of customActionCleanups.splice(0))
+            cleanup();
         unsubscribe?.();
         pageObserver?.disconnect();
         thumbObserver?.disconnect();
+        for (const task of thumbTasks)
+            task.cancel();
+        thumbTasks = [];
         for (const record of records) {
             record.task?.cancel();
             record.textLayer?.cancel();
         }
         records = [];
+        thumbRecords = [];
         void doc?.destroy();
         doc = undefined;
         root.replaceChildren();
@@ -156,23 +189,49 @@ export async function mountPdfViewer(input, container, ctx, deps, options = {})
     };
     document.addEventListener('keydown', keyHandler);
     // -------------------------------------------------------------- pdf.js
-    const pdfjs = await deps.loadPdfjs();
-    throwIfAborted();
-    pdfjs.GlobalWorkerOptions.workerSrc = await ctx.assets.resolveAssetUrl('assets/pdfjs/pdf.worker.min.mjs');
-    throwIfAborted();
+    let pdfjs;
+    try {
+        pdfjs = await deps.loadPdfjs();
+        throwIfAborted();
+        pdfjs.GlobalWorkerOptions.workerSrc = options.workerSrc
+            ?? await ctx.assets.resolveAssetUrl(PDF_WORKER_ASSET_KEY);
+        throwIfAborted();
+    }
+    catch (error) {
+        if (error instanceof MountAbortedError)
+            throw error;
+        ctx.logger.log('error', `pdf worker asset failed: ${String(error)}`);
+        status.textContent = t('pdf.workerLoadFailed');
+        status.classList.add('omni-pdf__status--error');
+        return {
+            get controller() { return controller; },
+            get operation() { return operationState; },
+            isDirty: () => false,
+            cancelOperation: () => undefined,
+            refreshToolbarActions: () => undefined,
+            dispose: teardown
+        };
+    }
     async function loadDocument(bytes, password) {
         const request = {
             // pdf.js transfers the buffer to its worker; keep ours intact.
-            data: bytes.slice()
+            data: bytes.slice(),
+            isEvalSupported: options.isEvalSupported ?? false
         };
         if (password !== undefined)
             request.password = password;
-        loadingTask = pdfjs.getDocument(request);
+        const task = pdfjs.getDocument(request);
+        loadingTask = task;
         try {
-            return await loadingTask.promise;
+            return await task.promise;
+        }
+        catch (error) {
+            await task.destroy();
+            throw error;
         }
         finally {
-            loadingTask = undefined;
+            if (loadingTask === task)
+                loadingTask = undefined;
         }
     }
     /**
@@ -224,10 +283,16 @@ export async function mountPdfViewer(input, container, ctx, deps, options = {})
             panel.append(inputEl, actions);
             overlay.appendChild(panel);
             frame.appendChild(overlay);
+            let finished = false;
             const finish = (value) => {
+                if (finished)
+                    return;
+                finished = true;
+                cancelPasswordPrompt = undefined;
                 overlay.remove();
                 resolve(value);
             };
+            cancelPasswordPrompt = () => finish(null);
             submit.addEventListener('click', () => finish(inputEl.value));
             cancel.addEventListener('click', () => finish(null));
             inputEl.addEventListener('keydown', (e) => {
@@ -240,7 +305,11 @@ export async function mountPdfViewer(input, container, ctx, deps, options = {})
         });
     }
     // --------------------------------------------------------------- toolbar
-    const editingAvailable = typeof deps.loadPdfLib === 'function';
+    const canUseBrowserProcessing = processingMode !== 'host' && typeof deps.loadPdfLib === 'function';
+    const canDelegateBuild = processingMode !== 'browser' && typeof deps.processing?.buildPdf === 'function';
+    const canDelegateMerge = processingMode !== 'browser' && typeof deps.processing?.mergePdfs === 'function';
+    const editingAvailable = canUseBrowserProcessing || canDelegateBuild;
+    const mergeAvailable = canUseBrowserProcessing || canDelegateMerge;
     function toolButton(labelKey, onClick, parent = toolbar) {
         const b = el('button', 'omni-pdf__tool', t(labelKey));
         b.type = 'button';
@@ -254,6 +323,9 @@ export async function mountPdfViewer(input, container, ctx, deps, options = {})
         button.title = t(reasonKey);
     }
     toolbar.appendChild(pageInfo);
+    const saveModeBadge = el('span', 'omni-pdf__save-mode', t(saveMode === 'hybrid' ? 'pdf.saveModeHybrid' : 'pdf.saveModeFlattened'));
+    saveModeBadge.title = t(saveMode === 'hybrid' ? 'pdf.saveModeHybridTitle' : 'pdf.saveModeFlattenedTitle');
+    toolbar.appendChild(saveModeBadge);
     const textBtn = toolButton('pdf.annotationText', () => {
         tool = tool === 'text' ? 'view' : 'text';
         syncToolButtons();
@@ -341,6 +413,28 @@ export async function mountPdfViewer(input, container, ctx, deps, options = {})
     const saveBtn = toolButton('pdf.save', () => void save());
     const saveAsBtn = toolButton('pdf.saveAs', () => void saveAs());
     const mergeBtn = toolButton('pdf.merge', () => void merge());
+    const customActionButtons = (options.toolbarActions ?? []).map((action) => {
+        const button = el('button', 'omni-pdf__tool omni-pdf__host-action', action.label);
+        button.type = 'button';
+        button.dataset.actionId = action.id;
+        if (action.title !== undefined)
+            button.title = action.title;
+        button.setAttribute('aria-label', action.ariaLabel ?? action.label);
+        const listener = () => {
+            try {
+                void Promise.resolve(action.onClick()).catch((error) => {
+                    ctx.logger.log('error', `pdf toolbar action ${action.id} failed: ${String(error)}`);
+                });
+            }
+            catch (error) {
+                ctx.logger.log('error', `pdf toolbar action ${action.id} failed: ${String(error)}`);
+            }
+        };
+        button.addEventListener('click', listener);
+        customActionCleanups.push(() => button.removeEventListener('click', listener));
+        toolbar.appendChild(button);
+        return { action, button };
+    });
     function syncToolButtons() {
         textBtn.setAttribute('aria-pressed', String(tool === 'text'));
         signatureBtn.setAttribute('aria-pressed', String(tool === 'signature'));
@@ -349,7 +443,7 @@ export async function mountPdfViewer(input, container, ctx, deps, options = {})
     }
     syncToolButtons();
     if (!editingAvailable) {
-        for (const b of [textBtn, signatureBtn, highlightBtn, markupMenuBtn, highlightChoiceBtn, underlineBtn, strikeoutBtn, resetBtn, saveBtn, saveAsBtn, mergeBtn]) {
+        for (const b of [textBtn, signatureBtn, highlightBtn, markupMenuBtn, highlightChoiceBtn, underlineBtn, strikeoutBtn, resetBtn, saveBtn, saveAsBtn]) {
             degrade(b, 'pdf.editingUnavailable');
         }
         highlightColorInput.disabled = true;
@@ -361,9 +455,11 @@ export async function mountPdfViewer(input, container, ctx, deps, options = {})
             degrade(saveBtn, 'common.noWriteback');
         if (!ctx.save)
             degrade(saveAsBtn, 'common.noFileSave');
-        if (!ctx.filePick)
-            degrade(mergeBtn, 'pdf.noFilePick');
     }
+    if (!ctx.filePick)
+        degrade(mergeBtn, 'pdf.noFilePick');
+    else if (!mergeAvailable)
+        degrade(mergeBtn, 'pdf.editingUnavailable');
     function syncMarkupAvailability() {
         if (!editingAvailable)
             return;
@@ -544,9 +640,9 @@ export async function mountPdfViewer(input, container, ctx, deps, options = {})
                 page: position.page,
                 x: position.x,
                 y: position.y,
-                width: 120,
-                height: 60,
-                dataUrl: image
+                width: image.width,
+                height: image.height,
+                dataUrl: image.dataUrl
             }
         });
     });
@@ -575,7 +671,8 @@ export async function mountPdfViewer(input, container, ctx, deps, options = {})
         crop.width = maxX - minX + 1 + pad * 2;
         crop.height = maxY - minY + 1 + pad * 2;
         crop.getContext('2d')?.drawImage(signatureCanvas, minX, minY, maxX - minX + 1, maxY - minY + 1, pad, pad, maxX - minX + 1, maxY - minY + 1);
-        return crop.toDataURL('image/png');
+        const size = containPdfSignatureSize(crop.width, crop.height);
+        return { dataUrl: crop.toDataURL('image/png'), ...size };
     }
     /** Rasterize user-added text for portable PDF flattening. The sidecar
      * keeps the original string, size and color, so Omni can still edit it. */
@@ -800,6 +897,7 @@ export async function mountPdfViewer(input, container, ctx, deps, options = {})
                 continue;
             }
             const overlay = el('div', 'omni-pdf__annotation');
+            overlay.dataset.annotationId = annotation.id;
             overlay.tabIndex = 0;
             overlay.setAttribute('role', 'button');
             overlay.setAttribute('aria-label', annotation.kind === 'text' ? annotation.text : t('pdf.signature'));
@@ -870,6 +968,47 @@ export async function mountPdfViewer(input, container, ctx, deps, options = {})
             record.wrapper.appendChild(overlay);
         }
     }
+    /** Mirror the page annotations onto a thumbnail as non-interactive,
+     *  scaled-down overlays so thumbs stay in sync with markup edits. */
+    function renderThumbOverlays(thumbRecord) {
+        for (const node of thumbRecord.holder.querySelectorAll('.omni-pdf__thumb-annotation')) {
+            node.remove();
+        }
+        const scale = thumbRecord.scale;
+        for (const annotation of controller.state.annotations) {
+            if (annotation.page !== thumbRecord.pageNumber)
+                continue;
+            if (annotation.kind === 'highlight' || annotation.kind === 'underline' || annotation.kind === 'strikeout') {
+                for (const rect of mergeHighlightRects(annotation.rects)) {
+                    const box = el('div', `omni-pdf__thumb-annotation omni-pdf__${annotation.kind}`);
+                    box.style.left = `${rect.x * scale}px`;
+                    box.style.top = `${rect.y * scale}px`;
+                    box.style.width = `${rect.width * scale}px`;
+                    box.style.height = `${rect.height * scale}px`;
+                    box.style.setProperty('--omni-hl-color', annotation.color);
+                    thumbRecord.holder.appendChild(box);
+                }
+                continue;
+            }
+            const overlay = el('div', 'omni-pdf__thumb-annotation');
+            overlay.style.left = `${annotation.x * scale}px`;
+            overlay.style.top = `${annotation.y * scale}px`;
+            if (annotation.kind === 'text') {
+                overlay.textContent = annotation.text;
+                overlay.style.fontSize = `${annotation.size * scale}px`;
+                overlay.style.color = annotation.color;
+            }
+            else {
+                const image = el('img');
+                image.src = annotation.dataUrl;
+                image.alt = '';
+                image.style.width = `${annotation.width * scale}px`;
+                image.style.height = `${annotation.height * scale}px`;
+                overlay.appendChild(image);
+            }
+            thumbRecord.holder.appendChild(overlay);
+        }
+    }
     // -------------------------------------------------------------- render
     async function renderPage(record, epoch) {
         if (disposed || epoch !== renderEpoch || record.rendered || record.rendering)
@@ -880,7 +1019,7 @@ export async function mountPdfViewer(input, container, ctx, deps, options = {})
         canvas.width = Math.floor(viewport.width);
         canvas.height = Math.floor(viewport.height);
         canvas.setAttribute('role', 'img');
-        canvas.setAttribute('aria-label', t('common.page', { page: record.pageNumber, pages: controller.state.pageOrder.length }));
+        canvas.setAttribute('aria-label', t('common.page', { page: record.displayNumber, pages: controller.state.pageOrder.length }));
         const canvasContext = canvas.getContext('2d');
         if (!canvasContext) {
             record.rendering = false;
@@ -941,21 +1080,24 @@ export async function mountPdfViewer(input, container, ctx, deps, options = {})
     }
     function setCurrentPage(pageNumber) {
         currentPage = pageNumber;
-        pageInput.value = String(currentPage);
+        const displayNumber = records.findIndex((record) => record.pageNumber === currentPage) + 1;
+        pageInput.value = String(Math.max(1, displayNumber));
+        pageInput.max = String(records.length);
         pageTotal.textContent = `/ ${records.length}`;
         records.forEach((record, index) => {
             thumbs.children[index]?.toggleAttribute('aria-current', record.pageNumber === currentPage);
         });
     }
     function goToPageInput() {
-        const pageNumber = Number(pageInput.value);
-        const record = records.find((item) => item.pageNumber === pageNumber);
+        const displayNumber = Number(pageInput.value);
+        const record = Number.isInteger(displayNumber) ? records[displayNumber - 1] : undefined;
         if (!record) {
-            pageInput.value = String(currentPage);
+            const currentDisplay = records.findIndex((item) => item.pageNumber === currentPage) + 1;
+            pageInput.value = String(Math.max(1, currentDisplay));
             return;
         }
         scrollToPage(record);
-        setCurrentPage(pageNumber);
+        setCurrentPage(record.pageNumber);
     }
     pageInput.addEventListener('keydown', (event) => {
         if (event.key !== 'Enter')
@@ -1026,26 +1168,32 @@ export async function mountPdfViewer(input, container, ctx, deps, options = {})
         const epoch = ++renderEpoch;
         pageObserver?.disconnect();
         thumbObserver?.disconnect();
+        for (const task of thumbTasks)
+            task.cancel();
+        thumbTasks = [];
         for (const record of records) {
             record.task?.cancel();
             record.textLayer?.cancel();
         }
         records = [];
+        thumbRecords = [];
         pages.replaceChildren();
         thumbs.replaceChildren();
         const scale = controller.state.zoom / 100;
         const pageTotal = controller.state.pageOrder.length;
         const thumbRenderers = [];
-        for (const pageNumber of controller.state.pageOrder) {
+        for (const [displayIndex, pageNumber] of controller.state.pageOrder.entries()) {
+            const displayNumber = displayIndex + 1;
             const page = await doc.getPage(pageNumber);
             if (disposed || epoch !== renderEpoch)
                 return;
             const viewport = page.getViewport({ scale });
             const wrapper = el('div', 'omni-pdf__page');
             wrapper.dataset.pageNumber = String(pageNumber);
+            wrapper.dataset.displayNumber = String(displayNumber);
             wrapper.style.width = `${viewport.width}px`;
             wrapper.style.height = `${viewport.height}px`;
-            wrapper.appendChild(el('div', 'omni-pdf__placeholder', t('common.page', { page: pageNumber, pages: pageTotal })));
+            wrapper.appendChild(el('div', 'omni-pdf__placeholder', t('common.page', { page: displayNumber, pages: pageTotal })));
             wrapper.addEventListener('click', (event) => {
                 const target = event.target;
                 if (target instanceof Element && target.closest('.omni-pdf__annotation'))
@@ -1080,6 +1228,7 @@ export async function mountPdfViewer(input, container, ctx, deps, options = {})
             pages.appendChild(wrapper);
             const record = {
                 pageNumber,
+                displayNumber,
                 page,
                 wrapper,
                 rendered: false,
@@ -1091,11 +1240,10 @@ export async function mountPdfViewer(input, container, ctx, deps, options = {})
             // --- thumbnail (lazy-rendered — docs §5: never all at once) ---
             const thumb = el('button', 'omni-pdf__thumb');
             thumb.type = 'button';
-            thumb.setAttribute('aria-label', t('common.page', { page: pageNumber, pages: pageTotal }));
+            thumb.setAttribute('aria-label', t('common.page', { page: displayNumber, pages: pageTotal }));
             const thumbCanvas = el('canvas');
-            const thumbViewport = page.getViewport({
-                scale: Math.min(0.18, 90 / (viewport.width / scale || 1))
-            });
+            const thumbScale = Math.min(0.18, 90 / (viewport.width / scale || 1));
+            const thumbViewport = page.getViewport({ scale: thumbScale });
             thumbCanvas.width = Math.floor(thumbViewport.width);
             thumbCanvas.height = Math.floor(thumbViewport.height);
             let thumbRendered = false;
@@ -1106,13 +1254,22 @@ export async function mountPdfViewer(input, container, ctx, deps, options = {})
                 const thumbContext = thumbCanvas.getContext('2d');
                 if (!thumbContext)
                     return;
-                void page
-                    .render({ canvasContext: thumbContext, viewport: thumbViewport })
-                    .promise.catch(() => undefined);
+                const task = page.render({ canvasContext: thumbContext, viewport: thumbViewport });
+                thumbTasks.push(task);
+                void task.promise
+                    .catch(() => undefined)
+                    .finally(() => {
+                    thumbTasks = thumbTasks.filter((candidate) => candidate !== task);
+                });
             };
             thumbRenderers.push({ element: thumb, render: renderThumb });
-            const label = el('span', 'omni-pdf__thumb-label', String(pageNumber));
-            thumb.append(thumbCanvas, label);
+            const label = el('span', 'omni-pdf__thumb-label', String(displayNumber));
+            const thumbHolder = el('div', 'omni-pdf__thumb-page');
+            thumbHolder.appendChild(thumbCanvas);
+            thumb.append(thumbHolder, label);
+            const thumbRecord = { pageNumber, holder: thumbHolder, scale: thumbScale };
+            thumbRecords.push(thumbRecord);
+            renderThumbOverlays(thumbRecord);
             thumb.addEventListener('click', () => {
                 // Keep thumbnail navigation inside the PDF scroll container.
                 scrollToPage(record);
@@ -1211,10 +1368,20 @@ export async function mountPdfViewer(input, container, ctx, deps, options = {})
     function refreshChrome() {
         const state = controller.state;
         zoomLevel.textContent = `${state.zoom}%`;
-        zoomOutBtn.disabled = state.zoom === PDF_ZOOM_LEVELS[0];
-        zoomInBtn.disabled = state.zoom === PDF_ZOOM_LEVELS[PDF_ZOOM_LEVELS.length - 1];
+        zoomOutBtn.disabled = state.zoom <= controller.minZoom;
+        zoomInBtn.disabled = state.zoom >= controller.maxZoom;
+        const busy = operationState.status === 'running';
         if (editingAvailable && ctx.writeback) {
-            saveBtn.disabled = !(state.dirty || mergedSinceSave);
+            saveBtn.disabled = busy || !(state.dirty || mergedSinceSave);
+        }
+        if (editingAvailable && ctx.save)
+            saveAsBtn.disabled = busy;
+        if (mergeAvailable && ctx.filePick)
+            mergeBtn.disabled = busy;
+        for (const { action, button } of customActionButtons) {
+            button.disabled = typeof action.disabled === 'function'
+                ? action.disabled()
+                : action.disabled ?? false;
         }
     }
     /** Full rebuild only when zoom / page structure changed; annotation-only
@@ -1232,6 +1399,8 @@ export async function mountPdfViewer(input, container, ctx, deps, options = {})
             if (record.rendered)
                 renderOverlays(record);
         }
+        for (const thumbRecord of thumbRecords)
+            renderThumbOverlays(thumbRecord);
     }
     function adoptController(next) {
         unsubscribe?.();
@@ -1261,80 +1430,164 @@ export async function mountPdfViewer(input, container, ctx, deps, options = {})
             })
         };
     }
+    function isOperationCancelled(error, signal) {
+        return signal.aborted || (typeof error === 'object' && error !== null
+            && error.name === 'AbortError');
+    }
+    async function runOperation(kind, work) {
+        const abortController = new AbortController();
+        operationController = abortController;
+        operationState = { status: 'running', kind };
+        refreshChrome();
+        const control = {
+            signal: abortController.signal,
+            onProgress(progress) {
+                if (operationController !== abortController || abortController.signal.aborted)
+                    return;
+                const normalized = progress === undefined
+                    ? undefined
+                    : Math.max(0, Math.min(1, progress));
+                operationState = normalized === undefined
+                    ? { status: 'running', kind }
+                    : { status: 'running', kind, progress: normalized };
+                const base = t(kind === 'merge' ? 'pdf.merging' : 'pdf.saving');
+                status.textContent = normalized === undefined
+                    ? base
+                    : `${base} ${Math.round(normalized * 100)}%`;
+            }
+        };
+        control.onProgress(undefined);
+        try {
+            const value = await work(control);
+            if (abortController.signal.aborted || disposed) {
+                throw new DOMException('PDF operation cancelled', 'AbortError');
+            }
+            operationState = { status: 'succeeded', kind };
+            return { status: 'succeeded', value };
+        }
+        catch (error) {
+            if (isOperationCancelled(error, abortController.signal)) {
+                operationState = { status: 'cancelled', kind };
+                status.textContent = t('pdf.operationCancelled');
+                return { status: 'cancelled' };
+            }
+            operationState = { status: 'failed', kind, error: String(error) };
+            return { status: 'failed' };
+        }
+        finally {
+            if (operationController === abortController)
+                operationController = undefined;
+            refreshChrome();
+        }
+    }
+    async function buildOutput(state, control) {
+        if (canDelegateBuild) {
+            return deps.processing.buildPdf({ source: sourceBytes, state, mode: saveMode }, control);
+        }
+        if (!canUseBrowserProcessing)
+            throw new Error('PDF processing service unavailable');
+        if (control.signal.aborted)
+            throw new DOMException('PDF operation cancelled', 'AbortError');
+        const lib = await ensurePdfLib();
+        const output = saveMode === 'hybrid'
+            ? await buildSavedPdf(lib, sourceBytes, state)
+            : await buildEditedPdf(lib, sourceBytes, state);
+        if (control.signal.aborted)
+            throw new DOMException('PDF operation cancelled', 'AbortError');
+        return output;
+    }
+    async function mergeOutput(second, control) {
+        if (canDelegateMerge) {
+            return deps.processing.mergePdfs({ first: sourceBytes, second }, control);
+        }
+        if (!canUseBrowserProcessing)
+            throw new Error('PDF merge service unavailable');
+        if (control.signal.aborted)
+            throw new DOMException('PDF operation cancelled', 'AbortError');
+        const lib = await ensurePdfLib();
+        const output = await mergePdfBytes(lib, sourceBytes, second);
+        if (control.signal.aborted)
+            throw new DOMException('PDF operation cancelled', 'AbortError');
+        return output;
+    }
     async function save() {
         if (!ctx.writeback || saveBtn.disabled)
             return;
-        try {
-            const lib = await ensurePdfLib();
-            // Flatten from the pristine base (not the on-disk flattened copy),
-            // embedding the sidecar so overlays stay removable on reopen. The
-            // in-memory session keeps `sourceBytes` pristine + the live layer;
-            // we only rebaseline the dirty marker.
-            const data = await buildSavedPdf(lib, sourceBytes, stateForSave());
+        const result = await runOperation('save', async (control) => {
+            const data = await buildOutput(stateForSave(), control);
             await ctx.writeback.write(data);
+        });
+        if (result.status === 'succeeded') {
             mergedSinceSave = false;
             controller.dispatch({ type: 'mark-saved' });
             refreshChrome();
             status.textContent = t('common.savedToOriginal');
         }
-        catch (error) {
-            ctx.logger.log('error', `pdf save failed: ${String(error)}`);
+        else if (result.status === 'failed') {
+            ctx.logger.log('error', `pdf save failed: ${operationState.status === 'failed' ? operationState.error : ''}`);
             status.textContent = t('common.saveFailed');
         }
     }
     async function saveAs() {
         if (!ctx.save || saveAsBtn.disabled)
             return;
-        try {
-            const lib = await ensurePdfLib();
-            // Keep the same hybrid sidecar as Save so a Save As document can
-            // be reopened in Omni Viewer with all overlays still editable.
-            // Other PDF readers continue to see the flattened result.
-            const data = await buildSavedPdf(lib, sourceBytes, stateForSave());
-            await ctx.save.saveFile(savedPdfName(input.fileName), data, 'application/pdf');
+        const result = await runOperation('save-as', async (control) => {
+            const data = await buildOutput(stateForSave(), control);
+            const saveResult = await ctx.save.saveFile(savedPdfName(input.fileName), data, 'application/pdf');
+            await options.onSaveAsComplete?.(saveResult);
+            if (saveResult?.status === 'cancelled') {
+                throw new DOMException('Save As cancelled', 'AbortError');
+            }
+        });
+        if (result.status === 'succeeded') {
             status.textContent = t('common.saved', { name: savedPdfName(input.fileName) });
         }
-        catch (error) {
-            ctx.logger.log('error', `pdf save-as failed: ${String(error)}`);
+        else if (result.status === 'failed') {
+            ctx.logger.log('error', `pdf save-as failed: ${operationState.status === 'failed' ? operationState.error : ''}`);
             status.textContent = t('common.saveFailed');
         }
     }
     async function merge() {
         if (!ctx.filePick || mergeBtn.disabled)
             return;
-        const picked = await ctx.filePick.pickFile({ accept: ['application/pdf', '.pdf'] });
+        const picked = await ctx.filePick.pickFile({
+            accept: ['application/pdf', '.pdf'],
+            ...(options.maxMergeBytes === undefined ? {} : { maxBytes: options.maxMergeBytes })
+        });
         if (!picked || disposed)
             return;
-        try {
-            status.textContent = t('pdf.merging');
-            const lib = await ensurePdfLib();
+        const result = await runOperation('merge', async (control) => {
             // `sourceBytes` is the pristine base while the controller holds
             // the live reorder/delete/annotation layer. Keep that layer and
             // append the new source pages to its current visible order.
             const previousState = controller.state;
-            const previousSourcePageCount = doc?.numPages ?? sourceBytes.length;
-            const merged = await mergePdfBytes(lib, sourceBytes, picked.data);
-            await doc?.destroy();
-            doc = await loadDocument(merged);
+            const previousSourcePageCount = doc?.numPages ?? 0;
+            const merged = await mergeOutput(picked.data, control);
+            const candidate = await loadDocument(merged);
             if (disposed) {
-                void doc.destroy();
-                return;
+                void candidate.destroy();
+                throw new DOMException('PDF operation cancelled', 'AbortError');
             }
+            const previousDocument = doc;
+            doc = candidate;
             sourceBytes = merged;
             currentPage = 1;
             // The merged pages exist only in memory until the user saves.
             mergedSinceSave = true;
             const appendedPages = Array.from({ length: Math.max(0, doc.numPages - previousSourcePageCount) }, (_, index) => previousSourcePageCount + index + 1);
-            adoptController(createPdfController(doc.numPages, {
+            adoptController(createPdfController(candidate.numPages, {
                 pageOrder: [...previousState.pageOrder, ...appendedPages],
                 annotations: previousState.annotations
-            }));
+            }, controllerOptions));
+            await previousDocument?.destroy();
             refreshChrome();
             await rebuildLayout();
+        });
+        if (result.status === 'succeeded') {
             status.textContent = t('pdf.mergeComplete');
         }
-        catch (error) {
-            ctx.logger.log('error', `pdf merge failed: ${String(error)}`);
+        else if (result.status === 'failed') {
+            ctx.logger.log('error', `pdf merge failed: ${operationState.status === 'failed' ? operationState.error : ''}`);
             status.textContent = t('pdf.mergeFailed');
         }
     }
@@ -1362,12 +1615,17 @@ export async function mountPdfViewer(input, container, ctx, deps, options = {})
             }
             status.classList.add('omni-pdf__status--error');
             // Stable failed handle: one empty controller, normal dispose.
-            const failedController = createPdfController(0);
+            const failedController = createPdfController(0, undefined, controllerOptions);
             return {
                 get controller() {
                     return failedController;
                 },
+                get operation() {
+                    return operationState;
+                },
                 isDirty: () => false,
+                cancelOperation: () => operationController?.abort(),
+                refreshToolbarActions: refreshChrome,
                 dispose: teardown
             };
         }
@@ -1379,14 +1637,33 @@ export async function mountPdfViewer(input, container, ctx, deps, options = {})
     // overlays as a removable layer.
     const sidecar = await readSidecar(doc);
     if (sidecar) {
-        await doc.destroy();
-        sourceBytes = sidecar.base;
-        doc = await loadDocument(sourceBytes, password);
-        throwIfAborted();
-        adoptController(createPdfController(doc.numPages, sidecar.layer));
+        let baseDocument;
+        try {
+            baseDocument = await loadDocument(sidecar.base, password);
+            throwIfAborted();
+        }
+        catch (error) {
+            throwIfAborted();
+            ctx.logger.log('warn', `pdf sidecar base ignored: ${String(error)}`);
+        }
+        if (baseDocument) {
+            const flattenedDocument = doc;
+            doc = baseDocument;
+            sourceBytes = sidecar.base;
+            adoptController(createPdfController(doc.numPages, sidecar.layer, controllerOptions));
+            try {
+                await flattenedDocument.destroy();
+            }
+            catch (error) {
+                ctx.logger.log('warn', `pdf flattened document cleanup failed: ${String(error)}`);
+            }
+        }
+        else {
+            adoptController(createPdfController(doc.numPages, undefined, controllerOptions));
+        }
     }
     else {
-        adoptController(createPdfController(doc.numPages));
+        adoptController(createPdfController(doc.numPages, undefined, controllerOptions));
     }
     refreshChrome();
     await rebuildLayout();
@@ -1395,7 +1672,12 @@ export async function mountPdfViewer(input, container, ctx, deps, options = {})
         get controller() {
             return controller;
         },
+        get operation() {
+            return operationState;
+        },
         isDirty: () => controller.state.dirty || mergedSinceSave,
+        cancelOperation: () => operationController?.abort(),
+        refreshToolbarActions: refreshChrome,
         dispose: teardown
     };
 }