@drvillo/react-browser-e-signing 0.1.2 → 0.2.0

package/README.md

@@ -59,6 +59,12 @@ pnpm demo
 - `SIGNATURE_FONTS`
 - `sha256`
 
+### Configuration
+
+- `configure(options)` — PDF worker URL, signature font mode (`network` | `local-only`), optional `fontUrlResolver`, optional `onWarning` callback
+- `getPdfWorkerSrc()` — from `@drvillo/react-browser-e-signing/worker`; returns a bundler-resolved URL for the packaged `pdf.worker.min.mjs` (recommended default for `pdfWorkerSrc`)
+- Types: `ESigningConfig`, `SignatureFontWarning`
+
 ### Types
 
 - `FieldPlacement`
@@ -121,12 +127,120 @@ pnpm test
 pnpm typecheck
 ```
 
+After a fresh clone, run **`pnpm build` once** so `dist/` includes the bundled worker, `worker.mjs`, and types (the copy step runs after tsup’s type emit).
+
 ## Notes
 
-- `PdfViewer` sets `react-pdf` worker from CDN by default using the runtime PDF.js version.
+- **PDF worker:** PDF.js **must** load its worker from a URL. This package ships `pdf.worker.min.mjs` built from the same `pdfjs-dist` version as `react-pdf` (see **Bundled PDF.js worker** below). The package does **not** inject a CDN URL by default; call `configure({ pdfWorkerSrc: getPdfWorkerSrc() })` or set `workerSrc` on `PdfViewer` so the worker loads (recommended for production). See **Production hardening** below.
 - Browser test config skips execution when Playwright Chromium is not available in the environment.
 - Demo theme switcher (`default` / `custom`) shows how a container app can fully re-theme the same components.
 
+## Production hardening
+
+Runtime calls to external CDNs (PDF.js worker, Google Fonts) often fail in real apps: **CSP** (`worker-src`, `connect-src`, `font-src`), ad blockers, corporate proxies, or offline users. They also add noisy console errors (`Failed to fetch`) even when the rest of the UI works. This library defaults to **no injected worker URL** and lets you control loading explicitly.
+
+### Bundled PDF.js worker (recommended)
+
+The npm package includes `pdf.worker.min.mjs` at the same path layout as `react-pdf`’s `pdfjs-dist` dependency, so you do **not** need unpkg or a manual copy script for the default flow.
+
+Configure once (e.g. app entry or a client-only module):
+
+```tsx
+import { configure } from '@drvillo/react-browser-e-signing'
+import { getPdfWorkerSrc } from '@drvillo/react-browser-e-signing/worker'
+
+configure({ pdfWorkerSrc: getPdfWorkerSrc() })
+```
+
+`getPdfWorkerSrc()` uses `new URL('./pdf.worker.min.mjs', import.meta.url)` so Vite, webpack 5, and similar bundlers emit the worker as an asset and rewrite the URL. **Do not** point at a third-party CDN in production if you can avoid it.
+
+Or per viewer:
+
+```tsx
+import { getPdfWorkerSrc } from '@drvillo/react-browser-e-signing/worker'
+
+<PdfViewer workerSrc={getPdfWorkerSrc()} {...pdfViewerProps} />
+```
+
+`workerSrc` on `PdfViewer` overrides `configure({ pdfWorkerSrc })`.
+
+**Advanced:** import the raw file (e.g. Vite):
+
+```tsx
+import workerUrl from '@drvillo/react-browser-e-signing/pdf.worker.min.mjs?url'
+
+configure({ pdfWorkerSrc: workerUrl })
+```
+
+**Versioning:** when this library upgrades `react-pdf` / `pdfjs-dist`, the published worker file is regenerated from that `pdfjs-dist` version. Keep your app on the published package version you intend; do not mix a different `pdfjs-dist` worker binary with another API version.
+
+**SSR / Next.js App Router:** PDF.js runs in the browser. Set `pdfWorkerSrc` only on the client — e.g. in `useEffect`, or in a file loaded via `dynamic(..., { ssr: false })`, or in a client-only entry — so `getPdfWorkerSrc()` and worker loading are not evaluated during SSR.
+
+### Manual self-host (fallback)
+
+If you prefer serving the worker from your own `public/` folder, copy the file that matches the `pdfjs-dist` version used by `react-pdf` (see `node_modules/react-pdf/package.json`):
+
+```bash
+cp node_modules/pdfjs-dist/build/pdf.worker.min.mjs public/pdf.worker.min.mjs
+```
+
+Then:
+
+```tsx
+import { configure } from '@drvillo/react-browser-e-signing'
+
+configure({ pdfWorkerSrc: '/pdf.worker.min.mjs' })
+```
+
+### Typed signatures: local-only fonts (no network)
+
+Skip all font fetches (handwriting fonts won’t load from Google; the browser uses whatever faces are already available, with sensible fallback):
+
+```tsx
+configure({ fontMode: 'local-only' })
+```
+
+Default is `fontMode: 'network'`, which keeps the previous Google Fonts behavior but **does not throw** on failure; failures are reported via `onWarning` when set.
+
+### Custom font URLs (self-hosted woff/woff2)
+
+```tsx
+configure({
+  fontUrlResolver: (family) => `/fonts/${family.replace(/\s+/g, '-')}.woff2`,
+})
+```
+
+Return `null` to fall back to Google Fonts for that family (when `fontMode` is `'network'`).
+
+### Observability
+
+```tsx
+configure({
+  onWarning: (w) => {
+    console.warn(`[react-browser-e-signing] ${w.code}: ${w.message}`)
+  },
+})
+```
+
+Warnings are non-throwing; signing flow should remain usable.
+
+### CSP-oriented example
+
+If everything is same-origin (including the worker URL after your bundler emits it):
+
+```
+Content-Security-Policy: worker-src 'self'; script-src 'self'; connect-src 'self'; font-src 'self';
+```
+
+A self-hosted worker loaded from the same origin as your app typically satisfies `worker-src 'self'`. Adjust `connect-src` / `font-src` if you still use Google Fonts or load scripts from elsewhere.
+
+### Migration from v0.1.2 and earlier
+
+Previously, `PdfViewer` set the worker to unpkg at module load, and typed fonts fetched Google Fonts CSS + files at runtime.
+
+- **Worker:** to restore the old CDN behavior (not recommended for production), set `pdfWorkerSrc` to the unpkg URL for your PDF.js version, e.g. `https://unpkg.com/pdfjs-dist@<version>/build/pdf.worker.min.mjs` (match `pdfjs.version` from `react-pdf` / `pdfjs-dist`).
+- **Fonts:** behavior is unchanged when you omit `configure()` except that network failures no longer surface as thrown errors from `loadSignatureFont`; use `fontMode: 'local-only'` for strict no-network deployments.
+
 ## Limitations
 
 - Single signer workflow in v0.1

package/dist/index.d.ts

@@ -5,6 +5,22 @@ import { ReactNode } from 'react';
 declare const SIGNATURE_FONTS: readonly ["Caveat", "Homemade Apple", "Reenie Beanie", "Mr Dafoe", "Pacifico", "Qwitcher Grypen"];
 declare function loadSignatureFont(fontFamily: string): Promise<void>;
 
+interface SignatureFontWarning {
+    code: string;
+    message: string;
+}
+interface ESigningConfig {
+    /** PDF.js worker script URL (e.g. self-hosted `/pdf.worker.min.mjs`). When unset, `PdfViewer` does not set `GlobalWorkerOptions.workerSrc`. */
+    pdfWorkerSrc?: string;
+    /** `network`: fetch Google Fonts when loading typed signature fonts (default). `local-only`: no fetches; browser uses available/system fonts. */
+    fontMode?: 'network' | 'local-only';
+    /** Return a woff/woff2 URL for a font family, or `null` to fall back to Google Fonts (when `fontMode` is `network`). */
+    fontUrlResolver?: (fontFamily: string) => string | null;
+    /** Non-throwing callback for recoverable issues (font/worker setup). */
+    onWarning?: (warning: SignatureFontWarning) => void;
+}
+declare function configure(options: ESigningConfig): void;
+
 interface PdfViewerProps {
     pdfData: ArrayBuffer | null;
     numPages: number;
@@ -18,8 +34,10 @@ interface PdfViewerProps {
     }) => void;
     renderOverlay?: (pageIndex: number) => ReactNode;
     className?: string;
+    /** PDF.js worker script URL. Overrides `configure({ pdfWorkerSrc })`. When neither is set, worker URL is left unset (no CDN injection). */
+    workerSrc?: string;
 }
-declare function PdfViewer({ pdfData, numPages, scale, onScaleChange, onDocumentLoadSuccess, onPageDimensions, renderOverlay, className, }: PdfViewerProps): react_jsx_runtime.JSX.Element;
+declare function PdfViewer({ pdfData, numPages, scale, onScaleChange, onDocumentLoadSuccess, onPageDimensions, renderOverlay, className, workerSrc, }: PdfViewerProps): react_jsx_runtime.JSX.Element;
 
 type FieldType = 'signature' | 'fullName' | 'title' | 'date';
 interface FieldPlacement {
@@ -248,4 +266,4 @@ declare const defaults: {
     readonly DEFAULT_FIELD_HEIGHT_PERCENT: 5;
 };
 
-export { FieldOverlay, FieldPalette, type FieldPlacement, type FieldType, type PdfPageDimensions, PdfViewer, SIGNATURE_FONTS, SLOTS, SignatureField, type SignatureFieldPreview, SignaturePad, SignaturePreview, type SignatureStyle, SignerDetailsPanel, type SignerInfo, SigningComplete, type SigningResult, defaults, loadSignatureFont, mapFromPoints, mapToPoints, modifyPdf, sha256, useFieldPlacement, usePdfDocument, useSignatureRenderer };
+export { type ESigningConfig, FieldOverlay, FieldPalette, type FieldPlacement, type FieldType, type PdfPageDimensions, PdfViewer, SIGNATURE_FONTS, SLOTS, SignatureField, type SignatureFieldPreview, type SignatureFontWarning, SignaturePad, SignaturePreview, type SignatureStyle, SignerDetailsPanel, type SignerInfo, SigningComplete, type SigningResult, configure, defaults, loadSignatureFont, mapFromPoints, mapToPoints, modifyPdf, sha256, useFieldPlacement, usePdfDocument, useSignatureRenderer };

package/dist/index.js

@@ -1,10 +1,19 @@
 import { pdfjs, Document, Page } from 'react-pdf';
+import { useEffect, useRef, useMemo, useState, useCallback } from 'react';
 import { jsx, jsxs } from 'react/jsx-runtime';
-import { useRef, useEffect, useMemo, useState, useCallback } from 'react';
 import SignaturePadLibrary from 'signature_pad';
 import fontkit from '@pdf-lib/fontkit';
 import { PDFDocument, StandardFonts } from 'pdf-lib';
 
+// src/lib/config.ts
+var _config = {};
+function configure(options) {
+  _config = { ..._config, ...options };
+}
+function getConfig() {
+  return _config;
+}
+
 // src/lib/signature-fonts.ts
 var loadedFonts = /* @__PURE__ */ new Set();
 var SIGNATURE_FONTS = [
@@ -29,18 +38,51 @@ function extractFontSource(cssText) {
   if (!sourceMatch) return null;
   return sourceMatch[1].replace(/['"]/g, "");
 }
+function warnFontLoad(message) {
+  try {
+    getConfig().onWarning?.({ code: "FONT_LOAD_FAILED", message });
+  } catch {
+  }
+}
+async function loadFontFaceFromUrl(fontFamily, url) {
+  if (typeof FontFace === "undefined" || typeof document === "undefined") return;
+  const fontFace = new FontFace(fontFamily, `url(${url})`);
+  await fontFace.load();
+  const fontSet = document.fonts;
+  fontSet.add(fontFace);
+}
 async function loadSignatureFont(fontFamily) {
   if (loadedFonts.has(fontFamily)) return;
   if (typeof document === "undefined") return;
   if (typeof FontFace === "undefined") return;
-  const cssUrl = buildGoogleFontsCssUrl(fontFamily);
-  const cssText = await loadCssFromGoogleFonts(cssUrl);
-  const fontSource = extractFontSource(cssText);
-  if (!fontSource) throw new Error(`Unable to extract font source for ${fontFamily}`);
-  const fontFace = new FontFace(fontFamily, `url(${fontSource})`);
-  await fontFace.load();
-  const fontSet = document.fonts;
-  fontSet.add(fontFace);
+  const { fontMode = "network", fontUrlResolver } = getConfig();
+  if (fontMode === "local-only") {
+    loadedFonts.add(fontFamily);
+    return;
+  }
+  const tryLoadFromGoogle = async () => {
+    try {
+      const cssUrl = buildGoogleFontsCssUrl(fontFamily);
+      const cssText = await loadCssFromGoogleFonts(cssUrl);
+      const fontSource = extractFontSource(cssText);
+      if (!fontSource) throw new Error(`Unable to extract font source for ${fontFamily}`);
+      await loadFontFaceFromUrl(fontFamily, fontSource);
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      warnFontLoad(`Google Fonts load failed for "${fontFamily}": ${detail}`);
+    }
+  };
+  if (fontUrlResolver) {
+    try {
+      const resolved = fontUrlResolver(fontFamily);
+      if (resolved) await loadFontFaceFromUrl(fontFamily, resolved);
+      else await tryLoadFromGoogle();
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      warnFontLoad(`Custom font load failed for "${fontFamily}": ${detail}`);
+      await tryLoadFromGoogle();
+    }
+  } else await tryLoadFromGoogle();
   loadedFonts.add(fontFamily);
 }
 
@@ -48,9 +90,6 @@ async function loadSignatureFont(fontFamily) {
 function cn(...values) {
   return values.filter(Boolean).join(" ");
 }
-if (typeof window !== "undefined") {
-  pdfjs.GlobalWorkerOptions.workerSrc = `https://unpkg.com/pdfjs-dist@${pdfjs.version}/build/pdf.worker.min.mjs`;
-}
 var MIN_SCALE = 0.5;
 var MAX_SCALE = 2;
 var SCALE_STEP = 0.1;
@@ -62,8 +101,15 @@ function PdfViewer({
   onDocumentLoadSuccess,
   onPageDimensions,
   renderOverlay,
-  className
+  className,
+  workerSrc
 }) {
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    const fromConfig = getConfig().pdfWorkerSrc;
+    const next = workerSrc ?? fromConfig;
+    if (next) pdfjs.GlobalWorkerOptions.workerSrc = next;
+  }, [workerSrc]);
   if (!pdfData)
     return /* @__PURE__ */ jsx("div", { "data-slot": "pdf-viewer-empty", className: cn(className), children: "Upload a PDF to begin" });
   return /* @__PURE__ */ jsxs("div", { "data-slot": "pdf-viewer", className: cn(className), children: [
@@ -802,7 +848,8 @@ function useSignatureRenderer({ signerName, style }) {
       setSignatureDataUrl(dataUrl || null);
     }).catch(() => {
       if (!isActive) return;
-      setSignatureDataUrl(null);
+      const dataUrl = drawTypedSignature({ signerName: normalizedName, fontFamily: style.fontFamily });
+      setSignatureDataUrl(dataUrl || null);
     }).finally(() => {
       if (!isActive) return;
       setIsRendering(false);
@@ -969,6 +1016,6 @@ var defaults = {
   DEFAULT_FIELD_HEIGHT_PERCENT: 5
 };
 
-export { FieldOverlay, FieldPalette, PdfViewer, SIGNATURE_FONTS, SLOTS, SignatureField, SignaturePad, SignaturePreview, SignerDetailsPanel, SigningComplete, defaults, loadSignatureFont, mapFromPoints, mapToPoints, modifyPdf, sha256, useFieldPlacement, usePdfDocument, useSignatureRenderer };
+export { FieldOverlay, FieldPalette, PdfViewer, SIGNATURE_FONTS, SLOTS, SignatureField, SignaturePad, SignaturePreview, SignerDetailsPanel, SigningComplete, configure, defaults, loadSignatureFont, mapFromPoints, mapToPoints, modifyPdf, sha256, useFieldPlacement, usePdfDocument, useSignatureRenderer };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map