@printwithsynergy/lens-pdf 0.3.0-beta.81

package/docs/fallback.md

@@ -0,0 +1,174 @@
+---
+title: "Fallback & capability detection"
+description: "Tools self-hide when their backing service is unwired. Hosts can opt into graceful degradation with the in-browser pdf.js fallback adapter for page rendering, layers, and color sampling."
+group: "Reference"
+order: 4
+---
+
+# Fallback behaviour & capability detection
+
+LensPDF's components no longer all render the same regardless of what the
+host wired. Instead each component picks one of three modes per render:
+
+| Mode       | When                                                                                  | Render                                  |
+| ---------- | ------------------------------------------------------------------------------------- | --------------------------------------- |
+| `wired`    | Host supplied a real implementation for the backing service.                          | Normal — use the service.               |
+| `fallback` | Service is unwired **and** `host.pdfFallback` is set.                                 | Use the in-browser fallback adapter.    |
+| `hidden`   | Service is unwired **and** no `pdfFallback` is set (or no fallback exists for it).    | `return null` — the component disappears. |
+
+The distinction matters: a host that wires a real service and gets back an
+empty list still renders an empty state ("This PDF has no optional content
+layers"), because the host explicitly opted in. A host that didn't wire the
+service at all gets nothing — no panel, no menu item, no inert button.
+
+## Capability detection
+
+The default services exported from `@printwithsynergy/lens-pdf/host` are
+tagged with a non-enumerable symbol marker. `isUnwired(service)` returns
+`true` for any of those defaults and `false` for anything a host substitutes
+in. Components use this to choose their render mode.
+
+The full set of unwired defaults is available as a single object:
+
+```ts
+import { defaultUnwiredServices } from "@printwithsynergy/lens-pdf/host";
+```
+
+Spread it and override only the services your host provides — no need
+to manually `markUnwired` each field:
+
+```ts
+import { isUnwired, useViewerServices } from "@printwithsynergy/lens-pdf/host";
+
+const { layers } = useViewerServices();
+if (isUnwired(layers)) {
+  // Host didn't wire the LayerService.
+}
+```
+
+You generally don't need `isUnwired` directly — `useFallbackMode(service)`
+takes the service object and returns the three-state mode for you.
+
+## In-browser fallback (pdf.js)
+
+Hosts that want graceful degradation for the base tools can ship a raw PDF
+URL plus the bundled pdf.js adapter:
+
+```ts
+import { createPdfJsFallback, ViewerHostContext } from "@printwithsynergy/lens-pdf/host";
+
+const fallback = createPdfJsFallback({
+  pdfUrl: "/proofs/abc-signed.pdf",
+  // Optional — only needed if your bundler hasn't already configured
+  // pdf.js's worker.
+  workerSrc: "/pdfjs/pdf.worker.min.mjs",
+});
+
+<ViewerHostContext.Provider
+  value={{
+    apiBase: "",
+    jobApiBase: "",
+    readOnly: true,
+    pdfUrl: "/proofs/abc-signed.pdf",
+    pdfFallback: fallback,
+    debug: import.meta.env.DEV,
+  }}
+>
+  {children}
+</ViewerHostContext.Provider>
+```
+
+Add `pdfjs-dist` to your app's dependencies (it's an *optional* peer dep of
+`@printwithsynergy/lens-pdf` and loaded lazily via `import("pdfjs-dist")`,
+so consumers that don't use the fallback pay no bundle cost).
+
+### What the fallback can do
+
+| Tool / panel       | Wired service       | Falls back?                     |
+| ------------------ | ------------------- | ------------------------------- |
+| `PageCanvas`       | `pageImages`        | ✅ Renders pages with pdf.js.   |
+| `PageNavigator`    | `pageImages`*       | ✅ via `getPageCount()`.         |
+| `MeasureTool`      | (none — needs dims) | ✅ via `getPageDimensions()`.    |
+| `LayerPanel`       | `layers`            | ✅ via `listLayers()`.           |
+| `ColorPickerTool`  | `colorSample`       | ✅ RGB sample only (no TAC).     |
+| `SeparationCanvas` | `separations`       | ❌ pdf.js can't split inks.      |
+| `DensitometerTool` | `densitometer`      | ❌ pdf.js can't split inks.      |
+| `TACHeatmapOverlay`| `tacHeatmap`        | ❌ Needs server-side rendering.  |
+| `AnnotationCanvas` | `annotations`       | ❌ Annotations need persistence. |
+| `AnnotationThread` | `annotations`       | ❌ Same.                         |
+| `MobileDrawer`     | `reports` (links)   | ❌ Report URLs are host-built.   |
+
+\* `PageNavigator` reads page count from the host's page list, but
+`getPageCount()` is exposed on the adapter so hosts that build their own
+glue can bootstrap the page list from the PDF directly.
+
+The three ❌ rows need real ink-channel separations, which only a
+server-side renderer (Ghostscript, MuPDF with separation rendering, etc.)
+can produce. pdf.js renders to RGB; there's no path to reconstruct CMYK
+from the resulting raster. Those components stay hidden when their
+dedicated services are unwired, fallback or no fallback.
+
+For the preflight-grade tools, deploy the optional reference server
+under [`server/`](https://github.com/Printwithsynergy/lens-pdf/tree/main/server)
+or wire `services.separations` / `services.densitometer` /
+`services.tacHeatmap` to your own backend. See
+[server.md](./server.md) for the contract and a wiring example.
+
+### Debug logging
+
+Set `debug: true` on the host context (typically `import.meta.env.DEV` or
+`process.env.NODE_ENV !== "production"`) and every self-hide gets a
+one-shot `console.info`:
+
+```
+[lens-pdf] DensitometerTool hidden — host did not wire `services.densitometer`.
+Provide an implementation, or set `pdfFallback` on the host context to use the
+in-browser PDF fallback.
+```
+
+The log is deduped per-component-name so re-renders don't spam the console.
+With `debug` off (the default) hidden components are silent.
+
+## Security
+
+LensPDF is a pure renderer. It does not authenticate, sign, or rate-limit
+any of the URLs it consumes. Specifically:
+
+- The `pdfUrl` you put on the host context is fetched verbatim by the
+  user's browser. If a downstream user shouldn't be able to read that PDF,
+  the host must enforce that with signed/expiring/scoped URLs **before**
+  handing the URL to the viewer.
+- Service URL builders (`getPageImageUrl`, `getChannelImageUrl`, etc.) are
+  the same — whatever URL the host returns is what the browser fetches.
+- The pdf.js fallback adapter parses the PDF entirely client-side. If the
+  PDF blob contains data the user shouldn't see (other pages, hidden
+  layers, embedded files), they will be able to extract it via DevTools.
+  Strip / redact upstream if that matters.
+- The viewer never stores credentials. If your services need auth, do it
+  at the URL level (signed query strings, cookies the browser already
+  carries, etc.).
+- `readOnly: true` hides write-only UI but is **not** a security boundary —
+  it's a UX convenience. Enforce write-side authz on the server.
+
+## The service contract (for non-JS hosts)
+
+If you're wiring LensPDF from a PHP, Laravel, Perl, Rails, or any other
+backend, your job is just to expose HTTP endpoints that match the shape
+each `ViewerService` URL builder calls. There is no SDK to install — the
+viewer is decoupled by design. The minimal contract is:
+
+| Service           | Endpoint shape (your choice)                                    | Returns                  |
+| ----------------- | --------------------------------------------------------------- | ------------------------ |
+| `pageImages`      | `GET /pdf/{job}/page/{n}.png?dpi=N`                             | PNG bytes                |
+| `layers`          | `GET /pdf/{job}/layers` + `GET /pdf/{job}/layer/{i}.png?dpi=N`  | JSON list + PNGs         |
+| `separations`     | `GET /pdf/{job}/channel/{name}.png?dpi=N`                       | PNG bytes (greyscale)    |
+| `tacHeatmap`      | `GET /pdf/{job}/tac.png?dpi=N&limit=L` + `…/tac.json?...`       | PNG + JSON runs          |
+| `colorSample`     | `GET /pdf/{job}/color?page=N&x=X&y=Y`                           | `ColorSample` JSON       |
+| `densitometer`    | `GET /pdf/{job}/density?page=N&x=X&y=Y&limit=L`                 | `DensitometerSample` JSON |
+| `annotations`     | CRUD on `/pdf/{job}/annotations[/id]`                           | `AnnotationEntry` JSON   |
+| `reports`         | `GET /pdf/{job}/report.html` + `GET /pdf/{job}/report.pdf`      | Static URLs              |
+
+Pick whatever URL scheme fits your framework's routing. The viewer's
+synchronous URL builders just need to produce the right string — they
+don't care what's on the other end as long as it returns the documented
+content-type.

package/docs/lens-pdf-viewer.md

@@ -0,0 +1,128 @@
+---
+title: "LensPDFViewer (one-line viewer)"
+description: "Default high-level composition. One JSX line gets you a working multi-page PDF viewer with auto-discovered pages, layers, zoom, color picker, and measure tool."
+group: "Getting started"
+order: 3
+---
+
+# LensPDFViewer
+
+The default composition. Drop it into any React 19 project and you have
+a working PDF viewer — no host-context wiring, no per-page mounting, no
+worrying about pdf.js workers.
+
+```tsx
+import { LensPDFViewer } from "@printwithsynergy/lens-pdf";
+
+export function MyViewer() {
+  return <LensPDFViewer pdfUrl="https://example.com/file.pdf" />;
+}
+```
+
+## What it does
+
+- Builds a pdf.js fallback adapter from `pdfUrl` and configures the
+  worker URL.
+- Wraps `ViewerHostContext` and (optionally) `ViewerServicesContext`.
+- Auto-discovers page count, page dimensions, and OCG layers from the
+  PDF.
+- Renders every page in a scrollable, lazy-loaded virtual list (or
+  one at a time with `mode="single"`).
+- Seeds initial layer state from the PDF's defaults (default-on
+  layers enabled, default-off off).
+- Ships a responsive default toolbar with zoom, layers, color picker,
+  and measure tool.
+- Reflows to a bottom-drawer layout under 768 px wide.
+
+## Props
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `pdfUrl` | `string` | required | PDF URL fetched by the user's browser. **Sign / scope upstream** — see [Security](#security). |
+| `workerSrc` | `string` | `defaultPdfWorkerSrc` (unpkg, pinned to bundled pdfjs-dist version) | Override to self-host the pdf.js worker. |
+| `services` | `ViewerServices` | _(unset)_ | Pass when your host has a backend with separations / densitometer / TAC / annotations / reports. Components for unwired services hide silently. |
+| `tokens` | `ThemeTokens` | `defaultThemeTokens` | Brand palette. |
+| `className` | `string` | `""` | Class hook on the outer shell. |
+| `mode` | `"scroll"` \| `"single"` | `"scroll"` | Page rendering mode. |
+| `tools` | `ReadonlyArray<"zoom"\|"layers"\|"color-picker"\|"measure">` | all four | Toolbar contents. Pass `[]` for no toolbar. |
+| `initialZoom` | `number` | `100` | Starting zoom percent. |
+| `brand` | `string` | _(none)_ | Optional brand label rendered in the top-left of the toolbar. |
+| `header` | `(state: LensPDFViewerState) => ReactNode` | _(built-in toolbar)_ | Replace the default toolbar. Receives viewer state. |
+| `sidebar` | `(state: LensPDFViewerState) => ReactNode` | _(none)_ | Inject a sidebar next to the page list. |
+| `footer` | `ReactNode` | _(none)_ | Static footer content rendered below the viewer stage. |
+
+## What gets hidden when no services are wired
+
+The composition relies on the host-agnostic capability-detection
+contract from [fallback.md](./fallback.md). With only `pdfUrl` set:
+
+| Component | Visible | Notes |
+| --- | --- | --- |
+| Page rendering, navigation, zoom | ✅ | pdf.js fallback. |
+| Layer panel | ✅ if PDF has OCGs | pdf.js fallback. |
+| Color picker | ✅ | RGB only (no TAC). |
+| Measure tool | ✅ | Page dimensions from PDF. |
+| Separations | ❌ hidden | Needs a backend; pdf.js renders RGB only. |
+| Densitometer | ❌ hidden | Same. |
+| TAC heatmap | ❌ hidden | Same. |
+| Annotations | ❌ hidden | Needs persistence. |
+| Report links | ❌ hidden | Needs a backend. |
+
+Pass `services` to wire the backend-dependent ones. The reference
+server in [`server/`](https://github.com/Printwithsynergy/lens-pdf/tree/main/server)
+is a turnkey option — see [server.md](./server.md).
+
+## Slot props
+
+Slot props let you replace individual regions without reimplementing the
+entire viewer. Each slot accepts a static `ReactNode` or a render
+function that receives the current `LensPDFViewerState`:
+
+```tsx
+import { LensPDFViewer } from "@printwithsynergy/lens-pdf/components";
+
+<LensPDFViewer
+  pdfUrl={url}
+  header={(state) => (
+    <div>
+      <span>Page {state.currentPage}</span>
+      <button onClick={() => state.setZoom(state.zoom + 25)}>Zoom in</button>
+    </div>
+  )}
+  footer={<p>Powered by LensPDF</p>}
+/>
+```
+
+`LensPDFViewerState` exposes: `zoom`, `setZoom`, `currentPage`,
+`setCurrentPage`, `pageCount`, `activeTool`, `setActiveTool`,
+`enabledLayers`, `toggleLayer`, `setAllLayers`, `hasLayers`,
+`layersOpen`, `setLayersOpen`.
+
+## Custom layouts
+
+`<LensPDFViewer>` is purely additive. The lower-level surface stays
+exactly as before — for bespoke layouts compose `PageCanvas`,
+`LayerPanel`, `MeasureTool`, `ColorPickerTool`, etc. with your own
+context providers. See [components.md](./components.md) for the per-
+component reference.
+
+## Other integration tiers
+
+- **Less boilerplate** — [`<LensPDFDemo>`](./components.md#drop-in-demo)
+  bakes in upload, URL paste, drag-drop, and validation. ~5 lines.
+- **More control** — [`useLensPDF()`](./share-links.md) +
+  `<LensPDFProvider>` manage state while you build the layout.
+- **Full custom** — wire `ViewerHostContext` + `ViewerServicesContext`
+  yourself. See [architecture.md](./architecture.md).
+
+## Security
+
+The `pdfUrl` you pass is fetched verbatim by the user's browser. If a
+user shouldn't be able to read that PDF, the host must enforce that
+upstream — sign the URL, scope it, expire it. The viewer is a pure
+renderer and doesn't authenticate anything.
+
+The pdf.js worker is loaded from unpkg by default. For deployments
+that can't reach unpkg (intranet, air-gapped CI, strict CSPs), set
+`workerSrc` to a self-hosted URL or import the worker into your app's
+build and pass its bundler-resolved URL.

package/docs/licensing.md

@@ -0,0 +1,78 @@
+---
+title: "Licensing"
+description: "AGPL-3.0-or-later licensing terms for LensPDF — what hosts can do, what they must do, and how to request alternative terms for proprietary use."
+group: "Project"
+order: 11
+---
+
+# Licensing
+
+LensPDF is published under **AGPL-3.0-or-later** — the GNU Affero
+General Public License, version 3 or any later version. The full
+licence text lives in [`LICENSE`](https://github.com/Printwithsynergy/lens-pdf/blob/main/LICENSE)
+at the root of the repository, and `package.json` declares the same
+SPDX identifier so npm tooling picks it up automatically.
+
+## What you can do
+
+- Use LensPDF in any application, commercial or non-commercial.
+- Modify the source — fork it, vendor it, patch it for your build.
+- Redistribute it, modified or unmodified, on any platform.
+- Combine it with other AGPL-compatible code.
+
+## What you must do
+
+If you distribute LensPDF (binary or source) — or **make it available
+over a network** — you have to:
+
+- Make the **complete corresponding source code** of your modified
+  version available, under AGPL-3.0-or-later, to every recipient and
+  every user interacting with it remotely.
+- Preserve the copyright and licence notices from this repository.
+- State the changes you made, with dates.
+- License any larger work that links against LensPDF under
+  AGPL-3.0-or-later.
+
+The "**make available over a network**" clause (§13 of AGPL-3) is the
+key difference from GPLv3: a SaaS that ships LensPDF — even if no one
+ever downloads a binary — has to offer the source to its users. Hosting
+a hosted PDF viewer that imports `@printwithsynergy/lens-pdf` triggers
+this.
+
+## Third-party code
+
+LensPDF re-exports and bundles open-source dependencies:
+
+- **pdf.js** (Apache-2.0) — fallback rendering adapter.
+- **fabric.js** (MIT) — annotation canvas (optional peer).
+- **React** (MIT) — peer.
+
+Their licences are compatible with AGPL-3.0-or-later. When you ship
+LensPDF you also ship those dependencies, so check their notices in
+`node_modules` and reproduce them if your distribution channel
+requires it.
+
+## Alternative / commercial licensing
+
+The AGPL-3.0 reciprocity requirement is incompatible with some
+proprietary or closed-source products. If you want to embed LensPDF
+in a product you can't or don't want to release under AGPL-3.0,
+contact **licensing@printwithsynergy.com** to discuss commercial
+terms.
+
+## Why AGPL?
+
+LensPDF is the rendering core for the printwithsynergy OSS PDF
+tooling family. Releasing it under AGPL keeps the core honest:
+improvements anyone makes — even hidden behind a SaaS — flow back to
+the community. Hosts that want a non-reciprocal arrangement can buy
+into the commercial track above; everyone else gets the same code on
+the same terms.
+
+## Contributor licensing
+
+Contributions are accepted under the same AGPL-3.0-or-later terms by
+default. By submitting a PR you agree your changes are licensed that
+way, and that you have the right to submit them. See
+[Contributing](/docs/contributing) for the boundary rules and PR
+style.

package/docs/measurement-units.md

@@ -0,0 +1,87 @@
+---
+title: "Measurement units"
+description: "Built-in millimetre, inch, point, pica, and agate definitions, plus the MeasurementUnit protocol for adding custom units to the MeasureTool."
+group: "Reference"
+order: 7
+---
+
+# Measurement units
+
+`MeasureTool` accepts a `units` prop. The five built-ins cover most print
+workflows; pass any subset, or write your own conforming to the
+`MeasurementUnit` Protocol.
+
+## Built-ins
+
+```ts
+import {
+  mmUnit,
+  inchUnit,
+  pointUnit,
+  picaUnit,
+  agateUnit,
+  defaultMeasurementUnits,   // [mm, in, pt]
+  allMeasurementUnits,       // [mm, in, pt, pica, agate]
+} from "@printwithsynergy/lens-pdf/units";
+```
+
+| Unit | id | label | Conversion (from PDF points) |
+| --- | --- | --- | --- |
+| Millimetre | `mm` | `mm` | `pt × 25.4 / 72` |
+| Inch | `in` | `in` | `pt / 72` |
+| Point | `pt` | `pt` | identity (PDF native) |
+| Pica | `pica` | `pc` | `pt / 12` |
+| Agate | `agate` | `ag` | `pt / 5.5` |
+
+`MeasureTool` defaults to `defaultMeasurementUnits` (mm, in, pt). Pass
+`allMeasurementUnits` to add pica + agate, or supply a custom subset.
+
+```tsx
+import { MeasureTool } from "@printwithsynergy/lens-pdf/components";
+import { allMeasurementUnits } from "@printwithsynergy/lens-pdf/units";
+
+<MeasureTool
+  pageWidthPts={612}
+  pageHeightPts={792}
+  canvasWidth={800}
+  canvasHeight={1036}
+  units={allMeasurementUnits}
+/>;
+```
+
+## Custom units
+
+The Protocol is small — anchor your conversions to PDF points (1 pt =
+1/72 inch) and you're done.
+
+```ts
+import type { MeasurementUnit } from "@printwithsynergy/lens-pdf/plugin";
+
+export const cmUnit: MeasurementUnit = {
+  id: "cm",
+  label: "cm",
+  fromPoints: (pts) => (pts * 25.4) / 72 / 10,
+  toPoints: (cm) => (cm * 10 * 72) / 25.4,
+};
+
+export const emUnit: MeasurementUnit = {
+  id: "em",
+  label: "em",
+  // 1em = 12pt by typographic convention; adjust if you have a real
+  // type-size in scope.
+  fromPoints: (pts) => pts / 12,
+  toPoints: (em) => em * 12,
+};
+```
+
+Pass them to `MeasureTool` directly, or merge with the built-ins:
+
+```tsx
+<MeasureTool
+  units={[mmUnit, cmUnit, inchUnit, pointUnit]}
+  /* … */
+/>;
+```
+
+The `id` is used for keying / preference storage; keep it stable across
+versions if you persist user choice.