fix(docs): keep navbar visible on scroll (#2445) (thanks @chenyuan99)

CHANGELOG.md

@@ -39,6 +39,7 @@ Status: unreleased.
 - Telegram: allow caption param for media sends. (#1888) Thanks @mguellsegarra.
 - Telegram: support plugin sendPayload channelData (media/buttons) and validate plugin commands. (#1917) Thanks @JoshuaLelon.
 - Telegram: avoid block replies when streaming is disabled. (#1885) Thanks @ivancasco.
+- Docs: keep docs header sticky so navbar stays visible while scrolling. (#2445) Thanks @chenyuan99.
 - Security: use Windows ACLs for permission audits and fixes on Windows. (#1957)
 - Auth: show copyable Google auth URL after ASCII prompt. (#1787) Thanks @robbyczgw-cla.
 - Routing: precompile session key regexes. (#1697) Thanks @Ray0907.

docs/assets/terminal.css

@@ -87,7 +87,7 @@ body {
     radial-gradient(900px 600px at 95% 10%, color-mix(in oklab, var(--accent2) 14%, transparent), transparent 60%),
     radial-gradient(900px 600px at 50% 120%, color-mix(in oklab, var(--link) 10%, transparent), transparent 55%),
     linear-gradient(180deg, var(--bg0), var(--bg1));
-  overflow-x: visible;
+  overflow-x: hidden;
 }
 
 body::before,
@@ -115,6 +115,9 @@ body::after {
 }
 
 .shell {
+  position: sticky;
+  top: 0;
+  z-index: 100;
   padding: 22px 16px 10px;
 }
 
@@ -126,13 +129,10 @@ body::after {
     linear-gradient(180deg, color-mix(in oklab, var(--panel2) 88%, transparent), color-mix(in oklab, var(--panel) 92%, transparent));
   box-shadow: var(--shadow-px);
   border: var(--border) solid var(--frame-border);
-  overflow: visible;
+  overflow: hidden;
 }
 
 .shell__titlebar {
-  position: sticky;
-  top: 0;
-  z-index: 100;
   display: flex;
   align-items: center;
   justify-content: space-between;
@@ -298,9 +298,6 @@ body::after {
 }
 
 .shell__nav {
-  position: sticky;
-  top: 68px; /* Adjust this value based on the height of your titlebar */
-  z-index: 99;
   display: flex;
   align-items: center;
   justify-content: space-between;

src/docs/terminal-css.test.ts

@@ -0,0 +1,28 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+
+function readTerminalCss() {
+  // This test is intentionally simple: it guards against regressions where the
+  // docs header stops being sticky because sticky elements live inside an
+  // overflow-clipped container.
+  const path = join(process.cwd(), "docs", "assets", "terminal.css");
+  return readFileSync(path, "utf8");
+}
+
+describe("docs terminal.css", () => {
+  test("keeps the docs header sticky (shell is sticky)", () => {
+    const css = readTerminalCss();
+    expect(css).toMatch(/\.shell\s*\{[^}]*position:\s*sticky;[^}]*top:\s*0;[^}]*\}/s);
+  });
+
+  test("does not rely on making body overflow visible", () => {
+    const css = readTerminalCss();
+    expect(css).not.toMatch(/body\s*\{[^}]*overflow-x:\s*visible;[^}]*\}/s);
+  });
+
+  test("does not make the terminal frame overflow visible (can break layout)", () => {
+    const css = readTerminalCss();
+    expect(css).not.toMatch(/\.shell__frame\s*\{[^}]*overflow:\s*visible;[^}]*\}/s);
+  });
+});