@signiphi/pdf-signer 0.2.0-beta.3 → 0.2.0-beta.31

package/README.md

@@ -7,6 +7,7 @@ Flexible React components for PDF viewing, form filling, and signature capture.
 - 📄 **PDF Viewing** - Render PDFs with PDF.js viewer
 - ✍️ **Signature Capture** - Draw or upload signatures
 - 📝 **Form Filling** - Fill PDF form fields
+- 💬 **Annotation Chat** - Threaded highlights, ink, and free-text with sender/receiver review round-trips
 - 🎨 **Flexible Styling** - Use headless components or pre-styled components
 - 📱 **Responsive** - Works on desktop and mobile devices
 - 🔧 **TypeScript** - Fully typed API
@@ -1138,6 +1139,289 @@ For implementation details, troubleshooting, and advanced topics, see:
 
 ---
 
+## Annotation Chat & Review Round-Trips
+
+`SubmissionForm` can host an interactive annotation panel on top of the PDF
+viewer. Receivers can highlight, free-draw, drop free-text notes, and reply
+to threads; senders can review submissions, reply, add their own
+annotations, and volley the document back. The flow is opt-in and the
+state is the consumer's responsibility — the form emits change events,
+the host app persists.
+
+### Two roles, one component
+
+The same `SubmissionForm` renders for both sides of a review round-trip.
+The role is gated by the **`role`** prop (route-driven, NOT identity-driven):
+
+| `role`       | Sign tab? | Can annotate? | Submit-for-Review? |
+|--------------|-----------|---------------|--------------------|
+| `'signer'`   | yes       | yes           | yes (volley back)  |
+| `'reviewer'` | no        | yes           | yes (volley back)  |
+
+Set `role` per-route in your host app — e.g. the receiver's signing
+URL renders with `role="signer"`, the sender's review URL renders with
+`role="reviewer"`. Don't drive it from `currentAuthor.name`; that would
+couple the role to a display string.
+
+> **Note:** the deprecated `reviewMode` boolean is still accepted —
+> `reviewMode={true}` maps to `role="reviewer"`. Prefer `role` in new
+> code; `reviewMode` will be removed in a future major.
+
+### The `pdfUrl` / `pdfUrlForSigning` contract
+
+Annotations are baked into the PDF on submit (`Submit for Review`). The
+receiver's *signing* operation must run against a clean copy — otherwise
+the signed PDF carries the review marks burned into page content.
+
+- `pdfUrl` — what the user sees in the viewer.
+- `pdfUrlForSigning` — the original/prepared PDF the final fill runs against.
+
+When `enableAnnotationChat` or `reviewMode` is true, **always pass both**.
+
+**Strict contract (signing after review):** when the document actually
+carries review annotations, signing it requires a clean `pdfUrlForSigning`
+that is **distinct** from `pdfUrl`. If `pdfUrlForSigning` is
+missing/empty/whitespace-only, or points at the same file as `pdfUrl` —
+including trivial variations like a cache-buster query (`file.pdf?v=2`), a
+trailing slash, or host casing — `handleSubmit` **throws a
+`ReviewAnnotationSigningError` at submit time** — before any fill runs — so
+the signed copy can never silently embed the review marks. Correctly
+configured signing (a distinct, un-baked `pdfUrlForSigning`) bakes the
+signer's form-field signatures only; review annotations are never written
+into the signed deliverable. (Separately, a softer render-time warning still
+logs — and throws in development — whenever annotation features are enabled
+without `pdfUrlForSigning`, to catch the misconfiguration early.)
+
+URL comparison is best-effort: it cannot detect two *different* URLs (e.g. a
+CDN alias on another host) that serve the same baked file. The durable
+guarantee is content-based — before filling, the actual signing bytes are
+scanned for baked review markup and signing is refused if any is found
+(`assertSigningBytesFreeOfReviewMarkup`), independent of how the URLs were
+wired.
+
+The guard is also exported standalone for custom submit flows:
+
+```ts
+import { assertSigningSourceIsClean } from '@signiphi/pdf-signer/utils';
+
+assertSigningSourceIsClean({
+  hasReviewAnnotations, // true if the doc went through review
+  pdfUrl,
+  pdfUrlForSigning,
+}); // throws ReviewAnnotationSigningError on misconfiguration
+```
+
+### Round-trip example
+
+```tsx
+import {
+  SubmissionForm,
+  type AnnotationThread,
+  type AnnotationChatConfig,
+} from '@signiphi/pdf-signer';
+
+function ReceiverSigningPage({ document, currentUser, savedAnnotations }) {
+  const [annotations, setAnnotations] = useState<AnnotationThread[]>(
+    savedAnnotations ?? []
+  );
+
+  const annotationChatConfig: AnnotationChatConfig = {
+    currentAuthor: {
+      id: currentUser.id,
+      name: currentUser.name,
+      email: currentUser.email,
+    },
+    initialAnnotations: annotations,
+    onAnnotationsChange: setAnnotations,
+    enabledTools: ['highlight', 'freehand_highlight', 'ink', 'freetext'],
+    enableReplies: true,
+    enableResolve: true,
+  };
+
+  return (
+    <SubmissionForm
+      pdfUrl={document.bakedReviewPdfUrl ?? document.preparedPdfUrl}
+      pdfUrlForSigning={document.preparedPdfUrl}        // clean source
+      enableAnnotationChat
+      annotationChatConfig={annotationChatConfig}
+      role="signer"                                      // receiver = signer
+      onRequestReview={async (data) => {
+        await api.submitForReview(document.id, data);
+      }}
+      onSubmit={async (data) => {
+        await api.submitSigned(document.id, data);
+      }}
+      // ...other props
+    />
+  );
+}
+
+function SenderReviewPage({ document, currentUser, latestAnnotations }) {
+  const [annotations, setAnnotations] = useState<AnnotationThread[]>(
+    latestAnnotations
+  );
+
+  return (
+    <SubmissionForm
+      pdfUrl={document.bakedReviewPdfUrl}
+      pdfUrlForSigning={document.preparedPdfUrl}
+      enableAnnotationChat
+      role="reviewer"                                    // sender = reviewer
+      annotationChatConfig={{
+        currentAuthor: { id: currentUser.id, name: currentUser.name, email: currentUser.email },
+        initialAnnotations: annotations,
+        onAnnotationsChange: setAnnotations,
+        enabledTools: ['highlight', 'ink', 'freetext'],
+        enableReplies: true,
+      }}
+      requestReviewButtonLabel="Send back to receiver"
+      onRequestReview={async (data) => {
+        await api.respondToReview(document.id, data);
+      }}
+      onSubmit={async () => {}}                          // unused in reviewMode
+    />
+  );
+}
+```
+
+### `initialAnnotations` shape
+
+`AnnotationChatConfig.initialAnnotations` accepts `AnnotationThread[]`.
+Round-trip the same shape via `onAnnotationsChange`:
+
+```ts
+type AnnotationThread = {
+  annotation: Annotation;       // primary annotation (highlight, ink, etc.)
+  replies: AnnotationReply[];   // chat replies, threaded via PDF /IRT entries
+};
+```
+
+Each `Annotation` carries a `pdfJsSerializedData` blob — populated by the
+bridge when the editor is created/modified. **Persist that blob with the
+annotation.** It contains the PDF user-space rect/inkList/quadPoints used
+when baking. If you store annotations through a non-PDF.js path (e.g.
+imported JSON without serialized data) `embedAnnotationsInPdf` will skip
+those threads on save — see "Surfacing dropped annotations" below.
+
+### Surfacing dropped annotations
+
+When the host calls `embedAnnotationsInPdf` directly (e.g. to render a
+final reviewable PDF), threads missing PDF user-space data are returned
+in the `skipped` array:
+
+```ts
+import { embedAnnotationsInPdf } from '@signiphi/pdf-signer';
+
+const { pdfBytes, skipped } = await embedAnnotationsInPdf(rawPdfBytes, threads, {
+  // Either inspect skipped after the fact:
+  onSkipped: (s) => toast.warn(`Dropped ${s.length} annotation(s)`),
+  // ...or hard-fail:
+  // throwOnSkip: true,
+});
+```
+
+Pre-flight check: every annotation that should be persisted must carry
+`annotation.pdfJsSerializedData` by the time the user clicks submit.
+
+### Stamp (image) tool
+
+The `'stamp'` tool opens a native file picker. Uploads are validated
+client-side before they reach PDF.js: only `image/*` MIME types are
+accepted, and files larger than **10 MB** are rejected. Oversized or
+non-image selections are dropped silently with a console warning — the
+consumer doesn't need to gate the picker.
+
+### Composable building blocks (greenfield consumers)
+
+`<SubmissionForm>` is a back-compat preset bundling viewer + signing +
+annotations. New consumers who want their own UI can compose smaller
+primitives instead:
+
+| Component / hook       | Purpose                                                              |
+|------------------------|----------------------------------------------------------------------|
+| `<PdfJsProvider>`      | Supplies PDF.js config (worker / viewer paths) to the subtree.       |
+| `<PdfDocument>`        | Renders the viewer and exposes its ref + load state via context.     |
+| `<AnnotationLayer>`    | Opt-in annotation chat; render-prop API on top of `useAnnotationChat`.|
+| `usePdfDocument()`     | Read the surrounding `<PdfDocument>` context (viewer ref, URLs).     |
+| `usePdfJsConfig()`     | Read the active PDF.js config from a provider or the global default. |
+
+```tsx
+import {
+  PdfJsProvider,
+  PdfDocument,
+  AnnotationLayer,
+  AnnotationChatPanel,
+} from '@signiphi/pdf-signer';
+
+function MyReviewer({ pdfUrl, originalUrl, currentAuthor, savedAnnotations }) {
+  return (
+    <PdfJsProvider config={{ viewerBasePath: '/static/pdfjs' }}>
+      <PdfDocument pdfUrl={pdfUrl} pdfUrlForSigning={originalUrl} enableAnnotationEditor>
+        <AnnotationLayer
+          role="reviewer"
+          config={{
+            currentAuthor,
+            initialAnnotations: savedAnnotations,
+            onAnnotationsChange: (anns) => persist(anns),
+          }}
+        >
+          {(api) => (
+            <AnnotationChatPanel
+              annotations={api.annotations}
+              activeAnnotationId={api.activeAnnotationId}
+              onAddReply={api.addReply}
+              onResolveThread={api.resolveThread}
+              onUnresolveThread={api.unresolveThread}
+              onSelectAnnotation={api.setActiveAnnotation}
+              onDeleteAnnotation={api.removeAnnotation}
+              currentAuthor={currentAuthor}
+              enabledTools={['highlight', 'ink', 'freetext']}
+              enableReplies
+              enableResolve
+            />
+          )}
+        </AnnotationLayer>
+      </PdfDocument>
+    </PdfJsProvider>
+  );
+}
+```
+
+For the all-in-one experience (signing + annotations + multi-signer +
+attachments), continue to use `<SubmissionForm>` — it's the supported
+preset for the full review/signing flow.
+
+---
+
+### Headless usage (advanced)
+
+`useAnnotationChat`, `AnnotationBridge`, and `embedAnnotationsInPdf` are
+exported as building blocks, but the hook layer ships with one tight
+coupling that consumers must respect:
+
+**Iframe contract.** `useAnnotationChat` drives an `AnnotationBridge`
+that reaches into a PDF.js viewer iframe to deserialize/inject editors.
+The discovery routine looks for an `<iframe title="PDF Viewer">` in the
+DOM and a `viewerRef` whose `current.getPDFViewerApplication()` returns
+the same `PDFViewerApplication` instance running inside that iframe. If
+you frame your own viewer (custom shell, embedded `<embed>`, etc.) the
+hook will not find the iframe and the bridge will silently noop.
+
+If your custom UI cannot satisfy that contract, the supported path is to
+keep `<SubmissionForm>` (or `<PdfViewerStyled>`) at the framing layer and
+build your own panel UI on top — they expose `viewerRef` and the
+underlying `pdfViewerApplication` for that purpose. Truly headless
+support (custom iframe sources, explicit `iframeRef` prop) is on the
+roadmap; until then treat `useAnnotationChat` as an implementation detail
+of the framed components.
+
+The other building blocks are framework-agnostic:
+- `embedAnnotationsInPdf(bytes, threads, options?)` — pure function.
+- `AnnotationBridge` — accepts an `iframeRef` directly; safe to drive
+  from any UI as long as the iframe runs the bundled PDF.js viewer.
+
+---
+
 ## Multi-Signer Support
 
 The package supports multi-signer workflows where multiple people sign the same document in sequence. Each signer only sees and fills their assigned fields.