Merge pull request #662 from embedpdf/fix/font-fallback-null

Allow null to disable font fallback

Author: bobsingor

.changeset/fontfallback-null-opt-out.md

@@ -0,0 +1,6 @@
+---
+"@embedpdf/snippet": patch
+"@embedpdf/engines": patch
+---
+
+Fix `fontFallback: null` not disabling the default jsDelivr CDN font fallback. The snippet previously stripped `null` with a truthy filter before it reached the worker, so the worker fell back to the CDN config. The value is now forwarded correctly (preserving `null` while still omitting an unset option), and the `fontFallback` type is widened to `FontFallbackConfig | null` across the engine hooks/options so the documented airgapped opt-out is type-correct end to end.

packages/engines/src/lib/orchestrator/remote-executor.ts

@@ -59,9 +59,10 @@ export interface RemoteExecutorOptions {
    */
   logger?: Logger;
   /**
-   * Font fallback configuration for handling missing fonts
+   * Font fallback configuration for handling missing fonts.
+   * Set to `null` to disable the fallback entirely (no external font requests).
    */
-  fontFallback?: FontFallbackConfig;
+  fontFallback?: FontFallbackConfig | null;
 }
 
 const LOG_SOURCE = 'RemoteExecutor';

packages/engines/src/lib/pdfium/engine.ts

@@ -192,8 +192,9 @@ export interface PdfiumEngineOptions {
    * Font fallback configuration for handling missing fonts in PDFs.
    * When enabled, PDFium will request fallback fonts from configured URLs
    * when it encounters text that requires fonts not embedded in the PDF.
+   * Set to `null` to disable the fallback entirely (no external font requests).
    */
-  fontFallback?: FontFallbackConfig;
+  fontFallback?: FontFallbackConfig | null;
 }
 
 /**

packages/engines/src/lib/pdfium/web/direct-engine.ts

@@ -21,8 +21,9 @@ export interface CreatePdfiumEngineOptions {
    * Font fallback configuration for handling missing fonts in PDFs.
    * When enabled, PDFium will request fallback fonts from configured URLs
    * when it encounters text that requires fonts not embedded in the PDF.
+   * Set to `null` to disable the fallback entirely (no external font requests).
    */
-  fontFallback?: FontFallbackConfig;
+  fontFallback?: FontFallbackConfig | null;
 }
 
 /**

packages/engines/src/lib/pdfium/web/worker-engine.ts

@@ -27,8 +27,9 @@ export interface CreatePdfiumEngineOptions {
    * Font fallback configuration for handling missing fonts in PDFs.
    * When enabled, PDFium will request fallback fonts from configured URLs
    * when it encounters text that requires fonts not embedded in the PDF.
+   * Set to `null` to disable the fallback entirely (no external font requests).
    */
-  fontFallback?: FontFallbackConfig;
+  fontFallback?: FontFallbackConfig | null;
 }
 
 /**

packages/engines/src/shared/hooks/use-pdfium-engine.ts

@@ -11,8 +11,9 @@ interface UsePdfiumEngineProps {
   encoderPoolSize?: number;
   /**
    * Font fallback configuration for handling missing fonts in PDFs.
+   * Set to `null` to disable the fallback entirely (no external font requests).
    */
-  fontFallback?: FontFallbackConfig;
+  fontFallback?: FontFallbackConfig | null;
 }
 
 export function usePdfiumEngine(config?: UsePdfiumEngineProps) {

packages/engines/src/svelte/hooks/use-pdfium-engine.svelte.ts

@@ -10,8 +10,9 @@ export interface UsePdfiumEngineProps {
   logger?: Logger;
   /**
    * Font fallback configuration for handling missing fonts in PDFs.
+   * Set to `null` to disable the fallback entirely (no external font requests).
    */
-  fontFallback?: FontFallbackConfig;
+  fontFallback?: FontFallbackConfig | null;
 }
 
 export function usePdfiumEngine(config?: UsePdfiumEngineProps) {

packages/engines/src/vue/composables/use-pdfium-engine.ts

@@ -11,8 +11,9 @@ interface UsePdfiumEngineProps {
   logger?: Logger;
   /**
    * Font fallback configuration for handling missing fonts in PDFs.
+   * Set to `null` to disable the fallback entirely (no external font requests).
    */
-  fontFallback?: FontFallbackConfig;
+  fontFallback?: FontFallbackConfig | null;
 }
 
 interface UsePdfiumEngineResult {

viewers/snippet/src/components/app.tsx

@@ -233,8 +233,11 @@ export interface PDFViewerConfig {
   wasmUrl?: string;
   /** Enable debug logging. Default: false */
   log?: boolean;
-  /** Font fallback configuration. Defaults to CDN fonts from jsDelivr. */
-  fontFallback?: FontFallbackConfig;
+  /**
+   * Font fallback configuration. Defaults to CDN fonts from jsDelivr.
+   * Set to `null` to disable the fallback entirely (no external font requests).
+   */
+  fontFallback?: FontFallbackConfig | null;
 
   // === Global Permissions ===
   /**
@@ -570,7 +573,7 @@ const logger = new AllLogger([new ConsoleLogger(), new PerfLogger()]);
 export function PDFViewer({ config, onRegistryReady }: PDFViewerProps) {
   const { engine, isLoading } = usePdfiumEngine({
     ...(config.wasmUrl && { wasmUrl: config.wasmUrl }),
-    ...(config.fontFallback && { fontFallback: config.fontFallback }),
+    ...(config.fontFallback !== undefined && { fontFallback: config.fontFallback }),
     worker: config.worker,
     logger: config.log ? logger : undefined,
   });