@printwithsynergy/lens-pdf 0.3.0-beta.81

package/docs/plugins.md

@@ -0,0 +1,256 @@
+---
+title: "Plugin model"
+description: "Slot identifiers, plugin shapes, and registration semantics. Includes the replaces mechanism for shadowing first-party plugins with third-party drop-in alternatives."
+group: "Reference"
+order: 6
+---
+
+# Plugin model
+
+LensPDF mounts plugins into nine slots:
+
+- `overlay.canvas` — drawn on top of the page tile.
+- `panel.right`, `panel.left`, `panel.bottom` — side / bottom panels.
+- `toolbar.top`, `toolbar.left`, `toolbar.bottom` — toolbar pills.
+- `annotation.source` — non-visual; supplies annotation data via
+  `AnnotationSourceProvider`.
+- `dialog.modal` — modal dialog launched from another plugin.
+
+## The manifest
+
+Every plugin shares a manifest:
+
+```ts
+interface ViewerPluginManifest {
+  id: string;          // "vendor.area.feature"
+  version: string;     // semver — bump on protocol-affecting changes
+  slot: ViewerSlot;
+  replaces?: string;   // shadow another plugin's id in slot lookups
+}
+```
+
+Visual plugins (overlay / panel / toolbar / dialog) implement
+`mount(ctx: ViewerContext): ReactNode`. `AnnotationSourceProvider`
+instead provides `subscribe(ctx, onChange)` returning an unsubscribe
+callback.
+
+`ViewerContext` carries the live viewer state and the same
+`ViewerServices` your host wired up:
+
+```ts
+interface ViewerContext {
+  readonly page: number;       // 1-indexed current page
+  readonly zoom: number;       // multiplier; 1.0 = 100%
+  readonly pan: { x: number; y: number };  // CSS px
+  readonly viewport: { width: number; height: number };  // CSS px
+  readonly selectionBbox: readonly [number, number, number, number] | null;
+  readonly document: { pageCount: number; pageDimensions: ReadonlyArray<{ width: number; height: number }> };
+  readonly services: ViewerServices;
+}
+```
+
+## Plugin shapes
+
+### `OverlayPlugin`
+
+```ts
+interface OverlayPlugin extends ViewerPluginManifest {
+  slot: "overlay.canvas";
+  mount(ctx: ViewerContext): ReactNode;
+}
+```
+
+Use for overlays that draw on top of the page canvas (rulers, finding
+boxes, brand-spec violations, etc.).
+
+### `PanelPlugin`
+
+```ts
+interface PanelPlugin extends ViewerPluginManifest {
+  slot: "panel.right" | "panel.left" | "panel.bottom";
+  title: string;       // tab / header label
+  order?: number;      // lower renders first
+  mount(ctx: ViewerContext): ReactNode;
+}
+```
+
+### `ToolbarPlugin`
+
+```ts
+interface ToolbarPlugin extends ViewerPluginManifest {
+  slot: "toolbar.top" | "toolbar.left" | "toolbar.bottom";
+  order?: number;
+  mount(ctx: ViewerContext): ReactNode;
+}
+```
+
+### `AnnotationSourceProvider`
+
+Non-visual; supplies annotation data to the viewer. The viewer subscribes
+on mount and the provider invokes the callback with the current list and
+on every change.
+
+```ts
+interface AnnotationSourceProvider extends ViewerPluginManifest {
+  slot: "annotation.source";
+  subscribe(
+    ctx: ViewerContext,
+    onChange: (annotations: ReadonlyArray<unknown>) => void,
+  ): () => void;     // returns an unsubscribe
+}
+```
+
+### `DialogPlugin`
+
+```ts
+interface DialogPlugin extends ViewerPluginManifest {
+  slot: "dialog.modal";
+  mount(ctx: ViewerContext): ReactNode;
+}
+```
+
+## Registering a plugin
+
+```tsx
+import { register, type OverlayPlugin } from "@printwithsynergy/lens-pdf/plugin";
+
+const ruler: OverlayPlugin = {
+  id: "demo.overlay.ruler",
+  version: "0.1.0",
+  slot: "overlay.canvas",
+  mount(ctx) {
+    return <RulerOverlay zoom={ctx.zoom} viewport={ctx.viewport} />;
+  },
+};
+
+register(ruler);
+```
+
+`register` throws if an id is already registered or if a `replaces` claim
+collides — both are programmer errors.
+
+`unregister(id)` removes a plugin and frees any `replaces` claim it held.
+`listAll()` returns every registered plugin (including the shadowed ones)
+for inspection / debugging.
+
+`_resetRegistryForTesting()` is exported for tests only — production code
+never calls it.
+
+## Reading plugins back at render-time
+
+The host mounts each slot by calling `getPluginsForSlot(slot)`:
+
+```tsx
+import { Fragment } from "react";
+import {
+  getPluginsForSlot,
+  type ViewerContext,
+} from "@printwithsynergy/lens-pdf/plugin";
+
+function OverlaySlot({ ctx }: { ctx: ViewerContext }) {
+  const plugins = getPluginsForSlot("overlay.canvas");
+  return (
+    <>
+      {plugins.map((p) => (
+        <Fragment key={p.id}>{p.mount(ctx)}</Fragment>
+      ))}
+    </>
+  );
+}
+```
+
+`getPluginsForSlot` returns plugins:
+
+- Sorted by `order` ascending (lowest first); insertion order breaks ties.
+- With anything shadowed by a `replaces` claim filtered out.
+
+## Replacing a first-party plugin
+
+When a plugin pack ships a drop-in alternative, set `replaces` on the
+override:
+
+```ts
+register({
+  id: "thirdparty.panel.findings",
+  version: "0.1.0",
+  slot: "panel.right",
+  replaces: "vendor.panel.findings",  // shadow the original
+  title: "Findings",
+  mount: (ctx) => <ThirdPartyFindings ctx={ctx} />,
+});
+```
+
+Constraints:
+
+- The replacement must declare the same `slot` as the target. Cross-slot
+  overrides are not supported (panels can't replace overlays, etc.).
+- At most one plugin can claim a given `replaces` target — a second
+  registration that targets the same id throws.
+- The target id does not need to be registered yet. The override
+  registers cleanly even before the target loads, and starts shadowing
+  as soon as the target appears.
+
+## Viewer shell plugins (`LensPDF` / `LensPDFDemo`)
+
+The drop-in components also expose a focused shell-plugin API for
+sidebar/menu/tool customization without touching the global plugin
+registry.
+
+Import from `@printwithsynergy/lens-pdf/components`:
+
+```ts
+type LensPDFShellSlot = "panel.left" | "overlay.toolbar";
+
+interface LensPDFShellPlugin {
+  id: string;
+  slot: LensPDFShellSlot;
+  order?: number;
+  replaces?: string;
+  isAvailable?: (ctx: LensPDFShellPluginContext) => boolean;
+  render: (ctx: LensPDFShellPluginContext) => ReactNode;
+}
+```
+
+Pass plugins directly:
+
+```tsx
+<LensPDF
+  pdfUrl="/proofs/abc.pdf"
+  plugins={[
+    {
+      id: "acme.left.custom",
+      slot: "panel.left",
+      order: 15,
+      render: (ctx) => <div>Page {ctx.currentPage}</div>,
+    },
+  ]}
+/>
+```
+
+`replaces` uses the same shadow semantics as the global registry:
+set `replaces: "<builtin-id>"` to override a first-party shell plugin.
+
+## `OverlayItem`
+
+Plugins and host adapters translate their domain types — findings,
+annotations, brand-spec violations — into `OverlayItem`s before handing
+them to a core component. The shape is deliberately minimal:
+
+```ts
+interface OverlayItem {
+  readonly id: string;
+  readonly page: number;                                              // 1-indexed
+  readonly bbox?: readonly [number, number, number, number];          // PDF points
+  readonly tier?: "error" | "warning" | "advisory" | "info" | "neutral";
+  readonly color?: string;                                            // CSS hex, optional override
+  readonly label?: string;
+  readonly description?: string;
+  readonly code?: string;                                             // short identifier code
+  readonly data?: Record<string, unknown>;                            // round-trip payload
+}
+```
+
+`PageCanvas` and `PageNavigator` consume `OverlayItem[]` directly. The
+default tier→colour map is `error` red, `warning` amber, `advisory` blue,
+`info` / `neutral` slate (see `SEVERITY_COLORS` in `/types`); set `color`
+on an item to override per-item.

package/docs/security.md

@@ -0,0 +1,69 @@
+---
+title: "Security policy"
+description: "How to report a vulnerability in LensPDF, what's in scope vs. out of scope, supported versions, and how disclosure is coordinated."
+group: "Project"
+order: 10
+---
+
+# Security policy
+
+LensPDF is the renderer, not the access layer. This page covers what
+counts as a LensPDF vulnerability, how to report one, and what we
+promise back.
+
+## Reporting a vulnerability
+
+If you believe you've found a security issue in LensPDF, please **do
+not** open a public GitHub issue. Instead, email
+**security@printwithsynergy.com** with:
+
+- A clear description of the issue and its impact.
+- Steps to reproduce (a minimal repro repo or code snippet helps).
+- The version / commit you tested against.
+- Any suggested mitigation, if you have one.
+
+We aim to acknowledge reports within **3 business days** and to ship a
+fix or workaround within **30 days** for confirmed issues, depending on
+severity.
+
+You're welcome to request a CVE assignment; we'll coordinate disclosure
+timing with you.
+
+## Scope
+
+LensPDF is a pure renderer. It does not authenticate, sign, or
+rate-limit any URL it consumes — those concerns are the host's. The
+following are **not** in scope as LensPDF vulnerabilities and should
+be reported to the relevant host instead:
+
+- A signed URL that didn't expire when the host expected it to.
+- Unauthorised access to a PDF the host served from an unguarded
+  endpoint.
+- Cross-tenant data leaks at the host's API layer.
+
+In scope:
+
+- Issues in the viewer's rendering or sampling that could leak data the
+  user's session shouldn't see (e.g., a tool returning a value derived
+  from a PDF object the host meant to hide).
+- XSS / injection / prototype-pollution in any code shipped from this
+  repo.
+- Issues in the pdf.js fallback adapter or in any dependency we
+  bundle / re-export.
+- DoS-grade resource exhaustion in the renderer or sampling tools.
+
+For dependency vulnerabilities, please report to the upstream project
+first; we'll bump our version after they ship a fix.
+
+## Supported versions
+
+Until the package reaches `1.0.0`, only the latest minor version line
+receives security fixes. Once `1.0.0` ships, the latest two minor
+version lines are supported.
+
+## Disclosure
+
+We follow [coordinated
+disclosure](https://en.wikipedia.org/wiki/Coordinated_vulnerability_disclosure):
+fixes ship before details are made public, and reporters are credited
+in the release notes unless they request otherwise.

package/docs/server.md

@@ -0,0 +1,212 @@
+---
+title: "Reference server"
+description: "Optional Node + Ghostscript backend that supplies real ink separations, densitometer readings, TAC heatmap, and color sampling. Deploy if you need preflight-grade tools the in-browser fallback can't provide."
+group: "Reference"
+order: 9
+---
+
+# Reference server
+
+The viewer's [`SeparationCanvas`](./components.md#separationcanvas),
+[`DensitometerTool`](./components.md#densitometertool), and
+[`TACHeatmapOverlay`](./components.md#tacheatmapoverlay) all require
+real ink-channel rasters. The pdf.js fallback can't produce those —
+pdf.js renders to RGB, and there's no in-browser path to reconstruct
+CMYK or spot inks from the result. For preflight-grade output you need
+a server-side renderer.
+
+The repo ships a small reference implementation under
+[`server/`](https://github.com/Printwithsynergy/lens-pdf/tree/main/server)
+that you can deploy as-is or read as a contract guide and replace with
+your own. It's a Node + Express service that shells out to Ghostscript
+(`tiffsep` device) for separation rendering. Auth, rate limiting, and
+multi-tenant isolation are deliberately out of scope; run it behind
+your gateway.
+
+## Quick start
+
+```sh
+git clone https://github.com/Printwithsynergy/lens-pdf
+cd lens-pdf/server
+docker build -t lens-pdf-server .
+docker run -p 3000:3000 -v lens-jobs:/var/lib/lens-pdf/jobs lens-pdf-server
+```
+
+`server/README.md` has the full local-development workflow and the
+list of environment variables.
+
+## When you need it
+
+| Component | Reference server | pdf.js fallback | Empty |
+| --- | --- | --- | --- |
+| `PageCanvas` | ✅ | ✅ | hidden |
+| `PageNavigator` | ✅ | ✅ | hidden |
+| `LayerPanel` | wire your own `layers` service | ✅ | hidden |
+| `MeasureTool` | ✅ (page dims via PDF) | ✅ | hidden |
+| `ColorPickerTool` | ✅ (true RGB sample) | ✅ (RGB only) | hidden |
+| `SeparationCanvas` | **✅ only here** | hidden | hidden |
+| `DensitometerTool` | **✅ only here** | hidden | hidden |
+| `TACHeatmapOverlay` | **✅ only here** | hidden | hidden |
+| `AnnotationCanvas` | wire your own `annotations` service | hidden | hidden |
+| Reports | wire your own `reports` service | hidden | hidden |
+
+Mix and match — the host can use the reference server for separations
+and the pdf.js fallback for everything else, or wire its own
+implementations for any subset.
+
+## Wiring example
+
+Pre-register the PDF on the server (do this server-side at upload
+time, not from the browser, so you don't have to expose the source
+URL to the user):
+
+```ts
+await fetch(`${apiBase}/jobs/${jobId}/source`, {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ url: signedPdfUrl }),
+});
+```
+
+Then point the viewer's services at the same base URL:
+
+```ts
+import type { ViewerServices } from "@printwithsynergy/lens-pdf/plugin";
+
+const services: ViewerServices = {
+  pageImages: {
+    getPageImageUrl: ({ pageNum, dpi }) =>
+      `${apiBase}/jobs/${jobId}/page/${pageNum}.png?dpi=${dpi}`,
+  },
+  separations: {
+    getChannelImageUrl: ({ pageNum, channelName, dpi }) =>
+      `${apiBase}/jobs/${jobId}/channel/${encodeURIComponent(channelName)}.png?page=${pageNum}&dpi=${dpi}`,
+  },
+  tacHeatmap: {
+    getHeatmapImageUrl: ({ pageNum, dpi, tacLimit }) =>
+      `${apiBase}/jobs/${jobId}/tac.png?page=${pageNum}&dpi=${dpi}&limit=${tacLimit}`,
+    listRuns: async () => [], // not implemented in the reference server yet
+  },
+  colorSample: {
+    sampleAt: async ({ pageNum, pdfX, pdfY, dpi = 150 }) => {
+      const r = await fetch(
+        `${apiBase}/jobs/${jobId}/color?page=${pageNum}` +
+        `&x=${pdfX}&y=${pdfY}&dpi=${dpi}` +
+        `&pageWidthPts=${pageWidthPts}&pageHeightPts=${pageHeightPts}`,
+      );
+      return r.ok ? await r.json() : null;
+    },
+  },
+  densitometer: {
+    sampleAt: async ({ pageNum, pdfX, pdfY, dpi = 150, tacLimit }) => {
+      const r = await fetch(`${apiBase}/jobs/${jobId}/density`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          page: pageNum,
+          x: pdfX,
+          y: pdfY,
+          pageWidthPts,
+          pageHeightPts,
+          dpi,
+          tacLimit,
+        }),
+      });
+      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();
+    },
+  },
+  // …leave layers / annotations / reports unwired or supply your own.
+} as ViewerServices;
+```
+
+The viewer doesn't care that any of these came from the same backend —
+each `ViewerServices` field is independent and can point anywhere.
+
+## HTTP contract
+
+The reference server is one shape; you can implement any of the
+endpoints differently as long as the responses match. The contract:
+
+| Method | Path | Returns |
+| --- | --- | --- |
+| `POST` | `/jobs/{jobId}/source` | Accept the PDF (raw bytes via `application/pdf`, or `application/json` `{ url }` to fetch). |
+| `GET` | `/jobs/{jobId}/page/{n}.png?dpi=N` | Composite RGB PNG. |
+| `GET` | `/jobs/{jobId}/channels?page=N` | `{ "channels": ["Cyan", "Magenta", ...] }`. |
+| `GET` | `/jobs/{jobId}/channel/{name}.png?page=N&dpi=N` | Grayscale PNG, white = no ink. |
+| `GET` | `/jobs/{jobId}/tac.png?page=N&dpi=N&limit=L` | RGBA PNG, transparent under the limit. |
+| `GET` | `/jobs/{jobId}/color?page=N&x=X&y=Y&pageWidthPts=W&pageHeightPts=H&dpi=N` | `ColorSample` JSON. |
+| `POST` | `/jobs/{jobId}/density` | `DensitometerSample` JSON. Body: `{ page, x, y, pageWidthPts, pageHeightPts, dpi, tacLimit }`. |
+| `DELETE` | `/jobs/{jobId}` | Drop server-side state for the job. |
+
+`ColorSample` and `DensitometerSample` shapes are defined in
+`@printwithsynergy/lens-pdf/types` — match those exactly.
+
+## Security caveats
+
+The viewer is a pure renderer; the reference server is a thin
+Ghostscript wrapper. Authz, rate limiting, multi-tenant isolation, and
+SSRF prevention are **your responsibility**. Specifically:
+
+- The optional `LENS_BEARER_TOKEN` is a coarse single-secret check
+  meant for private-network deploys. For anything user-facing, run the
+  service behind your real gateway.
+- The `{ url: "..." }` upload mode fetches whatever URL you give it.
+  Block internal hostnames at your egress layer or skip the URL flow
+  and upload PDFs directly.
+- Treat every uploaded PDF as hostile. Run the container with
+  `--read-only`, drop capabilities, set ulimits.
+- Ghostscript with `-dSAFER` is the default but historical sandbox
+  bypasses exist; isolate the process accordingly.
+- The 60 s render timeout protects against the most obvious DoS
+  attempts; pair with per-tenant concurrency caps.
+
+See [`server/README.md`](https://github.com/Printwithsynergy/lens-pdf/tree/main/server#security)
+for the full list.
+
+## Cloudflare / CDN deployment
+
+Every per-job GET response is marked **immutable** with a 1-year TTL
+and tagged with `Cache-Tag: job-{jobId}`:
+
+```
+Cache-Control: public, max-age=31536000, immutable, s-maxage=31536000
+Cache-Tag: job-{jobId}
+```
+
+So putting Cloudflare in front of the server gives you free edge
+caching with no extra config — the default Cache Rules will respect
+the headers and store responses at the edge for a year.
+
+Two things to watch:
+
+1. **Don't set `LENS_BEARER_TOKEN`** if you want CDN caching. An
+   `Authorization` header makes Cloudflare bypass the edge cache.
+   Move auth to the gateway tier (Cloudflare Access, signed URLs,
+   mTLS at the origin) instead.
+2. **`DELETE /jobs/{jobId}` should be paired with a Cloudflare
+   purge-by-tag call** from your control plane (tag: `job-{jobId}`).
+   On Cloudflare plans without tag purges, rely on the immutable URL
+   pattern — a new `jobId` produces new URLs that haven't been cached
+   yet.
+
+The reference server's `server/README.md` has the full Cloudflare
+deployment writeup.
+
+## Limitations of this reference
+
+- Per-text-run TAC metadata (the hover-tooltip layer of
+  `TACHeatmapOverlay`) is not implemented — heatmap renders fine, the
+  per-run list is empty.
+- ICC output-intent overrides are not exposed as env vars yet.
+- The in-process cache is in-memory; multi-pod deployments need to
+  swap `cache.ts` for a shared backend (or rely entirely on the
+  Cloudflare edge tier).
+- Layers (OCGs), annotations, reports — wire those to your own
+  services.
+
+If you need any of these, the source is small enough to fork. Pull
+requests welcome.