From 2f78318c0ce98d593b4d9a382c01839a3a011665 Mon Sep 17 00:00:00 2001
From: Beckett Frey <beckett.frey@gmail.com>
Date: Thu, 20 Aug 2026 12:41:18 -0500
Subject: [PATCH] Give the docs viewer a single scroll context

/docs inset the pdoc bundle in a bordered card inside a viewport-height
region, then hung the Footer off the end of it. pdoc already ships two
scrolling panes of its own, so that stacked a third: the window scrolled to
reach the Footer, and doing so slid the whole docs card out of view.

Hand the bundle the full viewport below the navbar and drop the Footer from
this route, leaving only the two panes pdoc intends. Point the frame at
voxkit.html directly -- index.html is a meta-refresh stub, and in a frame
that hop lands in session history and swallows the first Back press.

The page no longer needs client state, so it renders on the server with
real metadata.

Closes #15
---
 app/docs/page.tsx | 54 +++++++++++++++++++++++++++++------------------
 app/globals.css   | 11 ++++++++++
 2 files changed, 44 insertions(+), 21 deletions(-)

diff --git a/app/docs/page.tsx b/app/docs/page.tsx
index f4db611..66790d4 100644
--- a/app/docs/page.tsx
+++ b/app/docs/page.tsx
@@ -1,27 +1,39 @@
-"use client";
-import { Footer, Navbar } from "../../layout";
+import type { Metadata } from "next";
+import { Navbar } from "../../layout";
 
+export const metadata: Metadata = {
+  title: "VoxKit API Documentation",
+  description:
+    "Generated API reference for the VoxKit Python package: storage, analyzers, engines, and configuration.",
+};
+
+/**
+ * The pdoc bundle in `public/docs` is already a complete documentation site,
+ * with a sidebar pane and a content pane that scroll independently. This route
+ * hands it the whole viewport below the navbar instead of insetting it in a
+ * card, so those two are the only scrollbars on the page.
+ *
+ * `Footer` is deliberately absent. As a sibling of a viewport-height region it
+ * put a third, outer scrollbar on the window, and scrolling it slid the entire
+ * docs pane out of view.
+ */
 export default function DocsPage() {
   return (
-    <>
-      <div className="h-screen flex flex-col bg-gradient-to-br from-slate-900 via-slate-800 to-slate-900 text-white overflow-hidden">
-        <Navbar view="Docs" />
-
-        {/* Documentation iframe container */}
-        <div className="flex-1 px-4 sm:px-6 lg:px-8 pt-24 pb-8 overflow-hidden">
-          <div className="max-w-7xl w-full h-full mx-auto">
-            {/* Iframe wrapper with styling */}
-            <div className="h-full rounded-lg overflow-hidden shadow-2xl border border-slate-700 bg-white">
-              <iframe
-                src="/docs/index.html"
-                className="w-full h-full border-none"
-                title="VoxKit API Documentation"
-              />
-            </div>
-          </div>
-        </div>
+    <div data-full-viewport className="h-dvh overflow-hidden bg-slate-900">
+      <Navbar view="Docs" />
+      {/* Navbar is `fixed` but sets no `top`, so it renders wherever its static
+          position falls. It has to stay the first child of an unpadded parent;
+          the clearance for it belongs on this sibling instead. */}
+      <div className="h-full pt-16">
+        {/* Straight to voxkit.html. /docs/index.html is only a meta-refresh
+            stub, and in a frame that hop becomes a session history entry, so
+            pressing Back once just bounces the visitor into the docs again. */}
+        <iframe
+          src="/docs/voxkit.html"
+          title="VoxKit API documentation"
+          className="block h-full w-full border-none"
+        />
       </div>
-      <Footer />
-    </>
+    </div>
   );
 }
diff --git a/app/globals.css b/app/globals.css
index f54bba4..3991ca1 100644
--- a/app/globals.css
+++ b/app/globals.css
@@ -27,6 +27,17 @@ body {
   overflow-y: scroll;
 }
 
+/*
+ * Opt-out for pages that fill the viewport exactly and delegate scrolling to a
+ * child (see app/docs/page.tsx). There is nothing for the window to scroll, so
+ * the forced scrollbar above would render as a second, dead track beside the
+ * child's real one. No layout shift to guard against here either: the page
+ * cannot grow past the viewport.
+ */
+body:has([data-full-viewport]) {
+  overflow-y: hidden;
+}
+
 /* Hero fall-in animation for headings */
 @keyframes fallIn {
   0% {