@printwithsynergy/lens-pdf 0.3.0-beta.81

package/dist/plugin/registry.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Viewer plugin registry — runtime registration + slot-aware lookup.
+ *
+ * Plugin packs call `register(plugin)` during module load (typically
+ * from a top-level `register.ts` the consumer imports for side
+ * effects). The viewer reads `getPluginsForSlot(slot)` at render
+ * time to find what to mount.
+ *
+ * The registry is process-wide. Apps mounting two viewer instances on
+ * the same page currently share the same plugin set; per-instance
+ * scoping is a future addition.
+ *
+ * @public
+ */
+import type { ViewerPlugin, ViewerSlot } from "./types";
+/**
+ * Register a plugin. Throws on duplicate id, or on a second
+ * `replaces` claim against the same target.
+ *
+ * @public
+ */
+export declare function register(plugin: ViewerPlugin): void;
+/**
+ * Unregister a plugin by id. No-op if absent. Also clears any
+ * `replaces` claim this plugin held, freeing the target for a
+ * subsequent override.
+ *
+ * @public
+ */
+export declare function unregister(id: string): void;
+/**
+ * Return every registered plugin for a slot, sorted by `order` asc
+ * (where supported by the plugin shape; defaults to insertion order).
+ *
+ * Plugins that have been overridden via another plugin's `replaces`
+ * field are filtered out — the overrider takes their place when it
+ * shares the same slot. Cross-slot overrides also remove the
+ * original from this slot (the override declares an intent to take
+ * over the named feature; rendering the replaced one alongside
+ * would defeat the override semantics).
+ *
+ * @public
+ */
+export declare function getPluginsForSlot<S extends ViewerSlot>(slot: S): Array<Extract<ViewerPlugin, {
+    slot: S;
+}>>;
+/**
+ * Snapshot of every registered plugin (mainly for tests / debugging).
+ * Includes plugins that have been overridden — `getPluginsForSlot`
+ * filters those out, but they remain in the registry.
+ *
+ * @public
+ */
+export declare function listAll(): ReadonlyArray<ViewerPlugin>;
+/**
+ * Reset the registry. **Test-only.** Production code never calls this.
+ *
+ * @public
+ */
+export declare function _resetRegistryForTesting(): void;
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../plugin/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAOxD;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAkBnD;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAM3C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,UAAU,EACpD,IAAI,EAAE,CAAC,GACN,KAAK,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,CAAC,CAAA;CAAE,CAAC,CAAC,CAa3C;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,IAAI,aAAa,CAAC,YAAY,CAAC,CAErD;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAG/C"}

package/dist/plugin/registry.js

@@ -0,0 +1,102 @@
+/**
+ * Viewer plugin registry — runtime registration + slot-aware lookup.
+ *
+ * Plugin packs call `register(plugin)` during module load (typically
+ * from a top-level `register.ts` the consumer imports for side
+ * effects). The viewer reads `getPluginsForSlot(slot)` at render
+ * time to find what to mount.
+ *
+ * The registry is process-wide. Apps mounting two viewer instances on
+ * the same page currently share the same plugin set; per-instance
+ * scoping is a future addition.
+ *
+ * @public
+ */
+const _registry = new Map();
+// id-of-target → id-of-overrider. When `replaces` is set on a
+// registered plugin, that plugin shadows the target in slot lookups.
+const _overrides = new Map();
+/**
+ * Register a plugin. Throws on duplicate id, or on a second
+ * `replaces` claim against the same target.
+ *
+ * @public
+ */
+export function register(plugin) {
+    if (_registry.has(plugin.id)) {
+        throw new Error(`viewer plugin already registered: ${plugin.id} ` +
+            `(version ${_registry.get(plugin.id)?.version})`);
+    }
+    if (plugin.replaces !== undefined) {
+        const claimer = _overrides.get(plugin.replaces);
+        if (claimer !== undefined) {
+            throw new Error(`viewer plugin override conflict: '${plugin.id}' tried to ` +
+                `replace '${plugin.replaces}', but '${claimer}' already does`);
+        }
+        _overrides.set(plugin.replaces, plugin.id);
+    }
+    _registry.set(plugin.id, plugin);
+}
+/**
+ * Unregister a plugin by id. No-op if absent. Also clears any
+ * `replaces` claim this plugin held, freeing the target for a
+ * subsequent override.
+ *
+ * @public
+ */
+export function unregister(id) {
+    const plugin = _registry.get(id);
+    if (plugin?.replaces !== undefined) {
+        _overrides.delete(plugin.replaces);
+    }
+    _registry.delete(id);
+}
+/**
+ * Return every registered plugin for a slot, sorted by `order` asc
+ * (where supported by the plugin shape; defaults to insertion order).
+ *
+ * Plugins that have been overridden via another plugin's `replaces`
+ * field are filtered out — the overrider takes their place when it
+ * shares the same slot. Cross-slot overrides also remove the
+ * original from this slot (the override declares an intent to take
+ * over the named feature; rendering the replaced one alongside
+ * would defeat the override semantics).
+ *
+ * @public
+ */
+export function getPluginsForSlot(slot) {
+    const matches = [];
+    for (const plugin of _registry.values()) {
+        if (plugin.slot !== slot)
+            continue;
+        if (_overrides.has(plugin.id))
+            continue; // someone replaces this
+        matches.push(plugin);
+    }
+    matches.sort((a, b) => {
+        const ao = "order" in a ? (a.order ?? 0) : 0;
+        const bo = "order" in b ? (b.order ?? 0) : 0;
+        return ao - bo;
+    });
+    return matches;
+}
+/**
+ * Snapshot of every registered plugin (mainly for tests / debugging).
+ * Includes plugins that have been overridden — `getPluginsForSlot`
+ * filters those out, but they remain in the registry.
+ *
+ * @public
+ */
+export function listAll() {
+    return Array.from(_registry.values());
+}
+/**
+ * Reset the registry. **Test-only.** Production code never calls this.
+ *
+ * @public
+ */
+export function _resetRegistryForTesting() {
+    _registry.clear();
+    _overrides.clear();
+}
+//# sourceMappingURL=registry.js.map

package/dist/plugin/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../plugin/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,MAAM,SAAS,GAA8B,IAAI,GAAG,EAAE,CAAC;AACvD,8DAA8D;AAC9D,qEAAqE;AACrE,MAAM,UAAU,GAAwB,IAAI,GAAG,EAAE,CAAC;AAElD;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,MAAoB;IAC3C,IAAI,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACb,qCAAqC,MAAM,CAAC,EAAE,GAAG;YAC/C,YAAY,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,OAAO,GAAG,CACnD,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QAClC,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAChD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CACb,qCAAqC,MAAM,CAAC,EAAE,aAAa;gBACzD,YAAY,MAAM,CAAC,QAAQ,WAAW,OAAO,gBAAgB,CAChE,CAAC;QACJ,CAAC;QACD,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;IAC7C,CAAC;IACD,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;AACnC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,EAAU;IACnC,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACjC,IAAI,MAAM,EAAE,QAAQ,KAAK,SAAS,EAAE,CAAC;QACnC,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACrC,CAAC;IACD,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AACvB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAO;IAEP,MAAM,OAAO,GAA8C,EAAE,CAAC;IAC9D,KAAK,MAAM,MAAM,IAAI,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC;QACxC,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI;YAAE,SAAS;QACnC,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YAAE,SAAS,CAAC,wBAAwB;QACjE,OAAO,CAAC,IAAI,CAAC,MAA4C,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACpB,MAAM,EAAE,GAAG,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7C,MAAM,EAAE,GAAG,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7C,OAAO,EAAE,GAAG,EAAE,CAAC;IACjB,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,OAAO;IACrB,OAAO,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC;AACxC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,wBAAwB;IACtC,SAAS,CAAC,KAAK,EAAE,CAAC;IAClB,UAAU,CAAC,KAAK,EAAE,CAAC;AACrB,CAAC"}

package/dist/plugin/services.d.ts

@@ -0,0 +1,380 @@
+/**
+ * Viewer services — host-supplied data-source protocols.
+ *
+ * Components reach page images, layers, separations, annotations,
+ * telemetry, i18n, and theme tokens through these protocols rather
+ * than hardcoding any backend specifics. Hosts implement the
+ * protocols their backend supports; the rest fall through to no-op
+ * defaults (see `host/index.ts`) and the consuming components
+ * self-hide.
+ *
+ * @public
+ */
+import type { ColorSample, DensitometerSample } from "../types";
+/**
+ * Page-image source. Returns a URL the viewer renders into a canvas
+ * / `<img>` tag. The viewer caches results — services should not
+ * implement their own cache.
+ *
+ * URL builders are **synchronous**: hosts that need async signing
+ * pre-resolve into a redirect proxy or blob URL upstream. Returning
+ * a Promise here would force every consumer through `useEffect` +
+ * state, which doesn't fit the `<img src={url}>` rendering pattern.
+ *
+ * @public
+ */
+export interface PageImageService {
+    /**
+     * Standard page-tile URL. The host resolves whatever path /
+     * blob / signed URL is appropriate.
+     */
+    getPageImageUrl(args: {
+        pageNum: number;
+        /** Render DPI; viewer asks for the DPI it needs. */
+        dpi: number;
+    }): string;
+}
+/**
+ * PDF Optional Content Group (OCG / "layer") source.
+ *
+ * Hosts that don't expose layers should leave the no-op default
+ * (returns no layers); the `LayerPanel` then renders an empty-
+ * state placeholder.
+ *
+ * @public
+ */
+export interface LayerService {
+    /**
+     * Synchronous URL for an isolated layer image. The host renders
+     * one PNG per OCG with a transparent background; the viewer
+     * composites the active subset locally.
+     */
+    getLayerImageUrl(args: {
+        pageNum: number;
+        layerIndex: number;
+        dpi: number;
+    }): string;
+    /** List the OCGs available for the current document. */
+    listLayers(): Promise<ReadonlyArray<{
+        name: string;
+        ocg_index: number;
+        default_on: boolean;
+    }>>;
+}
+/**
+ * Per-channel separation source. Hosts that don't expose ink
+ * separations leave the no-op default (returns an empty URL); the
+ * SeparationCanvas renders blank stock for any unrenderable channel.
+ *
+ * @public
+ */
+export interface SeparationService {
+    /**
+     * Synchronous URL for an isolated channel image (one PNG per ink
+     * with a transparent background). Channel name is process-ink
+     * (`"Cyan"`, `"Magenta"`, `"Yellow"`, `"Black"`) or a spot ink
+     * (`"Pantone Reflex Blue C"`, etc.). The host is responsible for
+     * percent-encoding the channel name in whatever URL it returns.
+     */
+    getChannelImageUrl(args: {
+        pageNum: number;
+        channelName: string;
+        dpi: number;
+    }): string;
+}
+/**
+ * Total-Area-Coverage heatmap source. Hosts that don't compute a
+ * TAC heatmap leave the no-op default (URL returns empty, runs
+ * resolves to []); the overlay renders nothing in that case.
+ *
+ * @public
+ */
+export interface TACHeatmapService {
+    /** Synchronous URL for the heatmap image (per-pixel RGBA tint). */
+    getHeatmapImageUrl(args: {
+        pageNum: number;
+        dpi: number;
+        tacLimit: number;
+    }): string;
+    /**
+     * Per-text-run TAC readings used to drive the hover-tooltip layer.
+     * Coordinates are PDF points with origin at the **top-left** of the
+     * page (matches poppler's ``pdftotext -bbox`` output).
+     */
+    listRuns(args: {
+        pageNum: number;
+        dpi: number;
+        tacLimit: number;
+    }): Promise<ReadonlyArray<{
+        x0: number;
+        y0: number;
+        x1: number;
+        y1: number;
+        mean_tac: number;
+        limit: number;
+        exceeds: boolean;
+    }>>;
+}
+/**
+ * Color-sampler source — picks the rendered colour at a single PDF
+ * point and returns RGB + hex + total area coverage. Hosts that
+ * don't expose colour sampling leave the no-op default (returns
+ * `null`); the `ColorPickerTool` then shows nothing.
+ *
+ * @public
+ */
+export interface ColorSampleService {
+    /**
+     * Sample at the given PDF coordinates (origin lower-left). Returns
+     * `null` on any failure — the tool deliberately swallows errors so
+     * a flaky network doesn't push a popover with a confusing chrome
+     * fallback colour.
+     */
+    sampleAt(args: {
+        pageNum: number;
+        pdfX: number;
+        pdfY: number;
+        /** Optional render DPI override; service decides the default. */
+        dpi?: number;
+    }): Promise<ColorSample | null>;
+}
+/**
+ * Densitometer source — reads ink-channel percentages + Total Area
+ * Coverage at a PDF point. Hosts that can't split ink channels
+ * (RGB-only documents, no Ghostscript) leave the no-op default —
+ * `sampleAt` then throws a `"No separations"` error so the tool
+ * renders its friendly amber banner.
+ *
+ * @public
+ */
+export interface DensitometerService {
+    /**
+     * Sample at the given PDF coordinates. On success returns the
+     * ink-channel readings + TAC. On failure throws an `Error` with
+     * a short user-facing message — the tool surfaces `.message`
+     * verbatim in its readout panel. Distinct error paths a typical
+     * server-side implementation produces:
+     *   - "No separations available for this page." — backend signals
+     *     the page can't be split (e.g. RGB-only document, no CMYK)
+     *   - "Sampling failed (NNN)" — backend non-2xx other than the
+     *     "no separations" case
+     *   - "Network error" — fetch rejected
+     */
+    sampleAt(args: {
+        pageNum: number;
+        pdfX: number;
+        pdfY: number;
+        /** Optional render DPI override; service decides the default. */
+        dpi?: number;
+        tacLimit: number;
+    }): Promise<DensitometerSample>;
+}
+/**
+ * One annotation record exposed by `AnnotationService.list()` and
+ * `getForPage()`. `fabricJson` is the serialised Fabric.js canvas
+ * snapshot — opaque to `core/`, only the host + the canvas component
+ * inspect it.
+ *
+ * @public
+ */
+export interface AnnotationEntry {
+    id: string;
+    jobId: string;
+    pageNum: number;
+    authorEmail: string;
+    authorName: string | null;
+    createdAt: string;
+    updatedAt: string;
+    fabricJson?: unknown;
+}
+/**
+ * Annotation source. Phase-2 shape replaces the speculative
+ * `list/create/update/remove` Protocol with concrete methods that
+ * match actual call sites: per-page upsert (canvas autosave),
+ * per-page load (canvas init), full list (sidebar thread), delete by
+ * id (sidebar thread).
+ *
+ * Hosts that don't expose annotations leave the no-op default
+ * (returns empty list / null). The `<AnnotationCanvas>` and
+ * `<AnnotationThread>` components both gracefully render their
+ * empty states.
+ *
+ * @public
+ */
+export interface AnnotationService {
+    /** List every annotation for the current job (every page, every author). */
+    list(): Promise<ReadonlyArray<AnnotationEntry>>;
+    /**
+     * Load the active author's saved drawing for one page. Returns
+     * `null` when nothing is saved yet (or the author isn't logged in).
+     */
+    getForPage(pageNum: number): Promise<AnnotationEntry | null>;
+    /**
+     * Upsert the active author's drawing for one page. Best-effort —
+     * implementations should swallow network errors so flaky
+     * connectivity doesn't block the user from continuing to draw.
+     */
+    saveForPage(pageNum: number, fabricJson: unknown): Promise<void>;
+    /** Delete a single annotation by id. */
+    remove(id: string): Promise<void>;
+}
+/**
+ * Report-export source — supplies the URLs the drawer / toolbar
+ * link to for the HTML report viewer and PDF download. Hosts that
+ * don't expose report exports leave the no-op default (returns
+ * empty strings); the consuming menu items render but their links
+ * resolve to the current page (still inert).
+ *
+ * @public
+ */
+export interface ReportsService {
+    /** URL the "View HTML Report" link points at. */
+    getHtmlReportUrl(): string;
+    /** URL the "Download PDF" link points at. */
+    getPdfDownloadUrl(): string;
+}
+/**
+ * Telemetry / analytics. No-op default keeps OSS hosts fast.
+ *
+ * @public
+ */
+export interface TelemetryService {
+    track(event: string, properties?: Record<string, unknown>): void;
+}
+/**
+ * Internationalisation. No-op default returns the key unchanged.
+ *
+ * @public
+ */
+export interface I18nService {
+    t(key: string, params?: Record<string, string | number>): string;
+}
+/**
+ * Optional in-browser fallback that pulls "minimum data" directly from
+ * a raw PDF blob when a host hasn't wired a richer service. Hosts that
+ * supply this — typically by calling ``createPdfJsFallback(pdfUrl)``
+ * exported from ``@printwithsynergy/lens-pdf/host`` — let the viewer
+ * keep tools like PageCanvas, PageNavigator, MeasureTool, LayerPanel,
+ * and ColorPickerTool functional without a server backend.
+ *
+ * **Capabilities not covered**: true ink separations (CMYK/spot
+ * channels), TAC heatmaps, and the densitometer all require server-
+ * side rendering (Ghostscript/MuPDF). pdf.js only renders to RGB, so
+ * those tools stay hidden when their dedicated services are unwired.
+ *
+ * Every method returns a Promise so the adapter can lazy-load pdf.js
+ * on first use. ``sampleColorAt`` returns ``null`` on failure to match
+ * the {@link ColorSampleService} contract.
+ *
+ * @public
+ */
+export interface PdfFallbackAdapter {
+    getPageCount(): Promise<number>;
+    getPageDimensions(pageNum: number): Promise<{
+        widthPts: number;
+        heightPts: number;
+    }>;
+    renderPageToUrl(args: {
+        pageNum: number;
+        dpi: number;
+    }): Promise<string>;
+    listLayers(): Promise<ReadonlyArray<{
+        name: string;
+        ocg_index: number;
+        default_on: boolean;
+    }>>;
+    sampleColorAt(args: {
+        pageNum: number;
+        pdfX: number;
+        pdfY: number;
+        dpi?: number;
+    }): Promise<ColorSample | null>;
+}
+/**
+ * Theme tokens. Plugins that need brand colours read them from here
+ * rather than hardcoding hex strings. The optional `logo*` fields let
+ * a host bundle its full visual identity (colours + logo + label) into
+ * a single object — `<LensPDFDemo>` reads them as a fallback when the
+ * equivalent props (`brand`, `brandLogoUrl`) are not set.
+ *
+ * @public
+ */
+export interface ThemeTokens {
+    readonly primary: string;
+    readonly accent: string;
+    readonly bg: string;
+    readonly fg: string;
+    readonly border: string;
+    /** Optional brand logo image URL shown in the demo top bar. Any URL the browser can fetch — PNG / SVG / `data:` URI. */
+    readonly logoUrl?: string;
+    /** Optional brand label shown next to the logo. Mirrors the `brand` prop on `<LensPDFDemo>`. Default: `"LensPDF"`. */
+    readonly logoText?: string;
+    /** Optional pixel cap on the rendered logo height. Width is auto so non-square logos keep their aspect ratio. Default: 24. */
+    readonly logoMaxHeight?: number;
+    /** Optional alt text for the logo `<img>`. When omitted, the logo is `aria-hidden` and `logoText` carries the meaning. */
+    readonly logoAlt?: string;
+}
+/**
+ * Aggregate service surface exposed via `ViewerContext.services`.
+ *
+ * @public
+ */
+export interface ViewerServices {
+    readonly pageImages: PageImageService;
+    readonly layers: LayerService;
+    readonly separations: SeparationService;
+    readonly tacHeatmap: TACHeatmapService;
+    readonly colorSample: ColorSampleService;
+    readonly densitometer: DensitometerService;
+    readonly annotations: AnnotationService;
+    readonly reports: ReportsService;
+    readonly telemetry: TelemetryService;
+    readonly i18n: I18nService;
+    readonly tokens: ThemeTokens;
+}
+/**
+ * Telemetry stub — drops every event on the floor.
+ *
+ * @public
+ */
+export declare const noopTelemetry: TelemetryService;
+/**
+ * I18n stub — returns the key unchanged. Suitable for English-only
+ * environments and tests.
+ *
+ * @public
+ */
+export declare const noopI18n: I18nService;
+/**
+ * Default theme tokens — neutral light palette. Hosts typically
+ * override these with their tenant or product branding.
+ *
+ * @public
+ */
+export declare const defaultThemeTokens: ThemeTokens;
+/**
+ * Dark theme tokens — dark-mode palette. Drop-in alternative to
+ * {@link defaultThemeTokens} for hosts that want a dark chrome.
+ *
+ * @public
+ */
+export declare const darkThemeTokens: ThemeTokens;
+/**
+ * Tag a service object as a no-op default. Hosts almost never call
+ * this — it's used internally by ``defaultViewerServices`` and
+ * exposed only so unit tests / advanced hosts can simulate the
+ * unwired state.
+ *
+ * @public
+ */
+export declare function markUnwired<T extends object>(service: T): T;
+/**
+ * Returns ``true`` when the given service is the no-op default — i.e.
+ * the host did not wire a real implementation. Components call this
+ * to decide between hiding themselves (unwired) and rendering an
+ * empty state (wired but returned no data).
+ *
+ * @public
+ */
+export declare function isUnwired(service: object | null | undefined): boolean;
+//# sourceMappingURL=services.d.ts.map

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

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

package/dist/plugin/services.js

@@ -0,0 +1,104 @@
+/**
+ * Viewer services — host-supplied data-source protocols.
+ *
+ * Components reach page images, layers, separations, annotations,
+ * telemetry, i18n, and theme tokens through these protocols rather
+ * than hardcoding any backend specifics. Hosts implement the
+ * protocols their backend supports; the rest fall through to no-op
+ * defaults (see `host/index.ts`) and the consuming components
+ * self-hide.
+ *
+ * @public
+ */
+// ---------------------------------------------------------------------------
+// No-op stubs (used by OSS hosts and tests)
+// ---------------------------------------------------------------------------
+/**
+ * Telemetry stub — drops every event on the floor.
+ *
+ * @public
+ */
+export const noopTelemetry = {
+    track: () => { },
+};
+/**
+ * I18n stub — returns the key unchanged. Suitable for English-only
+ * environments and tests.
+ *
+ * @public
+ */
+export const noopI18n = {
+    t: (key, params) => {
+        if (!params)
+            return key;
+        return Object.entries(params).reduce((acc, [k, v]) => acc.replaceAll(`{${k}}`, String(v)), key);
+    },
+};
+/**
+ * Default theme tokens — neutral light palette. Hosts typically
+ * override these with their tenant or product branding.
+ *
+ * @public
+ */
+export const defaultThemeTokens = {
+    primary: "#0f172a",
+    accent: "#3b82f6",
+    bg: "#ffffff",
+    fg: "#0f172a",
+    border: "#e2e8f0",
+};
+/**
+ * Dark theme tokens — dark-mode palette. Drop-in alternative to
+ * {@link defaultThemeTokens} for hosts that want a dark chrome.
+ *
+ * @public
+ */
+export const darkThemeTokens = {
+    primary: "#0f172a",
+    accent: "#3b82f6",
+    bg: "#0e0a14",
+    fg: "#f5f3f7",
+    border: "#2b2138",
+};
+// ---------------------------------------------------------------------------
+// Capability detection
+// ---------------------------------------------------------------------------
+/**
+ * Non-enumerable marker tagged onto every default no-op service so
+ * components can tell "host didn't wire this" apart from "host wired
+ * something that returned no data". Components use the former to hide
+ * themselves outright; the latter still renders an empty state because
+ * the host explicitly opted in.
+ */
+const UNWIRED_MARKER = Symbol.for("@printwithsynergy/lens-pdf:unwired");
+/**
+ * Tag a service object as a no-op default. Hosts almost never call
+ * this — it's used internally by ``defaultViewerServices`` and
+ * exposed only so unit tests / advanced hosts can simulate the
+ * unwired state.
+ *
+ * @public
+ */
+export function markUnwired(service) {
+    Object.defineProperty(service, UNWIRED_MARKER, {
+        value: true,
+        enumerable: false,
+        configurable: false,
+        writable: false,
+    });
+    return service;
+}
+/**
+ * Returns ``true`` when the given service is the no-op default — i.e.
+ * the host did not wire a real implementation. Components call this
+ * to decide between hiding themselves (unwired) and rendering an
+ * empty state (wired but returned no data).
+ *
+ * @public
+ */
+export function isUnwired(service) {
+    if (!service)
+        return true;
+    return service[UNWIRED_MARKER] === true;
+}
+//# sourceMappingURL=services.js.map

package/dist/plugin/services.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"services.js","sourceRoot":"","sources":["../../plugin/services.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAkVH,8EAA8E;AAC9E,4CAA4C;AAC5C,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAqB;IAC7C,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC;CAChB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAgB;IACnC,CAAC,EAAE,CAAC,GAAW,EAAE,MAAwC,EAAE,EAAE;QAC3D,IAAI,CAAC,MAAM;YAAE,OAAO,GAAG,CAAC;QACxB,OAAO,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,CAClC,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,EACpD,GAAG,CACJ,CAAC;IACJ,CAAC;CACF,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAgB;IAC7C,OAAO,EAAE,SAAS;IAClB,MAAM,EAAE,SAAS;IACjB,EAAE,EAAE,SAAS;IACb,EAAE,EAAE,SAAS;IACb,MAAM,EAAE,SAAS;CAClB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAgB;IAC1C,OAAO,EAAE,SAAS;IAClB,MAAM,EAAE,SAAS;IACjB,EAAE,EAAE,SAAS;IACb,EAAE,EAAE,SAAS;IACb,MAAM,EAAE,SAAS;CAClB,CAAC;AAEF,8EAA8E;AAC9E,uBAAuB;AACvB,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,cAAc,GAAG,MAAM,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAC;AAExE;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAmB,OAAU;IACtD,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,cAAc,EAAE;QAC7C,KAAK,EAAE,IAAI;QACX,UAAU,EAAE,KAAK;QACjB,YAAY,EAAE,KAAK;QACnB,QAAQ,EAAE,KAAK;KAChB,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CAAC,OAAkC;IAC1D,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,OAAQ,OAAmC,CAAC,cAAc,CAAC,KAAK,IAAI,CAAC;AACvE,CAAC"}