pdfcedar 0.1.0-beta.0 → 0.1.1-beta.0

package/README.md

@@ -1,223 +1,238 @@
-# PDFCedar
-
-An embeddable PDF viewer for web apps. View, search, annotate, rearrange pages and save standard PDFs, in
-React, Vue, Angular or plain HTML. One function, no framework lock-in.
-
-> **Free to try, licensed for production.** Every feature works without a key, with a "PDFCedar trial" watermark.
-> Live demo, docs and pricing: [pdfcedar.brimij.com](https://pdfcedar.brimij.com). Terms: [LICENSE](./LICENSE).
-
-## Install
-
-```sh
-npm install pdfcedar
-npx pdfcedar-assets public/pdfcedar
-```
-
-The second command copies the PDF engine (a web worker plus font and character-map files, about 4.5 MB) into a
-folder your app serves. Bundlers copy JavaScript, not these files, so they need this one step. Add it to your
-`postinstall` script so upgrades stay in sync:
-
-```json
-"scripts": { "postinstall": "pdfcedar-assets public/pdfcedar" }
-```
-
-## Quick start
-
-```html
-<div id="viewer" style="height: 100vh"></div>
-```
-
-```js
-import { createViewer } from 'pdfcedar';
-
-const viewer = await createViewer({
-  container: document.getElementById('viewer'),
-  document: '/files/contract.pdf', // or a File, Blob or ArrayBuffer
-  assetBaseUrl: '/pdfcedar/', // where pdfcedar-assets copied the engine files
-  user: { id: 'u1', name: 'Asha' }, // author name on annotations
-});
-
-viewer.on('annotationAdded', ({ annotation }) => console.log('added', annotation));
-const bytes = await viewer.save(); // a standard PDF with all annotations and page changes
-```
-
-The container needs a height; the viewer fills it.
-
-### Without a bundler
-
-```html
-<script src="https://your-cdn/pdfcedar/dist/index.umd.cjs"></script>
-<script>
-  PDFCedar.createViewer({ container: document.getElementById('viewer'), document: 'file.pdf' });
-</script>
-```
-
-The UMD build finds `dist/pdfjs/` next to itself, so `assetBaseUrl` isn't needed when you serve the whole `dist` folder.
-
-### Frameworks
-
-| | Mount in | Destroy in |
-|---|---|---|
-| React | `useEffect` | the effect's cleanup |
-| Vue | `onMounted` | `onBeforeUnmount` |
-| Angular | `ngAfterViewInit` | `ngOnDestroy` |
-
-Complete, runnable examples are in the repository's `examples/` folder. Always call `viewer.destroy()` when the
-component goes away; it frees the worker, canvases and listeners.
-
-## Options
-
-| Option | Type | |
-|---|---|---|
-| `container` | `HTMLElement` | Required. The viewer fills it. |
-| `document` | `string \| File \| Blob \| ArrayBuffer` | Required. A URL (fetched with range requests) or the file itself. |
-| `licenseKey` | `string` | Your licence key (see below). Without a valid one the viewer runs in trial mode. |
-| `assetBaseUrl` | `string` | URL of the folder holding the engine files. |
-| `theme` | `'light' \| 'dark' \| ThemeObject` | A `ThemeObject` maps `--pl-*` CSS variables to values. |
-| `toolbar` | `ToolName[]` | Which tools to show. Omit for all. |
-| `readOnly` | `boolean` | Viewing, search and print only. |
-| `user` | `{ id, name }` | Author of new annotations and replies. |
-| `collaboration` | `{ serverUrl, roomId }` | Real-time sharing with everyone in the room (see below). |
-| `signatureStore` | `{ load(), save(list) }` | Where the user's saved signatures persist (e.g. your backend). Without it they last for the page session. |
-
-`ToolName` is any of `'zoom'`, `'search'`, `'download'`, `'print'`, `'pages'`, `'select'`, `'highlight'`, `'underline'`,
-`'strikeout'`, `'note'`, `'ink'`, `'rectangle'`, `'ellipse'`, `'line'`, `'arrow'`, `'freeText'`, `'signature'`, `'redaction'`.
-
-## API
-
-```ts
-// Events: documentLoaded, pageChanged, annotationAdded, annotationChanged, annotationRemoved,
-//         formFieldChanged, signatureAdded, saved. Payloads are typed (see ViewerEvents).
-viewer.on(event, handler); viewer.off(event, handler);
-
-// Navigation
-viewer.goToPage(3); viewer.setZoom(1.5); viewer.fit('width'); // or 'page'
-const hits = await viewer.search('total');                   // highlights every match
-
-// Annotations (coordinates in PDF points, origin bottom-left)
-const note = viewer.annotations.add({ type: 'note', page: 1, rect: { x: 72, y: 700, width: 24, height: 24 }, contents: 'Check this' });
-viewer.annotations.update(note.id, { color: '#2563eb' });
-viewer.annotations.remove(note.id);
-viewer.annotations.list();                       // or list({ page: 1, type: 'highlight' })
-const json = viewer.annotations.export();        // save to your backend…
-viewer.annotations.import(json);                 // …and restore later
-viewer.undo(); viewer.redo();
-
-// Pages (1-based)
-viewer.pages.rotate(1, 90); viewer.pages.delete(2); viewer.pages.move(3, 1);
-await viewer.pages.merge(file);
-
-// Forms: the file's own fields are drawn as fillable controls
-viewer.forms.getValues();                        // { fullName: '', subscribe: false, plan: 'pro', interests: ['A'] }
-viewer.forms.setValues({ fullName: 'Asha Rao', subscribe: true }); // one undo step; FormValueError if invalid
-viewer.forms.flatten();                          // on save, fields become part of the page
-
-// Signatures: the Signature tool lets users draw, type or upload one; from code:
-const signature = await viewer.signatures.add({
-  page: 1,
-  rect: { x: 360, y: 90, width: 150, height: 50 },
-  image: blobOrDataUrlOrUrl, // PNG, JPEG, WebP, SVG…
-});
-// Movable, resizable and undoable until saved; saving draws it into the page.
-
-// Redaction: mark areas (the Redact tool marks selected text or a dragged box), then apply
-viewer.redaction.mark({ page: 1, rect: { x: 72, y: 640, width: 180, height: 14 } });
-await viewer.redaction.apply(); // final: marks turn black, undo history is cleared
-const redacted = await viewer.save(); // the content under the marks is removed from the file
-
-// Output
-const bytes = await viewer.save();               // Uint8Array
-await viewer.download('reviewed.pdf');
-await viewer.print();
-viewer.destroy();
-```
-
-Annotation types: `highlight`, `underline`, `strikeout`, `note`, `reply`, `ink`, `rectangle`, `ellipse`, `line`,
-`arrow`, `freeText`, `signature`. Saved files use standard PDF annotations with appearance streams, so Acrobat Reader, Chrome,
-Firefox and Safari show them and can edit them. Signatures are the exception: saving draws them into the page, so they
-can no longer be moved or removed in any viewer.
-
-## Redaction
-
-Applied redactions remove content from the saved file, not just cover it:
-
-- **Text:** removed glyph by glyph. The rest of the line keeps its position.
-- **Images, including scans:** the pixels under the mark are blacked out in the image itself.
-- **Shapes:** vector shapes entirely inside a mark are removed.
-- **Annotations and form fields:** any that overlap a mark are deleted.
-- **Hidden copies:** `/ActualText` that repeats removed text is stripped, and no copy of the original content stays in the file.
-
-Unapplied marks are saved as standard `/Redact` annotations, which Acrobat can apply.
-
-## Theming
-
-```css
-.pdfcedar-viewer {
-  --pl-accent: #7c3aed;
-  --pl-bg: #f4f4f5;
-  --pl-surface: #ffffff;
-  --pl-text: #18181b;
-  --pl-font: 'Inter', system-ui, sans-serif;
-}
-```
-
-## Collaboration
-
-```js
-createViewer({
-  container,
-  document: '/files/contract.pdf',
-  user: { id: 'u1', name: 'Asha Rao' },
-  collaboration: { serverUrl: 'wss://collab.example.com', roomId: 'contract-123' },
-});
-```
-
-- **What's shared:** everyone in the room sees each other's annotations, replies, signatures, redaction marks and form
-  values within a second, and the toolbar shows who's online.
-- **Events and undo:** changes from others fire the usual events with `source: 'remote'`, and never enter your undo
-  history.
-- **Offline:** edits made offline sync when the connection is back.
-- **Not shared:** page changes (rotate, delete, reorder) stay per person, so everyone in a room should have the same
-  pages.
-- **Server:** run your own. The repository's `apps/collab-server` is a small ready-made one (`node src/server.mjs`);
-  any y-websocket-compatible server works too. Documents never pass through PDFCedar's servers.
-- **Size:** the collaboration code loads only when this option is set.
-
-## Licence key
-
-```js
-createViewer({ container, document, licenseKey: 'PL1.eyJ2Ijox…' });
-```
-
-- **Offline check:** the key is checked in the browser, with no network call. It's a signed list of the domains
-  you bought it for, so nothing about your users or documents leaves the page.
-- **Domains:** `example.com` covers only that host; `*.example.com` covers its subdomains. Any valid key also works
-  on `localhost` and `127.0.0.1`, for development.
-- **Trial mode:** without a valid key (missing, mistyped, expired, or on another domain) everything still works,
-  but the pages carry a "PDFCedar trial" watermark and a Trial badge. Saved, downloaded and printed files are
-  watermarked too. The console says why, as does the
-  viewer element's `data-license-reason` attribute.
-
-## Phones and tablets
-
-- **Pinch** zooms around your fingers; on desktop, Ctrl/⌘ + wheel and trackpad pinches do the same.
-- **Drawing:** one finger draws with the drawing tools. A second finger turns a stroke into a pinch, so no stray line is left.
-- **Select tool:** touching a selected annotation drags it; elsewhere, one finger scrolls. Handles are larger on touch screens.
-- **Narrow viewers** (under 640 px wide, by the viewer's own width) get a compact toolbar:
-  - **Annotate** shows the tools in a row that scrolls sideways.
-  - **More** holds Search, Download and Print.
-  - The sidebar is a drawer that starts closed.
-
-Give your page `<meta name="viewport" content="width=device-width, initial-scale=1">`, as every mobile page needs.
-
-## Browser support
-
-Chrome and Edge 119+, Firefox 121+, Safari 17.4+ (desktop and iOS), Chrome on Android.
-
-## Errors
-
-- `createViewer` rejects if the file can't be opened (bad URL, not a PDF).
-- `annotations.add` / `update` / `import` throw `AnnotationValidationError` (with a `path` such as `rect.width`) for invalid input.
-- `forms.setValues` throws `FormValueError` (with the `field` name) for an unknown field or a value it can't hold; nothing changes.
-- `annotations.update` / `remove` throw `AnnotationValidationError` for an applied redaction (applying is final).
-- `save` / `download` throw `EncryptedDocumentError` for password-protected PDFs.
+# PDFCedar
+
+An embeddable PDF viewer for web apps. View, search, annotate, rearrange pages and save standard PDFs, in
+React, Vue, Angular or plain HTML. One function, no framework lock-in.
+
+> **Free to try, licensed for production.** Every feature works without a key, with a "PDFCedar trial" watermark.
+> Live demo, docs and pricing: [pdfcedar.brimij.com](https://pdfcedar.brimij.com). Terms: [LICENSE](./LICENSE).
+
+## Install
+
+```sh
+npm install pdfcedar
+npx pdfcedar-assets public/pdfcedar
+```
+
+The second command copies the PDF engine (a web worker plus font and character-map files, about 4.5 MB) into a
+folder your app serves. Bundlers copy JavaScript, not these files, so they need this one step. Add it to your
+`postinstall` script so upgrades stay in sync:
+
+```json
+"scripts": { "postinstall": "pdfcedar-assets public/pdfcedar" }
+```
+
+## Quick start
+
+```html
+<div id="viewer" style="height: 100vh"></div>
+```
+
+```js
+import { createViewer } from 'pdfcedar';
+
+const viewer = await createViewer({
+  container: document.getElementById('viewer'),
+  document: '/files/contract.pdf', // or a File, Blob or ArrayBuffer
+  assetBaseUrl: '/pdfcedar/', // where pdfcedar-assets copied the engine files
+  user: { id: 'u1', name: 'Asha' }, // author name on annotations
+});
+
+viewer.on('annotationAdded', ({ annotation }) => console.log('added', annotation));
+const bytes = await viewer.save(); // a standard PDF with all annotations and page changes
+```
+
+The container needs a height; the viewer fills it. (Without one, the viewer falls back to `80vh` and warns in the
+console: otherwise it would grow to the whole document's length and draw every page.)
+
+**Server-side rendering** (Next.js, Nuxt, Angular SSR): importing `pdfcedar` on the server is safe and does nothing;
+the PDF engine loads only when `createViewer` runs in the browser. Call it from client-only code (`useEffect`,
+`onMounted`, `afterNextRender`).
+
+**Bundle size:** the entry is about 60 kB gzipped. The PDF engine (about 165 kB gzipped) and the save code load on
+demand as separate chunks. Vite may still warn that those chunks are over 500 kB; that's expected, and
+`build.chunkSizeWarningLimit: 1000` silences it.
+
+### Without a bundler
+
+```html
+<div id="viewer" style="height: 100vh"></div>
+<script src="https://cdn.jsdelivr.net/npm/pdfcedar@0.1.1-beta.0/dist/pdfcedar.umd.js"></script>
+<script>
+  PDFCedar.createViewer({ container: document.getElementById('viewer'), document: 'file.pdf' });
+</script>
+```
+
+`dist/pdfcedar.umd.js` works from jsDelivr, unpkg or your own server. It finds the engine files (`dist/pdfjs/`) next
+to itself, so `assetBaseUrl` isn't needed. Pin the exact version, as here: CDN ranges like `@0.1` skip beta releases.
+
+### Frameworks
+
+| | Mount in | Destroy in |
+|---|---|---|
+| React | `useEffect` | the effect's cleanup |
+| Vue | `onMounted` | `onBeforeUnmount` |
+| Angular | `ngAfterViewInit` | `ngOnDestroy` |
+
+Complete, runnable examples are in the repository's `examples/` folder. Always call `viewer.destroy()` when the
+component goes away; it frees the worker, canvases and listeners.
+
+## Options
+
+| Option | Type | |
+|---|---|---|
+| `container` | `HTMLElement` | Required. The viewer fills it. |
+| `document` | `string \| File \| Blob \| ArrayBuffer` | Required. A URL (fetched with range requests) or the file itself. |
+| `licenseKey` | `string` | Your licence key (see below). Without a valid one the viewer runs in trial mode. |
+| `assetBaseUrl` | `string` | URL of the folder holding the engine files. |
+| `theme` | `'light' \| 'dark' \| ThemeObject` | A `ThemeObject` maps `--pl-*` CSS variables to values. |
+| `toolbar` | `ToolName[]` | Which tools to show. Omit for all. |
+| `readOnly` | `boolean` | Viewing, search and print only. |
+| `user` | `{ id, name }` | Author of new annotations and replies. |
+| `collaboration` | `{ serverUrl, roomId }` | Real-time sharing with everyone in the room (see below). |
+| `signatureStore` | `{ load(), save(list) }` | Where the user's saved signatures persist (e.g. your backend). Without it they last for the page session. |
+| `password` | `string` | For password-protected PDFs. If it's missing or wrong, the viewer asks the user; `createViewer` rejects with `EncryptedDocumentError` if they cancel. |
+| `httpHeaders` | `Record<string, string>` | Sent when `document` is a URL, e.g. `{ Authorization: 'Bearer …' }` for files behind a login. |
+| `withCredentials` | `boolean` | Send cookies when `document` is a URL on another origin (the server must allow credentials). |
+
+`ToolName` is any of `'zoom'`, `'search'`, `'download'`, `'print'`, `'pages'`, `'select'`, `'highlight'`, `'underline'`,
+`'strikeout'`, `'note'`, `'ink'`, `'rectangle'`, `'ellipse'`, `'line'`, `'arrow'`, `'freeText'`, `'signature'`, `'redaction'`.
+
+## API
+
+```ts
+// Events: documentLoaded, pageChanged, annotationAdded, annotationChanged, annotationRemoved,
+//         formFieldChanged, signatureAdded, saved. Payloads are typed (see ViewerEvents).
+viewer.on(event, handler); viewer.off(event, handler);
+
+// Navigation
+viewer.goToPage(3); viewer.setZoom(1.5); viewer.fit('width'); // or 'page'
+const hits = await viewer.search('total');                   // highlights every match
+
+// Annotations (coordinates in PDF points, origin bottom-left)
+const note = viewer.annotations.add({ type: 'note', page: 1, rect: { x: 72, y: 700, width: 24, height: 24 }, contents: 'Check this' });
+viewer.annotations.update(note.id, { color: '#2563eb' });
+viewer.annotations.remove(note.id);
+viewer.annotations.list();                       // or list({ page: 1, type: 'highlight' })
+const json = viewer.annotations.export();        // save to your backend…
+viewer.annotations.import(json);                 // …and restore later
+viewer.undo(); viewer.redo();
+
+// Pages (1-based)
+viewer.pages.rotate(1, 90); viewer.pages.delete(2); viewer.pages.move(3, 1);
+await viewer.pages.merge(file);
+
+// Forms: the file's own fields are drawn as fillable controls
+viewer.forms.getValues();                        // { fullName: '', subscribe: false, plan: 'pro', interests: ['A'] }
+viewer.forms.setValues({ fullName: 'Asha Rao', subscribe: true }); // one undo step; FormValueError if invalid
+viewer.forms.flatten();                          // on save, fields become part of the page
+
+// Signatures: the Signature tool lets users draw, type or upload one; from code:
+const signature = await viewer.signatures.add({
+  page: 1,
+  rect: { x: 360, y: 90, width: 150, height: 50 },
+  image: blobOrDataUrlOrUrl, // PNG, JPEG, WebP, SVG…
+});
+// Movable, resizable and undoable until saved; saving draws it into the page.
+
+// Redaction: mark areas (the Redact tool marks selected text or a dragged box), then apply
+viewer.redaction.mark({ page: 1, rect: { x: 72, y: 640, width: 180, height: 14 } });
+await viewer.redaction.apply(); // final: marks turn black, undo history is cleared
+const redacted = await viewer.save(); // the content under the marks is removed from the file
+
+// Output
+const bytes = await viewer.save();               // Uint8Array
+await viewer.download('reviewed.pdf');
+await viewer.print();
+viewer.destroy();
+```
+
+Annotation types: `highlight`, `underline`, `strikeout`, `note`, `reply`, `ink`, `rectangle`, `ellipse`, `line`,
+`arrow`, `freeText`, `signature`. Saved files use standard PDF annotations with appearance streams, so Acrobat Reader, Chrome,
+Firefox and Safari show them and can edit them. Signatures are the exception: saving draws them into the page, so they
+can no longer be moved or removed in any viewer.
+
+## Redaction
+
+Applied redactions remove content from the saved file, not just cover it:
+
+- **Text:** removed glyph by glyph. The rest of the line keeps its position.
+- **Images, including scans:** the pixels under the mark are blacked out in the image itself.
+- **Shapes:** vector shapes entirely inside a mark are removed.
+- **Annotations and form fields:** any that overlap a mark are deleted.
+- **Hidden copies:** `/ActualText` that repeats removed text is stripped, and no copy of the original content stays in the file.
+
+Unapplied marks are saved as standard `/Redact` annotations, which Acrobat can apply.
+
+## Theming
+
+```css
+.pdfcedar-viewer {
+  --pl-accent: #7c3aed;
+  --pl-bg: #f4f4f5;
+  --pl-surface: #ffffff;
+  --pl-text: #18181b;
+  --pl-font: 'Inter', system-ui, sans-serif;
+}
+```
+
+## Collaboration
+
+```js
+createViewer({
+  container,
+  document: '/files/contract.pdf',
+  user: { id: 'u1', name: 'Asha Rao' },
+  collaboration: { serverUrl: 'wss://collab.example.com', roomId: 'contract-123' },
+});
+```
+
+- **What's shared:** everyone in the room sees each other's annotations, replies, signatures, redaction marks and form
+  values within a second, and the toolbar shows who's online.
+- **Events and undo:** changes from others fire the usual events with `source: 'remote'`, and never enter your undo
+  history.
+- **Offline:** edits made offline sync when the connection is back.
+- **Not shared:** page changes (rotate, delete, reorder) stay per person, so everyone in a room should have the same
+  pages.
+- **Server:** run your own. The repository's `apps/collab-server` is a small ready-made one (`node src/server.mjs`);
+  any y-websocket-compatible server works too. Documents never pass through PDFCedar's servers.
+- **Size:** the collaboration code loads only when this option is set.
+
+## Licence key
+
+```js
+createViewer({ container, document, licenseKey: 'PL1.eyJ2Ijox…' });
+```
+
+- **Offline check:** the key is checked in the browser, with no network call. It's a signed list of the domains
+  you bought it for, so nothing about your users or documents leaves the page.
+- **Domains:** `example.com` covers only that host; `*.example.com` covers its subdomains. Any valid key also works
+  on `localhost` and `127.0.0.1`, for development.
+- **Trial mode:** without a valid key (missing, mistyped, expired, or on another domain) everything still works,
+  but the pages carry a "PDFCedar trial" watermark and a Trial badge. Saved, downloaded and printed files are
+  watermarked too. The console says why, as does the
+  viewer element's `data-license-reason` attribute.
+
+## Phones and tablets
+
+- **Pinch** zooms around your fingers; on desktop, Ctrl/⌘ + wheel and trackpad pinches do the same.
+- **Drawing:** one finger draws with the drawing tools. A second finger turns a stroke into a pinch, so no stray line is left.
+- **Select tool:** touching a selected annotation drags it; elsewhere, one finger scrolls. Handles are larger on touch screens.
+- **Narrow viewers** (under 640 px wide, by the viewer's own width) get a compact toolbar:
+  - **Annotate** shows the tools in a row that scrolls sideways.
+  - **More** holds Search, Download and Print.
+  - The sidebar is a drawer that starts closed.
+
+Give your page `<meta name="viewport" content="width=device-width, initial-scale=1">`, as every mobile page needs.
+
+## Browser support
+
+Chrome and Edge 119+, Firefox 121+, Safari 17.4+ (desktop and iOS), Chrome on Android.
+
+## Errors
+
+- `createViewer` rejects if the file can't be opened (bad URL, not a PDF).
+- `annotations.add` / `update` / `import` throw `AnnotationValidationError` (with a `path` such as `rect.width`) for invalid input.
+- `forms.setValues` throws `FormValueError` (with the `field` name) for an unknown field or a value it can't hold; nothing changes.
+- `annotations.update` / `remove` throw `AnnotationValidationError` for an applied redaction (applying is final).
+- `createViewer` rejects with `EncryptedDocumentError` when a password-protected PDF is opened and the user cancels the password prompt.
+- `save` / `download` / `print` throw `EncryptedDocumentError` for password-protected PDFs (viewing, annotating and searching them work; writing encrypted files back out is not supported yet).

package/dist/chunks/{errors-Bd8CCmBG.js → errors-Cq5TPos_.js}

@@ -176,10 +176,10 @@ var h = class extends Error {
 		super(`${e} is not implemented yet (planned for Milestone ${t}).`), this.name = "NotImplementedError";
 	}
 }, g = class extends Error {
-	constructor() {
-		super("Saving password-protected (encrypted) PDFs is not supported yet."), this.name = "EncryptedDocumentError";
+	constructor(e = "Saving password-protected (encrypted) PDFs is not supported yet.") {
+		super(e), this.name = "EncryptedDocumentError";
 	}
 };
 export { l as a, p as c, u as d, s as f, n as g, t as h, d as i, f as l, e as m, h as n, o, a as p, m as r, c as s, g as t, r as u };
 
-//# sourceMappingURL=errors-Bd8CCmBG.js.map
+//# sourceMappingURL=errors-Cq5TPos_.js.map