From b4050a457bc60036143471e73c7411b934a084e6 Mon Sep 17 00:00:00 2001
From: Hong Yi Chen <hongyigma@gmail.com>
Date: Sun, 10 May 2026 15:24:52 -0700
Subject: [PATCH 01/11] docs: redesign search dialog with persistent Ask AI
 footer + cleaner results
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add sticky bottom footer with 'Ask AI: "<query>"' CTA + keyboard hint strip
- Make search form sticky at top of dialog
- Add Topic > Section breadcrumb above each result; tighten title/excerpt
- Restyle <mark> highlight to a neutral chip; drop tree-diagram icon
- Move Ask AI to last navigable item; always show ⌘+I/Ctrl+I shortcut
- Close search dialog when Kapa Ask panel opens (all open paths)

Co-Authored-By: Oz <oz-agent@warp.dev>
---
 src/components/CustomSidebar.astro  | 247 ++++++++++++++++++------
 src/components/KapaChatLauncher.tsx |  10 +
 src/styles/warp-components.css      | 284 ++++++++++++++++++++++++++--
 3 files changed, 462 insertions(+), 79 deletions(-)

diff --git a/src/components/CustomSidebar.astro b/src/components/CustomSidebar.astro
index 5c512714..95964916 100644
--- a/src/components/CustomSidebar.astro
+++ b/src/components/CustomSidebar.astro
@@ -35,30 +35,115 @@ import KapaLauncher from './KapaLauncher.astro';
 <Default><slot /></Default>
 
 <!-- Search UX enhancements:
-     1. "Ask AI" row styled like a search result at the bottom of the
-        results area (GitBook-style). Always visible when results or
-        no-results message are shown.
+     1. Persistent dialog footer (GitBook-style):
+          - "Ask AI" CTA whose label interpolates the live search query
+            ("Ask AI" when empty, `Ask AI: "<query>"` once typed) and
+            surfaces the ⌘+I (Ctrl+I on Windows/Linux) shortcut. Clicking
+            it routes the query into the Kapa Ask chat panel.
+          - Keyboard-hint strip (↑↓ Navigate · ↵ Select · Esc Close)
+            hidden under 50rem.
      2. Arrow key navigation through results with visible selection
-        state. Enter opens the selected result. -->
+        state. Enter opens the selected result. Ask AI is the LAST
+        navigable item, so arrow-down past the last doc result lands
+        on it.
+     3. Breadcrumb row injected at the top of each result title,
+        derived from the result URL (first segment maps to the topic
+        label; subsequent segments are humanized). -->
 <script is:inline>
 	(() => {
 		var dialog = document.querySelector('site-search dialog');
 		if (!dialog) return;
 
+		var footerId = 'warp-search-footer';
 		var askAiId = 'warp-search-ask-ai';
+		var breadcrumbClass = 'warp-search-breadcrumb';
 		var selectedIndex = -1;
 
-		// --- Build the Ask AI row (result-card style) ---
-		function buildAskAiRow() {
-			var row = document.createElement('button');
-			row.id = askAiId;
-			row.type = 'button';
-			row.className = 'warp-search-ask-ai-row';
-			row.innerHTML = '<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/></svg>'
+		// Mirrors the top-level sidebar topic labels (see src/sidebar.ts) so
+		// the breadcrumb's first segment reads as the user-facing topic name
+		// rather than the URL slug. Unmapped segments fall back to a humanized
+		// version (e.g. "agent-platform" → "Agents", "foo-bar" → "Foo bar").
+		var TOPIC_LABELS = {
+			'terminal': 'Terminal',
+			'code': 'Code',
+			'getting-started': 'Getting started',
+			'knowledge-and-collaboration': 'Knowledge & collaboration',
+			'agent-platform': 'Agents',
+			'reference': 'Reference',
+			'changelog': 'Changelog',
+			'support-and-community': 'Support',
+			'enterprise': 'Enterprise',
+			'guides': 'Guides',
+			'api': 'API',
+		};
+
+		// Detect Apple platforms once so the Ask AI kbd reads ⌘+I on Macs and
+		// Ctrl+I elsewhere. Mirrors KapaChatLauncher.tsx which binds the same
+		// shortcut via keymatch's `CmdOrCtrl+I`.
+		var isMac = /(Mac|iPhone|iPod|iPad)/i.test(navigator.platform || '');
+		var modKey = isMac ? '\u2318' : 'Ctrl';
+
+		function humanize(slug) {
+			return slug.replace(/-/g, ' ').replace(/^(\w)/, function (c) {
+				return c.toUpperCase();
+			});
+		}
+
+		function labelForSegment(segment, isFirst) {
+			if (isFirst && TOPIC_LABELS[segment]) return TOPIC_LABELS[segment];
+			return humanize(segment);
+		}
+
+		// Build a breadcrumb (`Topic › Section`) from a result URL. We drop
+		// the leaf segment because the result title already carries it, and
+		// cap the breadcrumb at two levels (topic + section) so it stays
+		// scannable at the eyebrow scale.
+		function breadcrumbFromUrl(url) {
+			if (!url) return '';
+			var path = url;
+			try {
+				path = new URL(url, 'https://docs.warp.dev').pathname;
+			} catch (e) {}
+			var segments = path.split('/').filter(function (s) {
+				return s && s !== 'index' && !s.endsWith('.html');
+			});
+			if (segments.length === 0) return TOPIC_LABELS.terminal;
+			// Drop the leaf segment if there's more than one (the title carries it).
+			var parts = segments.length > 1 ? segments.slice(0, -1) : segments;
+			// Cap at the first two parts (topic + section) so we don't sprawl.
+			if (parts.length > 2) parts = parts.slice(0, 2);
+			return parts.map(function (seg, i) { return labelForSegment(seg, i === 0); }).join('\u00a0\u203a\u00a0');
+		}
+
+		function renderAskAiLabel(label) {
+			var query = label && label.trim();
+			if (!query) return 'Ask AI';
+			var escaped = query
+				.replace(/&/g, '&amp;')
+				.replace(/</g, '&lt;')
+				.replace(/>/g, '&gt;')
+				.replace(/"/g, '&quot;');
+			return 'Ask AI: <span class="warp-search-ask-ai-row__query">"' + escaped + '"</span>';
+		}
+
+		// --- Build the persistent footer (Ask AI + keyboard hints) once ---
+		function buildFooter() {
+			var footer = document.createElement('div');
+			footer.id = footerId;
+			footer.className = 'warp-search-footer';
+
+			var askAi = document.createElement('button');
+			askAi.id = askAiId;
+			askAi.type = 'button';
+			askAi.className = 'warp-search-ask-ai-row';
+			askAi.innerHTML =
+				'<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">'
+				+ '<path d="M9.937 15.5A2 2 0 0 0 8.5 14.063l-6.135-1.582a.5.5 0 0 1 0-.962L8.5 9.936A2 2 0 0 0 9.937 8.5l1.582-6.135a.5.5 0 0 1 .963 0L14.063 8.5A2 2 0 0 0 15.5 9.937l6.135 1.581a.5.5 0 0 1 0 .964L15.5 14.063a2 2 0 0 0-1.437 1.437l-1.582 6.135a.5.5 0 0 1-.963 0z"/>'
+				+ '<path d="M20 3v4"/><path d="M22 5h-4"/><path d="M4 17v2"/><path d="M5 18H3"/>'
+				+ '</svg>'
 				+ '<span class="warp-search-ask-ai-row__label">Ask AI</span>'
-				+ '<kbd class="warp-search-ask-ai-row__kbd" aria-hidden="true">Enter</kbd>';
-			row.addEventListener('click', function () {
-				// Grab the current search query so Kapa can pre-fill it
+				+ '<kbd class="warp-search-ask-ai-row__kbd" aria-hidden="true">' + modKey + '<span style="margin:0 0.0625rem">+</span>I</kbd>';
+			askAi.addEventListener('click', function () {
 				var searchInput = dialog.querySelector('.pagefind-ui__search-input');
 				var searchQuery = searchInput ? searchInput.value.trim() : '';
 				if (searchQuery) {
@@ -68,47 +153,82 @@ import KapaLauncher from './KapaLauncher.astro';
 				var kapaBtn = document.querySelector('.warp-kapa-button');
 				if (kapaBtn) kapaBtn.click();
 			});
-			return row;
+			footer.appendChild(askAi);
+
+			var hints = document.createElement('div');
+			hints.className = 'warp-search-keyboard-hints';
+			hints.innerHTML =
+				'<span class="warp-search-keyboard-hints__group">'
+				+ '<kbd class="warp-search-keyboard-hints__kbd">\u2191</kbd>'
+				+ '<kbd class="warp-search-keyboard-hints__kbd">\u2193</kbd>'
+				+ '<span>Navigate</span>'
+				+ '</span>'
+				+ '<span class="warp-search-keyboard-hints__group">'
+				+ '<kbd class="warp-search-keyboard-hints__kbd">\u21b5</kbd>'
+				+ '<span>Select</span>'
+				+ '</span>'
+				+ '<span class="warp-search-keyboard-hints__group">'
+				+ '<kbd class="warp-search-keyboard-hints__kbd">Esc</kbd>'
+				+ '<span>Close</span>'
+				+ '</span>';
+			footer.appendChild(hints);
+
+			return footer;
 		}
 
-		// --- Inject / remove the Ask AI row ---
-		// Pagefind re-renders the results area on every keystroke, which
-		// removes our injected element. We re-inject on every observer
-		// tick by checking if the element is still in the DOM.
-		// The Ask AI row is always visible when the dialog is open --
-		// even before the user types a query.
-		function injectAskAi() {
-			var existing = document.getElementById(askAiId);
-			// Find the best container: results area if it exists, otherwise
-			// the search container (#starlight__search) for the empty state.
-			var container = dialog.querySelector('.pagefind-ui__results-area')
-				|| dialog.querySelector('#starlight__search');
-			if (!container) return;
-			// If it already exists and is still in the container, skip
-			if (existing && container.contains(existing)) return;
-			// Re-build and append
-			if (existing) existing.remove();
-			container.appendChild(buildAskAiRow());
+		function ensureFooter() {
+			var existing = document.getElementById(footerId);
+			if (existing) return existing;
+			var frame = dialog.querySelector('.dialog-frame');
+			if (!frame) return null;
+			var footer = buildFooter();
+			frame.appendChild(footer);
+			return footer;
 		}
 
-		function removeAskAi() {
-			var el = document.getElementById(askAiId);
+		function removeFooter() {
+			var el = document.getElementById(footerId);
 			if (el) el.remove();
 		}
 
+		function updateAskAiLabel() {
+			var labelEl = dialog.querySelector('.warp-search-ask-ai-row__label');
+			if (!labelEl) return;
+			var searchInput = dialog.querySelector('.pagefind-ui__search-input');
+			var value = searchInput ? searchInput.value : '';
+			labelEl.innerHTML = renderAskAiLabel(value);
+		}
+
+		// --- Breadcrumb injection ---
+		// Pagefind re-renders the results area on every keystroke, so on every
+		// observer tick we (re)inject a small breadcrumb above each result
+		// title. The breadcrumb is idempotent (we skip if already present).
+		function injectBreadcrumbs() {
+			dialog.querySelectorAll('.pagefind-ui__result-title:not(:where(.pagefind-ui__result-nested *))').forEach(function (titleEl) {
+				if (titleEl.querySelector('.' + breadcrumbClass)) return;
+				var link = titleEl.querySelector('.pagefind-ui__result-link');
+				if (!link) return;
+				var crumb = breadcrumbFromUrl(link.getAttribute('href') || '');
+				if (!crumb) return;
+				var span = document.createElement('span');
+				span.className = breadcrumbClass;
+				span.textContent = crumb;
+				titleEl.insertBefore(span, titleEl.firstChild);
+			});
+		}
+
 		// --- Arrow key navigation ---
 		// Navigate per VISIBLE ROW: each .pagefind-ui__result-title and
 		// .pagefind-ui__result-nested is one navigable item (matching the
-		// mouse hover granularity). Ask AI is first (it's at the top).
+		// mouse hover granularity). Ask AI is LAST so arrow-down past the
+		// last result lands on it (mirrors GitBook's persistent CTA).
 		function getNavigableItems() {
 			var items = [];
-			// Ask AI row first (visually at top of results)
-			var askAi = document.getElementById(askAiId);
-			if (askAi) items.push(askAi);
-			// Collect each visible row: title rows and sub-result rows
 			dialog.querySelectorAll('.pagefind-ui__result-title:not(:where(.pagefind-ui__result-nested *)), .pagefind-ui__result-nested').forEach(function (row) {
 				items.push(row);
 			});
+			var askAi = document.getElementById(askAiId);
+			if (askAi) items.push(askAi);
 			return items;
 		}
 
@@ -128,15 +248,7 @@ import KapaLauncher from './KapaLauncher.astro';
 			selectedIndex = index;
 			var item = items[selectedIndex];
 			item.classList.add('warp-search-selected');
-			// When wrapping to the first item (Ask AI at index 0),
-			// scroll the entire dialog frame to the top so the search
-			// box and Ask AI are both visible.
-			if (selectedIndex === 0) {
-				var frame = dialog.querySelector('.dialog-frame');
-				if (frame) frame.scrollTop = 0;
-			} else {
-				item.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
-			}
+			item.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
 		}
 
 		// Clear keyboard selection when mouse moves over results
@@ -156,37 +268,54 @@ import KapaLauncher from './KapaLauncher.astro';
 			} else if (e.key === 'ArrowUp') {
 				e.preventDefault();
 				selectItem(selectedIndex - 1);
-		} else if (e.key === 'Enter') {
+			} else if (e.key === 'Enter') {
 				if (selectedIndex >= 0 && selectedIndex < items.length) {
 					e.preventDefault();
-					// For result rows, click the link inside; for Ask AI, click the row
+					// For result rows, click the link inside; for Ask AI, click the button
 					var link = items[selectedIndex].querySelector('.pagefind-ui__result-link');
 					if (link) { link.click(); } else { items[selectedIndex].click(); }
-				} else if (items.length > 1) {
-					// No selection: go to first doc result (skip Ask AI at index 0)
-					e.preventDefault();
-					var firstLink = items[1] && items[1].querySelector('.pagefind-ui__result-link');
-					if (firstLink) firstLink.click();
+				} else {
+					// No keyboard selection: open the first doc result if any.
+					var firstResult = dialog.querySelector('.pagefind-ui__result-link');
+					if (firstResult) {
+						e.preventDefault();
+						firstResult.click();
+					}
 				}
 			}
 		});
 
-		// --- Observer: inject Ask AI + reset selection on results change ---
+		// --- Observer: refresh breadcrumbs + reset selection on results change ---
+		// The footer is built once and lives outside Pagefind's render scope so
+		// it survives every re-render without re-injection.
 		var observer = new MutationObserver(function () {
-			injectAskAi();
+			injectBreadcrumbs();
 			clearSelection();
 		});
 
 		dialog.addEventListener('close', function () {
 			observer.disconnect();
-			removeAskAi();
+			removeFooter();
 			clearSelection();
 		});
 
+		// Wire the input listener at the dialog level (delegated) so it
+		// catches the Pagefind input even though that input is mounted after
+		// the dialog itself exists. Updates the Ask AI label live as the
+		// user types or clears the query.
+		dialog.addEventListener('input', function (e) {
+			if (e.target && e.target.classList && e.target.classList.contains('pagefind-ui__search-input')) {
+				updateAskAiLabel();
+			}
+		});
+
 		new MutationObserver(function () {
 			if (dialog.open) {
+				ensureFooter();
+				updateAskAiLabel();
 				var target = dialog.querySelector('#starlight__search') || dialog;
 				observer.observe(target, { childList: true, subtree: true });
+				injectBreadcrumbs();
 				clearSelection();
 			}
 		}).observe(dialog, { attributes: true, attributeFilter: ['open'] });
diff --git a/src/components/KapaChatLauncher.tsx b/src/components/KapaChatLauncher.tsx
index f4c02572..4f4c862f 100644
--- a/src/components/KapaChatLauncher.tsx
+++ b/src/components/KapaChatLauncher.tsx
@@ -122,6 +122,16 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 	};
 
 	const openPanel = () => {
+		// Close any open Pagefind search dialog so the two modals don't
+		// stack visually. This covers every path into Kapa: the `⌘+I` /
+		// `Ctrl+I` global shortcut, the trigger button, and the new
+		// "Ask AI" CTA inside the search footer (which also closes its
+		// own dialog before calling us — this is a belt-and-braces guard).
+		const searchDialog = document.querySelector<HTMLDialogElement>('site-search dialog');
+		if (searchDialog?.open) {
+			searchDialog.close();
+		}
+
 		setIsOpen(true);
 		// If a search query was passed from the search dialog's "Ask AI"
 		// button, auto-submit it after the panel opens.
diff --git a/src/styles/warp-components.css b/src/styles/warp-components.css
index dc2b2e05..06581412 100644
--- a/src/styles/warp-components.css
+++ b/src/styles/warp-components.css
@@ -956,6 +956,27 @@ site-search dialog::backdrop {
   background-color: rgba(255, 255, 255, 0.55);
 }
 
+/* Dialog frame: drop the outer padding to 0 so the sticky Pagefind form at
+   the top and our injected footer at the bottom anchor flush against the
+   dialog edges. Padding moves onto `.search-container` instead so the
+   results area keeps its original inset. The frame itself stays a flex
+   column with `overflow: auto` (the Starlight default) — sticky positioning
+   on the form + footer pins them as the body scrolls. */
+site-search dialog .dialog-frame {
+  padding: 0;
+  gap: 0;
+}
+
+site-search dialog .search-container {
+  padding: 1rem;
+}
+
+@media (min-width: 50rem) {
+  site-search dialog .search-container {
+    padding: 1.5rem;
+  }
+}
+
 /* Pagefind UI custom-property overrides. These cascade into Pagefind's own
    stylesheet (which authors all its surfaces against
    `--pagefind-ui-background` / `--pagefind-ui-border` / `--pagefind-ui-tag`
@@ -969,7 +990,13 @@ site-search dialog::backdrop {
    `--sl-search-corners` is Starlight's own knob for the result-card
    corners (defaults to `0.3125rem` = 5px, between our `sm` and `md`
    tokens, which never matches anything else). Pin it to `sm` so the
-   list rows match the input above them. */
+   list rows match the input above them.
+
+   `--sl-search-result-pad-*` are Starlight's knobs over Pagefind's own
+   default vertical padding. Pin them to a compact 0.625rem block / 0.875rem
+   inline pair so every result row sits tighter (matches GitBook density),
+   and drop the leading 3.75rem inline-start gutter that's reserved for the
+   page/tree icon — we hide that icon below. */
 site-search #starlight__search {
   --pagefind-ui-background: var(--warp-control-bg);
   --pagefind-ui-border: var(--warp-control-border);
@@ -978,6 +1005,46 @@ site-search #starlight__search {
   --pagefind-ui-primary: var(--sl-color-white);
   --pagefind-ui-border-radius: var(--sl-radius-sm);
   --sl-search-corners: var(--sl-radius-sm);
+  --sl-search-result-pad-block: 0.625rem;
+  --sl-search-result-pad-inline-start: 0.875rem;
+  --sl-search-result-pad-inline-end: 0.875rem;
+  --sl-search-result-nested-pad-block: 0.5rem;
+  --sl-search-result-spacing: 0.25rem;
+}
+
+/* Hide Starlight's leading page + tree-diagram icons. They were tuned for
+   Pagefind's default verbose layout and read as decorative noise in our
+   tighter cards. The breadcrumb injected by CustomSidebar.astro replaces
+   their role of communicating "this is a page" / "this is a heading". */
+site-search #starlight__search .pagefind-ui__result-title:not(:where(.pagefind-ui__result-nested *))::before,
+site-search #starlight__search .pagefind-ui__result-nested::before {
+  display: none;
+}
+
+/* Pin the Pagefind search form to the top of the scrolling dialog. With
+   `.dialog-frame` carrying the scroll, `position: sticky; top: 0` anchors
+   the form at the dialog's inner top edge as the user scrolls results.
+   The negative `margin-block-start` cancels the parent `.search-container`
+   padding so the form sits flush against the dialog top, and the matching
+   `padding-block-start` restores the visual inset. */
+site-search #starlight__search .pagefind-ui__form {
+  position: sticky;
+  top: 0;
+  z-index: 2;
+  background: var(--sl-color-bg);
+  margin-block-start: -1rem;
+  padding-block: 1rem 0.5rem;
+  margin-inline: -1rem;
+  padding-inline: 1rem;
+}
+
+@media (min-width: 50rem) {
+  site-search #starlight__search .pagefind-ui__form {
+    margin-block-start: -1.5rem;
+    padding-block: 1.5rem 0.5rem;
+    margin-inline: -1.5rem;
+    padding-inline: 1.5rem;
+  }
 }
 
 /* Input focus border: Starlight's default flips `--pagefind-ui-border` to
@@ -1040,56 +1107,195 @@ site-search #starlight__search .warp-search-selected {
   background-color: var(--warp-control-bg-hover);
 }
 
+/* Tighten the title typography. Pagefind's default is `21px * scale`
+   semibold; that reads as a stamped-down heading inside a 4px-radius
+   chip. Step it down to body size with the white text token so the title
+   still anchors the row but doesn't dominate it. The link itself
+   inherits color; restate it to defeat Starlight's `--pagefind-ui-text`
+   default which paints the link a lighter gray than the surrounding row. */
+site-search #starlight__search .pagefind-ui__result-title {
+  font-size: var(--sl-text-sm);
+  font-weight: 600;
+  line-height: 1.35;
+}
+
+site-search #starlight__search .pagefind-ui__result-title .pagefind-ui__result-link {
+  color: var(--sl-color-white);
+}
+
+/* Excerpt: drop a step below the title, line-clamp to 2 rows so each
+   result stays a compact two-or-three-line block instead of an open-ended
+   paragraph. `-webkit-line-clamp` is well-supported and degrades to
+   `overflow: hidden` on browsers that don't support it. */
+site-search #starlight__search .pagefind-ui__result-excerpt {
+  font-size: var(--sl-text-xs);
+  line-height: 1.5;
+  color: var(--sl-color-gray-2);
+  margin-top: 0.25rem;
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+
+/* `<mark>` highlight inside excerpts: the Pagefind default uses a saturated
+   yellow that fights the grayscale chrome. Swap to a neutral wash that
+   matches the chrome hover surface so the highlight reads as a chip rather
+   than a stamp. */
+site-search #starlight__search .pagefind-ui__result-excerpt mark,
+site-search #starlight__search .pagefind-ui__result-title mark {
+  background-color: rgba(255, 255, 255, 0.12);
+  color: var(--sl-color-white);
+  font-weight: 600;
+  padding: 0 0.125rem;
+  border-radius: var(--sl-radius-xs);
+}
+
+:root[data-theme='light'] site-search #starlight__search .pagefind-ui__result-excerpt mark,
+:root[data-theme='light'] site-search #starlight__search .pagefind-ui__result-title mark {
+  background-color: rgba(0, 0, 0, 0.08);
+  color: var(--sl-color-black);
+}
+
+/* Breadcrumb row injected by CustomSidebar.astro into each
+   `.pagefind-ui__result-title` (mirrors GitBook's small label above the
+   title showing the result's section path). Sits above the result link
+   as a quiet eyebrow at the smallest legible scale. */
+.warp-search-breadcrumb {
+  display: block;
+  margin-bottom: 0.25rem;
+  font-size: var(--sl-text-2xs);
+  font-weight: 400;
+  color: var(--sl-color-gray-3);
+  letter-spacing: 0.02em;
+}
+
+.warp-search-breadcrumb__separator {
+  margin: 0 0.25rem;
+  color: var(--sl-color-gray-4);
+}
+
+/* Nested sub-results: drop the connecting tree-diagram indent so
+   sub-results sit flush with the parent card. The breadcrumb on the
+   parent title already carries the section context. */
+site-search #starlight__search .pagefind-ui__result-nested {
+  padding-inline-start: var(--sl-search-result-pad-inline-start);
+}
+
+site-search #starlight__search .pagefind-ui__result-nested .pagefind-ui__result-link {
+  font-size: var(--sl-text-sm);
+  font-weight: 500;
+  color: var(--sl-color-gray-1);
+}
+
 /* --------------------------------------------------------------------------
-   19. "Ask AI" row in the search dialog
+   19. Persistent search footer (Ask AI + keyboard hints)
    --------------------------------------------------------------------------
-   Styled as a result card so it reads as an inline option, not a separate
-   CTA. Sits at the bottom of the results area. Shows an Enter kbd hint
-   when selected via arrow keys. */
+   GitBook-style sticky footer pinned to the bottom of the search dialog.
+   Contains the "Ask AI" CTA (with the current query interpolated into the
+   label) and a Scalar-style keyboard hint strip (↑↓ Navigate · ↵ Select ·
+   Esc Close). Built and injected once per dialog open by the script in
+   CustomSidebar.astro. */
+
+.warp-search-footer {
+  position: sticky;
+  bottom: 0;
+  z-index: 2;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+  margin-block-start: 0.5rem;
+  padding: 0.625rem 1rem 0.875rem;
+  background: var(--sl-color-bg);
+  border-top: 1px solid var(--sl-color-hairline-light);
+}
 
+@media (min-width: 50rem) {
+  .warp-search-footer {
+    padding: 0.75rem 1.5rem 1rem;
+  }
+}
+
+/* Ask AI CTA. Reads like a chrome button: same surface + hairline as the
+   trigger button this modal opened from, with a leading sparkle icon, a
+   flexible label that interpolates the current query, and a trailing
+   keyboard shortcut chip. */
 .warp-search-ask-ai-row {
   display: flex;
   align-items: center;
-  gap: 0.75rem;
+  gap: 0.625rem;
   width: 100%;
-  padding: 0.75rem 1.25rem;
-  margin-top: 0.5rem;
-  border: 0;
+  padding: 0.625rem 0.75rem;
+  border: 1px solid var(--warp-control-border);
   border-radius: var(--sl-radius-sm);
   background: var(--warp-control-bg);
-  color: var(--sl-color-text-accent);
+  color: var(--warp-control-text);
   font-family: var(--__sl-font, 'Inter', sans-serif);
   font-size: var(--sl-text-sm);
   font-weight: 500;
+  line-height: 1.2;
   cursor: pointer;
-  transition: background-color 0.15s ease, outline-color 0.15s ease;
+  transition: border-color 0.15s ease, color 0.15s ease, background-color 0.15s ease;
 }
 
 .warp-search-ask-ai-row:hover,
-.warp-search-ask-ai-row.warp-search-selected {
-  outline: 1px solid var(--warp-control-border-hover);
+.warp-search-ask-ai-row.warp-search-selected,
+.warp-search-ask-ai-row:focus-visible {
+  border-color: var(--warp-control-border-hover);
   background-color: var(--warp-control-bg-hover);
+  color: var(--warp-control-text-hover);
+  outline: none;
 }
 
 .warp-search-ask-ai-row svg {
   flex-shrink: 0;
-  opacity: 0.7;
+  width: 14px;
+  height: 14px;
+  color: var(--warp-control-icon);
+}
+
+.warp-search-ask-ai-row:hover svg,
+.warp-search-ask-ai-row.warp-search-selected svg {
+  color: var(--warp-control-text-hover);
 }
 
 .warp-search-ask-ai-row__label {
   flex: 1;
+  min-width: 0;
   text-align: left;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* Highlighted query inside the Ask AI label (e.g. `Ask AI: "<query>"`).
+   Keeps the label color but raises weight so the typed query reads as the
+   subject of the action. */
+.warp-search-ask-ai-row__query {
+  font-weight: 600;
+  color: var(--sl-color-white);
 }
 
+:root[data-theme='light'] .warp-search-ask-ai-row__query {
+  color: var(--sl-color-black);
+}
+
+/* Keyboard shortcut chip — always visible (replaces the previous Enter
+   hint that only appeared on keyboard selection). Surface mirrors
+   `.warp-sidebar-search button[data-open-modal] kbd` (§16) so the modal's
+   AI shortcut and the sidebar trigger's ⌘K share one chip style. */
 .warp-search-ask-ai-row__kbd {
-  display: none;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.125rem;
+  flex-shrink: 0;
   padding: 0.125rem 0.375rem;
   border-radius: var(--sl-radius-xs);
   background: rgba(255, 255, 255, 0.08);
   color: var(--sl-color-gray-3);
   font-family: var(--__sl-font);
   font-size: var(--sl-text-2xs);
-  font-weight: 400;
+  font-weight: 500;
   line-height: 1.2;
 }
 
@@ -1097,8 +1303,46 @@ site-search #starlight__search .warp-search-selected {
   background: rgba(0, 0, 0, 0.06);
 }
 
-/* Show the Enter hint only when the row is selected via keyboard */
-.warp-search-selected .warp-search-ask-ai-row__kbd,
-.warp-search-ask-ai-row.warp-search-selected .warp-search-ask-ai-row__kbd {
-  display: inline-block;
+/* Keyboard hints strip below the Ask AI row. A quiet single-line legend
+   of the available shortcuts (↑↓ Navigate · ↵ Select · Esc Close). Hidden
+   on narrow viewports — at mobile widths the modal already exposes a
+   Cancel button at the top and keyboard navigation is less relevant. */
+.warp-search-keyboard-hints {
+  display: none;
+  align-items: center;
+  gap: 0.875rem;
+  font-size: var(--sl-text-2xs);
+  color: var(--sl-color-gray-3);
+}
+
+@media (min-width: 50rem) {
+  .warp-search-keyboard-hints {
+    display: flex;
+  }
+}
+
+.warp-search-keyboard-hints__group {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.375rem;
+}
+
+.warp-search-keyboard-hints__kbd {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 1.25rem;
+  height: 1.25rem;
+  padding: 0 0.3125rem;
+  border-radius: var(--sl-radius-xs);
+  background: rgba(255, 255, 255, 0.08);
+  color: var(--sl-color-gray-2);
+  font-family: var(--__sl-font);
+  font-size: var(--sl-text-2xs);
+  font-weight: 500;
+  line-height: 1;
+}
+
+:root[data-theme='light'] .warp-search-keyboard-hints__kbd {
+  background: rgba(0, 0, 0, 0.06);
 }

From 5d86c29970f88e99a87a9b0db323c52041c0027a Mon Sep 17 00:00:00 2001
From: Hong Yi Chen <hongyigma@gmail.com>
Date: Sun, 10 May 2026 15:35:33 -0700
Subject: [PATCH 02/11] docs: search dialog polish round 2

- Switch dialog frame to flex column so the results scroll and the
  footer is pinned by layout (restores Pagefind's magnifier + clear
  icons that were broken by the sticky-form padding)
- Exclude CopyPageButton from the Pagefind index via
  data-pagefind-ignore so 'Copy page', 'Copy page as Markdown for
  LLMs', etc. stop leaking into every result excerpt
- Footer: bump surface to var(--sl-color-gray-6), border-top to
  var(--sl-color-hairline), and add a soft scrim above so it reads
  as clearly pinned
- Light-mode fixes: drop the broken var(--sl-color-black) overrides
  on <mark> and the Ask AI query span (--sl-color-black is WHITE in
  light mode); --sl-color-white is mode-aware and works in both
- Style the 'Load more results' button + tighten 'N results' message
  spacing and footer gap/padding
- Add scoped ::selection so dragging across results uses the chrome
  palette instead of the saturated OS accent

Co-Authored-By: Oz <oz-agent@warp.dev>
---
 src/components/CopyPageButton.astro |   2 +-
 src/styles/warp-components.css      | 122 ++++++++++++++++++----------
 2 files changed, 79 insertions(+), 45 deletions(-)

diff --git a/src/components/CopyPageButton.astro b/src/components/CopyPageButton.astro
index d1bc523e..f844f15b 100644
--- a/src/components/CopyPageButton.astro
+++ b/src/components/CopyPageButton.astro
@@ -17,7 +17,7 @@ const chatgptUrl = `https://chatgpt.com/?q=${prompt}`;
 const claudeUrl = `https://claude.ai/new?q=${prompt}`;
 ---
 
-<div class="copy-dropdown-wrapper" id="copy-dropdown-wrapper">
+<div class="copy-dropdown-wrapper" id="copy-dropdown-wrapper" data-pagefind-ignore>
   <button class="copy-dropdown-trigger" id="copy-dropdown-trigger">
     <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
       <rect width="14" height="14" x="8" y="8" rx="2" ry="2"/>
diff --git a/src/styles/warp-components.css b/src/styles/warp-components.css
index 06581412..7b8ea2fa 100644
--- a/src/styles/warp-components.css
+++ b/src/styles/warp-components.css
@@ -956,18 +956,26 @@ site-search dialog::backdrop {
   background-color: rgba(255, 255, 255, 0.55);
 }
 
-/* Dialog frame: drop the outer padding to 0 so the sticky Pagefind form at
-   the top and our injected footer at the bottom anchor flush against the
-   dialog edges. Padding moves onto `.search-container` instead so the
-   results area keeps its original inset. The frame itself stays a flex
-   column with `overflow: auto` (the Starlight default) — sticky positioning
-   on the form + footer pins them as the body scrolls. */
+/* Dialog frame: convert into a real flex column so the Pagefind-rendered
+   `.search-container` scrolls in the middle and our injected
+   `.warp-search-footer` sits as a sibling pinned by flex flow. The
+   alternative (sticky form + sticky footer on a single scroll container)
+   broke Pagefind's absolutely-positioned magnifier + clear icons — they
+   sit at `top: 13-15px` of the form, so any form-level padding pushes the
+   input down and leaves the icons floating above it. Flex flow keeps the
+   form at its default zero-padding layout. */
 site-search dialog .dialog-frame {
   padding: 0;
   gap: 0;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
 }
 
 site-search dialog .search-container {
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow-y: auto;
   padding: 1rem;
 }
 
@@ -1021,30 +1029,43 @@ site-search #starlight__search .pagefind-ui__result-nested::before {
   display: none;
 }
 
-/* Pin the Pagefind search form to the top of the scrolling dialog. With
-   `.dialog-frame` carrying the scroll, `position: sticky; top: 0` anchors
-   the form at the dialog's inner top edge as the user scrolls results.
-   The negative `margin-block-start` cancels the parent `.search-container`
-   padding so the form sits flush against the dialog top, and the matching
-   `padding-block-start` restores the visual inset. */
-site-search #starlight__search .pagefind-ui__form {
-  position: sticky;
-  top: 0;
-  z-index: 2;
-  background: var(--sl-color-bg);
-  margin-block-start: -1rem;
-  padding-block: 1rem 0.5rem;
-  margin-inline: -1rem;
-  padding-inline: 1rem;
+/* Results-count message ("12 results for changelog"). Pagefind defaults
+   to a heavy block-margin around it; pull it to a quiet single-line
+   section label flush with the first result card. */
+site-search #starlight__search .pagefind-ui__message {
+  margin: 0.25rem 0 0.75rem;
+  font-size: var(--sl-text-sm);
+  font-weight: 500;
+  color: var(--sl-color-gray-2);
 }
 
-@media (min-width: 50rem) {
-  site-search #starlight__search .pagefind-ui__form {
-    margin-block-start: -1.5rem;
-    padding-block: 1.5rem 0.5rem;
-    margin-inline: -1.5rem;
-    padding-inline: 1.5rem;
-  }
+/* "Load more results" button: match the chrome card system so it reads as
+   a row of the same family as the result list. Pagefind's default is a
+   borderless inline button at body size that floats below the last card
+   on too much air. */
+site-search #starlight__search .pagefind-ui__button {
+  display: block;
+  width: 100%;
+  margin: 0.75rem 0 0;
+  padding: 0.5rem 0.875rem;
+  border: 1px solid var(--warp-control-border);
+  border-radius: var(--sl-radius-sm);
+  background: var(--warp-control-bg);
+  color: var(--warp-control-text);
+  font-family: var(--__sl-font, 'Inter', sans-serif);
+  font-size: var(--sl-text-sm);
+  font-weight: 500;
+  line-height: 1.2;
+  cursor: pointer;
+  transition: border-color 0.15s ease, color 0.15s ease, background-color 0.15s ease;
+}
+
+site-search #starlight__search .pagefind-ui__button:hover,
+site-search #starlight__search .pagefind-ui__button:focus-visible {
+  border-color: var(--warp-control-border-hover);
+  background-color: var(--warp-control-bg-hover);
+  color: var(--warp-control-text-hover);
+  outline: none;
 }
 
 /* Input focus border: Starlight's default flips `--pagefind-ui-border` to
@@ -1141,7 +1162,9 @@ site-search #starlight__search .pagefind-ui__result-excerpt {
 /* `<mark>` highlight inside excerpts: the Pagefind default uses a saturated
    yellow that fights the grayscale chrome. Swap to a neutral wash that
    matches the chrome hover surface so the highlight reads as a chip rather
-   than a stamp. */
+   than a stamp. `--sl-color-white` is mode-aware in Starlight (warm off-white
+   in dark, near-black in light) so it gives the right text contrast in both
+   themes — only the background tone needs a light-mode override. */
 site-search #starlight__search .pagefind-ui__result-excerpt mark,
 site-search #starlight__search .pagefind-ui__result-title mark {
   background-color: rgba(255, 255, 255, 0.12);
@@ -1154,7 +1177,19 @@ site-search #starlight__search .pagefind-ui__result-title mark {
 :root[data-theme='light'] site-search #starlight__search .pagefind-ui__result-excerpt mark,
 :root[data-theme='light'] site-search #starlight__search .pagefind-ui__result-title mark {
   background-color: rgba(0, 0, 0, 0.08);
-  color: var(--sl-color-black);
+}
+
+/* Scoped text-selection color so dragging across result text picks up the
+   chrome palette instead of the OS accent (saturated macOS blue read as
+   foreign next to the grayscale dialog). */
+site-search dialog ::selection {
+  background-color: rgba(255, 255, 255, 0.16);
+  color: var(--sl-color-white);
+}
+
+:root[data-theme='light'] site-search dialog ::selection {
+  background-color: rgba(0, 0, 0, 0.10);
+  color: var(--sl-color-white);
 }
 
 /* Breadcrumb row injected by CustomSidebar.astro into each
@@ -1198,21 +1233,23 @@ site-search #starlight__search .pagefind-ui__result-nested .pagefind-ui__result-
    CustomSidebar.astro. */
 
 .warp-search-footer {
-  position: sticky;
-  bottom: 0;
-  z-index: 2;
+  flex: 0 0 auto;
   display: flex;
   flex-direction: column;
-  gap: 0.5rem;
-  margin-block-start: 0.5rem;
-  padding: 0.625rem 1rem 0.875rem;
-  background: var(--sl-color-bg);
-  border-top: 1px solid var(--sl-color-hairline-light);
+  gap: 0.625rem;
+  padding: 0.625rem 1rem 0.75rem;
+  background: var(--sl-color-gray-6);
+  border-top: 1px solid var(--sl-color-hairline);
+  box-shadow: 0 -8px 12px -8px rgba(0, 0, 0, 0.25);
+}
+
+:root[data-theme='light'] .warp-search-footer {
+  box-shadow: 0 -8px 12px -8px rgba(0, 0, 0, 0.08);
 }
 
 @media (min-width: 50rem) {
   .warp-search-footer {
-    padding: 0.75rem 1.5rem 1rem;
+    padding: 0.75rem 1.5rem 0.875rem;
   }
 }
 
@@ -1270,16 +1307,13 @@ site-search #starlight__search .pagefind-ui__result-nested .pagefind-ui__result-
 
 /* Highlighted query inside the Ask AI label (e.g. `Ask AI: "<query>"`).
    Keeps the label color but raises weight so the typed query reads as the
-   subject of the action. */
+   subject of the action. `--sl-color-white` is mode-aware (warm off-white
+   in dark, near-black in light) so one rule covers both themes. */
 .warp-search-ask-ai-row__query {
   font-weight: 600;
   color: var(--sl-color-white);
 }
 
-:root[data-theme='light'] .warp-search-ask-ai-row__query {
-  color: var(--sl-color-black);
-}
-
 /* Keyboard shortcut chip — always visible (replaces the previous Enter
    hint that only appeared on keyboard selection). Surface mirrors
    `.warp-sidebar-search button[data-open-modal] kbd` (§16) so the modal's

From 977b6663f8b536226f1c84a17264eff5deff97a1 Mon Sep 17 00:00:00 2001
From: Hong Yi Chen <hongyigma@gmail.com>
Date: Sun, 10 May 2026 15:42:22 -0700
Subject: [PATCH 03/11] docs: replace blue search input focus border with
 chrome neutral

Set --pagefind-ui-border AND border-color on .pagefind-ui__form:focus-within
directly (CSS variables don't cascade upward, so the prior override on
input:focus alone never repainted the form). Also kill the browser's
default focus outline on the input \u2014 the form border swap is the visible
focus affordance.

Co-Authored-By: Oz <oz-agent@warp.dev>
---
 src/styles/warp-components.css | 20 ++++++++++++++++----
 1 file changed, 16 insertions(+), 4 deletions(-)

diff --git a/src/styles/warp-components.css b/src/styles/warp-components.css
index 7b8ea2fa..7f5f36e7 100644
--- a/src/styles/warp-components.css
+++ b/src/styles/warp-components.css
@@ -1069,11 +1069,23 @@ site-search #starlight__search .pagefind-ui__button:focus-visible {
 }
 
 /* Input focus border: Starlight's default flips `--pagefind-ui-border` to
-   the saturated Warp blue accent on focus, which is the bright cyan ring
-   in the screenshot. Replace with the chrome ladder's hover border so the
-   input matches the trigger button's `:hover` affordance. */
-site-search #starlight__search input:focus {
+   the saturated Warp blue accent on focus, which renders as a bright cyan
+   ring around the form. Set the variable on every level Pagefind reads it
+   from (form + input) AND set `border-color` directly on the form's
+   `:focus-within` state — belt-and-braces because CSS variables don't
+   cascade upward, so setting `--pagefind-ui-border` on the input alone
+   never affected the form's painted border. Also strip the browser's
+   default focus outline on the input (the form's hover-border swap is
+   the visible focus affordance). */
+site-search #starlight__search .pagefind-ui__form:focus-within {
   --pagefind-ui-border: var(--warp-control-border-hover);
+  border-color: var(--warp-control-border-hover);
+}
+
+site-search #starlight__search input:focus,
+site-search #starlight__search input:focus-visible {
+  --pagefind-ui-border: var(--warp-control-border-hover);
+  outline: none;
 }
 
 /* Cancel + clear buttons: drop the blue accent color in favor of a calm

From a31e68766ffa947689e675cf32174cc399553dec Mon Sep 17 00:00:00 2001
From: Hong Yi Chen <hongyigma@gmail.com>
Date: Sun, 10 May 2026 15:45:47 -0700
Subject: [PATCH 04/11] docs: drop blue-tinted footer fill, use page bg +
 stronger scrim

var(--sl-color-gray-6) is Oz #252b37 in dark mode \u2014 visibly cool/blue
against the neutral #121212 canvas, out of family with the rest of the
chrome. Move back to var(--sl-color-bg) (matches the dialog body) and
strengthen the box-shadow scrim above the footer to keep the pinned
separation crisp.

Co-Authored-By: Oz <oz-agent@warp.dev>
---
 src/styles/warp-components.css | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/src/styles/warp-components.css b/src/styles/warp-components.css
index 7f5f36e7..8c326f23 100644
--- a/src/styles/warp-components.css
+++ b/src/styles/warp-components.css
@@ -1245,18 +1245,22 @@ site-search #starlight__search .pagefind-ui__result-nested .pagefind-ui__result-
    CustomSidebar.astro. */
 
 .warp-search-footer {
+  /* Surface stays on the dialog body (`--sl-color-bg`) so the footer is
+     fully neutral — `--sl-color-gray-6` reads visibly blue in dark mode
+     (Oz `#252b37`) and pulls the chrome out of family. The hairline +
+     scrim do the separating work. */
   flex: 0 0 auto;
   display: flex;
   flex-direction: column;
   gap: 0.625rem;
   padding: 0.625rem 1rem 0.75rem;
-  background: var(--sl-color-gray-6);
-  border-top: 1px solid var(--sl-color-hairline);
-  box-shadow: 0 -8px 12px -8px rgba(0, 0, 0, 0.25);
+  background: var(--sl-color-bg);
+  border-top: 1px solid var(--sl-color-hairline-light);
+  box-shadow: 0 -8px 12px -8px rgba(0, 0, 0, 0.35);
 }
 
 :root[data-theme='light'] .warp-search-footer {
-  box-shadow: 0 -8px 12px -8px rgba(0, 0, 0, 0.08);
+  box-shadow: 0 -8px 12px -8px rgba(0, 0, 0, 0.10);
 }
 
 @media (min-width: 50rem) {

From 7e356df36f0ed7c0cc319dc840971e075e908a54 Mon Sep 17 00:00:00 2001
From: Hong Yi Chen <hongyigma@gmail.com>
Date: Sun, 10 May 2026 15:58:12 -0700
Subject: [PATCH 05/11] docs: group page results into one card with indented
 sub-results

- Move card chrome (bg + border + radius) to .pagefind-ui__result so the
  parent title and its sub-results render as one grouped card per page,
  with the parent title at top and sub-results indented inside
- Sub-results (.pagefind-ui__result-nested) get a 1px left rule + indent
  so they read as children of the parent above
- Inter-card spacing (margin-bottom: 0.75rem on .pagefind-ui__result) is
  visibly larger than intra-card spacing (--sl-search-result-spacing:
  0.125rem) so different pages are clearly separated
- Tighten 'N results for <query>' message: reset .pagefind-ui__drawer
  and .pagefind-ui__results margin-top to 0, message bottom margin 0.5rem
- Empty state: override Starlight's dialog min-height: 15rem -> auto so
  the dialog sizes to its content (form + footer) instead of forcing
  ~150px of dead space when no results are shown

Co-Authored-By: Oz <oz-agent@warp.dev>
---
 src/styles/warp-components.css | 87 ++++++++++++++++++++++++----------
 1 file changed, 61 insertions(+), 26 deletions(-)

diff --git a/src/styles/warp-components.css b/src/styles/warp-components.css
index 8c326f23..d7587c50 100644
--- a/src/styles/warp-components.css
+++ b/src/styles/warp-components.css
@@ -942,6 +942,11 @@ body {
 site-search dialog {
   background-color: var(--sl-color-bg);
   border: 1px solid var(--sl-color-hairline-light);
+  /* Drop Starlight's default `min-height: 15rem` so the empty-state dialog
+     sizes to its actual content (form + footer ≈ 150px) instead of forcing
+     dead space inside the scroll container. `height: max-content` (Starlight
+     default) handles natural sizing; `max-height` is unchanged. */
+  min-height: auto;
 }
 
 /* Stronger neutral backdrop. Starlight's `--sl-color-backdrop-overlay`
@@ -1017,7 +1022,30 @@ site-search #starlight__search {
   --sl-search-result-pad-inline-start: 0.875rem;
   --sl-search-result-pad-inline-end: 0.875rem;
   --sl-search-result-nested-pad-block: 0.5rem;
-  --sl-search-result-spacing: 0.25rem;
+  /* Intra-card spacing only. Inter-card spacing comes from the
+     `.pagefind-ui__result` margin-bottom rule below so card-to-card gaps
+     read visibly larger than nested-row gaps. */
+  --sl-search-result-spacing: 0.125rem;
+}
+
+/* Page card wrapper. Pagefind renders one `<li class="pagefind-ui__result">`
+   per page; inside, the parent title and sub-results are flat siblings.
+   Move the card chrome onto this wrapper so the parent title + its nested
+   rows read as a single grouped card. */
+site-search #starlight__search .pagefind-ui__result {
+  background-color: var(--warp-control-bg);
+  border: 1px solid var(--warp-control-border);
+  border-radius: var(--sl-radius-sm);
+  padding: 0.625rem 0;
+  margin-bottom: 0.75rem;
+}
+
+site-search #starlight__search .pagefind-ui__result:last-child {
+  margin-bottom: 0;
+}
+
+site-search #starlight__search .pagefind-ui__result-inner {
+  width: 100%;
 }
 
 /* Hide Starlight's leading page + tree-diagram icons. They were tuned for
@@ -1031,9 +1059,18 @@ site-search #starlight__search .pagefind-ui__result-nested::before {
 
 /* Results-count message ("12 results for changelog"). Pagefind defaults
    to a heavy block-margin around it; pull it to a quiet single-line
-   section label flush with the first result card. */
+   section label flush with the first result card. The drawer + results
+   resets cancel Pagefind's parent margins so nothing compounds. */
+site-search #starlight__search .pagefind-ui__drawer {
+  margin-top: 0;
+}
+
+site-search #starlight__search .pagefind-ui__results {
+  margin-top: 0;
+}
+
 site-search #starlight__search .pagefind-ui__message {
-  margin: 0.25rem 0 0.75rem;
+  margin: 0.25rem 0 0.5rem;
   font-size: var(--sl-text-sm);
   font-weight: 500;
   color: var(--sl-color-gray-2);
@@ -1106,35 +1143,28 @@ site-search #starlight__search .pagefind-ui__search-clear:focus {
   outline: 1px solid var(--warp-control-border-hover);
 }
 
-/* Result cards. Starlight paints the title row + each nested sub-result
-   with `--sl-color-black` (`#121212`), which on the cool gray-6 dialog
-   read as stamped-down patches. With the dialog now sharing the page
-   canvas, raise each result onto the chrome `--warp-control-bg` so the
-   list reads as a stack of tactile chips. A 1px hairline keeps the cards
-   distinct without a heavy outline. */
+/* Result rows are now transparent siblings inside the page card. The
+   parent title sits at top with its breadcrumb; each `.pagefind-ui__result-nested`
+   sub-result sits below, indented with a left rule that signals "this
+   belongs to the page above." */
 site-search #starlight__search .pagefind-ui__result-title:not(:where(.pagefind-ui__result-nested *)),
 site-search #starlight__search .pagefind-ui__result-nested,
 site-search #starlight__search .pagefind-ui__result-tags {
-  background-color: var(--warp-control-bg);
+  background-color: transparent;
 }
 
-/* Hover / keyboard-focus state. Replace the blue accent outline + tinted
-   fill with the same neutral wash the chrome buttons use on hover. The
-   1px border swap stays inside the existing layout box, so list rows
-   don't shift on hover. */
-site-search #starlight__search .pagefind-ui__result-title:not(:where(.pagefind-ui__result-nested *)):hover,
-site-search #starlight__search .pagefind-ui__result-title:not(:where(.pagefind-ui__result-nested *)):focus-within,
+/* Hover / keyboard-focus state is scoped to nested rows only — the parent
+   title is now visually part of the card, so hovering its own row would
+   give it a second-tier highlight that competes with the card itself. */
 site-search #starlight__search .pagefind-ui__result-nested:hover,
 site-search #starlight__search .pagefind-ui__result-nested:focus-within {
-  outline: 1px solid var(--warp-control-border-hover);
   background-color: var(--warp-control-bg-hover);
 }
 
-/* Arrow-key selection state for search results. Applied by the
-   keyboard navigation script in CustomSidebar.astro. Targets the
-   same per-row elements (.pagefind-ui__result-title and
-   .pagefind-ui__result-nested) that the hover rules above target,
-   so keyboard and mouse highlight produce identical visuals. */
+/* Arrow-key selection state for search results. The keyboard navigation
+   script in CustomSidebar.astro adds `.warp-search-selected` to the
+   currently-focused row (parent title or nested). Same wash as hover
+   plus a 1px border so keyboard selection pops clearly inside the card. */
 site-search #starlight__search .warp-search-selected {
   outline: 1px solid var(--warp-control-border-hover);
   background-color: var(--warp-control-bg-hover);
@@ -1222,11 +1252,16 @@ site-search dialog ::selection {
   color: var(--sl-color-gray-4);
 }
 
-/* Nested sub-results: drop the connecting tree-diagram indent so
-   sub-results sit flush with the parent card. The breadcrumb on the
-   parent title already carries the section context. */
+/* Nested sub-results: indent inside the parent card with a 1px left rule
+   acting as the "tree" indicator that this row belongs to the page above.
+   The margin pulls the rule away from the card edge so the row reads as
+   a child, not as a separate sibling. */
 site-search #starlight__search .pagefind-ui__result-nested {
-  padding-inline-start: var(--sl-search-result-pad-inline-start);
+  margin-inline-start: 0.625rem;
+  padding-inline-start: 0.875rem;
+  padding-inline-end: var(--sl-search-result-pad-inline-end);
+  border-inline-start: 1px solid var(--warp-control-border);
+  border-radius: 0;
 }
 
 site-search #starlight__search .pagefind-ui__result-nested .pagefind-ui__result-link {

From 934c6911b4cc960ab9f30deaf13b6ca8c42b228f Mon Sep 17 00:00:00 2001
From: Hong Yi Chen <hongyigma@gmail.com>
Date: Sun, 10 May 2026 16:09:16 -0700
Subject: [PATCH 06/11] docs: design pass on result cards + unify input icons
 to Lucide

- Hard zero the chrome around 'N results' message: reset margins/padding
  on .pagefind-ui__form, .pagefind-ui__drawer, .pagefind-ui__results-area,
  and .pagefind-ui__results so the message sits flush against the form
  above and the first card below
- Drop the left rule on sub-results (read as a hard outline competing
  with the card edge); use indent + smaller type-scale to signal
  hierarchy (sub-result title --sl-text-xs, excerpt --sl-text-2xs)
- Hide redundant parent excerpt when sub-results exist via :has() so
  each card shows breadcrumb + title + sub-results without repeating
  the same matched content
- Softer hover wash on sub-results (rgba white/black 0.04) so hovering
  stays inside the card surface
- Subtler card border via --sl-color-hairline-light + tighter card
  padding (0.5rem 0) + inter-card margin-bottom: 0.5rem
- Unify the magnifier + clear-X icons by overriding Pagefind's mask-image
  with matched Lucide SVGs (stroke-width:2, rounded caps/joins) so the
  pair reads as one icon family inside the dialog

Co-Authored-By: Oz <oz-agent@warp.dev>
---
 src/styles/warp-components.css | 123 ++++++++++++++++++++++++++-------
 1 file changed, 99 insertions(+), 24 deletions(-)

diff --git a/src/styles/warp-components.css b/src/styles/warp-components.css
index d7587c50..862d9267 100644
--- a/src/styles/warp-components.css
+++ b/src/styles/warp-components.css
@@ -1018,10 +1018,10 @@ site-search #starlight__search {
   --pagefind-ui-primary: var(--sl-color-white);
   --pagefind-ui-border-radius: var(--sl-radius-sm);
   --sl-search-corners: var(--sl-radius-sm);
-  --sl-search-result-pad-block: 0.625rem;
+  --sl-search-result-pad-block: 0.5rem;
   --sl-search-result-pad-inline-start: 0.875rem;
   --sl-search-result-pad-inline-end: 0.875rem;
-  --sl-search-result-nested-pad-block: 0.5rem;
+  --sl-search-result-nested-pad-block: 0.375rem;
   /* Intra-card spacing only. Inter-card spacing comes from the
      `.pagefind-ui__result` margin-bottom rule below so card-to-card gaps
      read visibly larger than nested-row gaps. */
@@ -1031,13 +1031,15 @@ site-search #starlight__search {
 /* Page card wrapper. Pagefind renders one `<li class="pagefind-ui__result">`
    per page; inside, the parent title and sub-results are flat siblings.
    Move the card chrome onto this wrapper so the parent title + its nested
-   rows read as a single grouped card. */
+   rows read as a single grouped card. Border is `--sl-color-hairline-light`
+   (8% white) instead of `--warp-control-border` (#404040) so the card edge
+   reads as a hairline frame, not a chip outline. */
 site-search #starlight__search .pagefind-ui__result {
   background-color: var(--warp-control-bg);
-  border: 1px solid var(--warp-control-border);
+  border: 1px solid var(--sl-color-hairline-light);
   border-radius: var(--sl-radius-sm);
-  padding: 0.625rem 0;
-  margin-bottom: 0.75rem;
+  padding: 0.5rem 0;
+  margin-bottom: 0.5rem;
 }
 
 site-search #starlight__search .pagefind-ui__result:last-child {
@@ -1048,6 +1050,15 @@ site-search #starlight__search .pagefind-ui__result-inner {
   width: 100%;
 }
 
+/* When sub-results are rendered, the page-level excerpt repeats the same
+   matched content the sub-results below provide more usefully (with
+   anchors + per-section context). Hide it so each card shows breadcrumb
+   + title + sub-results, no redundant body excerpt. Results with no
+   sub-results keep their excerpt as the only available context. */
+site-search #starlight__search .pagefind-ui__result:has(.pagefind-ui__result-nested) .pagefind-ui__result-inner > .pagefind-ui__result-excerpt {
+  display: none;
+}
+
 /* Hide Starlight's leading page + tree-diagram icons. They were tuned for
    Pagefind's default verbose layout and read as decorative noise in our
    tighter cards. The breadcrumb injected by CustomSidebar.astro replaces
@@ -1057,20 +1068,34 @@ site-search #starlight__search .pagefind-ui__result-nested::before {
   display: none;
 }
 
-/* Results-count message ("12 results for changelog"). Pagefind defaults
-   to a heavy block-margin around it; pull it to a quiet single-line
-   section label flush with the first result card. The drawer + results
-   resets cancel Pagefind's parent margins so nothing compounds. */
+/* Results-count message ("12 results for changelog"). Pagefind's default
+   UI stacks margins on the form + drawer + results container; we hard-zero
+   every level so the message sits flush against the form above and the
+   first card below. */
+site-search #starlight__search .pagefind-ui__form {
+  margin-bottom: 0;
+  padding-bottom: 0;
+}
+
 site-search #starlight__search .pagefind-ui__drawer {
-  margin-top: 0;
+  margin: 0;
+  padding: 0;
+}
+
+site-search #starlight__search .pagefind-ui__results-area {
+  margin: 0;
+  padding: 0;
 }
 
 site-search #starlight__search .pagefind-ui__results {
-  margin-top: 0;
+  margin: 0;
+  padding: 0;
+  list-style: none;
 }
 
 site-search #starlight__search .pagefind-ui__message {
-  margin: 0.25rem 0 0.5rem;
+  margin: 0.5rem 0 0.625rem;
+  padding: 0;
   font-size: var(--sl-text-sm);
   font-weight: 500;
   color: var(--sl-color-gray-2);
@@ -1135,8 +1160,41 @@ site-search button[data-close-modal]:hover {
   color: var(--sl-color-white);
 }
 
+/* Unify the in-input magnifier (`.pagefind-ui__form::before`) and clear-X
+   (`.pagefind-ui__search-clear::before`) icons with the rest of the chrome.
+   Pagefind ships its own icon SVGs via `mask-image`, drawn in a slightly
+   different stroke style than the Lucide icons we use everywhere else
+   (Kapa "Ask" button, Ask AI sparkle, etc.). Override both with matched
+   Lucide SVGs at `stroke-width=2`, `stroke-linecap/linejoin=round` so the
+   pair reads as a single icon family inside the dialog. The element's
+   `background-color` shows through the mask alpha, so the icon color
+   tracks `--pagefind-ui-text` / our explicit color rules below. */
+site-search #starlight__search .pagefind-ui__form::before {
+  background-color: var(--sl-color-gray-2);
+  -webkit-mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Ccircle cx='11' cy='11' r='8'/%3E%3Cpath d='m21 21-4.3-4.3'/%3E%3C/svg%3E");
+  mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Ccircle cx='11' cy='11' r='8'/%3E%3Cpath d='m21 21-4.3-4.3'/%3E%3C/svg%3E");
+  -webkit-mask-size: contain;
+  mask-size: contain;
+  -webkit-mask-repeat: no-repeat;
+  mask-repeat: no-repeat;
+  -webkit-mask-position: center;
+  mask-position: center;
+}
+
 site-search #starlight__search .pagefind-ui__search-clear::before {
   background-color: var(--sl-color-gray-3);
+  -webkit-mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M18 6 6 18'/%3E%3Cpath d='m6 6 12 12'/%3E%3C/svg%3E");
+  mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M18 6 6 18'/%3E%3Cpath d='m6 6 12 12'/%3E%3C/svg%3E");
+  -webkit-mask-size: contain;
+  mask-size: contain;
+  -webkit-mask-repeat: no-repeat;
+  mask-repeat: no-repeat;
+  -webkit-mask-position: center;
+  mask-position: center;
+}
+
+site-search #starlight__search .pagefind-ui__search-clear:hover::before {
+  background-color: var(--sl-color-white);
 }
 
 site-search #starlight__search .pagefind-ui__search-clear:focus {
@@ -1155,10 +1213,17 @@ site-search #starlight__search .pagefind-ui__result-tags {
 
 /* Hover / keyboard-focus state is scoped to nested rows only — the parent
    title is now visually part of the card, so hovering its own row would
-   give it a second-tier highlight that competes with the card itself. */
+   give it a second-tier highlight that competes with the card itself.
+   Use a soft white wash instead of the chip `--warp-control-bg-hover` so
+   the hover stays inside the card surface without painting a hard chip. */
 site-search #starlight__search .pagefind-ui__result-nested:hover,
 site-search #starlight__search .pagefind-ui__result-nested:focus-within {
-  background-color: var(--warp-control-bg-hover);
+  background-color: rgba(255, 255, 255, 0.04);
+}
+
+:root[data-theme='light'] site-search #starlight__search .pagefind-ui__result-nested:hover,
+:root[data-theme='light'] site-search #starlight__search .pagefind-ui__result-nested:focus-within {
+  background-color: rgba(0, 0, 0, 0.04);
 }
 
 /* Arrow-key selection state for search results. The keyboard navigation
@@ -1252,24 +1317,34 @@ site-search dialog ::selection {
   color: var(--sl-color-gray-4);
 }
 
-/* Nested sub-results: indent inside the parent card with a 1px left rule
-   acting as the "tree" indicator that this row belongs to the page above.
-   The margin pulls the rule away from the card edge so the row reads as
-   a child, not as a separate sibling. */
+/* Nested sub-results: indent inside the parent card. No left rule — the
+   indentation + smaller type-scale (.pagefind-ui__result-nested  link
+   below) is enough to signal hierarchy. The previous 1px rule read as a
+   hard outline competing with the card edge. */
 site-search #starlight__search .pagefind-ui__result-nested {
-  margin-inline-start: 0.625rem;
-  padding-inline-start: 0.875rem;
+  padding-inline-start: 1rem;
   padding-inline-end: var(--sl-search-result-pad-inline-end);
-  border-inline-start: 1px solid var(--warp-control-border);
   border-radius: 0;
 }
 
+site-search #starlight__search .pagefind-ui__result-nested .pagefind-ui__result-title {
+  font-size: var(--sl-text-xs);
+  font-weight: 600;
+  line-height: 1.35;
+}
+
 site-search #starlight__search .pagefind-ui__result-nested .pagefind-ui__result-link {
-  font-size: var(--sl-text-sm);
-  font-weight: 500;
+  font-size: var(--sl-text-xs);
+  font-weight: 600;
   color: var(--sl-color-gray-1);
 }
 
+site-search #starlight__search .pagefind-ui__result-nested .pagefind-ui__result-excerpt {
+  font-size: var(--sl-text-2xs);
+  color: var(--sl-color-gray-3);
+  margin-top: 0.125rem;
+}
+
 /* --------------------------------------------------------------------------
    19. Persistent search footer (Ask AI + keyboard hints)
    --------------------------------------------------------------------------

From ddb81410b386882432e33383cc577e3ec1fe36c7 Mon Sep 17 00:00:00 2001
From: Hong Yi Chen <hongyigma@gmail.com>
Date: Sun, 10 May 2026 16:17:52 -0700
Subject: [PATCH 07/11] docs: hide mobile Cancel, pin icon sizes, continuous
 sub-result rail

- Hide Starlight's upstream <button data-close-modal>Cancel</button> on
  all viewports so the search bar takes full width on mobile. Backdrop
  tap + ESC still close the dialog.
- Pin .pagefind-ui__form::before and .pagefind-ui__search-clear::before
  to width: 16px; height: 16px so the Lucide mask icons stop being
  stretched to Pagefind's scaled default sizes (the X was rendering
  ~40px on mobile).
- Restore a continuous left rail on sub-results: 2px
  border-inline-start on .pagefind-ui__result-nested using
  --warp-control-border-hover, plus --sl-search-result-spacing: 0 so
  rows stack flush and the per-row border paints one unbroken vertical
  bar. Margin-inline-start: 0.625rem insets the rail from the card edge.

Co-Authored-By: Oz <oz-agent@warp.dev>
---
 src/styles/warp-components.css | 45 ++++++++++++++++++++++------------
 1 file changed, 29 insertions(+), 16 deletions(-)

diff --git a/src/styles/warp-components.css b/src/styles/warp-components.css
index 862d9267..bcca9470 100644
--- a/src/styles/warp-components.css
+++ b/src/styles/warp-components.css
@@ -1022,10 +1022,11 @@ site-search #starlight__search {
   --sl-search-result-pad-inline-start: 0.875rem;
   --sl-search-result-pad-inline-end: 0.875rem;
   --sl-search-result-nested-pad-block: 0.375rem;
-  /* Intra-card spacing only. Inter-card spacing comes from the
-     `.pagefind-ui__result` margin-bottom rule below so card-to-card gaps
-     read visibly larger than nested-row gaps. */
-  --sl-search-result-spacing: 0.125rem;
+  /* Intra-card spacing pinned to 0 so the per-row left border on
+     `.pagefind-ui__result-nested` forms one continuous vertical rail
+     across all sub-results inside a card. Inter-card spacing comes from
+     the `.pagefind-ui__result` margin-bottom rule below. */
+  --sl-search-result-spacing: 0;
 }
 
 /* Page card wrapper. Pagefind renders one `<li class="pagefind-ui__result">`
@@ -1150,14 +1151,14 @@ site-search #starlight__search input:focus-visible {
   outline: none;
 }
 
-/* Cancel + clear buttons: drop the blue accent color in favor of a calm
-   gray that recedes the way every other secondary chrome action does. */
+/* Hide Starlight's upstream mobile Cancel button entirely. It renders
+   beside `.pagefind-ui__form` at viewports <50rem (Starlight ships it
+   with `class="sl-flex md:sl-hidden"`) and squashes the search input.
+   Mobile users still close the dialog via backdrop tap (wired by
+   Starlight's `site-search` element) and ESC; the persistent footer +
+   keyboard hints handle desktop. */
 site-search button[data-close-modal] {
-  color: var(--sl-color-gray-2);
-}
-
-site-search button[data-close-modal]:hover {
-  color: var(--sl-color-white);
+  display: none;
 }
 
 /* Unify the in-input magnifier (`.pagefind-ui__form::before`) and clear-X
@@ -1170,6 +1171,8 @@ site-search button[data-close-modal]:hover {
    `background-color` shows through the mask alpha, so the icon color
    tracks `--pagefind-ui-text` / our explicit color rules below. */
 site-search #starlight__search .pagefind-ui__form::before {
+  width: 16px;
+  height: 16px;
   background-color: var(--sl-color-gray-2);
   -webkit-mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Ccircle cx='11' cy='11' r='8'/%3E%3Cpath d='m21 21-4.3-4.3'/%3E%3C/svg%3E");
   mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Ccircle cx='11' cy='11' r='8'/%3E%3Cpath d='m21 21-4.3-4.3'/%3E%3C/svg%3E");
@@ -1182,6 +1185,8 @@ site-search #starlight__search .pagefind-ui__form::before {
 }
 
 site-search #starlight__search .pagefind-ui__search-clear::before {
+  width: 16px;
+  height: 16px;
   background-color: var(--sl-color-gray-3);
   -webkit-mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M18 6 6 18'/%3E%3Cpath d='m6 6 12 12'/%3E%3C/svg%3E");
   mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M18 6 6 18'/%3E%3Cpath d='m6 6 12 12'/%3E%3C/svg%3E");
@@ -1317,13 +1322,21 @@ site-search dialog ::selection {
   color: var(--sl-color-gray-4);
 }
 
-/* Nested sub-results: indent inside the parent card. No left rule — the
-   indentation + smaller type-scale (.pagefind-ui__result-nested  link
-   below) is enough to signal hierarchy. The previous 1px rule read as a
-   hard outline competing with the card edge. */
+/* Nested sub-results: indent inside the parent card with a continuous
+   2px left rail signaling "these all belong to the page above". With
+   `--sl-search-result-spacing: 0` (above) sub-result rows stack flush,
+   so the per-row `border-inline-start` paints a single unbroken vertical
+   bar from the first sub-result down through the last. The margin pulls
+   the rail one notch inset from the card edge so it reads as structural,
+   not as a card outline. Use `--warp-control-border-hover` (#585756 /
+   #9d9d9b) instead of the lighter `--warp-control-border` so the rail is
+   readable but not loud. */
 site-search #starlight__search .pagefind-ui__result-nested {
-  padding-inline-start: 1rem;
+  margin-inline-start: 0.625rem;
+  padding-inline-start: 0.875rem;
   padding-inline-end: var(--sl-search-result-pad-inline-end);
+  padding-block: 0.375rem;
+  border-inline-start: 2px solid var(--warp-control-border-hover);
   border-radius: 0;
 }
 

From cb56ba339c5fa9c144dede00382b1ddc22f6e7f3 Mon Sep 17 00:00:00 2001
From: Hong Yi Chen <hongyigma@gmail.com>
Date: Sun, 10 May 2026 16:27:14 -0700
Subject: [PATCH 08/11] docs: tidy search-dialog comments + drop inline style

- Refresh stale section headers + docstrings so they describe what
  actually ships: \u00a719 'sticky footer' \u2192 'flex-pinned footer';
  --sl-search-result-pad-* docstring updated to current 0.5rem block
  values; result-row transparent-bg comment rewritten to point at the
  rail rule it now coexists with; .warp-search-keyboard-hints rationale
  updated now that the Cancel button is hidden.
- Remove the unused .warp-search-breadcrumb__separator rule (the
  breadcrumb is rendered as a single textContent string with an
  embedded U+203A, no per-separator span ever exists).
- Move the inline 'margin:0 0.0625rem' on the kbd '+' span out of the
  script-built markup and into a dedicated .warp-search-ask-ai-row__kbd-plus
  CSS class.

Co-Authored-By: Oz <oz-agent@warp.dev>
---
 src/components/CustomSidebar.astro |  2 +-
 src/styles/warp-components.css     | 43 +++++++++++++++++-------------
 2 files changed, 25 insertions(+), 20 deletions(-)

diff --git a/src/components/CustomSidebar.astro b/src/components/CustomSidebar.astro
index 95964916..811b6747 100644
--- a/src/components/CustomSidebar.astro
+++ b/src/components/CustomSidebar.astro
@@ -142,7 +142,7 @@ import KapaLauncher from './KapaLauncher.astro';
 				+ '<path d="M20 3v4"/><path d="M22 5h-4"/><path d="M4 17v2"/><path d="M5 18H3"/>'
 				+ '</svg>'
 				+ '<span class="warp-search-ask-ai-row__label">Ask AI</span>'
-				+ '<kbd class="warp-search-ask-ai-row__kbd" aria-hidden="true">' + modKey + '<span style="margin:0 0.0625rem">+</span>I</kbd>';
+				+ '<kbd class="warp-search-ask-ai-row__kbd" aria-hidden="true">' + modKey + '<span class="warp-search-ask-ai-row__kbd-plus">+</span>I</kbd>';
 			askAi.addEventListener('click', function () {
 				var searchInput = dialog.querySelector('.pagefind-ui__search-input');
 				var searchQuery = searchInput ? searchInput.value.trim() : '';
diff --git a/src/styles/warp-components.css b/src/styles/warp-components.css
index bcca9470..779406f3 100644
--- a/src/styles/warp-components.css
+++ b/src/styles/warp-components.css
@@ -1006,10 +1006,10 @@ site-search dialog .search-container {
    list rows match the input above them.
 
    `--sl-search-result-pad-*` are Starlight's knobs over Pagefind's own
-   default vertical padding. Pin them to a compact 0.625rem block / 0.875rem
-   inline pair so every result row sits tighter (matches GitBook density),
-   and drop the leading 3.75rem inline-start gutter that's reserved for the
-   page/tree icon — we hide that icon below. */
+   default vertical padding. Pin them to a compact 0.5rem block / 0.875rem
+   inline pair (and 0.375rem block for nested rows) so every result row
+   sits tighter, and drop the leading 3.75rem inline-start gutter that's
+   reserved for the page/tree icon — we hide that icon below. */
 site-search #starlight__search {
   --pagefind-ui-background: var(--warp-control-bg);
   --pagefind-ui-border: var(--warp-control-border);
@@ -1206,10 +1206,11 @@ site-search #starlight__search .pagefind-ui__search-clear:focus {
   outline: 1px solid var(--warp-control-border-hover);
 }
 
-/* Result rows are now transparent siblings inside the page card. The
-   parent title sits at top with its breadcrumb; each `.pagefind-ui__result-nested`
-   sub-result sits below, indented with a left rule that signals "this
-   belongs to the page above." */
+/* Result rows are transparent siblings inside the page card so the card
+   wrapper (`.pagefind-ui__result`) is the only painted surface; the
+   parent title and any nested rows just sit on top of it. Sub-result
+   indent + left rail are handled by the dedicated `.pagefind-ui__result-nested`
+   rule near the bottom of this section. */
 site-search #starlight__search .pagefind-ui__result-title:not(:where(.pagefind-ui__result-nested *)),
 site-search #starlight__search .pagefind-ui__result-nested,
 site-search #starlight__search .pagefind-ui__result-tags {
@@ -1317,11 +1318,6 @@ site-search dialog ::selection {
   letter-spacing: 0.02em;
 }
 
-.warp-search-breadcrumb__separator {
-  margin: 0 0.25rem;
-  color: var(--sl-color-gray-4);
-}
-
 /* Nested sub-results: indent inside the parent card with a continuous
    2px left rail signaling "these all belong to the page above". With
    `--sl-search-result-spacing: 0` (above) sub-result rows stack flush,
@@ -1361,10 +1357,12 @@ site-search #starlight__search .pagefind-ui__result-nested .pagefind-ui__result-
 /* --------------------------------------------------------------------------
    19. Persistent search footer (Ask AI + keyboard hints)
    --------------------------------------------------------------------------
-   GitBook-style sticky footer pinned to the bottom of the search dialog.
-   Contains the "Ask AI" CTA (with the current query interpolated into the
-   label) and a Scalar-style keyboard hint strip (↑↓ Navigate · ↵ Select ·
-   Esc Close). Built and injected once per dialog open by the script in
+   Footer pinned to the bottom of the search dialog via the parent flex
+   column in §18 (`.dialog-frame { display: flex; flex-direction: column;
+   overflow: hidden }` + `.warp-search-footer { flex: 0 0 auto }`). Contains
+   the "Ask AI" CTA (with the current query interpolated into the label) and
+   a Scalar-style keyboard hint strip (↑↓ Navigate · ↵ Select · Esc Close).
+   Built and injected once per dialog open by the script in
    CustomSidebar.astro. */
 
 .warp-search-footer {
@@ -1476,10 +1474,17 @@ site-search #starlight__search .pagefind-ui__result-nested .pagefind-ui__result-
   background: rgba(0, 0, 0, 0.06);
 }
 
+/* `+` separator between the modifier glyph and the letter inside the kbd
+   chip. A hair of inline margin keeps `⌘ + I` from collapsing to `⌘+I`
+   while staying tighter than a regular space. */
+.warp-search-ask-ai-row__kbd-plus {
+  margin: 0 0.0625rem;
+}
+
 /* Keyboard hints strip below the Ask AI row. A quiet single-line legend
    of the available shortcuts (↑↓ Navigate · ↵ Select · Esc Close). Hidden
-   on narrow viewports — at mobile widths the modal already exposes a
-   Cancel button at the top and keyboard navigation is less relevant. */
+   on narrow viewports to prioritize screen real estate; keyboard hints
+   are also less relevant on touch devices. */
 .warp-search-keyboard-hints {
   display: none;
   align-items: center;

From af4e394b753ce7ca3fb8d96b39074b490b519bae Mon Sep 17 00:00:00 2001
From: Hong Yi Chen <hongyigma@gmail.com>
Date: Sun, 10 May 2026 16:32:47 -0700
Subject: [PATCH 09/11] docs: hide 'Clear' label + drop wraparound focus
 outline on clear button

- Collapse Pagefind's translated 'Clear' text node via font-size:0 +
  line-height:0 so only the X icon shows; the text stays in the DOM so
  screen readers still announce the button as 'Clear'.
- Drop the standalone :focus outline on .pagefind-ui__search-clear (it
  painted a partial-row chip-within-chip box at the top-right of the
  input). Extend the hover icon-color shift to :focus-visible so
  keyboard users still get a visible focus signal; the form's
  :focus-within border keeps signalling that the search input as a
  whole has focus.

Co-Authored-By: Oz <oz-agent@warp.dev>
---
 src/styles/warp-components.css | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/src/styles/warp-components.css b/src/styles/warp-components.css
index 779406f3..6850802d 100644
--- a/src/styles/warp-components.css
+++ b/src/styles/warp-components.css
@@ -1198,12 +1198,27 @@ site-search #starlight__search .pagefind-ui__search-clear::before {
   mask-position: center;
 }
 
-site-search #starlight__search .pagefind-ui__search-clear:hover::before {
+/* The Pagefind clear button ships with a translated "Clear" label as its
+   text node alongside the `::before` icon, which renders as visible copy
+   stacked under the X. Collapse the label to zero size so only the icon
+   shows; the text node stays in the DOM so screen readers still announce
+   the button as "Clear". */
+site-search #starlight__search .pagefind-ui__search-clear {
+  font-size: 0;
+  line-height: 0;
+}
+
+/* Hover + keyboard focus: brighten just the icon. The form's `:focus-within`
+   border already signals that the search input as a whole has focus, so
+   the clear button doesn't need its own wraparound outline (which would
+   read as a chip-within-chip against the input border). */
+site-search #starlight__search .pagefind-ui__search-clear:hover::before,
+site-search #starlight__search .pagefind-ui__search-clear:focus-visible::before {
   background-color: var(--sl-color-white);
 }
 
 site-search #starlight__search .pagefind-ui__search-clear:focus {
-  outline: 1px solid var(--warp-control-border-hover);
+  outline: none;
 }
 
 /* Result rows are transparent siblings inside the page card so the card

From 9b724e72ca3f1dea756264a9467e2140af162753 Mon Sep 17 00:00:00 2001
From: Hong Yi Chen <hongyigma@gmail.com>
Date: Sun, 10 May 2026 16:39:29 -0700
Subject: [PATCH 10/11] docs: balance clear-X icon size + spacing with the
 magnifier

- Drop the X mask to 13x13 (vs the magnifier's 16x16). Lucide's X spans
  almost the full viewBox while the magnifier's circle only fills the
  inner ~half, so identical pixel sizes made the X visually heavier.
  13px matches the optical weight of the magnifier circle.
- Push the clear button to inset-inline-end: 18px so it sits ~the same
  distance from the input's right edge as the magnifier sits from the
  left edge (~20px), giving the icon pair symmetric breathing room.

Co-Authored-By: Oz <oz-agent@warp.dev>
---
 src/styles/warp-components.css | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/src/styles/warp-components.css b/src/styles/warp-components.css
index 6850802d..ff81c824 100644
--- a/src/styles/warp-components.css
+++ b/src/styles/warp-components.css
@@ -1185,8 +1185,12 @@ site-search #starlight__search .pagefind-ui__form::before {
 }
 
 site-search #starlight__search .pagefind-ui__search-clear::before {
-  width: 16px;
-  height: 16px;
+  /* The Lucide X spans almost the full viewBox while the magnifier circle
+     only fills the inner ~half, so rendering both at 16px makes the X
+     visually outweigh the magnifier. Pull the X down to 13px so the two
+     icons read as the same optical weight. */
+  width: 13px;
+  height: 13px;
   background-color: var(--sl-color-gray-3);
   -webkit-mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M18 6 6 18'/%3E%3Cpath d='m6 6 12 12'/%3E%3C/svg%3E");
   mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M18 6 6 18'/%3E%3Cpath d='m6 6 12 12'/%3E%3C/svg%3E");
@@ -1202,10 +1206,13 @@ site-search #starlight__search .pagefind-ui__search-clear::before {
    text node alongside the `::before` icon, which renders as visible copy
    stacked under the X. Collapse the label to zero size so only the icon
    shows; the text node stays in the DOM so screen readers still announce
-   the button as "Clear". */
+   the button as "Clear". `inset-inline-end` pushes the button away from
+   the input's right edge so the X has the same breathing room as the
+   magnifier on the left (~20px from the form edge). */
 site-search #starlight__search .pagefind-ui__search-clear {
   font-size: 0;
   line-height: 0;
+  inset-inline-end: 18px;
 }
 
 /* Hover + keyboard focus: brighten just the icon. The form's `:focus-within`

From 862f5ab061d3242c347bcee0dcc6f0119c0cd049 Mon Sep 17 00:00:00 2001
From: Hong Yi Chen <hongyigma@gmail.com>
Date: Sun, 10 May 2026 16:44:43 -0700
Subject: [PATCH 11/11] =?UTF-8?q?docs:=20pre-fill=20Kapa=20input=20with=20?=
 =?UTF-8?q?current=20search=20query=20on=20Ask=20AI=20/=20=E2=8C=98+I?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both entry points into Kapa (the ⌘+I / Ctrl+I global shortcut and the
'Ask AI' footer CTA inside the search dialog) now hand the live search
query off to Kapa's input. Previously the ⌘+I path passed nothing, and
the Ask AI button auto-submitted via a window-stashed variable instead
of pre-filling.

- KapaChatLauncher#openPanel() is now the single owner of the handoff:
  reads .pagefind-ui__search-input.value before closing the search
  dialog (closing tears down the input), then setQuery(pendingQuery)
  so the value appears in the controlled Kapa input.
- Pre-fills instead of auto-submits so the user can refine before
  sending. The existing open-dialog effect focuses inputRef, so the
  cursor lands at the end of the pre-filled text — Enter or edit.
- Drops the timeout-based submitQuery hack. Keeps __warpAskAiQuery as
  a legacy fallback in case any other caller still uses it.
- CustomSidebar's Ask AI click handler is simplified to just route
  the click; openPanel reads the input and closes the search dialog.

Co-Authored-By: Oz <oz-agent@warp.dev>
---
 src/components/CustomSidebar.astro  |  8 ++-----
 src/components/KapaChatLauncher.tsx | 34 +++++++++++++++++------------
 2 files changed, 22 insertions(+), 20 deletions(-)

diff --git a/src/components/CustomSidebar.astro b/src/components/CustomSidebar.astro
index 811b6747..1a5027ae 100644
--- a/src/components/CustomSidebar.astro
+++ b/src/components/CustomSidebar.astro
@@ -144,12 +144,8 @@ import KapaLauncher from './KapaLauncher.astro';
 				+ '<span class="warp-search-ask-ai-row__label">Ask AI</span>'
 				+ '<kbd class="warp-search-ask-ai-row__kbd" aria-hidden="true">' + modKey + '<span class="warp-search-ask-ai-row__kbd-plus">+</span>I</kbd>';
 			askAi.addEventListener('click', function () {
-				var searchInput = dialog.querySelector('.pagefind-ui__search-input');
-				var searchQuery = searchInput ? searchInput.value.trim() : '';
-				if (searchQuery) {
-					window.__warpAskAiQuery = searchQuery;
-				}
-				dialog.close();
+				// openPanel() in KapaChatLauncher reads the live search input and
+				// closes the search dialog itself, so we just route the click.
 				var kapaBtn = document.querySelector('.warp-kapa-button');
 				if (kapaBtn) kapaBtn.click();
 			});
diff --git a/src/components/KapaChatLauncher.tsx b/src/components/KapaChatLauncher.tsx
index 4f4c862f..d4e1bcb9 100644
--- a/src/components/KapaChatLauncher.tsx
+++ b/src/components/KapaChatLauncher.tsx
@@ -122,27 +122,33 @@ function ChatSurface({ title, welcomeMessage, autoOpen = false, onNewConversatio
 	};
 
 	const openPanel = () => {
-		// Close any open Pagefind search dialog so the two modals don't
-		// stack visually. This covers every path into Kapa: the `⌘+I` /
-		// `Ctrl+I` global shortcut, the trigger button, and the new
-		// "Ask AI" CTA inside the search footer (which also closes its
-		// own dialog before calling us — this is a belt-and-braces guard).
+		// If the Pagefind search dialog is open with a query typed in, hand
+		// that query off to Kapa's input. Both entry points (the ⌘+I / Ctrl+I
+		// global shortcut and the "Ask AI" footer CTA) route through here, so
+		// this is the single place that owns the search → Kapa handoff. Read
+		// the value BEFORE closing the dialog — closing tears down the input.
 		const searchDialog = document.querySelector<HTMLDialogElement>('site-search dialog');
+		let pendingQuery: string | undefined;
 		if (searchDialog?.open) {
+			const searchInput = searchDialog.querySelector<HTMLInputElement>('.pagefind-ui__search-input');
+			pendingQuery = searchInput?.value.trim() || undefined;
 			searchDialog.close();
 		}
+		// Legacy fallback: earlier callers stashed the query on window before
+		// triggering us. Kept as a belt-and-braces guard in case any path
+		// still uses it.
+		if (!pendingQuery && (window as any).__warpAskAiQuery) {
+			pendingQuery = (window as any).__warpAskAiQuery;
+			delete (window as any).__warpAskAiQuery;
+		}
 
 		setIsOpen(true);
-		// If a search query was passed from the search dialog's "Ask AI"
-		// button, auto-submit it after the panel opens.
-		const pendingQuery = (window as any).__warpAskAiQuery;
+		// Pre-fill (don't auto-submit) so the user can refine before sending.
+		// The input is controlled by `query` state, and the open-dialog effect
+		// focuses inputRef once the dialog mounts — cursor lands at the end
+		// of the pre-filled text, ready for Enter or edits.
 		if (pendingQuery) {
-			delete (window as any).__warpAskAiQuery;
-			// Wait for the panel to mount and the input to be ready
-			setTimeout(() => {
-				submitQuery(pendingQuery);
-				setHasStartedConversation(true);
-			}, 100);
+			setQuery(pendingQuery);
 		}
 	};