feat(docs): view-transition polish, branded search + 404, chrome pass

AGENTS.md

@@ -334,7 +334,7 @@ The TypeScript SDK (`@wavehouse/sdk` in `clients/ts/`) is the canonical client a
 
 | Backend change | SDK considerations |
 | -------------- | ------------------ |
-| New user-facing API endpoint | Add a typed client method (in `clients/ts/src/client.ts` or the relevant subsystem file: `query-builder.ts`, `pipes.ts`, `policy.ts`, `stream/`, etc.); update `docs/src/content/docs/sdk.md` |
+| New user-facing API endpoint | Add a typed client method (in `clients/ts/src/client.ts` or the relevant subsystem file: `query-builder.ts`, `pipes.ts`, `policy.ts`, `stream/`, etc.); update the matching SDK doc page under `docs/src/content/docs/sdk/` (`queries`, `streaming`, `pipes`, `admin`, or `reference` by topic — plus the API tree in `reference.md`) |
 | Change to JWT auth / role extraction | Update auth handling in `clients/ts/src/http.ts` and types in `clients/ts/src/client.ts` |
 | Change to `EventMessage` / ingest event format | Update payload types in `clients/ts/src/` (some are codegen-regenerated — re-run the SDK codegen CLI) |
 | New / changed structured query AST | Update `clients/ts/src/query-builder.ts` types + builder methods |

docs/astro.config.mjs

@@ -116,6 +116,14 @@ export default defineConfig({
       lastUpdated: true,
       expressiveCode: {
         themes: ["github-dark", "github-light"],
+        // Long lines wrap with a hanging indent instead of growing a
+        // horizontal scrollbar — in a 45rem column, scroll-to-read code was
+        // the docs' biggest readability complaint. Authors can still opt a
+        // block out with ```lang wrap=false where alignment matters.
+        defaultProps: {
+          wrap: true,
+          preserveIndent: true,
+        },
         styleOverrides: {
           // 0.75rem − 1px so the frame's OUTER corner lands at exactly 12px
           // (--radius-md, matching cards): EC adds the 1px border width to the

docs/src/components/Footer.astro

@@ -7,6 +7,8 @@ import EditLink from "virtual:starlight/components/EditLink";
 import LastUpdated from "virtual:starlight/components/LastUpdated";
 import Pagination from "virtual:starlight/components/Pagination";
 import MermaidZoom from "./MermaidZoom.astro";
+import ReadingProgress from "./ReadingProgress.astro";
+import ScrollHints from "./ScrollHints.astro";
 import WaveMark from "./WaveMark.astro";
 
 const year = new Date().getFullYear();
@@ -24,6 +26,7 @@ const repo = "https://github.com/Wave-RF/WaveHouse";
 {
   hasSidebar ? (
     <footer class="wh-footer wh-footer--compact not-content">
+      <ReadingProgress />
       <div class="wh-footer__meta">
         <EditLink />
         <LastUpdated />
@@ -124,9 +127,11 @@ const repo = "https://github.com/Wave-RF/WaveHouse";
   )
 }
 
-{/* Click-to-zoom for Mermaid diagrams — rendered once per page from here
-    (Footer is on every page); self-contained script + styles, no markup. */}
+{/* Click-to-zoom for Mermaid diagrams + horizontal-scroll affordances —
+    rendered once per page from here (Footer is on every page);
+    self-contained scripts + styles, no markup. */}
 <MermaidZoom />
+<ScrollHints />
 
 <script is:inline>
   function setupFooterLinkTracking() {
@@ -236,14 +241,26 @@ const repo = "https://github.com/Wave-RF/WaveHouse";
     letter-spacing: -0.02em;
     color: var(--wh-ink);
   }
-  /* push the links to the trailing edge of the content column */
+  /* push the links to the trailing edge of the content column (gap sized so
+     the row + the external-link arrows still fit the prose column on one
+     line — 1.25rem tipped it into an awkward two-row wrap) */
   .wh-footer__links {
     margin-inline-start: auto;
     display: flex;
     flex-wrap: wrap;
-    gap: 1.25rem;
+    gap: 1rem;
     font-size: 0.875rem;
   }
+  /* In the 72–86rem window Starlight squeezes the content pane below the
+     prose width and the single-row bar can't fit (needs ~700px, gets ~650) —
+     wrap deliberately: links become their own left-aligned row under the
+     brand instead of a ragged right-aligned overflow. */
+  @media (max-width: 86rem) {
+    .wh-footer__links {
+      margin-inline-start: 0;
+      flex-basis: 100%;
+    }
+  }
   .wh-footer__links a {
     color: var(--wh-ink-muted);
     text-decoration: none;
@@ -342,7 +359,9 @@ const repo = "https://github.com/Wave-RF/WaveHouse";
     border-top: 1px solid var(--wh-border);
   }
 
-  @media (max-width: 50rem) {
+  /* 40rem (not 50): at tablet widths three narrow columns fit comfortably —
+     the 2-col fallback stranded PROJECT alone on a second row at 768px. */
+  @media (max-width: 40rem) {
     .wh-footer__cols {
       grid-template-columns: repeat(2, minmax(0, 1fr));
     }

docs/src/components/Head.astro

@@ -2,6 +2,7 @@
 import Default from "@astrojs/starlight/components/Head.astro";
 import VtbotStarlight from "astro-vtbot/components/starlight/Base.astro";
 import PostHog from "./PostHog.astro";
+import ProgressBar from "./ProgressBar.astro";
 ---
 
 {/*
@@ -11,9 +12,16 @@ import PostHog from "./PostHog.astro";
   <ClientRouter/> detached them (showModal on a removed dialog). fallback="swap"
   = instant swap where the View Transition API is absent. See Starlight #2823;
   full rationale in CHANGELOG.
+
+  No transition:animate choreography on purpose — a direction-aware slide +
+  title morph were tried (PR #313) and rejected as too much motion for docs.
+  <ProgressBar/> (ours, not vtbot's — see the component) is a top loading bar
+  for slow fetches; a grace delay keeps fast cached navigations from ever
+  seeing it.
 */}
 <VtbotStarlight viewTransitionsFallback="swap">
   <Default><slot /></Default>
+  <ProgressBar />
   <PostHog />
   {/*
     Two media-scoped theme-color tags so the browser chrome (mobile address bar,

docs/src/components/Hero.astro

@@ -241,6 +241,38 @@ if (import.meta.env.DEV && !heroTitle) {
   document.addEventListener('DOMContentLoaded', setupHeroCTATracking);
   document.addEventListener('astro:page-load', setupHeroCTATracking);
 
+  // The install chip follows the reader's package-manager choice from the
+  // docs' synced install tabs (Starlight persists the selected tab LABEL in
+  // localStorage under its syncKey — see /sdk's <Tabs syncKey="pkg">). The
+  // keys here must match those tab labels exactly. "CDN" (and anything
+  // unknown) keeps the pnpm default — there's no one-liner shell command for
+  // a script tag.
+  function syncHeroInstallCmd() {
+    var PKG_PREFIX = {
+      pnpm: 'pnpm add ',
+      npm: 'npm install ',
+      yarn: 'yarn add ',
+      bun: 'bun add ',
+      deno: 'deno add npm:'
+    };
+    var label = null;
+    try { label = localStorage.getItem('starlight-synced-tabs__pkg'); } catch (e) {}
+    var prefix = label && PKG_PREFIX[label];
+    if (!prefix) return;
+    document.querySelectorAll('.wh-hero__install').forEach(function(btn) {
+      var cmd = prefix + '@wavehouse/sdk';
+      btn.setAttribute('data-copy', cmd);
+      btn.setAttribute('aria-label', 'Copy: ' + cmd);
+      var span = btn.querySelector('.wh-hero__install-cmd');
+      // The command span is "<prefix text node><span.pkg>@wavehouse/sdk</span>".
+      if (span && span.firstChild && span.firstChild.nodeType === Node.TEXT_NODE) {
+        span.firstChild.nodeValue = prefix;
+      }
+    });
+  }
+  document.addEventListener('DOMContentLoaded', syncHeroInstallCmd);
+  document.addEventListener('astro:page-load', syncHeroInstallCmd);
+
   // Click-to-copy install command — devs expect it, and it makes the SDK the
   // one-line "try it now". Falls back to a manual selection range when the
   // async clipboard API isn't available (http / older browsers).
@@ -375,6 +407,17 @@ if (import.meta.env.DEV && !heroTitle) {
     gap: 0.75rem;
     margin-top: 0.5rem;
   }
+  /* Stacked CTAs on small phones hug their labels at ragged widths — go
+     full-width and centered so the pair reads as a deliberate stack. */
+  @media (max-width: 30rem) {
+    .wh-hero__actions {
+      width: 100%;
+    }
+    .wh-hero__action {
+      flex: 1 1 100%;
+      justify-content: center;
+    }
+  }
   .wh-hero__action {
     display: inline-flex;
     align-items: center;

docs/src/components/MermaidZoom.astro

@@ -1,8 +1,9 @@
 ---
-// Click-to-zoom for Mermaid diagrams. Diagrams render inside the ~46–58rem
-// content column, so wide ones (and dense ones) read small inline; clicking
-// any diagram opens it in a lightbox — small diagrams scale up to fill the
-// viewport, wide ones show at natural size with pan-scroll for full detail.
+// Click-to-zoom for Mermaid diagrams. Dense diagrams read small inline;
+// clicking any diagram opens it in a lightbox that always FITS the viewport
+// (small diagrams scale up, capped 2.5×; oversized ones scale down — never
+// scrollbars by default). Diagrams larger than the stage also get a 1:1
+// toggle: natural size with pan + edge fades, for full label detail.
 //
 // Rendered once (from Footer.astro, which is on every page). The script uses
 // event delegation on `document` so it survives Astro view-transition
@@ -42,12 +43,19 @@
       overlay.setAttribute("aria-modal", "true");
       overlay.setAttribute("aria-label", "Enlarged diagram");
       overlay.innerHTML =
+        '<button class="wh-zoom__one" type="button" hidden aria-pressed="false" ' +
+        'aria-label="Toggle natural size (pan to explore)">1:1</button>' +
         '<button class="wh-zoom__close" type="button" aria-label="Close enlarged diagram">' +
         '<svg viewBox="0 0 24 24" width="22" height="22" aria-hidden="true" fill="none" ' +
         'stroke="currentColor" stroke-width="2" stroke-linecap="round">' +
         '<path d="M6 6l12 12M18 6L6 18"/></svg></button>' +
         '<div class="wh-zoom__stage"></div>';
       overlay.addEventListener("click", (e) => {
+        if (e.target.closest(".wh-zoom__one")) {
+          const btn = e.target.closest(".wh-zoom__one");
+          if (overlay.__whSetMode) overlay.__whSetMode(btn.getAttribute("aria-pressed") !== "true");
+          return;
+        }
         // Backdrop / stage padding click closes; clicks on the SVG itself don't.
         if (!e.target.closest("svg") || e.target.closest(".wh-zoom__close")) close();
       });
@@ -58,6 +66,13 @@
       if (!overlay) buildOverlay();
       const stage = overlay.querySelector(".wh-zoom__stage");
       stage.replaceChildren();
+      // The stage is reused across opens — a prior 1:1 pan session leaves
+      // its edge-fade attributes behind, which painted a phantom fade on
+      // the next (fitting) diagram.
+      stage.removeAttribute("data-wh-more");
+      stage.removeAttribute("data-wh-more-start");
+      stage.scrollLeft = 0;
+      stage.scrollTop = 0;
 
       // Re-id the clone rather than cloneNode-ing as-is: a Mermaid SVG scopes
       // its entire inline <style> (font-family, themed fills) by the root id
@@ -76,16 +91,54 @@
       const vb = (svg.getAttribute("viewBox") || "").split(/\s+/).map(Number);
       const natW = vb.length === 4 && vb[2] ? vb[2] : svg.getBoundingClientRect().width;
       const natH = vb.length === 4 && vb[3] ? vb[3] : svg.getBoundingClientRect().height;
-      const fit = Math.min((window.innerWidth * 0.94) / natW, (window.innerHeight * 0.9) / natH);
-      // Enlarge diagrams smaller than the viewport (cap 2.5×); show larger
-      // ones at natural size and let the stage scroll for pan.
-      const scale = fit > 1 ? Math.min(fit, 2.5) : 1;
-      clone.style.width = natW * scale + "px";
-      clone.style.height = natH * scale + "px";
+      // Fit inside the stage's CONTENT box: its max-width/height (94vw/90vh)
+      // include its own padding, so sizing against the raw viewport fractions
+      // overshot by the padding and the "fully zoomed" state always showed
+      // both scrollbars. Read the padding from computed style (clamp()
+      // resolves without layout) rather than duplicating the CSS values here.
+      const cs = getComputedStyle(stage);
+      const padX = parseFloat(cs.paddingLeft) + parseFloat(cs.paddingRight);
+      const padY = parseFloat(cs.paddingTop) + parseFloat(cs.paddingBottom);
+      const fit = Math.min(
+        (window.innerWidth * 0.94 - padX) / natW,
+        (window.innerHeight * 0.9 - padY) / natH,
+      );
+      // The modal ALWAYS fits the diagram to the stage — scaling UP small
+      // diagrams (cap 2.5×) and DOWN oversized ones — so the default view
+      // never grows scrollbars (which also squared the sheet's rounded
+      // corners). Diagrams larger than the stage get a 1:1 toggle instead:
+      // natural size + pan, with the ScrollHints edge fades as the wayfinding
+      // (pinch-zoom also works natively on touch). Floor the pixel sizes so
+      // fractional rounding can't tip a perfect fit into a 1px overflow.
+      const fitScale = Math.min(fit, 2.5);
+      const sizeTo = (scale) => {
+        clone.style.width = Math.floor(natW * scale) + "px";
+        clone.style.height = Math.floor(natH * scale) + "px";
+      };
+      sizeTo(fitScale);
       clone.style.maxWidth = "none";
       clone.style.minWidth = "0";
       stage.appendChild(clone);
 
+      const oneBtn = overlay.querySelector(".wh-zoom__one");
+      oneBtn.hidden = !(fit < 0.98); // 1:1 only buys anything when fit shrank it
+      oneBtn.setAttribute("aria-pressed", "false");
+      overlay.__whSetMode = (natural) => {
+        sizeTo(natural ? 1 : fitScale);
+        oneBtn.setAttribute("aria-pressed", String(natural));
+        stage.scrollLeft = 0;
+        stage.scrollTop = 0;
+        // Stamp the edge fades for the new size (ScrollHints' capture-phase
+        // scroll listener keeps them updated as the user pans).
+        requestAnimationFrame(() => {
+          stage.toggleAttribute(
+            "data-wh-more",
+            stage.scrollWidth - stage.clientWidth - stage.scrollLeft > 8,
+          );
+          stage.toggleAttribute("data-wh-more-start", false);
+        });
+      };
+
       overlay.removeAttribute("hidden");
       // Next frame so the un-hide paints before the open transition.
       requestAnimationFrame(() => overlay.classList.add("is-open"));
@@ -168,7 +221,10 @@
     max-height: 90vh;
     overflow: auto;
     display: grid;
-    place-items: center;
+    /* `safe`: plain centering makes the overflow START side unreachable when
+       a natural-size diagram exceeds the stage (phones could never scroll to
+       the diagram's left/top edge); safe centering falls back to start. */
+    place-items: safe center;
     border-radius: var(--radius-md, 12px);
     /* The cloned SVG's themed fills use --wh-mermaid-* vars resolved on
        :root, so the diagram keeps its colors inside the overlay. A surface
@@ -181,7 +237,8 @@
   .wh-zoom__stage > svg {
     display: block;
   }
-  .wh-zoom__close {
+  .wh-zoom__close,
+  .wh-zoom__one {
     position: fixed;
     top: clamp(0.5rem, 2vw, 1.25rem);
     right: clamp(0.5rem, 2vw, 1.25rem);
@@ -194,13 +251,30 @@
     background: var(--wh-surface, #14171c);
     color: var(--wh-ink, #f1f3f7);
     cursor: pointer;
-    transition: background 0.12s ease, transform 0.12s ease;
+    transition: background 0.12s ease, transform 0.12s ease,
+      border-color 0.12s ease;
+  }
+  .wh-zoom__one {
+    right: calc(clamp(0.5rem, 2vw, 1.25rem) + 3.1rem);
+    font-family: var(--sl-font-mono);
+    font-size: 0.75rem;
+    font-weight: 650;
+    letter-spacing: 0.02em;
+  }
+  .wh-zoom__one[hidden] {
+    display: none;
+  }
+  .wh-zoom__one[aria-pressed="true"] {
+    border-color: var(--wh-accent, #06b0bf);
+    color: var(--wh-accent-text, var(--wh-accent-hi, #1dc9d8));
   }
-  .wh-zoom__close:hover {
+  .wh-zoom__close:hover,
+  .wh-zoom__one:hover {
     background: var(--wh-surface-2, #1b1f26);
     transform: scale(1.05);
   }
-  .wh-zoom__close:focus-visible {
+  .wh-zoom__close:focus-visible,
+  .wh-zoom__one:focus-visible {
     outline: 2px solid var(--wh-accent-text, var(--wh-accent-hi));
     outline-offset: 2px;
   }

docs/src/components/PostHog.astro

@@ -28,7 +28,10 @@ const apiHost =
       api_host: apiHost,
       ui_host: 'https://us.posthog.com',
       defaults: '2026-01-30',
-      capture_pageview: 'history_change'
+      capture_pageview: 'history_change',
+      // Surface broken docs JS (LiveDemo SSE, copy buttons, theme scripts) in
+      // PostHog error tracking — volume on a docs site is negligible.
+      capture_exceptions: true
     })
   }
 </script>