@norskvideo/ctl-dev-kit 0.2.2 → 0.2.3

package/docs-theme/README.md

@@ -0,0 +1,82 @@
+# `docs-theme/` — the shared Norsk docs site theme
+
+The parts of an Astro + Starlight docs site that must **never** differ between
+Norsk products: the theme, the three component overrides, the content schema,
+and the Astro/Starlight configuration itself. A product's site owns only what
+genuinely differs — its content, its sidebar, its origin and its two names.
+
+    custom.css              the palette + self-hosted Geist faces
+    fonts/                  the woff2 those @font-face rules point at
+    components/Footer.astro    the "captured against" line on a generated guide
+    components/Sidebar.astro   the "Built against" versions footer
+    components/SiteTitle.astro the masthead wordmark, decoupled from the tab title
+    content.config.ts       the docs collection, incl. `capturedAgainst`
+    starlight.ts            `norskDocsSite()` — the whole Astro config bar the site's own parts
+    sync.ts                 the writer and the drift gate
+
+## Consuming it
+
+A docs site's `astro.config.mjs` becomes its sidebar plus five lines:
+
+```js
+import { defineConfig } from "astro/config";
+import { isPublicBuild, norskDocsSite } from "./src/starlight.ts";
+
+export default defineConfig(
+  norskDocsSite({
+    origin: "https://ctl.norsk.video",
+    tabTitle: "Norsk",              // browser tab suffix — tabs truncate
+    wordmark: "norsk-ctl",          // masthead — names the tool in hand
+    buildVersions: [{ label: "norsk-ctl", value: version }],
+    sidebar: [...],
+  }),
+);
+```
+
+`norskDocsSite()` supplies the two-build shape (`dist-embedded` at base `/docs`
+for the copy baked into a product binary, `dist-public` at base `/` for the
+site on its own domain, selected by `ASTRO_BUILD=public`), the /docs-prefix
+strip that makes the public build's absolute links work, the mermaid pipeline,
+the favicon convention, and the component + CSS wiring.
+
+## Why the files are copied into the site, not imported from here
+
+A docs site is a **standalone package** — its own `bun.lock`, its own
+`node_modules`, outside the monorepo's workspaces, because Astro's dependency
+tree has no business in a product install. It therefore cannot depend on this
+package the way every other dev-kit consumer does. That is measured, not
+assumed: adding `"@norskvideo/ctl-dev-kit": "file:../../dev-kit"` to norsk-ctl's
+website and installing fails with
+
+    error: @norskvideo/ctl-sdk@workspace:* failed to resolve
+
+because bun must then resolve this package's own `workspace:*` dependencies
+from a directory that is not in a workspace.
+
+So the theme is a **forced copy**, handled the way this package already handles
+every forced copy — canonical bytes here, a writer, and a gate:
+
+```
+bun node_modules/@norskvideo/ctl-dev-kit/docs-theme/sync.ts sync  <site>
+bun node_modules/@norskvideo/ctl-dev-kit/docs-theme/sync.ts check <site>
+```
+
+`<site>` is the directory holding `astro.config.mjs`; the copies land in its
+`src/`, so this directory mirrors a site's `src/` and the path map is an
+identity. A site runs `check` in its own test suite (norsk-ctl:
+`website/tests/theme-drift.test.ts`, which `bun run check` runs), so a
+hand-edited copy fails before it is published.
+
+**Keeping the copies at those exact paths is load-bearing.** Astro derives a
+component's scoped-style class from its path, so moving `Footer.astro` rewrites
+a class attribute on every page of the site.
+
+## Not yet
+
+- **`conventions/check-drift.ts` does not know about this directory.** Its gate
+  runs at a product repo's root against files at fixed repo-root paths; a docs
+  site is a nested package a repo may or may not have. When the first product
+  repo outside this monorepo grows a site, the two gates should become one —
+  `check-drift` gaining a "if `website/astro.config.mjs` exists, check the theme"
+  clause is the obvious shape.
+- **`create-product` does not render a site.** No generated repo has one yet.

package/docs-theme/components/Footer.astro

@@ -0,0 +1,40 @@
+---
+/**
+ * Starlight's footer plus the "captured against" line on a generated guide.
+ *
+ * The test-driven guides every Norsk docs site carries are captured by a
+ * Playwright run against a real stack and republished from a cache, so a page
+ * can be older than the product it documents — some guides ride every release,
+ * the expensive ones a weekly run. The shared renderer writes what the run knew
+ * into the page's front matter (`capturedAgainst`, see content.config.ts) and
+ * this says it on the page: "Captured 2026-09-17 against norsk-mgr 0.1.0-…". A
+ * page without the field (hand-written, or captured before the field existed)
+ * shows nothing extra.
+ */
+import Default from "@astrojs/starlight/components/Footer.astro";
+
+const against = Astro.locals.starlightRoute.entry.data.capturedAgainst;
+const parts: string[] = [];
+if (against?.norskMgr) parts.push(`norsk-mgr ${against.norskMgr}`);
+if (against?.norsk) parts.push(`Norsk Manager ${against.norsk}`);
+const line = against ? `Captured ${against.when}${parts.length ? ` against ${parts.join(", ")}` : ""}` : null;
+---
+
+{
+	line && (
+		<p class="captured-against">
+			{line} — every command and screenshot on this page is from that run.
+		</p>
+	)
+}
+<Default><slot /></Default>
+
+<style>
+	.captured-against {
+		margin-top: 3rem;
+		padding-top: 1rem;
+		border-top: 1px solid var(--sl-color-hairline-light);
+		font-size: var(--sl-text-sm);
+		color: var(--sl-color-gray-3);
+	}
+</style>

package/docs-theme/components/Sidebar.astro

@@ -0,0 +1,73 @@
+---
+/**
+ * Starlight's sidebar plus a footer stating what this docs build was built
+ * against. Every product site wants this line and none of them should word it
+ * differently, so the markup is shared and only the rows differ: the site
+ * passes them to `norskDocsSite({ buildVersions })`, which injects them as
+ * `__BUILD_VERSIONS__` (see starlight.ts on why a vite define rather than an
+ * import). They are read at build time from the product's own files, so they
+ * cannot drift from what ships the way a hand-written literal in MDX did.
+ */
+import Default from "@astrojs/starlight/components/Sidebar.astro";
+
+// Injected by vite.define in starlight.ts — see the note there on why this is
+// not resolved from within the component.
+declare const __BUILD_VERSIONS__: Array<{ label: string; value: string; splitOnLastColon?: boolean }>;
+// The repo/tag split keeps a long image pin wrapping sensibly in a narrow
+// sidebar: `norskvideo/x:tag` breaks after the colon rather than mid-word.
+const rows = __BUILD_VERSIONS__.map((v) => ({
+  label: v.label,
+  parts: v.splitOnLastColon ? v.value.split(/:(?=[^:]*$)/) : [v.value],
+}));
+---
+
+<Default><slot /></Default>
+
+<div class="build-versions">
+	<p class="build-versions__heading">Built against</p>
+	<dl>
+		{/* One line per row on purpose: whitespace between expressions inside a
+		    template expression survives into the emitted <code>, and a stray
+		    space in the middle of an image pin is a rendering change. */}
+		{rows.map((row) => (
+			<Fragment><dt>{row.label}</dt><dd><code>{row.parts[0]}{row.parts.length > 1 && <Fragment>:<wbr />{row.parts[1]}</Fragment>}</code></dd></Fragment>
+		))}
+	</dl>
+</div>
+
+<style>
+	.build-versions {
+		margin-top: 1.5rem;
+		padding-top: 1rem;
+		border-top: 1px solid var(--sl-color-hairline-light);
+		font-size: var(--sl-text-xs);
+		color: var(--sl-color-gray-3);
+	}
+
+	.build-versions__heading {
+		margin: 0 0 0.5rem;
+		font-weight: 600;
+		text-transform: uppercase;
+		letter-spacing: 0.05em;
+		color: var(--sl-color-gray-2);
+	}
+
+	.build-versions dl {
+		margin: 0;
+	}
+
+	.build-versions dt {
+		margin-top: 0.5rem;
+	}
+
+	.build-versions dd {
+		margin: 0.125rem 0 0;
+	}
+
+	.build-versions code {
+		font-size: var(--sl-text-xs);
+		overflow-wrap: anywhere;
+		background: none;
+		padding: 0;
+	}
+</style>

package/docs-theme/components/SiteTitle.astro

@@ -0,0 +1,52 @@
+---
+/**
+ * The masthead wordmark, top-left of every page.
+ *
+ * Exists only to say something different from `starlight.title`. Starlight
+ * drives the masthead and the browser-tab suffix from that single value, and
+ * the two want different things: the tab wants the short family name because
+ * tabs truncate, the masthead wants to name the tool the reader is holding.
+ * `norskDocsSite({ tabTitle, wordmark })` is where a site says both, and the
+ * wordmark reaches here as `__SITE_WORDMARK__`.
+ *
+ * The wordmark is the binary name, deliberately. Everything under it — the
+ * sidebar, the commands, the paths — says the binary's name, and a masthead
+ * reading anything else would be a second name for one thing: it splits
+ * searches and makes the reader learn a mapping. How to SAY it is a real
+ * question, and it is answered in prose on the index page rather than by
+ * renaming the product.
+ *
+ * Not a wrapper around Starlight's own SiteTitle, because the text it renders
+ * comes from `Astro.locals.starlightRoute.siteTitle` and mutating that would
+ * also move the <title> — the exact coupling this override is here to break.
+ * Reimplemented instead, which is cheap: the upstream component is a link, a
+ * span and some logo handling, and no logo is configured here.
+ */
+declare const __SITE_WORDMARK__: string;
+
+const { siteTitleHref } = Astro.locals.starlightRoute;
+---
+
+<a href={siteTitleHref} class="site-title sl-flex">
+	<span translate="no">{__SITE_WORDMARK__}</span>
+</a>
+
+<style>
+	/* Mirrors upstream SiteTitle.astro. Same layer, so a Starlight upgrade that
+	   restyles the masthead still applies here. */
+	@layer starlight.core {
+		.site-title {
+			align-items: center;
+			gap: var(--sl-nav-gap);
+			font-size: var(--sl-text-h4);
+			font-weight: 600;
+			color: var(--sl-color-text-accent);
+			text-decoration: none;
+			white-space: nowrap;
+			min-width: 0;
+		}
+		span {
+			overflow: hidden;
+		}
+	}
+</style>

package/docs-theme/content.config.ts

@@ -0,0 +1,25 @@
+import { defineCollection, z } from "astro:content";
+import { docsLoader } from "@astrojs/starlight/loaders";
+import { docsSchema } from "@astrojs/starlight/schema";
+
+// The docs content collection every Norsk product site declares. Shared so a
+// page authored for one site is loadable by another and the guide renderer has
+// one schema to satisfy.
+//
+// `capturedAgainst` is what the test-driven guides' renderer writes into a
+// generated page's front matter (`renderMarkdown` in the shared guide
+// renderer): the versions the page was captured against and the capture date.
+// Footer.astro renders it; a hand-written page simply has none. Strings, not
+// dates — the renderer quotes them for exactly that reason.
+export const capturedAgainstSchema = z.object({
+  norsk: z.string().optional(),
+  norskMgr: z.string().optional(),
+  when: z.string(),
+});
+
+export const collections = {
+  docs: defineCollection({
+    loader: docsLoader(),
+    schema: docsSchema({ extend: z.object({ capturedAgainst: capturedAgainstSchema.optional() }) }),
+  }),
+};

package/docs-theme/custom.css

@@ -0,0 +1,108 @@
+/* Match the norsk-ctl frontend's Tailwind zinc palette. */
+
+/*
+ * Self-hosted Geist Sans + Mono, byte-identical to @norskvideo/ctl-sdk/base.css so the
+ * docs chrome renders in the same face as the app and the guide screenshots.
+ * Standalone package — it can't @import the SDK's base.css, so it vendors the
+ * woff2 (see src/fonts/README obligations). Relative url() → Vite fingerprints
+ * them into the build; never a CDN.
+ */
+@font-face {
+  font-family: "Geist";
+  font-style: normal;
+  font-weight: 100 900; /* variable range → no faux bold */
+  font-display: swap;
+  src: url("./fonts/Geist.woff2") format("woff2-variations"),
+       url("./fonts/Geist.woff2") format("woff2");
+}
+
+@font-face {
+  font-family: "Geist Mono";
+  font-style: normal;
+  font-weight: 100 900;
+  font-display: swap;
+  src: url("./fonts/GeistMono.woff2") format("woff2-variations"),
+       url("./fonts/GeistMono.woff2") format("woff2");
+}
+
+:root {
+  --sl-font: "Geist", ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  --sl-font-mono: "Geist Mono", ui-monospace, "SF Mono", "Cascadia Code", "Fira Code", Menlo, Consolas, monospace;
+}
+
+/* Dark theme — primary. Tailwind zinc + indigo accent matching the React app. */
+:root[data-theme="dark"] {
+  /* Backgrounds */
+  --sl-color-bg: #18181b;               /* zinc-900 */
+  --sl-color-bg-nav: #1f1f23;           /* zinc-850 */
+  --sl-color-bg-sidebar: #1f1f23;       /* zinc-850 */
+  --sl-color-bg-inline-code: #27272a;   /* zinc-800 */
+  --sl-color-bg-accent: #818cf8;        /* indigo-400 */
+
+  /* Text */
+  --sl-color-text: #e4e4e7;             /* zinc-200 */
+  --sl-color-text-accent: #a5b4fc;      /* indigo-300 */
+  --sl-color-text-invert: #18181b;      /* zinc-900 */
+
+  /* Gray ramp */
+  --sl-color-white: #fafafa;            /* zinc-50 */
+  --sl-color-gray-1: #e4e4e7;           /* zinc-200 */
+  --sl-color-gray-2: #a1a1aa;           /* zinc-400 */
+  --sl-color-gray-3: #71717a;           /* zinc-500 */
+  --sl-color-gray-4: #52525b;           /* zinc-600 */
+  --sl-color-gray-5: #3f3f46;           /* zinc-700 */
+  --sl-color-gray-6: #27272a;           /* zinc-800 */
+  --sl-color-black: #18181b;            /* zinc-900 */
+
+  /* Accent */
+  --sl-color-accent-low: #1e1b4b;       /* indigo-950 */
+  --sl-color-accent: #6366f1;           /* indigo-500 */
+  --sl-color-accent-high: #c7d2fe;      /* indigo-200 */
+
+  /* Hairlines */
+  --sl-color-hairline-light: #27272a;   /* zinc-800 */
+  --sl-color-hairline: #3f3f46;         /* zinc-700 */
+  --sl-color-hairline-shade: #52525b;   /* zinc-600 */
+}
+
+/* Light theme — reasonable defaults, zinc-tinted. */
+:root {
+  --sl-color-accent-low: #eef2ff;       /* indigo-50 */
+  --sl-color-accent: #4f46e5;           /* indigo-600 */
+  --sl-color-accent-high: #312e81;      /* indigo-900 */
+  --sl-color-hairline-light: #e4e4e7;   /* zinc-200 */
+  --sl-color-hairline: #d4d4d8;         /* zinc-300 */
+}
+
+/* Scrollbars — mirror frontend. */
+::-webkit-scrollbar {
+  width: 6px;
+  height: 6px;
+}
+::-webkit-scrollbar-track {
+  background: #18181b;
+}
+::-webkit-scrollbar-thumb {
+  background: #3f3f46;
+  border-radius: 3px;
+}
+
+/* Nav title weight + tracking to match the app brand. */
+.site-title {
+  font-weight: 700 !important;
+  letter-spacing: -0.02em;
+}
+
+/* Tighter heading tracking. */
+h1 { letter-spacing: -0.035em; }
+h2 { letter-spacing: -0.025em; }
+h3 { letter-spacing: -0.015em; }
+
+/* Cards — rounded, accent on hover. */
+.sl-link-card,
+.card {
+  border-radius: 12px;
+}
+.sl-link-card:hover {
+  border-color: var(--sl-color-accent);
+}

package/docs-theme/fonts/Geist-LICENSE.txt

@@ -0,0 +1,92 @@
+Copyright (c) 2023 Vercel, in collaboration with basement.studio
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION AND CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/docs-theme/starlight.ts

@@ -0,0 +1,162 @@
+/**
+ * The Astro + Starlight configuration every Norsk product docs site is built
+ * from. A site's own `astro.config.mjs` is reduced to what genuinely differs:
+ * its origin, its two names, its sidebar, and the versions it was built
+ * against.
+ *
+ *     export default defineConfig(
+ *       norskDocsSite({
+ *         origin: PUBLIC_SITE_ORIGIN,
+ *         tabTitle: "Norsk",
+ *         wordmark: "norsk-ctl",
+ *         buildVersions: [...],
+ *         sidebar: [...],
+ *       }),
+ *     );
+ *
+ * Everything here is the part that must NOT differ between sites: the theme,
+ * the component overrides, the mermaid pipeline, the favicon convention, and
+ * the two-build (public / embedded) shape described on `publicBuild` below.
+ */
+import { readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { unified } from "@astrojs/markdown-remark";
+import starlight from "@astrojs/starlight";
+import rehypeMermaid from "rehype-mermaid";
+
+/** One row of the sidebar's "Built against" footer (components/Sidebar.astro). */
+export interface BuildVersion {
+  /** Row label, e.g. "norsk-ctl". */
+  label: string;
+  /** Row value, read at build time from the product's own files. */
+  value: string;
+  /** Break a `repo:tag` image pin after the last colon so it wraps sensibly. */
+  splitOnLastColon?: boolean;
+}
+
+export interface NorskDocsSiteOptions {
+  /** Canonical public origin. Drives the sitemap and <link rel="canonical">. */
+  origin: string;
+  /** BROWSER TAB suffix only ("Quickstart | Norsk"), kept short — tabs truncate. */
+  tabTitle: string;
+  /** Masthead wordmark. Deliberately different from `tabTitle`; see SiteTitle.astro. */
+  wordmark: string;
+  /** Starlight's sidebar. The one part of the nav a site fully owns. */
+  sidebar: unknown[];
+  /** Rows for the sidebar's "Built against" footer. */
+  buildVersions: BuildVersion[];
+  /**
+   * Dev-preview only: machine names `astro dev --host` may be reached by on the
+   * LAN (Vite 403s unknown Host headers otherwise). No effect on builds.
+   */
+  devAllowedHosts?: string[];
+}
+
+/**
+ * Two builds from one content collection, selected by ASTRO_BUILD:
+ * `dist-embedded` (base `/docs`) is the bundle baked into a product binary and
+ * served by the daemon, `dist-public` (base `/`) is the standalone site on the
+ * product's own domain. Exported because a site's sidebar legitimately differs
+ * between the two — a section that only exists once it is published.
+ */
+export function isPublicBuild(): boolean {
+  return process.env.ASTRO_BUILD === "public";
+}
+
+/**
+ * Content (and any vendored HTML) is authored with absolute /docs/... links —
+ * correct for the daemon-embedded build (served under /docs), but a 404 in the
+ * public build (served at /). Astro doesn't base-prefix absolute links in
+ * MDX/components/static files, so for the public build a post-build pass strips
+ * the /docs prefix from href/src attributes across the emitted HTML.
+ * Attribute-scoped so it never touches /docs literals in body text. No-op for
+ * the embedded build.
+ */
+function stripDocsBaseForPublic() {
+  const rewriteHtml = (html: string) =>
+    html.replace(/((?:href|src)=")\/docs(\/|")/g, (_m, attr, tail) => (tail === "/" ? `${attr}/` : `${attr}/"`));
+  const walk = (root: string, fn: (p: string) => void) => {
+    for (const name of readdirSync(root)) {
+      const p = join(root, name);
+      if (statSync(p).isDirectory()) walk(p, fn);
+      else if (p.endsWith(".html")) fn(p);
+    }
+  };
+  return {
+    name: "strip-docs-base-public",
+    hooks: {
+      "astro:build:done": ({ dir }: { dir: URL }) => {
+        if (!isPublicBuild()) return;
+        walk(fileURLToPath(dir), (p) => {
+          writeFileSync(p, rewriteHtml(readFileSync(p, "utf-8")));
+        });
+      },
+    },
+  };
+}
+
+export function norskDocsSite(options: NorskDocsSiteOptions) {
+  const isPublic = isPublicBuild();
+  const mermaidLaunchOptions = process.env.BROWSER_FOR_TESTING
+    ? { executablePath: process.env.BROWSER_FOR_TESTING }
+    : undefined;
+
+  return {
+    // The public site lives at the domain root; the embedded bundle is served
+    // by the daemon under /docs. `site` is the canonical origin: it drives the
+    // sitemap and <link rel="canonical">, and without it @astrojs/sitemap
+    // (pulled in by Starlight) skips and warns. The embedded build reuses the
+    // same origin — its sitemap is inert since it is never crawled, but setting
+    // `site` keeps the build warning-free.
+    site: options.origin,
+    base: isPublic ? "/" : "/docs",
+    outDir: isPublic ? "./dist-public" : "./dist-embedded",
+    markdown: {
+      syntaxHighlight: { excludeLangs: ["mermaid"] },
+      // Astro 6 deprecated top-level `rehypePlugins`; the pipeline now lives in
+      // a `unified()` processor. `syntaxHighlight` stays at the markdown level.
+      processor: unified({
+        rehypePlugins: [
+          [
+            rehypeMermaid,
+            { strategy: "img-svg", dark: true, mermaidConfig: { theme: "dark" }, launchOptions: mermaidLaunchOptions },
+          ],
+        ],
+      }),
+    },
+    integrations: [
+      stripDocsBaseForPublic(),
+      starlight({
+        title: options.tabTitle,
+        customCss: ["./src/custom.css"],
+        components: {
+          // Appends the "Built against" footer below the nav.
+          Sidebar: "./src/components/Sidebar.astro",
+          // Decouples the masthead wordmark from `title` above.
+          SiteTitle: "./src/components/SiteTitle.astro",
+          // Adds the "captured against" line to a generated guide (front
+          // matter `capturedAgainst`, see content.config.ts).
+          Footer: "./src/components/Footer.astro",
+        },
+        // Starlight base-prefixes this (emits a `/docs/favicon.png`
+        // shortcut-icon link for the embedded build); a raw head <link> would
+        // not, and 404s the embedded link-check.
+        favicon: "/favicon.png",
+        sidebar: options.sidebar,
+      }),
+    ],
+    vite: {
+      server: { allowedHosts: options.devAllowedHosts ?? [] },
+      // Injected rather than imported: a component resolving its own path at
+      // runtime finds dist-embedded/.prerender/chunks/ instead of the source
+      // tree and fails the build, and the site's version readers want the
+      // product's files, not the site's. Both values are build-time constants,
+      // so a define is the cheapest correct channel.
+      define: {
+        __BUILD_VERSIONS__: JSON.stringify(options.buildVersions),
+        __SITE_WORDMARK__: JSON.stringify(options.wordmark),
+      },
+    },
+  };
+}

package/docs-theme/sync.ts

@@ -0,0 +1,145 @@
+#!/usr/bin/env bun
+/**
+ * The docs theme is a FORCED COPY, and this is its writer and its gate.
+ *
+ *   sync.ts check <site>   diff the site's copies against this dev-kit's
+ *                          canonical bytes; exit 1 on drift, naming the file.
+ *   sync.ts sync  <site>   rewrite the copies from the canonical.
+ *
+ * `<site>` is the docs site's package root (the directory holding
+ * `astro.config.mjs`); it defaults to the current directory.
+ *
+ * WHY A COPY, when the dev-kit's rule is to single-source anything consumable.
+ * A docs site is a STANDALONE package: it carries its own bun.lock and its own
+ * node_modules, outside the monorepo's workspaces, because Astro's dependency
+ * tree has no business in the product install. So it cannot depend on the
+ * dev-kit the way every other consumer does. That is not a preference — it is
+ * checked: adding `"@norskvideo/ctl-dev-kit": "file:../../dev-kit"` to
+ * norsk-ctl's website and installing fails outright, because bun then has to
+ * resolve the dev-kit's own `workspace:*` dependencies (ctl-sdk, foundation,
+ * test-harness, product-template-schema) from a directory that is not in a
+ * workspace:
+ *
+ *     error: @norskvideo/ctl-sdk@workspace:* failed to resolve
+ *
+ * A product repo outside this monorepo installs the published tarball and hits
+ * no such wall — but it would then consume the theme by a second mechanism, and
+ * one theme reaching two sites two ways is exactly the drift this package
+ * exists to stop. So every site, here and elsewhere, gets the same deal: copies
+ * at fixed paths, rewritten by `sync`, and `check` in its test suite.
+ *
+ * The copies land at the paths Starlight and Astro already expect
+ * (`src/custom.css`, `src/components/*.astro`, `src/content.config.ts`), which
+ * is also why the canonical directory mirrors a site's `src/`: the map below is
+ * an identity. Keeping the component paths identical is load-bearing for more
+ * than tidiness — Astro derives a component's scoped-style class from its path,
+ * so moving one rewrites a class attribute on every page.
+ *
+ * Canonical bytes are resolved relative to THIS file, so the script works both
+ * workspace-symlinked and installed from the published tarball — the same
+ * arrangement as conventions/check-drift.ts.
+ */
+import { cpSync, mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const CANONICAL = dirname(fileURLToPath(import.meta.url));
+
+/** The site subdirectory the canonical tree is copied into. */
+export const SITE_DIR = "src";
+
+/**
+ * Every canonical file, as a path relative to this directory — which is also
+ * its path relative to the site's `src/`. Derived from the tree rather than
+ * listed, so a file added here reaches every site without a second edit; the
+ * script's own source and its test are the only exclusions.
+ */
+export function themeFiles(canonical: string = CANONICAL): string[] {
+  const out: string[] = [];
+  const walk = (dir: string) => {
+    for (const name of readdirSync(dir).sort()) {
+      const p = join(dir, name);
+      if (statSync(p).isDirectory()) {
+        walk(p);
+        continue;
+      }
+      const rel = relative(canonical, p);
+      if (rel === "sync.ts" || rel === "sync.test.ts" || rel === "README.md") continue;
+      out.push(rel);
+    }
+  };
+  walk(canonical);
+  return out;
+}
+
+export interface ThemeDrift {
+  ok: boolean;
+  problems: string[];
+}
+
+const RESYNC = "Edit the dev-kit source and re-run `sync`, never hand-edit the copy.";
+
+/** Compare a site's copies against the canonical bytes. Text is diffed by line
+ *  so the failure names the drift; binaries (the woff2) compare byte-wise. */
+export function checkTheme(siteRoot: string, canonical: string = CANONICAL): ThemeDrift {
+  const problems: string[] = [];
+  for (const rel of themeFiles(canonical)) {
+    const copy = join(siteRoot, SITE_DIR, rel);
+    const want = readFileSync(join(canonical, rel));
+    let got: Buffer;
+    try {
+      got = readFileSync(copy);
+    } catch {
+      problems.push(`${SITE_DIR}/${rel}: missing — the docs theme is not synced. ${RESYNC}`);
+      continue;
+    }
+    if (got.equals(want)) continue;
+    problems.push(`${SITE_DIR}/${rel}: ${firstDiff(got, want)}. ${RESYNC}`);
+  }
+  return { ok: problems.length === 0, problems };
+}
+
+function firstDiff(got: Buffer, want: Buffer): string {
+  // A woff2 has no lines worth naming; say so rather than printing binary.
+  if (got.includes(0) || want.includes(0))
+    return `differs from the canonical (${want.length} bytes, found ${got.length})`;
+  const a = got.toString("utf8").split("\n");
+  const e = want.toString("utf8").split("\n");
+  for (let i = 0; i < Math.max(a.length, e.length); i++) {
+    if (a[i] !== e[i]) {
+      return `line ${i + 1}: expected ${JSON.stringify(e[i] ?? "<missing>")}, found ${JSON.stringify(a[i] ?? "<missing>")}`;
+    }
+  }
+  return "content differs";
+}
+
+/** Rewrite the site's copies from the canonical bytes. */
+export function syncTheme(siteRoot: string, canonical: string = CANONICAL): string[] {
+  const written: string[] = [];
+  for (const rel of themeFiles(canonical)) {
+    const to = join(siteRoot, SITE_DIR, rel);
+    mkdirSync(dirname(to), { recursive: true });
+    cpSync(join(canonical, rel), to);
+    written.push(`${SITE_DIR}/${rel}`);
+  }
+  return written;
+}
+
+if (import.meta.main) {
+  const [mode, site] = process.argv.slice(2);
+  const siteRoot = site ?? process.cwd();
+  if (mode === "sync") {
+    for (const f of syncTheme(siteRoot)) console.log(`wrote ${f}`);
+  } else if (mode === "check") {
+    const { ok, problems } = checkTheme(siteRoot);
+    if (!ok) {
+      console.error("docs theme drift:");
+      for (const p of problems) console.error(`  - ${p}`);
+      process.exit(1);
+    }
+    console.log(`docs theme: ${themeFiles().length} files in step with the dev-kit.`);
+  } else {
+    console.error("usage: sync.ts check|sync [site-root]");
+    process.exit(2);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-dev-kit",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "type": "module",
   "exports": {
     "./create-product": "./create-product/create-product.ts",
@@ -12,6 +12,7 @@
     "./doc-guide/instance-proxy": "./doc-guide/instance-proxy.js",
     "./doc-guide/live-browser": "./doc-guide/live-browser.js",
     "./doc-guide/prose-bundle": "./doc-guide/prose-bundle.js",
+    "./docs-theme/sync": "./docs-theme/sync.ts",
     "./docs/path-existence": "./docs/path-existence.ts",
     "./docs/splice-generated": "./docs/splice-generated.ts",
     "./licence/check-entitlement": "./licence/check-entitlement.ts",