teamsync-pdf-viewer 1.0.3 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,82 @@
+# Changelog
+
+All notable changes to `teamsync-pdf-viewer` are documented here.
+
+## [1.2.0] — 2026-08-31
+
+### Added
+- **`AnnotationManager`** (`instance.annotationManager`, also `instance.Core.annotationManager`):
+  the canonical annotation list with undo/redo, granular `annotationChanged` events
+  (`add` | `modify` | `delete`, with an `imported` flag), authorship stamping
+  (`currentUser`), edit permissions (read-only viewer, read-only annotation, other authors —
+  `permissions.canEditOthers`) and programmatic `addAnnotations` / `updateAnnotation` /
+  `deleteAnnotations` / `getAnnotationById`.
+- **Native XFDF**: `annotationManager.importAnnotations(xfdf)` and
+  `exportAnnotations({ annotList?, useDisplayAuthor? })` (bare fragments per annotation, or a full
+  document). Reads Acrobat/Apryse XFDF (square, circle, line/arrow, ink, highlight quads, freetext,
+  callout, sticky note, stamp with image data, link) and keeps everything else as read-only
+  `opaque` annotations that re-export verbatim; unknown attributes/children (e.g. Apryse
+  `trn-custom-data`) are preserved across a round-trip. Stable UUID ids double as the XFDF `name`.
+- **Page geometry module** (`createPageGeometry`, `rectToPdf`, `quadPointsToRects`, …): the single
+  authority for base-page-space ↔ PDF-user-space conversion, mirroring pdf.js's viewport transform.
+- **Print** (menu item enabled, `instance.print()`): the exported document is printed through the
+  browser's PDF viewer in a hidden frame.
+- `instance.on('annotationChanged', …)` typed event; `Annotation.author/authorId/createdAt/
+  modifiedAt/readOnly/strokes/rects` fields; multi-stroke ink and multi-rect highlights render.
+
+### Fixed
+- Export geometry: annotations are baked exactly where they were drawn (any page size, CropBox
+  offset or intrinsic /Rotate) — replaces the hard-coded `scale = 1.5` conversion.
+- Mixed page sizes: layout, scrolling, hit-testing and fit-to-width/page now use per-page
+  dimensions instead of page 1's.
+- Annotation ids were timestamps (collision-prone); now `crypto.randomUUID()`.
+
+## [1.1.0] — 2026-08-31
+
+### Breaking
+- The npm entry point is now **side-effect free**: importing the package no longer touches `window`,
+  never auto-mounts a demo viewer into `#root`, and no longer installs the iframe `postMessage` bridge.
+  Those behaviours live in the demo/iframe application build only (`src/demo/main.tsx`,
+  `npm run build:app`, `public/webviewer.js`).
+- `react`, `react-dom` and `pdfjs-dist` are **peer dependencies** (previously `react` was a hard
+  dependency, which could install a second React copy).
+- The pdf.js **worker is no longer inlined** as a `data:` URL. Hosts must serve
+  `pdf.worker.min.mjs` (matching their installed `pdfjs-dist`) and call `configurePdfAssets({ workerSrc })`
+  or pass `assets={{ workerSrc }}` to `<TeamSyncViewer>`. This shrinks the bundle from 5.3 MB to
+  well under 1 MB and works under strict Content-Security-Policies.
+- The UMD build was removed (`pdfjs-dist` v6 is ESM-only, so it never worked for real consumers).
+  Script-tag users are served by the iframe package.
+- `DocumentViewer`, `Header`, `Sidebar` and `PageRenderer` are no longer exported — they are
+  internal components with unstable props. Use `<TeamSyncViewer>` / `createWebViewer()`.
+- Library styles are scoped under `.tspdf-root`; the global `*`/`body` resets moved to the demo.
+
+### Added
+- `<TeamSyncViewer>` — an embeddable, container-sized React component with a small, typed prop
+  surface (`fileUrl`, `readOnly`, `currentUser`, `assets`, `withCredentials`, `toolbar`, `sidebars`,
+  `initialScale: 'fit-width' | 'fit-page'`, `onReady`, `onDocumentLoaded`, `onDocumentLoadError(error, retry)`,
+  `onFirstPageRendered`, `onPasswordRequired`, `onPageChange`, `onAnnotationsChange`).
+- `createWebViewer(options, element)` (the old `WebViewer()` remains as a deprecated alias) returning a
+  `WebViewerInstance` with `destroy()`, `loadDocument(url)`, typed `on()/off()` events
+  (`documentLoaded`, `documentLoadError`, `firstPageRendered`, `pageChanged`, `annotationsChanged`,
+  `toolChanged`, `destroy`), `getFileData()`, `getAnnotations()` and the legacy `UI`/`Core` facades.
+- Per-instance event bus: several viewers can be mounted on one page without cross-talk; keyboard
+  shortcuts apply to the focused viewer only.
+- `configurePdfAssets()` for worker / CMap / standard-font / wasm locations.
+- Real TypeScript declarations (`dist/index.d.ts`), `teamsync-pdf-viewer/style.css`, `"use client"`
+  banner for React Server Components bundlers, `sideEffects` metadata, source maps.
+- CI workflow (lint, typecheck, unit tests, library + demo builds, `publint` + `arethetypeswrong`
+  package guards) and a first vitest suite.
+
+### Fixed
+- `package.json` `types` condition ordering and the non-existent `dist/style.css` export.
+- Export (`getFileData`) no longer issues a `HEAD` probe nor re-downloads the document; it uses the
+  bytes of the already-loaded document, so presigned/expiring URLs work.
+- Pages with an intrinsic `/Rotate` render correctly; UI rotation now composes on top of it
+  (search highlights and redactions were previously misplaced on such pages).
+- Hard-coded signer email removed from digital-signature placeholders (uses `currentUser.name`).
+- Watermark text no longer defaults to `user@example.com - Confidential` in embedded usage.
+- Loading errors (including password-protected documents) are surfaced instead of being logged only.
+- Truncated `LICENSE` replaced with the full CPAL-1.0 text; stale docs and package name fixed.
+
+## [1.0.4] — 2026-08-15
+- Historical release (never published to npm; 1.0.3 is the last 1.0.x on the registry).

package/LICENSE

@@ -73,5 +73,100 @@ You must cause all Covered Code to which You contribute to contain a file docume
 
 3.4 Intellectual Property Matters
 
-     (a) Third Party Claims.  If Contributor has knowledge that a license under a third party’s intellectual property rights is required to exercise the rights granted by such Contributor under Sections 2.1 or 2.2, Contributor must include a text file with the Source Code distribution titled “LEGAL” which describes the claim and the party making the claim in sufficient detail that a recipient will know whom to contact. If Contributor obtains such knowledge after the Modificati
+     (a) Third Party Claims.  If Contributor has knowledge that a license under a third party’s intellectual property rights is required to exercise the rights granted by such Contributor under Sections 2.1 or 2.2, Contributor must include a text file with the Source Code distribution titled “LEGAL” which describes the claim and the party making the claim in sufficient detail that a recipient will know whom to contact. If Contributor obtains such knowledge after the Modification is made available as described in Section 3.2, Contributor shall promptly modify the LEGAL file in all copies Contributor makes available thereafter and shall take other steps (such as notifying appropriate mailing lists or newsgroups) reasonably calculated to inform those who received the Covered Code that new knowledge has been obtained.
 
+     (b) Contributor APIs.  If Contributor’s Modifications include an application programming interface and Contributor has knowledge of patent licenses which are reasonably necessary to implement that API, Contributor must also include this information in the LEGAL file.
+
+     (c) Representations. Contributor represents that, except as disclosed pursuant to Section 3.4(a) above, Contributor believes that Contributor’s Modifications are Contributor’s original creation(s) and/or Contributor has sufficient rights to grant the rights conveyed by this License.
+
+3.5 Required Notices.
+You must duplicate the notice in Exhibit A in each file of the Source Code. If it is not possible to put such notice in a particular Source Code file due to its structure, then You must include such notice in a location (such as a relevant directory) where a user would be likely to look for such a notice. If You created one or more Modification(s) You may add your name as a Contributor to the notice described in Exhibit A. You must also duplicate this License in any documentation for the Source Code where You describe recipients’ rights or ownership rights relating to Covered Code. You may choose to offer, and to charge a fee for, warranty, support, indemnity or liability obligations to one or more recipients of Covered Code. However, You may do so only on Your own behalf, and not on behalf of the Initial Developer or any Contributor. You must make it absolutely clear than any such warranty, support, indemnity or liability obligation is offered by You alone, and You hereby agree to indemnify the Initial Developer and every Contributor for any liability incurred by the Initial Developer or such Contributor as a result of warranty, support, indemnity or liability terms You offer.
+
+3.6 Distribution of Executable Versions.
+You may distribute Covered Code in Executable form only if the requirements of Section 3.1-3.5 have been met for that Covered Code, and if You include a notice stating that the Source Code version of the Covered Code is available under the terms of this License, including a description of how and where You have fulfilled the obligations of Section 3.2. The notice must be conspicuously included in any notice in an Executable version, related documentation or collateral in which You describe recipients’ rights relating to the Covered Code. You may distribute the Executable version of Covered Code or ownership rights under a license of Your choice, which may contain terms different from this License, provided that You are in compliance with the terms of this License and that the license for the Executable version does not attempt to limit or alter the recipient’s rights in the Source Code version from the rights set forth in this License. If You distribute the Executable version under a different license You must make it absolutely clear that any terms which differ from this License are offered by You alone, not by the Initial Developer, Original Developer or any Contributor. You hereby agree to indemnify the Initial Developer, Original Developer and every Contributor for any liability incurred by the Initial Developer, Original Developer or such Contributor as a result of any such terms You offer.
+
+3.7 Larger Works.
+You may create a Larger Work by combining Covered Code with other code not governed by the terms of this License and distribute the Larger Work as a single product. In such a case, You must make sure the requirements of this License are fulfilled for the Covered Code.
+
+4. Inability to Comply Due to Statute or Regulation.
+If it is impossible for You to comply with any of the terms of this License with respect to some or all of the Covered Code due to statute, judicial order, or regulation then You must: (a) comply with the terms of this License to the maximum extent possible; and (b) describe the limitations and the code they affect. Such description must be included in the LEGAL file described in Section 3.4 and must be included with all distributions of the Source Code. Except to the extent prohibited by statute or regulation, such description must be sufficiently detailed for a recipient of ordinary skill to be able to understand it.
+
+5. Application of this License.
+This License applies to code to which the Initial Developer has attached the notice in Exhibit A and to related Covered Code.
+
+6. Versions of the License.
+
+6.1 New Versions.
+Socialtext, Inc. (“Socialtext”) may publish revised and/or new versions of the License from time to time. Each version will be given a distinguishing version number.
+
+6.2 Effect of New Versions.
+Once Covered Code has been published under a particular version of the License, You may always continue to use it under the terms of that version. You may also choose to use such Covered Code under the terms of any subsequent version of the License published by Socialtext. No one other than Socialtext has the right to modify the terms applicable to Covered Code created under this License.
+
+6.3 Derivative Works.
+If You create or use a modified version of this License (which you may only do in order to apply it to code which is not already Covered Code governed by this License), You must (a) rename Your license so that the phrases “Socialtext”, “CPAL” or any confusingly similar phrase do not appear in your license (except to note that your license differs from this License) and (b) otherwise make it clear that Your version of the license contains terms which differ from the CPAL. (Filling in the name of the Initial Developer, Original Developer, Original Code or Contributor in the notice described in Exhibit A shall not of themselves be deemed to be modifications of this License.)
+
+7. DISCLAIMER OF WARRANTY.
+COVERED CODE IS PROVIDED UNDER THIS LICENSE ON AN “AS IS” BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, WARRANTIES THAT THE COVERED CODE IS FREE OF DEFECTS, MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE OR NON-INFRINGING. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE COVERED CODE IS WITH YOU. SHOULD ANY COVERED CODE PROVE DEFECTIVE IN ANY RESPECT, YOU (NOT THE INITIAL DEVELOPER, ORIGINAL DEVELOPER OR ANY OTHER CONTRIBUTOR) ASSUME THE COST OF ANY NECESSARY SERVICING, REPAIR OR CORRECTION. THIS DISCLAIMER OF WARRANTY CONSTITUTES AN ESSENTIAL PART OF THIS LICENSE. NO USE OF ANY COVERED CODE IS AUTHORIZED HEREUNDER EXCEPT UNDER THIS DISCLAIMER.
+
+8. TERMINATION.
+
+8.1 This License and the rights granted hereunder will terminate automatically if You fail to comply with terms herein and fail to cure such breach within 30 days of becoming aware of the breach. All sublicenses to the Covered Code which are properly granted shall survive any termination of this License. Provisions which, by their nature, must remain in effect beyond the termination of this License shall survive.
+
+8.2 If You initiate litigation by asserting a patent infringement claim (excluding declatory judgment actions) against Initial Developer, Original Developer or a Contributor (the Initial Developer, Original Developer or Contributor against whom You file such action is referred to as “Participant”) alleging that:
+
+     (a) such Participant’s Contributor Version directly or indirectly infringes any patent, then any and all rights granted by such Participant to You under Sections 2.1 and/or 2.2 of this License shall, upon 60 days notice from Participant terminate prospectively, unless if within 60 days after receipt of notice You either: (i) agree in writing to pay Participant a mutually agreeable reasonable royalty for Your past and future use of Modifications made by such Participant, or (ii) withdraw Your litigation claim with respect to the Contributor Version against such Participant. If within 60 days of notice, a reasonable royalty and payment arrangement are not mutually agreed upon in writing by the parties or the litigation claim is not withdrawn, the rights granted by Participant to You under Sections 2.1 and/or 2.2 automatically terminate at the expiration of the 60 day notice period specified above.
+
+     (b) any software, hardware, or device, other than such Participant’s Contributor Version, directly or indirectly infringes any patent, then any rights granted to You by such Participant under Sections 2.1(b) and 2.2(b) are revoked effective as of the date You first made, used, sold, distributed, or had made, Modifications made by that Participant.
+
+8.3 If You assert a patent infringement claim against Participant alleging that such Participant’s Contributor Version directly or indirectly infringes any patent where such claim is resolved (such as by license or settlement) prior to the initiation of patent infringement litigation, then the reasonable value of the licenses granted by such Participant under Sections 2.1 or 2.2 shall be taken into account in determining the amount or value of any payment or license.
+
+8.4 In the event of termination under Sections 8.1 or 8.2 above, all end user license agreements (excluding distributors and resellers) which have been validly granted by You or any distributor hereunder prior to termination shall survive termination.
+
+9. LIMITATION OF LIABILITY.
+UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL THEORY, WHETHER TORT (INCLUDING NEGLIGENCE), CONTRACT, OR OTHERWISE, SHALL YOU, THE INITIAL DEVELOPER, ORIGINAL DEVELOPER, ANY OTHER CONTRIBUTOR, OR ANY DISTRIBUTOR OF COVERED CODE, OR ANY SUPPLIER OF ANY OF SUCH PARTIES, BE LIABLE TO ANY PERSON FOR ANY INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR MALFUNCTION, OR ANY AND ALL OTHER COMMERCIAL DAMAGES OR LOSSES, EVEN IF SUCH PARTY SHALL HAVE BEEN INFORMED OF THE POSSIBILITY OF SUCH DAMAGES. THIS LIMITATION OF LIABILITY SHALL NOT APPLY TO LIABILITY FOR DEATH OR PERSONAL INJURY RESULTING FROM SUCH PARTY’S NEGLIGENCE TO THE EXTENT APPLICABLE LAW PROHIBITS SUCH LIMITATION. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THIS EXCLUSION AND LIMITATION MAY NOT APPLY TO YOU.
+
+10. U.S. GOVERNMENT END USERS.
+The Covered Code is a “commercial item,” as that term is defined in 48 C.F.R. 2.101 (Oct. 1995), consisting of “commercial computer software” and “commercial computer software documentation,” as such terms are used in 48 C.F.R. 12.212 (Sept. 1995). Consistent with 48 C.F.R. 12.212 and 48 C.F.R. 227.7202-1 through 227.7202-4 (June 1995), all U.S. Government End Users acquire Covered Code with only those rights set forth herein.
+
+11. MISCELLANEOUS.
+This License represents the complete agreement concerning subject matter hereof. If any provision of this License is held to be unenforceable, such provision shall be reformed only to the extent necessary to make it enforceable. This License shall be governed by California law provisions (except to the extent applicable law, if any, provides otherwise), excluding its conflict-of-law provisions. With respect to disputes in which at least one party is a citizen of, or an entity chartered or registered to do business in the United States of America, any litigation relating to this License shall be subject to the jurisdiction of the Federal Courts of the Northern District of California, with venue lying in Santa Clara County, California, with the losing party responsible for costs, including without limitation, court costs and reasonable attorneys’ fees and expenses. The application of the United Nations Convention on Contracts for the International Sale of Goods is expressly excluded. Any law or regulation which provides that the language of a contract shall be construed against the drafter shall not apply to this License.
+
+12. RESPONSIBILITY FOR CLAIMS.
+As between Initial Developer, Original Developer and the Contributors, each party is responsible for claims and damages arising, directly or indirectly, out of its utilization of rights under this License and You agree to work with Initial Developer, Original Developer and Contributors to distribute such responsibility on an equitable basis. Nothing herein is intended or shall be deemed to constitute any admission of liability.
+
+13. MULTIPLE-LICENSED CODE.
+Initial Developer may designate portions of the Covered Code as Multiple-Licensed. Multiple-Licensed means that the Initial Developer permits you to utilize portions of the Covered Code under Your choice of the CPAL or the alternative licenses, if any, specified by the Initial Developer in the file described in Exhibit A.
+
+14. ADDITIONAL TERM: ATTRIBUTION
+
+     (a) As a modest attribution to the organizer of the development of the Original Code (“Original Developer”), in the hope that its promotional value may help justify the time, money and effort invested in writing the Original Code, the Original Developer may include in Exhibit B (“Attribution Information”) a requirement that each time an Executable and Source Code or a Larger Work is launched or initially run (which includes initiating a session), a prominent display of the Original Developer’s Attribution Information (as defined below) must occur on the graphic user interface employed by the end user to access such Covered Code (which may include display on a splash screen), if any. The size of the graphic image should be consistent with the size of the other elements of the Attribution Information. If the access by the end user to the Executable and Source Code does not create a graphic user interface for access to the Covered Code, this obligation shall not apply. If the Original Code displays such Attribution Information in a particular form (such as in the form of a splash screen, notice at login, an “about” display, or dedicated attribution area on user interface screens), continued use of such form for that Attribution Information is one way of meeting this requirement for notice.
+
+     (b) Attribution information may only include a copyright notice, a brief phrase, graphic image and a URL (“Attribution Information”) and is subject to the Attribution Limits as defined below. For these purposes, prominent shall mean display for sufficient duration to give reasonable notice to the user of the identity of the Original Developer and that if You include Attribution Information or similar information for other parties, You must ensure that the Attribution Information for the Original Developer shall be no less prominent than such Attribution Information or similar information for the other party. For greater certainty, the Original Developer may choose to specify in Exhibit B below that the above attribution requirement only applies to an Executable and Source Code resulting from the Original Code or any Modification, but not a Larger Work. The intent is to provide for reasonably modest attribution, therefore the Original Developer cannot require that You display, at any time, more than the following information as Attribution Information: (a) a copyright notice including the name of the Original Developer; (b) a word or one phrase (not exceeding 10 words); (c) one graphic image provided by the Original Developer; and (d) a URL (collectively, the “Attribution Limits”).
+
+     (c) If Exhibit B does not include any Attribution Information, then there are no requirements for You to display any Attribution Information of the Original Developer.
+
+     (d) You acknowledge that all trademarks, service marks and/or trade names contained within the Attribution Information distributed with the Covered Code are the exclusive property of their owners and may only be used with the permission of their owners, or under circumstances otherwise permitted by law or as expressly set out in this License.
+
+15. ADDITIONAL TERM: NETWORK USE.
+The term “External Deployment” means the use, distribution, or communication of the Original Code or Modifications in any way such that the Original Code or Modifications may be used by anyone other than You, whether those works are distributed or communicated to those persons or made available as an application intended for use over a network. As an express condition for the grants of license hereunder, You must treat any External Deployment by You of the Original Code or Modifications as a distribution under section 3.1 and make Source Code available under Section 3.2.
+
+EXHIBIT A. Common Public Attribution License Version 1.0.
+
+“The contents of this file are subject to the Common Public Attribution License Version 1.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at https://opensource.org/license/cpal-1-0. The License is based on the Mozilla Public License Version 1.1 but Sections 14 and 15 have been added to cover use of software over a computer network and provide for limited attribution for the Original Developer. In addition, Exhibit A has been modified to be consistent with Exhibit B.
+Software distributed under the License is distributed on an “AS IS” basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License.
+The Original Code is TeamSync PDF Viewer.
+The Original Developer is not the Initial Developer and is __________. If left blank, the Original Developer is the Initial Developer. (Left blank: the Original Developer is the Initial Developer.)
+The Initial Developer of the Original Code is AngelBot Ai Pvt Ltd. All portions of the code written by AngelBot Ai Pvt Ltd are Copyright (c) 2026 AngelBot Ai Pvt Ltd. All Rights Reserved.
+Contributor: as recorded in the repository history at https://github.com/angelbot-ai/TeamSync-PDF-Viewer.
+Alternatively, the contents of this file may be used under the terms of the _____ license (the [___] License), in which case the provisions of [______] License are applicable instead of those above.
+If you wish to allow use of your version of this file only under the terms of the [____] License and not to allow others to use your version of this file under the CPAL, indicate your decision by deleting the provisions above and replace them with the notice and other provisions required by the [___] License. If you do not delete the provisions above, a recipient may use your version of this file under either the CPAL or the [___] License.”
+
+[NOTE: The text of this Exhibit A may differ slightly from the text of the notices in the Source Code files of the Original Code. You should use the text of this Exhibit A rather than the text found in the Original Code Source Code for Your Modifications.]
+
+EXHIBIT B. Attribution Information
+
+Attribution Copyright Notice: Copyright (c) 2026 AngelBot Ai Pvt Ltd. All Rights Reserved.
+Attribution Phrase (not exceeding 10 words): Powered by TeamSync PDF Viewer
+Attribution URL: https://pdfviewer.teamsync.com/
+Graphic Image as provided in the Covered Code, if any: the TeamSync logo included in the Covered Code (public/favicon.svg), if any.
+Display of Attribution Information is required in Larger Works which are defined in the CPAL as a work which combines Covered Code or portions thereof with code not governed by the terms of the CPAL.

package/README.md

@@ -1,233 +1,254 @@
 # TeamSync PDF Viewer SDK
 
+Client-side PDF viewing, annotation, search, redaction and watermarking for React — built on
+[pdf.js](https://mozilla.github.io/pdf.js/) and [pdf-lib](https://pdf-lib.js.org/).
+
 <div align="center">
 
 ![TeamSync PDF Viewer UI](https://raw.githubusercontent.com/angelbot-ai/TeamSync-PDF-Viewer/main/docs/images/viewer_ui.png)
 
-### **100% Open Source. 100% Client-Side. Enterprise PDF Engine.**
-
 [![License: CPAL-1.0](https://img.shields.io/badge/License-CPAL--1.0-blue.svg)](LICENSE)
 [![Live Demo](https://img.shields.io/badge/Live%20Demo-pdfviewer.teamsync.com-000000.svg)](https://pdfviewer.teamsync.com/)
-[![NPM Version](https://img.shields.io/badge/npm-%40angelbot--ai%2Fteamsync--pdf--viewer-blue.svg)](https://www.npmjs.com/package/teamsync-pdf-viewer)
-[![React 19](https://img.shields.io/badge/React-19-61dafb.svg)](https://reactjs.org/)
-[![Vite 8](https://img.shields.io/badge/Vite-8.2-646cff.svg)](https://vitejs.dev/)
-[![TypeScript](https://img.shields.io/badge/TypeScript-6.0-blue.svg)](https://www.typescriptlang.org/)
-
-*No paywalls. No vendor lock-in. No server dependencies.*  
-Try the **[Interactive Live Demo](https://pdfviewer.teamsync.com/)** or integrate the high-performance PDF Viewer SDK into your React applications.
+[![npm](https://img.shields.io/npm/v/teamsync-pdf-viewer.svg)](https://www.npmjs.com/package/teamsync-pdf-viewer)
+[![React 18/19](https://img.shields.io/badge/React-18%20%7C%2019-61dafb.svg)](https://react.dev/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-types%20included-blue.svg)](https://www.typescriptlang.org/)
 
 </div>
 
 ---
 
-## 🚀 Why TeamSync PDF Viewer?
-
-Traditional commercial PDF viewers force developers into expensive per-domain licenses, opaque sales calls, and heavy server-side processing dependencies. **TeamSync PDF Viewer** is built from the ground up to solve these pain points.
-
-- 💰 **Zero-Cost, Transparent Licensing**: Uncapped usage, no per-server fees, and no commercial paywalls. 100% free and open-source under CPAL 1.0.
-- ⚡ **100% Client-Side WebAssembly**: Documents never leave the browser sandbox. Process, redact, and render PDFs entirely on the client—guaranteeing instant **HIPAA**, **GDPR**, and **FINRA** compliance.
-- 🔌 **Universal WebViewer API**: Clean, intuitive `WebViewer({...})` API interface that makes integrating into your web applications effortless.
-- 🎨 **Headless & Customizable**: Built for modern React 19 SPA lifecycles. No bloated iFrames to fight—customize toolbars, sidebars, context menus, and controls natively.
+## Features
+
+- **Viewing** — continuous or page-by-page scrolling, single / double / cover-facing layouts,
+  thumbnails panel, zoom 10 % – 6400 % with fit-to-width / fit-to-page, pinch and wheel zoom,
+  rotation, pan tool, high-DPI canvas rendering, progressive loading of linearized PDFs (HTTP Range).
+- **Text** — real selectable text layer, client-side search with highlighting and a results panel.
+- **Annotations** — highlighter, freehand ink, shapes (rectangle, ellipse, line, arrow), text,
+  sticky notes, callouts, hyperlinks (page-jump or URL), signature images, undo/redo, keyboard shortcuts.
+- **Redaction** — manual and regex/PII-driven redactions, burned in on export by rasterizing the
+  affected pages so the underlying content is destroyed; redacted text is also stripped from the
+  text layer and search index.
+- **Watermarks** — single or tiled forensic watermarks, rendered live and baked on export.
+- **Export** — download the annotated / redacted / watermarked document; no server round-trip.
+- **Embeddable** — `<TeamSyncViewer>` sizes to its container, several viewers can share a page,
+  keyboard shortcuts apply to the focused viewer only, and importing the package is side-effect free
+  (safe under SSR).
+
+- **Annotation API** — `instance.annotationManager`: undo/redo, granular `annotationChanged`
+  events, authorship + edit permissions, programmatic add/update/delete and **native XFDF**
+  import/export (Acrobat/Apryse-compatible; unknown markup is preserved as read-only pass-through).
+- **Print** — via the menu or `instance.print()`.
+
+Not yet supported: AcroForm filling, rendering of annotations already embedded in the PDF (only
+XFDF-imported ones), document outline/bookmarks, password prompts (password-protected files raise
+`onPasswordRequired`).
 
 ---
 
-## 📦 Installation via NPM
-
-Install the package into your React / TypeScript project:
+## Installation
 
 ```bash
-# Using npm
-npm install teamsync-pdf-viewer
-
-# Using yarn
-yarn add teamsync-pdf-viewer
-
-# Using pnpm
-pnpm add teamsync-pdf-viewer
+npm install teamsync-pdf-viewer pdfjs-dist
 ```
 
-### Installing from GitHub Packages (Alternative)
-
-If installing from GitHub Packages registry:
+`react`, `react-dom` (18 or 19) and `pdfjs-dist` (6.x) are **peer dependencies**. `pdf-lib` and
+`lucide-react` are installed automatically.
 
-1. Create or update your `.npmrc` file:
-   ```ini
-   @angelbot-ai:registry=https://npm.pkg.github.com
-   ```
-2. Install via npm:
-   ```bash
-   npm install teamsync-pdf-viewer
-   ```
-
----
+### Serve the pdf.js assets
 
-## 📖 Official Documentation & Wiki
+The library never bundles the pdf.js worker (bundling it produced a 5 MB package with a `data:`
+URL worker that strict Content-Security-Policies reject). Serve the worker — and, for full font /
+CJK / JPEG 2000 support, the CMaps, standard fonts and wasm decoders — from your own origin and tell
+the viewer where they are.
 
-Explore detailed SDK guides, parameter options, code snippets, and architecture deep dives:
-
-- 🏠 **[Wiki Home](docs/wiki/Home.md)**: Main documentation index & overview.
-- 🚀 **[Getting Started Guide](docs/wiki/Getting-Started.md)**: Installation, CDN, and framework setups.
-- ⚙️ **[API Reference & Options](docs/wiki/API-Reference-&-Options.md)**: Complete parameter list for `WebViewerOptions` & `SDKPermissions`.
-- 🎨 **[Annotations & Markup Guide](docs/wiki/Annotations-&-Markup-Guide.md)**: Freehand drawing, vector shapes, callouts & links.
-- 🛡️ **[Redactions & PII Sanitization Guide](docs/wiki/Redactions-&-PII-Sanitization.md)**: Binary redactions, regex PII scanning & discard options.
-- 💧 **[Forensic Watermarking Guide](docs/wiki/Forensic-Watermarking.md)**: Dynamic single and tiled watermark setup.
-- 🔌 **[Plugin Architecture Guide](docs/wiki/Plugin-Architecture.md)**: Writing custom extension plugins.
-
----
+**Vite / Rollup**
 
-## ✨ Uncompromised Feature Set
+```ts
+import workerSrc from 'pdfjs-dist/build/pdf.worker.min.mjs?url';
+import { configurePdfAssets } from 'teamsync-pdf-viewer';
 
-Everything you need to build collaborative, secure document workflows.
+configurePdfAssets({ workerSrc });
+```
 
-### 🎨 Smart Markup & Annotations
-- **Full Drawing Toolkit**: Freehand ink (`brush`), highlighters, geometric shapes (rectangles, ellipses), arrows, and lines.
-- **Notes & Callouts**: Sticky notes, callout text boxes with directional arrows, and text annotations.
-- **Interactive Hyperlinks**: Create internal page-jump links (`#page=N`) or external web URL links directly on document selections.
+**Next.js (or any static host)** — copy the files at build time and reference them by URL:
 
-### 🛡️ Military-Grade Secure Redaction
-- **Binary-Level Data Obliteration**: We don't just place black boxes over text—redactions are permanently rasterized and burned into the underlying PDF vector structure.
-- **Text Layer Sanitization**: Redacted text is automatically stripped from the DOM `textLayer` and PDF content streams, preventing copy/paste extraction and search indexing.
-- **Automatic Regex Redactions**: Programmatically locate and redact sensitive PII (Aadhaar numbers, SSNs, credit cards, dates of birth) in a single click.
-- **Discard Unapplied Redactions**: Easily discard individual pending redactions or bulk-discard all unapplied redaction marks before committing.
+```bash
+# e.g. in a prebuild script
+cp node_modules/pdfjs-dist/build/pdf.worker.min.mjs public/pdfjs/
+cp -r node_modules/pdfjs-dist/cmaps node_modules/pdfjs-dist/standard_fonts node_modules/pdfjs-dist/wasm public/pdfjs/
+```
 
-### 🔍 High-DPI Canvas Rendering & Search
-- **Retina 60 FPS Zoom & Pan**: High-DPI `devicePixelRatio` scaling eliminates blurred text. Micro-debounced rendering enables buttery-smooth 60 FPS trackpad pinching and 360° mouse drag panning.
-- **Contextual Document Search**: Instant client-side text search with real-time match highlighting, result jumping, and match counting.
+```ts
+configurePdfAssets({
+  workerSrc: '/pdfjs/pdf.worker.min.mjs',
+  cMapUrl: '/pdfjs/cmaps/',
+  standardFontDataUrl: '/pdfjs/standard_fonts/',
+  wasmUrl: '/pdfjs/wasm/',
+});
+```
 
-### 💧 Dynamic Forensic Watermarking
-- Programmatic, non-destructive watermarks rendered on the fly (single centered or full-page tiled) with customizable text, color, opacity, font size, and rotation.
+The worker **must** come from the same `pdfjs-dist` version the viewer runs against
+(`import { pdfjsVersion } from 'teamsync-pdf-viewer'` tells you which one is loaded).
 
 ---
 
-## 💻 Developer SDK Usage
-
-### Standard WebViewer Initialization
-
-Drop the SDK into any container element with a single function call:
+## Usage
 
-```typescript
-import { WebViewer } from 'teamsync-pdf-viewer';
-import 'teamsync-pdf-viewer/style.css';
-
-WebViewer({
-  initialDoc: '/sample.pdf',
-  initialScale: 1.0, // 100% natural size
-  enableAnnotations: true,
-  permissions: {
-    canRedact: true,
-    canAddAnnotations: true
-  },
-  watermark: {
-    text: 'CONFIDENTIAL',
-    mode: 'single',
-    size: 48,
-    opacity: 0.1,
-    color: '#dc2626'
-  }
-}, document.getElementById('viewer-container')).then((instance) => {
-  console.log('TeamSync PDF Viewer is ready!', instance);
-  
-  // Export annotated PDF buffer
-  instance.Core.documentViewer.getDocument().getFileData().then((pdfBytes) => {
-    console.log('Exported PDF byte length:', pdfBytes.length);
-  });
-});
-```
-
-### Native React Component Usage
-
-For native React integration, use the `<DocumentViewer />` component:
+### React component
 
 ```tsx
-import { DocumentViewer } from 'teamsync-pdf-viewer';
+'use client'; // Next.js App Router: the viewer is client-only
+
+import { TeamSyncViewer, type WebViewerInstance } from 'teamsync-pdf-viewer';
 import 'teamsync-pdf-viewer/style.css';
 
-function App() {
+export function ContractViewer({ url }: { url: string }) {
   return (
-    <div style={{ width: '100vw', height: '100vh' }}>
-      <DocumentViewer
-        initialDoc="/contract.pdf"
-        scale={1.0}
-        enableAnnotations={true}
-        permissions={{ canRedact: true }}
+    <div style={{ height: '80vh' }}>
+      <TeamSyncViewer
+        fileUrl={url}
+        fileName="contract.pdf"
+        assets={{ workerSrc: '/pdfjs/pdf.worker.min.mjs', cMapUrl: '/pdfjs/cmaps/' }}
+        currentUser={{ id: 'u-42', name: 'Jane Doe' }}
+        initialScale="fit-width"
+        watermark={{ text: 'CONFIDENTIAL', mode: 'tiled', opacity: 0.08 }}
+        onReady={(instance: WebViewerInstance) => console.log('ready', instance)}
+        onDocumentLoadError={(error, retry) => {
+          // e.g. mint a fresh presigned URL and retry
+          retry(/* newUrl */);
+        }}
       />
     </div>
   );
 }
 ```
 
----
-
-## 🛠️ Local Development Quick Start
+In Next.js, load it with `next/dynamic(() => import('./ContractViewer'), { ssr: false })` or keep
+it inside a client component — the package itself never touches `window` at import time.
 
-### 1. Clone & Install
+### Imperative API
 
-```bash
-git clone https://github.com/angelbot-ai/TeamSync-PDF-Viewer.git
-cd TeamSync-PDF-Viewer
-npm install
-```
+```ts
+import { createWebViewer } from 'teamsync-pdf-viewer';
+import 'teamsync-pdf-viewer/style.css';
 
-### 2. Launch Dev Server
+const instance = await createWebViewer(
+  { initialDoc: '/sample.pdf', fileName: 'sample.pdf', permissions: { canRedact: true } },
+  document.getElementById('viewer-container')!
+);
 
-```bash
-npm run dev
+instance.on('documentLoaded', ({ numPages }) => console.log(numPages, 'pages'));
+const pdfBytes = await instance.getFileData(); // annotated / redacted / watermarked Uint8Array
+instance.destroy(); // unmounts and releases every listener
 ```
 
-Open `http://localhost:5173` in your browser to launch the live SDK viewer.
+`WebViewer()` remains available as a deprecated alias of `createWebViewer()`.
 
 ---
 
-## 🔌 Extensible Plugin Architecture
+## API overview
+
+### `<TeamSyncViewer>` props / `WebViewerOptions`
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `fileUrl` (`initialDoc`) | `string` | — | URL of the PDF. Fetched by pdf.js (CORS + Range supported). |
+| `fileName` | `string` | `annotated_document.pdf` | Name used for downloads. |
+| `assets` | `PdfAssetPaths` | — | Worker / CMap / font / wasm locations (or call `configurePdfAssets`). |
+| `withCredentials` | `boolean` | `false` | Send cookies with the document request. |
+| `initialScale` | `number \| 'fit-width' \| 'fit-page'` | `1` | Initial zoom. |
+| `initialPage` | `number` | `1` | 1-based page to open. |
+| `readOnly` | `boolean` | `false` | Disables all annotation / redaction editing. |
+| `permissions` | `SDKPermissions` | all `true` | `canAddAnnotations`, `canEditAnnotations`, `canDeleteAnnotations`, `canRedact`. |
+| `currentUser` | `{ id, name }` | — | Author of annotations created in this viewer. |
+| `watermark` | `WatermarkOptions` | — | `{ text, mode: 'single' \| 'tiled', size, opacity, color }`. |
+| `redactions`, `regexRedactions` | `Redaction[]`, `RegExp[]` | `[]` | Pre-set and pattern-driven redactions. |
+| `toolbar`, `sidebars`, `leftPanelOpen` | `boolean` | `true` | Chrome toggles. |
+| `autoFocus` | `boolean` | `false` | Focus the viewer on mount (keyboard shortcuts). |
+| `plugins` | `ViewerPlugin[]` | `[]` | Extension plugins. |
+
+`permissions.canEditOthers` (default `false`) lets a user edit or delete annotations authored by
+someone else; annotations carry `author`/`authorId` from `currentUser`.
+
+Callbacks: `onReady(instance)`, `onDocumentLoaded({ url, numPages })`,
+`onDocumentLoadError(error, retry(newUrl?), { url, passwordRequired })`, `onFirstPageRendered`,
+`onPasswordRequired`, `onPageChange(page, numPages)`, `onAnnotationsChange(annotations)`.
+
+### `WebViewerInstance`
+
+- `on(type, listener)` / `off` — typed events: `documentLoaded`, `documentLoadError`,
+  `firstPageRendered`, `pageChanged`, `annotationsChanged`, `toolChanged`, `destroy`.
+- `loadDocument(url)` — load or reload (resolves on load, rejects on error).
+- `getFileData({ explicitAnnotations? })` — export the document as `Uint8Array`.
+- `getAnnotations()`, `getCurrentPage()`, `getPageCount()`, `getPdfDocument()`, `print()`.
+- `annotationManager` — `getAnnotationsList()`, `getAnnotationById(id)`, `addAnnotations(list)`,
+  `updateAnnotation(id, patch)`, `deleteAnnotations(ids, { force })`, `undo()`/`redo()`,
+  `importAnnotations(xfdf)`, `exportAnnotations({ annotList?, useDisplayAuthor? })`,
+  `setCurrentUser(name, id?)`, `setReadOnly(bool)`, `canEdit(annotation)`,
+  `addEventListener('annotationChanged', ({ annotations, action, imported }) => …)`.
+- `destroy()` — unmount (imperative API) and release every listener.
+- `UI.*` / `Core.*` — legacy facades (`UI.openElements`, `UI.fitWidth`,
+  `Core.annotationManager.exportAnnotations()`, `Core.documentViewer.getDocument().getFileData()`).
+
+Full reference: [docs/wiki/API-Reference-&-Options.md](docs/wiki/API-Reference-&-Options.md).
 
-TeamSync PDF Viewer features a decoupled **Plugin Architecture**. Core PDF rendering, smart annotations, redaction engines, and search remain lightweight and modular in the main engine, while enterprise extensions plug in as independent modules.
+---
 
-```
-┌─────────────────────────────────────────────────────────┐
-│              TeamSync PDF Viewer Core                   │
-│   (Page Rendering, Annotations, Redactions, Search)     │
-└───────────────────────────┬─────────────────────────────┘
-                            │ Plugins Registry API
-┌───────────────────────────▼─────────────────────────────┐
-│                   Custom Extension                      │
-│      (Custom Modals, Action Buttons, Export Hooks)      │
-└─────────────────────────────────────────────────────────┘
-```
+## Documentation
+
+- [Getting Started](docs/wiki/Getting-Started.md) · [API Reference & Options](docs/wiki/API-Reference-&-Options.md)
+- [Annotations & Markup](docs/wiki/Annotations-&-Markup-Guide.md) · [Redactions & PII Sanitization](docs/wiki/Redactions-&-PII-Sanitization.md)
+- [Forensic Watermarking](docs/wiki/Forensic-Watermarking.md) · [Plugin Architecture](docs/wiki/Plugin-Architecture.md)
+- [Changelog](CHANGELOG.md)
 
 ---
 
-## 🏛️ Architecture & Tech Stack
+## Development
+
+```bash
+git clone https://github.com/angelbot-ai/TeamSync-PDF-Viewer.git
+cd TeamSync-PDF-Viewer
+npm install
+npm run dev          # demo application at http://localhost:5173
+npm test             # unit tests (vitest)
+npm run build        # library -> dist/
+npm run verify:package   # publint + arethetypeswrong + artifact guards
+npm run build:app    # demo / iframe package build (Vercel)
+```
 
-- **Core Engine**: HTML5, TypeScript, WebAssembly (PDF.js + pdf-lib)
-- **UI & State**: React 19, Lucide Icons, Pure CSS Modules
-- **Build System**: Vite 8 & Oxlint (Sub-500ms tree-shakable builds)
+Layout:
 
 ```
-TeamSync-PDF-Viewer/
-├── src/
-│   ├── components/       # Native React UI (Header, DocumentViewer, Sidebars, Modals)
-│   ├── hooks/            # Search & Keyboard shortcut hooks
-│   ├── utils/            # Redaction algorithms & vector helpers
-│   ├── plugins/          # Plugin API interfaces & registry
-│   ├── index.ts          # Main SDK package exports
-│   ├── main.tsx          # WebViewer SDK entry point & public API bridge
-│   └── App.tsx           # Demo Application Shell
-├── public/               # Static PDF assets & PDF.js workers
-└── docs/images/          # High-res UI documentation screenshots
+src/
+├── index.ts              # public entry (side-effect free)
+├── core/                 # createWebViewer, WebViewerInstance, event bus, pdf.js assets, export
+├── components/           # TeamSyncViewer + internal UI (DocumentViewer, Header, sidebars, modals)
+├── annotations/          # annotation data model
+├── hooks/, utils/        # search, shortcuts, rotation helpers, regex redaction
+├── plugins/              # plugin interfaces
+└── demo/                 # demo & iframe-package bootstrap (not published)
 ```
 
----
+### Releasing
+
+1. Bump `version` in `package.json` + add a `CHANGELOG.md` entry, merge to `main`.
+2. Either push a tag `vX.Y.Z` on that commit, or run the **Publish to npm** workflow manually
+   with the ref to publish. The workflow re-runs the full verification chain, checks the version
+   is not already on the registry, and publishes with provenance (needs the `NPM_TOKEN` secret).
 
-## 📄 License
+### Iframe package (script-tag hosts)
 
-Distributed under the **CPAL 1.0 (Common Public Attribution License)**.  
-100% Free and Open Source for personal and commercial usage.
+`npm run build:app` produces a self-contained viewer; `public/webviewer.js` wraps it in an iframe
+with a `postMessage` bridge and exposes a `WebViewer(options, element)` function for non-React hosts.
 
 ---
-<div align="center">
-  <b>AngelBot AI • TeamSync • </b> <a href="https://www.teamsync.com" target="_blank" rel="noopener noreferrer">https://www.teamsync.com</a>
-</div>
 
-<div align="center">
-  <b>TeamSync PDF Viewer Engine</b> • Engineered with ❤️ for the Open Web.
-</div>
+## TypeScript notes
+
+Declarations ship in `dist/src/`. They resolve under `moduleResolution: "bundler"` (Next.js, Vite,
+webpack) and `node10`; `node16`/`nodenext` resolution is not supported yet because the emitted
+declarations use extension-less relative imports.
+
+## License
+
+[CPAL-1.0](LICENSE) — Copyright © 2026 AngelBot Ai Pvt Ltd.