omni-viewer-core 0.1.0

package/dist/viewers/pdf/controller.d.ts

@@ -0,0 +1,120 @@
+export declare const PDF_ZOOM_LEVELS: readonly [50, 75, 100, 125, 150, 200, 300];
+export type PdfZoom = number;
+export interface PdfTextAnnotation {
+    id: string;
+    kind: 'text';
+    page: number;
+    x: number;
+    y: number;
+    text: string;
+    size: number;
+    color: string;
+    /** Portable raster used when flattening text into an external PDF. */
+    rasterDataUrl?: string;
+    rasterWidth?: number;
+    rasterHeight?: number;
+}
+export interface PdfSignatureAnnotation {
+    id: string;
+    kind: 'signature';
+    page: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    dataUrl: string;
+}
+/** One rectangle of a highlight, in unscaled page coordinates. */
+export interface PdfHighlightRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * PDF.js commonly returns one client rect per text span, even for a single
+ * continuous selection. Join neighbouring spans on the same text line so
+ * the highlight is rendered as one uninterrupted range (including spaces).
+ */
+export declare function mergeHighlightRects(rects: readonly PdfHighlightRect[]): PdfHighlightRect[];
+export interface PdfHighlightAnnotation {
+    id: string;
+    kind: 'highlight';
+    page: number;
+    /** A text selection can span several lines -> several rects. */
+    rects: PdfHighlightRect[];
+    color: string;
+}
+/** A text selection rendered as a horizontal strike through each line. */
+export interface PdfStrikeoutAnnotation {
+    id: string;
+    kind: 'strikeout';
+    page: number;
+    rects: PdfHighlightRect[];
+    color: string;
+}
+/** A text selection rendered as an underline beneath each line. */
+export interface PdfUnderlineAnnotation {
+    id: string;
+    kind: 'underline';
+    page: number;
+    rects: PdfHighlightRect[];
+    color: string;
+}
+export type PdfAnnotation = PdfTextAnnotation | PdfSignatureAnnotation | PdfHighlightAnnotation | PdfStrikeoutAnnotation | PdfUnderlineAnnotation;
+export type PdfAnnotationInput = Omit<PdfTextAnnotation, 'id'> | Omit<PdfSignatureAnnotation, 'id'> | Omit<PdfHighlightAnnotation, 'id'> | Omit<PdfStrikeoutAnnotation, 'id'> | Omit<PdfUnderlineAnnotation, 'id'>;
+export interface PdfViewState {
+    zoom: PdfZoom;
+    pageOrder: readonly number[];
+    annotations: readonly PdfAnnotation[];
+    selectedAnnotationId: string | null;
+    dirty: boolean;
+}
+export type PdfAction = {
+    type: 'zoom-in';
+} | {
+    type: 'zoom-out';
+} | {
+    type: 'set-zoom';
+    zoom: number;
+} | {
+    type: 'reorder-pages';
+    from: number;
+    to: number;
+} | {
+    type: 'delete-page';
+    page: number;
+} | {
+    type: 'reset-pages';
+} | {
+    type: 'add-annotation';
+    annotation: PdfAnnotationInput;
+} | {
+    type: 'move-annotation';
+    id: string;
+    x: number;
+    y: number;
+} | {
+    type: 'remove-annotation';
+    id: string;
+} | {
+    type: 'select-annotation';
+    id: string | null;
+} | {
+    type: 'undo';
+} | {
+    type: 'redo';
+} | {
+    type: 'mark-saved';
+};
+export interface PdfController {
+    readonly state: PdfViewState;
+    dispatch(action: PdfAction): void;
+    subscribe(listener: (state: PdfViewState) => void): () => void;
+}
+/** Persisted layer used to restore an editing session (sidecar rehydration). */
+export interface PdfControllerSeed {
+    pageOrder?: readonly number[];
+    annotations?: readonly PdfAnnotation[];
+}
+export declare function createPdfController(pageCount: number, seed?: PdfControllerSeed): PdfController;

package/dist/viewers/pdf/controller.js

@@ -0,0 +1,191 @@
+export const PDF_ZOOM_LEVELS = [50, 75, 100, 125, 150, 200, 300];
+/**
+ * PDF.js commonly returns one client rect per text span, even for a single
+ * continuous selection. Join neighbouring spans on the same text line so
+ * the highlight is rendered as one uninterrupted range (including spaces).
+ */
+export function mergeHighlightRects(rects) {
+    const rows = [];
+    for (const rect of [...rects].sort((a, b) => a.y - b.y || a.x - b.x)) {
+        const center = rect.y + rect.height / 2;
+        const row = rows.at(-1);
+        if (!row) {
+            rows.push([rect]);
+            continue;
+        }
+        const rowCenter = row.reduce((sum, item) => sum + item.y + item.height / 2, 0) / row.length;
+        const rowHeight = Math.max(...row.map((item) => item.height));
+        if (Math.abs(center - rowCenter) <= Math.max(2, Math.min(rect.height, rowHeight) / 2)) {
+            row.push(rect);
+            continue;
+        }
+        rows.push([rect]);
+    }
+    return rows.flatMap((row) => {
+        const merged = [];
+        for (const rect of row.sort((a, b) => a.x - b.x)) {
+            const previous = merged.at(-1);
+            const gap = Math.max(4, Math.min(16, rect.height * 0.9));
+            if (previous && rect.x <= previous.x + previous.width + gap) {
+                const right = Math.max(previous.x + previous.width, rect.x + rect.width);
+                const bottom = Math.max(previous.y + previous.height, rect.y + rect.height);
+                previous.x = Math.min(previous.x, rect.x);
+                previous.y = Math.min(previous.y, rect.y);
+                previous.width = right - previous.x;
+                previous.height = bottom - previous.y;
+            }
+            else {
+                merged.push({ ...rect });
+            }
+        }
+        return merged;
+    });
+}
+function nearestZoom(value) {
+    return PDF_ZOOM_LEVELS.reduce((best, candidate) => Math.abs(candidate - value) < Math.abs(best - value) ? candidate : best);
+}
+/** Highest `pdf-a<n>` suffix among seeded ids, so new ids never collide. */
+function maxSequence(annotations) {
+    let max = 0;
+    for (const annotation of annotations) {
+        const n = /^pdf-a(\d+)$/.exec(annotation.id)?.[1];
+        if (n)
+            max = Math.max(max, Number(n));
+    }
+    return max;
+}
+function copyAnnotations(annotations) {
+    return annotations.map((annotation) => annotation.kind === 'highlight' || annotation.kind === 'strikeout' || annotation.kind === 'underline'
+        ? { ...annotation, rects: annotation.rects.map((rect) => ({ ...rect })) }
+        : { ...annotation });
+}
+export function createPdfController(pageCount, seed) {
+    const original = Array.from({ length: Math.max(0, Math.floor(pageCount)) }, (_, i) => i + 1);
+    const listeners = new Set();
+    let zoom = 100;
+    // A seeded order may only reference pages that still exist; an empty result
+    // falls back to the natural order so the document is never left blank.
+    const seededOrder = seed?.pageOrder?.filter((page) => page >= 1 && page <= original.length) ?? [];
+    let pageOrder = seededOrder.length > 0 ? seededOrder.slice() : original.slice();
+    let annotations = seed?.annotations
+        ? seed.annotations.filter((a) => pageOrder.includes(a.page)).map((a) => ({ ...a }))
+        : [];
+    let selectedAnnotationId = null;
+    let savedSignature = '';
+    let sequence = maxSequence(annotations);
+    const undoStack = [];
+    const redoStack = [];
+    const signature = () => JSON.stringify({ pageOrder, annotations });
+    const snapshot = () => ({
+        pageOrder: pageOrder.slice(),
+        annotations: copyAnnotations(annotations),
+        selectedAnnotationId
+    });
+    const restore = (value) => {
+        pageOrder = value.pageOrder.slice();
+        annotations = copyAnnotations(value.annotations);
+        selectedAnnotationId = value.selectedAnnotationId;
+    };
+    const state = () => ({
+        zoom, pageOrder: pageOrder.slice(), annotations: copyAnnotations(annotations),
+        selectedAnnotationId, dirty: signature() !== savedSignature
+    });
+    const emit = () => { const next = state(); for (const listener of listeners)
+        listener(next); };
+    savedSignature = signature();
+    return {
+        get state() { return state(); },
+        subscribe(listener) { listeners.add(listener); return () => listeners.delete(listener); },
+        dispatch(action) {
+            if (action.type === 'undo') {
+                const previous = undoStack.pop();
+                if (!previous)
+                    return;
+                redoStack.push(snapshot());
+                restore(previous);
+                emit();
+                return;
+            }
+            if (action.type === 'redo') {
+                const next = redoStack.pop();
+                if (!next)
+                    return;
+                undoStack.push(snapshot());
+                restore(next);
+                emit();
+                return;
+            }
+            const tracksHistory = action.type === 'reorder-pages'
+                || action.type === 'delete-page'
+                || action.type === 'reset-pages'
+                || action.type === 'add-annotation'
+                || action.type === 'move-annotation'
+                || action.type === 'remove-annotation';
+            const before = tracksHistory ? snapshot() : undefined;
+            const beforeSignature = tracksHistory ? signature() : undefined;
+            switch (action.type) {
+                case 'zoom-in': {
+                    zoom = PDF_ZOOM_LEVELS.find((level) => level > zoom)
+                        ?? PDF_ZOOM_LEVELS[PDF_ZOOM_LEVELS.length - 1];
+                    break;
+                }
+                case 'zoom-out': {
+                    zoom = [...PDF_ZOOM_LEVELS].reverse().find((level) => level < zoom)
+                        ?? PDF_ZOOM_LEVELS[0];
+                    break;
+                }
+                case 'set-zoom': {
+                    if (!Number.isFinite(action.zoom))
+                        return;
+                    zoom = Math.max(25, Math.min(400, Math.round(action.zoom)));
+                    break;
+                }
+                case 'reorder-pages': {
+                    if (!Number.isInteger(action.from) || !Number.isInteger(action.to) || action.from < 0 || action.to < 0 || action.from >= pageOrder.length || action.to >= pageOrder.length)
+                        return;
+                    const [page] = pageOrder.splice(action.from, 1);
+                    if (page !== undefined)
+                        pageOrder.splice(action.to, 0, page);
+                    break;
+                }
+                case 'delete-page':
+                    if (pageOrder.length <= 1)
+                        return;
+                    pageOrder = pageOrder.filter((page) => page !== action.page);
+                    annotations = annotations.filter((annotation) => annotation.page !== action.page);
+                    break;
+                case 'reset-pages':
+                    pageOrder = original.slice();
+                    annotations = [];
+                    selectedAnnotationId = null;
+                    break;
+                case 'add-annotation': {
+                    const annotation = action.annotation.kind === 'text'
+                        ? { ...action.annotation, id: `pdf-a${++sequence}` }
+                        : { ...action.annotation, id: `pdf-a${++sequence}` };
+                    annotations = [...annotations, annotation];
+                    break;
+                }
+                case 'move-annotation':
+                    annotations = annotations.map((a) => a.id === action.id ? { ...a, x: action.x, y: action.y } : a);
+                    break;
+                case 'remove-annotation':
+                    annotations = annotations.filter((a) => a.id !== action.id);
+                    if (selectedAnnotationId === action.id)
+                        selectedAnnotationId = null;
+                    break;
+                case 'select-annotation':
+                    selectedAnnotationId = action.id;
+                    break;
+                case 'mark-saved':
+                    savedSignature = signature();
+                    break;
+            }
+            if (before && beforeSignature !== signature()) {
+                undoStack.push(before);
+                redoStack.length = 0;
+            }
+            emit();
+        }
+    };
+}

package/dist/viewers/pdf/editing.d.ts

@@ -0,0 +1,26 @@
+import { type PdfAnnotation, type PdfViewState } from './controller.js';
+/** Type-only reference — erased at compile time. */
+export type PdfLibModule = typeof import('pdf-lib');
+export declare const SIDECAR_LAYER_NAME = "omni-viewer-layer.json";
+export declare const SIDECAR_ORIGINAL_NAME = "omni-viewer-original.pdf";
+/** Result of parsing a sidecar's layer JSON. */
+export interface ParsedLayer {
+    pageOrder: number[];
+    annotations: PdfAnnotation[];
+}
+/** Persist reordered/deleted pages plus the text/signature overlays,
+ *  flattened into the page content (portable, non-editable output). */
+export declare function buildEditedPdf(pdfLib: PdfLibModule, source: Uint8Array, state: PdfViewState): Promise<Uint8Array>;
+/**
+ * Like {@link buildEditedPdf}, but also embeds the hybrid sidecar so the
+ * omni viewer can rehydrate a removable overlay layer on reopen:
+ *   - the pristine (unflattened) source, and
+ *   - the layer JSON `{ version, pageOrder, annotations }`.
+ * External readers only ever see the flattened pages.
+ */
+export declare function buildSavedPdf(pdfLib: PdfLibModule, pristine: Uint8Array, state: PdfViewState): Promise<Uint8Array>;
+/** Parse and validate a sidecar layer JSON string; null if unusable. */
+export declare function parseLayer(text: string): ParsedLayer | null;
+/** Append every page of `second` after `first`. */
+export declare function mergePdfBytes(pdfLib: PdfLibModule, first: Uint8Array, second: Uint8Array): Promise<Uint8Array>;
+export declare function savedPdfName(name: string): string;

package/dist/viewers/pdf/editing.js

@@ -0,0 +1,265 @@
+// PDF editing helpers built on pdf-lib.
+//
+// pdf-lib is an optional peer dependency: this module never imports it at
+// runtime (ADR 14 — the base viewer entry must stay free of external
+// imports). Callers inject the loaded module; `viewers/pdf/self-loading`
+// provides the dynamic-import loader for platforms whose bundler resolves it.
+import { mergeHighlightRects } from './controller.js';
+// Hybrid sidecar: saved PDFs keep flattened (portable) pages while embedding
+// the pristine source + a layer JSON, so the omni viewer can restore a
+// removable overlay layer on reopen. External readers only see the flat pages.
+export const SIDECAR_LAYER_NAME = 'omni-viewer-layer.json';
+export const SIDECAR_ORIGINAL_NAME = 'omni-viewer-original.pdf';
+/** Bumped when the sidecar shape changes; older/newer versions are ignored. */
+const SIDECAR_VERSION = 1;
+/** Defensive ceilings — the sidecar is untrusted input on reopen. */
+const MAX_ANNOTATIONS = 2000;
+const MAX_TEXT_LENGTH = 10_000;
+const MAX_DATAURL_LENGTH = 4_000_000;
+const MAX_HIGHLIGHT_RECTS = 500;
+function parseColor(pdfLib, value) {
+    const hex = /^#?([0-9a-f]{6})$/i.exec(value)?.[1] ?? '000000';
+    return pdfLib.rgb(parseInt(hex.slice(0, 2), 16) / 255, parseInt(hex.slice(2, 4), 16) / 255, parseInt(hex.slice(4, 6), 16) / 255);
+}
+function pngBytes(dataUrl) {
+    const encoded = /^data:image\/png;base64,(.*)$/i.exec(dataUrl)?.[1];
+    if (!encoded)
+        return undefined;
+    const binary = atob(encoded);
+    return Uint8Array.from(binary, (c) => c.charCodeAt(0));
+}
+async function stamp(pdfLib, page, annotation) {
+    const { height } = page.getSize();
+    if (annotation.kind === 'text') {
+        if (annotation.rasterDataUrl && annotation.rasterWidth && annotation.rasterHeight) {
+            const bytes = pngBytes(annotation.rasterDataUrl);
+            if (bytes) {
+                const image = await page.doc.embedPng(bytes);
+                page.drawImage(image, {
+                    x: annotation.x,
+                    y: height - annotation.y - annotation.rasterHeight,
+                    width: annotation.rasterWidth,
+                    height: annotation.rasterHeight
+                });
+                return;
+            }
+        }
+        const font = await page.doc.embedFont(pdfLib.StandardFonts.Helvetica);
+        page.drawText(annotation.text, {
+            x: annotation.x,
+            y: height - annotation.y - annotation.size,
+            size: annotation.size,
+            font,
+            color: parseColor(pdfLib, annotation.color)
+        });
+        return;
+    }
+    if (annotation.kind === 'highlight') {
+        const color = parseColor(pdfLib, annotation.color);
+        for (const rect of mergeHighlightRects(annotation.rects)) {
+            page.drawRectangle({
+                x: rect.x,
+                y: height - rect.y - rect.height,
+                width: rect.width,
+                height: rect.height,
+                color,
+                // Multiply keeps the underlying text legible through the tint.
+                blendMode: pdfLib.BlendMode.Multiply
+            });
+        }
+        return;
+    }
+    if (annotation.kind === 'strikeout') {
+        const color = parseColor(pdfLib, annotation.color);
+        for (const rect of mergeHighlightRects(annotation.rects)) {
+            page.drawLine({
+                start: { x: rect.x, y: height - rect.y - rect.height / 2 },
+                end: { x: rect.x + rect.width, y: height - rect.y - rect.height / 2 },
+                thickness: Math.max(1, rect.height * 0.08),
+                color
+            });
+        }
+        return;
+    }
+    if (annotation.kind === 'underline') {
+        const color = parseColor(pdfLib, annotation.color);
+        for (const rect of mergeHighlightRects(annotation.rects)) {
+            page.drawLine({
+                start: { x: rect.x, y: height - rect.y - rect.height * 0.1 },
+                end: { x: rect.x + rect.width, y: height - rect.y - rect.height * 0.1 },
+                thickness: Math.max(1, rect.height * 0.08),
+                color
+            });
+        }
+        return;
+    }
+    const bytes = pngBytes(annotation.dataUrl);
+    if (!bytes)
+        return;
+    const image = await page.doc.embedPng(bytes);
+    page.drawImage(image, {
+        x: annotation.x,
+        y: height - annotation.y - annotation.height,
+        width: annotation.width,
+        height: annotation.height
+    });
+}
+/** Reorder/delete pages and stamp the overlays into a fresh (unsaved) doc. */
+async function flattenInto(pdfLib, source, state) {
+    const original = await pdfLib.PDFDocument.load(source);
+    const output = await pdfLib.PDFDocument.create();
+    const indices = state.pageOrder
+        .map((page) => page - 1)
+        .filter((page) => page >= 0 && page < original.getPageCount());
+    const copied = await output.copyPages(original, indices);
+    copied.forEach((page) => output.addPage(page));
+    for (const annotation of state.annotations) {
+        const outputIndex = state.pageOrder.indexOf(annotation.page);
+        const page = output.getPages()[outputIndex];
+        if (page)
+            await stamp(pdfLib, page, annotation);
+    }
+    return output;
+}
+/** Persist reordered/deleted pages plus the text/signature overlays,
+ *  flattened into the page content (portable, non-editable output). */
+export async function buildEditedPdf(pdfLib, source, state) {
+    const output = await flattenInto(pdfLib, source, state);
+    return output.save();
+}
+/**
+ * Like {@link buildEditedPdf}, but also embeds the hybrid sidecar so the
+ * omni viewer can rehydrate a removable overlay layer on reopen:
+ *   - the pristine (unflattened) source, and
+ *   - the layer JSON `{ version, pageOrder, annotations }`.
+ * External readers only ever see the flattened pages.
+ */
+export async function buildSavedPdf(pdfLib, pristine, state) {
+    const output = await flattenInto(pdfLib, pristine, state);
+    const layer = JSON.stringify({
+        version: SIDECAR_VERSION,
+        pageOrder: state.pageOrder,
+        annotations: state.annotations
+    });
+    await output.attach(new TextEncoder().encode(layer), SIDECAR_LAYER_NAME, {
+        mimeType: 'application/json'
+    });
+    await output.attach(pristine, SIDECAR_ORIGINAL_NAME, {
+        mimeType: 'application/pdf'
+    });
+    return output.save();
+}
+function toAnnotation(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const a = raw;
+    const num = (v) => typeof v === 'number' && Number.isFinite(v);
+    if (typeof a.id !== 'string' || !Number.isInteger(a.page) || a.page < 1)
+        return null;
+    if (a.kind === 'text') {
+        if (!num(a.x) || !num(a.y))
+            return null;
+        if (typeof a.text !== 'string' || a.text.length > MAX_TEXT_LENGTH)
+            return null;
+        if (!num(a.size) || typeof a.color !== 'string')
+            return null;
+        return {
+            id: a.id, kind: 'text', page: a.page,
+            x: a.x, y: a.y, text: a.text, size: a.size, color: a.color,
+            ...(typeof a.rasterDataUrl === 'string'
+                && /^data:image\/png;base64,/i.test(a.rasterDataUrl)
+                && num(a.rasterWidth) && num(a.rasterHeight)
+                ? {
+                    rasterDataUrl: a.rasterDataUrl,
+                    rasterWidth: a.rasterWidth,
+                    rasterHeight: a.rasterHeight
+                }
+                : {})
+        };
+    }
+    if (a.kind === 'signature') {
+        if (!num(a.x) || !num(a.y))
+            return null;
+        if (typeof a.dataUrl !== 'string' || a.dataUrl.length > MAX_DATAURL_LENGTH)
+            return null;
+        if (!/^data:image\/png;base64,/i.test(a.dataUrl))
+            return null;
+        if (!num(a.width) || !num(a.height))
+            return null;
+        return {
+            id: a.id, kind: 'signature', page: a.page,
+            x: a.x, y: a.y, width: a.width, height: a.height, dataUrl: a.dataUrl
+        };
+    }
+    if (a.kind === 'highlight' || a.kind === 'strikeout' || a.kind === 'underline') {
+        if (typeof a.color !== 'string' || !Array.isArray(a.rects))
+            return null;
+        const rects = [];
+        for (const r of a.rects.slice(0, MAX_HIGHLIGHT_RECTS)) {
+            if (!r || typeof r !== 'object')
+                continue;
+            const rr = r;
+            if (num(rr.x) && num(rr.y) && num(rr.width) && num(rr.height)) {
+                rects.push({ x: rr.x, y: rr.y, width: rr.width, height: rr.height });
+            }
+        }
+        if (rects.length === 0)
+            return null;
+        return { id: a.id, kind: a.kind, page: a.page, rects, color: a.color };
+    }
+    return null;
+}
+/** Parse and validate a sidecar layer JSON string; null if unusable. */
+export function parseLayer(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const obj = raw;
+    if (obj.version !== SIDECAR_VERSION)
+        return null;
+    const pageOrder = Array.isArray(obj.pageOrder)
+        ? obj.pageOrder.filter((n) => Number.isInteger(n) && n > 0)
+        : [];
+    const annotationsRaw = Array.isArray(obj.annotations)
+        ? obj.annotations.slice(0, MAX_ANNOTATIONS)
+        : [];
+    const annotations = [];
+    for (const entry of annotationsRaw) {
+        const parsed = toAnnotation(entry);
+        if (parsed)
+            annotations.push(parsed);
+    }
+    if (pageOrder.length === 0 && annotations.length === 0)
+        return null;
+    return { pageOrder, annotations };
+}
+/** Append every page of `second` after `first`. */
+export async function mergePdfBytes(pdfLib, first, second) {
+    const [left, right] = await Promise.all([
+        pdfLib.PDFDocument.load(first),
+        pdfLib.PDFDocument.load(second)
+    ]);
+    const output = await pdfLib.PDFDocument.create();
+    for (const source of [left, right]) {
+        // pdf-lib's addPage takes a single page — spreading silently drops
+        // all but the first one.
+        for (const page of await output.copyPages(source, source.getPageIndices())) {
+            output.addPage(page);
+        }
+    }
+    return output.save();
+}
+export function savedPdfName(name) {
+    // The host can supply a page/URL-like name (for example `viewer.html`
+    // or `report.pdf?token=...`). Keep only the final path component and
+    // replace its extension, so Save As is always a real `.pdf` download.
+    const leaf = name.trim().split(/[\\/]/).pop()?.split(/[?#]/, 1)[0] ?? '';
+    const stem = leaf.replace(/\.[^.]*$/, '') || 'document';
+    return `${stem}-edited.pdf`;
+}

package/dist/viewers/pdf/index.d.ts

@@ -0,0 +1,88 @@
+import type { FilePickService, FileSaveService, FileWritebackService, HostContext } from '../../host/index.js';
+import { type MountOptions, type ViewerHandle, type ViewerInput } from '../types.js';
+import { type PdfController } from './controller.js';
+import { type PdfLibModule } from './editing.js';
+export { createPdfController, PDF_ZOOM_LEVELS } from './controller.js';
+export type { PdfController, PdfAction, PdfViewState, PdfAnnotation } from './controller.js';
+export { pdfViewerCss } from './styles.js';
+export { buildEditedPdf, mergePdfBytes, savedPdfName } from './editing.js';
+export type { PdfLibModule } from './editing.js';
+/** Viewer metadata — single source for the registry codegen (DESIGN.md §7). */
+export declare const PDF_VIEWER_META: {
+    id: string;
+    displayNameKey: string;
+    extensions: string[];
+    priority: number;
+    requiredServices: readonly [];
+    optionalServices: readonly ["save", "writeback", "filePick"];
+    inputOwnership: "borrows";
+};
+export type PdfViewerContext = HostContext & {
+    save?: FileSaveService;
+    writeback?: FileWritebackService;
+    filePick?: FilePickService;
+};
+/** Opaque pdf.js viewport — passed straight back to render()/TextLayer. */
+export type PdfJsViewport = {
+    width: number;
+    height: number;
+};
+export interface PdfJsPage {
+    getViewport(options: {
+        scale: number;
+    }): PdfJsViewport;
+    render(options: {
+        canvasContext: CanvasRenderingContext2D;
+        viewport: unknown;
+    }): {
+        promise: Promise<void>;
+        cancel(): void;
+    };
+    /** Text runs + geometry, fed as-is into TextLayer as textContentSource. */
+    getTextContent(): Promise<unknown>;
+}
+/** pdf.js v4 TextLayer — positions transparent, selectable spans over canvas. */
+export interface PdfJsTextLayer {
+    render(): Promise<void>;
+    cancel(): void;
+}
+export interface PdfJsDocument {
+    numPages: number;
+    getPage(n: number): Promise<PdfJsPage>;
+    destroy(): Promise<void>;
+    /** Embedded files keyed by name; used to read the hybrid sidecar. */
+    getAttachments?(): Promise<Record<string, {
+        filename: string;
+        content: Uint8Array;
+    }> | null>;
+}
+export interface PdfJsLoadingTask {
+    promise: Promise<PdfJsDocument>;
+    destroy(): void;
+}
+export interface PdfJsModule {
+    getDocument(options: {
+        data: Uint8Array;
+        password?: string;
+    }): PdfJsLoadingTask;
+    GlobalWorkerOptions: {
+        workerSrc: string;
+    };
+    TextLayer: new (options: {
+        textContentSource: unknown;
+        container: HTMLElement;
+        viewport: unknown;
+    }) => PdfJsTextLayer;
+}
+/** External modules the viewer needs, injected by the adapter (ADR 14). */
+export interface PdfViewerDeps {
+    loadPdfjs(): Promise<PdfJsModule>;
+    /** Editing dependency (save / save-as / merge / annotation stamping).
+     *  Absent -> editing controls disabled with a reason. */
+    loadPdfLib?(): Promise<PdfLibModule>;
+}
+export interface PdfViewerHandle extends ViewerHandle {
+    readonly controller: PdfController;
+    isDirty(): boolean;
+}
+export declare function mountPdfViewer(input: ViewerInput, container: HTMLElement, ctx: PdfViewerContext, deps: PdfViewerDeps, options?: MountOptions): Promise<PdfViewerHandle>;