@printwithsynergy/lens-pdf 0.3.0-beta.81

package/docs/services.md

@@ -0,0 +1,210 @@
+---
+title: "Wiring ViewerServices"
+description: "Implement only the protocols your host supports — page images, layers, separations, TAC heatmaps, color sampling, densitometer, annotations, reports. Unwired services hide their consuming components automatically."
+group: "Reference"
+order: 3
+---
+
+# Wiring `ViewerServices`
+
+Every field on `ViewerServices` is independent. Implement the ones your host
+supports; the rest fall through to *unwired* no-op defaults exported from
+`@printwithsynergy/lens-pdf/plugin`. Consuming components detect the unwired
+state and self-hide rather than rendering empty placeholders — see
+[docs/fallback.md](./fallback.md) for the full capability-detection model,
+the in-browser pdf.js fallback, and debug logging.
+
+### Quick start with `defaultUnwiredServices`
+
+The easiest way to build a partial `ViewerServices` is to spread the
+pre-built defaults and override only the services your host provides:
+
+```ts
+import { defaultUnwiredServices } from "@printwithsynergy/lens-pdf/host";
+
+export const services = {
+  ...defaultUnwiredServices,
+  pageImages: {
+    getPageImageUrl: ({ pageNum, dpi }) =>
+      `/api/pdf/${pageNum}.png?dpi=${dpi}`,
+  },
+  tokens: { ...defaultUnwiredServices.tokens, accent: "#e50c6a" },
+};
+```
+
+Everything you don't override stays *unwired* and the consuming
+components self-hide.
+
+### Manual approach
+
+The full manual approach gives you finer-grained control:
+
+```ts
+import type { ViewerServices } from "@printwithsynergy/lens-pdf/plugin";
+import {
+  defaultThemeTokens,
+  noopI18n,
+  noopTelemetry,
+} from "@printwithsynergy/lens-pdf/plugin";
+
+export const services: ViewerServices = {
+  pageImages: {
+    getPageImageUrl: ({ pageNum, dpi }) =>
+      `/api/pdf/${pageNum}.png?dpi=${dpi}`,
+  },
+
+  layers: {
+    getLayerImageUrl: ({ pageNum, layerIndex, dpi }) =>
+      `/api/pdf/${pageNum}/layer/${layerIndex}.png?dpi=${dpi}`,
+    listLayers: async () => [
+      { name: "Background", ocg_index: 0, default_on: true },
+      { name: "CutContour", ocg_index: 1, default_on: true },
+    ],
+  },
+
+  separations: {
+    getChannelImageUrl: ({ pageNum, channelName, dpi }) =>
+      `/api/pdf/${pageNum}/channel/${encodeURIComponent(channelName)}.png?dpi=${dpi}`,
+  },
+
+  tacHeatmap: {
+    getHeatmapImageUrl: ({ pageNum, dpi, tacLimit }) =>
+      `/api/pdf/${pageNum}/tac.png?dpi=${dpi}&limit=${tacLimit}`,
+    listRuns: async () => [],
+  },
+
+  colorSample: {
+    sampleAt: async ({ pageNum, pdfX, pdfY }) => {
+      const r = await fetch(`/api/pdf/${pageNum}/color?x=${pdfX}&y=${pdfY}`);
+      return r.ok ? await r.json() : null;
+    },
+  },
+
+  densitometer: {
+    sampleAt: async (args) => {
+      const r = await fetch(`/api/pdf/${args.pageNum}/density`, {
+        method: "POST",
+        body: JSON.stringify(args),
+      });
+      if (!r.ok) {
+        if (r.status === 422) throw new Error("No separations available for this page.");
+        throw new Error(`Sampling failed (${r.status})`);
+      }
+      return await r.json();
+    },
+  },
+
+  annotations: {
+    list: async () => [],
+    getForPage: async () => null,
+    saveForPage: async () => {},
+    remove: async () => {},
+  },
+
+  reports: {
+    getHtmlReportUrl: () => "/api/pdf/report.html",
+    getPdfDownloadUrl: () => "/api/pdf/report.pdf",
+  },
+
+  telemetry: noopTelemetry,
+  i18n: noopI18n,
+  tokens: defaultThemeTokens,
+};
+```
+
+## When you need each field
+
+| Service | When you need it |
+| --- | --- |
+| `pageImages.getPageImageUrl` | Always. Returns the URL of the rendered page tile at a given DPI. |
+| `layers.*` | Mounting `LayerCanvas` or `LayerPanel`. Provides per-OCG isolated tiles + the OCG list. |
+| `separations.getChannelImageUrl` | Mounting `SeparationCanvas`. Returns one tile per ink channel with a transparent background — the canvas composites locally. |
+| `tacHeatmap.*` | Mounting `TACHeatmapOverlay`. Provides a heatmap image plus per-text-run TAC readings for hover tooltips. |
+| `colorSample.sampleAt` | `ColorPickerTool`. Returns RGB + hex + TAC at a PDF point, or `null` on failure. |
+| `densitometer.sampleAt` | `DensitometerTool`. Returns ink-channel percentages + TAC. Throw `Error("No separations available for this page.")` for RGB-only PDFs — the tool surfaces the message verbatim. |
+| `annotations.*` | `AnnotationCanvas`, `AnnotationThread`. Per-page upsert + global list + delete. |
+| `reports.*` | Report-export menu items in `MobileDrawer` or your own toolbar. |
+| `telemetry`, `i18n`, `tokens` | Always present; defaults are safe. Override to plug into your analytics, translation table, or brand palette. |
+
+## Notes on each service
+
+### `pageImages`
+
+URL builders are **synchronous**. If your host needs async signing,
+pre-resolve into a redirect proxy or blob URL upstream. Returning a Promise
+here would force every `<img src={...}>` consumer through `useEffect` +
+state, which doesn't fit the rendering pattern.
+
+The viewer caches results internally — your service should not implement
+its own cache.
+
+### `layers`
+
+`getLayerImageUrl` returns one PNG per OCG with a transparent background
+(typically rendered via Ghostscript's `pngalpha` device with every other
+OCG hidden). The browser composites the active subset locally with
+`source-over` blending, so toggling a layer is just a redraw — no API
+round-trip after the first warm-up.
+
+### `separations`
+
+Same instant-toggle pattern, but per ink channel. Channel name is a
+process ink (`"Cyan"`, `"Magenta"`, `"Yellow"`, `"Black"`) or a spot ink
+(`"Pantone Reflex Blue C"`, etc.). Your service is responsible for
+percent-encoding the channel name in whatever URL it returns.
+
+> Real ink separations require a server-side renderer (Ghostscript,
+> MuPDF, etc.) — the in-browser pdf.js fallback can't produce them.
+> See [server.md](./server.md) for a deployable reference.
+
+### `tacHeatmap`
+
+`getHeatmapImageUrl` returns a per-pixel RGBA tint over the page.
+`listRuns` returns per-text-run TAC readings used for the hover-tooltip
+layer. Run coordinates use a **top-left origin** to match poppler's
+`pdftotext -bbox` output (the rest of the API uses lower-left).
+
+> Like `separations`, the heatmap is computed from per-ink rasters and
+> is server-side only. See [server.md](./server.md).
+
+### `colorSample`
+
+The tool deliberately swallows errors — return `null` instead of throwing
+so a flaky network doesn't pop a tooltip with a confusing fallback color.
+
+### `densitometer`
+
+Distinct error messages your `sampleAt` can throw to drive the tool's UI:
+
+- `"No separations available for this page."` — engine 422 (RGB-only
+  document, no CMYK to split). Surfaces as the friendly amber banner.
+- `"Sampling failed (NNN)"` — engine non-2xx other than 422.
+- `"Network error"` — fetch rejected.
+
+The tool reads `Error.message` verbatim — keep messages user-facing.
+
+> Server-side only — see [server.md](./server.md).
+
+### `annotations`
+
+Four concrete methods that match the actual call sites:
+
+- `list()` — sidebar thread (every page, every author).
+- `getForPage(pageNum)` — canvas init for the active author.
+- `saveForPage(pageNum, fabricJson)` — canvas autosave (best-effort; the
+  canvas swallows network errors so the user can keep drawing).
+- `remove(id)` — sidebar thread.
+
+`fabricJson` is an opaque `unknown` — only the host and `AnnotationCanvas`
+interpret it (it's the serialised Fabric.js canvas snapshot).
+
+### `reports`
+
+Both URL builders are synchronous. Hosts without report exports leave the
+no-op defaults — the consuming menu items (currently `MobileDrawer`'s
+"Share &amp; Export" section) drop the report links entirely rather than
+rendering inert hrefs.
+
+### `telemetry`, `i18n`, `tokens`
+
+See [theming.md](./theming.md).

package/docs/share-links.md

@@ -0,0 +1,111 @@
+---
+title: "Shareable links"
+description: "Generate and parse shareable viewer URLs that pre-load a specific PDF with custom settings — fullscreen, zoom, page, mode, tools, and theme."
+group: "Reference"
+order: 9
+---
+
+# Shareable links
+
+`generateShareLink()` builds a URL that opens any LensPDF host page
+with a specific PDF pre-loaded and settings applied.
+`parseShareParams()` reads those query params back into props your
+component can consume.
+
+Both are exported from `@printwithsynergy/lens-pdf/host`.
+
+## URL format
+
+```
+https://lenspdf.com/demo?url=<encoded>&fullscreen=true&zoom=150&page=1&mode=single&theme=dark
+```
+
+| Param | Type | Notes |
+| --- | --- | --- |
+| `url` | URL-encoded string | PDF URL to pre-load. |
+| `fullscreen` | `"true"` \| `"1"` | Open in fullscreen (no site chrome). |
+| `zoom` | integer | Initial zoom percentage. |
+| `page` | integer | Initial page number (1-indexed). |
+| `mode` | `"scroll"` \| `"single"` | Defaults to `"scroll"` when absent. |
+| `tools` | comma-separated | Subset of tools to enable. |
+| `theme` | `"light"` \| `"dark"` \| JSON | Preset name or inline `ThemeTokens`. |
+
+## Generating a link
+
+```ts
+import { generateShareLink } from "@printwithsynergy/lens-pdf/host";
+
+const link = generateShareLink({
+  baseUrl: "https://lenspdf.com/demo",
+  pdfUrl: "https://cdn.example.com/proof.pdf",
+  fullscreen: true,
+  zoom: 150,
+  page: 2,
+});
+// → "https://lenspdf.com/demo?url=https%3A%2F%2Fcdn.example.com%2Fproof.pdf&fullscreen=true&zoom=150&page=2"
+```
+
+### `ShareLinkOptions`
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `baseUrl` | `string` | required | Host demo/viewer page URL. |
+| `pdfUrl` | `string` | required | PDF URL to pre-load. |
+| `fullscreen` | `boolean` | `false` | Fixed-position full-viewport. |
+| `zoom` | `number` | _(omitted)_ | Percentage. |
+| `page` | `number` | _(omitted)_ | 1-indexed page. |
+| `mode` | `"scroll" \| "single"` | `"scroll"` | Only serialised when not `"scroll"`. |
+| `tools` | `string[]` | _(omitted)_ | Comma-joined in URL. |
+| `theme` | `"light" \| "dark" \| Partial<ThemeTokens>` | _(omitted)_ | Preset name or JSON-encoded tokens. |
+
+## Parsing on the consumer side
+
+```ts
+import { parseShareParams } from "@printwithsynergy/lens-pdf/host";
+
+const params = parseShareParams(new URLSearchParams(window.location.search));
+
+// params.pdfUrl      → "https://cdn.example.com/proof.pdf"
+// params.fullscreen  → true
+// params.zoom        → 150
+// params.page        → 2
+```
+
+### `ParsedShareParams`
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `pdfUrl` | `string \| undefined` | |
+| `fullscreen` | `boolean` | Defaults to `false`. |
+| `zoom` | `number \| undefined` | |
+| `page` | `number \| undefined` | |
+| `mode` | `"scroll" \| "single" \| undefined` | |
+| `tools` | `string[] \| undefined` | |
+| `theme` | `"light" \| "dark" \| Partial<ThemeTokens> \| undefined` | |
+
+## End-to-end with `<LensPDFDemo>`
+
+Wire `parseShareParams` into `<LensPDFDemo>` props:
+
+```tsx
+import { LensPDFDemo } from "@printwithsynergy/lens-pdf/components";
+import { parseShareParams } from "@printwithsynergy/lens-pdf/host";
+
+export function DemoPage() {
+  const params = parseShareParams(new URLSearchParams(window.location.search));
+
+  return (
+    <LensPDFDemo
+      brand="MyApp"
+      initialPdfUrl={params.pdfUrl}
+      fullscreen={params.fullscreen}
+      initialZoom={params.zoom ?? 80}
+      initialPage={params.page}
+    />
+  );
+}
+```
+
+Users can now share links like
+`https://myapp.com/demo?url=https://cdn.example.com/proof.pdf&fullscreen=true`
+that open the viewer full-screen with the PDF pre-loaded.

package/docs/theming.md

@@ -0,0 +1,164 @@
+---
+title: "Theme, i18n, telemetry, read-only mode"
+description: "Brand tokens, translation strings, analytics hooks, and the read-only flag for share-link viewers. All optional — the no-op defaults keep OSS hosts fast."
+group: "Reference"
+order: 8
+---
+
+# Theme, i18n, telemetry, read-only mode
+
+Three of the `ViewerServices` fields are infrastructure rather than data:
+`tokens`, `i18n`, `telemetry`. They always have safe defaults; override
+when you need to plug into your brand palette, translation table, or
+analytics. The `readOnly` flag lives on `ViewerHostContext` and toggles
+write-only UI.
+
+## Theme tokens
+
+```ts
+interface ThemeTokens {
+  readonly primary: string;   // brand primary
+  readonly accent: string;    // brand accent
+  readonly bg: string;        // surface background
+  readonly fg: string;        // foreground / body text
+  readonly border: string;    // hairline border
+  // Optional brand-identity fields read by <LensPDFDemo> as a
+  // fallback when the equivalent props (`brand`, `brandLogoUrl`)
+  // aren't set. Lets a host bundle palette + logo + label into a
+  // single tokens object.
+  readonly logoUrl?: string;        // brand logo image URL
+  readonly logoText?: string;       // brand label (default: "LensPDF")
+  readonly logoMaxHeight?: number;  // pixel cap on logo height (default: 24)
+  readonly logoAlt?: string;        // alt text for the logo <img>
+}
+```
+
+`defaultThemeTokens` is a neutral light palette:
+
+```ts
+import { defaultThemeTokens } from "@printwithsynergy/lens-pdf/plugin";
+
+// {
+//   primary: "#0f172a",
+//   accent:  "#3b82f6",
+//   bg:      "#ffffff",
+//   fg:      "#0f172a",
+//   border:  "#e2e8f0",
+// }
+```
+
+`darkThemeTokens` is a dark palette preset for demo and dark-mode UIs:
+
+```ts
+import { darkThemeTokens } from "@printwithsynergy/lens-pdf/plugin";
+
+// {
+//   primary: "#0f172a",
+//   accent:  "#3b82f6",
+//   bg:      "#0e0a14",
+//   fg:      "#f5f3f7",
+//   border:  "#2b2138",
+// }
+```
+
+`<LensPDFDemo>` uses `darkThemeTokens` by default; `<LensPDFViewer>`
+uses `defaultThemeTokens`.
+
+Pass your own through `services.tokens`:
+
+```ts
+const services: ViewerServices = {
+  // …
+  tokens: {
+    primary: "#1a3a7a",
+    accent: "#2563eb",
+    bg: "#ffffff",
+    fg: "#0f172a",
+    border: "#e2e8f0",
+  },
+};
+```
+
+Plugins read from `ctx.services.tokens` rather than hardcoding hex
+strings, so swapping a brand palette is a single context-value change.
+
+## i18n
+
+```ts
+interface I18nService {
+  t(key: string, params?: Record<string, string | number>): string;
+}
+```
+
+The `noopI18n` default returns the key unchanged with `{param}`
+placeholders substituted. Drop in a real translator as needed:
+
+```ts
+import type { I18nService } from "@printwithsynergy/lens-pdf/plugin";
+
+export const i18n: I18nService = {
+  t: (key, params) => translateWithICU(key, params),
+};
+```
+
+Suitable for English-only environments and tests, the no-op behaves
+like:
+
+```ts
+noopI18n.t("hello.name", { name: "Ada" });    // "hello.name"
+// (the key is returned because no entry exists; placeholders still
+// substitute when present in the key text itself)
+```
+
+## Telemetry
+
+```ts
+interface TelemetryService {
+  track(event: string, properties?: Record<string, unknown>): void;
+}
+```
+
+`noopTelemetry` drops every event on the floor. Wire your analytics by
+overriding:
+
+```ts
+import type { TelemetryService } from "@printwithsynergy/lens-pdf/plugin";
+
+export const telemetry: TelemetryService = {
+  track: (event, props) => window.analytics?.track(event, props),
+};
+```
+
+OSS hosts that don't want to ship analytics can leave the no-op default —
+no events will leave the browser.
+
+## Read-only mode
+
+Set `ViewerHostContext.readOnly` to `true` to suppress write-only UI.
+
+```tsx
+<ViewerHostContext.Provider
+  value={{
+    apiBase: "/api/share/abc123",
+    jobApiBase: "/api/share/abc123",
+    readOnly: true,
+  }}
+>
+  …
+</ViewerHostContext.Provider>
+```
+
+What flips:
+
+- `AnnotationCanvas` skips its autosave path entirely (reads still work,
+  saves are a no-op).
+- `MobileDrawer` hides annotation, share, and verdict controls based on
+  the same flag.
+- Your own host UI should branch on `useViewerHost().readOnly` to hide
+  any control that mutates server state.
+
+Public-token / share-link viewers typically run with `readOnly: true` and
+a constrained `apiBase` (`/api/share/<token>` etc.), with annotations
+read but not written. The annotation service can be wired to a no-op
+`saveForPage` / `remove` even when `readOnly` is false, but flipping the
+host flag is the standard pattern.

package/docs/validation.md

@@ -0,0 +1,83 @@
+---
+title: "PDF validation"
+description: "Client-side PDF validation — magic bytes, MIME type, file size — before handing a file to the viewer or pdf.js fallback. Runs entirely in the browser."
+group: "Reference"
+order: 10
+---
+
+# PDF validation
+
+LensPDF ships client-side validation utilities that run entirely in the
+browser. Use them before handing user-supplied files or URLs to the
+viewer.
+
+Both are exported from `@printwithsynergy/lens-pdf/host`.
+
+## `validatePdfFile(file, maxBytes?)`
+
+Async. Checks a `File` object:
+
+1. **MIME type** — must be `application/pdf` (or empty — some browsers
+   don't populate MIME for drag-dropped files).
+2. **Magic bytes** — first 5 bytes must be `%PDF-` (hex `25 50 44 46 2D`).
+3. **Size** — must be ≤ `maxBytes` (default: 50 MB).
+
+```ts
+import { validatePdfFile } from "@printwithsynergy/lens-pdf/host";
+
+const result = await validatePdfFile(file);
+if (!result.valid) {
+  console.error(result.error);
+}
+```
+
+Pass a custom limit:
+
+```ts
+const result = await validatePdfFile(file, 100 * 1024 * 1024); // 100 MB
+```
+
+## `validatePdfUrl(url)`
+
+Synchronous. Validates URL format only — does not fetch or inspect
+headers.
+
+Checks:
+1. String is non-empty after trimming.
+2. Parses as a valid `URL`.
+3. Protocol is `http:`, `https:`, or `blob:`.
+
+```ts
+import { validatePdfUrl } from "@printwithsynergy/lens-pdf/host";
+
+const result = validatePdfUrl(draftUrl);
+if (!result.valid) {
+  setError(result.error);
+  return;
+}
+```
+
+## `PdfValidationResult`
+
+Both functions return the same shape:
+
+```ts
+interface PdfValidationResult {
+  valid: boolean;
+  error?: string; // Human-readable message when valid is false
+}
+```
+
+## Built-in usage
+
+`<LensPDFDemo>` calls both validators automatically — file uploads go
+through `validatePdfFile` and URL submissions go through
+`validatePdfUrl`. The `maxFileSize` prop on `LensPDFDemo` is forwarded
+to `validatePdfFile`.
+
+## Security note
+
+These checks are **client-side only** and meant to catch user mistakes
+early (wrong file type, oversized files, malformed URLs). They are not
+a security boundary — a determined user can bypass them. Always validate
+and sanitise uploads on the server side when applicable.