Root silently swallows errors and doesn't support password-protected PDFs

[dbartholomae]

When Root fails to load a PDF (e.g. network error, corrupt file, or password-protected PDF), initialState is never set, so the loader prop renders indefinitely with no way for consumers to detect or handle the failure.

This happens because usePDFDocumentContext catches all errors from getDocument() and only logs them:

// current behavior in usePDFDocumentContext
loadingTask.promise.then((proxy) => {
  onDocumentLoad?.({ proxy, source });
  setProgress(1);
  generateViewports(proxy);
}).catch((error) => {
  if (loadingTask.destroyed) return;
  console.error("Error loading PDF document", error);
  // initialState stays null → loader renders forever
});

Requested changes

1. Add an onError callback

Add an onError callback to Root / usePDFDocumentParams, called when PDF loading fails:

<Root
  source={source}
  onError={(error) => setFailed(true)}
/>

2. Add an onPassword callback

pdfjs-dist already supports password-protected PDFs via loadingTask.onPassword, but lector doesn't expose it. This would allow consumers to prompt the user for a password and retry:

<Root
  source={source}
  onPassword={(callback, reason) => {
    // show password prompt, then call callback(password)
  }}
/>

Current workaround

We pre-probe the PDF with a separate getDocument() call to detect errors and password requirements before passing the source to Root, and use an onDocumentLoad-based timeout to detect if lector's own load silently fails.

Happy to contribute a PR for this if you're open to it.

Environment

• @anaralabs/lector 3.8.0
• pdfjs-dist 4.10.38