@norskvideo/ctl-dev-kit 0.1.24 → 0.1.25

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

@@ -0,0 +1,56 @@
+export type Step = {
+    slug: string;
+    file: string;
+    head: string;
+    desc: string;
+};
+export type ManualPage = {
+    id: string;
+    nav: string;
+    title: string;
+    kind: "fn" | "ex";
+    tag?: string;
+    intro: string;
+    steps: Step[];
+    links: string[];
+    thin?: boolean;
+};
+export interface ManualOverview {
+    /** The overview <h1>. */
+    headline: string;
+    /** The lead paragraph under it. */
+    lead: string;
+    /** The hero capture (a representative shot) and its caption. */
+    hero: {
+        slug: string;
+        file: string;
+        alt: string;
+        caption: string;
+    };
+    /** Left column heading of the two-up index. Default "By function". */
+    byFunctionHeading?: string;
+    /** Right column heading. Default "By example". */
+    byExampleHeading?: string;
+    /** The small print under the right column heading. */
+    byExampleIntro: string;
+}
+export interface ManualSpec {
+    /** Sidebar wordmark + document brand. */
+    brand: string;
+    /** The full <title> for both the fragment and the standalone document. */
+    title: string;
+    overview: ManualOverview;
+    functionality: ManualPage[];
+    examples: ManualPage[];
+}
+export interface BuildManualResult {
+    /** Artifact-ready fragment (no doctype/head/body). */
+    indexHtml: string;
+    /** Complete standalone document wrapping the fragment. */
+    standaloneHtml: string;
+    /** `<slug>/<file>` of every referenced capture not found on disk. */
+    missing: string[];
+}
+export declare function buildManual(spec: ManualSpec, opts: {
+    docsRoot: string;
+}): BuildManualResult;

package/doc-guide/{build-manual.ts → build-manual.js}

@@ -13,120 +13,63 @@
 // Product-specific content — the page arrays, the overview copy, the brand — is
 // supplied by the caller in `ManualSpec`; everything structural (layout, CSS,
 // routing) lives here so every product's manual looks and behaves the same.
-
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-
-export type Step = { slug: string; file: string; head: string; desc: string };
-
-export type ManualPage = {
-  id: string;
-  nav: string;
-  title: string;
-  kind: "fn" | "ex";
-  tag?: string;
-  intro: string;
-  steps: Step[];
-  links: string[];
-  thin?: boolean;
-};
-
-export interface ManualOverview {
-  /** The overview <h1>. */
-  headline: string;
-  /** The lead paragraph under it. */
-  lead: string;
-  /** The hero capture (a representative shot) and its caption. */
-  hero: { slug: string; file: string; alt: string; caption: string };
-  /** Left column heading of the two-up index. Default "By function". */
-  byFunctionHeading?: string;
-  /** Right column heading. Default "By example". */
-  byExampleHeading?: string;
-  /** The small print under the right column heading. */
-  byExampleIntro: string;
-}
-
-export interface ManualSpec {
-  /** Sidebar wordmark + document brand. */
-  brand: string;
-  /** The full <title> for both the fragment and the standalone document. */
-  title: string;
-  overview: ManualOverview;
-  functionality: ManualPage[];
-  examples: ManualPage[];
-}
-
-export interface BuildManualResult {
-  /** Artifact-ready fragment (no doctype/head/body). */
-  indexHtml: string;
-  /** Complete standalone document wrapping the fragment. */
-  standaloneHtml: string;
-  /** `<slug>/<file>` of every referenced capture not found on disk. */
-  missing: string[];
-}
-
-const esc = (s: string) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
-
+const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 /** Resize a captured PNG to <=1100px wide JPEG and return a data URI. Missing
  *  captures become a labelled placeholder so the manual still builds. */
-function makeUri(docsRoot: string, slug: string, file: string, missing: string[]): string {
-  const path = join(docsRoot, slug, file);
-  if (!existsSync(path)) {
-    missing.push(`${slug}/${file}`);
-    const label = esc(`missing: ${slug}/${file}`);
-    const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="880" height="200"><rect width="100%" height="100%" fill="#1a2230"/><text x="50%" y="50%" fill="#6b7787" font-family="monospace" font-size="15" text-anchor="middle" dominant-baseline="middle">${label}</text></svg>`;
-    return `data:image/svg+xml;base64,${Buffer.from(svg).toString("base64")}`;
-  }
-  const r = spawnSync("magick", [path, "-resize", "1100x>", "-quality", "82", "jpg:-"], {
-    maxBuffer: 64 * 1024 * 1024,
-  });
-  if (r.status !== 0 || !r.stdout?.length) {
-    throw new Error(`magick failed for ${path}: ${r.stderr?.toString() ?? "no output"}`);
-  }
-  return `data:image/jpeg;base64,${r.stdout.toString("base64")}`;
+function makeUri(docsRoot, slug, file, missing) {
+    const path = join(docsRoot, slug, file);
+    if (!existsSync(path)) {
+        missing.push(`${slug}/${file}`);
+        const label = esc(`missing: ${slug}/${file}`);
+        const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="880" height="200"><rect width="100%" height="100%" fill="#1a2230"/><text x="50%" y="50%" fill="#6b7787" font-family="monospace" font-size="15" text-anchor="middle" dominant-baseline="middle">${label}</text></svg>`;
+        return `data:image/svg+xml;base64,${Buffer.from(svg).toString("base64")}`;
+    }
+    const r = spawnSync("magick", [path, "-resize", "1100x>", "-quality", "82", "jpg:-"], {
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    if (r.status !== 0 || !r.stdout?.length) {
+        throw new Error(`magick failed for ${path}: ${r.stderr?.toString() ?? "no output"}`);
+    }
+    return `data:image/jpeg;base64,${r.stdout.toString("base64")}`;
 }
-
-export function buildManual(spec: ManualSpec, opts: { docsRoot: string }): BuildManualResult {
-  const { docsRoot } = opts;
-  const missing: string[] = [];
-  const uri = (slug: string, file: string) => makeUri(docsRoot, slug, file, missing);
-
-  const FN = spec.functionality;
-  const EX = spec.examples;
-  const ALL = [...FN, ...EX];
-  const byId = new Map(ALL.map((p) => [p.id, p]));
-
-  function pageHtml(p: ManualPage): string {
-    const steps = p.steps
-      .map(
-        (s, i) => `<li class="step">
+export function buildManual(spec, opts) {
+    const { docsRoot } = opts;
+    const missing = [];
+    const uri = (slug, file) => makeUri(docsRoot, slug, file, missing);
+    const FN = spec.functionality;
+    const EX = spec.examples;
+    const ALL = [...FN, ...EX];
+    const byId = new Map(ALL.map((p) => [p.id, p]));
+    function pageHtml(p) {
+        const steps = p.steps
+            .map((s, i) => `<li class="step">
       <div class="stinfo"><span class="stnum">${String(i + 1).padStart(2, "0")}</span><div><h3>${esc(s.head)}</h3><p>${esc(s.desc)}</p></div></div>
       <div class="shot"><img loading="lazy" src="${uri(s.slug, s.file)}" alt="${esc(s.head)}"></div>
-    </li>`,
-      )
-      .join("\n");
-    const links = p.links.length
-      ? `<div class="xlinks"><span class="xlab">${p.kind === "fn" ? "Seen in" : "Uses"}</span>${p.links
-          .map((id) => {
-            const t = byId.get(id);
-            return t ? `<a href="#${id}" class="chip">${esc(t.nav)}</a>` : "";
-          })
-          .join("")}</div>`
-      : "";
-    const thin = p.thin
-      ? `<p class="thin">More of this walkthrough is coming — this deployment shape has one screen captured so far.</p>`
-      : "";
-    return `<article class="page" id="${p.id}">
+    </li>`)
+            .join("\n");
+        const links = p.links.length
+            ? `<div class="xlinks"><span class="xlab">${p.kind === "fn" ? "Seen in" : "Uses"}</span>${p.links
+                .map((id) => {
+                const t = byId.get(id);
+                return t ? `<a href="#${id}" class="chip">${esc(t.nav)}</a>` : "";
+            })
+                .join("")}</div>`
+            : "";
+        const thin = p.thin
+            ? `<p class="thin">More of this walkthrough is coming — this deployment shape has one screen captured so far.</p>`
+            : "";
+        return `<article class="page" id="${p.id}">
     <div class="phead"><span class="kind ${p.kind}">${p.kind === "fn" ? "Functionality" : "Example deployment"}</span><h1>${esc(p.title)}</h1>${p.tag ? `<div class="ptag mono">${esc(p.tag)}</div>` : ""}</div>
     <p class="lead">${esc(p.intro)}</p>
     <ol class="steps">${steps}</ol>
     ${thin}${links}
   </article>`;
-  }
-
-  const ov = spec.overview;
-  const overview = `<article class="page" id="overview">
+    }
+    const ov = spec.overview;
+    const overview = `<article class="page" id="overview">
   <div class="phead"><span class="kind ov">Overview</span><h1>${esc(ov.headline)}</h1></div>
   <p class="lead">${esc(ov.lead)}</p>
   <div class="heroshot"><div class="shot"><img src="${uri(ov.hero.slug, ov.hero.file)}" alt="${esc(ov.hero.alt)}"></div><p class="hcap">${esc(ov.hero.caption)}</p></div>
@@ -135,13 +78,11 @@ export function buildManual(spec: ManualSpec, opts: { docsRoot: string }): Build
     <div><h2>${esc(ov.byExampleHeading ?? "By example")}</h2><p class="mini">${esc(ov.byExampleIntro)}</p><div class="linklist">${EX.map((p) => `<a href="#${p.id}">${esc(p.nav)}</a>`).join("")}</div></div>
   </div>
 </article>`;
-
-  const nav = `
+    const nav = `
   <a href="#overview" data-nav class="ovlink">Overview</a>
   <div class="ngroup"><div class="ghead">Functionality</div>${FN.map((p) => `<a href="#${p.id}" data-nav>${esc(p.nav)}</a>`).join("")}</div>
   <div class="ngroup"><div class="ghead">Examples <span class="ct">${EX.length}</span></div>${EX.map((p) => `<a href="#${p.id}" data-nav>${esc(p.nav)}</a>`).join("")}</div>`;
-
-  const html = `<title>${esc(spec.title)}</title>
+    const html = `<title>${esc(spec.title)}</title>
 <style>
 :root{--bg:#0a0d12;--bg2:#0c1118;--surf:#131923;--ink:#eaeff5;--dim:#939dab;--faint:#5f6a79;
   --line:#212a36;--accent:#54d6cf;--measure:64ch}
@@ -227,8 +168,7 @@ ${ALL.map(pageHtml).join("\n")}
   window.addEventListener('hashchange',show);show();
 })();
 </script>`;
-
-  const standaloneHtml = `<!doctype html>
+    const standaloneHtml = `<!doctype html>
 <html lang="en">
 <head>
 <meta charset="utf-8" />
@@ -239,6 +179,5 @@ ${ALL.map(pageHtml).join("\n")}
 ${html}
 </body>
 </html>`;
-
-  return { indexHtml: html, standaloneHtml, missing };
+    return { indexHtml: html, standaloneHtml, missing };
 }

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

@@ -0,0 +1,57 @@
+import type { Page } from "@playwright/test";
+export type UiEntry = {
+    kind: "section";
+    heading: string;
+} | {
+    kind: "step";
+    heading: string;
+    description?: string;
+} | {
+    kind: "text";
+    prose: string;
+} | {
+    kind: "capture";
+    caption: string;
+    filename: string;
+};
+export interface UiFixture {
+    type: "ui";
+    title: string;
+    entries: UiEntry[];
+}
+/** Resolve the repo-level docs/generated root. NORSK_DOCS_ROOT wins (absolute or
+ *  relative to cwd); otherwise <cwd>/docs/generated, which is correct for runners
+ *  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;
+/** 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. */
+export interface CaptureTreatment {
+    crop?: string;
+    spotlight?: string;
+    /** Slack in px around a spotlight region before the dimming starts. */
+    pad?: number;
+}
+/** 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 declare function screenshotFor(page: Page, treat?: CaptureTreatment): Promise<Buffer>;
+/** 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 declare class DocGuide {
+    private slug;
+    private title;
+    private entries;
+    private captureIndex;
+    constructor(slug: string, title: string);
+    section(heading: string): void;
+    step(heading: string, description?: string): void;
+    text(prose: string): void;
+    /** 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>;
+    /** Write entries.json + the rendered index.md under docs/generated/<slug>/. */
+    flush(): Promise<void>;
+}

package/doc-guide/doc-guide.js

@@ -0,0 +1,128 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+/** Resolve the repo-level docs/generated root. NORSK_DOCS_ROOT wins (absolute or
+ *  relative to cwd); otherwise <cwd>/docs/generated, which is correct for runners
+ *  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 function docsRoot() {
+    const override = process.env.NORSK_DOCS_ROOT;
+    if (override)
+        return isAbsolute(override) ? override : resolve(process.cwd(), override);
+    return resolve(process.cwd(), "docs/generated");
+}
+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`
+ *  clips it. Scrolls the target into view first so the lit region is on-screen. */
+async function spotlightOn(page, selector, pad) {
+    await page.locator(selector).first().scrollIntoViewIfNeeded();
+    await page.evaluate(({ selector, pad, id }) => {
+        const el = document.querySelector(selector);
+        if (!el)
+            throw new Error(`spotlight target not found: ${selector}`);
+        const r = el.getBoundingClientRect();
+        const box = document.createElement("div");
+        box.id = id;
+        Object.assign(box.style, {
+            position: "fixed",
+            left: `${Math.max(0, r.left - pad)}px`,
+            top: `${Math.max(0, r.top - pad)}px`,
+            width: `${r.width + pad * 2}px`,
+            height: `${r.height + pad * 2}px`,
+            border: "2px solid #54d6cf",
+            borderRadius: "10px",
+            boxShadow: "0 0 0 4000px rgba(6,9,13,0.62)",
+            zIndex: "2147483647",
+            pointerEvents: "none",
+        });
+        document.body.appendChild(box);
+    }, { selector, pad, id: SPOTLIGHT_ID });
+}
+async function spotlightOff(page) {
+    await page.evaluate((id) => document.getElementById(id)?.remove(), SPOTLIGHT_ID);
+}
+/** 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) {
+    // Wait for web fonts, else the snapshot catches a fallback font mid-swap.
+    await page.evaluate(() => document.fonts.ready);
+    if (treat?.crop)
+        return page.locator(treat.crop).first().screenshot();
+    if (treat?.spotlight) {
+        await spotlightOn(page, treat.spotlight, treat.pad ?? 8);
+        try {
+            return await page.screenshot();
+        }
+        finally {
+            await spotlightOff(page);
+        }
+    }
+    return page.screenshot({ fullPage: true });
+}
+/** Pure markdown assembly — exposed so a render step can re-emit markdown from a
+ * stored entries.json without re-running the browser. */
+export function renderUiMarkdown(title, entries) {
+    const lines = ["---", `title: ${title}`, "---", "", `# ${title}`, ""];
+    for (const entry of entries) {
+        switch (entry.kind) {
+            case "section":
+                lines.push(`## ${entry.heading}`, "");
+                break;
+            case "step":
+                lines.push(`### ${entry.heading}`, "");
+                if (entry.description)
+                    lines.push(entry.description, "");
+                break;
+            case "text":
+                lines.push(entry.prose, "");
+                break;
+            case "capture":
+                lines.push(`![${entry.caption}](./${entry.filename})`, "");
+                break;
+        }
+    }
+    return lines.join("\n");
+}
+export class DocGuide {
+    slug;
+    title;
+    entries = [];
+    captureIndex = 0;
+    constructor(slug, title) {
+        this.slug = slug;
+        this.title = title;
+    }
+    section(heading) {
+        this.entries.push({ kind: "section", heading });
+    }
+    step(heading, description) {
+        this.entries.push({ kind: "step", heading, description });
+    }
+    text(prose) {
+        this.entries.push({ kind: "text", prose });
+    }
+    /** 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) {
+        if (process.env.DOCS_GENERATE !== "1")
+            return;
+        this.captureIndex++;
+        const filename = `${this.slug}-${String(this.captureIndex).padStart(3, "0")}.png`;
+        const buffer = await screenshotFor(page, treat);
+        const outDir = join(docsRoot(), this.slug);
+        mkdirSync(outDir, { recursive: true });
+        writeFileSync(join(outDir, filename), buffer);
+        this.entries.push({ kind: "capture", caption, filename });
+    }
+    /** Write entries.json + the rendered index.md under docs/generated/<slug>/. */
+    async flush() {
+        if (process.env.DOCS_GENERATE !== "1")
+            return;
+        const outDir = join(docsRoot(), this.slug);
+        mkdirSync(outDir, { recursive: true });
+        const fixture = { type: "ui", title: this.title, entries: this.entries };
+        writeFileSync(join(outDir, "entries.json"), `${JSON.stringify(fixture, null, 2)}\n`);
+        writeFileSync(join(outDir, "index.md"), renderUiMarkdown(this.title, this.entries));
+    }
+}

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

@@ -0,0 +1,19 @@
+import { type PlaywrightTestConfig } from "@playwright/test";
+export interface GuidesConfigOptions {
+    /** Vite port. Pick one clear of the product's dev servers and sibling sessions. */
+    port: number;
+    /** Absolute path to the repo-level docs/generated dir. Exported as NORSK_DOCS_ROOT. */
+    docsRoot: string;
+    /** Capture viewport. Default 1440x960. */
+    viewport?: {
+        width: number;
+        height: 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;
+}
+export declare function guidesConfig(opts: GuidesConfigOptions): PlaywrightTestConfig;

package/doc-guide/guides-config.js

@@ -0,0 +1,28 @@
+import { defineConfig } from "@playwright/test";
+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;
+    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({
+        testDir: opts.testDir ?? "./tests/guides",
+        workers: 1,
+        timeout: opts.timeout ?? 60_000,
+        use: {
+            baseURL,
+            browserName: "chromium",
+            headless: true,
+            viewport: opts.viewport ?? { width: 1440, height: 960 },
+            ...(process.env.BROWSER_FOR_TESTING && { launchOptions: { executablePath: process.env.BROWSER_FOR_TESTING } }),
+        },
+        webServer: {
+            command,
+            url: baseURL,
+            reuseExistingServer: !process.env.CI,
+            timeout: 120_000, // cold CI runners are slow to first-serve
+            stdout: "pipe",
+            stderr: "pipe",
+        },
+    });
+}

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

@@ -0,0 +1,16 @@
+export interface InstanceProxy {
+    /** Origin of the proxy, e.g. http://localhost:53421 */
+    origin: string;
+    /** Full dashboard URL for a hash-routed page, under the advertised prefix. */
+    dashboardUrl: (page?: string) => string;
+    stop: () => void;
+}
+/** Start a reverse proxy that serves `${prefix}/…` by forwarding `/…` to
+ *  studioHostPort. `prefix` equals the instance's advertised `studioUrlPrefix`
+ *  (`/instance/<instanceId>`); `dashboardKey` is the product's baked dashboard
+ *  path segment (the dashboard is served at `/dashboard/<dashboardKey>/`). */
+export declare function startInstanceProxy(opts: {
+    studioHostPort: number;
+    instanceId: string;
+    dashboardKey: string;
+}): InstanceProxy;

package/doc-guide/instance-proxy.js

@@ -0,0 +1,90 @@
+// A tiny per-instance reverse proxy for the engine-tier doc-guides.
+//
+// A product's baked operator dashboard is built to run behind the runner's oauth2
+// proxy: its `env` endpoint advertises instance-scoped paths
+// (`apiBasePath: /instance/<id>/live/api`, `wsBasePath: /instance/<id>/live`).
+// The harness, though, publishes Studio DIRECTLY on studioHostPort with no
+// `/instance/<id>` prefix — so those advertised paths 404 and the console never
+// leaves its "workflow starting up" splash.
+//
+// Rather than drag the whole oauth2 proxy + TLS + port 443 into a doc run, this
+// serves the dashboard under exactly the prefix `env` advertises and strips it
+// before forwarding to studioHostPort — for both HTTP and the live-state
+// WebSocket (`useLiveComponent`), which is what carries programReceiving / audio
+// levels and therefore the ON AIR badge. Plain HTTP, ephemeral port, self-owned.
+// Response headers that describe the upstream transfer encoding; fetch() has
+// already decoded the body, so forwarding these would misdescribe what we send.
+const STRIP_RESPONSE_HEADERS = ["content-encoding", "content-length", "transfer-encoding"];
+/** Start a reverse proxy that serves `${prefix}/…` by forwarding `/…` to
+ *  studioHostPort. `prefix` equals the instance's advertised `studioUrlPrefix`
+ *  (`/instance/<instanceId>`); `dashboardKey` is the product's baked dashboard
+ *  path segment (the dashboard is served at `/dashboard/<dashboardKey>/`). */
+export function startInstanceProxy(opts) {
+    const prefix = `/instance/${opts.instanceId}`;
+    const httpUpstream = `http://localhost:${opts.studioHostPort}`;
+    const strip = (pathname) => pathname === prefix ? "/" : pathname.startsWith(`${prefix}/`) ? pathname.slice(prefix.length) : pathname;
+    const server = Bun.serve({
+        port: 0,
+        async fetch(req, srv) {
+            const u = new URL(req.url);
+            const path = strip(u.pathname);
+            if (req.headers.get("upgrade")?.toLowerCase() === "websocket") {
+                const upstreamUrl = `ws://localhost:${opts.studioHostPort}${path}${u.search}`;
+                const ok = srv.upgrade(req, { data: { upstreamUrl, upstream: null, queue: [] } });
+                return ok ? undefined : new Response("ws upgrade failed", { status: 400 });
+            }
+            const headers = new Headers(req.headers);
+            headers.delete("host");
+            const body = req.method === "GET" || req.method === "HEAD" ? undefined : await req.arrayBuffer();
+            const upstream = await fetch(`${httpUpstream}${path}${u.search}`, {
+                method: req.method,
+                headers,
+                body,
+                redirect: "manual",
+            });
+            const outHeaders = new Headers(upstream.headers);
+            for (const h of STRIP_RESPONSE_HEADERS)
+                outHeaders.delete(h);
+            return new Response(upstream.body, { status: upstream.status, headers: outHeaders });
+        },
+        websocket: {
+            open(ws) {
+                const up = new WebSocket(ws.data.upstreamUrl);
+                up.binaryType = "arraybuffer";
+                ws.data.upstream = up;
+                up.onopen = () => {
+                    for (const m of ws.data.queue)
+                        up.send(m);
+                    ws.data.queue = [];
+                };
+                up.onmessage = (e) => ws.send(e.data);
+                up.onclose = (e) => ws.close(e.code || 1000, e.reason);
+                up.onerror = () => {
+                    try {
+                        ws.close();
+                    }
+                    catch { }
+                };
+            },
+            message(ws, message) {
+                const up = ws.data.upstream;
+                if (up && up.readyState === WebSocket.OPEN)
+                    up.send(message);
+                else
+                    ws.data.queue.push(message);
+            },
+            close(ws) {
+                try {
+                    ws.data.upstream?.close();
+                }
+                catch { }
+            },
+        },
+    });
+    const origin = `http://localhost:${server.port}`;
+    return {
+        origin,
+        dashboardUrl: (page = "onair") => `${origin}${prefix}/dashboard/${opts.dashboardKey}/#/${page}`,
+        stop: () => server.stop(true),
+    };
+}

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

@@ -0,0 +1,15 @@
+import { type Browser, type BrowserContext, type Page } from "@playwright/test";
+export interface LiveBrowser {
+    browser: Browser;
+    context: BrowserContext;
+    page: Page;
+}
+/** 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. */
+export declare function launchLiveBrowser(opts?: {
+    viewport?: {
+        width: number;
+        height: number;
+    };
+}): Promise<LiveBrowser>;

package/doc-guide/live-browser.js

@@ -0,0 +1,21 @@
+// Engine-tier doc-guide browser support. The fixture-tier guides run under the
+// @playwright/test runner against a Vite dev server; the engine tier instead
+// drives a REAL launched instance from inside a bun:test that already owns the
+// product harness lifecycle. So we launch a raw chromium here (the same nixpkgs
+// chromium the fixture tier uses, via BROWSER_FOR_TESTING) rather than go through
+// the test-runner's webServer model.
+import { chromium } from "@playwright/test";
+/** 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. */
+export async function launchLiveBrowser(opts) {
+    const executablePath = process.env.BROWSER_FOR_TESTING;
+    if (!executablePath) {
+        throw new Error("BROWSER_FOR_TESTING is unset — run inside `nix develop` so chromium is on offer");
+    }
+    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 page = await context.newPage();
+    return { browser, context, page };
+}

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@norskvideo/ctl-dev-kit",
-  "version": "0.1.24",
+  "version": "0.1.25",
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
     "./testing/invariants": "./testing/invariants.ts",
     "./testing/byte-snapshot": "./testing/byte-snapshot.ts",
     "./create-product": "./create-product/create-product.ts",
-    "./doc-guide": "./doc-guide/doc-guide.ts",
-    "./doc-guide/build-manual": "./doc-guide/build-manual.ts",
-    "./doc-guide/guides-config": "./doc-guide/guides-config.ts",
-    "./doc-guide/instance-proxy": "./doc-guide/instance-proxy.ts",
-    "./doc-guide/live-browser": "./doc-guide/live-browser.ts"
+    "./doc-guide": "./doc-guide/doc-guide.js",
+    "./doc-guide/build-manual": "./doc-guide/build-manual.js",
+    "./doc-guide/guides-config": "./doc-guide/guides-config.js",
+    "./doc-guide/instance-proxy": "./doc-guide/instance-proxy.js",
+    "./doc-guide/live-browser": "./doc-guide/live-browser.js"
   },
   "bin": {
     "ctl-dev-kit": "./create-product/cli.ts"

package/doc-guide/doc-guide.ts

@@ -1,174 +0,0 @@
-import { mkdirSync, writeFileSync } from "node:fs";
-import { isAbsolute, join, resolve } from "node:path";
-import type { Page } from "@playwright/test";
-
-// Shared support for a product repo's Playwright/engine doc-guides. A guide drives
-// a real surface (a configure SPA, an operator dashboard, a launched instance) and
-// narrates itself; entries render to an illustrated markdown manual under
-// <repo>/docs/generated/<slug>/. Screenshots can never depict a UI that doesn't
-// exist, because they come from a real, asserted run.
-//
-// Extracted from norsk-commentary (which took it from norsk-ctl) into the dev kit
-// so every ctl product shoots its manual the same way. The one thing that had to
-// change on the way in: the old copy resolved docs/generated RELATIVE TO ITS OWN
-// FILE, which worked only while it lived in the repo. Living in node_modules it
-// cannot, so the docs root is now explicit — NORSK_DOCS_ROOT if set, else
-// <cwd>/docs/generated. A fixture runner whose cwd is a package subdir (e.g.
-// dashboards/<slug>) MUST export NORSK_DOCS_ROOT to the repo-level dir; the
-// guidesConfig() factory does this for you. Resolution is deferred to call time
-// so the env var need only be set before the first capture, not before import.
-
-export type UiEntry =
-  | { kind: "section"; heading: string }
-  | { kind: "step"; heading: string; description?: string }
-  | { kind: "text"; prose: string }
-  | { kind: "capture"; caption: string; filename: string };
-
-export interface UiFixture {
-  type: "ui";
-  title: string;
-  entries: UiEntry[];
-}
-
-/** Resolve the repo-level docs/generated root. NORSK_DOCS_ROOT wins (absolute or
- *  relative to cwd); otherwise <cwd>/docs/generated, which is correct for runners
- *  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 function docsRoot(): string {
-  const override = process.env.NORSK_DOCS_ROOT;
-  if (override) return isAbsolute(override) ? override : resolve(process.cwd(), override);
-  return resolve(process.cwd(), "docs/generated");
-}
-
-/** 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. */
-export interface CaptureTreatment {
-  crop?: string;
-  spotlight?: string;
-  /** Slack in px around a spotlight region before the dimming starts. */
-  pad?: number;
-}
-
-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`
- *  clips it. Scrolls the target into view first so the lit region is on-screen. */
-async function spotlightOn(page: Page, selector: string, pad: number): Promise<void> {
-  await page.locator(selector).first().scrollIntoViewIfNeeded();
-  await page.evaluate(
-    ({ selector, pad, id }) => {
-      const el = document.querySelector(selector);
-      if (!el) throw new Error(`spotlight target not found: ${selector}`);
-      const r = el.getBoundingClientRect();
-      const box = document.createElement("div");
-      box.id = id;
-      Object.assign(box.style, {
-        position: "fixed",
-        left: `${Math.max(0, r.left - pad)}px`,
-        top: `${Math.max(0, r.top - pad)}px`,
-        width: `${r.width + pad * 2}px`,
-        height: `${r.height + pad * 2}px`,
-        border: "2px solid #54d6cf",
-        borderRadius: "10px",
-        boxShadow: "0 0 0 4000px rgba(6,9,13,0.62)",
-        zIndex: "2147483647",
-        pointerEvents: "none",
-      } satisfies Partial<CSSStyleDeclaration>);
-      document.body.appendChild(box);
-    },
-    { selector, pad, id: SPOTLIGHT_ID },
-  );
-}
-
-async function spotlightOff(page: Page): Promise<void> {
-  await page.evaluate((id) => document.getElementById(id)?.remove(), SPOTLIGHT_ID);
-}
-
-/** 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: Page, treat?: CaptureTreatment): Promise<Buffer> {
-  // Wait for web fonts, else the snapshot catches a fallback font mid-swap.
-  await page.evaluate(() => document.fonts.ready);
-  if (treat?.crop) return page.locator(treat.crop).first().screenshot();
-  if (treat?.spotlight) {
-    await spotlightOn(page, treat.spotlight, treat.pad ?? 8);
-    try {
-      return await page.screenshot();
-    } finally {
-      await spotlightOff(page);
-    }
-  }
-  return page.screenshot({ fullPage: true });
-}
-
-/** Pure markdown assembly — exposed so a render step can re-emit markdown from a
- * stored entries.json without re-running the browser. */
-export function renderUiMarkdown(title: string, entries: UiEntry[]): string {
-  const lines: string[] = ["---", `title: ${title}`, "---", "", `# ${title}`, ""];
-  for (const entry of entries) {
-    switch (entry.kind) {
-      case "section":
-        lines.push(`## ${entry.heading}`, "");
-        break;
-      case "step":
-        lines.push(`### ${entry.heading}`, "");
-        if (entry.description) lines.push(entry.description, "");
-        break;
-      case "text":
-        lines.push(entry.prose, "");
-        break;
-      case "capture":
-        lines.push(`![${entry.caption}](./${entry.filename})`, "");
-        break;
-    }
-  }
-  return lines.join("\n");
-}
-
-export class DocGuide {
-  private entries: UiEntry[] = [];
-  private captureIndex = 0;
-
-  constructor(
-    private slug: string,
-    private title: string,
-  ) {}
-
-  section(heading: string): void {
-    this.entries.push({ kind: "section", heading });
-  }
-
-  step(heading: string, description?: string): void {
-    this.entries.push({ kind: "step", heading, description });
-  }
-
-  text(prose: string): void {
-    this.entries.push({ kind: "text", prose });
-  }
-
-  /** 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: Page, caption: string, treat?: CaptureTreatment): Promise<void> {
-    if (process.env.DOCS_GENERATE !== "1") return;
-    this.captureIndex++;
-    const filename = `${this.slug}-${String(this.captureIndex).padStart(3, "0")}.png`;
-    const buffer = await screenshotFor(page, treat);
-    const outDir = join(docsRoot(), this.slug);
-    mkdirSync(outDir, { recursive: true });
-    writeFileSync(join(outDir, filename), buffer);
-    this.entries.push({ kind: "capture", caption, filename });
-  }
-
-  /** Write entries.json + the rendered index.md under docs/generated/<slug>/. */
-  async flush(): Promise<void> {
-    if (process.env.DOCS_GENERATE !== "1") return;
-    const outDir = join(docsRoot(), this.slug);
-    mkdirSync(outDir, { recursive: true });
-    const fixture: UiFixture = { type: "ui", title: this.title, entries: this.entries };
-    writeFileSync(join(outDir, "entries.json"), `${JSON.stringify(fixture, null, 2)}\n`);
-    writeFileSync(join(outDir, "index.md"), renderUiMarkdown(this.title, this.entries));
-  }
-}

package/doc-guide/guides-config.ts

@@ -1,63 +0,0 @@
-import { defineConfig, type PlaywrightTestConfig } from "@playwright/test";
-
-// Playwright config factory for a product's FIXTURE-tier doc-guides: boot the
-// product's Vite app alone (no daemon, no license, no Docker) and drive it to
-// produce illustrated manual captures under <repo>/docs/generated/<slug>/.
-//
-// Carries the hard-won CI defaults so every product's runner behaves the same:
-//   - bind + probe 127.0.0.1 explicitly. On CI runners `localhost` can resolve to
-//     IPv6 ::1 first while Vite listens on IPv4, so the readiness probe never gets
-//     200 and the webServer "times out" though the server is up.
-//   - a 120s webServer timeout (cold CI runners are slow to first-serve) and piped
-//     stdout/stderr so a stuck boot shows in the log.
-//   - export NORSK_DOCS_ROOT so the dev-kit DocGuide writes to the REPO-level
-//     docs/generated even though the runner's cwd is a package subdir. Set here at
-//     config-eval time, before any guide imports doc-guide.ts.
-//
-// Chromium comes from the nix flake via BROWSER_FOR_TESTING; the guide script
-// wraps the whole run in with-display.sh to supply an X display.
-
-export interface GuidesConfigOptions {
-  /** Vite port. Pick one clear of the product's dev servers and sibling sessions. */
-  port: number;
-  /** Absolute path to the repo-level docs/generated dir. Exported as NORSK_DOCS_ROOT. */
-  docsRoot: string;
-  /** Capture viewport. Default 1440x960. */
-  viewport?: { width: number; height: 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;
-}
-
-export function guidesConfig(opts: GuidesConfigOptions): PlaywrightTestConfig {
-  // 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;
-
-  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({
-    testDir: opts.testDir ?? "./tests/guides",
-    workers: 1,
-    timeout: opts.timeout ?? 60_000,
-    use: {
-      baseURL,
-      browserName: "chromium",
-      headless: true,
-      viewport: opts.viewport ?? { width: 1440, height: 960 },
-      ...(process.env.BROWSER_FOR_TESTING && { launchOptions: { executablePath: process.env.BROWSER_FOR_TESTING } }),
-    },
-    webServer: {
-      command,
-      url: baseURL,
-      reuseExistingServer: !process.env.CI,
-      timeout: 120_000, // cold CI runners are slow to first-serve
-      stdout: "pipe",
-      stderr: "pipe",
-    },
-  });
-}

package/doc-guide/instance-proxy.ts

@@ -1,111 +0,0 @@
-// A tiny per-instance reverse proxy for the engine-tier doc-guides.
-//
-// A product's baked operator dashboard is built to run behind the runner's oauth2
-// proxy: its `env` endpoint advertises instance-scoped paths
-// (`apiBasePath: /instance/<id>/live/api`, `wsBasePath: /instance/<id>/live`).
-// The harness, though, publishes Studio DIRECTLY on studioHostPort with no
-// `/instance/<id>` prefix — so those advertised paths 404 and the console never
-// leaves its "workflow starting up" splash.
-//
-// Rather than drag the whole oauth2 proxy + TLS + port 443 into a doc run, this
-// serves the dashboard under exactly the prefix `env` advertises and strips it
-// before forwarding to studioHostPort — for both HTTP and the live-state
-// WebSocket (`useLiveComponent`), which is what carries programReceiving / audio
-// levels and therefore the ON AIR badge. Plain HTTP, ephemeral port, self-owned.
-
-import type { ServerWebSocket } from "bun";
-
-interface WsBridge {
-  upstreamUrl: string;
-  upstream: WebSocket | null;
-  queue: (string | ArrayBufferLike | Uint8Array)[];
-}
-
-export interface InstanceProxy {
-  /** Origin of the proxy, e.g. http://localhost:53421 */
-  origin: string;
-  /** Full dashboard URL for a hash-routed page, under the advertised prefix. */
-  dashboardUrl: (page?: string) => string;
-  stop: () => void;
-}
-
-// Response headers that describe the upstream transfer encoding; fetch() has
-// already decoded the body, so forwarding these would misdescribe what we send.
-const STRIP_RESPONSE_HEADERS = ["content-encoding", "content-length", "transfer-encoding"];
-
-/** Start a reverse proxy that serves `${prefix}/…` by forwarding `/…` to
- *  studioHostPort. `prefix` equals the instance's advertised `studioUrlPrefix`
- *  (`/instance/<instanceId>`); `dashboardKey` is the product's baked dashboard
- *  path segment (the dashboard is served at `/dashboard/<dashboardKey>/`). */
-export function startInstanceProxy(opts: {
-  studioHostPort: number;
-  instanceId: string;
-  dashboardKey: string;
-}): InstanceProxy {
-  const prefix = `/instance/${opts.instanceId}`;
-  const httpUpstream = `http://localhost:${opts.studioHostPort}`;
-  const strip = (pathname: string): string =>
-    pathname === prefix ? "/" : pathname.startsWith(`${prefix}/`) ? pathname.slice(prefix.length) : pathname;
-
-  const server = Bun.serve<WsBridge>({
-    port: 0,
-    async fetch(req, srv) {
-      const u = new URL(req.url);
-      const path = strip(u.pathname);
-
-      if (req.headers.get("upgrade")?.toLowerCase() === "websocket") {
-        const upstreamUrl = `ws://localhost:${opts.studioHostPort}${path}${u.search}`;
-        const ok = srv.upgrade(req, { data: { upstreamUrl, upstream: null, queue: [] } });
-        return ok ? undefined : new Response("ws upgrade failed", { status: 400 });
-      }
-
-      const headers = new Headers(req.headers);
-      headers.delete("host");
-      const body = req.method === "GET" || req.method === "HEAD" ? undefined : await req.arrayBuffer();
-      const upstream = await fetch(`${httpUpstream}${path}${u.search}`, {
-        method: req.method,
-        headers,
-        body,
-        redirect: "manual",
-      });
-      const outHeaders = new Headers(upstream.headers);
-      for (const h of STRIP_RESPONSE_HEADERS) outHeaders.delete(h);
-      return new Response(upstream.body, { status: upstream.status, headers: outHeaders });
-    },
-    websocket: {
-      open(ws: ServerWebSocket<WsBridge>) {
-        const up = new WebSocket(ws.data.upstreamUrl);
-        up.binaryType = "arraybuffer";
-        ws.data.upstream = up;
-        up.onopen = () => {
-          for (const m of ws.data.queue) up.send(m as string | ArrayBufferLike);
-          ws.data.queue = [];
-        };
-        up.onmessage = (e: MessageEvent) => ws.send(e.data);
-        up.onclose = (e: CloseEvent) => ws.close(e.code || 1000, e.reason);
-        up.onerror = () => {
-          try {
-            ws.close();
-          } catch {}
-        };
-      },
-      message(ws: ServerWebSocket<WsBridge>, message: string | Buffer) {
-        const up = ws.data.upstream;
-        if (up && up.readyState === WebSocket.OPEN) up.send(message);
-        else ws.data.queue.push(message);
-      },
-      close(ws: ServerWebSocket<WsBridge>) {
-        try {
-          ws.data.upstream?.close();
-        } catch {}
-      },
-    },
-  });
-
-  const origin = `http://localhost:${server.port}`;
-  return {
-    origin,
-    dashboardUrl: (page = "onair") => `${origin}${prefix}/dashboard/${opts.dashboardKey}/#/${page}`,
-    stop: () => server.stop(true),
-  };
-}

package/doc-guide/live-browser.ts

@@ -1,29 +0,0 @@
-// Engine-tier doc-guide browser support. The fixture-tier guides run under the
-// @playwright/test runner against a Vite dev server; the engine tier instead
-// drives a REAL launched instance from inside a bun:test that already owns the
-// product harness lifecycle. So we launch a raw chromium here (the same nixpkgs
-// chromium the fixture tier uses, via BROWSER_FOR_TESTING) rather than go through
-// the test-runner's webServer model.
-
-import { type Browser, type BrowserContext, chromium, type Page } from "@playwright/test";
-
-export interface LiveBrowser {
-  browser: Browser;
-  context: BrowserContext;
-  page: Page;
-}
-
-/** 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. */
-export async function launchLiveBrowser(opts?: { viewport?: { width: number; height: number } }): Promise<LiveBrowser> {
-  const executablePath = process.env.BROWSER_FOR_TESTING;
-  if (!executablePath) {
-    throw new Error("BROWSER_FOR_TESTING is unset — run inside `nix develop` so chromium is on offer");
-  }
-  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 page = await context.newPage();
-  return { browser, context, page };
-}