@specbook/ui 0.0.0-stage → 0.1.0

package/dist-viewer/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64' role='img' aria-label='Specbook'><defs><linearGradient id='g' x1='0' y1='0' x2='1' y2='1'><stop offset='0' stop-color='#8b5cf6'/><stop offset='1' stop-color='#5b21b6'/></linearGradient></defs><rect width='64' height='64' rx='15' fill='url(#g)'/><path d='M32 19.5c-4.5-3-10-3.6-15.5-2.4v28.4c5.500-1.200 11-.6 15.500 2.400 4.500-3 10-3.600 15.500-2.400V17.100c-5.500-1.200-11-.6-15.500 2.400z' fill='#fff' fill-opacity='.95'/><path d='M32 19.500v28.400' stroke='#6d28d9' stroke-width='2' stroke-linecap='round'/><path d='M38 27.500v9.500l7.500-4.750z' fill='#6d28d9'/><path d='M26.500 28.500l-4 3.750 4 3.750' fill='none' stroke='#6d28d9' stroke-width='2.200' stroke-linecap='round' stroke-linejoin='round'/></svg>

package/dist-viewer/index.html

@@ -0,0 +1,19 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
+    <meta name="referrer" content="no-referrer" />
+    <title>Specbook</title>
+    <link rel="icon" href="./favicon.svg" type="image/svg+xml" />
+    <link rel="apple-touch-icon" href="./apple-touch-icon.png" />
+    <script type="module" crossorigin src="./assets/index-DnYdlDXQ.js"></script>
+    <link rel="modulepreload" crossorigin href="./assets/panel-CoQ6iQpX.js">
+    <link rel="modulepreload" crossorigin href="./assets/mount-B-qFOcWp.js">
+    <link rel="stylesheet" crossorigin href="./assets/panel-Coi9H1nv.css">
+    <link rel="stylesheet" crossorigin href="./assets/index-Ds6DZpGP.css">
+  </head>
+  <body>
+    <div id="app"></div>
+  </body>
+</html>

package/dist-viewer/specbook.js

@@ -0,0 +1 @@
+import{r as e,t}from"./assets/mount-B-qFOcWp.js";function n(){let e=document.getElementById(`specbook-config`);if(e?.textContent)try{return JSON.parse(e.textContent)}catch{}let t=document.querySelector(`script[src$="specbook.js"][data-spec]`);return{spec:t?.dataset.spec,baseUrl:t?.dataset.baseUrl}}function r(e){let t=e?document.querySelector(e):document.getElementById(`app`);if(t)return t;let n=document.createElement(`div`);return n.id=`app`,document.body.append(n),n}var i=(e,t,n=!1)=>{e.textContent=t,e.style.cssText=`font:16px system-ui,sans-serif;padding:24px;color:${n?`#b42318`:`#5b6270`}`};async function a(){let a=n(),o=r(a.target);if(!a.spec)return i(o,`Specbook: no spec was given (set "spec" in #specbook-config).`,!0);let s;try{s=new URL(a.spec,location.href).toString()}catch{return i(o,`Specbook: "${a.spec}" is not a valid address.`,!0)}i(o,`Loading the API…`);let c=new e;try{let e=await c.open({kind:`url`,url:s}).promise;o.textContent=``,o.removeAttribute(`style`),await t({result:e,worker:c,source:{kind:`url`,url:s},baseUrl:a.baseUrl,shareable:!1,setTitle:!1})}catch(e){i(o,`Specbook: ${e instanceof Error?e.message:String(e)}`,!0)}}a();

package/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Specbook</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@specbook/ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "The Specbook docs app, spec viewer and embeddable specbook.js.",
+  "keywords": [
+    "specbook",
+    "openapi",
+    "swagger",
+    "api-documentation",
+    "api-explorer",
+    "openapi-viewer"
+  ],
+  "license": "MIT",
+  "homepage": "https://ui.specbook.dev",
+  "bugs": {
+    "url": "https://github.com/specbook-dev/specbook/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/specbook-dev/specbook.git",
+    "directory": "packages/ui"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@preact/signals": "2.11.3",
+    "@specbook/codegen": "0.1.0",
+    "@specbook/core": "0.1.0",
+    "preact": "11.0.1",
+    "prism-code-editor": "^5.4.0"
+  },
+  "devDependencies": {
+    "@faker-js/faker": "9.3.0",
+    "@specbook/vite": "0.1.0",
+    "@vitest/browser-playwright": "5.0.3",
+    "playwright": "1.64.0",
+    "typescript": "7.0.2",
+    "vite": "8.3.4",
+    "vitest": "5.0.3"
+  },
+  "files": [
+    "src",
+    "index.html",
+    "dist-viewer",
+    "!**/*.test.*"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsc --noEmit",
+    "test": "vitest run",
+    "test:browser": "pnpm --filter @specbook/vite build && vitest run --config vitest.browser.config.ts",
+    "build:viewer": "vite build --config vite.viewer.config.ts",
+    "dev:viewer": "vite --config vite.viewer.config.ts",
+    "test:viewer": "pnpm run build:viewer && vitest run --config vitest.viewer.config.ts",
+    "build:site": "pnpm run build:viewer && node scripts/assemble-site.mjs",
+    "deploy:site": "pnpm run build:viewer && node scripts/assemble-site.mjs --previous https://ui.specbook.dev && npx --yes wrangler@4 pages deploy dist-site --project-name specbook-ui --branch main"
+  }
 }

package/src/app.tsx

@@ -0,0 +1,363 @@
+import { signal } from '@preact/signals'
+import { useEffect, useMemo, useRef, useState } from 'preact/hooks'
+import markUrl from './assets/mark.svg'
+import { applyBranding, brand } from './branding'
+import { CatalogList, Overview, type ServiceInfo } from './components/Catalog'
+import { EnvBadge } from './components/EnvBadge'
+import { EnvironmentMenu } from './components/EnvironmentMenu'
+import { GitHubStar } from './components/GitHubStar'
+import { ListResizer, listWidth } from './components/ListResizer'
+import { Palette } from './components/Palette'
+import { ShareMenu } from './components/ShareMenu'
+import { ThemeToggle } from './components/ThemeToggle'
+import type { SequenceInfo, Variant } from './engine'
+import { type Entry, go, pageOf, paletteOpen, parseHash, route, setDefaultService } from './nav'
+import { engine, registry } from './runtime'
+import { env, environmentRisk, environments, locale, seed, version } from './store'
+
+// the hosted viewer is Specbook itself, so its header carries our mark unless the API brings a logo
+const ownMark = globalThis.__SPECBOOK_VIEWER__?.source ? markUrl : undefined
+
+// one API: its links leave the service out
+{
+  const names = Object.keys(registry.manifests)
+  setDefaultService(names.length === 1 ? names[0] : undefined)
+}
+
+const fakerLocales = signal<string[]>([])
+
+type HostModule = typeof import('./panel/Host')
+
+/** The side panel is a separate chunk: it holds the editor and is only fetched on first Play. */
+function usePanelHost() {
+  const [host, setHost] = useState<HostModule>()
+  const wanted = route.value.kind === 'op' || route.value.kind === 'seq'
+  useEffect(() => {
+    if (wanted && !host) import('./panel/Host').then(setHost)
+  }, [wanted, host])
+  return wanted ? host : undefined
+}
+
+export function App() {
+  const [variants, setVariants] = useState<Record<string, Variant[]>>({})
+  const [sequences, setSequences] = useState<SequenceInfo[] | undefined>(undefined)
+  const [menuOpen, setMenuOpen] = useState(false)
+
+  useEffect(() => {
+    const onHash = () => {
+      route.value = parseHash(location.hash)
+    }
+    addEventListener('hashchange', onHash)
+    // The project's config comes first: the overview waits for it. Saved requests and sequences are
+    // only needed for search and the Try picker, so they load once the first screen can be drawn.
+    const loadRest = () => {
+      engine.loadVariants(registry.requests, version.value).then(setVariants)
+      // Headers are read from the files' text; only ones that aren't plain literals are imported.
+      const odd = registry.sequences.filter((e) => registry.unresolvedSequences.includes(e.file))
+      if (odd.length) engine.loadSequences(odd, version.value).then(setSequences)
+    }
+    engine
+      .config(version.value)
+      .then(async (c) => {
+        fakerLocales.value = Object.keys(c.faker?.locales ?? {})
+        if (c.faker?.default) locale.value = c.faker.default
+        const b = c.branding
+        const assets = registry.brandingAssets
+        const only = Object.values(registry.manifests)
+        // with one API, the spec's own `info.x-logo` is the fallback after the project's files
+        const spec = only.length === 1 ? only[0]?.logo : undefined
+        const file = b?.logo ?? (await assets.logo?.().catch(() => undefined))
+        const resolved = {
+          ready: true,
+          name: b?.name,
+          title: b?.title,
+          tagline: b?.tagline,
+          links: b?.links ?? [],
+          badge: b?.badge,
+          logo: file ?? spec?.url,
+          logoBackground: file ? undefined : spec?.backgroundColor,
+          favicon: b?.favicon ?? (await assets.favicon?.().catch(() => undefined)),
+        }
+        brand.value = resolved
+        applyBranding(b, resolved, only.length === 1 ? (only[0]?.title ?? 'Specbook') : 'Specbook')
+      })
+      .catch(() => {
+        // a project without a readable config still gets its overview, from the APIs' own titles
+        brand.value = { ...brand.value, ready: true }
+      })
+      .finally(loadRest)
+    engine.environments(version.value).then((e) => {
+      environments.value = e
+    })
+    engine.environmentRisks(version.value).then((r) => {
+      environmentRisk.value = r
+    })
+    return () => removeEventListener('hashchange', onHash)
+  }, [])
+
+  // the settings menu (a phone) closes when you go somewhere else, or press Escape
+  const lastRoute = useRef(route.value)
+  useEffect(() => {
+    if (lastRoute.current === route.value) return
+    lastRoute.current = route.value
+    setMenuOpen(false)
+  }, [route.value])
+  useEffect(() => {
+    if (!menuOpen) return
+    const key = (e: KeyboardEvent) => e.key === 'Escape' && setMenuOpen(false)
+    addEventListener('keydown', key)
+    return () => removeEventListener('keydown', key)
+  }, [menuOpen])
+
+  const multiService = Object.keys(registry.manifests).length > 1
+  const entries = useMemo<Entry[]>(() => {
+    const out: Entry[] = []
+    const metas = [
+      ...Object.values(registry.sequenceMeta),
+      ...(sequences ?? []).map((s) => ({ ...s.seq.meta })),
+    ]
+    for (const m of metas) {
+      out.push({
+        kind: 'seq',
+        route: { kind: 'seq', id: m.id },
+        title: m.title,
+        group: m.tags?.[0] ?? 'sequence',
+        tags: m.tags,
+        flowGroup: m.group,
+        description: m.description,
+        hay: `${m.description ?? ''} ${(m.tags ?? []).join(' ')}`,
+      })
+    }
+    for (const m of Object.values(registry.manifests)) {
+      for (const o of m.operations) {
+        const key = `${m.service}/${o.id}`
+        const saved = (variants[key] ?? []).map((v) => v.name).join(' ')
+        out.push({
+          kind: 'op',
+          route: { kind: 'op', key },
+          title: o.summary?.replace(/\.$/, '') || o.path,
+          group: `${multiService ? `${m.service} · ` : ''}${o.tags[0] ?? 'default'}`,
+          service: m.service,
+          tag: o.tags[0] ?? 'default',
+          method: o.method,
+          path: o.path,
+          secured: o.secured,
+          hay: `${o.id} ${o.method} ${o.path} ${o.tags.join(' ')} ${saved}`,
+        })
+      }
+    }
+    return out
+  }, [sequences, variants, multiService])
+
+  const r = route.value
+  const opInfo = r.kind === 'op' ? findOp(r.key) : undefined
+  const seqId = r.kind === 'seq' ? r.id : undefined
+  const [opened, setOpened] = useState<SequenceInfo>()
+  useEffect(() => {
+    if (!seqId) return
+    const file = registry.sequenceMeta[seqId]?.file
+    if (file) {
+      const entry = registry.sequences.filter((e) => e.file === file)
+      engine.loadSequences(entry, version.value).then((l) => setOpened(l[0]))
+    } else setOpened(sequences?.find((s) => s.seq.meta.id === seqId))
+  }, [seqId, sequences, version.value])
+  const seqInfo = opened?.seq.meta.id === seqId ? opened : undefined
+  const panel = usePanelHost()
+  const close = () => go(pageOf(route.value))
+
+  const services = useMemo<ServiceInfo[]>(
+    () =>
+      Object.values(registry.manifests)
+        .map((m) => ({
+          id: m.service,
+          title: m.title,
+          version: m.version,
+          ops: m.operations.length,
+        }))
+        .sort((a, b) => a.id.localeCompare(b.id)),
+    [],
+  )
+
+  // previous/next within the group the open item belongs to
+  const neighbors = useMemo(() => {
+    if (r.kind !== 'op' && r.kind !== 'seq') return {}
+    const active = entries.find(
+      (e) =>
+        (e.route.kind === 'op' && r.kind === 'op' && e.route.key === r.key) ||
+        (e.route.kind === 'seq' && r.kind === 'seq' && e.route.id === r.id),
+    )
+    if (!active) return {}
+    const sibs = entries.filter((e) =>
+      active.kind === 'seq'
+        ? e.kind === 'seq'
+        : e.service === active.service && e.tag === active.tag,
+    )
+    const at = sibs.indexOf(active)
+    const to = (e?: Entry) => (e ? () => go({ ...e.route, play: '' } as typeof r) : undefined)
+    return { prev: to(sibs[at - 1]), next: to(sibs[at + 1]) }
+  }, [entries, r.kind === 'op' ? r.key : r.kind === 'seq' ? r.id : ''])
+
+  const navigate = (to: { tab: 'docs' | 'try'; example?: string }) =>
+    go(
+      r.kind === 'op'
+        ? { kind: 'op', key: r.key, play: to.example ?? r.play ?? '', tab: to.tab }
+        : r.kind === 'seq'
+          ? { kind: 'seq', id: r.id, play: '', tab: to.tab }
+          : r,
+    )
+
+  return (
+    <div
+      class="app"
+      style={listWidth.value ? { '--sb-list-w': `${listWidth.value}px` } : undefined}
+    >
+      <header class="header">
+        <button type="button" class="brand" onClick={() => go({ kind: 'home' })}>
+          {(brand.value.logo ?? ownMark) && (
+            <img
+              class="brand-logo"
+              src={brand.value.logo ?? ownMark}
+              alt=""
+              style={
+                brand.value.logoBackground
+                  ? {
+                      background: brand.value.logoBackground,
+                      padding: '3px 6px',
+                      borderRadius: '4px',
+                    }
+                  : undefined
+              }
+            />
+          )}
+          <span class="brand-name">{brand.value.name ?? 'Specbook'}</span>
+        </button>
+        <button type="button" class="palette-btn" onClick={() => (paletteOpen.value = true)}>
+          <span>Jump to an operation or flow…</span>
+          <kbd>⌘K</kbd>
+        </button>
+        <span class="spacer" />
+        <span class="header-env">
+          <EnvBadge />
+        </span>
+        <button
+          type="button"
+          class="menu-btn icon"
+          aria-label="Settings"
+          aria-expanded={menuOpen}
+          onClick={() => setMenuOpen(!menuOpen)}
+        >
+          ⋯
+        </button>
+        <div class={`header-controls ${menuOpen ? 'open' : ''}`}>
+          {registry.loadFaker && (
+            <span
+              class="row muted"
+              title="Generated values such as {{faker.person.fullName}}: new on every run, or fixed so the same number always gives the same data"
+            >
+              <label class="row">
+                Synthetic data
+                <select
+                  aria-label="Synthetic data"
+                  value={seed.value === undefined ? 'random' : 'fixed'}
+                  onChange={(e) => {
+                    const fixed = (e.target as HTMLSelectElement).value === 'fixed'
+                    seed.value = fixed ? (seed.value ?? 42) : undefined
+                  }}
+                >
+                  <option value="random">New each run</option>
+                  <option value="fixed">Fixed</option>
+                </select>
+              </label>
+              {seed.value !== undefined && (
+                <input
+                  type="number"
+                  class="seed-input"
+                  aria-label="Seed number"
+                  title="The same number gives the same data every run"
+                  value={seed.value}
+                  onInput={(e) => {
+                    const n = (e.target as HTMLInputElement).valueAsNumber
+                    seed.value = Number.isFinite(n) ? n : undefined
+                  }}
+                />
+              )}
+            </span>
+          )}
+          {fakerLocales.value.length > 1 && (
+            <label class="row muted">
+              locale
+              <select
+                value={locale.value ?? ''}
+                onChange={(e) =>
+                  (locale.value = (e.target as HTMLSelectElement).value || undefined)
+                }
+              >
+                {fakerLocales.value.map((l) => (
+                  <option value={l}>{l}</option>
+                ))}
+              </select>
+            </label>
+          )}
+          <EnvironmentMenu />
+          <label class="row">
+            Environment
+            <select
+              value={env.value}
+              onChange={(e) => (env.value = (e.target as HTMLSelectElement).value)}
+            >
+              {environments.value.map((e) => (
+                <option value={e}>{e}</option>
+              ))}
+            </select>
+          </label>
+          <GitHubStar />
+          <ShareMenu />
+          <ThemeToggle />
+        </div>
+      </header>
+      <div class="layout" data-view={r.kind === 'home' ? 'splash' : 'list'}>
+        <nav class="list-col" aria-label="Operations and flows">
+          <CatalogList entries={entries} services={services} />
+        </nav>
+        <ListResizer />
+        <main class="stage">
+          {(r.kind === 'home' || r.kind === 'browse') && <Overview services={services} />}
+        </main>
+      </div>
+      <Palette entries={entries} />
+      {panel && r.kind === 'op' && opInfo && (
+        <panel.Host
+          kind="op"
+          modal={false}
+          service={opInfo.service}
+          op={opInfo.op}
+          variants={variants[r.key] ?? []}
+          example={r.play ?? ''}
+          tab={r.tab}
+          onNavigate={navigate}
+          onPrev={neighbors.prev}
+          onNext={neighbors.next}
+          onClose={close}
+        />
+      )}
+      {panel && r.kind === 'seq' && seqInfo && (
+        <panel.Host
+          kind="seq"
+          modal={false}
+          info={seqInfo}
+          tab={r.tab}
+          onNavigate={navigate}
+          onPrev={neighbors.prev}
+          onNext={neighbors.next}
+          onClose={close}
+        />
+      )}
+    </div>
+  )
+}
+
+function findOp(key: string) {
+  const [service, id] = key.split('/') as [string, string]
+  const op = registry.manifests[service]?.operations.find((o) => o.id === id)
+  return op ? { service, op } : undefined
+}

package/src/assets/mark.svg

@@ -0,0 +1 @@
+<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64' role='img' aria-label='Specbook'><defs><linearGradient id='g' x1='0' y1='0' x2='1' y2='1'><stop offset='0' stop-color='#8b5cf6'/><stop offset='1' stop-color='#5b21b6'/></linearGradient></defs><rect width='64' height='64' rx='15' fill='url(#g)'/><path d='M32 19.5c-4.5-3-10-3.6-15.5-2.4v28.4c5.500-1.200 11-.6 15.500 2.400 4.500-3 10-3.600 15.500-2.400V17.100c-5.500-1.200-11-.6-15.500 2.400z' fill='#fff' fill-opacity='.95'/><path d='M32 19.500v28.400' stroke='#6d28d9' stroke-width='2' stroke-linecap='round'/><path d='M38 27.500v9.500l7.500-4.750z' fill='#6d28d9'/><path d='M26.500 28.500l-4 3.750 4 3.750' fill='none' stroke='#6d28d9' stroke-width='2.200' stroke-linecap='round' stroke-linejoin='round'/></svg>

package/src/badge.ts

@@ -0,0 +1,14 @@
+const OWN = /(^|\.)specbook\.dev$/i
+
+/**
+ * "Powered by Specbook" shows on a published site (a build, or the viewer on someone's own host) and
+ * not for the author running the dev server, nor on specbook.dev itself, where the name is already
+ * everywhere. A project turns it off with `branding.badge: false`.
+ */
+export function showBadge(o: { host: string; published: boolean; badge?: boolean }): boolean {
+  return o.published && o.badge !== false && !OWN.test(o.host)
+}
+
+/** The link back carries the host, so a site's referrals can be told apart without any tracking script. */
+export const badgeHref = (host: string) =>
+  `https://ui.specbook.dev/?ref=${encodeURIComponent(host)}`

package/src/branding.ts

@@ -0,0 +1,92 @@
+import { signal } from '@preact/signals'
+import type { BrandingConfig } from '@specbook/core'
+
+export interface Brand {
+  /** the project's config has been read; until then the overview would show its fallback text */
+  ready?: boolean
+  name?: string
+  title?: string
+  tagline?: string
+  logo?: string
+  /** background behind a logo that needs one (from the spec's x-logo) */
+  logoBackground?: string
+  favicon?: string
+  links: { label: string; href: string }[]
+  /** `false` hides the "Powered by Specbook" line */
+  badge?: boolean
+}
+
+/** The resolved branding: config text and colours, plus logo/favicon from URLs or `.specbook/branding/`. */
+export const brand = signal<Brand>({ links: [], ready: false })
+
+function rgb(hex: string): [number, number, number] | undefined {
+  const m = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(hex.trim())
+  if (!m) return undefined
+  const h =
+    (m[1] as string).length === 3
+      ? [...(m[1] as string)].map((c) => c + c).join('')
+      : (m[1] as string)
+  return [0, 2, 4].map((i) => Number.parseInt(h.slice(i, i + 2), 16)) as [number, number, number]
+}
+
+/** Whichever of white and near-black has the better contrast ratio on the accent. */
+export function onAccent(hex: string): string | undefined {
+  const c = rgb(hex)
+  if (!c) return undefined
+  const lin = c.map((v) => {
+    const s = v / 255
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4
+  })
+  const l = 0.2126 * (lin[0] as number) + 0.7152 * (lin[1] as number) + 0.0722 * (lin[2] as number)
+  const dark = 0.006 // #0b1020
+  const onWhite = 1.05 / (l + 0.05)
+  const onDark = (l + 0.05) / (dark + 0.05)
+  return onDark > onWhite ? '#0b1020' : '#ffffff'
+}
+
+const tokens = (accent: string) =>
+  `--sb-accent:${accent};--sb-accent-hover:color-mix(in srgb,${accent} 82%,black);` +
+  `--sb-focus-ring:color-mix(in srgb,${accent} 45%,white);` +
+  (onAccent(accent) ? `--sb-text-on-accent:${onAccent(accent)};` : '')
+
+/**
+ * The accent as CSS: unlayered, so it wins over the default tokens. A separate dark value applies
+ * under `prefers-color-scheme: dark` (unless the light theme is forced) and `data-theme="dark"`.
+ */
+export function brandCss(b: Pick<BrandingConfig, 'accent' | 'accentDark'>): string {
+  if (!b.accent && !b.accentDark) return ''
+  const light = b.accent ? `:root{${tokens(b.accent)}}` : ''
+  if (!b.accentDark) return light
+  return (
+    `${light}` +
+    `@media (prefers-color-scheme: dark){:root:not([data-theme="light"]){${tokens(b.accentDark)}}}` +
+    `:root[data-theme="dark"]{${tokens(b.accentDark)}}`
+  )
+}
+
+/** Applies the branding to the page: accent tokens, tab title and favicon. */
+export function applyBranding(
+  cfg: BrandingConfig | undefined,
+  resolved: Brand,
+  fallbackName: string,
+) {
+  if (typeof document === 'undefined') return
+  let style = document.getElementById('specbook-brand') as HTMLStyleElement | null
+  if (!style) {
+    style = document.createElement('style')
+    style.id = 'specbook-brand'
+    document.head.append(style)
+  }
+  style.textContent = cfg ? brandCss(cfg) : ''
+  const name = resolved.name ?? fallbackName
+  document.title = resolved.title ? `${name} · ${resolved.title}` : name
+  if (resolved.favicon || resolved.logo) {
+    let link = document.querySelector<HTMLLinkElement>('link[rel="icon"]')
+    if (!link) {
+      link = document.createElement('link')
+      link.rel = 'icon'
+      document.head.append(link)
+    }
+    link.href = (resolved.favicon ?? resolved.logo) as string
+  }
+}