@printwithsynergy/lens-pdf 0.3.0-beta.81

package/dist/host/useLensPDF.js

@@ -0,0 +1,213 @@
+/**
+ * `useLensPDF` — React hook that manages all viewer state.
+ *
+ * Returns everything a consumer needs to render a viewer: context
+ * values, fallback adapter, page/zoom/layer/tool state, and
+ * computed canvas dimensions. Pass the return value to
+ * {@link LensPDFProvider} (or spread into `<LensPDFViewer>`) and
+ * you're done — no manual context wiring required.
+ *
+ * @public
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { defaultThemeTokens, markUnwired, noopI18n, noopTelemetry } from "../plugin/services.js";
+import { pageInfoFromDimensions } from "../types/index.js";
+import { createPdfJsFallback } from "../fallback-pdfjs/index.js";
+// ---------------------------------------------------------------------------
+// Default values
+// ---------------------------------------------------------------------------
+const DEFAULT_PAGE = pageInfoFromDimensions(1, 612, 792);
+const PTS_TO_PX = 96 / 72;
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+/**
+ * Manages all LensPDF viewer state. Pair with `<LensPDFProvider>`
+ * or `<LensPDFViewer>` for rendering.
+ *
+ * ```tsx
+ * const viewer = useLensPDF("https://cdn.example.com/proof.pdf");
+ * return (
+ *   <LensPDFProvider value={viewer}>
+ *     <PageCanvas page={viewer.currentPageInfo} zoom={viewer.zoom} ... />
+ *   </LensPDFProvider>
+ * );
+ * ```
+ *
+ * @public
+ */
+export function useLensPDF(pdfUrl, opts = {}) {
+    const { tokens: tokenOverrides, services: serviceOverrides, initialZoom = 100, workerSrc, initialPage = 1, } = opts;
+    // -----------------------------------------------------------------------
+    // Tokens
+    // -----------------------------------------------------------------------
+    const tokens = useMemo(() => ({ ...defaultThemeTokens, ...tokenOverrides }), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [JSON.stringify(tokenOverrides)]);
+    // -----------------------------------------------------------------------
+    // Fallback adapter (recreated when pdfUrl changes)
+    // -----------------------------------------------------------------------
+    const fallback = useMemo(() => (pdfUrl ? createPdfJsFallback({ pdfUrl, workerSrc }) : undefined), [pdfUrl, workerSrc]);
+    // -----------------------------------------------------------------------
+    // Services
+    // -----------------------------------------------------------------------
+    const servicesValue = useMemo(() => {
+        const base = {
+            pageImages: markUnwired({ getPageImageUrl: () => "" }),
+            layers: markUnwired({ getLayerImageUrl: () => "", listLayers: async () => [] }),
+            separations: markUnwired({ getChannelImageUrl: () => "" }),
+            tacHeatmap: markUnwired({ getHeatmapImageUrl: () => "", listRuns: async () => [] }),
+            colorSample: markUnwired({ sampleAt: async () => null }),
+            densitometer: markUnwired({
+                sampleAt: async () => { throw new Error("No separations available for this page."); },
+            }),
+            annotations: markUnwired({
+                list: async () => [],
+                getForPage: async () => null,
+                saveForPage: async () => { },
+                remove: async () => { },
+            }),
+            reports: markUnwired({ getHtmlReportUrl: () => "", getPdfDownloadUrl: () => "" }),
+            telemetry: noopTelemetry,
+            i18n: noopI18n,
+            tokens,
+        };
+        if (!serviceOverrides)
+            return base;
+        return { ...base, ...serviceOverrides, tokens };
+    }, [tokens, serviceOverrides]);
+    // -----------------------------------------------------------------------
+    // Host context
+    // -----------------------------------------------------------------------
+    const hostValue = useMemo(() => ({
+        apiBase: "",
+        jobApiBase: "",
+        readOnly: true,
+        pdfUrl,
+        pdfFallback: fallback,
+    }), [pdfUrl, fallback]);
+    // -----------------------------------------------------------------------
+    // State
+    // -----------------------------------------------------------------------
+    const [pageCount, setPageCount] = useState(null);
+    const [pageDims, setPageDims] = useState(new Map());
+    const [zoom, setZoom] = useState(initialZoom);
+    const [currentPage, setCurrentPage] = useState(initialPage);
+    const [enabledLayers, setEnabledLayers] = useState(new Set());
+    const [hasLayers, setHasLayers] = useState(false);
+    const [activeTool, setActiveTool] = useState("none");
+    const [error, setError] = useState(null);
+    // Track fallback identity to reset state on URL change.
+    const prevFallbackRef = useRef(fallback);
+    useEffect(() => {
+        if (prevFallbackRef.current !== fallback) {
+            prevFallbackRef.current = fallback;
+            setPageCount(null);
+            setPageDims(new Map());
+            setCurrentPage(initialPage);
+            setEnabledLayers(new Set());
+            setHasLayers(false);
+            setError(null);
+        }
+    }, [fallback, initialPage]);
+    // -----------------------------------------------------------------------
+    // Load page count + layers from fallback
+    // -----------------------------------------------------------------------
+    useEffect(() => {
+        if (!fallback)
+            return;
+        let cancelled = false;
+        fallback
+            .getPageCount()
+            .then((n) => { if (!cancelled)
+            setPageCount(n); })
+            .catch((err) => { if (!cancelled)
+            setError(err.message); });
+        return () => { cancelled = true; };
+    }, [fallback]);
+    useEffect(() => {
+        if (!fallback)
+            return;
+        let cancelled = false;
+        fallback.listLayers().then((layers) => {
+            if (cancelled)
+                return;
+            setHasLayers(layers.length > 0);
+            setEnabledLayers(new Set(layers.filter((l) => l.default_on).map((l) => l.ocg_index)));
+        });
+        return () => { cancelled = true; };
+    }, [fallback]);
+    // -----------------------------------------------------------------------
+    // Derived page info
+    // -----------------------------------------------------------------------
+    const currentDims = pageDims.get(currentPage);
+    const currentPageInfo = currentDims
+        ? pageInfoFromDimensions(currentPage, currentDims.widthPts, currentDims.heightPts)
+        : { ...DEFAULT_PAGE, page_num: currentPage };
+    const pages = useMemo(() => {
+        if (pageCount === null)
+            return [];
+        return Array.from({ length: pageCount }, (_, i) => {
+            const num = i + 1;
+            const dims = pageDims.get(num);
+            return dims
+                ? pageInfoFromDimensions(num, dims.widthPts, dims.heightPts)
+                : { ...DEFAULT_PAGE, page_num: num };
+        });
+    }, [pageCount, pageDims]);
+    // -----------------------------------------------------------------------
+    // Canvas dimensions
+    // -----------------------------------------------------------------------
+    const scale = zoom / 100;
+    const canvasWidth = Math.round(currentPageInfo.width_pts * PTS_TO_PX * scale);
+    const canvasHeight = Math.round(currentPageInfo.height_pts * PTS_TO_PX * scale);
+    // -----------------------------------------------------------------------
+    // Layer callbacks
+    // -----------------------------------------------------------------------
+    const toggleLayer = useCallback((ocgIndex) => {
+        setEnabledLayers((prev) => {
+            const next = new Set(prev);
+            if (next.has(ocgIndex))
+                next.delete(ocgIndex);
+            else
+                next.add(ocgIndex);
+            return next;
+        });
+    }, []);
+    const setAllLayers = useCallback((enabled) => {
+        if (!fallback)
+            return;
+        if (enabled) {
+            fallback.listLayers().then((layers) => {
+                setEnabledLayers(new Set(layers.map((l) => l.ocg_index)));
+            });
+        }
+        else {
+            setEnabledLayers(new Set());
+        }
+    }, [fallback]);
+    return {
+        hostValue,
+        servicesValue,
+        fallback,
+        pageCount,
+        currentPage,
+        setCurrentPage,
+        currentPageInfo,
+        pages,
+        pageDims,
+        zoom,
+        setZoom,
+        canvasWidth,
+        canvasHeight,
+        enabledLayers,
+        toggleLayer,
+        setAllLayers,
+        hasLayers,
+        activeTool,
+        setActiveTool,
+        error,
+        setError,
+    };
+}
+//# sourceMappingURL=useLensPDF.js.map

package/dist/host/useLensPDF.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLensPDF.js","sourceRoot":"","sources":["../../host/useLensPDF.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+/**
+ * `@printwithsynergy/lens-pdf` — root barrel.
+ *
+ * Re-exports every public protocol, component, and unit. Host
+ * applications usually import directly from a sub-path (`/host`,
+ * `/components`, `/plugin`, `/units`, `/types`) so their bundler
+ * only pulls what they use; this convenience barrel exists for
+ * smaller embeds that want the whole surface in one import.
+ *
+ * The viewer is host-agnostic — no SaaS-specific imports, no
+ * hardcoded backend paths. Hosts wire their own concrete
+ * `ViewerServices` and supply their own host context. See the
+ * `core/`-scoped ESLint rule (mirrored in `docs/contributing.md`)
+ * for the boundary that keeps it that way.
+ *
+ * Distributed under AGPL-3.0-or-later.
+ *
+ * @public
+ */
+export * from "./plugin";
+export { defaultUnwiredServices, ViewerHostContext, ViewerServicesContext, useViewerHost, useViewerServices, useFallbackMode, } from "./host";
+export type { ViewerHostContextValue } from "./host";
+export { validatePdfFile, validatePdfUrl } from "./host/pdfValidation";
+export type { PdfValidationResult } from "./host/pdfValidation";
+export { generateShareLink, parseShareParams } from "./host/shareLink";
+export type { ShareLinkOptions, ParsedShareParams } from "./host/shareLink";
+export { useLensPDF } from "./host/useLensPDF";
+export type { UseLensPDFOptions, UseLensPDFReturn } from "./host/useLensPDF";
+export { LensPDFProvider } from "./host/LensPDFProvider";
+export type { LensPDFProviderProps } from "./host/LensPDFProvider";
+export { pageInfoFromDimensions } from "./types";
+export { LensPDFDemo } from "./components/LensPDFDemo";
+export { FindingsSidebar } from "./components/FindingsSidebar";
+export type { FindingsSidebarProps } from "./components/FindingsSidebar";
+export { DielineInfoPanel } from "./components/DielineInfoPanel";
+export type { DielineInfoPanelProps } from "./components/DielineInfoPanel";
+export type { LensPDFDemoProps, LensPDFDemoTool, } from "./components/LensPDFDemo";
+export { LensPDF } from "./components/LensPDF";
+export type { LensPDFProps } from "./components/LensPDF";
+export { createBrowserViewerServices, defaultBrowserWorkerSrc, detectSpotInksFromPdfBytes, rgbToCmyk, useBrowserViewerServicesVersion, PROCESS_CHANNELS, } from "./browser";
+export type { BrowserViewerServices, BrowserViewerServicesOptions, DetectedInk, } from "./browser";
+export { AnnotationCanvas } from "./components/AnnotationCanvas";
+export { AnnotationNotesPanel } from "./components/AnnotationNotesPanel";
+export { AnnotationThread } from "./components/AnnotationThread";
+export { AnnotationToolbar } from "./components/AnnotationToolbar";
+export { BoxOverlay } from "./components/BoxOverlay";
+export { ColorPickerTool } from "./components/ColorPickerTool";
+export { DensitometerTool } from "./components/DensitometerTool";
+export { DielineOverlay } from "./components/DielineOverlay";
+export { LayerCanvas } from "./components/LayerCanvas";
+export { LayerPanel } from "./components/LayerPanel";
+export { LensPDFViewer } from "./components/LensPDFViewer";
+export type { LensPDFViewerProps, LensPDFViewerState, LensPDFViewerTool, } from "./components/LensPDFViewer";
+export { MeasureTool } from "./components/MeasureTool";
+export { createDefaultShellPlugins } from "./components/defaultShellPlugins";
+export { MobileBottomSheet } from "./components/MobileBottomSheet";
+export { MobileDrawer } from "./components/MobileDrawer";
+export { PageCanvas } from "./components/PageCanvas";
+export { PageNavigator } from "./components/PageNavigator";
+export { SeparationCanvas } from "./components/SeparationCanvas";
+export { TACHeatmapOverlay } from "./components/TACHeatmapOverlay";
+export { ZoomControls } from "./components/ZoomControls";
+export { pluginsForPreset } from "./components/presets";
+export type { LensPDFPresetKind } from "./components/presets";
+export { computeFeatureAvailability, pluginsForSlot, resolveShellPlugins, } from "./components/shellPlugins";
+export type { LensPDFFeatureAvailability, LensPDFShellPlugin, LensPDFShellPluginContext, LensPDFShellSlot, } from "./components/shellPlugins";
+export { agateUnit, allMeasurementUnits, defaultMeasurementUnits, inchUnit, mmUnit, picaUnit, pointUnit, } from "./units";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,62 @@
+/**
+ * `@printwithsynergy/lens-pdf` — root barrel.
+ *
+ * Re-exports every public protocol, component, and unit. Host
+ * applications usually import directly from a sub-path (`/host`,
+ * `/components`, `/plugin`, `/units`, `/types`) so their bundler
+ * only pulls what they use; this convenience barrel exists for
+ * smaller embeds that want the whole surface in one import.
+ *
+ * The viewer is host-agnostic — no SaaS-specific imports, no
+ * hardcoded backend paths. Hosts wire their own concrete
+ * `ViewerServices` and supply their own host context. See the
+ * `core/`-scoped ESLint rule (mirrored in `docs/contributing.md`)
+ * for the boundary that keeps it that way.
+ *
+ * Distributed under AGPL-3.0-or-later.
+ *
+ * @public
+ */
+export * from "./plugin/index.js";
+// Host-level utilities re-exported for convenience.
+export { defaultUnwiredServices, ViewerHostContext, ViewerServicesContext, useViewerHost, useViewerServices, useFallbackMode, } from "./host/index.js";
+export { validatePdfFile, validatePdfUrl } from "./host/pdfValidation.js";
+export { generateShareLink, parseShareParams } from "./host/shareLink.js";
+export { useLensPDF } from "./host/useLensPDF.js";
+export { LensPDFProvider } from "./host/LensPDFProvider.js";
+export { pageInfoFromDimensions } from "./types/index.js";
+export { LensPDFDemo } from "./components/LensPDFDemo.js";
+export { FindingsSidebar } from "./components/FindingsSidebar.js";
+export { DielineInfoPanel } from "./components/DielineInfoPanel.js";
+// Drop-in production viewer — same feature surface as <LensPDFDemo>
+// without the upload chrome. The recommended single-component entry
+// point for hosts integrating LensPDF.
+export { LensPDF } from "./components/LensPDF.js";
+// Browser-only ViewerServices factory — gives consumers a one-liner
+// path to a fully wired viewer without a server backend.
+export { createBrowserViewerServices, defaultBrowserWorkerSrc, detectSpotInksFromPdfBytes, rgbToCmyk, useBrowserViewerServicesVersion, PROCESS_CHANNELS, } from "./browser/index.js";
+export { AnnotationCanvas } from "./components/AnnotationCanvas.js";
+export { AnnotationNotesPanel } from "./components/AnnotationNotesPanel.js";
+export { AnnotationThread } from "./components/AnnotationThread.js";
+export { AnnotationToolbar } from "./components/AnnotationToolbar.js";
+export { BoxOverlay } from "./components/BoxOverlay.js";
+export { ColorPickerTool } from "./components/ColorPickerTool.js";
+export { DensitometerTool } from "./components/DensitometerTool.js";
+export { DielineOverlay } from "./components/DielineOverlay.js";
+export { LayerCanvas } from "./components/LayerCanvas.js";
+export { LayerPanel } from "./components/LayerPanel.js";
+export { LensPDFViewer } from "./components/LensPDFViewer.js";
+export { MeasureTool } from "./components/MeasureTool.js";
+export { createDefaultShellPlugins } from "./components/defaultShellPlugins.js";
+export { MobileBottomSheet } from "./components/MobileBottomSheet.js";
+export { MobileDrawer } from "./components/MobileDrawer.js";
+export { PageCanvas } from "./components/PageCanvas.js";
+export { PageNavigator } from "./components/PageNavigator.js";
+export { SeparationCanvas } from "./components/SeparationCanvas.js";
+export { TACHeatmapOverlay } from "./components/TACHeatmapOverlay.js";
+export { ZoomControls } from "./components/ZoomControls.js";
+export { pluginsForPreset } from "./components/presets.js";
+export { computeFeatureAvailability, pluginsForSlot, resolveShellPlugins, } from "./components/shellPlugins.js";
+// Built-in MeasurementUnit definitions consumed by MeasureTool.
+export { agateUnit, allMeasurementUnits, defaultMeasurementUnits, inchUnit, mmUnit, picaUnit, pointUnit, } from "./units/index.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,cAAc,UAAU,CAAC;AAEzB,oDAAoD;AACpD,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,qBAAqB,EACrB,aAAa,EACb,iBAAiB,EACjB,eAAe,GAChB,MAAM,QAAQ,CAAC;AAGhB,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEvE,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEvE,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AAEjD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAE/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAOjE,oEAAoE;AACpE,oEAAoE;AACpE,uCAAuC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAG/C,oEAAoE;AACpE,yDAAyD;AACzD,OAAO,EACL,2BAA2B,EAC3B,uBAAuB,EACvB,0BAA0B,EAC1B,SAAS,EACT,+BAA+B,EAC/B,gBAAgB,GACjB,MAAM,WAAW,CAAC;AAOnB,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAM3D,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,yBAAyB,EAAE,MAAM,kCAAkC,CAAC;AAC7E,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,OAAO,EACL,0BAA0B,EAC1B,cAAc,EACd,mBAAmB,GACpB,MAAM,2BAA2B,CAAC;AAQnC,gEAAgE;AAChE,OAAO,EACL,SAAS,EACT,mBAAmB,EACnB,uBAAuB,EACvB,QAAQ,EACR,MAAM,EACN,QAAQ,EACR,SAAS,GACV,MAAM,SAAS,CAAC"}

package/dist/plugin/context.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Viewer context — single argument passed to every plugin's `mount` /
+ * `subscribe` call.
+ *
+ * The context is intentionally narrow: viewer state only (page,
+ * zoom, pan, viewport, selection) plus the `services` surface for
+ * data sources. No host- or domain-shaped types live here — those
+ * belong in plugin packs.
+ *
+ * Plugins that need richer data subscribe to it via the relevant
+ * service (`services.annotations`, `services.pageImages`, etc.).
+ *
+ * @public
+ */
+import type { ViewerServices } from "./services";
+/**
+ * Read-only viewport state.
+ *
+ * @public
+ */
+export interface ViewerViewport {
+    /** Width in CSS pixels. */
+    readonly width: number;
+    /** Height in CSS pixels. */
+    readonly height: number;
+}
+/**
+ * Read-only document metadata. Anything host- or domain-specific
+ * (job id, brand spec, finding catalog, audit verdict) is exposed
+ * via services or plugin payloads, not here.
+ *
+ * @public
+ */
+export interface ViewerDocumentMetadata {
+    /** Total page count. */
+    readonly pageCount: number;
+    /** Per-page width/height in PDF points. */
+    readonly pageDimensions: ReadonlyArray<{
+        width: number;
+        height: number;
+    }>;
+}
+/**
+ * Single argument bundle passed to plugins.
+ *
+ * @public
+ */
+export interface ViewerContext {
+    /** 1-indexed current page. */
+    readonly page: number;
+    /** Zoom factor: 1.0 = 100%. */
+    readonly zoom: number;
+    /** Pan offset in CSS pixels (relative to viewport top-left). */
+    readonly pan: {
+        readonly x: number;
+        readonly y: number;
+    };
+    /** Current viewport size. */
+    readonly viewport: ViewerViewport;
+    /**
+     * Bounding box (in PDF points) of the user's current selection,
+     * or `null` if nothing is selected.
+     */
+    readonly selectionBbox: readonly [number, number, number, number] | null;
+    /** Document metadata. */
+    readonly document: ViewerDocumentMetadata;
+    /** Host-supplied data-source services. */
+    readonly services: ViewerServices;
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/plugin/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../plugin/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,4BAA4B;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,wBAAwB;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,2CAA2C;IAC3C,QAAQ,CAAC,cAAc,EAAE,aAAa,CAAC;QACrC,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC,CAAC;CACJ;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,8BAA8B;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,QAAQ,CAAC,GAAG,EAAE;QAAE,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACzD,6BAA6B;IAC7B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IACzE,yBAAyB;IACzB,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;IAC1C,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;CACnC"}

package/dist/plugin/context.js

@@ -0,0 +1,16 @@
+/**
+ * Viewer context — single argument passed to every plugin's `mount` /
+ * `subscribe` call.
+ *
+ * The context is intentionally narrow: viewer state only (page,
+ * zoom, pan, viewport, selection) plus the `services` surface for
+ * data sources. No host- or domain-shaped types live here — those
+ * belong in plugin packs.
+ *
+ * Plugins that need richer data subscribe to it via the relevant
+ * service (`services.annotations`, `services.pageImages`, etc.).
+ *
+ * @public
+ */
+export {};
+//# sourceMappingURL=context.js.map

package/dist/plugin/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../plugin/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}

package/dist/plugin/findings-location.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Findings location helpers — split OverlayItems into "located in
+ * viewer" (those with a position the canvas can highlight + click)
+ * and "informational" (page-level metadata that's still surfaced
+ * to consumers, just not as a clickable overlay).
+ *
+ * Adapter authors moving findings from other preflight engines
+ * (callas pdfToolbox, PitStop, Acrobat, lint-pdf, custom rule
+ * engines) into Lens's contract should rely on these helpers to
+ * categorise each finding the same way Lens's canvas does — there
+ * is one source of truth for "can the viewer locate this?".
+ *
+ * @module
+ */
+import type { OverlayItem } from "./types";
+/**
+ * Decide whether an OverlayItem can be located on the page.
+ *
+ * Returns ``true`` when the item carries a bbox the canvas can
+ * draw + tooltip + jump to, or a non-empty ``regions`` array for
+ * multi-rect findings. Returns ``false`` for page-level items
+ * (whole-page metadata, classification labels, document-scoped
+ * advisories, etc.) — those should be surfaced separately and
+ * NOT made clickable, since the click has nowhere to go.
+ *
+ * Hosts MUST use this predicate (not a bare ``item.bbox != null``
+ * check) so future overlay kinds (regions, polygons, masks) stay
+ * supported without each consumer growing its own duplicated
+ * heuristic.
+ */
+export declare function hasViewerLocation(item: OverlayItem): boolean;
+/**
+ * Split OverlayItems into ``{ located, informational }``.
+ *
+ * Order within each bucket is preserved — useful when the host
+ * sorts findings by tier / page / severity before passing them
+ * in and wants the sidebar to render in the same order.
+ *
+ * @example
+ * ```ts
+ * import { splitFindingsByLocation } from "@printwithsynergy/lens-pdf";
+ *
+ * const { located, informational } = splitFindingsByLocation(items);
+ * // Pass `located` to <LensPDF items={...}> so only locatable
+ * // findings draw on the canvas; render `informational` in a
+ * // separate non-clickable section of your sidebar.
+ * ```
+ */
+export declare function splitFindingsByLocation<T extends OverlayItem>(items: readonly T[]): {
+    located: T[];
+    informational: T[];
+};
+//# sourceMappingURL=findings-location.d.ts.map

package/dist/plugin/findings-location.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"findings-location.d.ts","sourceRoot":"","sources":["../../plugin/findings-location.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAS5D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,WAAW,EAC3D,KAAK,EAAE,SAAS,CAAC,EAAE,GAClB;IAAE,OAAO,EAAE,CAAC,EAAE,CAAC;IAAC,aAAa,EAAE,CAAC,EAAE,CAAA;CAAE,CAWtC"}

package/dist/plugin/findings-location.js

@@ -0,0 +1,72 @@
+/**
+ * Findings location helpers — split OverlayItems into "located in
+ * viewer" (those with a position the canvas can highlight + click)
+ * and "informational" (page-level metadata that's still surfaced
+ * to consumers, just not as a clickable overlay).
+ *
+ * Adapter authors moving findings from other preflight engines
+ * (callas pdfToolbox, PitStop, Acrobat, lint-pdf, custom rule
+ * engines) into Lens's contract should rely on these helpers to
+ * categorise each finding the same way Lens's canvas does — there
+ * is one source of truth for "can the viewer locate this?".
+ *
+ * @module
+ */
+/**
+ * Decide whether an OverlayItem can be located on the page.
+ *
+ * Returns ``true`` when the item carries a bbox the canvas can
+ * draw + tooltip + jump to, or a non-empty ``regions`` array for
+ * multi-rect findings. Returns ``false`` for page-level items
+ * (whole-page metadata, classification labels, document-scoped
+ * advisories, etc.) — those should be surfaced separately and
+ * NOT made clickable, since the click has nowhere to go.
+ *
+ * Hosts MUST use this predicate (not a bare ``item.bbox != null``
+ * check) so future overlay kinds (regions, polygons, masks) stay
+ * supported without each consumer growing its own duplicated
+ * heuristic.
+ */
+export function hasViewerLocation(item) {
+    if (Array.isArray(item.bbox) && item.bbox.length === 4)
+        return true;
+    // Future overlay shapes — polygons / regions — are still under
+    // the same predicate. Adapter authors that emit ``regions`` on
+    // an OverlayItem don't need to also set ``bbox`` for the canvas
+    // to consider the item located.
+    const maybe = item;
+    if (Array.isArray(maybe.regions) && maybe.regions.length > 0)
+        return true;
+    return false;
+}
+/**
+ * Split OverlayItems into ``{ located, informational }``.
+ *
+ * Order within each bucket is preserved — useful when the host
+ * sorts findings by tier / page / severity before passing them
+ * in and wants the sidebar to render in the same order.
+ *
+ * @example
+ * ```ts
+ * import { splitFindingsByLocation } from "@printwithsynergy/lens-pdf";
+ *
+ * const { located, informational } = splitFindingsByLocation(items);
+ * // Pass `located` to <LensPDF items={...}> so only locatable
+ * // findings draw on the canvas; render `informational` in a
+ * // separate non-clickable section of your sidebar.
+ * ```
+ */
+export function splitFindingsByLocation(items) {
+    const located = [];
+    const informational = [];
+    for (const item of items) {
+        if (hasViewerLocation(item)) {
+            located.push(item);
+        }
+        else {
+            informational.push(item);
+        }
+    }
+    return { located, informational };
+}
+//# sourceMappingURL=findings-location.js.map

package/dist/plugin/findings-location.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"findings-location.js","sourceRoot":"","sources":["../../plugin/findings-location.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAiB;IACjD,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACpE,+DAA+D;IAC/D,+DAA+D;IAC/D,gEAAgE;IAChE,gCAAgC;IAChC,MAAM,KAAK,GAAG,IAAwC,CAAC;IACvD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1E,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,uBAAuB,CACrC,KAAmB;IAEnB,MAAM,OAAO,GAAQ,EAAE,CAAC;IACxB,MAAM,aAAa,GAAQ,EAAE,CAAC;IAC9B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,iBAAiB,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrB,CAAC;aAAM,CAAC;YACN,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC;AACpC,CAAC"}

package/dist/plugin/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Viewer plugin protocol — public surface.
+ *
+ * @public
+ */
+export type { AnnotationSourceProvider, DialogPlugin, MeasurementUnit, OverlayItem, OverlayPlugin, PanelPlugin, ToolbarPlugin, ViewerPlugin, ViewerPluginManifest, ViewerSlot, } from "./types";
+export type { ViewerContext, ViewerDocumentMetadata, ViewerViewport, } from "./context";
+export type { AnnotationEntry, AnnotationService, ColorSampleService, DensitometerService, I18nService, LayerService, PageImageService, PdfFallbackAdapter, ReportsService, SeparationService, TACHeatmapService, TelemetryService, ThemeTokens, ViewerServices, } from "./services";
+export { darkThemeTokens, defaultThemeTokens, isUnwired, markUnwired, noopI18n, noopTelemetry, } from "./services";
+export { _resetRegistryForTesting, getPluginsForSlot, listAll, register, unregister, } from "./registry";
+/**
+ * Findings-location helpers — shared logic for adapter authors
+ * (lint-pdf, callas, PitStop, Acrobat, custom rule engines) that
+ * map their findings into ``OverlayItem``s. Use these to split
+ * located findings (the viewer can highlight + click) from
+ * informational findings (page-level metadata).
+ */
+export { hasViewerLocation, splitFindingsByLocation } from "./findings-location";
+//# sourceMappingURL=index.d.ts.map

package/dist/plugin/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../plugin/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EACV,wBAAwB,EACxB,YAAY,EACZ,eAAe,EACf,WAAW,EACX,aAAa,EACb,WAAW,EACX,aAAa,EACb,YAAY,EACZ,oBAAoB,EACpB,UAAU,GACX,MAAM,SAAS,CAAC;AAEjB,YAAY,EACV,aAAa,EACb,sBAAsB,EACtB,cAAc,GACf,MAAM,WAAW,CAAC;AAEnB,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACnB,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,WAAW,EACX,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,SAAS,EACT,WAAW,EACX,QAAQ,EACR,aAAa,GACd,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,wBAAwB,EACxB,iBAAiB,EACjB,OAAO,EACP,QAAQ,EACR,UAAU,GACX,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/plugin/index.js

@@ -0,0 +1,16 @@
+/**
+ * Viewer plugin protocol — public surface.
+ *
+ * @public
+ */
+export { darkThemeTokens, defaultThemeTokens, isUnwired, markUnwired, noopI18n, noopTelemetry, } from "./services.js";
+export { _resetRegistryForTesting, getPluginsForSlot, listAll, register, unregister, } from "./registry.js";
+/**
+ * Findings-location helpers — shared logic for adapter authors
+ * (lint-pdf, callas, PitStop, Acrobat, custom rule engines) that
+ * map their findings into ``OverlayItem``s. Use these to split
+ * located findings (the viewer can highlight + click) from
+ * informational findings (page-level metadata).
+ */
+export { hasViewerLocation, splitFindingsByLocation } from "./findings-location.js";
+//# sourceMappingURL=index.js.map

package/dist/plugin/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../plugin/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAsCH,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,SAAS,EACT,WAAW,EACX,QAAQ,EACR,aAAa,GACd,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,wBAAwB,EACxB,iBAAiB,EACjB,OAAO,EACP,QAAQ,EACR,UAAU,GACX,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC"}