@norskvideo/ctl-dev-kit 0.2.23 → 0.2.24

package/doc-guide/doc-guide.d.ts

@@ -62,6 +62,19 @@ export declare function livePictureFailure(selector: string, phase: string | nul
 export declare function awaitLivePicture(page: Page, selector: string, opts?: {
     timeoutMs?: number;
 }): Promise<void>;
+/** How long a capture waits for web fonts before shooting anyway. */
+export declare const FONTS_READY_TIMEOUT_MS = 10000;
+/** `document.fonts.ready`, bounded. True when the fonts settled in time.
+ *
+ *  Unbounded, this hung commentary's composition guide for its whole 360s test
+ *  budget on 2026-10-03 (CI only, after the Take, with the page about to render
+ *  the advanced compositor): `fonts.ready` resolves only once every pending font
+ *  load has finished, a request that never answers never finishes, and
+ *  `page.evaluate` has no timeout of its own. The test then timed out, its
+ *  teardown with it, and the instance ran on for hours. A capture in a fallback
+ *  font is a far smaller failure than that, so bound the wait inside the page
+ *  AND around the call -- a wedged renderer never answers the call at all. */
+export declare function awaitFontsReady(page: Pick<Page, "evaluate">, timeoutMs?: number): Promise<boolean>;
 /** Produce the screenshot bytes for a capture, applying its treatment. Split out
  *  from `DocGuide.capture` (which also gates on DOCS_GENERATE and writes the file)
  *  so the treatment geometry is testable on its own. */

package/doc-guide/doc-guide.js

@@ -79,14 +79,47 @@ async function spotlightOn(page, selector, pad) {
 async function spotlightOff(page) {
     await page.evaluate((id) => document.getElementById(id)?.remove(), SPOTLIGHT_ID);
 }
+/** How long a capture waits for web fonts before shooting anyway. */
+export const FONTS_READY_TIMEOUT_MS = 10_000;
+/** `document.fonts.ready`, bounded. True when the fonts settled in time.
+ *
+ *  Unbounded, this hung commentary's composition guide for its whole 360s test
+ *  budget on 2026-10-03 (CI only, after the Take, with the page about to render
+ *  the advanced compositor): `fonts.ready` resolves only once every pending font
+ *  load has finished, a request that never answers never finishes, and
+ *  `page.evaluate` has no timeout of its own. The test then timed out, its
+ *  teardown with it, and the instance ran on for hours. A capture in a fallback
+ *  font is a far smaller failure than that, so bound the wait inside the page
+ *  AND around the call -- a wedged renderer never answers the call at all. */
+export async function awaitFontsReady(page, timeoutMs = FONTS_READY_TIMEOUT_MS) {
+    let timer;
+    const late = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(false), timeoutMs);
+    });
+    const ready = page
+        .evaluate((ms) => Promise.race([
+        document.fonts.ready.then(() => true),
+        new Promise((resolve) => setTimeout(() => resolve(false), ms)),
+    ]), timeoutMs)
+        .catch(() => false);
+    try {
+        return await Promise.race([ready, late]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 /** Produce the screenshot bytes for a capture, applying its treatment. Split out
  *  from `DocGuide.capture` (which also gates on DOCS_GENERATE and writes the file)
  *  so the treatment geometry is testable on its own. */
 export async function screenshotFor(page, treat) {
     if (treat?.livePicture)
         await awaitLivePicture(page, treat.livePicture, { timeoutMs: treat.livePictureTimeoutMs });
-    // Wait for web fonts, else the snapshot catches a fallback font mid-swap.
-    await page.evaluate(() => document.fonts.ready);
+    // Wait for web fonts, else the snapshot catches a fallback font mid-swap --
+    // but not forever (see awaitFontsReady).
+    if (!(await awaitFontsReady(page))) {
+        console.warn(`[doc-guide] web fonts not ready after ${FONTS_READY_TIMEOUT_MS}ms; capturing with what has loaded`);
+    }
     if (treat?.crop)
         return page.locator(treat.crop).first().screenshot();
     if (treat?.spotlight) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-dev-kit",
-  "version": "0.2.23",
+  "version": "0.2.24",
   "type": "module",
   "exports": {
     "./create-product": "./create-product/create-product.ts",