@norskvideo/ctl-dev-kit 0.1.23 → 0.1.25

package/conventions/check-drift.ts

@@ -218,6 +218,7 @@ export interface CanonicalBytes {
   flake: string;
   upgradeLatest: string;
   syncDevKit: string;
+  publishDocs: string;
   checks: string;
   biome: string;
   tsconfigBase: string;
@@ -359,6 +360,21 @@ export function checkDrift(repoRoot: string, canonical: CanonicalBytes): DriftRe
     );
   }
 
+  // publish-docs.yml is OPTIONAL — a product carries it once it has an
+  // illustrated manual to publish nightly. Unlike the workflows above it has NO
+  // per-repo line: it is deliberately product-agnostic (per-repo bits live in
+  // scripts/doc-guide/regen-manual.sh + an optional prepull-extra.sh), so it is a
+  // verbatim byte-for-byte copy of the canonical.
+  const publishDocsPath = join(repoRoot, ".github", "workflows", "publish-docs.yml");
+  if (existsSync(publishDocsPath)) {
+    const actual = readFileSync(publishDocsPath, "utf8");
+    if (actual !== canonical.publishDocs) {
+      push(
+        `.github/workflows/publish-docs.yml has drifted from @norskvideo/ctl-dev-kit conventions/publish-docs.yml (${firstDiffLine(actual, canonical.publishDocs)}). ${RESYNC}`,
+      );
+    }
+  }
+
   return { ok: problems.length === 0, problems };
 }
 
@@ -369,6 +385,7 @@ if (import.meta.main) {
     flake: readFileSync(join(import.meta.dir, "..", "build", "flake.nix"), "utf8"),
     upgradeLatest: readFileSync(join(import.meta.dir, "upgrade-latest.yml"), "utf8"),
     syncDevKit: readFileSync(join(import.meta.dir, "sync-dev-kit.yml"), "utf8"),
+    publishDocs: readFileSync(join(import.meta.dir, "publish-docs.yml"), "utf8"),
     checks: readFileSync(join(import.meta.dir, "checks.yml"), "utf8"),
     biome: readFileSync(join(import.meta.dir, "biome.base.json"), "utf8"),
     tsconfigBase: readFileSync(join(import.meta.dir, "tsconfig.base.json"), "utf8"),

package/conventions/docs.md

@@ -0,0 +1,133 @@
+# The illustrated product manual (shared across all Norsk ctl product repos)
+
+How a Norsk ctl product builds, writes, and publishes its **illustrated manual** —
+the self-contained HTML page a prospect or operator reads to understand what the
+product does. This is the shared half; the per-product half is the manual's
+actual page content, which lives in the product repo.
+
+Like [`personas.md`](./personas.md) this is a **shipped reference**, not a
+drift-gated copy: consume it from
+`node_modules/@norskvideo/ctl-dev-kit/conventions/docs.md`. The two things that
+ARE single-sourced and gated are the workflow (`publish-docs.yml`) and the
+toolchain library (`@norskvideo/ctl-dev-kit/doc-guide`); this file is the
+convention that ties them together.
+
+## What the manual is (and is not)
+
+The manual is one hash-routed HTML page assembled from **two cross-linked
+collections**, plus an overview:
+
+- **Functionality pages** — one capability per page (remote talent, live mixing,
+  output shapes, …). "What the product does."
+- **Example-deployment pages** — worked shows, each a concrete shape a reader can
+  recognise as close to their own. "What a real deployment looks like." Named as
+  starting points, never as a fixed menu or a tier ladder.
+- **Overview** — a hero capture and two ways in: by function, or by example.
+
+It is NOT the reference (`CommentaryConfig` / CI author material — that stays in
+`docs/reference.md` + `examples/`), NOT the operator runbook (host footprint,
+limitations — mostly ctl's), and NOT a feature checklist. It is the
+capability-first, illustrated front door.
+
+### Who reads it
+
+Name the reader before writing a page (see `personas.md` and the product's own
+`docs/personas.md`):
+
+- **Evaluator** — the overview, the example gallery, first light. Wants "does
+  this do what I need?" in minutes.
+- **Builder** — the illustrated task pages. The domain-fluent operator who stands
+  the show up and runs it.
+
+Integrator and Operator are served elsewhere (reference / ctl). Runtime actors
+(a commentator, a contributor, a producer) are NOT readers of the manual — the
+operator is the Builder; the others receive join links and onboarding kit.
+
+## Voice
+
+Customer- and Builder-facing, plain, capability-led. The rules that keep every
+product's manual in one voice:
+
+- **No internal/test vocabulary.** Never `engine`, `fixture`, `Playwright`,
+  `assertion`, `harness`, `instance`, `SSR`, a slug, or a DOM id in reader-facing
+  copy. The reader does not know or care how the shot was produced.
+- **Lead with the capability, not the UI state.** "A commentator joins from a
+  browser with a link" — not "the connections page shows a slot in the pending
+  state."
+- **Plain, not markety.** Describe what it does; skip the superlatives.
+- **No floor / ceiling / max / tier framing.** A deployment is described by its
+  shape ("compose and two delivery groups"), never as "the maximal build" or "the
+  ceiling" — the ceiling is wherever the customer needs it to be. Internal example
+  slugs (e.g. `commentary-max`) may keep the word; the copy a reader sees must not.
+- **Examples are starting points.** "Worked deployments — the pieces combine
+  freely; any show is described in config," not a menu the reader must pick from.
+
+## Captures
+
+Every screenshot is a REAL capture written by a doc-guide driving a real surface
+that the guide also asserts — so a shot can never depict a UI that does not
+exist. A guide runs at one of three tiers:
+
+- **Fixture** — the product's Vite app booted alone, fed representative state (no
+  daemon, no license). Proves the UI renders correctly. Fast; runs in CI.
+- **Frontend** — the standalone configure form, same model.
+- **Engine** — a REAL launched instance, driven live (On Air actually lighting
+  up, a real feed composited). Slow, licensed, nightly.
+
+Per-step treatments (`CaptureTreatment`, from the doc-guide library):
+
+- **full page** (default) — the whole surface, for orientation shots.
+- **`crop`** — a tight element screenshot of one component, by CSS selector, for
+  a close-up. Anchor crops on a stable `data-region` / `data-*` attribute the
+  component renders, not on incidental structure.
+- **`spotlight`** — the whole screen with one region lit and everything else
+  dimmed, for "look here, in context."
+
+## The toolchain
+
+All single-sourced in `@norskvideo/ctl-dev-kit/doc-guide` — products import it,
+they do not copy it:
+
+- `@norskvideo/ctl-dev-kit/doc-guide` — `DocGuide` (a guide narrates itself into
+  `docs/generated/<slug>/`), `screenshotFor`, `CaptureTreatment`. Writes under
+  `NORSK_DOCS_ROOT` (the repo-level `docs/generated`); the config factory sets it.
+- `@norskvideo/ctl-dev-kit/doc-guide/guides-config` — `guidesConfig({ port,
+  docsRoot, … })`, the Playwright config for the fixture/frontend tiers, carrying
+  the CI defaults (bind+probe `127.0.0.1`, 120s webServer timeout, piped output).
+- `@norskvideo/ctl-dev-kit/doc-guide/build-manual` — `buildManual(spec, {
+  docsRoot })`, the generic assembler. The product supplies ONLY the page content
+  (`ManualSpec`: brand, overview, functionality[], examples[]); layout, CSS and
+  routing live in the assembler so every product's manual looks the same.
+- `@norskvideo/ctl-dev-kit/doc-guide/{instance-proxy,live-browser}` — engine-tier
+  support (serve the baked dashboard under its advertised instance prefix; launch
+  the nix chromium for a live capture).
+- `doc-guide/with-display.sh` — wrap the run in an X display for headless chromium
+  on a true-headless Linux box. Copy it to the repo's `scripts/` (it must be a
+  repo-local executable the package.json guide scripts invoke).
+
+Per-repo, the product provides: its guide suites, a thin `build-manual.ts` that
+supplies the `ManualSpec` and does the file IO, and
+`scripts/doc-guide/regen-manual.sh` — the one command a release runs to drive
+every tier with capture-writing on, then assemble. `regen-manual.sh` owns the
+slug list and which tiers run (set `SKIP_ENGINE=1` to regenerate only the fast
+tiers). An engine tier needing images beyond the universal media+studio pair
+pulls them in an optional `scripts/doc-guide/prepull-extra.sh`.
+
+## The publish contract
+
+Latest-only, republished by ctl:
+
+- Each product's nightly (`publish-docs.yml`, single-sourced + drift-gated)
+  rebuilds the manual to ONE self-contained `manual.html` and publishes it as the
+  asset of a **moving `docs-latest` GitHub Release** — never versioned, its single
+  asset clobbered each night. Stable URL:
+  `https://github.com/<owner>/<repo>/releases/download/docs-latest/manual.html`.
+- **norsk-ctl's docs build fetches each registered product's `docs-latest` asset
+  and mounts it at `/products/<slug>/`**, deploying the one Cloudflare Pages
+  project — so ctl republishes every product's manual whenever it builds its docs.
+  A true per-product subdir on ctl's site only works by ctl aggregating, because a
+  Pages deploy is whole-site.
+
+Two files back the contract: `manual.html` (the standalone document — publish
+THIS, not the Artifact fragment `index.html`) and, on the ctl side, the product
+registry the aggregator reads.

package/conventions/publish-docs.yml

@@ -0,0 +1,141 @@
+# Nightly: regenerate this product's illustrated manual and publish it as the
+# product's "latest docs" artifact, for the norsk-ctl docs site to republish.
+#
+# THE CROSS-PRODUCT PATTERN (each product does this; norsk-ctl aggregates):
+#   - Every product's nightly rebuilds its manual to ONE self-contained
+#     `manual.html` and publishes it as the asset of a MOVING `docs-latest`
+#     GitHub Release. Latest-only: the release is never versioned, its single
+#     asset is clobbered each night. Stable URL:
+#       https://github.com/<owner>/<repo>/releases/download/docs-latest/manual.html
+#   - norsk-ctl's docs build fetches each registered product's `docs-latest`
+#     asset and mounts it under `/products/<slug>/`, deploying the one
+#     Cloudflare Pages project — so ctl republishes every product's manual
+#     whenever it builds its docs.
+#
+# This workflow is SINGLE-SOURCED in @norskvideo/ctl-dev-kit
+# (conventions/publish-docs.yml) and copied verbatim, same as checks.yml. It is
+# deliberately product-agnostic: everything per-repo lives in repo-local scripts
+# it calls —
+#   - scripts/doc-guide/regen-manual.sh   : the guide tiers + slug list + assemble
+#   - scripts/doc-guide/prepull-extra.sh  : OPTIONAL, any images beyond media+studio
+# so the drift gate can keep every product's copy byte-identical.
+#
+# Nightly-only by design: a guide's engine tier stands up real instances (slow,
+# and subject to teardown flakes), so it does not ride every push. The
+# licensed-runner setup mirrors integration.yml — ctl comes from the released
+# binary via NORSK_CTL_BINARY, Docker is used directly on the x64 pool.
+name: publish-docs
+
+on:
+  schedule:
+    - cron: "30 1 * * *" # 01:30 UTC — ahead of ctl's nightly docs build
+  workflow_dispatch:
+
+permissions:
+  contents: write # move the docs-latest release + clobber its asset
+
+concurrency:
+  group: publish-docs-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  publish:
+    runs-on: x64
+    steps:
+      # A guide's engine tier launches the same docker instances the integration
+      # suite does, leaving root-owned bind-mount target dirs under test-temp/
+      # that the non-root runner can't remove — which fails actions/checkout's
+      # own cleanup before anything runs. Nuke them from a throwaway root
+      # container first. Best-effort. (Mirrors integration.yml.)
+      - name: Clear stale root-owned test-temp (pre-checkout)
+        run: |
+          set -uo pipefail
+          tt="$GITHUB_WORKSPACE/test-temp"
+          [ -d "$tt" ] || exit 0
+          docker run --rm --user 0:0 -v "$tt":/t alpine sh \
+            -c 'rm -rf /t/* /t/.[!.]* 2>/dev/null || true' || rm -rf "$tt"/* 2>/dev/null || true
+
+      - uses: actions/checkout@v5
+        with:
+          clean: false
+
+      - name: Write the Norsk license (from the org secret)
+        env:
+          NORSK_LICENSE_V2: ${{ secrets.NORSK_LICENSE_V2 }}
+        run: printf '%s' "$NORSK_LICENSE_V2" > "$RUNNER_TEMP/norsk-license.json"
+
+      - name: Download the released norsk-ctl binary (latest channel)
+        run: |
+          set -euo pipefail
+          S3="https://s3.eu-west-1.amazonaws.com/norsk.video/norsk-ctl"
+          ver="$(curl -fsSL "$S3/latest")"
+          echo "norsk-ctl latest channel -> $ver"
+          curl -fsSL "$S3/$ver/norsk-ctl-$ver-linux-x64" -o "$RUNNER_TEMP/norsk-ctl"
+          chmod +x "$RUNNER_TEMP/norsk-ctl"
+          "$RUNNER_TEMP/norsk-ctl" --version || true
+
+      # Cold-runner first pulls overrun the harness's per-test launch timeouts;
+      # pre-pull the universal media + studio images (every product pins them in
+      # manifest.seed.json) so compose/run hit local images. A product needing
+      # more (e.g. a WHIP driver) pulls them in scripts/doc-guide/prepull-extra.sh.
+      - name: Pre-pull the media + studio images
+        run: |
+          set -euo pipefail
+          for img in "$(jq -r '.latest.media' manifest.seed.json)" "$(jq -r '.latest.studio' manifest.seed.json)"; do
+            echo "pre-pulling $img"
+            docker pull "$img"
+          done
+          if [ -x scripts/doc-guide/prepull-extra.sh ]; then
+            echo "running scripts/doc-guide/prepull-extra.sh"
+            ./scripts/doc-guide/prepull-extra.sh
+          fi
+
+      # Rebuild every workspace the manual depends on (a guide's engine tier packs
+      # the freshly-built dashboard + frontend dist into the launched template),
+      # then run the product's doc-guide tiers and assemble the manual.
+      # regen-manual.sh owns the slug list and which tiers run; with-display.sh
+      # wraps the whole run in an X display for headless chromium (the engine tier
+      # drives a raw chromium that needs one).
+      - name: Regenerate the illustrated manual (all tiers)
+        env:
+          NORSK_CTL_BINARY: ${{ runner.temp }}/norsk-ctl
+          NORSK_LICENSE_FILE: ${{ runner.temp }}/norsk-license.json
+          # This runner launches Studio as a HOST sibling (DooD), so the harness
+          # reaches host-published ports via the host-gateway alias, not
+          # localhost — same as the integration suite.
+          NORSK_TEST_HOST: host.docker.internal
+        run: |
+          nix develop .#build --command bash -c '
+            set -euo pipefail
+            # clean:false persists node_modules between runs for speed, but a
+            # workspace dep whose version moved leaves stale copies that
+            # --frozen-lockfile does not reliably relink, so a new export is "not
+            # found". Nuke EVERY node_modules — including nested per-workspace ones
+            # — for a deterministic install. A nightly can afford it.
+            find . -name node_modules -type d -prune -exec rm -rf {} + 2>/dev/null || true
+            bun install --frozen-lockfile
+            bun run build:no-lint
+            bash scripts/with-display.sh scripts/doc-guide/regen-manual.sh
+          '
+
+      # Publish the assembled manual as the moving docs-latest release asset.
+      # gh is on PATH inside the nix shell; `upload --clobber` replaces the
+      # same-named asset in place, so the release stays latest-only.
+      - name: Publish manual.html to the moving docs-latest release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          nix develop .#build --command bash -c '
+            set -euo pipefail
+            # Publish the STANDALONE document (complete <!doctype>…</html>), not
+            # the Artifact fragment index.html — ctl hosts it directly as a page.
+            man="docs/generated/manual/manual.html"
+            [ -s "$man" ] || { echo "::error::manual was not generated at $man"; exit 1; }
+            cp "$man" "$RUNNER_TEMP/manual.html"
+            if ! gh release view docs-latest >/dev/null 2>&1; then
+              gh release create docs-latest --title "Docs (latest)" --prerelease \
+                --notes "Latest product manual, rebuilt nightly and republished by the norsk-ctl docs site. Not a versioned release — the manual.html asset is clobbered each night."
+            fi
+            gh release upload docs-latest "$RUNNER_TEMP/manual.html" --clobber
+            echo "published -> docs-latest/manual.html"
+          '

package/conventions/sync-drift.ts

@@ -153,6 +153,13 @@ export function syncDrift(repoRoot: string, canonical: CanonicalBytes): SyncRepo
   syncWorkflow(repoRoot, ".github/workflows/upgrade-latest.yml", canonical.upgradeLatest, r);
   syncWorkflow(repoRoot, ".github/workflows/sync-dev-kit.yml", canonical.syncDevKit, r);
 
+  // publish-docs.yml is optional and verbatim (no per-repo line) — only re-sync a
+  // repo that already carries it, unlike biome/tsconfig which every repo must have.
+  const publishDocsRel = ".github/workflows/publish-docs.yml";
+  if (existsSync(join(repoRoot, publishDocsRel))) {
+    writeIfChanged(join(repoRoot, publishDocsRel), canonical.publishDocs, publishDocsRel, r.written);
+  }
+
   syncFlake(repoRoot, canonical.flake, r);
   syncClaude(repoRoot, canonical.core, r);
   syncGitignore(repoRoot, canonical.gitignoreCore, r);
@@ -169,6 +176,7 @@ if (import.meta.main) {
     flake: readFileSync(join(dir, "..", "build", "flake.nix"), "utf8"),
     upgradeLatest: readFileSync(join(dir, "upgrade-latest.yml"), "utf8"),
     syncDevKit: readFileSync(join(dir, "sync-dev-kit.yml"), "utf8"),
+    publishDocs: readFileSync(join(dir, "publish-docs.yml"), "utf8"),
     checks: readFileSync(join(dir, "checks.yml"), "utf8"),
     biome: readFileSync(join(dir, "biome.base.json"), "utf8"),
     tsconfigBase: readFileSync(join(dir, "tsconfig.base.json"), "utf8"),

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.js

@@ -0,0 +1,183 @@
+// Generic assembler for a ctl product's illustrated manual: two cross-linked
+// collections (functionality pages + example-deployment pages), each a step
+// walkthrough, rendered into one self-contained, hash-routed HTML page.
+//
+// Every screenshot is a real capture a doc-guide wrote under
+// <docsRoot>/<slug>/<slug>-00N.png. This assembler reads those PNGs, resizes each
+// with ImageMagick, inlines it as a data URI, and returns both the Artifact
+// FRAGMENT (index.html — the Artifact tool supplies the doctype/head/body) and a
+// complete STANDALONE document (manual.html — for hosting the manual directly as
+// a page). A referenced shot that hasn't been generated yet renders as a labelled
+// gap rather than crashing the build; every gap is reported in `missing`.
+//
+// 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";
+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, 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, 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}">
+    <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">
+  <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>
+  <div class="twocol">
+    <div><h2>${esc(ov.byFunctionHeading ?? "By function")}</h2><div class="linklist">${FN.map((p) => `<a href="#${p.id}">${esc(p.nav)}</a>`).join("")}</div></div>
+    <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 = `
+  <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>
+<style>
+:root{--bg:#0a0d12;--bg2:#0c1118;--surf:#131923;--ink:#eaeff5;--dim:#939dab;--faint:#5f6a79;
+  --line:#212a36;--accent:#54d6cf;--measure:64ch}
+@media (prefers-color-scheme:light){:root{--bg:#f5f7f9;--bg2:#eef1f4;--surf:#fff;--ink:#0f1620;
+  --dim:#54606e;--faint:#8c96a3;--line:#e2e7ec;--accent:#0c8f86}}
+:root[data-theme="dark"]{--bg:#0a0d12;--bg2:#0c1118;--surf:#131923;--ink:#eaeff5;--dim:#939dab;
+  --faint:#5f6a79;--line:#212a36;--accent:#54d6cf}
+:root[data-theme="light"]{--bg:#f5f7f9;--bg2:#eef1f4;--surf:#fff;--ink:#0f1620;--dim:#54606e;
+  --faint:#8c96a3;--line:#e2e7ec;--accent:#0c8f86}
+*{box-sizing:border-box}
+body{margin:0;background:var(--bg);color:var(--ink);line-height:1.6;
+  font-family:system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;-webkit-font-smoothing:antialiased}
+.mono{font-family:ui-monospace,"SF Mono",Menlo,monospace}
+.wrap{display:grid;grid-template-columns:264px minmax(0,1fr);max-width:1400px;margin:0 auto}
+aside{position:sticky;top:0;align-self:start;height:100vh;overflow-y:auto;padding:26px 18px 48px;
+  border-right:1px solid var(--line);background:var(--bg2)}
+.brand{font-family:ui-monospace,Menlo,monospace;font-size:11px;letter-spacing:.2em;text-transform:uppercase;color:var(--accent);margin-bottom:22px}
+aside a{display:block;text-decoration:none;color:var(--dim);padding:6px 10px;border-radius:7px;font-size:13px;line-height:1.35}
+aside a:hover{background:var(--surf);color:var(--ink)}
+aside a.active{background:var(--surf);color:var(--ink);box-shadow:inset 2px 0 0 var(--accent)}
+.ovlink{margin-bottom:16px;font-weight:600;color:var(--ink)}
+.ngroup{margin-bottom:20px}
+.ghead{font-family:ui-monospace,Menlo,monospace;font-size:10.5px;letter-spacing:.16em;text-transform:uppercase;color:var(--faint);margin:0 10px 6px;display:flex;gap:8px;align-items:center}
+.ct{background:var(--surf);border:1px solid var(--line);border-radius:20px;padding:0 6px;font-size:9.5px;color:var(--dim)}
+main{min-width:0;padding:0 clamp(20px,5vw,72px)}
+.page{display:none;max-width:840px;padding:52px 0 88px;animation:fade .18s ease}
+.page.on{display:block}
+@keyframes fade{from{opacity:0;transform:translateY(4px)}to{opacity:1;transform:none}}
+@media (prefers-reduced-motion:reduce){.page{animation:none}}
+.phead{margin-bottom:20px}
+.kind{display:inline-block;font-family:ui-monospace,Menlo,monospace;font-size:10px;letter-spacing:.14em;text-transform:uppercase;color:var(--accent);margin-bottom:12px}
+.kind.ex{color:var(--dim)}.kind.ov{color:var(--faint)}
+.phead h1{font-size:clamp(26px,4vw,42px);line-height:1.05;letter-spacing:-.028em;margin:0;font-weight:730;text-wrap:balance}
+.ptag{margin-top:12px;font-size:12px;color:var(--faint)}
+.lead{font-size:clamp(15px,1.9vw,18px);color:var(--dim);max-width:var(--measure);margin:0 0 8px}
+
+.steps{list-style:none;margin:34px 0 0;padding:0}
+.step{padding:28px 0;border-top:1px solid var(--line)}
+.stinfo{display:flex;gap:16px;align-items:baseline;margin-bottom:16px;max-width:var(--measure)}
+.stnum{font-family:ui-monospace,Menlo,monospace;font-size:13px;color:var(--accent);flex:none;padding-top:2px}
+.stinfo h3{font-size:17px;margin:0 0 4px;letter-spacing:-.01em}
+.stinfo p{margin:0;color:var(--dim);font-size:14.5px}
+.shot{border:1px solid var(--line);border-radius:12px;overflow:hidden;background:#000;box-shadow:0 22px 46px -32px rgba(0,0,0,.8)}
+.shot img{display:block;max-width:100%;height:auto;margin:0 auto}
+.heroshot{margin-bottom:36px}
+.heroshot .shot{border-color:color-mix(in srgb,var(--accent) 24%,var(--line))}
+.hcap{margin:12px 0 0;color:var(--dim);font-size:13px;max-width:56ch}
+
+.thin{margin-top:26px;font-family:ui-monospace,Menlo,monospace;font-size:12px;color:var(--faint);
+  background:var(--surf);border:1px dashed var(--line);border-radius:9px;padding:11px 14px;max-width:var(--measure)}
+.xlinks{margin-top:36px;padding-top:22px;border-top:1px solid var(--line);display:flex;flex-wrap:wrap;gap:10px;align-items:center}
+.xlab{font-family:ui-monospace,Menlo,monospace;font-size:10.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--faint);margin-right:4px}
+.chip{text-decoration:none;font-size:13px;color:var(--ink);background:var(--surf);border:1px solid var(--line);border-radius:20px;padding:6px 13px}
+.chip:hover{border-color:var(--accent);color:var(--accent)}
+.twocol{display:grid;grid-template-columns:1fr 1fr;gap:32px;margin-top:40px;padding-top:30px;border-top:1px solid var(--line)}
+.twocol h2{font-size:15px;margin:0 0 12px}
+.mini{font-size:12.5px;color:var(--faint);margin:0 0 12px;max-width:40ch}
+.linklist{display:flex;flex-direction:column;gap:2px}
+.linklist a{text-decoration:none;color:var(--dim);font-size:14px;padding:5px 0}
+.linklist a:hover{color:var(--accent)}
+@media (max-width:880px){.wrap{grid-template-columns:1fr}
+  aside{position:static;height:auto;border-right:none;border-bottom:1px solid var(--line)}
+  .twocol{grid-template-columns:1fr}}
+</style>
+
+<div class="wrap">
+<aside><div class="brand">${esc(spec.brand)}</div>${nav}</aside>
+<main>
+${overview}
+${ALL.map(pageHtml).join("\n")}
+</main>
+</div>
+
+<script>
+(function(){
+  var pages=[].slice.call(document.querySelectorAll('.page'));
+  var links=[].slice.call(document.querySelectorAll('[data-nav]'));
+  function show(){var id=(location.hash||'#overview').slice(1);
+    if(!document.getElementById(id))id='overview';
+    pages.forEach(function(p){p.classList.toggle('on',p.id===id)});
+    links.forEach(function(a){a.classList.toggle('active',a.getAttribute('href')==='#'+id)});
+    window.scrollTo(0,0);}
+  window.addEventListener('hashchange',show);show();
+})();
+</script>`;
+    const standaloneHtml = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>${esc(spec.title)}</title>
+</head>
+<body>
+${html}
+</body>
+</html>`;
+    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/doc-guide/with-display.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Run "$@" with an X DISPLAY available — passes through if one is already set,
+# otherwise wraps in xvfb-run. Needed because nix-pinned headless chromium on
+# a true-headless Linux box silently no-ops page.fill on plain HTML inputs and
+# crashes the renderer on some pages; giving it a real X display avoids both.
+# On Mac this is a no-op (xvfb-run isn't on PATH and Apple's chromium doesn't
+# need it).
+#
+# Part of the @norskvideo/ctl-dev-kit doc-guide toolchain. A product copies this
+# to its own scripts/ (it must be a repo-local executable the package.json guide
+# scripts can invoke); the dev-kit is the canonical source.
+
+set -euo pipefail
+
+if [ -n "${DISPLAY:-}" ] || ! command -v xvfb-run >/dev/null 2>&1; then
+  exec "$@"
+fi
+
+exec xvfb-run -a --server-args="-screen 0 1280x720x24" "$@"

package/package.json

@@ -1,12 +1,17 @@
 {
   "name": "@norskvideo/ctl-dev-kit",
-  "version": "0.1.23",
+  "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"
+    "./create-product": "./create-product/create-product.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"
@@ -14,6 +19,14 @@
   "dependencies": {
     "@norskvideo/ctl-sdk": "^0.1.0"
   },
+  "peerDependencies": {
+    "@playwright/test": "*"
+  },
+  "peerDependenciesMeta": {
+    "@playwright/test": {
+      "optional": true
+    }
+  },
   "publishConfig": {
     "access": "public"
   }