@norskvideo/ctl-dev-kit 0.2.54 → 0.2.56

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

@@ -24,6 +24,21 @@ export interface UiFixture {
  *  whose cwd is the repo root (the engine tier). Deferred, not module-level, so a
  *  config that sets the env var at eval time is honoured. */
 export declare function docsRoot(): string;
+/** The spoken ceiling for one step. The video spikes measured a step narrating
+ *  at about 2.5 words/s: 35 words is 14 s on one still, 50 is 20 s, and the
+ *  renderer's own lint warns at 35. This is the hard stop. */
+export declare const DEFAULT_CAPTION_WORDS = 50;
+/** Why a step's text cannot be narrated as written, or null when it can. Pure,
+ *  so the wording is pinned without a browser. Checks the budget first: an
+ *  over-long caption gets rewritten anyway, and the rewrite is where the
+ *  phrasing gets fixed. */
+export declare function captionFault(text: string, budget: number): string | null;
+/** Device scale factor for a capture: 2 in a DOCS_GENERATE run, 1 otherwise.
+ *  The video spike found the manual's component crops 383 to 778 px wide; in
+ *  a 1080p frame they are soft, and no renderer recovers detail that was never
+ *  captured. A plain run writes no captures, so it keeps 1x and is unchanged.
+ *  One place for both tiers: guidesConfig and launchLiveBrowser read it. */
+export declare function captureScaleFactor(): number;
 /** Per-step screenshot treatment. `crop` shoots one component at its own bounds;
  *  `spotlight` keeps the whole screen for context but dims everything except the
  *  named region and outlines it. Omit both for a plain full-page capture.
@@ -40,6 +55,9 @@ export interface CaptureTreatment {
     /** How long `livePicture` may take to arrive. Default 60s: a WebTransport
      *  session plus a catalog plus a keyframe, on a cold encoder. */
     livePictureTimeoutMs?: number;
+    /** The rest of the live-picture gate: the product's own slate markers, the
+     *  motion thresholds. `livePictureTimeoutMs` is the shorthand for its timeout. */
+    livePictureGate?: LivePictureGate;
 }
 /** The attributes Studio's shared MoQ player (norsk-studio-built-ins
  *  `lib/shared/moq-player`) stamps on the container it mounts into. `live`
@@ -49,19 +67,83 @@ export interface CaptureTreatment {
 export declare const MOQ_PHASE_ATTR = "data-moq-phase";
 export declare const MOQ_ERROR_ATTR = "data-moq-error";
 export type MoqPhase = "connecting" | "live" | "error";
+/** Slates and modals a tile must not be showing. Products add their own via
+ *  `occluderSelectors`; the text pattern catches a slate rendered as DOM text. */
+export declare const DEFAULT_OCCLUDER_SELECTORS: readonly string[];
+export declare const DEFAULT_OCCLUDER_TEXT: RegExp;
+export interface LivePictureGate extends LivePictureMotion {
+    /** Default 60s: a WebTransport session plus a catalog plus a keyframe, on a cold encoder. */
+    timeoutMs?: number;
+    /** Selectors that mark a slate or modal when visible inside the tile. Default DEFAULT_OCCLUDER_SELECTORS. */
+    occluderSelectors?: readonly string[];
+    /** Visible text inside the tile that marks a slate; null disables. Default DEFAULT_OCCLUDER_TEXT. */
+    occluderText?: RegExp | null;
+    /** Gap between the two frame samples the motion check compares. Default 500ms. */
+    frameGapMs?: number;
+}
+/** What the browser reports about a tile, for `judgeLivePicture` to rule on.
+ *  Gathering is a browser matter; the ruling is pure, so each check and its
+ *  wording are pinned without a launch. */
+export interface LivePictureEvidence {
+    /** `data-moq-phase` on the tile; null when nothing stamped it. */
+    phase: string | null;
+    /** `data-moq-error`, when the player reported one. */
+    error: string | null;
+    /** What `elementFromPoint` found at the tile's centre when it was neither
+     *  the tile nor inside it (as `tag#id.class`); null when the tile is on top. */
+    coveredBy: string | null;
+    /** Slate or modal matches visible inside the tile: the selector that hit,
+     *  or `text "..."` for the text pattern. Empty when none. */
+    occluders: string[];
+    /** Two luma samples of the tile's drawable (video or canvas), downsampled to
+     *  FRAME_SAMPLE_W x FRAME_SAMPLE_H and taken `frameGapMs` apart; null when
+     *  the tile has nothing to draw. */
+    frames: [number[], number[]] | null;
+    frameGapMs: number;
+}
+export type LivePictureCheck = "phase" | "covered" | "occluded" | "frozen" | "undrawable";
+/** What counts as motion between the two samples. A slate is still; a live
+ *  picture moves somewhere. Per-pixel on 0..255 luma, after the downsample
+ *  has averaged out decoder noise. */
+export interface LivePictureMotion {
+    /** A sampled pixel has moved when its luma changed by more than this. Default 6. */
+    pixelDelta?: number;
+    /** The fraction of sampled pixels that must have moved. Default 0.02. */
+    minChangedFraction?: number;
+}
+export declare const FRAME_SAMPLE_W = 32;
+export declare const FRAME_SAMPLE_H = 18;
+export type LivePictureVerdict = {
+    live: true;
+} | {
+    live: false;
+    check: LivePictureCheck;
+    reason: string;
+};
+/** Rule on whether the tile is showing a live picture, naming the first
+ *  check that says it is not. */
+export declare function judgeLivePicture(evidence: LivePictureEvidence, motion?: LivePictureMotion): LivePictureVerdict;
 /** The failure a guide sees when a tile never shows a picture: the tile, the
  *  phase it was stuck in and, for an error, the player's own reason — so a
  *  broken preview reads as what it is rather than as a timeout. Pure, so the
  *  wording is pinned without a browser. */
 export declare function livePictureFailure(selector: string, phase: string | null, error: string | null, timeoutMs: number): string;
-/** Block until the tile at `selector` reports a decoded frame, or fail saying
- *  why it did not. This is the wait a guide puts between "the source connected"
- *  and the capture: the player mounts at that moment, and a screenshot taken
- *  then is of a spinner. A wall-clock sleep would hide a broken preview; this
- *  turns it into a named failure. */
-export declare function awaitLivePicture(page: Page, selector: string, opts?: {
-    timeoutMs?: number;
-}): Promise<void>;
+/** The failure for whichever check the tile never passed. The phase check
+ *  keeps its original wording; the composite checks name themselves. */
+export declare function livePictureGateFailure(selector: string, verdict: Exclude<LivePictureVerdict, {
+    live: true;
+}>, timeoutMs: number): string;
+/** Block until the tile at `selector` shows a live picture, or fail saying
+ *  which check it never passed. This is the wait a guide puts between "the
+ *  source connected" and the capture: the player mounts at that moment, and a
+ *  screenshot taken then is of a spinner. A wall-clock sleep would hide a
+ *  broken preview; this turns it into a named failure.
+ *
+ *  Live means: the player stamped `live`, nothing else sits at the tile's
+ *  centre, no slate or modal is visible inside it, and its picture moved
+ *  between two samples. The last two are what let a standby slate and a
+ *  modal over the hero through the phase check alone (2026-10-07). */
+export declare function awaitLivePicture(page: Page, selector: string, opts?: LivePictureGate): 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.
@@ -82,15 +164,28 @@ export declare function screenshotFor(page: Page, treat?: CaptureTreatment): Pro
 /** Pure markdown assembly — exposed so a render step can re-emit markdown from a
  * stored entries.json without re-running the browser. */
 export declare function renderUiMarkdown(title: string, entries: UiEntry[]): string;
+export interface DocGuideOptions {
+    /** Spoken-word budget for one step (heading + description) or text() block.
+     *  Default: NORSK_DOCS_CAPTION_WORDS (which guidesConfig exports), else 50. */
+    captionWords?: number;
+}
+/** The budget a guide is held to: an explicit option, else the env var the
+ *  config factory exports, else the default. Read at call time, like docsRoot. */
+export declare function captionBudget(option?: number): number;
 export declare class DocGuide {
     private slug;
     private title;
+    private options;
     private entries;
     private captureIndex;
-    constructor(slug: string, title: string);
+    constructor(slug: string, title: string, options?: DocGuideOptions);
     section(heading: string): void;
     step(heading: string, description?: string): void;
     text(prose: string): void;
+    /** Only the DOCS_GENERATE run is published and narrated, so only it is held
+     *  to the spoken budget; a plain run of the guide asserts the UI and says
+     *  nothing about the prose. */
+    private lintCaption;
     /** Screenshot the page and write it immediately under the slug's docs dir. Pass
      *  a treatment to crop to one component or spotlight a region in context. */
     capture(page: Page, caption: string, treat?: CaptureTreatment): Promise<void>;

package/doc-guide/doc-guide.js

@@ -10,6 +10,37 @@ export function docsRoot() {
         return isAbsolute(override) ? override : resolve(process.cwd(), override);
     return resolve(process.cwd(), "docs/generated");
 }
+/** The spoken ceiling for one step. The video spikes measured a step narrating
+ *  at about 2.5 words/s: 35 words is 14 s on one still, 50 is 20 s, and the
+ *  renderer's own lint warns at 35. This is the hard stop. */
+export const DEFAULT_CAPTION_WORDS = 50;
+const SPOKEN_WORD = /[\p{L}\p{N}]/u;
+const RAW_URL = /https?:\/\/\S+/;
+const SLASH_BETWEEN_WORDS = /\S+\/\S+/;
+/** Why a step's text cannot be narrated as written, or null when it can. Pure,
+ *  so the wording is pinned without a browser. Checks the budget first: an
+ *  over-long caption gets rewritten anyway, and the rewrite is where the
+ *  phrasing gets fixed. */
+export function captionFault(text, budget) {
+    const count = text.split(/\s+/).filter((token) => SPOKEN_WORD.test(token)).length;
+    if (count > budget)
+        return `${count} words; the spoken budget is ${budget}`;
+    const url = RAW_URL.exec(text);
+    if (url)
+        return `contains a raw URL ("${url[0]}"); say "the address" and let the page carry the link`;
+    const slash = SLASH_BETWEEN_WORDS.exec(text);
+    if (slash)
+        return `contains a slash between words ("${slash[0]}"); write "or" or "and", or hyphenate`;
+    return null;
+}
+/** Device scale factor for a capture: 2 in a DOCS_GENERATE run, 1 otherwise.
+ *  The video spike found the manual's component crops 383 to 778 px wide; in
+ *  a 1080p frame they are soft, and no renderer recovers detail that was never
+ *  captured. A plain run writes no captures, so it keeps 1x and is unchanged.
+ *  One place for both tiers: guidesConfig and launchLiveBrowser read it. */
+export function captureScaleFactor() {
+    return process.env.DOCS_GENERATE === "1" ? 2 : 1;
+}
 /** The attributes Studio's shared MoQ player (norsk-studio-built-ins
  *  `lib/shared/moq-player`) stamps on the container it mounts into. `live`
  *  means the first video frame has decoded — not that the transport is up or
@@ -18,35 +49,161 @@ export function docsRoot() {
 export const MOQ_PHASE_ATTR = "data-moq-phase";
 export const MOQ_ERROR_ATTR = "data-moq-error";
 const LIVE_PICTURE_TIMEOUT_MS = 60_000;
+const LIVE_PICTURE_POLL_MS = 250;
+const LIVE_PICTURE_FRAME_GAP_MS = 500;
+/** Slates and modals a tile must not be showing. Products add their own via
+ *  `occluderSelectors`; the text pattern catches a slate rendered as DOM text. */
+export const DEFAULT_OCCLUDER_SELECTORS = ["[data-slate]", '[role="dialog"]', ".modal"];
+export const DEFAULT_OCCLUDER_TEXT = /temporarily unavailable|standby/i;
+export const FRAME_SAMPLE_W = 32;
+export const FRAME_SAMPLE_H = 18;
+const DEFAULT_PIXEL_DELTA = 6;
+const DEFAULT_MIN_CHANGED_FRACTION = 0.02;
+function changedFraction(a, b, pixelDelta) {
+    const n = Math.min(a.length, b.length);
+    if (n === 0)
+        return 0;
+    let changed = 0;
+    for (let i = 0; i < n; i++)
+        if (Math.abs(a[i] - b[i]) > pixelDelta)
+            changed++;
+    return changed / n;
+}
+function phaseReason(phase, error) {
+    if (phase === null)
+        return "not stamped — is a player mounted there?";
+    return phase === "error" && error ? `error: ${error}` : phase;
+}
+/** Rule on whether the tile is showing a live picture, naming the first
+ *  check that says it is not. */
+export function judgeLivePicture(evidence, motion = {}) {
+    if (evidence.phase !== "live")
+        return { live: false, check: "phase", reason: phaseReason(evidence.phase, evidence.error) };
+    if (evidence.coveredBy !== null)
+        return { live: false, check: "covered", reason: `the tile's centre is under "${evidence.coveredBy}"` };
+    if (evidence.occluders.length > 0)
+        return {
+            live: false,
+            check: "occluded",
+            reason: `a slate or modal is visible inside the tile: ${evidence.occluders.join(", ")}`,
+        };
+    if (evidence.frames === null)
+        return { live: false, check: "undrawable", reason: "no video or canvas inside the tile to sample" };
+    const need = motion.minChangedFraction ?? DEFAULT_MIN_CHANGED_FRACTION;
+    const moved = changedFraction(evidence.frames[0], evidence.frames[1], motion.pixelDelta ?? DEFAULT_PIXEL_DELTA);
+    if (moved < need)
+        return {
+            live: false,
+            check: "frozen",
+            reason: `the picture did not change across ${evidence.frameGapMs}ms (${(moved * 100).toFixed(1)}% of sampled pixels moved; need ${need * 100}%)`,
+        };
+    return { live: true };
+}
 /** The failure a guide sees when a tile never shows a picture: the tile, the
  *  phase it was stuck in and, for an error, the player's own reason — so a
  *  broken preview reads as what it is rather than as a timeout. Pure, so the
  *  wording is pinned without a browser. */
 export function livePictureFailure(selector, phase, error, timeoutMs) {
-    const state = phase === null
-        ? "not stamped — is a player mounted there?"
-        : phase === "error" && error
-            ? `error: ${error}`
-            : phase;
-    return `the MoQ preview at "${selector}" never decoded a frame in ${timeoutMs}ms (phase: ${state})`;
-}
-/** Block until the tile at `selector` reports a decoded frame, or fail saying
- *  why it did not. This is the wait a guide puts between "the source connected"
- *  and the capture: the player mounts at that moment, and a screenshot taken
- *  then is of a spinner. A wall-clock sleep would hide a broken preview; this
- *  turns it into a named failure. */
-export async function awaitLivePicture(page, selector, opts) {
-    const timeoutMs = opts?.timeoutMs ?? LIVE_PICTURE_TIMEOUT_MS;
-    try {
-        await page.waitForFunction(({ selector, attr }) => document.querySelector(selector)?.getAttribute(attr) === "live", { selector, attr: MOQ_PHASE_ATTR }, { timeout: timeoutMs });
+    return `the MoQ preview at "${selector}" never decoded a frame in ${timeoutMs}ms (phase: ${phaseReason(phase, error)})`;
+}
+/** The failure for whichever check the tile never passed. The phase check
+ *  keeps its original wording; the composite checks name themselves. */
+export function livePictureGateFailure(selector, verdict, timeoutMs) {
+    if (verdict.check === "phase") {
+        return `the MoQ preview at "${selector}" never decoded a frame in ${timeoutMs}ms (phase: ${verdict.reason})`;
     }
-    catch {
-        const [phase, error] = await page.evaluate(({ selector, phaseAttr, errorAttr }) => {
-            const el = document.querySelector(selector);
-            return [el?.getAttribute(phaseAttr) ?? null, el?.getAttribute(errorAttr) ?? null];
-        }, { selector, phaseAttr: MOQ_PHASE_ATTR, errorAttr: MOQ_ERROR_ATTR });
-        throw new Error(livePictureFailure(selector, phase, error, timeoutMs));
+    return `the MoQ preview at "${selector}" never showed a live picture in ${timeoutMs}ms (${verdict.check}: ${verdict.reason})`;
+}
+/** Gather, in the page, everything `judgeLivePicture` rules on. Stops at the
+ *  phase when the tile is not live: the frame samples cost `frameGapMs`. */
+async function collectLivePictureEvidence(page, selector, gate) {
+    return page.evaluate(async ({ selector, phaseAttr, errorAttr, occluderSelectors, occluderText, frameGapMs, w, h }) => {
+        const el = document.querySelector(selector);
+        const phase = el?.getAttribute(phaseAttr) ?? null;
+        const error = el?.getAttribute(errorAttr) ?? null;
+        const evidence = { phase, error, coveredBy: null, occluders: [], frames: null, frameGapMs };
+        if (!el || phase !== "live")
+            return evidence;
+        const describe = (n) => `${n.tagName.toLowerCase()}${n.id ? `#${n.id}` : ""}${Array.from(n.classList)
+            .map((c) => `.${c}`)
+            .join("")}`;
+        let r = el.getBoundingClientRect();
+        if (r.bottom < 0 || r.right < 0 || r.top > innerHeight || r.left > innerWidth) {
+            el.scrollIntoView({ block: "nearest", inline: "nearest" });
+            r = el.getBoundingClientRect();
+        }
+        const hit = document.elementFromPoint(r.left + r.width / 2, r.top + r.height / 2);
+        if (hit === null)
+            evidence.coveredBy = "nothing (is the tile off-screen?)";
+        else if (!el.contains(hit))
+            evidence.coveredBy = describe(hit);
+        const visible = (n) => n.getClientRects().length > 0 && getComputedStyle(n).visibility !== "hidden";
+        for (const sel of occluderSelectors) {
+            if (Array.from(el.querySelectorAll(sel)).some(visible))
+                evidence.occluders.push(sel);
+        }
+        if (occluderText) {
+            const match = new RegExp(occluderText.source, occluderText.flags).exec(el.innerText ?? "");
+            if (match)
+                evidence.occluders.push(`text "${match[0]}"`);
+        }
+        const drawable = el.matches("video, canvas") ? el : el.querySelector("video, canvas");
+        if (!drawable)
+            return evidence;
+        const scratch = document.createElement("canvas");
+        scratch.width = w;
+        scratch.height = h;
+        const ctx = scratch.getContext("2d");
+        if (!ctx)
+            return evidence;
+        const sample = () => {
+            ctx.drawImage(drawable, 0, 0, w, h);
+            const d = ctx.getImageData(0, 0, w, h).data;
+            const luma = [];
+            for (let i = 0; i < d.length; i += 4)
+                luma.push(Math.round(0.299 * d[i] + 0.587 * d[i + 1] + 0.114 * d[i + 2]));
+            return luma;
+        };
+        const first = sample();
+        await new Promise((resolve) => setTimeout(resolve, frameGapMs));
+        evidence.frames = [first, sample()];
+        return evidence;
+    }, {
+        selector,
+        phaseAttr: MOQ_PHASE_ATTR,
+        errorAttr: MOQ_ERROR_ATTR,
+        occluderSelectors: [...gate.occluderSelectors],
+        occluderText: gate.occluderText ? { source: gate.occluderText.source, flags: gate.occluderText.flags } : null,
+        frameGapMs: gate.frameGapMs,
+        w: FRAME_SAMPLE_W,
+        h: FRAME_SAMPLE_H,
+    });
+}
+/** Block until the tile at `selector` shows a live picture, or fail saying
+ *  which check it never passed. This is the wait a guide puts between "the
+ *  source connected" and the capture: the player mounts at that moment, and a
+ *  screenshot taken then is of a spinner. A wall-clock sleep would hide a
+ *  broken preview; this turns it into a named failure.
+ *
+ *  Live means: the player stamped `live`, nothing else sits at the tile's
+ *  centre, no slate or modal is visible inside it, and its picture moved
+ *  between two samples. The last two are what let a standby slate and a
+ *  modal over the hero through the phase check alone (2026-10-07). */
+export async function awaitLivePicture(page, selector, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? LIVE_PICTURE_TIMEOUT_MS;
+    const gate = {
+        occluderSelectors: opts.occluderSelectors ?? DEFAULT_OCCLUDER_SELECTORS,
+        occluderText: opts.occluderText === undefined ? DEFAULT_OCCLUDER_TEXT : opts.occluderText,
+        frameGapMs: opts.frameGapMs ?? LIVE_PICTURE_FRAME_GAP_MS,
+    };
+    const deadline = Date.now() + timeoutMs;
+    let verdict = judgeLivePicture(await collectLivePictureEvidence(page, selector, gate), opts);
+    while (!verdict.live && Date.now() < deadline) {
+        await page.waitForTimeout(LIVE_PICTURE_POLL_MS);
+        verdict = judgeLivePicture(await collectLivePictureEvidence(page, selector, gate), opts);
     }
+    if (!verdict.live)
+        throw new Error(livePictureGateFailure(selector, verdict, timeoutMs));
 }
 const SPOTLIGHT_ID = "docguide-spotlight";
 /** Dim the page except the target region, drawn as one fixed box whose oversized
@@ -113,8 +270,12 @@ export async function awaitFontsReady(page, timeoutMs = FONTS_READY_TIMEOUT_MS)
  *  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 });
+    if (treat?.livePicture) {
+        await awaitLivePicture(page, treat.livePicture, {
+            timeoutMs: treat.livePictureTimeoutMs,
+            ...treat.livePictureGate,
+        });
+    }
     // Wait for web fonts, else the snapshot catches a fallback font mid-swap --
     // but not forever (see awaitFontsReady).
     if (!(await awaitFontsReady(page))) {
@@ -157,24 +318,48 @@ export function renderUiMarkdown(title, entries) {
     }
     return lines.join("\n");
 }
+/** The budget a guide is held to: an explicit option, else the env var the
+ *  config factory exports, else the default. Read at call time, like docsRoot. */
+export function captionBudget(option) {
+    if (option !== undefined)
+        return option;
+    const fromEnv = Number(process.env.NORSK_DOCS_CAPTION_WORDS);
+    return Number.isInteger(fromEnv) && fromEnv > 0 ? fromEnv : DEFAULT_CAPTION_WORDS;
+}
+const TEXT_LABEL_WORDS = 6;
 export class DocGuide {
     slug;
     title;
+    options;
     entries = [];
     captureIndex = 0;
-    constructor(slug, title) {
+    constructor(slug, title, options = {}) {
         this.slug = slug;
         this.title = title;
+        this.options = options;
     }
     section(heading) {
         this.entries.push({ kind: "section", heading });
     }
     step(heading, description) {
+        this.lintCaption(`step "${heading}"`, description ? `${heading} ${description}` : heading);
         this.entries.push({ kind: "step", heading, description });
     }
     text(prose) {
+        const label = prose.split(/\s+/).slice(0, TEXT_LABEL_WORDS).join(" ");
+        this.lintCaption(`text "${label} ..."`, prose);
         this.entries.push({ kind: "text", prose });
     }
+    /** Only the DOCS_GENERATE run is published and narrated, so only it is held
+     *  to the spoken budget; a plain run of the guide asserts the UI and says
+     *  nothing about the prose. */
+    lintCaption(what, narrated) {
+        if (process.env.DOCS_GENERATE !== "1")
+            return;
+        const fault = captionFault(narrated, captionBudget(this.options.captionWords));
+        if (fault)
+            throw new Error(`doc-guide "${this.slug}": ${what} cannot be narrated: ${fault}`);
+    }
     /** Screenshot the page and write it immediately under the slug's docs dir. Pass
      *  a treatment to crop to one component or spotlight a region in context. */
     async capture(page, caption, treat) {

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

@@ -9,11 +9,17 @@ export interface GuidesConfigOptions {
         width: number;
         height: number;
     };
+    /** Pixel density of the captures. Default 2 in a DOCS_GENERATE run, 1
+     *  otherwise (see captureScaleFactor): crops shot at 1x are soft in a video frame. */
+    deviceScaleFactor?: number;
     /** webServer command. Default `bunx vite --port <port> --strictPort --host 127.0.0.1`. */
     command?: string;
     /** Playwright testDir. Default "./tests/guides". */
     testDir?: string;
     /** Per-test timeout in ms. Default 60_000. */
     timeout?: number;
+    /** Spoken-word budget for one step's text in a DOCS_GENERATE run (see
+     *  DocGuide). Exported as NORSK_DOCS_CAPTION_WORDS. Default: the dev-kit's 50. */
+    captionWords?: number;
 }
 export declare function guidesConfig(opts: GuidesConfigOptions): PlaywrightTestConfig;

package/doc-guide/guides-config.js

@@ -1,8 +1,11 @@
 import { defineConfig } from "@playwright/test";
+import { captureScaleFactor } from "./doc-guide.js";
 export function guidesConfig(opts) {
     // Exported before the test files import the dev-kit DocGuide, so its deferred
     // docsRoot() resolves to the repo-level dir rather than <package>/docs/generated.
     process.env.NORSK_DOCS_ROOT = opts.docsRoot;
+    if (opts.captionWords !== undefined)
+        process.env.NORSK_DOCS_CAPTION_WORDS = String(opts.captionWords);
     const baseURL = `http://127.0.0.1:${opts.port}`;
     const command = opts.command ?? `bunx vite --port ${opts.port} --strictPort --host 127.0.0.1`;
     return defineConfig({
@@ -14,6 +17,7 @@ export function guidesConfig(opts) {
             browserName: "chromium",
             headless: true,
             viewport: opts.viewport ?? { width: 1440, height: 960 },
+            deviceScaleFactor: opts.deviceScaleFactor ?? captureScaleFactor(),
             ...(process.env.BROWSER_FOR_TESTING && { launchOptions: { executablePath: process.env.BROWSER_FOR_TESTING } }),
         },
         webServer: {

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

@@ -12,4 +12,6 @@ export declare function launchLiveBrowser(opts?: {
         width: number;
         height: number;
     };
+    /** Default: captureScaleFactor() -- 2 in a DOCS_GENERATE run, 1 otherwise. */
+    deviceScaleFactor?: number;
 }): Promise<LiveBrowser>;

package/doc-guide/live-browser.js

@@ -5,6 +5,7 @@
 // chromium the fixture tier uses, via BROWSER_FOR_TESTING) rather than go through
 // the test-runner's webServer model.
 import { chromium } from "@playwright/test";
+import { captureScaleFactor } from "./doc-guide.js";
 /** Launch headless chromium for a live-dashboard capture. Uses the nix-provided
  *  chromium (BROWSER_FOR_TESTING) so no Playwright browser download is needed;
  *  --no-sandbox because the nix chromium has no setuid sandbox helper. */
@@ -15,7 +16,10 @@ export async function launchLiveBrowser(opts) {
     }
     const browser = await chromium.launch({ executablePath, args: ["--no-sandbox"] });
     const viewport = opts?.viewport ?? { width: 1440, height: 960 };
-    const context = await browser.newContext({ viewport, deviceScaleFactor: 1 });
+    const context = await browser.newContext({
+        viewport,
+        deviceScaleFactor: opts?.deviceScaleFactor ?? captureScaleFactor(),
+    });
     const page = await context.newPage();
     return { browser, context, page };
 }