From 85722ed2c45b250405c62426c46b748445f55399 Mon Sep 17 00:00:00 2001
From: Chris Feijoo <chris@kube.io>
Date: Wed, 19 Aug 2026 19:04:35 +0200
Subject: [PATCH] FE-1455: Tighten the docs site chrome

---
 apps/petrinaut-docs/README.md                 |  28 +++
 apps/petrinaut-docs/astro.config.mjs          |  41 +++-
 apps/petrinaut-docs/src/components/Head.astro |  14 ++
 .../src/components/SiteTitle.astro            | 157 +++++++++++++
 apps/petrinaut-docs/src/styles/chrome.css     | 207 ++++++++++++++++++
 5 files changed, 445 insertions(+), 2 deletions(-)
 create mode 100644 apps/petrinaut-docs/src/components/Head.astro
 create mode 100644 apps/petrinaut-docs/src/components/SiteTitle.astro
 create mode 100644 apps/petrinaut-docs/src/styles/chrome.css

diff --git a/apps/petrinaut-docs/README.md b/apps/petrinaut-docs/README.md
index fc9cf0ab92e..0d88a2da978 100644
--- a/apps/petrinaut-docs/README.md
+++ b/apps/petrinaut-docs/README.md
@@ -64,6 +64,34 @@ output, which would otherwise reach the root-hoisted `cookie@0.7.2` that
 `express` pins and fail on a missing `parseCookie` export. Nesting keeps Astro on
 its own `cookie@2.x` without changing hoisting for the rest of the monorepo.
 
+## Chrome overrides
+
+[`src/styles/chrome.css`](src/styles/chrome.css), registered as Starlight's
+`customCss`, narrows both side panels to give the content column more width,
+tones down the header, and rounds the corners on markdown images so the embedded
+diagrams match the bordered cards beside them. The left nav takes its own
+`--pnd-sidebar-width` because Starlight sizes both panels from
+`--sl-sidebar-width`, and collapsing the nav has to zero one of them without
+flattening the other. The collapse toggle and resize handle come from
+`components.SiteTitle`, the header's leftmost slot, next to the rail they act
+on — and the fixed header is the one piece of chrome still on screen once the
+nav is gone. Both
+controls remember their state in `localStorage`, restored by a `head` script so
+a collapsed sidebar does not render open and then jump.
+
+## The code font
+
+Code renders in JetBrains Mono, requested through Astro's font support in
+[`astro.config.mjs`](astro.config.mjs) and emitted by `<Font>` in
+[`src/components/Head.astro`](src/components/Head.astro).
+
+A build downloads one variable file covering weights 400 to 700, subsets it to
+latin, and writes it beside the other assets, so a reader makes no request to a
+font host. The head carries a `preload` link and `font-display: swap`, and Astro
+generates a metric-matched fallback, which is what keeps text from shifting when
+the file arrives. The downloaded originals are cached under `.astro/`, which is
+ignored.
+
 ## Deployment
 
 Vercel builds the site from [`vercel.json`](vercel.json), which runs
diff --git a/apps/petrinaut-docs/astro.config.mjs b/apps/petrinaut-docs/astro.config.mjs
index 389a70fe7f6..9c397b468cf 100644
--- a/apps/petrinaut-docs/astro.config.mjs
+++ b/apps/petrinaut-docs/astro.config.mjs
@@ -4,7 +4,7 @@ import { fileURLToPath } from "node:url";
 
 import react from "@astrojs/react";
 import starlight from "@astrojs/starlight";
-import { defineConfig } from "astro/config";
+import { defineConfig, fontProviders } from "astro/config";
 
 /**
  * Renders the architecture bundle produced by `@local/petrinaut-arch-docs`.
@@ -213,12 +213,29 @@ export default defineConfig({
   trailingSlash: "never",
   build: { format: "file" },
 
+  /*
+   * One variable file covers every weight the code blocks use, downloaded and
+   * subset at build time so a reader makes no request to a font host. Italic is
+   * left out: no code style in the docs uses it.
+   */
+  fonts: [
+    {
+      provider: fontProviders.fontsource(),
+      name: "JetBrains Mono",
+      cssVariable: "--pnd-font-mono",
+      weights: ["400 700"],
+      styles: ["normal"],
+      subsets: ["latin"],
+      fallbacks: ["ui-monospace", "SFMono-Regular", "Menlo", "monospace"],
+    },
+  ],
+
   integrations: [
     // Generated layer pages import the bundle's facts and relations cards, and
     // authored pages may import its diagram components; both are React.
     react(),
     starlight({
-      title: "Architecture Docs",
+      title: "Docs",
       description:
         "How the Petrinaut packages fit together — generated from annotations in the source.",
       // The helmet carries the Petrinaut identity, so the title beside it names
@@ -229,6 +246,26 @@ export default defineConfig({
         replacesTitle: false,
       },
       favicon: "/favicon.ico",
+      // Narrows both side panels and rounds the images, and styles the collapse
+      // controls that `components.SiteTitle` renders. See `chrome.css`.
+      customCss: ["./src/styles/chrome.css"],
+      components: {
+        Head: "./src/components/Head.astro",
+        SiteTitle: "./src/components/SiteTitle.astro",
+      },
+      // Restores the collapsed state before first paint. In the component's own
+      // script the sidebar would render at full width and then jump.
+      head: [
+        {
+          tag: "script",
+          content: `try {
+  const stored = localStorage.getItem("pnd:sidebar");
+  const width = localStorage.getItem("pnd:sidebar-width");
+  if (stored === "collapsed") document.documentElement.dataset.pndSidebar = stored;
+  if (width) document.documentElement.style.setProperty("--pnd-sidebar-open-width", width);
+} catch {}`,
+        },
+      ],
       social: [
         {
           icon: "github",
diff --git a/apps/petrinaut-docs/src/components/Head.astro b/apps/petrinaut-docs/src/components/Head.astro
new file mode 100644
index 00000000000..8d5b9f56bf2
--- /dev/null
+++ b/apps/petrinaut-docs/src/components/Head.astro
@@ -0,0 +1,14 @@
+---
+/**
+ * Starlight's head, plus the font faces and preload links for the code font.
+ *
+ * Astro's `<Font>` emits both, so the family has to be requested from a
+ * component in the head rather than from configuration alone.
+ */
+
+import Default from "@astrojs/starlight/components/Head.astro";
+import { Font } from "astro:assets";
+---
+
+<Default><slot /></Default>
+<Font cssVariable="--pnd-font-mono" preload />
diff --git a/apps/petrinaut-docs/src/components/SiteTitle.astro b/apps/petrinaut-docs/src/components/SiteTitle.astro
new file mode 100644
index 00000000000..43dd6d405b2
--- /dev/null
+++ b/apps/petrinaut-docs/src/components/SiteTitle.astro
@@ -0,0 +1,157 @@
+---
+import Default from "@astrojs/starlight/components/SiteTitle.astro";
+
+/**
+ * Adds the desktop sidebar collapse toggle and resize handle beside the title.
+ *
+ * They hang off `SiteTitle` because it is the header's leftmost slot, next to
+ * the rail's edge where the controls act, and the fixed header is the only
+ * chrome still on screen once the sidebar pane itself is collapsed away. Both
+ * are display: none unless the page has a sidebar (see `chrome.css`), so the
+ * splash-template 404 page does not grow controls with nothing to control.
+ */
+---
+
+<button
+  class="pnd-sidebar-toggle"
+  type="button"
+  aria-controls="starlight__sidebar"
+  aria-expanded="true"
+  aria-label="Toggle sidebar"
+>
+  <svg
+    aria-hidden="true"
+    width="16"
+    height="16"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    stroke-width="2"
+    stroke-linejoin="round"
+  >
+    <rect x="3" y="3" width="18" height="18" rx="2"></rect>
+    <path d="M9 3v18"></path>
+  </svg>
+</button>
+
+<Default><slot /></Default>
+
+<div
+  class="pnd-sidebar-resize"
+  role="separator"
+  aria-orientation="vertical"
+  aria-label="Resize sidebar"
+  tabindex="0"
+>
+</div>
+
+<script is:inline>
+  (() => {
+    const root = document.documentElement;
+    const toggle = /** @type {HTMLButtonElement | null} */ (
+      document.querySelector(".pnd-sidebar-toggle")
+    );
+    const handle = /** @type {HTMLElement | null} */ (
+      document.querySelector(".pnd-sidebar-resize")
+    );
+
+    if (!toggle || !handle) {
+      return;
+    }
+
+    /**
+     * @param {string} key
+     * @param {string} value
+     */
+    const remember = (key, value) => {
+      try {
+        localStorage.setItem(key, value);
+      } catch {
+        // Private browsing denies storage; the control still works this session.
+      }
+    };
+
+    toggle.setAttribute(
+      "aria-expanded",
+      String(root.dataset.pndSidebar !== "collapsed"),
+    );
+
+    toggle.addEventListener("click", () => {
+      const collapsed = root.dataset.pndSidebar !== "collapsed";
+
+      if (collapsed) {
+        root.dataset.pndSidebar = "collapsed";
+      } else {
+        delete root.dataset.pndSidebar;
+      }
+
+      toggle.setAttribute("aria-expanded", String(!collapsed));
+      remember("pnd:sidebar", collapsed ? "collapsed" : "expanded");
+    });
+
+    /** @param {number} edge Where the pane's trailing edge should land, in px. */
+    const resizeTo = (edge) => {
+      const width = `${Math.round(Math.min(Math.max(edge, 224), 480))}px`;
+
+      root.style.setProperty("--pnd-sidebar-open-width", width);
+      remember("pnd:sidebar-width", width);
+    };
+
+    handle.addEventListener("pointerdown", (event) => {
+      handle.setPointerCapture(event.pointerId);
+
+      /** @param {PointerEvent} move */
+      const onMove = (move) => resizeTo(move.clientX);
+
+      handle.addEventListener("pointermove", onMove);
+      handle.addEventListener(
+        "pointerup",
+        () => handle.removeEventListener("pointermove", onMove),
+        { once: true },
+      );
+    });
+
+    handle.addEventListener("keydown", (event) => {
+      const step =
+        event.key === "ArrowLeft" ? -16 : event.key === "ArrowRight" ? 16 : 0;
+
+      if (step !== 0) {
+        event.preventDefault();
+        resizeTo(handle.getBoundingClientRect().left + 3 + step);
+      }
+    });
+
+    // A gradient cannot ask whether the text fits, so the labels that do not
+    // fit are marked here and the fade keys off the mark. Deferred because this
+    // script is in the header, which the browser parses before the sidebar.
+    const markLabels = () => {
+      const pane = document.querySelector(".sidebar-content");
+
+      if (!pane) {
+        return;
+      }
+
+      const labels = pane.querySelectorAll("a > span, .group-label > span");
+
+      const markClipped = () => {
+        for (const label of labels) {
+          label.toggleAttribute(
+            "data-pnd-clipped",
+            label.scrollWidth > label.clientWidth + 1,
+          );
+        }
+      };
+
+      markClipped();
+      // Fires on the pane's own resize and when expanding a group changes it.
+      new ResizeObserver(markClipped).observe(pane);
+      pane.addEventListener("toggle", markClipped, { capture: true });
+    };
+
+    if (document.readyState === "loading") {
+      document.addEventListener("DOMContentLoaded", markLabels, { once: true });
+    } else {
+      markLabels();
+    }
+  })();
+</script>
diff --git a/apps/petrinaut-docs/src/styles/chrome.css b/apps/petrinaut-docs/src/styles/chrome.css
new file mode 100644
index 00000000000..a98013bc68a
--- /dev/null
+++ b/apps/petrinaut-docs/src/styles/chrome.css
@@ -0,0 +1,207 @@
+/*
+ * Chrome overrides for the architecture docs site, registered as Starlight's
+ * `customCss`. Custom CSS is unlayered, so these rules win over Starlight's
+ * `@layer starlight.core` without needing extra specificity to fight it. The
+ * exception is `Page.astro`'s inline `<style>` block, which is also unlayered:
+ * `--sl-content-inline-start` and the no-sidebar `--sl-content-width` are set
+ * there, so the `:root[data-has-sidebar]` prefixes below are load-bearing
+ * specificity, not decoration.
+ *
+ * Every sidebar rule is gated on `[data-has-sidebar]`: the 404 page uses the
+ * splash template, which has no sidebar to toggle, resize, or collapse.
+ */
+
+:root {
+  /*
+   * Starlight derives both side panels from `--sl-sidebar-width`. The left nav
+   * takes its own width so collapsing it can zero that one without flattening
+   * the on-this-page column, which keeps this variable for the right panel.
+   */
+  --sl-sidebar-width: 15rem;
+  --sl-content-width: 56rem;
+
+  /* Set inline on `<html>` by the resize handle, then restored on load. */
+  --pnd-sidebar-open-width: 15.5rem;
+  --pnd-sidebar-width: var(--pnd-sidebar-open-width);
+}
+
+/* Collapsing hands the width the nav gives up to the content column. */
+:root[data-has-sidebar][data-pnd-sidebar="collapsed"] {
+  --pnd-sidebar-width: 0rem;
+  --sl-content-width: 64rem;
+}
+
+/* 50rem is where Starlight turns the mobile drawer into a fixed rail. */
+@media (min-width: 50rem) {
+  :root[data-has-sidebar] {
+    --sl-content-inline-start: var(--pnd-sidebar-width);
+  }
+
+  .sidebar-pane {
+    width: var(--pnd-sidebar-width);
+  }
+
+  :root[data-pnd-sidebar="collapsed"] .sidebar-pane {
+    display: none;
+  }
+
+  /* Not zero: below 72rem nothing else insets the column from the edge. */
+  :root[data-has-sidebar][data-pnd-sidebar="collapsed"] {
+    --sl-content-inline-start: 2rem;
+  }
+}
+
+/* Code font -------------------------------------------------------------- */
+
+/* Starlight composes its own system stack after this, so it stays the fallback. */
+:root {
+  --sl-font-mono: var(--pnd-font-mono);
+}
+
+/* Header ---------------------------------------------------------------- */
+
+.site-title {
+  gap: 0.6rem;
+  font-size: var(--sl-text-sm);
+  font-weight: 500;
+  letter-spacing: 0.09em;
+  text-transform: uppercase;
+}
+
+.site-title img {
+  height: 1.5rem;
+}
+
+/* Sidebar controls ------------------------------------------------------ */
+
+/* Both controls belong to the desktop rail; the mobile drawer has its own. */
+.pnd-sidebar-toggle,
+.pnd-sidebar-resize {
+  display: none;
+}
+
+@media (min-width: 50rem) {
+  :root[data-has-sidebar] .pnd-sidebar-toggle {
+    display: flex;
+    flex: none;
+    align-items: center;
+    justify-content: center;
+    /* The wrapper has no gap, so the separation from the logo is set here.
+       The negative start pulls the button in from the header padding — only
+       as far as the title wrapper's own negative margin, since its
+       `overflow: clip` cuts anything past that. */
+    margin-inline: -0.25rem 0.85rem;
+    width: var(--sl-menu-button-size);
+    height: var(--sl-menu-button-size);
+    padding: 0;
+    border: 0;
+    border-radius: 0.25rem;
+    background: none;
+    color: var(--sl-color-gray-3);
+    cursor: pointer;
+  }
+
+  .pnd-sidebar-toggle:hover {
+    /* One step lighter than the header's own background, which in dark mode
+       is `--sl-color-gray-6` itself — that value would make hover invisible. */
+    background: var(--sl-color-gray-5);
+    color: var(--sl-color-white);
+  }
+
+  /*
+   * Rendered in the header but positioned against the viewport, so it sits on
+   * the pane's trailing edge and escapes the title wrapper's `overflow: clip`.
+   */
+  :root[data-has-sidebar] .pnd-sidebar-resize {
+    display: block;
+    position: fixed;
+    z-index: var(--sl-z-index-menu);
+    inset-block: var(--sl-nav-height) 0;
+    inset-inline-start: calc(var(--pnd-sidebar-width) - 3px);
+    width: 6px;
+    cursor: col-resize;
+    touch-action: none;
+  }
+
+  .pnd-sidebar-resize:hover,
+  .pnd-sidebar-resize:focus-visible {
+    background: var(--sl-color-accent);
+    outline: none;
+  }
+
+  :root[data-pnd-sidebar="collapsed"] .pnd-sidebar-resize {
+    display: none;
+  }
+}
+
+/* Sidebar labels -------------------------------------------------------- */
+
+/*
+ * One line per item. A label that outgrows the rail fades out at its trailing
+ * edge rather than wrapping to a second line, so the rail keeps one rhythm and
+ * a narrow sidebar stays readable.
+ */
+.sidebar-content a > span,
+.sidebar-content .group-label > span {
+  display: block;
+  overflow: hidden;
+  white-space: nowrap;
+}
+
+/* Marked by the header script, so a label that fits keeps its last letters. */
+.sidebar-content [data-pnd-clipped] {
+  mask-image: linear-gradient(to right, #000 calc(100% - 1.25rem), transparent);
+}
+
+/*
+ * The label fills the row rather than shrink-wrapping its text. Left as a flex
+ * item sized to content, the fade landed on the last word of every group
+ * header instead of at the rail's edge. `min-width: 0` is what lets this flex
+ * item shrink below its content at all.
+ */
+.sidebar-content .group-label {
+  flex: 1;
+  min-width: 0;
+}
+
+/* Sidebar groups -------------------------------------------------------- */
+
+/*
+ * A group grows and shrinks instead of snapping. `::details-content` is the box
+ * to animate, and `interpolate-size` is what makes the `auto` keyword a
+ * transition target; `allow-discrete` keeps the content painted for the whole
+ * collapse rather than dropping it on the first frame. Both features are recent,
+ * so the rule is guarded and older browsers keep the instant toggle.
+ */
+@supports selector(::details-content) and (interpolate-size: allow-keywords) {
+  @media (prefers-reduced-motion: no-preference) {
+    :root {
+      interpolate-size: allow-keywords;
+    }
+
+    .sidebar-content details::details-content {
+      block-size: 0;
+      overflow: hidden;
+      transition:
+        block-size 220ms ease,
+        content-visibility 220ms allow-discrete;
+    }
+
+    .sidebar-content details[open]::details-content {
+      block-size: auto;
+    }
+  }
+}
+
+/* Content --------------------------------------------------------------- */
+
+/*
+ * Rendered diagrams arrive as plain markdown images with a white background
+ * baked into the SVG, so they read as cards once their edge matches the layer
+ * cards beside them. Radius and border are `.arch-card`'s own values, which is
+ * why the border is a `color-mix` rather than a Starlight hairline token.
+ */
+.sl-markdown-content img {
+  border: 1px solid color-mix(in srgb, currentColor 22%, transparent);
+  border-radius: 0.5rem;
+}