stimulus-pdf-viewer-rails 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 863e0c885d62300048eda7098bb47e91082b609197aa5712557f9e76c1a33cd2
-  data.tar.gz: c99cdaa21cd6318fdec59037bd07ec86d1aed8260f45bd17852c90305e903f77
+  metadata.gz: 838e9d480a11d8bbf5a590bad2ab618624c1ec95284a1b7aa28b2c40468447ab
+  data.tar.gz: 7296bfffca896a43fb16a50a3d271a790eab5541d3744aef8df90ae336e2767a
 SHA512:
-  metadata.gz: 0a203691d3cc984e25cae915193472832086a52671137d9ccedf12dd8712033a99d3505c4cb664c5f5eb76943591bbb6f868703fbdf7b75ae3de5acd5957244d
-  data.tar.gz: 0bf609b800a496af6828e6382608214a75d6c7d2c583c3a34773797236fe73a7d66073369f28891908477fd6b02c40a19a7765b22d72f47f0d5baf1106087527
+  metadata.gz: 32804a93259414ccee6b961564c6587204c6deadcbf5bf07de69d1872751eb125c89099ec5e69125934f7a4ca85974b9bdf5b2b620912725bccb599ce27e082e
+  data.tar.gz: '099ea9e6b131bfba5f48b4a63818c03841e05b5da782f51adca84418bc9ee3538b8cc47982e169e76386acaa7c125278bb3794f53ac15a021efd152c1bbf9c37'

data/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.5.0] - 2026-08-11
+
+### Added
+- Updated stimulus-pdf-viewer to 0.5.0
+
+Adds support for password-protected PDFs: the viewer prompts for the password
+(with retry on incorrect entry) and opens encrypted documents in read-only
+mode — annotation tools are disabled and the download button delivers the
+original file. The vendored stylesheet includes new rules for the password
+prompt and read-only mode, so recompile your assets after upgrading. See the
+upstream
+[0.5.0 changelog](https://github.com/jhubert/stimulus-pdf-viewer/blob/main/CHANGELOG.md)
+for full details.
+
+## [0.4.1] - 2026-08-10
+
+### Fixed
+- Updated stimulus-pdf-viewer to 0.4.1
+
+This fixes `initialAnnotation` deep-links, which never scrolled to or selected
+the annotation (a string/number id mismatch in the annotation map lookup), and
+gives deep-linked annotations the same flash/highlight treatment as sidebar
+clicks. See the upstream
+[0.4.1 changelog](https://github.com/jhubert/stimulus-pdf-viewer/blob/main/CHANGELOG.md)
+for full details.
+
 ## [0.4.0] - 2026-06-24
 
 ### Added

data/app/assets/javascripts/stimulus-pdf-viewer.esm.js

@@ -369,11 +369,21 @@ class CoreViewer {
     this.container = container;
     this.eventBus = options.eventBus || new EventBus();
 
+    // Called when the document needs a password: ({ retry }) => Promise<string>.
+    // Resolve with the password, reject to abort the load. When absent,
+    // password-protected documents fail to load with a PasswordException.
+    this.onPasswordRequest = options.onPasswordRequest || null;
+
     // PDF.js document reference
     this.pdfDocument = null;
     this._loadingTask = null;
     this.pageCount = 0;
 
+    // Whether the loaded document is encrypted (user- or owner-password).
+    // Valid after load() resolves.
+    this.isEncrypted = false;
+    this._lastPassword = null;
+
     // Page data storage: pageNumber -> PageData
     this.pages = new Map();
 
@@ -434,6 +444,8 @@ class CoreViewer {
    * @returns {Promise<PDFDocumentProxy>}
    */
   async load(url) {
+    this._lastPassword = null;
+    this.isEncrypted = false;
     try {
       return await this._loadDocument(url)
     } catch (error) {
@@ -445,7 +457,10 @@ class CoreViewer {
             throw new Error(`HTTP ${response.status} fetching PDF`)
           }
           const data = new Uint8Array(await response.arrayBuffer());
-          return await this._loadDocument({ data })
+          // Reuse a password entered during the streamed attempt so the
+          // fallback doesn't prompt the user a second time
+          const source = this._lastPassword ? { data, password: this._lastPassword } : { data };
+          return await this._loadDocument(source)
         } catch (retryError) {
           console.error("PDF blob fallback also failed:", retryError);
           this.eventBus.dispatch(ViewerEvents.DOCUMENT_LOAD_ERROR, { error: retryError });
@@ -471,9 +486,32 @@ class CoreViewer {
     await this._teardownDocument();
 
     this._loadingTask = pdfjsLib.getDocument(source);
+
+    // Prompt for a password instead of failing with PasswordException. PDF.js
+    // calls onPassword again with INCORRECT_PASSWORD after a wrong attempt;
+    // passing an Error to updatePassword aborts the load.
+    if (this.onPasswordRequest) {
+      this._loadingTask.onPassword = (updatePassword, reason) => {
+        const retry = reason === pdfjsLib.PasswordResponses.INCORRECT_PASSWORD;
+        Promise.resolve(this.onPasswordRequest({ retry }))
+          .then(password => {
+            this._lastPassword = password;
+            updatePassword(password);
+          })
+          .catch(error => {
+            updatePassword(error instanceof Error ? error : new Error("Password entry cancelled"));
+          });
+      };
+    }
+
     this.pdfDocument = await this._loadingTask.promise;
     this.pageCount = this.pdfDocument.numPages;
 
+    // getPermissions() returns null for unencrypted documents. Any encryption
+    // (user- or owner-password) makes the document read-only downstream:
+    // pdf-lib can't open encrypted files to embed annotations on download.
+    this.isEncrypted = (await this.pdfDocument.getPermissions()) !== null;
+
     // Set initial display scale on container
     this.container.style.setProperty("--display-scale", String(this.displayScale));
 
@@ -1729,7 +1767,7 @@ class AnnotationManager {
     this.annotationsByPage.clear();
 
     for (const annotation of annotationsData) {
-      this.annotations.set(annotation.id, annotation);
+      this.annotations.set(this._key(annotation.id), annotation);
 
       if (!this.annotationsByPage.has(annotation.page)) {
         this.annotationsByPage.set(annotation.page, []);
@@ -1738,8 +1776,14 @@ class AnnotationManager {
     }
   }
 
+  // Ids arrive as numbers from JSON payloads but as strings from DOM
+  // datasets and Stimulus values, so the map is keyed by string
+  _key(id) {
+    return String(id)
+  }
+
   getAnnotation(id) {
-    return this.annotations.get(id)
+    return this.annotations.get(this._key(id))
   }
 
   getAnnotationsForPage(pageNumber) {
@@ -1785,7 +1829,7 @@ class AnnotationManager {
   }
 
   async deleteAnnotation(id) {
-    const existingAnnotation = this.annotations.get(id);
+    const existingAnnotation = this.getAnnotation(id);
     if (!existingAnnotation) return
 
     try {
@@ -1824,7 +1868,7 @@ class AnnotationManager {
   }
 
   _addAnnotation(annotation) {
-    this.annotations.set(annotation.id, annotation);
+    this.annotations.set(this._key(annotation.id), annotation);
 
     if (!this.annotationsByPage.has(annotation.page)) {
       this.annotationsByPage.set(annotation.page, []);
@@ -1833,7 +1877,7 @@ class AnnotationManager {
   }
 
   _updateAnnotation(annotation) {
-    const oldAnnotation = this.annotations.get(annotation.id);
+    const oldAnnotation = this.getAnnotation(annotation.id);
     if (!oldAnnotation) {
       this._addAnnotation(annotation);
       return
@@ -1850,27 +1894,27 @@ class AnnotationManager {
     } else {
       // Update in place
       const pageAnnotations = this.annotationsByPage.get(annotation.page);
-      const index = pageAnnotations.findIndex(a => a.id === annotation.id);
+      const index = pageAnnotations.findIndex(a => this._key(a.id) === this._key(annotation.id));
       if (index !== -1) {
         pageAnnotations[index] = annotation;
       }
     }
 
-    this.annotations.set(annotation.id, annotation);
+    this.annotations.set(this._key(annotation.id), annotation);
   }
 
   _removeAnnotation(id) {
-    const annotation = this.annotations.get(id);
+    const annotation = this.getAnnotation(id);
     if (!annotation) return
 
     this._removeAnnotationFromPage(id, annotation.page);
-    this.annotations.delete(id);
+    this.annotations.delete(this._key(id));
   }
 
   _removeAnnotationFromPage(id, pageNumber) {
     const pageAnnotations = this.annotationsByPage.get(pageNumber);
     if (pageAnnotations) {
-      const index = pageAnnotations.findIndex(a => a.id === id);
+      const index = pageAnnotations.findIndex(a => this._key(a.id) === this._key(id));
       if (index !== -1) {
         pageAnnotations.splice(index, 1);
       }
@@ -1982,6 +2026,16 @@ class DownloadManager {
     this._triggerDownload(pdfBytes, filename);
   }
 
+  // Download the original file untouched. Used for encrypted documents, which
+  // pdf-lib can't open to embed annotations or the watermark.
+  async downloadOriginal() {
+    const request = new FetchRequest("get", this.documentUrl, { responseKind: "blob" });
+    const response = await request.perform();
+    const pdfBytes = await response.response.arrayBuffer();
+    const filename = this._sanitizeFilename(this.documentName || "document");
+    this._triggerDownload(pdfBytes, filename);
+  }
+
   _applyWatermarkToPage(page, font, width, height) {
     if (!this.userName) return
 
@@ -4363,7 +4417,7 @@ class AnnotationSidebar {
     }
 
     // Selection state
-    if (this.selectedAnnotationId === annotation.id) {
+    if (this.selectedAnnotationId === String(annotation.id)) {
       item.classList.add("selected");
     }
 
@@ -4471,6 +4525,9 @@ class AnnotationSidebar {
   }
 
   _selectItem(annotationId) {
+    // Ids arrive as numbers from JSON payloads but as strings from DOM
+    // datasets and deep-links, so selection state is tracked as string
+    annotationId = String(annotationId);
     const previousId = this.selectedAnnotationId;
 
     // Skip if already selected
@@ -4527,7 +4584,7 @@ class AnnotationSidebar {
   onAnnotationDeleted(annotation) {
     if (this.isOpen) {
       // Clear selection if deleted annotation was selected
-      if (this.selectedAnnotationId === annotation.id) {
+      if (this.selectedAnnotationId === String(annotation.id)) {
         const previousId = this.selectedAnnotationId;
         this.selectedAnnotationId = null;
         this.element.dispatchEvent(new CustomEvent("pdf-sidebar:annotation-deselected", {
@@ -5599,6 +5656,122 @@ class FindBar {
   }
 }
 
+/**
+ * PasswordPrompt - Modal dialog for unlocking password-protected PDFs.
+ *
+ * Shown over the viewer when PDF.js requests a password during document
+ * load. Each request() call returns a promise that resolves with the
+ * entered password, or rejects when the user cancels.
+ */
+
+class PasswordPrompt {
+  constructor(options = {}) {
+    this.container = options.container;
+
+    this.element = null;
+    this.inputElement = null;
+    this.errorElement = null;
+
+    this._pending = null; // { resolve, reject } for the in-flight request
+
+    this._createUI();
+    this._setupEventListeners();
+  }
+
+  _createUI() {
+    this.element = document.createElement("div");
+    this.element.className = "pdf-password-prompt hidden";
+    this.element.innerHTML = `
+      <div class="pdf-password-prompt-dialog" role="dialog" aria-modal="true" aria-labelledby="pdf-password-prompt-title">
+        <h2 class="pdf-password-prompt-title" id="pdf-password-prompt-title">Password required</h2>
+        <p class="pdf-password-prompt-message">This document is protected. Enter the password to open it.</p>
+        <p class="pdf-password-prompt-error hidden">Incorrect password. Please try again.</p>
+        <input type="password" class="pdf-password-prompt-input" autocomplete="off" aria-label="Document password">
+        <div class="pdf-password-prompt-buttons">
+          <button type="button" class="pdf-password-prompt-btn pdf-password-prompt-cancel">Cancel</button>
+          <button type="button" class="pdf-password-prompt-btn pdf-password-prompt-submit">Open</button>
+        </div>
+      </div>
+    `;
+
+    this.inputElement = this.element.querySelector(".pdf-password-prompt-input");
+    this.errorElement = this.element.querySelector(".pdf-password-prompt-error");
+    this.submitButton = this.element.querySelector(".pdf-password-prompt-submit");
+    this.cancelButton = this.element.querySelector(".pdf-password-prompt-cancel");
+
+    this.container.appendChild(this.element);
+  }
+
+  _setupEventListeners() {
+    this.submitButton.addEventListener("click", () => this._submit());
+    this.cancelButton.addEventListener("click", () => this._cancel());
+
+    this.element.addEventListener("keydown", (e) => {
+      if (e.key === "Enter") {
+        e.preventDefault();
+        this._submit();
+      } else if (e.key === "Escape") {
+        e.preventDefault();
+        this._cancel();
+      }
+    });
+  }
+
+  /**
+   * Ask the user for the document password.
+   * @param {Object} options
+   * @param {boolean} options.retry - Whether a previous attempt was incorrect
+   * @returns {Promise<string>} Resolves with the password, rejects on cancel
+   */
+  request({ retry = false } = {}) {
+    return new Promise((resolve, reject) => {
+      // A request should never overlap another, but if it does, cancel the old one
+      this._pending?.reject(new Error("Password entry cancelled"));
+      this._pending = { resolve, reject };
+
+      this.errorElement.classList.toggle("hidden", !retry);
+      this.inputElement.value = "";
+      this.element.classList.remove("hidden");
+      this.inputElement.focus({ preventScroll: true });
+    })
+  }
+
+  _submit() {
+    const password = this.inputElement.value;
+    if (!password) {
+      this.inputElement.focus({ preventScroll: true });
+      return
+    }
+
+    const pending = this._pending;
+    this._pending = null;
+    this._hide();
+    pending?.resolve(password);
+  }
+
+  _cancel() {
+    const pending = this._pending;
+    this._pending = null;
+    this._hide();
+    pending?.reject(new Error("Password entry cancelled"));
+  }
+
+  _hide() {
+    this.element.classList.add("hidden");
+    this.inputElement.value = "";
+  }
+
+  /**
+   * Clean up. Safe to call multiple times.
+   */
+  destroy() {
+    this._pending?.reject(new Error("Password entry cancelled"));
+    this._pending = null;
+    this.element?.remove();
+    this.element = null;
+  }
+}
+
 class BaseTool {
   constructor(pdfViewer) {
     this.pdfViewer = pdfViewer;
@@ -7224,6 +7397,9 @@ class PdfViewer {
 
     this.currentTool = null;
     this.currentMode = ToolMode.SELECT;
+    // True once an encrypted document is loaded: annotations and annotated
+    // download are disabled (pdf-lib can't open encrypted files)
+    this.readOnly = false;
     this.selectedAnnotation = null;
     this.selectedAnnotationElement = null;
     this.pendingAnnotationSelection = null; // Annotation ID to select when rendered
@@ -7265,9 +7441,13 @@ class PdfViewer {
       return
     }
 
+    // Modal shown when a document needs a password to open
+    this.passwordPrompt = new PasswordPrompt({ container: this.container });
+
     // Core viewer (PDF.js wrapper with lazy rendering and events)
     this.viewer = new CoreViewer(this.pagesContainer, {
-      initialScale: 1.0
+      initialScale: 1.0,
+      onPasswordRequest: ({ retry }) => this.passwordPrompt.request({ retry })
     });
 
     // Subscribe to core viewer events
@@ -7411,9 +7591,11 @@ class PdfViewer {
    */
   _onDocumentLoaded(pageCount) {
     this._currentPage = 1;
+    this.readOnly = this.viewer.isEncrypted;
     this._dispatchEvent("pdf-viewer:ready", {
       pageCount,
-      currentPage: 1
+      currentPage: 1,
+      readOnly: this.readOnly
     });
   }
 
@@ -7510,11 +7692,12 @@ class PdfViewer {
         await this.thumbnailSidebar.setDocument(this.viewer.pdfDocument);
       }
 
-      // Load existing annotations from store
-      await this.annotationManager.loadAnnotations();
-
-      // Render annotations on all rendered pages
-      this._renderAnnotations();
+      // Load existing annotations from store and render them on all rendered
+      // pages. Skipped for encrypted documents, which are view-only.
+      if (!this.readOnly) {
+        await this.annotationManager.loadAnnotations();
+        this._renderAnnotations();
+      }
 
       const annotations = this.annotationManager.getAllAnnotations();
       this.container.dispatchEvent(new CustomEvent("pdf-viewer:annotations-loaded", {
@@ -7527,9 +7710,10 @@ class PdfViewer {
         this.viewer.goToPage(this.initialPage);
       }
 
-      // Navigate to initial annotation if specified
+      // Navigate to initial annotation if specified, flashing it so
+      // deep-link visitors can spot it immediately
       if (this.initialAnnotation) {
-        this._scrollToAnnotation(this.initialAnnotation);
+        this._scrollToAnnotationWithFlash(this.initialAnnotation);
       }
 
       // Start with select tool
@@ -7544,6 +7728,11 @@ class PdfViewer {
   }
 
   setTool(mode) {
+    // Encrypted documents are view-only: only the select tool is allowed
+    if (this.readOnly && mode !== ToolMode.SELECT) {
+      return
+    }
+
     // Deactivate current tool
     if (this.currentTool) {
       this.currentTool.deactivate();
@@ -8428,20 +8617,9 @@ class PdfViewer {
     }
   }
 
-  _scrollToAnnotation(annotationId) {
-    const annotation = this.annotationManager.getAnnotation(annotationId);
-    if (!annotation) return
-
-    // Mark this annotation for selection when it's rendered
-    this.pendingAnnotationSelection = annotationId;
-
-    // Go to the page - the annotation will be selected in _renderAnnotationsForPage
-    this.viewer.goToPage(annotation.page);
-  }
-
   /**
    * Scroll to annotation and flash/highlight it.
-   * Called from the annotation sidebar when clicking an annotation.
+   * Called from the annotation sidebar and for initial deep-links.
    */
   _scrollToAnnotationWithFlash(annotationId) {
     const annotation = this.annotationManager.getAnnotation(annotationId);
@@ -8557,10 +8735,15 @@ class PdfViewer {
     });
   }
 
-  // Download with annotations
+  // Download with annotations (or the original file for encrypted documents,
+  // which pdf-lib can't open to embed annotations)
   async download() {
     try {
-      await this.downloadManager.downloadWithAnnotations();
+      if (this.readOnly) {
+        await this.downloadManager.downloadOriginal();
+      } else {
+        await this.downloadManager.downloadWithAnnotations();
+      }
     } catch (error) {
       console.error("Failed to download PDF:", error);
       throw error
@@ -8589,6 +8772,7 @@ class PdfViewer {
     this.findController?.destroy();
     this.findBar?.destroy();
     this.colorPicker?.destroy();
+    this.passwordPrompt?.destroy();
 
     Object.values(this.tools || {}).forEach(tool => tool.destroy?.());
 
@@ -8658,7 +8842,9 @@ class pdf_viewer_controller extends Controller {
     if (this.hasLoadingOverlayTarget) {
       this.loadingOverlayTarget.classList.add("hidden");
     }
-    const message = this.errorMessageValue || "Failed to load PDF document";
+    const isPasswordError = /password/i.test(String(error?.message || "")) || /password/i.test(String(error?.name || ""));
+    const message = this.errorMessageValue ||
+      (isPasswordError ? "A password is required to open this document" : "Failed to load PDF document");
     this._showError(message);
     this.containerTarget.dispatchEvent(new CustomEvent("pdf-viewer:load-failed", {
       bubbles: true,
@@ -8839,6 +9025,10 @@ class pdf_viewer_controller extends Controller {
   }
 
   _activateTool(toolName) {
+    // View-only for encrypted documents; the buttons are disabled, but guard
+    // against keyboard/programmatic activation too
+    if (this._readOnly && toolName !== "select") return
+
     // Tool map for name -> mode conversion
     const toolMap = {
       select: ToolMode.SELECT,
@@ -9024,8 +9214,8 @@ class pdf_viewer_controller extends Controller {
   _setupPageNavigationListeners() {
     // Listen for ready event from PdfViewer
     this._readyHandler = (e) => {
-      const { pageCount, currentPage } = e.detail;
-      this._onViewerReady(pageCount, currentPage);
+      const { pageCount, currentPage, readOnly } = e.detail;
+      this._onViewerReady(pageCount, currentPage, readOnly);
     };
     this.containerTarget.addEventListener("pdf-viewer:ready", this._readyHandler);
 
@@ -9037,12 +9227,16 @@ class pdf_viewer_controller extends Controller {
     this.containerTarget.addEventListener("pdf-viewer:page-changed", this._pageChangedHandler);
   }
 
-  _onViewerReady(pageCount, currentPage) {
+  _onViewerReady(pageCount, currentPage, readOnly) {
     // Hide the loading overlay
     if (this.hasLoadingOverlayTarget) {
       this.loadingOverlayTarget.classList.add("hidden");
     }
 
+    if (readOnly) {
+      this._enterReadOnlyMode();
+    }
+
     if (this.hasPageCountTarget) {
       this.pageCountTarget.textContent = pageCount;
     }
@@ -9063,6 +9257,16 @@ class pdf_viewer_controller extends Controller {
     this._setZoomPreset("auto");
   }
 
+  // Encrypted documents are view-only: disable the annotation tools and hide
+  // the color picker. Download stays enabled but delivers the original file.
+  _enterReadOnlyMode() {
+    this._readOnly = true;
+    this.containerTarget.classList.add("pdf-viewer-read-only");
+    this.containerTarget
+      .querySelectorAll('.pdf-tool-btn[data-tool]:not([data-tool="select"]), .pdf-overflow-tool-btn[data-tool]:not([data-tool="select"])')
+      .forEach(btn => { btn.disabled = true; });
+  }
+
   _onPageChanged(currentPage, pageCount) {
     if (this.hasPageInputTarget && document.activeElement !== this.pageInputTarget) {
       this.pageInputTarget.value = currentPage;

data/app/assets/javascripts/stimulus-pdf-viewer.js

@@ -389,11 +389,21 @@
       this.container = container;
       this.eventBus = options.eventBus || new EventBus();
 
+      // Called when the document needs a password: ({ retry }) => Promise<string>.
+      // Resolve with the password, reject to abort the load. When absent,
+      // password-protected documents fail to load with a PasswordException.
+      this.onPasswordRequest = options.onPasswordRequest || null;
+
       // PDF.js document reference
       this.pdfDocument = null;
       this._loadingTask = null;
       this.pageCount = 0;
 
+      // Whether the loaded document is encrypted (user- or owner-password).
+      // Valid after load() resolves.
+      this.isEncrypted = false;
+      this._lastPassword = null;
+
       // Page data storage: pageNumber -> PageData
       this.pages = new Map();
 
@@ -454,6 +464,8 @@
      * @returns {Promise<PDFDocumentProxy>}
      */
     async load(url) {
+      this._lastPassword = null;
+      this.isEncrypted = false;
       try {
         return await this._loadDocument(url)
       } catch (error) {
@@ -465,7 +477,10 @@
               throw new Error(`HTTP ${response.status} fetching PDF`)
             }
             const data = new Uint8Array(await response.arrayBuffer());
-            return await this._loadDocument({ data })
+            // Reuse a password entered during the streamed attempt so the
+            // fallback doesn't prompt the user a second time
+            const source = this._lastPassword ? { data, password: this._lastPassword } : { data };
+            return await this._loadDocument(source)
           } catch (retryError) {
             console.error("PDF blob fallback also failed:", retryError);
             this.eventBus.dispatch(ViewerEvents.DOCUMENT_LOAD_ERROR, { error: retryError });
@@ -491,9 +506,32 @@
       await this._teardownDocument();
 
       this._loadingTask = pdfjsLib__namespace.getDocument(source);
+
+      // Prompt for a password instead of failing with PasswordException. PDF.js
+      // calls onPassword again with INCORRECT_PASSWORD after a wrong attempt;
+      // passing an Error to updatePassword aborts the load.
+      if (this.onPasswordRequest) {
+        this._loadingTask.onPassword = (updatePassword, reason) => {
+          const retry = reason === pdfjsLib__namespace.PasswordResponses.INCORRECT_PASSWORD;
+          Promise.resolve(this.onPasswordRequest({ retry }))
+            .then(password => {
+              this._lastPassword = password;
+              updatePassword(password);
+            })
+            .catch(error => {
+              updatePassword(error instanceof Error ? error : new Error("Password entry cancelled"));
+            });
+        };
+      }
+
       this.pdfDocument = await this._loadingTask.promise;
       this.pageCount = this.pdfDocument.numPages;
 
+      // getPermissions() returns null for unencrypted documents. Any encryption
+      // (user- or owner-password) makes the document read-only downstream:
+      // pdf-lib can't open encrypted files to embed annotations on download.
+      this.isEncrypted = (await this.pdfDocument.getPermissions()) !== null;
+
       // Set initial display scale on container
       this.container.style.setProperty("--display-scale", String(this.displayScale));
 
@@ -1749,7 +1787,7 @@
       this.annotationsByPage.clear();
 
       for (const annotation of annotationsData) {
-        this.annotations.set(annotation.id, annotation);
+        this.annotations.set(this._key(annotation.id), annotation);
 
         if (!this.annotationsByPage.has(annotation.page)) {
           this.annotationsByPage.set(annotation.page, []);
@@ -1758,8 +1796,14 @@
       }
     }
 
+    // Ids arrive as numbers from JSON payloads but as strings from DOM
+    // datasets and Stimulus values, so the map is keyed by string
+    _key(id) {
+      return String(id)
+    }
+
     getAnnotation(id) {
-      return this.annotations.get(id)
+      return this.annotations.get(this._key(id))
     }
 
     getAnnotationsForPage(pageNumber) {
@@ -1805,7 +1849,7 @@
     }
 
     async deleteAnnotation(id) {
-      const existingAnnotation = this.annotations.get(id);
+      const existingAnnotation = this.getAnnotation(id);
       if (!existingAnnotation) return
 
       try {
@@ -1844,7 +1888,7 @@
     }
 
     _addAnnotation(annotation) {
-      this.annotations.set(annotation.id, annotation);
+      this.annotations.set(this._key(annotation.id), annotation);
 
       if (!this.annotationsByPage.has(annotation.page)) {
         this.annotationsByPage.set(annotation.page, []);
@@ -1853,7 +1897,7 @@
     }
 
     _updateAnnotation(annotation) {
-      const oldAnnotation = this.annotations.get(annotation.id);
+      const oldAnnotation = this.getAnnotation(annotation.id);
       if (!oldAnnotation) {
         this._addAnnotation(annotation);
         return
@@ -1870,27 +1914,27 @@
       } else {
         // Update in place
         const pageAnnotations = this.annotationsByPage.get(annotation.page);
-        const index = pageAnnotations.findIndex(a => a.id === annotation.id);
+        const index = pageAnnotations.findIndex(a => this._key(a.id) === this._key(annotation.id));
         if (index !== -1) {
           pageAnnotations[index] = annotation;
         }
       }
 
-      this.annotations.set(annotation.id, annotation);
+      this.annotations.set(this._key(annotation.id), annotation);
     }
 
     _removeAnnotation(id) {
-      const annotation = this.annotations.get(id);
+      const annotation = this.getAnnotation(id);
       if (!annotation) return
 
       this._removeAnnotationFromPage(id, annotation.page);
-      this.annotations.delete(id);
+      this.annotations.delete(this._key(id));
     }
 
     _removeAnnotationFromPage(id, pageNumber) {
       const pageAnnotations = this.annotationsByPage.get(pageNumber);
       if (pageAnnotations) {
-        const index = pageAnnotations.findIndex(a => a.id === id);
+        const index = pageAnnotations.findIndex(a => this._key(a.id) === this._key(id));
         if (index !== -1) {
           pageAnnotations.splice(index, 1);
         }
@@ -2002,6 +2046,16 @@
       this._triggerDownload(pdfBytes, filename);
     }
 
+    // Download the original file untouched. Used for encrypted documents, which
+    // pdf-lib can't open to embed annotations or the watermark.
+    async downloadOriginal() {
+      const request = new request_js.FetchRequest("get", this.documentUrl, { responseKind: "blob" });
+      const response = await request.perform();
+      const pdfBytes = await response.response.arrayBuffer();
+      const filename = this._sanitizeFilename(this.documentName || "document");
+      this._triggerDownload(pdfBytes, filename);
+    }
+
     _applyWatermarkToPage(page, font, width, height) {
       if (!this.userName) return
 
@@ -4383,7 +4437,7 @@
       }
 
       // Selection state
-      if (this.selectedAnnotationId === annotation.id) {
+      if (this.selectedAnnotationId === String(annotation.id)) {
         item.classList.add("selected");
       }
 
@@ -4491,6 +4545,9 @@
     }
 
     _selectItem(annotationId) {
+      // Ids arrive as numbers from JSON payloads but as strings from DOM
+      // datasets and deep-links, so selection state is tracked as string
+      annotationId = String(annotationId);
       const previousId = this.selectedAnnotationId;
 
       // Skip if already selected
@@ -4547,7 +4604,7 @@
     onAnnotationDeleted(annotation) {
       if (this.isOpen) {
         // Clear selection if deleted annotation was selected
-        if (this.selectedAnnotationId === annotation.id) {
+        if (this.selectedAnnotationId === String(annotation.id)) {
           const previousId = this.selectedAnnotationId;
           this.selectedAnnotationId = null;
           this.element.dispatchEvent(new CustomEvent("pdf-sidebar:annotation-deselected", {
@@ -5619,6 +5676,122 @@
     }
   }
 
+  /**
+   * PasswordPrompt - Modal dialog for unlocking password-protected PDFs.
+   *
+   * Shown over the viewer when PDF.js requests a password during document
+   * load. Each request() call returns a promise that resolves with the
+   * entered password, or rejects when the user cancels.
+   */
+
+  class PasswordPrompt {
+    constructor(options = {}) {
+      this.container = options.container;
+
+      this.element = null;
+      this.inputElement = null;
+      this.errorElement = null;
+
+      this._pending = null; // { resolve, reject } for the in-flight request
+
+      this._createUI();
+      this._setupEventListeners();
+    }
+
+    _createUI() {
+      this.element = document.createElement("div");
+      this.element.className = "pdf-password-prompt hidden";
+      this.element.innerHTML = `
+      <div class="pdf-password-prompt-dialog" role="dialog" aria-modal="true" aria-labelledby="pdf-password-prompt-title">
+        <h2 class="pdf-password-prompt-title" id="pdf-password-prompt-title">Password required</h2>
+        <p class="pdf-password-prompt-message">This document is protected. Enter the password to open it.</p>
+        <p class="pdf-password-prompt-error hidden">Incorrect password. Please try again.</p>
+        <input type="password" class="pdf-password-prompt-input" autocomplete="off" aria-label="Document password">
+        <div class="pdf-password-prompt-buttons">
+          <button type="button" class="pdf-password-prompt-btn pdf-password-prompt-cancel">Cancel</button>
+          <button type="button" class="pdf-password-prompt-btn pdf-password-prompt-submit">Open</button>
+        </div>
+      </div>
+    `;
+
+      this.inputElement = this.element.querySelector(".pdf-password-prompt-input");
+      this.errorElement = this.element.querySelector(".pdf-password-prompt-error");
+      this.submitButton = this.element.querySelector(".pdf-password-prompt-submit");
+      this.cancelButton = this.element.querySelector(".pdf-password-prompt-cancel");
+
+      this.container.appendChild(this.element);
+    }
+
+    _setupEventListeners() {
+      this.submitButton.addEventListener("click", () => this._submit());
+      this.cancelButton.addEventListener("click", () => this._cancel());
+
+      this.element.addEventListener("keydown", (e) => {
+        if (e.key === "Enter") {
+          e.preventDefault();
+          this._submit();
+        } else if (e.key === "Escape") {
+          e.preventDefault();
+          this._cancel();
+        }
+      });
+    }
+
+    /**
+     * Ask the user for the document password.
+     * @param {Object} options
+     * @param {boolean} options.retry - Whether a previous attempt was incorrect
+     * @returns {Promise<string>} Resolves with the password, rejects on cancel
+     */
+    request({ retry = false } = {}) {
+      return new Promise((resolve, reject) => {
+        // A request should never overlap another, but if it does, cancel the old one
+        this._pending?.reject(new Error("Password entry cancelled"));
+        this._pending = { resolve, reject };
+
+        this.errorElement.classList.toggle("hidden", !retry);
+        this.inputElement.value = "";
+        this.element.classList.remove("hidden");
+        this.inputElement.focus({ preventScroll: true });
+      })
+    }
+
+    _submit() {
+      const password = this.inputElement.value;
+      if (!password) {
+        this.inputElement.focus({ preventScroll: true });
+        return
+      }
+
+      const pending = this._pending;
+      this._pending = null;
+      this._hide();
+      pending?.resolve(password);
+    }
+
+    _cancel() {
+      const pending = this._pending;
+      this._pending = null;
+      this._hide();
+      pending?.reject(new Error("Password entry cancelled"));
+    }
+
+    _hide() {
+      this.element.classList.add("hidden");
+      this.inputElement.value = "";
+    }
+
+    /**
+     * Clean up. Safe to call multiple times.
+     */
+    destroy() {
+      this._pending?.reject(new Error("Password entry cancelled"));
+      this._pending = null;
+      this.element?.remove();
+      this.element = null;
+    }
+  }
+
   class BaseTool {
     constructor(pdfViewer) {
       this.pdfViewer = pdfViewer;
@@ -7244,6 +7417,9 @@
 
       this.currentTool = null;
       this.currentMode = ToolMode.SELECT;
+      // True once an encrypted document is loaded: annotations and annotated
+      // download are disabled (pdf-lib can't open encrypted files)
+      this.readOnly = false;
       this.selectedAnnotation = null;
       this.selectedAnnotationElement = null;
       this.pendingAnnotationSelection = null; // Annotation ID to select when rendered
@@ -7285,9 +7461,13 @@
         return
       }
 
+      // Modal shown when a document needs a password to open
+      this.passwordPrompt = new PasswordPrompt({ container: this.container });
+
       // Core viewer (PDF.js wrapper with lazy rendering and events)
       this.viewer = new CoreViewer(this.pagesContainer, {
-        initialScale: 1.0
+        initialScale: 1.0,
+        onPasswordRequest: ({ retry }) => this.passwordPrompt.request({ retry })
       });
 
       // Subscribe to core viewer events
@@ -7431,9 +7611,11 @@
      */
     _onDocumentLoaded(pageCount) {
       this._currentPage = 1;
+      this.readOnly = this.viewer.isEncrypted;
       this._dispatchEvent("pdf-viewer:ready", {
         pageCount,
-        currentPage: 1
+        currentPage: 1,
+        readOnly: this.readOnly
       });
     }
 
@@ -7530,11 +7712,12 @@
           await this.thumbnailSidebar.setDocument(this.viewer.pdfDocument);
         }
 
-        // Load existing annotations from store
-        await this.annotationManager.loadAnnotations();
-
-        // Render annotations on all rendered pages
-        this._renderAnnotations();
+        // Load existing annotations from store and render them on all rendered
+        // pages. Skipped for encrypted documents, which are view-only.
+        if (!this.readOnly) {
+          await this.annotationManager.loadAnnotations();
+          this._renderAnnotations();
+        }
 
         const annotations = this.annotationManager.getAllAnnotations();
         this.container.dispatchEvent(new CustomEvent("pdf-viewer:annotations-loaded", {
@@ -7547,9 +7730,10 @@
           this.viewer.goToPage(this.initialPage);
         }
 
-        // Navigate to initial annotation if specified
+        // Navigate to initial annotation if specified, flashing it so
+        // deep-link visitors can spot it immediately
         if (this.initialAnnotation) {
-          this._scrollToAnnotation(this.initialAnnotation);
+          this._scrollToAnnotationWithFlash(this.initialAnnotation);
         }
 
         // Start with select tool
@@ -7564,6 +7748,11 @@
     }
 
     setTool(mode) {
+      // Encrypted documents are view-only: only the select tool is allowed
+      if (this.readOnly && mode !== ToolMode.SELECT) {
+        return
+      }
+
       // Deactivate current tool
       if (this.currentTool) {
         this.currentTool.deactivate();
@@ -8448,20 +8637,9 @@
       }
     }
 
-    _scrollToAnnotation(annotationId) {
-      const annotation = this.annotationManager.getAnnotation(annotationId);
-      if (!annotation) return
-
-      // Mark this annotation for selection when it's rendered
-      this.pendingAnnotationSelection = annotationId;
-
-      // Go to the page - the annotation will be selected in _renderAnnotationsForPage
-      this.viewer.goToPage(annotation.page);
-    }
-
     /**
      * Scroll to annotation and flash/highlight it.
-     * Called from the annotation sidebar when clicking an annotation.
+     * Called from the annotation sidebar and for initial deep-links.
      */
     _scrollToAnnotationWithFlash(annotationId) {
       const annotation = this.annotationManager.getAnnotation(annotationId);
@@ -8577,10 +8755,15 @@
       });
     }
 
-    // Download with annotations
+    // Download with annotations (or the original file for encrypted documents,
+    // which pdf-lib can't open to embed annotations)
     async download() {
       try {
-        await this.downloadManager.downloadWithAnnotations();
+        if (this.readOnly) {
+          await this.downloadManager.downloadOriginal();
+        } else {
+          await this.downloadManager.downloadWithAnnotations();
+        }
       } catch (error) {
         console.error("Failed to download PDF:", error);
         throw error
@@ -8609,6 +8792,7 @@
       this.findController?.destroy();
       this.findBar?.destroy();
       this.colorPicker?.destroy();
+      this.passwordPrompt?.destroy();
 
       Object.values(this.tools || {}).forEach(tool => tool.destroy?.());
 
@@ -8678,7 +8862,9 @@
       if (this.hasLoadingOverlayTarget) {
         this.loadingOverlayTarget.classList.add("hidden");
       }
-      const message = this.errorMessageValue || "Failed to load PDF document";
+      const isPasswordError = /password/i.test(String(error?.message || "")) || /password/i.test(String(error?.name || ""));
+      const message = this.errorMessageValue ||
+        (isPasswordError ? "A password is required to open this document" : "Failed to load PDF document");
       this._showError(message);
       this.containerTarget.dispatchEvent(new CustomEvent("pdf-viewer:load-failed", {
         bubbles: true,
@@ -8859,6 +9045,10 @@
     }
 
     _activateTool(toolName) {
+      // View-only for encrypted documents; the buttons are disabled, but guard
+      // against keyboard/programmatic activation too
+      if (this._readOnly && toolName !== "select") return
+
       // Tool map for name -> mode conversion
       const toolMap = {
         select: ToolMode.SELECT,
@@ -9044,8 +9234,8 @@
     _setupPageNavigationListeners() {
       // Listen for ready event from PdfViewer
       this._readyHandler = (e) => {
-        const { pageCount, currentPage } = e.detail;
-        this._onViewerReady(pageCount, currentPage);
+        const { pageCount, currentPage, readOnly } = e.detail;
+        this._onViewerReady(pageCount, currentPage, readOnly);
       };
       this.containerTarget.addEventListener("pdf-viewer:ready", this._readyHandler);
 
@@ -9057,12 +9247,16 @@
       this.containerTarget.addEventListener("pdf-viewer:page-changed", this._pageChangedHandler);
     }
 
-    _onViewerReady(pageCount, currentPage) {
+    _onViewerReady(pageCount, currentPage, readOnly) {
       // Hide the loading overlay
       if (this.hasLoadingOverlayTarget) {
         this.loadingOverlayTarget.classList.add("hidden");
       }
 
+      if (readOnly) {
+        this._enterReadOnlyMode();
+      }
+
       if (this.hasPageCountTarget) {
         this.pageCountTarget.textContent = pageCount;
       }
@@ -9083,6 +9277,16 @@
       this._setZoomPreset("auto");
     }
 
+    // Encrypted documents are view-only: disable the annotation tools and hide
+    // the color picker. Download stays enabled but delivers the original file.
+    _enterReadOnlyMode() {
+      this._readOnly = true;
+      this.containerTarget.classList.add("pdf-viewer-read-only");
+      this.containerTarget
+        .querySelectorAll('.pdf-tool-btn[data-tool]:not([data-tool="select"]), .pdf-overflow-tool-btn[data-tool]:not([data-tool="select"])')
+        .forEach(btn => { btn.disabled = true; });
+    }
+
     _onPageChanged(currentPage, pageCount) {
       if (this.hasPageInputTarget && document.activeElement !== this.pageInputTarget) {
         this.pageInputTarget.value = currentPage;

data/app/assets/stylesheets/stimulus-pdf-viewer.scss

@@ -2467,6 +2467,112 @@
   }
 }
 
+// Password prompt for encrypted documents.
+// Sits above the loading overlay (z-index 100) and toasts (1001) so it is
+// reachable while the host app's spinner is still up.
+.pdf-password-prompt {
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: rgba(0, 0, 0, 0.4);
+  z-index: 1002;
+
+  &.hidden {
+    display: none;
+  }
+}
+
+.pdf-password-prompt-dialog {
+  width: min(360px, calc(100% - 32px));
+  padding: 24px;
+  background: #fff;
+  border-radius: 8px;
+  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.25);
+}
+
+.pdf-password-prompt-title {
+  margin: 0 0 8px;
+  font-size: 16px;
+  font-weight: 600;
+  color: #333;
+}
+
+.pdf-password-prompt-message {
+  margin: 0 0 12px;
+  font-size: 14px;
+  color: #666;
+}
+
+.pdf-password-prompt-error {
+  margin: 0 0 12px;
+  font-size: 13px;
+  color: #c62828;
+
+  &.hidden {
+    display: none;
+  }
+}
+
+.pdf-password-prompt-input {
+  width: 100%;
+  box-sizing: border-box;
+  padding: 8px 10px;
+  border: 1px solid #ccc;
+  border-radius: 6px;
+  font-size: 14px;
+
+  &:focus {
+    outline: none;
+    border-color: #0060df;
+    box-shadow: 0 0 0 2px rgba(0, 96, 223, 0.2);
+  }
+}
+
+.pdf-password-prompt-buttons {
+  display: flex;
+  justify-content: flex-end;
+  gap: 8px;
+  margin-top: 16px;
+}
+
+.pdf-password-prompt-btn {
+  padding: 6px 16px;
+  border: 1px solid #ccc;
+  border-radius: 6px;
+  background: #fff;
+  color: #333;
+  font-size: 13px;
+  font-weight: 500;
+  cursor: pointer;
+
+  &:hover {
+    background: #f5f5f5;
+  }
+
+  &.pdf-password-prompt-submit {
+    background: #0060df;
+    border-color: #0060df;
+    color: #fff;
+
+    &:hover {
+      background: #0050bf;
+    }
+  }
+}
+
+// Read-only mode for encrypted documents: annotation tool buttons are
+// disabled in JS; the color picker has no use, so hide it entirely.
+.pdf-viewer-read-only {
+  .pdf-toolbar-colors {
+    display: none;
+  }
+}
+
 // Screen reader only class for aria-live regions
 // Visually hidden but accessible to screen readers
 .pdf-viewer-announcer {

data/lib/stimulus_pdf_viewer/rails/version.rb

@@ -1,7 +1,7 @@
 module StimulusPdfViewer
   module Rails
-    VERSION = "0.4.0"
+    VERSION = '0.5.0'
     # This should match the npm package version
-    STIMULUS_PDF_VIEWER_VERSION = "0.4.0"
+    STIMULUS_PDF_VIEWER_VERSION = "0.5.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stimulus-pdf-viewer-rails
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Jeremy Baker
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-24 00:00:00.000000000 Z
+date: 2026-08-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties