@pixldocs/canvas-renderer 0.5.56 → 0.5.58

package/dist/index.d.ts

@@ -25,6 +25,19 @@ export declare function applyThemeToConfig(config: TemplateConfig, themeOverride
  */
 export declare function assemblePdfFromSvgs(svgResults: SvgRenderResult[], options?: PdfAssemblyOptions): Promise<PdfRenderResult>;
 
+/**
+ * Block until the webfonts referenced by `config` have actually loaded
+ * (or `maxWaitMs` elapses). Stronger than `ensureFontsForResolvedConfig`
+ * which only fire-and-forget queues `document.fonts.load()`.
+ *
+ * Use this BEFORE mounting `PreviewCanvas` so the synchronous
+ * `createText` auto-shrink loop measures against real font metrics
+ * instead of system fallback ones (which are typically narrower → loop
+ * decides "fits, no shrink needed" → text overflows once the real font
+ * swaps in).
+ */
+export declare function awaitFontsForConfig(config: TemplateConfig, maxWaitMs: number): Promise<void>;
+
 export declare interface CanvasNode {
     id: string;
     name?: string;
@@ -64,6 +77,16 @@ export declare function collectFontsFromConfig(config: TemplateConfig): Set<stri
  */
 export declare function collectImageUrls(config: TemplateConfig): string[];
 
+/**
+ * Returns true when any text node in `config` uses
+ * `overflowPolicy: 'auto-shrink'`. The synchronous shrink loop in
+ * `createText` measures with whatever font Fabric can resolve at mount
+ * time, so for these configs the consumer MUST block on real font load
+ * before mounting (otherwise it shrinks against fallback metrics and
+ * overflows once the real font swaps in).
+ */
+export declare function configHasAutoShrinkText(config: TemplateConfig | null | undefined): boolean;
+
 export declare interface DynamicField {
     id: string;
     label: string;
@@ -231,7 +254,7 @@ export declare function normalizeFontFamily(fontStack: string): string;
  * Package version banner. Bump alongside package.json so we can confirm
  * (via browser:log) that the deployed bundle matches the expected build.
  */
-export declare const PACKAGE_VERSION = "0.5.54";
+export declare const PACKAGE_VERSION = "0.5.57";
 
 export declare interface PageSettings {
     backgroundColor?: string;
@@ -391,6 +414,18 @@ export declare class PixldocsRenderer {
     private waitForCanvasImages;
     private waitForCanvasScene;
     private waitForRelevantFonts;
+    /**
+     * Block until the webfonts referenced by `config` have actually loaded
+     * (or `maxWaitMs` elapses). Used by the headless capture path BEFORE
+     * mounting `PreviewCanvas`, so the synchronous `createText` auto-shrink
+     * loop measures against final font metrics instead of fallback ones.
+     *
+     * Stronger than `ensureFontsForResolvedConfig` (which is fire-and-forget)
+     * — this awaits each `document.fonts.load(spec)` AND `document.fonts.ready`,
+     * racing the whole thing against `maxWaitMs` so a slow CDN can't hang the
+     * renderer.
+     */
+    private awaitFontsForConfig;
     private getNormalizedGradientStops;
     private paintPageBackground;
     private renderPageViaPreviewCanvas;
@@ -447,6 +482,21 @@ export declare interface RenderOptions {
     scale?: number;
     /** Custom pixel ratio override */
     pixelRatio?: number;
+    /**
+     * If true, skip the blocking font-ready wait before mounting the headless
+     * PreviewCanvas. Default: `false`. Setting this to `true` makes capture
+     * faster but can cause `overflowPolicy: 'auto-shrink'` text to overflow
+     * when the real webfont loads after auto-shrink has already measured
+     * against fallback metrics.
+     */
+    skipFontReadyWait?: boolean;
+    /**
+     * Maximum time (ms) to wait for `document.fonts.load()` per descriptor
+     * before mounting PreviewCanvas. Default: `4000` for configs that contain
+     * any `auto-shrink` text (correctness matters), `1800` otherwise. Only
+     * applies when `skipFontReadyWait` is false.
+     */
+    waitForFontsMs?: number;
 }
 
 export declare interface RenderResult {

package/dist/index.js

@@ -12244,6 +12244,46 @@ async function ensureFontsForResolvedConfig(config) {
     });
   }
 }
+function configHasAutoShrinkText$1(config) {
+  var _a;
+  if (!((_a = config == null ? void 0 : config.pages) == null ? void 0 : _a.length)) return false;
+  const walk = (nodes) => {
+    for (const node of nodes || []) {
+      if (!node) continue;
+      if (node.type === "text" && node.overflowPolicy === "auto-shrink") return true;
+      if (Array.isArray(node.children) && node.children.length && walk(node.children)) return true;
+    }
+    return false;
+  };
+  for (const page of config.pages) {
+    if (walk(page.children || [])) return true;
+  }
+  return false;
+}
+async function awaitFontsForConfig(config, maxWaitMs) {
+  if (typeof document === "undefined" || !document.fonts) return;
+  void ensureFontsForResolvedConfig(config);
+  const descriptors = collectFontDescriptorsFromConfig(config);
+  if (descriptors.length === 0) return;
+  const loads = Promise.all(
+    descriptors.map((d) => {
+      const stylePrefix = d.style === "italic" ? "italic " : "";
+      const spec = `${stylePrefix}${d.weight} 16px "${d.family}"`;
+      return document.fonts.load(spec).catch(() => []);
+    })
+  ).then(() => void 0);
+  await Promise.race([
+    loads,
+    new Promise((resolve) => setTimeout(resolve, maxWaitMs))
+  ]);
+  await Promise.race([
+    document.fonts.ready.catch(() => void 0).then(() => void 0),
+    new Promise((r) => setTimeout(r, Math.min(500, maxWaitMs)))
+  ]);
+  await new Promise(
+    (resolve) => requestAnimationFrame(() => requestAnimationFrame(() => resolve()))
+  );
+}
 const PREVIEW_DEBUG_PREFIX = "[canvas-renderer][preview-debug]";
 function countUnderlinedNodes(config) {
   var _a;
@@ -12329,15 +12369,17 @@ function PixldocsPreview(props) {
           underlinedNodes: countUnderlinedNodes(resolved.config)
         });
         setResolvedConfig(resolved.config);
-        ensureFontsForResolvedConfig(resolved.config).then(() => {
+        const hasAutoShrink = configHasAutoShrinkText$1(resolved.config);
+        const waitMs = hasAutoShrink ? 4e3 : 1800;
+        awaitFontsForConfig(resolved.config, waitMs).then(() => {
           if (!cancelled) {
-            console.log(PREVIEW_DEBUG_PREFIX, "resolve-mode fonts queued");
+            console.log(PREVIEW_DEBUG_PREFIX, "resolve-mode fonts settled", { hasAutoShrink, waitMs });
             setFontsReady(true);
             setIsLoading(false);
           }
         }).catch((err) => {
           if (!cancelled) {
-            console.warn(PREVIEW_DEBUG_PREFIX, "resolve-mode fonts queue failed", err);
+            console.warn(PREVIEW_DEBUG_PREFIX, "resolve-mode font wait failed", err);
             setFontsReady(true);
             setIsLoading(false);
           }
@@ -12406,16 +12448,26 @@ function PixldocsPreview(props) {
     setFontsReady(false);
     setCanvasSettled(false);
     setStabilizationPass(0);
-    ensureFontsForResolvedConfig(config).then(() => {
-      console.log(PREVIEW_DEBUG_PREFIX, "config-mode fonts queued", {
+    let cancelled = false;
+    const hasAutoShrink = configHasAutoShrinkText$1(config);
+    const waitMs = hasAutoShrink ? 4e3 : 1800;
+    awaitFontsForConfig(config, waitMs).then(() => {
+      if (cancelled) return;
+      console.log(PREVIEW_DEBUG_PREFIX, "config-mode fonts settled", {
         pageIndex,
+        hasAutoShrink,
+        waitMs,
         underlinedNodes: countUnderlinedNodes(config)
       });
       setFontsReady(true);
     }).catch((err) => {
-      console.warn(PREVIEW_DEBUG_PREFIX, "config-mode fonts queue failed", err);
+      if (cancelled) return;
+      console.warn(PREVIEW_DEBUG_PREFIX, "config-mode font wait failed", err);
       setFontsReady(true);
     });
+    return () => {
+      cancelled = true;
+    };
   }, [isResolveMode, config]);
   const handleCanvasReady = useCallback(() => {
     if (stabilizationPass === 0) {
@@ -12452,7 +12504,7 @@ function PixldocsPreview(props) {
     !canvasSettled && /* @__PURE__ */ jsx("div", { style: { position: "absolute", inset: 0, display: "flex", alignItems: "center", justifyContent: "center", minHeight: 200 }, children: /* @__PURE__ */ jsx("div", { style: { color: "#888", fontSize: 14 }, children: "Loading preview..." }) })
   ] });
 }
-const PACKAGE_VERSION = "0.5.54";
+const PACKAGE_VERSION = "0.5.57";
 let __underlineFixInstalled = false;
 function installUnderlineFix(fab) {
   var _a;
@@ -12549,6 +12601,22 @@ function installUnderlineFix(fab) {
   __underlineFixInstalled = true;
   console.log(`[canvas-renderer] underline-fix monkey patch installed (v${PACKAGE_VERSION})`);
 }
+function configHasAutoShrinkText(config) {
+  var _a;
+  if (!((_a = config == null ? void 0 : config.pages) == null ? void 0 : _a.length)) return false;
+  const walk = (nodes) => {
+    for (const node of nodes || []) {
+      if (!node) continue;
+      if (node.type === "text" && node.overflowPolicy === "auto-shrink") return true;
+      if (Array.isArray(node.children) && node.children.length && walk(node.children)) return true;
+    }
+    return false;
+  };
+  for (const page of config.pages) {
+    if (walk(page.children || [])) return true;
+  }
+  return false;
+}
 class PixldocsRenderer {
   constructor(config) {
     __publicField(this, "config");
@@ -12575,6 +12643,11 @@ class PixldocsRenderer {
       throw new Error(`Page index ${pageIndex} not found (template has ${templateConfig.pages.length} pages)`);
     }
     await ensureFontsForResolvedConfig(templateConfig);
+    if (!options.skipFontReadyWait) {
+      const hasAutoShrink = configHasAutoShrinkText(templateConfig);
+      const defaultWait = hasAutoShrink ? 4e3 : 1800;
+      await this.awaitFontsForConfig(templateConfig, options.waitForFontsMs ?? defaultWait);
+    }
     const { setPackageApiUrl: setPackageApiUrl2 } = await Promise.resolve().then(() => appApi);
     setPackageApiUrl2(this.config.imageProxyUrl);
     const dataUrl = await this.renderPageViaPreviewCanvas(
@@ -12582,7 +12655,8 @@ class PixldocsRenderer {
       pageIndex,
       pixelRatio,
       format,
-      quality
+      quality,
+      { skipFontReadyWait: options.skipFontReadyWait, waitForFontsMs: options.waitForFontsMs }
     );
     return {
       dataUrl,
@@ -12596,9 +12670,14 @@ class PixldocsRenderer {
    * Render all pages and return array of results.
    */
   async renderAllPages(templateConfig, options = {}) {
+    if (!options.skipFontReadyWait) {
+      const hasAutoShrink = configHasAutoShrinkText(templateConfig);
+      const defaultWait = hasAutoShrink ? 4e3 : 1800;
+      await this.awaitFontsForConfig(templateConfig, options.waitForFontsMs ?? defaultWait);
+    }
     const results = [];
     for (let i = 0; i < templateConfig.pages.length; i++) {
-      results.push(await this.render(templateConfig, { ...options, pageIndex: i }));
+      results.push(await this.render(templateConfig, { ...options, pageIndex: i, skipFontReadyWait: true }));
     }
     return results;
   }
@@ -12635,6 +12714,8 @@ class PixldocsRenderer {
       throw new Error(`Page index ${pageIndex} not found (template has ${templateConfig.pages.length} pages)`);
     }
     await ensureFontsForResolvedConfig(templateConfig);
+    const hasAutoShrinkSvg = configHasAutoShrinkText(templateConfig);
+    await this.awaitFontsForConfig(templateConfig, hasAutoShrinkSvg ? 4e3 : 1800);
     const { setPackageApiUrl: setPackageApiUrl2 } = await Promise.resolve().then(() => appApi);
     setPackageApiUrl2(this.config.imageProxyUrl);
     const canvasWidth = templateConfig.canvas.width;
@@ -12646,6 +12727,8 @@ class PixldocsRenderer {
    */
   async renderAllPageSvgs(templateConfig) {
     await ensureFontsForResolvedConfig(templateConfig);
+    const hasAutoShrinkSvg = configHasAutoShrinkText(templateConfig);
+    await this.awaitFontsForConfig(templateConfig, hasAutoShrinkSvg ? 4e3 : 1800);
     const { setPackageApiUrl: setPackageApiUrl2 } = await Promise.resolve().then(() => appApi);
     setPackageApiUrl2(this.config.imageProxyUrl);
     const results = [];
@@ -12898,6 +12981,26 @@ class PixldocsRenderer {
     ]);
     await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(() => resolve())));
   }
+  /**
+   * Block until the webfonts referenced by `config` have actually loaded
+   * (or `maxWaitMs` elapses). Used by the headless capture path BEFORE
+   * mounting `PreviewCanvas`, so the synchronous `createText` auto-shrink
+   * loop measures against final font metrics instead of fallback ones.
+   *
+   * Stronger than `ensureFontsForResolvedConfig` (which is fire-and-forget)
+   * — this awaits each `document.fonts.load(spec)` AND `document.fonts.ready`,
+   * racing the whole thing against `maxWaitMs` so a slow CDN can't hang the
+   * renderer.
+   */
+  async awaitFontsForConfig(config, maxWaitMs) {
+    if (typeof document === "undefined" || !document.fonts) return;
+    void ensureFontsForResolvedConfig(config);
+    await this.waitForRelevantFonts(config, maxWaitMs);
+    await Promise.race([
+      document.fonts.ready.catch(() => void 0).then(() => void 0),
+      new Promise((r) => setTimeout(r, Math.min(500, maxWaitMs)))
+    ]);
+  }
   getNormalizedGradientStops(gradient) {
     const stops = Array.isArray(gradient == null ? void 0 : gradient.stops) ? gradient.stops.map((stop) => ({
       offset: Math.max(0, Math.min(1, Number((stop == null ? void 0 : stop.offset) ?? 0))),
@@ -12971,10 +13074,19 @@ class PixldocsRenderer {
     } catch {
     }
   }
-  async renderPageViaPreviewCanvas(config, pageIndex, pixelRatio, format, quality) {
+  async renderPageViaPreviewCanvas(config, pageIndex, pixelRatio, format, quality, options = {}) {
     const { PreviewCanvas: PreviewCanvas2 } = await Promise.resolve().then(() => PreviewCanvas$1);
     const canvasWidth = config.canvas.width;
     const canvasHeight = config.canvas.height;
+    const hasAutoShrink = configHasAutoShrinkText(config);
+    let firstMountSettled = false;
+    let lateFontSettleDetected = false;
+    if (typeof document !== "undefined" && document.fonts && hasAutoShrink) {
+      document.fonts.ready.then(() => {
+        if (firstMountSettled) lateFontSettleDetected = true;
+      }).catch(() => {
+      });
+    }
     return new Promise((resolve, reject) => {
       const container = document.createElement("div");
       container.style.cssText = `
@@ -12987,6 +13099,8 @@ class PixldocsRenderer {
         cleanup();
         reject(new Error("Render timeout (30s)"));
       }, 3e4);
+      let root;
+      let mountKey = 0;
       const cleanup = () => {
         clearTimeout(timeout);
         try {
@@ -12995,6 +13109,46 @@ class PixldocsRenderer {
         }
         container.remove();
       };
+      const remountWithFreshKey = async () => {
+        mountKey += 1;
+        try {
+          clearMeasurementCache();
+        } catch {
+        }
+        try {
+          clearFabricCharCache();
+        } catch {
+        }
+        try {
+          root.unmount();
+        } catch {
+        }
+        root = createRoot(container);
+        await new Promise((settle) => {
+          const onReadyOnce = () => {
+            this.waitForCanvasScene(container, config, pageIndex).then(async () => {
+              const fabricInstance = this.getFabricCanvasFromContainer(container);
+              const expectedImageCount = this.getExpectedImageCount(config, pageIndex);
+              await this.waitForCanvasImages(container, expectedImageCount);
+              await this.waitForStableTextMetrics(container, config);
+              await this.waitForCanvasScene(container, config, pageIndex);
+              if (!fabricInstance) return settle();
+              settle();
+            }).catch(() => settle());
+          };
+          root.render(
+            createElement(PreviewCanvas2, {
+              key: `remount-${mountKey}`,
+              config,
+              pageIndex,
+              zoom: pixelRatio,
+              absoluteZoom: true,
+              skipFontReadyWait: false,
+              onReady: onReadyOnce
+            })
+          );
+        });
+      };
       const onReady = () => {
         this.waitForCanvasScene(container, config, pageIndex).then(async () => {
           try {
@@ -13003,16 +13157,23 @@ class PixldocsRenderer {
             await this.waitForCanvasImages(container, expectedImageCount);
             await this.waitForStableTextMetrics(container, config);
             await this.waitForCanvasScene(container, config, pageIndex);
+            firstMountSettled = true;
+            if (hasAutoShrink && lateFontSettleDetected) {
+              console.log("[canvas-renderer][parity] late font-settle detected — remounting for auto-shrink reflow");
+              await remountWithFreshKey();
+            }
             const fabricCanvas = container.querySelector("canvas.upper-canvas, canvas");
             const sourceCanvas = (fabricInstance == null ? void 0 : fabricInstance.lowerCanvasEl) || container.querySelector("canvas.lower-canvas") || fabricCanvas;
+            const fabricInstanceAfter = this.getFabricCanvasFromContainer(container) || fabricInstance;
+            const sourceCanvasAfter = (fabricInstanceAfter == null ? void 0 : fabricInstanceAfter.lowerCanvasEl) || container.querySelector("canvas.lower-canvas") || sourceCanvas;
             if (!sourceCanvas) {
               cleanup();
               reject(new Error("No canvas element found after render"));
               return;
             }
             const exportCanvas = document.createElement("canvas");
-            exportCanvas.width = sourceCanvas.width;
-            exportCanvas.height = sourceCanvas.height;
+            exportCanvas.width = sourceCanvasAfter.width;
+            exportCanvas.height = sourceCanvasAfter.height;
             const exportCtx = exportCanvas.getContext("2d");
             if (!exportCtx) {
               cleanup();
@@ -13020,10 +13181,10 @@ class PixldocsRenderer {
               return;
             }
             exportCtx.save();
-            exportCtx.scale(sourceCanvas.width / canvasWidth, sourceCanvas.height / canvasHeight);
+            exportCtx.scale(sourceCanvasAfter.width / canvasWidth, sourceCanvasAfter.height / canvasHeight);
             this.paintPageBackground(exportCtx, config.pages[pageIndex], canvasWidth, canvasHeight);
             exportCtx.restore();
-            exportCtx.drawImage(sourceCanvas, 0, 0);
+            exportCtx.drawImage(sourceCanvasAfter, 0, 0);
             const mimeType = format === "jpeg" ? "image/jpeg" : format === "webp" ? "image/webp" : "image/png";
             const dataUrl = exportCanvas.toDataURL(mimeType, quality);
             cleanup();
@@ -13034,7 +13195,7 @@ class PixldocsRenderer {
           }
         });
       };
-      const root = createRoot(container);
+      root = createRoot(container);
       root.render(
         createElement(PreviewCanvas2, {
           config,
@@ -15515,9 +15676,11 @@ export {
   PixldocsRenderer,
   applyThemeToConfig,
   assemblePdfFromSvgs,
+  awaitFontsForConfig,
   collectFontDescriptorsFromConfig,
   collectFontsFromConfig,
   collectImageUrls,
+  configHasAutoShrinkText$1 as configHasAutoShrinkText,
   embedFont,
   embedFontsForConfig,
   embedFontsInPdf,