@triiiceratops/plugin-pdf-export 1.0.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Flood
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/catalog.d.ts

@@ -0,0 +1,15 @@
+import type { LocaleCatalog } from '@triiiceratops/plugin-sdk';
+/**
+ * The plugin's package-owned localization catalog (CONTEXT.md **Active
+ * locale**). These strings previously lived in core's `messages/en.json` /
+ * `messages/de.json` under the `pdf_export_*` keys; migrating the plugin out of
+ * core moves them here so the catalog ships with (and evolves with) the plugin,
+ * and core's catalogs carry no plugin keys. `en` is the required fallback; a
+ * missing key resolves to `en` and then to the key itself.
+ *
+ * The `{param}` placeholders are substituted by the SDK locale service's `t`.
+ * The progress/error strings are passed through `t` and handed to
+ * `exportCanvasRangeAsPdf` as its `messages` builders (the pure export logic
+ * itself carries no i18n runtime).
+ */
+export declare const catalog: LocaleCatalog;

package/dist/contextKey.d.ts

@@ -0,0 +1,18 @@
+import type { PluginContext } from '@triiiceratops/plugin-sdk';
+import type { PdfExportConfig } from './types';
+/**
+ * Shared key for handing the SDK {@link PluginContext} (plus this activation's
+ * consumer config) to the panel through Svelte's component-context map.
+ * `getContext` returns a plain (non-reactive) value, which is exactly right
+ * here: the activation context and config are stable for the lifetime of a mount
+ * (a fresh mount gets a fresh context), so they must not be treated as reactive
+ * state.
+ */
+export declare const PLUGIN_CONTEXT_KEY: unique symbol;
+/** What `view.mount` passes to the panel through the context map. */
+export interface PanelContext {
+    /** The SDK activation context (viewer state, selectors, services). */
+    readonly context: PluginContext;
+    /** The consumer configuration this plugin instance was created with. */
+    readonly config: PdfExportConfig;
+}

package/dist/exportPdf.d.ts

@@ -0,0 +1,124 @@
+import { type ResolvedCanvasImage } from 'triiiceratops/image-export';
+/**
+ * Progress + error strings `exportCanvasRangeAsPdf` emits. In core this logic
+ * imported the Svelte i18n runtime (`m.pdf_export_*`); a framework-neutral,
+ * package-owned plugin must not, so the strings are injected instead. Callers
+ * (the plugin panel) pass builders resolved from the SDK per-viewer locale
+ * service over this package's catalog; the module ships English defaults so the
+ * pure logic — and its moved unit tests — run without a locale service.
+ */
+export interface PdfExportMessages {
+    errorNoCanvases(): string;
+    errorNotAvailable(): string;
+    errorNoCanvasesExported(): string;
+    progressCoverSheet(): string;
+    progressCanvas(params: {
+        current: number;
+        total: number;
+        label: string;
+    }): string;
+    progressDownload(params: {
+        filename: string;
+    }): string;
+}
+/** English fallbacks — the same strings core shipped in `messages/en.json`. */
+export declare const DEFAULT_PDF_EXPORT_MESSAGES: PdfExportMessages;
+type NormalizeCanvasRangeResult = {
+    startIndex: number;
+    endIndex: number;
+    indices: number[];
+};
+export type PdfCoverSheetField = {
+    label: string;
+    value: string;
+};
+export type PdfCoverSheetConfig = {
+    title?: string;
+    fields: PdfCoverSheetField[];
+};
+export type PdfImageRequestConfig = Pick<RequestInit, 'credentials' | 'headers' | 'mode' | 'referrerPolicy'>;
+export type PdfImageLoaderParams = {
+    canvas: any;
+    canvasId: string;
+    imageUrl: string;
+    manifestId: string | null;
+    targetWidth: number;
+    imageRequest: RequestInit;
+    resolvedImage: ResolvedCanvasImage | null;
+};
+export type PdfImageLoader = (params: PdfImageLoaderParams) => Promise<Blob> | Blob;
+export type PdfTextOverlay = {
+    text: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    coordinateSpace?: 'canvas' | 'image';
+};
+export type PdfExportOcrProviderContext = {
+    manifestId: string | null;
+    canvasId: string;
+    canvas: any;
+    canvasIndex: number;
+};
+export type PdfCanvasOcrOverlayProvider = (context: PdfExportOcrProviderContext) => Promise<PdfTextOverlay[] | null | undefined> | PdfTextOverlay[] | null | undefined;
+export type PdfExportFilenameProviderContext = {
+    manifestId: string | null;
+    manifestLabel?: string | null;
+    startIndex: number;
+    endIndex: number;
+    indices: number[];
+    canvases: any[];
+    exportedCount: number;
+    failedCanvases: string[];
+    defaultFilename: string;
+};
+export type PdfExportFilenameProvider = (context: PdfExportFilenameProviderContext) => Promise<string | null | undefined> | string | null | undefined;
+export type PdfOcrPlacementMode = 'fit-box' | 'word-anchor';
+export type PdfOcrSizingMode = 'fit-box' | 'height-only';
+export type PdfOcrVisibilityMode = 'transparent' | 'invisible' | 'debug';
+type ExportCanvasRangeAsPdfParams = {
+    canvases: any[];
+    startIndex: number;
+    endIndex: number;
+    targetWidth: number;
+    manifestId: string | null;
+    manifestLabel?: string | null;
+    getSelectedChoice?: (canvasId: string) => string | undefined;
+    getCanvasOcrOverlays?: PdfCanvasOcrOverlayProvider;
+    getCanvasAnnotations?: (canvasId: string) => Promise<any[]> | any[];
+    imageRequest?: PdfImageRequestConfig;
+    loadImageBlob?: PdfImageLoader;
+    ocrPlacementMode?: PdfOcrPlacementMode;
+    ocrSizingMode?: PdfOcrSizingMode;
+    ocrVisibilityMode?: PdfOcrVisibilityMode;
+    filename?: string;
+    getFilename?: PdfExportFilenameProvider;
+    coverSheet?: PdfCoverSheetConfig;
+    createdAt?: Date;
+    currentUrl?: string | null;
+    onProgress?: (message: string) => void;
+    /** Localized progress/error strings; defaults to English. */
+    messages?: PdfExportMessages;
+};
+type ExportCanvasRangeAsPdfResult = {
+    exportedCount: number;
+    failedCanvases: string[];
+    filename: string;
+};
+type CoverSheetRuntimeValues = {
+    createdAt: Date;
+    currentUrl: string | null;
+};
+export declare function buildCoverSheetFields(coverSheet: PdfCoverSheetConfig, runtimeValues: CoverSheetRuntimeValues): PdfCoverSheetField[];
+export declare function buildPdfFilename(params: {
+    manifestId: string | null;
+    manifestLabel?: string | null;
+    startIndex: number;
+    endIndex: number;
+}): string;
+export declare function normalizeCanvasRange(startIndex: number, endIndex: number, canvasCount: number): NormalizeCanvasRangeResult | null;
+export declare function extractOcrTextOverlays(annotations: any[]): PdfTextOverlay[];
+export declare function buildImageRequestInit(imageRequest?: PdfImageRequestConfig): RequestInit;
+export declare function exportCanvasRangeAsPdf({ canvases, startIndex, endIndex, targetWidth, manifestId, manifestLabel, getSelectedChoice, getCanvasOcrOverlays, getCanvasAnnotations, imageRequest, loadImageBlob, ocrPlacementMode, ocrSizingMode, ocrVisibilityMode, filename, getFilename, coverSheet, createdAt, currentUrl, onProgress, messages, }: ExportCanvasRangeAsPdfParams): Promise<ExportCanvasRangeAsPdfResult>;
+export {};

package/dist/icons.d.ts

@@ -0,0 +1,9 @@
+import { type IconDescriptor } from '@triiiceratops/plugin-sdk';
+/** The toolbar icon descriptor (the file-pdf glyph), validated by `svgIcon`. */
+export declare const FILE_PDF_ICON: IconDescriptor;
+/** Inner SVG markup for the in-panel glyphs (trusted static paths). */
+export declare const GLYPHS: {
+    readonly viewBox: "0 0 256 256";
+    readonly filePdf: "<path d=\"M224,152a8,8,0,0,1-8,8H192v16h16a8,8,0,0,1,0,16H192v16a8,8,0,0,1-16,0V152a8,8,0,0,1,8-8h32A8,8,0,0,1,224,152ZM92,172a28,28,0,0,1-28,28H56v8a8,8,0,0,1-16,0V152a8,8,0,0,1,8-8H64A28,28,0,0,1,92,172Zm-16,0a12,12,0,0,0-12-12H56v24h8A12,12,0,0,0,76,172Zm88,8a36,36,0,0,1-36,36H112a8,8,0,0,1-8-8V152a8,8,0,0,1,8-8h16A36,36,0,0,1,164,180Zm-16,0a20,20,0,0,0-20-20h-8v40h8A20,20,0,0,0,148,180ZM40,112V40A16,16,0,0,1,56,24h96a8,8,0,0,1,5.66,2.34l56,56A8,8,0,0,1,216,88v24a8,8,0,0,1-16,0V96H152a8,8,0,0,1-8-8V40H56v72a8,8,0,0,1-16,0ZM160,80h28.69L160,51.31Z\"/>";
+    readonly download: "<path d=\"M224,144v64a8,8,0,0,1-8,8H40a8,8,0,0,1-8-8V144a8,8,0,0,1,16,0v56H208V144a8,8,0,0,1,16,0Zm-101.66,5.66a8,8,0,0,0,11.32,0l40-40a8,8,0,0,0-11.32-11.32L136,124.69V32a8,8,0,0,0-16,0v92.69L93.66,98.34a8,8,0,0,0-11.32,11.32Z\"/>";
+};

package/dist/iife.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Self-contained IIFE entry — loadable from a `<script>` tag with no bundler.
+ *
+ * Loading this bundle bootstraps the `window.Triiiceratops` namespace if absent
+ * and registers the plugin factory into `window.Triiiceratops.plugins` (SPEC.md
+ * "Browser IIFEs register package-qualified factories in one `window.Triiiceratops`
+ * namespace"). It does NOT activate anything — activation is explicit and per
+ * viewer:
+ *
+ * ```html
+ * <script src="triiiceratops-element.iife.js"></script>
+ * <script src="triiiceratops-plugin-pdf-export.iife.js"></script>
+ * <script>
+ *   const viewer = document.querySelector('triiiceratops-viewer');
+ *   viewer.plugins = [
+ *     window.Triiiceratops.plugins.get('@triiiceratops/plugin-pdf-export'),
+ *   ];
+ * </script>
+ * ```
+ *
+ * The plugin script may load before OR after core: the registry is bootstrapped
+ * order-independently, so both script orders work. This bundle carries its own
+ * `pdf-lib` (bundled in), so no bundler and no separate dependency install is
+ * required for the no-bundler path.
+ */
+export {};