pdfcedar 0.0.0-stage → 0.1.1-beta.0

package/LICENSE

@@ -0,0 +1,47 @@
+PDFCedar Commercial License
+
+Copyright (c) 2026 Waseem Ahmad Dar. All rights reserved.
+
+PDFCedar is commercial software. It is licensed, not sold. By installing or using it you accept these terms.
+Pricing and the full terms of service are at https://pdfcedar.brimij.com.
+
+1. Evaluation (no licence key)
+   You may install and use PDFCedar free of charge to evaluate it and to develop and test your
+   applications. Without a valid licence key the software runs in trial mode: pages, saved files and
+   printed output carry a "PDFCedar trial" watermark. You may not use trial mode in production, and you
+   may not remove, hide or work around the watermark or the licence check.
+
+2. Production use (licence key required)
+   Using PDFCedar in an application available to end users requires a paid licence key. A key covers
+   one product, on the domains listed in it (a wildcard such as *.example.com covers its subdomains),
+   for the term of the plan you bought. Any valid key also works on localhost for development. There are
+   no limits on developers, end users or documents.
+
+3. Distribution
+   You may distribute PDFCedar only as part of your own application, bundled in that application's
+   build. You may not:
+   a. sell, sublicense, rent or redistribute it on its own;
+   b. offer it, or a product whose main purpose is PDF viewing or editing built on it, to other
+      developers as a software development kit, library or component;
+   c. modify, decompile or reverse engineer it, except where the law allows this despite this term;
+   d. share licence keys outside your organisation.
+
+4. Term and termination
+   A licence lasts for the term of the plan. When it expires, the software returns to trial mode until it
+   is renewed. Updates released during the term are included. If you breach these terms your licence ends
+   and you must stop using the software in production.
+
+5. Notices
+   This notice must be kept in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR
+THE USE OR OTHER DEALINGS IN THE SOFTWARE. THE TOTAL LIABILITY OF THE AUTHORS IS LIMITED TO THE FEES
+YOU PAID FOR THE SOFTWARE IN THE TWELVE MONTHS BEFORE A CLAIM.
+
+Contact: sales@brimij.com
+
+Third-party components bundled in this package keep their own licences: pdf.js (Apache License 2.0,
+see dist/pdfjs/LICENSE) and pdf-lib (MIT License, see dist/THIRD_PARTY_NOTICES.md).

package/README.md

@@ -1,3 +1,238 @@
-# Temporary Holding Version
+# PDFCedar
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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/bin/pdfcedar-assets.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// Copies PDFCedar's PDF engine files (pdf.js worker, fonts, cMaps) into a folder your app serves.
+//   npx pdfcedar-assets public/pdfcedar   →  then pass  assetBaseUrl: '/pdfcedar/'  to createViewer.
+// Bundlers (Vite, webpack, Angular CLI) copy JavaScript but not these runtime files, so this step makes them available.
+import { cpSync, existsSync, readFileSync, rmSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const args = process.argv.slice(2);
+if (args.length !== 1 || args[0].startsWith('-')) {
+  console.log('Usage: pdfcedar-assets <folder>\n\nExample: pdfcedar-assets public/pdfcedar, then createViewer({ assetBaseUrl: "/pdfcedar/", ... })');
+  process.exit(args.includes('--help') || args.includes('-h') ? 0 : 1);
+}
+
+const source = join(dirname(fileURLToPath(import.meta.url)), '..', 'dist', 'pdfjs');
+if (!existsSync(source)) {
+  console.error(`pdfcedar-assets: ${source} is missing. Reinstall the pdfcedar package.`);
+  process.exit(1);
+}
+const target = resolve(args[0]);
+// Start clean so files from an older version don't linger next to the new worker.
+rmSync(target, { recursive: true, force: true });
+cpSync(source, target, { recursive: true });
+const { version } = JSON.parse(readFileSync(join(source, '..', '..', 'package.json'), 'utf8'));
+console.log(`pdfcedar-assets: copied PDFCedar ${version} engine files to ${target}`);