@norskvideo/ctl-dev-kit 0.1.82 → 0.1.83

package/conventions/docs.md

@@ -82,6 +82,17 @@ Per-step treatments (`CaptureTreatment`, from the doc-guide library):
   component renders, not on incidental structure.
 - **`spotlight`** — the whole screen with one region lit and everything else
   dimmed, for "look here, in context."
+- **`livePicture`** — a live video tile the shot must not be taken without.
+  Studio's shared MoQ player (`norsk-studio-built-ins/lib/shared/moq-player`)
+  stamps `data-moq-phase` on the container it mounts into: `connecting`, then
+  `live` on the first decoded frame, or `error` with the reason in
+  `data-moq-error`. The player mounts at the moment the source connects, which
+  is also when a guide's "it's running" assertion passes — so a capture taken
+  then is of a spinner, and a sleep only hides a preview that is broken. Name
+  the tile here, or call `awaitLivePicture(page, selector)` before the capture
+  (the verify run skips captures, so an explicit wait is also the assertion);
+  either way a tile that never shows a picture fails the guide, naming the
+  phase it was stuck in and the player's own error.
 
 ## The toolchain
 

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

@@ -26,13 +26,42 @@ export interface UiFixture {
 export declare function docsRoot(): string;
 /** 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. */
+ *  named region and outlines it. Omit both for a plain full-page capture.
+ *  `livePicture` names a MoQ video tile the shot must not be taken without —
+ *  see `awaitLivePicture`. */
 export interface CaptureTreatment {
     crop?: string;
     spotlight?: string;
     /** Slack in px around a spotlight region before the dimming starts. */
     pad?: number;
+    /** A live video tile (Studio's shared MoQ player's container) that has to be
+     *  showing a picture before the capture is taken. */
+    livePicture?: string;
+    /** 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 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
+ *  the catalog arrived, both of which can hold for seconds with nothing on
+ *  screen, which is exactly what a capture taken on a clock shows. */
+export declare const MOQ_PHASE_ATTR = "data-moq-phase";
+export declare const MOQ_ERROR_ATTR = "data-moq-error";
+export type MoqPhase = "connecting" | "live" | "error";
+/** 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>;
 /** 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

@@ -10,6 +10,44 @@ export function docsRoot() {
         return isAbsolute(override) ? override : resolve(process.cwd(), override);
     return resolve(process.cwd(), "docs/generated");
 }
+/** 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
+ *  the catalog arrived, both of which can hold for seconds with nothing on
+ *  screen, which is exactly what a capture taken on a clock shows. */
+export const MOQ_PHASE_ATTR = "data-moq-phase";
+export const MOQ_ERROR_ATTR = "data-moq-error";
+const LIVE_PICTURE_TIMEOUT_MS = 60_000;
+/** 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 });
+    }
+    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));
+    }
+}
 const SPOTLIGHT_ID = "docguide-spotlight";
 /** Dim the page except the target region, drawn as one fixed box whose oversized
  *  box-shadow does the dimming — appended to <body> so no ancestor `overflow`
@@ -45,6 +83,8 @@ async function spotlightOff(page) {
  *  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);
     if (treat?.crop)

package/package.json

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