docs: landing scenario finder + mobile polish + CLS fixes

docs/app/components/docs/sidebar.tsx

@@ -103,7 +103,9 @@ function NavLink({ node, current }: { node: NavNode; current: string }) {
   );
 }
 
-/** A subsection with children — collapsible, auto-opens around the active page. */
+/** A subsection with children — collapsible at any depth, auto-opens around the
+ *  active page. The label itself toggles (same behaviour as a top-level group),
+ *  so a subsection-of-a-subsection expands/collapses on click just like its parent. */
 function NavSection({ node, current }: { node: NavNode; current: string }) {
   const active = node.children?.some((c) => containsHref(c, current)) ?? false;
   const [open, setOpen] = useState(active);
@@ -112,15 +114,21 @@ function NavSection({ node, current }: { node: NavNode; current: string }) {
       setOpen(true);
     }
   }, [active]);
+  const toggle = () => setOpen((o) => !o);
   return (
     <div className="nav-subsection">
       <div className="nav-sub-head">
-        <NavLink node={node} current={current} />
-        <Caret
-          open={open}
-          onToggle={() => setOpen((o) => !o)}
-          title={node.title}
-        />
+        <button
+          type="button"
+          className={`nav-item nav-sub-toggle ${
+            node.href === current ? "active" : ""
+          }`.trim()}
+          aria-expanded={open}
+          onClick={toggle}
+        >
+          {node.title}
+        </button>
+        <Caret open={open} onToggle={toggle} title={node.title} />
       </div>
       {open ? <NavTree nodes={node.children ?? []} current={current} /> : null}
     </div>
@@ -189,25 +197,44 @@ function NavGroup({ group, current }: { group: NavNode; current: string }) {
   );
 }
 
-export function Sidebar({ onSearch }: { onSearch?: () => void }) {
+export function Sidebar({
+  onSearch,
+  open = false,
+  onClose,
+}: {
+  onSearch?: () => void;
+  /** Drawer open state — only affects the mobile (≤860px) overlay layout. */
+  open?: boolean;
+  onClose?: () => void;
+}) {
   const { pathname } = useLocation();
   const current = pathname.replace(/\/$/, "") || "/";
   const sdk = useActiveSdk();
   return (
-    <aside className="sidebar">
-      <button type="button" className="side-search" onClick={onSearch}>
-        Search docs
-        <span className="sk">
-          <kbd>⌘</kbd>
-          <kbd>K</kbd>
-        </span>
-      </button>
-      <SdkSwitch sdk={sdk} current={current} />
-      <nav id="sidenav">
-        {navForSdk(sdk).map((group) => (
-          <NavGroup key={group.title} group={group} current={current} />
-        ))}
-      </nav>
-    </aside>
+    <>
+      {/* Backdrop sits under the drawer on mobile; tapping it closes the menu. */}
+      <button
+        type="button"
+        className={`sidebar-backdrop ${open ? "open" : ""}`.trim()}
+        aria-label="Close navigation menu"
+        tabIndex={open ? 0 : -1}
+        onClick={onClose}
+      />
+      <aside className={`sidebar ${open ? "open" : ""}`.trim()}>
+        <button type="button" className="side-search" onClick={onSearch}>
+          Search docs
+          <span className="sk">
+            <kbd>⌘</kbd>
+            <kbd>K</kbd>
+          </span>
+        </button>
+        <SdkSwitch sdk={sdk} current={current} />
+        <nav id="sidenav">
+          {navForSdk(sdk).map((group) => (
+            <NavGroup key={group.title} group={group} current={current} />
+          ))}
+        </nav>
+      </aside>
+    </>
   );
 }

docs/app/components/landing/demo-modal.tsx

@@ -0,0 +1,192 @@
+import { useEffect, useRef, useState } from "react";
+import { useThemeMode } from "@/lib/theme";
+
+/** A live demo the finder can open: the embed id + a human title for the bar. */
+export interface DemoTarget {
+  /** Demo id understood by `demos/interactive.html?embed=` (e.g. "ratelimit"). */
+  id: string;
+  /** Title shown in the modal bar. */
+  title: string;
+}
+
+function prefersReducedMotion(): boolean {
+  if (typeof window === "undefined") return false;
+  return Boolean(
+    window.matchMedia?.("(prefers-reduced-motion: reduce)").matches,
+  );
+}
+
+const PLAY_ICON = (
+  <svg
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth={2}
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    aria-hidden="true"
+  >
+    <path d="m8 5 11 7-11 7V5z" />
+  </svg>
+);
+
+const CLOSE_ICON = (
+  <svg
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth={2.2}
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    aria-hidden="true"
+  >
+    <path d="M18 6 6 18M6 6l12 12" />
+  </svg>
+);
+
+/**
+ * Centered overlay that opens a finder scenario's live demo in an `<iframe>`,
+ * pointed at the vendored `demos/interactive.html` embed mode (theme inherited
+ * from the host). React port of `INTEGRATION-scenario-finder.md` §6: focus moves
+ * to the close button on open and restores on close, Escape + backdrop close,
+ * background scroll is locked, and the enter transition is motion-aware.
+ *
+ * `demo === null` keeps the modal closed; a brief exit transition plays before
+ * the iframe unmounts so the demo stops running.
+ */
+export function DemoModal({
+  demo,
+  onClose,
+}: {
+  demo: DemoTarget | null;
+  onClose: () => void;
+}) {
+  const theme = useThemeMode();
+  // Mounted target (survives the exit transition after `demo` goes null).
+  const [current, setCurrent] = useState<DemoTarget | null>(demo);
+  // Drives the `.open` class — toggled a frame after mount so the enter plays.
+  const [shown, setShown] = useState(false);
+  const [loading, setLoading] = useState(true);
+  const closeRef = useRef<HTMLButtonElement>(null);
+  const dialogRef = useRef<HTMLDivElement>(null);
+  const restoreRef = useRef<HTMLElement | null>(null);
+
+  useEffect(() => {
+    if (demo) {
+      restoreRef.current = (document.activeElement as HTMLElement) ?? null;
+      setCurrent(demo);
+      setLoading(true);
+      const raf = requestAnimationFrame(() => setShown(true));
+      return () => cancelAnimationFrame(raf);
+    }
+    setShown(false);
+    const timer = setTimeout(
+      () => setCurrent(null),
+      prefersReducedMotion() ? 0 : 260,
+    );
+    return () => clearTimeout(timer);
+  }, [demo]);
+
+  // While a demo is mounted: lock scroll, close on Escape, and trap Tab focus
+  // inside the dialog so keyboard users can't reach background content.
+  useEffect(() => {
+    if (!current) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") {
+        onClose();
+        return;
+      }
+      if (e.key !== "Tab") return;
+      const dialog = dialogRef.current;
+      if (!dialog) return;
+      const focusable = dialog.querySelectorAll<HTMLElement>(
+        'a[href], button:not([disabled]), iframe, [tabindex]:not([tabindex="-1"])',
+      );
+      const first = focusable[0];
+      const last = focusable[focusable.length - 1];
+      if (!first || !last) return;
+      const active = document.activeElement;
+      if (e.shiftKey && active === first) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && active === last) {
+        e.preventDefault();
+        first.focus();
+      }
+    };
+    document.addEventListener("keydown", onKey);
+    document.body.style.overflow = "hidden";
+    return () => {
+      document.removeEventListener("keydown", onKey);
+      document.body.style.overflow = "";
+    };
+  }, [current, onClose]);
+
+  // Move focus into the dialog on open; restore it to the trigger on close.
+  useEffect(() => {
+    if (shown) closeRef.current?.focus();
+  }, [shown]);
+  useEffect(() => {
+    if (!current && restoreRef.current) {
+      restoreRef.current.focus?.();
+      restoreRef.current = null;
+    }
+  }, [current]);
+
+  if (!current) return null;
+
+  // `import.meta.env.BASE_URL` ends with "/" and respects DOCS_BASE_PATH.
+  const src = `${import.meta.env.BASE_URL}demos/interactive.html?embed=${current.id}&theme=${theme}&accent=brand#${current.id}`;
+
+  return (
+    <div className={`dm-overlay${shown ? " open" : ""}`} aria-hidden={!shown}>
+      <button
+        type="button"
+        className="dm-backdrop"
+        tabIndex={-1}
+        aria-hidden="true"
+        onClick={onClose}
+      />
+      <div
+        className="dm-dialog"
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="dm-title"
+        ref={dialogRef}
+      >
+        <div className="dm-bar">
+          <span className="dm-mark">{PLAY_ICON}</span>
+          <div className="dm-meta">
+            <span className="dm-eyebrow">Live demo</span>
+            <span className="dm-title" id="dm-title">
+              {current.title}
+            </span>
+          </div>
+          <div className="dm-actions">
+            <button
+              type="button"
+              className="dm-x"
+              ref={closeRef}
+              onClick={onClose}
+              aria-label="Close demo"
+            >
+              {CLOSE_ICON}
+            </button>
+          </div>
+        </div>
+        <div className="dm-stage">
+          <div className={`dm-loading${loading ? "" : " hide"}`}>
+            <span className="dm-spin" />
+            Loading demo…
+          </div>
+          <iframe
+            className="dm-frame"
+            title={`${current.title} — interactive demo`}
+            src={src}
+            onLoad={() => setLoading(false)}
+          />
+        </div>
+      </div>
+    </div>
+  );
+}

docs/app/components/landing/index.ts

@@ -1,6 +1,7 @@
 export { Footer } from "./footer";
 export { Hero } from "./hero";
 export { useReveal } from "./reveal";
+export { ScenarioFinder } from "./scenario-finder";
 export {
   Comparison,
   CTA,