+
+
+
diff --git a/src/components/SiteFooter.astro b/src/components/SiteFooter.astro
new file mode 100644
index 0000000..4d490ea
--- /dev/null
+++ b/src/components/SiteFooter.astro
@@ -0,0 +1,42 @@
+---
+import {Icon} from '@astrojs/starlight/components';
+import './site-footer.css';
+---
+
+
+
+
diff --git a/src/components/codeBlockTitles.spec.ts b/src/components/codeBlockTitles.spec.ts
new file mode 100644
index 0000000..e82d433
--- /dev/null
+++ b/src/components/codeBlockTitles.spec.ts
@@ -0,0 +1,113 @@
+import {test} from 'kizu';
+import {
+ COPY_FEEDBACK_MS,
+ copyButtonContent,
+ copyButtonMarkup,
+ defaultTitleFromLang,
+ ecDataCodeToText,
+ fileKindFromName,
+ isFilePathTitle,
+ kindFromTitle,
+ tryCopyText,
+} from './codeBlockTitles';
+
+test('copyButtonContent idle and copied labels', (assert) => {
+ assert.equal(copyButtonContent(false), {label: 'Copy', state: 'idle'});
+ assert.equal(copyButtonContent(true), {label: 'Copied!', state: 'copied'});
+});
+
+test('copyButtonContent keeps a custom idle label after Copied!', (assert) => {
+ assert.equal(copyButtonContent(false, 'Copy curl'), {label: 'Copy curl', state: 'idle'});
+ assert.equal(copyButtonContent(true, 'Copy curl'), {label: 'Copied!', state: 'copied'});
+});
+
+test('copyButtonMarkup is the docs chrome idle control', (assert) => {
+ const html = copyButtonMarkup({copyTarget: 'cursor-mcp-config'});
+ assert.equal(html.includes('class="cs-copy-btn"'), true);
+ assert.equal(html.includes('cs-copy-icon'), true);
+ assert.equal(html.includes('cs-copy-label'), true);
+ assert.equal(html.includes('Copy to clipboard'), true);
+ assert.equal(html.includes('data-copy-target="cursor-mcp-config"'), true);
+});
+
+test('copyButtonMarkup accepts id, copy value, and a custom idle label', (assert) => {
+ const html = copyButtonMarkup({
+ id: 'copy-curl-try',
+ copyValue: 'http://127.0.0.1:3000/v1/mcp',
+ label: 'Copy curl',
+ });
+ assert.equal(html.includes('id="copy-curl-try"'), true);
+ assert.equal(html.includes('data-copy="http://127.0.0.1:3000/v1/mcp"'), true);
+ assert.equal(html.includes('data-cs-copy-idle-label="Copy curl"'), true);
+ assert.equal(html.includes('>Copy curl'), true);
+ assert.equal(html.includes('class="btn'), false);
+});
+
+test('COPY_FEEDBACK_MS is 1500ms', (assert) => {
+ assert.equal(COPY_FEEDBACK_MS, 1500);
+});
+
+test('ecDataCodeToText turns EC delimiter into newlines', (assert) => {
+ assert.equal(ecDataCodeToText(`a\u007fb`), 'a\nb');
+ assert.equal(ecDataCodeToText('plain'), 'plain');
+});
+
+test('tryCopyText returns true only when write succeeds', async (assert) => {
+ assert.equal(await tryCopyText('hi', {writeText: async () => undefined}), true);
+ assert.equal(
+ await tryCopyText('hi', {
+ writeText: async () => {
+ throw new Error('denied');
+ },
+ }),
+ false,
+ );
+ assert.equal(await tryCopyText('', {writeText: async () => undefined}), false);
+});
+
+test('defaultTitleFromLang maps fence langs to tab labels', (assert) => {
+ assert.equal(defaultTitleFromLang('typescript'), 'typescript');
+ assert.equal(defaultTitleFromLang('tsx'), 'tsx');
+ assert.equal(defaultTitleFromLang('javascript'), 'javascript');
+ assert.equal(defaultTitleFromLang('json'), 'json');
+ assert.equal(defaultTitleFromLang('text'), 'text');
+ assert.equal(defaultTitleFromLang(''), 'code');
+});
+
+test('isFilePathTitle distinguishes filenames from bare lang titles', (assert) => {
+ assert.equal(isFilePathTitle('server/routes.ts'), true);
+ assert.equal(isFilePathTitle('getProductById.ts'), true);
+ assert.equal(isFilePathTitle('typescript'), false);
+ assert.equal(isFilePathTitle('bash'), false);
+ assert.equal(isFilePathTitle('SKILL.md'), true);
+});
+
+test('kindFromTitle maps langs and filenames to chips', (assert) => {
+ assert.equal(kindFromTitle('typescript'), 'TS');
+ assert.equal(kindFromTitle('tsx'), 'TSX');
+ assert.equal(kindFromTitle('server/app.ts'), 'TS');
+ assert.equal(kindFromTitle('text'), null);
+});
+
+test('fileKindFromName maps common extensions', (assert) => {
+ assert.equal(fileKindFromName('getProductById.ts'), 'TS');
+ assert.equal(fileKindFromName('App.tsx'), 'TSX');
+ assert.equal(fileKindFromName('index.js'), 'JS');
+ assert.equal(fileKindFromName('util.mjs'), 'JS');
+ assert.equal(fileKindFromName('package.json'), 'JSON');
+ assert.equal(fileKindFromName('README.md'), 'MD');
+ assert.equal(fileKindFromName('styles.css'), 'CSS');
+ assert.equal(fileKindFromName('main.py'), 'PY');
+ assert.equal(fileKindFromName('main.go'), 'GO');
+});
+
+test('fileKindFromName is case-insensitive and path-aware', (assert) => {
+ assert.equal(fileKindFromName('server/routes/Foo.TS'), 'TS');
+ assert.equal(fileKindFromName('nested/dir/app.tsx'), 'TSX');
+});
+
+test('fileKindFromName returns null for unknown extensions', (assert) => {
+ assert.equal(fileKindFromName('Makefile'), null);
+ assert.equal(fileKindFromName('notes.txt'), null);
+ assert.equal(fileKindFromName(''), null);
+});
diff --git a/src/components/codeBlockTitles.ts b/src/components/codeBlockTitles.ts
new file mode 100644
index 0000000..d24b3f3
--- /dev/null
+++ b/src/components/codeBlockTitles.ts
@@ -0,0 +1,326 @@
+export const COPY_FEEDBACK_MS = 1500;
+
+export function copyButtonContent(
+ isCopied: boolean,
+ idleLabel = 'Copy',
+): {label: string; state: 'idle' | 'copied'} {
+ return isCopied
+ ? {label: 'Copied!', state: 'copied'}
+ : {label: idleLabel, state: 'idle'};
+}
+
+/** Expressive Code joins multi-line `data-code` with U+007F. */
+export function ecDataCodeToText(dataCode: string): string {
+ return dataCode.replace(/\u007f/g, '\n');
+}
+
+export type TryCopyTextDeps = {
+ writeText?: (text: string) => Promise
+};
+
+/**
+ * Copy text to the clipboard: succeed β true; failure β false.
+ * Inject `writeText` in tests; browser path uses `navigator.clipboard.writeText`.
+ */
+export async function tryCopyText(text: string, deps: TryCopyTextDeps = {}): Promise {
+ if (!text) {
+ return false;
+ }
+
+ const writeText = deps.writeText
+ ?? (typeof navigator !== 'undefined' && navigator.clipboard?.writeText
+ ? (value: string): Promise => navigator.clipboard.writeText(value)
+ : undefined);
+
+ if (!writeText) {
+ return false;
+ }
+
+ try {
+ await writeText(text);
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+/** File-extension β short language label for code-block chrome. */
+const EXT_KIND: ReadonlyArray = [
+ [/\.tsx$/i, 'TSX'],
+ [/\.ts$/i, 'TS'],
+ [/\.jsx$/i, 'JSX'],
+ [/\.(?:js|mjs|cjs)$/i, 'JS'],
+ [/\.json$/i, 'JSON'],
+ [/\.(?:md|mdx)$/i, 'MD'],
+ [/\.(?:css|scss)$/i, 'CSS'],
+ [/\.py$/i, 'PY'],
+ [/\.go$/i, 'GO'],
+ [/\.(?:rs)$/i, 'RS'],
+ [/\.(?:ya?ml)$/i, 'YML'],
+];
+
+export function fileKindFromName(name: string): string | null {
+ for (const [re, kind] of EXT_KIND) {
+ if (re.test(name)) {
+ return kind;
+ }
+ }
+ return null;
+}
+
+/** Fence language β tab label when the block has no `title="β¦"`. */
+export function defaultTitleFromLang(lang: string): string {
+ const id = lang.trim().toLowerCase();
+ return id || 'code';
+}
+
+/** True when the title looks like a path/filename (not a bare language id). */
+export function isFilePathTitle(title: string): boolean {
+ return title.includes('/') || /\.[a-z0-9]+$/i.test(title);
+}
+
+/** Language id / filename β short chip (TS, JS, β¦). */
+export function kindFromTitle(title: string): string | null {
+ if (isFilePathTitle(title)) {
+ const base = title.includes('/') ? title.slice(title.lastIndexOf('/') + 1) : title;
+ return fileKindFromName(base);
+ }
+ const lang = title.trim().toLowerCase();
+ const LANG_KIND: Record = {
+ typescript: 'TS',
+ ts: 'TS',
+ tsx: 'TSX',
+ javascript: 'JS',
+ js: 'JS',
+ jsx: 'JSX',
+ mjs: 'JS',
+ cjs: 'JS',
+ json: 'JSON',
+ markdown: 'MD',
+ md: 'MD',
+ mdx: 'MD',
+ css: 'CSS',
+ scss: 'CSS',
+ python: 'PY',
+ py: 'PY',
+ go: 'GO',
+ rust: 'RS',
+ rs: 'RS',
+ yaml: 'YML',
+ yml: 'YML',
+ };
+ return LANG_KIND[lang] ?? null;
+}
+
+const COPY_ICON_SVG =
+ '';
+
+const CHECK_ICON_SVG =
+ '';
+
+function idleLabelOf(button: HTMLButtonElement): string {
+ return button.dataset.csCopyIdleLabel || copyButtonContent(false).label;
+}
+
+function escapeAttr(value: string): string {
+ return value
+ .replace(/&/g, '&')
+ .replace(/"/g, '"')
+ .replace(/>();
+
+/** Green βCopied!β then restore the idle label after COPY_FEEDBACK_MS. */
+export function showCopySuccess(button: HTMLButtonElement): void {
+ paintCopyButton(button, true);
+ const previous = copyResetTimers.get(button);
+ if (previous !== undefined) {
+ clearTimeout(previous);
+ }
+ copyResetTimers.set(button, setTimeout(() => {
+ paintCopyButton(button, false);
+ copyResetTimers.delete(button);
+ }, COPY_FEEDBACK_MS));
+}
+
+/** Idle chrome used by docs EC and explorer MCP / Try it copy controls. */
+export function copyButtonMarkup(attrs: {
+ copyTarget?: string
+ copyValue?: string
+ id?: string
+ label?: string
+} = {}): string {
+ const {label} = copyButtonContent(false, attrs.label);
+ const extra = [
+ attrs.id === undefined ? '' : ` id="${escapeAttr(attrs.id)}"`,
+ attrs.copyTarget === undefined ? '' : ` data-copy-target="${escapeAttr(attrs.copyTarget)}"`,
+ attrs.copyValue === undefined ? '' : ` data-copy="${escapeAttr(attrs.copyValue)}"`,
+ attrs.label === undefined ? '' : ` data-cs-copy-idle-label="${escapeAttr(attrs.label)}"`,
+ ].join('');
+ return (
+ ``
+ );
+}
+
+function createKindMark(kind: string): HTMLElement {
+ const badge = document.createElement('span');
+ badge.className = 'cs-code-kind';
+ badge.dataset.kind = kind;
+ badge.textContent = kind;
+ badge.setAttribute('aria-hidden', 'true');
+ return badge;
+}
+
+function ensureDots(header: HTMLElement): void {
+ let dots = header.querySelector(':scope > .cs-code-dots');
+ if (!(dots instanceof HTMLElement)) {
+ dots = document.createElement('span');
+ dots.className = 'cs-code-dots';
+ dots.setAttribute('aria-hidden', 'true');
+ header.prepend(dots);
+ }
+ // One element + CSS mask (shared by terminal + editor frames) β no child spans
+ dots.replaceChildren();
+}
+
+/** Park the EC copy control in the chrome row; icon + βCopyβ β green check + βCopied!β for COPY_FEEDBACK_MS. */
+function ensureCopyInHeader(frame: HTMLElement, header: HTMLElement): void {
+ const copy = frame.querySelector(':scope > .copy') ?? header.querySelector(':scope > .copy');
+ if (!(copy instanceof HTMLElement)) {
+ return;
+ }
+ if (copy.parentElement !== header) {
+ header.append(copy);
+ }
+
+ const button = copy.querySelector(':scope > button');
+ if (!(button instanceof HTMLButtonElement) || button.dataset.csCopyWired === '1') {
+ return;
+ }
+
+ button.dataset.csCopyWired = '1';
+ button.classList.add('cs-copy-btn');
+ button.type = 'button';
+ paintCopyButton(button, false);
+
+ button.addEventListener('click', (event) => {
+ // Own the clipboard path so we only show βCopied!β after a real success.
+ event.preventDefault();
+ event.stopPropagation();
+
+ const text = ecDataCodeToText(button.dataset.code ?? '');
+ void tryCopyText(text).then((ok) => {
+ if (ok) {
+ showCopySuccess(button);
+ }
+ });
+ });
+}
+
+function buildTitleNodes(text: string): Node[] {
+ const kind = kindFromTitle(text);
+ const nodes: Node[] = [];
+
+ if (kind) {
+ nodes.push(createKindMark(kind));
+ }
+
+ const name = document.createElement('span');
+ name.className = 'cs-code-name';
+
+ if (!isFilePathTitle(text)) {
+ const label = document.createElement('span');
+ label.className = 'cs-code-file';
+ label.textContent = text;
+ name.append(label);
+ nodes.push(name);
+ return nodes;
+ }
+
+ const slash = text.lastIndexOf('/');
+ const basename = slash === -1 ? text : text.slice(slash + 1);
+
+ if (slash !== -1) {
+ const dir = document.createElement('span');
+ dir.className = 'cs-code-path';
+ dir.textContent = text.slice(0, slash + 1);
+ name.append(dir);
+ }
+
+ const file = document.createElement('span');
+ file.className = 'cs-code-file';
+ file.textContent = basename;
+ name.append(file);
+ nodes.push(name);
+
+ return nodes;
+}
+
+function titleSourceText(title: HTMLElement): string {
+ const path = title.querySelector('.cs-code-path')?.textContent ?? '';
+ const file = title.querySelector('.cs-code-file')?.textContent ?? '';
+ if (path || file) {
+ return `${path}${file}`;
+ }
+ return (title.textContent ?? '').trim();
+}
+
+function enhanceTitle(frame: HTMLElement): void {
+ const header = frame.querySelector(':scope > .header');
+ const title = frame.querySelector(':scope > .header .title');
+ if (!(header instanceof HTMLElement) || !(title instanceof HTMLElement)) {
+ return;
+ }
+
+ ensureDots(header);
+ ensureCopyInHeader(frame, header);
+
+ if (frame.classList.contains('is-terminal')) {
+ title.dataset.csEnhanced = '1';
+ return;
+ }
+
+ if (title.dataset.csEnhanced === '1' && title.querySelector('.cs-code-name')) {
+ return;
+ }
+
+ const text = titleSourceText(title);
+ if (!text) {
+ title.dataset.csEnhanced = '1';
+ return;
+ }
+
+ title.replaceChildren(...buildTitleNodes(text));
+ title.dataset.csEnhanced = '1';
+}
+
+export function enhanceCodeBlockTitles(root: ParentNode = document): void {
+ const frames = Array.from(
+ root.querySelectorAll('.expressive-code .frame.has-title, .expressive-code .frame.is-terminal'),
+ );
+ for (const frame of frames) {
+ if (frame instanceof HTMLElement) {
+ enhanceTitle(frame);
+ }
+ }
+}
diff --git a/src/components/docsSearchQuery.spec.ts b/src/components/docsSearchQuery.spec.ts
new file mode 100644
index 0000000..2370f4c
--- /dev/null
+++ b/src/components/docsSearchQuery.spec.ts
@@ -0,0 +1,16 @@
+import {test} from 'kizu';
+import {DOCS_SEARCH_MIN_QUERY_LENGTH, DOCS_SEARCH_PAGE_SIZE, isDocsSearchQueryReady} from './docsSearchQuery.js';
+
+test('isDocsSearchQueryReady requires at least DOCS_SEARCH_MIN_QUERY_LENGTH characters', (assert) => {
+
+ assert.equal(DOCS_SEARCH_MIN_QUERY_LENGTH, 3);
+ assert.equal(isDocsSearchQueryReady('ab'), false);
+ assert.equal(isDocsSearchQueryReady('abc'), true);
+
+});
+
+test('DOCS_SEARCH_PAGE_SIZE matches Pagefind UI pagination', (assert) => {
+
+ assert.equal(DOCS_SEARCH_PAGE_SIZE, 25);
+
+});
diff --git a/src/components/docsSearchQuery.ts b/src/components/docsSearchQuery.ts
new file mode 100644
index 0000000..489c9c2
--- /dev/null
+++ b/src/components/docsSearchQuery.ts
@@ -0,0 +1,9 @@
+/** Docs search does not query Pagefind until the trimmed query is at least this long. */
+export const DOCS_SEARCH_MIN_QUERY_LENGTH = 3;
+
+/** Pagefind UI shows this many hits per page; βLoad moreβ fetches the next page. */
+export const DOCS_SEARCH_PAGE_SIZE = 25;
+
+export function isDocsSearchQueryReady(query: string): boolean {
+ return query.trim().length >= DOCS_SEARCH_MIN_QUERY_LENGTH;
+}
diff --git a/src/components/isUsefulPagefindMatch.spec.ts b/src/components/isUsefulPagefindMatch.spec.ts
new file mode 100644
index 0000000..284a338
--- /dev/null
+++ b/src/components/isUsefulPagefindMatch.spec.ts
@@ -0,0 +1,57 @@
+import {test} from 'kizu';
+import {isUsefulMark, isUsefulPagefindMatch} from './isUsefulPagefindMatch.js';
+
+test('rejects inverted short-prefix garbage (adsf β a, asdfasdf β as)', (assert) => {
+ assert.equal(isUsefulMark('adsf', 'a'), false);
+ assert.equal(isUsefulMark('asdfasdf', 'as'), false);
+ assert.equal(isUsefulMark('xyzz', 'x'), false);
+
+ assert.equal(
+ isUsefulPagefindMatch('adsf', {
+ excerpt: 'Fetch from a running server.',
+ }),
+ false,
+ );
+ assert.equal(
+ isUsefulPagefindMatch('asdfasdf', {
+ excerpt: 'same routes object as your RPC server',
+ }),
+ false,
+ );
+});
+
+test('keeps real prefix/extension matches and exact terms', (assert) => {
+ assert.equal(isUsefulMark('a', 'a'), true, 'intentional single-letter search');
+ assert.equal(isUsefulMark('route', 'route'), true);
+ assert.equal(isUsefulMark('route', 'routes'), true);
+ assert.equal(isUsefulMark('err', 'error'), true);
+ assert.equal(isUsefulMark('mcp', 'MCP'), true);
+ assert.equal(
+ isUsefulMark('adsf', 'host'),
+ false,
+ 'unrelated similar-length marks are not kept',
+ );
+
+ assert.equal(
+ isUsefulPagefindMatch('mcp', {
+ excerpt: 'Enable MCP tools on your API',
+ meta: {title: 'MCP'},
+ }),
+ true,
+ );
+ assert.equal(
+ isUsefulPagefindMatch('route', {
+ excerpt: 'Define a route with input and output',
+ sub_results: [{excerpt: 'Multiple routes share schemas'}],
+ }),
+ true,
+ );
+ assert.equal(
+ isUsefulPagefindMatch('openapi', {
+ excerpt: 'Fetch from a running server',
+ meta: {title: 'OpenAPI'},
+ }),
+ true,
+ 'title still counts when excerpt marks are weak',
+ );
+});
diff --git a/src/components/isUsefulPagefindMatch.ts b/src/components/isUsefulPagefindMatch.ts
new file mode 100644
index 0000000..1786cc6
--- /dev/null
+++ b/src/components/isUsefulPagefindMatch.ts
@@ -0,0 +1,56 @@
+/**
+ * Pagefind matches indexed terms that are prefixes of the query, so typing
+ * "adsf" returns every page that contains the word "a". Reject those weak
+ * inverted-prefix hits while keeping normal prefix/extension matches
+ * ("route" β "routes", "err" β "error").
+ */
+
+function normalize(text: string): string {
+ return text.replace(/<[^>]+>/g, '').trim().toLowerCase();
+}
+
+function extractMarks(html: string): string[] {
+ return [...html.matchAll(/([\s\S]*?)<\/mark>/gi)].map((match) => normalize(match[1] ?? ''));
+}
+
+export function isUsefulMark(query: string, mark: string): boolean {
+ const q = normalize(query);
+ const m = normalize(mark);
+ if (!q || !m) return false;
+ if (m === q) return true;
+ // Matched word extends the query: "route" β "routes"
+ if (m.startsWith(q)) return true;
+ // Indexed term is a prefix of the query: only keep if substantial
+ if (q.startsWith(m)) {
+ const minLen = Math.min(3, q.length);
+ return m.length >= minLen && m.length >= Math.ceil(q.length * 0.5);
+ }
+ return false;
+}
+
+export type PagefindMatchData = {
+ excerpt?: string;
+ meta?: {title?: string};
+ sub_results?: Array<{excerpt?: string; title?: string}>;
+};
+
+export function isUsefulPagefindMatch(query: string, data: PagefindMatchData): boolean {
+ const q = normalize(query);
+ if (!q) return false;
+
+ const htmlBits: string[] = [];
+ if (data.excerpt) htmlBits.push(data.excerpt);
+ for (const sub of data.sub_results ?? []) {
+ if (sub.excerpt) htmlBits.push(sub.excerpt);
+ }
+
+ const marks = htmlBits.flatMap(extractMarks);
+ if (marks.some((mark) => isUsefulMark(q, mark))) return true;
+
+ const plainBits = [
+ ...htmlBits.map(normalize),
+ normalize(data.meta?.title ?? ''),
+ ...(data.sub_results ?? []).map((sub) => normalize(sub.title ?? '')),
+ ];
+ return plainBits.some((text) => text.includes(q));
+}
diff --git a/src/components/pagefindMount.spec.ts b/src/components/pagefindMount.spec.ts
new file mode 100644
index 0000000..8f0130e
--- /dev/null
+++ b/src/components/pagefindMount.spec.ts
@@ -0,0 +1,30 @@
+import {test} from 'kizu';
+import {bindPagefindMount, type PagefindMountEl} from './pagefindMount.js';
+
+function hostWith(mount: PagefindMountEl | null): {querySelector(selector: string): PagefindMountEl | null} {
+ return {
+ querySelector(selector: string): PagefindMountEl | null {
+ return selector === '[data-cs-pagefind-root]' ? mount : null;
+ },
+ };
+}
+
+test('bindPagefindMount gives each site-search its own Pagefind selector', (assert) => {
+ const header = {id: 'starlight__search'};
+ const mobile = {id: 'starlight__search'};
+
+ assert.equal(
+ bindPagefindMount(hostWith(header), 'starlight__search-1'),
+ '#starlight__search-1',
+ );
+ assert.equal(
+ bindPagefindMount(hostWith(mobile), 'starlight__search-2'),
+ '#starlight__search-2',
+ );
+ assert.equal(header.id, 'starlight__search-1');
+ assert.equal(mobile.id, 'starlight__search-2');
+});
+
+test('bindPagefindMount returns null when this instance has no mount', (assert) => {
+ assert.equal(bindPagefindMount(hostWith(null), 'starlight__search-1'), null);
+});
diff --git a/src/components/pagefindMount.ts b/src/components/pagefindMount.ts
new file mode 100644
index 0000000..eff597a
--- /dev/null
+++ b/src/components/pagefindMount.ts
@@ -0,0 +1,18 @@
+export type PagefindMountEl = {
+ id: string;
+};
+
+export type PagefindMountHost = {
+ querySelector(selector: string): PagefindMountEl | null;
+};
+
+/**
+ * PagefindUI takes a document-level CSS selector. Header + mobile
+ * both used `#starlight__search`, so both UIs mounted into the first dialog.
+ */
+export function bindPagefindMount(host: PagefindMountHost, id: string): string | null {
+ const mount = host.querySelector('[data-cs-pagefind-root]');
+ if (!mount) return null;
+ mount.id = id;
+ return `#${id}`;
+}
diff --git a/src/components/searchClearRefocus.spec.ts b/src/components/searchClearRefocus.spec.ts
new file mode 100644
index 0000000..cf904ca
--- /dev/null
+++ b/src/components/searchClearRefocus.spec.ts
@@ -0,0 +1,71 @@
+import {test} from 'kizu';
+import {bindSearchClearRefocus} from './searchClearRefocus.js';
+
+function stubRoot(input: StubInput, clear: StubClear): Element {
+ return {
+ querySelector(selector: string): Element | null {
+ if (selector === '.pagefind-ui__search-input') return input as unknown as Element;
+ if (selector === '.pagefind-ui__search-clear') return clear as unknown as Element;
+ return null;
+ },
+ } as unknown as Element;
+}
+
+type StubInput = {
+ focusCalls: number;
+ focus(): void;
+};
+
+type StubClear = {
+ dataset: Record;
+ listeners: Array<() => void>;
+ addEventListener(_type: string, listener: () => void): void;
+ click(): void;
+};
+
+function stubInput(): StubInput {
+ return {
+ focusCalls: 0,
+ focus(): void {
+ this.focusCalls += 1;
+ },
+ };
+}
+
+function stubClear(): StubClear {
+ const clear: StubClear = {
+ dataset: {},
+ listeners: [],
+ addEventListener(_type, listener) {
+ this.listeners.push(listener);
+ },
+ click() {
+ for (const listener of this.listeners) listener();
+ },
+ };
+ return clear;
+}
+
+test('bindSearchClearRefocus is idempotent on the clear button', (assert) => {
+ const input = stubInput();
+ const clear = stubClear();
+ const root = stubRoot(input, clear);
+
+ bindSearchClearRefocus(root);
+ bindSearchClearRefocus(root);
+
+ assert.equal(clear.listeners.length, 1);
+
+ clear.click();
+
+ return new Promise((resolve, reject) => {
+ queueMicrotask(() => {
+ try {
+ assert.equal(input.focusCalls >= 1, true);
+ resolve();
+ } catch (err) {
+ reject(err);
+ }
+ });
+ });
+});
diff --git a/src/components/searchClearRefocus.ts b/src/components/searchClearRefocus.ts
new file mode 100644
index 0000000..0b4524b
--- /dev/null
+++ b/src/components/searchClearRefocus.ts
@@ -0,0 +1,29 @@
+/** Pagefind clears the query and blurs the input β put focus back for keyboard flow. */
+function scheduleNextFrame(callback: () => void): void {
+ if (typeof requestAnimationFrame === 'function') {
+ requestAnimationFrame(callback);
+ return;
+ }
+ setTimeout(callback, 0);
+}
+
+function scheduleSearchInputFocus(input: HTMLInputElement, focus: (el: HTMLInputElement) => void): void {
+ queueMicrotask(() => {
+ focus(input);
+ scheduleNextFrame(() => focus(input));
+ });
+}
+
+export function bindSearchClearRefocus(
+ root: Element,
+ focus: (input: HTMLInputElement) => void = (input) => input.focus(),
+): void {
+ const clear = root.querySelector('.pagefind-ui__search-clear');
+ const input = root.querySelector('.pagefind-ui__search-input');
+ if (!clear || !input || clear.dataset.csSearchClearBound === '1') return;
+
+ clear.dataset.csSearchClearBound = '1';
+ clear.addEventListener('click', () => {
+ scheduleSearchInputFocus(input, focus);
+ });
+}
diff --git a/src/components/searchDialog.spec.ts b/src/components/searchDialog.spec.ts
new file mode 100644
index 0000000..cb23c5e
--- /dev/null
+++ b/src/components/searchDialog.spec.ts
@@ -0,0 +1,84 @@
+import {test} from 'kizu';
+import {
+ isEditableSearchTarget,
+ openPrimaryDocsSearch,
+ shouldCloseOnOutsideClick,
+ shouldCloseSearchOnEscape,
+ shouldHandleGlobalSlash,
+} from './searchDialog.js';
+
+test('shouldHandleGlobalSlash opens only when idle and not typing in a field', (assert) => {
+ const base = {
+ key: '/',
+ metaKey: false,
+ ctrlKey: false,
+ altKey: false,
+ shiftKey: false,
+ anySearchDialogOpen: false,
+ targetIsEditable: false,
+ };
+ assert.equal(shouldHandleGlobalSlash(base), true);
+ assert.equal(shouldHandleGlobalSlash({...base, anySearchDialogOpen: true}), false);
+ assert.equal(shouldHandleGlobalSlash({...base, targetIsEditable: true}), false);
+ assert.equal(shouldHandleGlobalSlash({...base, key: 'Escape'}), false);
+ assert.equal(shouldHandleGlobalSlash({...base, metaKey: true}), false);
+});
+
+test('isEditableSearchTarget covers inputs, textareas, selects, and contenteditable', (assert) => {
+ assert.equal(isEditableSearchTarget({tagName: 'INPUT', isContentEditable: false}), true);
+ assert.equal(isEditableSearchTarget({tagName: 'TEXTAREA', isContentEditable: false}), true);
+ assert.equal(isEditableSearchTarget({tagName: 'SELECT', isContentEditable: false}), true);
+ assert.equal(isEditableSearchTarget({tagName: 'DIV', isContentEditable: true}), true);
+ assert.equal(isEditableSearchTarget({tagName: 'BODY', isContentEditable: false}), false);
+});
+
+test('shouldCloseSearchOnEscape closes the whole dialog on first Escape', (assert) => {
+ assert.equal(shouldCloseSearchOnEscape('Escape'), true);
+ assert.equal(shouldCloseSearchOnEscape('Esc'), false);
+ assert.equal(shouldCloseSearchOnEscape('/'), false);
+});
+
+test('shouldCloseOnOutsideClick is true for backdrop / outside the frame, and for links', (assert) => {
+ assert.equal(
+ shouldCloseOnOutsideClick({
+ targetIsLink: false,
+ targetInDocument: true,
+ targetInDialogFrame: false,
+ }),
+ true,
+ 'click on backdrop closes',
+ );
+ assert.equal(
+ shouldCloseOnOutsideClick({
+ targetIsLink: true,
+ targetInDocument: true,
+ targetInDialogFrame: true,
+ }),
+ true,
+ 'result link click closes',
+ );
+ assert.equal(
+ shouldCloseOnOutsideClick({
+ targetIsLink: false,
+ targetInDocument: true,
+ targetInDialogFrame: true,
+ }),
+ false,
+ 'click inside the dialog stays open',
+ );
+});
+
+test('openPrimaryDocsSearch clicks only the header search button', (assert) => {
+ const clicks: string[] = [];
+ const headerBtn = {click: (): void => { clicks.push('header'); }};
+ const mobileBtn = {click: (): void => { clicks.push('mobile'); }};
+ const root = {
+ querySelector(selector: string): {click(): void} | null {
+ if (selector === '[data-cs-docs-search-primary] [data-open-modal]') return headerBtn;
+ if (selector === '[data-open-modal]') return mobileBtn;
+ return null;
+ },
+ };
+ assert.equal(openPrimaryDocsSearch(root), true);
+ assert.equal(clicks, ['header']);
+});
diff --git a/src/components/searchDialog.ts b/src/components/searchDialog.ts
new file mode 100644
index 0000000..7e4c13e
--- /dev/null
+++ b/src/components/searchDialog.ts
@@ -0,0 +1,54 @@
+export type SlashKeyEvent = {
+ key: string;
+ metaKey: boolean;
+ ctrlKey: boolean;
+ altKey: boolean;
+ shiftKey: false | boolean;
+ anySearchDialogOpen: boolean;
+ targetIsEditable: boolean;
+};
+
+export type EditableTarget = {
+ tagName: string;
+ isContentEditable: boolean;
+};
+
+export function isEditableSearchTarget(el: EditableTarget): boolean {
+ const tag = el.tagName;
+ return tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT' || el.isContentEditable;
+}
+
+/** `/` opens search. Ignore when a search dialog is already open or the user is typing. */
+export function shouldHandleGlobalSlash(event: SlashKeyEvent): boolean {
+ if (event.key !== '/') return false;
+ if (event.metaKey || event.ctrlKey || event.altKey || event.shiftKey) return false;
+ if (event.anySearchDialogOpen) return false;
+ if (event.targetIsEditable) return false;
+ return true;
+}
+
+/** First Escape closes the dialog β do not let Pagefind only clear the query. */
+export function shouldCloseSearchOnEscape(key: string): boolean {
+ return key === 'Escape';
+}
+
+export function shouldCloseOnOutsideClick(opts: {
+ targetIsLink: boolean;
+ targetInDocument: boolean;
+ targetInDialogFrame: boolean;
+}): boolean {
+ if (opts.targetIsLink) return true;
+ return opts.targetInDocument && !opts.targetInDialogFrame;
+}
+
+export type SearchOpenRoot = {
+ querySelector(selector: string): {click(): void} | null;
+};
+
+/** Mobile drawer trigger opens the header dialog β never a second Pagefind UI. */
+export function openPrimaryDocsSearch(root: SearchOpenRoot): boolean {
+ const btn = root.querySelector('[data-cs-docs-search-primary] [data-open-modal]');
+ if (!btn) return false;
+ btn.click();
+ return true;
+}
diff --git a/src/components/searchIdleState.spec.ts b/src/components/searchIdleState.spec.ts
new file mode 100644
index 0000000..c5960a4
--- /dev/null
+++ b/src/components/searchIdleState.spec.ts
@@ -0,0 +1,29 @@
+import {test} from 'kizu';
+import {isSearchIdle} from './searchIdleState.js';
+
+test('idle when search is ready and query is empty or shorter than 3 characters', (assert) => {
+ assert.equal(isSearchIdle(true, true, ''), true);
+ assert.equal(isSearchIdle(true, true, ' '), true);
+ assert.equal(
+ isSearchIdle(true, true, 'te'),
+ true,
+ 'queries under 3 characters stay on idle chips',
+ );
+ assert.equal(
+ isSearchIdle(true, false, 'te'),
+ true,
+ 'short queries stay idle even if Pagefind left the drawer open',
+ );
+ assert.equal(
+ isSearchIdle(true, true, 'mcp'),
+ false,
+ 'typing during debounce is not idle',
+ );
+ assert.equal(isSearchIdle(true, false, ''), false);
+ assert.equal(isSearchIdle(true, false, 'mcp'), false);
+ assert.equal(
+ isSearchIdle(false, true, ''),
+ false,
+ 'Pagefind not ready yet β show loading, not idle chips',
+ );
+});
diff --git a/src/components/searchIdleState.ts b/src/components/searchIdleState.ts
new file mode 100644
index 0000000..1408b74
--- /dev/null
+++ b/src/components/searchIdleState.ts
@@ -0,0 +1,24 @@
+/**
+ * Pagefind keeps the results drawer hidden during debounce even after the
+ * input has text. Treat that as βtypingβ, not idle β otherwise suggestion
+ * chips stay visible under an active query.
+ *
+ * Also require searchReady so the idle panel never replaces the loading
+ * skeleton before Pagefind mounts. Queries shorter than 3 characters stay
+ * idle β Pagefind does not search until then.
+ */
+import {DOCS_SEARCH_MIN_QUERY_LENGTH} from './docsSearchQuery.js';
+
+export function isSearchIdle(
+ searchReady: boolean,
+ drawerHidden: boolean,
+ query: string,
+): boolean {
+ if (!searchReady) return false;
+
+ const trimmed = query.trim();
+ if (trimmed.length === 0) return drawerHidden;
+ if (trimmed.length < DOCS_SEARCH_MIN_QUERY_LENGTH) return true;
+
+ return false;
+}
diff --git a/src/components/searchKeyboardNav.spec.ts b/src/components/searchKeyboardNav.spec.ts
new file mode 100644
index 0000000..1ae8b40
--- /dev/null
+++ b/src/components/searchKeyboardNav.spec.ts
@@ -0,0 +1,337 @@
+import {test} from 'kizu';
+import {
+ activateSearchNavItem,
+ applySelection,
+ collectResultNavItems,
+ collectResultRows,
+ handleSearchKey,
+ markAwaitingFreshResults,
+ nextIndex,
+ resetSearchNavSession,
+ resolveKeyboardSelection,
+ resultLinkForRow,
+ scrollSearchSelectionIntoView,
+ shouldHandleSearchListKeyboard,
+ type KeyboardNavState,
+} from './searchKeyboardNav.js';
+
+test('resetSearchNavSession clears highlight and scroll for a new dialog open', (assert) => {
+ const selected = stubEl();
+ selected.setAttribute('data-cs-search-selected', 'true');
+ const scroller = {scrollTop: 480};
+ const root = {
+ querySelector(selector: string): {scrollTop: number} | null {
+ return selector === '.pagefind-ui__results-area' ? scroller : null;
+ },
+ querySelectorAll(selector: string): Element[] {
+ return selector === '[data-cs-search-selected]' ? [selected] : [];
+ },
+ } as unknown as ParentNode;
+
+ const next = resetSearchNavSession(root);
+ assert.equal(next.selectedIndex, -1);
+ assert.equal(next.lastFingerprint, '');
+ assert.equal(next.awaitingFreshResults, false);
+ assert.equal(next.userMovedResults, false);
+ assert.equal(selected.getAttribute('data-cs-search-selected'), null);
+ assert.equal(scroller.scrollTop, 0);
+});
+
+test('nextIndex clamps without wrapping', (assert) => {
+ assert.equal(nextIndex(0, -1, 3), 0);
+ assert.equal(nextIndex(2, 1, 3), 2);
+ assert.equal(nextIndex(1, 1, 3), 2);
+ assert.equal(nextIndex(1, -1, 3), 0);
+ assert.equal(nextIndex(0, 1, 0), -1, 'empty list stays unselected');
+});
+
+test('nextIndex from -1 enters at first or last', (assert) => {
+ assert.equal(nextIndex(-1, 1, 4), 0);
+ assert.equal(nextIndex(-1, -1, 4), 3);
+});
+
+test('applySelection sets data-cs-search-selected on one item', (assert) => {
+ const items = [stubEl(), stubEl(), stubEl()];
+ applySelection(items, 1);
+ assert.equal(items[0]?.getAttribute('data-cs-search-selected'), null);
+ assert.equal(items[1]?.getAttribute('data-cs-search-selected'), 'true');
+ assert.equal(items[2]?.getAttribute('data-cs-search-selected'), null);
+
+ applySelection(items, -1);
+ assert.equal(items[1]?.getAttribute('data-cs-search-selected'), null);
+});
+
+test('handleSearchKey moves selection with arrows and activates on Enter', (assert) => {
+ assert.equal(handleSearchKey('ArrowDown', -1, 3), {
+ preventDefault: true,
+ selectedIndex: 0,
+ activate: false,
+ });
+ assert.equal(handleSearchKey('ArrowUp', -1, 3), {
+ preventDefault: true,
+ selectedIndex: 2,
+ activate: false,
+ });
+ assert.equal(handleSearchKey('ArrowDown', 0, 3), {
+ preventDefault: true,
+ selectedIndex: 1,
+ activate: false,
+ });
+ assert.equal(handleSearchKey('Enter', 1, 3), {
+ preventDefault: true,
+ selectedIndex: 1,
+ activate: true,
+ });
+ assert.equal(handleSearchKey('Enter', -1, 3), {
+ preventDefault: false,
+ selectedIndex: -1,
+ activate: false,
+ });
+ assert.equal(handleSearchKey('a', 1, 3), {
+ preventDefault: false,
+ selectedIndex: 1,
+ activate: false,
+ });
+});
+
+test('shouldHandleSearchListKeyboard only when the search input is focused', (assert) => {
+ const input = {tagName: 'INPUT'} as Element;
+ const clear = {tagName: 'BUTTON'} as Element;
+ assert.equal(shouldHandleSearchListKeyboard(input, input), true);
+ assert.equal(shouldHandleSearchListKeyboard(clear, input), false);
+ assert.equal(shouldHandleSearchListKeyboard(null, input), false);
+ assert.equal(shouldHandleSearchListKeyboard(input, null), false);
+});
+
+test('awaiting stays blocked until fingerprint changes or search cycle completes', (assert) => {
+ const afterType = markAwaitingFreshResults({
+ selectedIndex: 0,
+ lastFingerprint: 'results:a',
+ awaitingFreshResults: false,
+ sawSearchingWhileAwaiting: false,
+ });
+ assert.equal(afterType.selectedIndex, -1);
+ assert.equal(afterType.awaitingFreshResults, true);
+
+ const stillStale = resolveKeyboardSelection(afterType, 'results', 'results:a', 2, false);
+ assert.equal(stillStale.selectedIndex, -1);
+ assert.equal(stillStale.awaitingFreshResults, false, 'live hits settle even without a searching phase');
+
+ const awaitingNoHits = markAwaitingFreshResults({
+ selectedIndex: 0,
+ lastFingerprint: 'results:a',
+ awaitingFreshResults: false,
+ sawSearchingWhileAwaiting: false,
+ });
+ const stillLoading = resolveKeyboardSelection(awaitingNoHits, 'results', 'results:a', 0, false);
+ assert.equal(stillLoading.awaitingFreshResults, true, 'still awaiting when live rows are not ready');
+
+ const searching = resolveKeyboardSelection(stillLoading, 'results', 'results:a', 2, true);
+ assert.equal(searching.awaitingFreshResults, true);
+ assert.equal(searching.sawSearchingWhileAwaiting, true);
+ assert.equal(searching.selectedIndex, -1);
+
+ const sameHits = resolveKeyboardSelection(searching, 'results', 'results:a', 2, false);
+ assert.equal(sameHits.awaitingFreshResults, false);
+ assert.equal(sameHits.selectedIndex, -1);
+
+ const afterType2 = markAwaitingFreshResults(sameHits);
+ const fresh = resolveKeyboardSelection(afterType2, 'results', 'results:b', 2, false);
+ assert.equal(fresh.selectedIndex, -1);
+ assert.equal(fresh.awaitingFreshResults, false);
+});
+
+test('fast same-hit search clears awaiting when live rows return', (assert) => {
+ const awaiting = markAwaitingFreshResults({
+ selectedIndex: 1,
+ lastFingerprint: 'results:a',
+ awaitingFreshResults: false,
+ sawSearchingWhileAwaiting: false,
+ userMovedResults: true,
+ });
+ const settled = resolveKeyboardSelection(awaiting, 'results', 'results:a', 4, false);
+ assert.equal(settled.awaitingFreshResults, false);
+ assert.equal(settled.selectedIndex, -1);
+ assert.equal(handleSearchKey('ArrowDown', settled.selectedIndex, 4).selectedIndex, 0);
+});
+test('fresh results stay unselected until arrow keys move selection', (assert) => {
+ const state = markAwaitingFreshResults({
+ selectedIndex: -1,
+ lastFingerprint: '',
+ awaitingFreshResults: false,
+ sawSearchingWhileAwaiting: false,
+ });
+ const resolved = resolveKeyboardSelection(state, 'results', 'results:x', 5, false);
+ assert.equal(resolved.selectedIndex, -1);
+ assert.equal(handleSearchKey('ArrowDown', resolved.selectedIndex, 5).selectedIndex, 0);
+});
+
+test('hydration fingerprint changes keep the current selection', (assert) => {
+ const state: KeyboardNavState = {
+ selectedIndex: 1,
+ lastFingerprint: 'results:a',
+ awaitingFreshResults: false,
+ sawSearchingWhileAwaiting: false,
+ userMovedResults: true,
+ };
+ const hydrated = resolveKeyboardSelection(state, 'results', 'results:a\0b', 2, false);
+ assert.equal(hydrated.selectedIndex, 1);
+ assert.equal(hydrated.awaitingFreshResults, false);
+});
+
+test('scrollSearchSelectionIntoView resets drawer scroll for the first row', (assert) => {
+ const scroller = {scrollTop: 240};
+ const root = {
+ querySelector(selector: string): {scrollTop: number} | null {
+ return selector === '.pagefind-ui__results-area' ? scroller : null;
+ },
+ };
+ const item = {
+ scrollIntoView(): void {
+ assert.fail('first row should reset drawer scroll instead of nearest');
+ },
+ };
+
+ scrollSearchSelectionIntoView(root, 0, item as unknown as HTMLElement, 3);
+ assert.equal(scroller.scrollTop, 0);
+});
+
+test('scrollSearchSelectionIntoView uses end alignment for the last item', (assert) => {
+ const scroller = {scrollTop: 0};
+ const root = {
+ querySelector(): {scrollTop: number} {
+ return scroller;
+ },
+ };
+ let block: ScrollLogicalPosition | undefined;
+ const item = {
+ scrollIntoView(options?: ScrollIntoViewOptions): void {
+ block = options?.block;
+ },
+ };
+
+ scrollSearchSelectionIntoView(root, 2, item as unknown as HTMLElement, 3);
+ assert.equal(block, 'end');
+});
+
+test('scrollSearchSelectionIntoView uses nearest for middle rows', (assert) => {
+ const scroller = {scrollTop: 0};
+ const root = {
+ querySelector(): {scrollTop: number} {
+ return scroller;
+ },
+ };
+ let scrolled = false;
+ const item = {
+ scrollIntoView(options?: ScrollIntoViewOptions): void {
+ scrolled = true;
+ assert.equal(options?.block, 'nearest');
+ },
+ };
+
+ scrollSearchSelectionIntoView(root, 2, item as unknown as HTMLElement, 5);
+ assert.equal(scrolled, true);
+ assert.equal(scroller.scrollTop, 0);
+});
+
+test('collectResultNavItems appends load more after result rows', (assert) => {
+ const loadMore = {
+ classList: {contains: (c: string): boolean => c === 'pagefind-ui__button'},
+ closest: (): null => null,
+ click(): void {},
+ };
+ const root = {
+ querySelector(selector: string): typeof loadMore | null {
+ if (selector === '.pagefind-ui__button') return loadMore;
+ return null;
+ },
+ querySelectorAll(selector: string): HTMLElement[] {
+ if (selector.includes('pagefind-ui__result-title')) {
+ return [stubRow('a'), stubRow('b')] as unknown as HTMLElement[];
+ }
+ return [];
+ },
+ };
+ const items = collectResultNavItems(root as unknown as ParentNode);
+ assert.equal(items.length, 3);
+ assert.equal(items[2], loadMore);
+});
+
+test('handleSearchKey reaches load more after the last result row', (assert) => {
+ assert.equal(handleSearchKey('ArrowDown', 1, 3), {
+ preventDefault: true,
+ selectedIndex: 2,
+ activate: false,
+ });
+});
+
+test('activateSearchNavItem clicks load more', (assert) => {
+ let clicked = false;
+ const button = {
+ classList: {contains: (c: string): boolean => c === 'pagefind-ui__button'},
+ click(): void {
+ clicked = true;
+ },
+ };
+ activateSearchNavItem(button as unknown as HTMLElement);
+ assert.equal(clicked, true);
+});
+
+function stubRow(href: string): {
+ querySelector(selector: string): {href: string} | null;
+} {
+ return {
+ querySelector(selector: string): {href: string} | null {
+ return selector === 'a.pagefind-ui__result-link' ? {href} : null;
+ },
+ };
+}
+
+function stubEl(): {
+ setAttribute(name: string, value: string): void;
+ removeAttribute(name: string): void;
+ getAttribute(name: string): string | null;
+} {
+ const attrs = new Map();
+ return {
+ setAttribute(name: string, value: string): void {
+ attrs.set(name, value);
+ },
+ removeAttribute(name: string): void {
+ attrs.delete(name);
+ },
+ getAttribute(name: string): string | null {
+ return attrs.has(name) ? (attrs.get(name) ?? null) : null;
+ },
+ };
+}
+
+test('collectResultRows skips rows inside stale snapshot hosts', (assert) => {
+ const live = stubEl();
+ live.className = 'pagefind-ui__result-title';
+ const liveLink = {getAttribute: () => '/live'} as HTMLAnchorElement;
+ live.querySelector = (selector: string): HTMLAnchorElement | null =>
+ selector === 'a.pagefind-ui__result-link' ? liveLink : null;
+
+ const staleRow = stubEl();
+ staleRow.className = 'pagefind-ui__result-nested';
+ const staleLink = {getAttribute: () => '/stale'} as HTMLAnchorElement;
+ staleRow.querySelector = (selector: string): HTMLAnchorElement | null =>
+ selector === 'a.pagefind-ui__result-link' ? staleLink : null;
+ staleRow.closest = (selector: string): Element | null =>
+ selector === '[data-cs-search-stale]' ? ({} as Element) : null;
+
+ live.closest = (): null => null;
+
+ const root = {
+ querySelectorAll(selector: string): HTMLElement[] {
+ if (selector.includes('pagefind-ui__result-title')) return [live];
+ if (selector.includes('pagefind-ui__result-nested')) return [staleRow];
+ return [];
+ },
+ } as unknown as ParentNode;
+
+ const rows = collectResultRows(root);
+ assert.equal(rows.length, 1);
+ assert.equal(resultLinkForRow(rows[0]!)?.getAttribute('href'), '/live');
+});
diff --git a/src/components/searchKeyboardNav.ts b/src/components/searchKeyboardNav.ts
new file mode 100644
index 0000000..7ffdbe8
--- /dev/null
+++ b/src/components/searchKeyboardNav.ts
@@ -0,0 +1,318 @@
+/** Attribute used for keyboard-selected search rows / idle chips. */
+const SEARCH_SELECTED_ATTR = 'data-cs-search-selected';
+
+export const INITIAL_KEYBOARD_NAV_STATE: KeyboardNavState = {
+ selectedIndex: -1,
+ lastFingerprint: '',
+ awaitingFreshResults: false,
+ sawSearchingWhileAwaiting: false,
+ userMovedResults: false,
+};
+
+export type SelectableItem = {
+ setAttribute(name: string, value: string): void;
+ removeAttribute(name: string): void;
+};
+
+export type SearchKeyResult = {
+ preventDefault: boolean;
+ selectedIndex: number;
+ activate: boolean;
+};
+
+/**
+ * Clamp selection within `[0, length)`. From `-1`, β β first, β β last.
+ * Empty list always returns `-1`.
+ */
+export function nextIndex(current: number, delta: number, length: number): number {
+ if (length <= 0) return -1;
+ if (current < 0) return delta > 0 ? 0 : length - 1;
+ const next = current + delta;
+ if (next < 0) return 0;
+ if (next >= length) return length - 1;
+ return next;
+}
+
+/** Mark exactly one item as selected (or none when index is out of range). */
+export function applySelection(items: SelectableItem[], index: number): void {
+ for (let i = 0; i < items.length; i++) {
+ const item = items[i];
+ if (!item) continue;
+ if (i === index) item.setAttribute(SEARCH_SELECTED_ATTR, 'true');
+ else item.removeAttribute(SEARCH_SELECTED_ATTR);
+ }
+}
+
+export function handleSearchKey(
+ key: string,
+ selectedIndex: number,
+ itemCount: number,
+): SearchKeyResult {
+ if (key === 'ArrowDown') {
+ return {
+ preventDefault: itemCount > 0,
+ selectedIndex: nextIndex(selectedIndex, 1, itemCount),
+ activate: false,
+ };
+ }
+ if (key === 'ArrowUp') {
+ return {
+ preventDefault: itemCount > 0,
+ selectedIndex: nextIndex(selectedIndex, -1, itemCount),
+ activate: false,
+ };
+ }
+ if (key === 'Enter') {
+ const canActivate = selectedIndex >= 0 && selectedIndex < itemCount;
+ return {
+ preventDefault: canActivate,
+ selectedIndex,
+ activate: canActivate,
+ };
+ }
+ return {preventDefault: false, selectedIndex, activate: false};
+}
+
+/** Result-list keys apply only while the query field is focused β not on clear / other controls. */
+export function shouldHandleSearchListKeyboard(
+ activeElement: Element | null,
+ searchInput: Element | null,
+): boolean {
+ return Boolean(searchInput && activeElement === searchInput);
+}
+
+/** Visible Pagefind βload moreβ control, when present. */
+export function collectLoadMoreButton(root: ParentNode): HTMLElement | null {
+ const button = root.querySelector('.pagefind-ui__button');
+ if (!button || button.closest('.pagefind-ui__hidden')) return null;
+ return button;
+}
+
+/** Result rows plus load-more when Pagefind shows it. */
+export function collectResultNavItems(root: ParentNode): HTMLElement[] {
+ const rows = collectResultRows(root);
+ const loadMore = collectLoadMoreButton(root);
+ return loadMore ? [...rows, loadMore] : rows;
+}
+
+export function isLoadMoreButton(item: HTMLElement): boolean {
+ return item.classList.contains('pagefind-ui__button');
+}
+
+export function activateSearchNavItem(item: HTMLElement): void {
+ if (isLoadMoreButton(item)) {
+ item.click();
+ return;
+ }
+ resultLinkForRow(item)?.click();
+}
+
+/** Page title / nested rows that already have a navigable link (skip placeholders). */
+export function collectResultRows(root: ParentNode): HTMLElement[] {
+ return Array.from(
+ root.querySelectorAll(
+ '.pagefind-ui__result-title:not(:where(.pagefind-ui__result-nested *)), .pagefind-ui__result-nested',
+ ),
+ ).filter((row) => resultLinkForRow(row) !== null && !row.closest?.('[data-cs-search-stale]'));
+}
+
+/** Idle suggestion chips. */
+export function collectSuggestionChips(root: ParentNode): HTMLElement[] {
+ return Array.from(root.querySelectorAll('[data-cs-search-suggestion]'));
+}
+
+export function resultLinkForRow(row: HTMLElement): HTMLAnchorElement | null {
+ return row.querySelector('a.pagefind-ui__result-link');
+}
+
+/** Scroll container for Pagefind hits (results-area when present, else drawer). */
+export function findSearchResultsScroller(root: ParentNode): HTMLElement | null {
+ return (
+ root.querySelector('.pagefind-ui__results-area') ??
+ root.querySelector('.pagefind-ui__drawer')
+ );
+}
+
+/**
+ * Keep keyboard selection visible. Index 0 scrolls the drawer flush to the top so
+ * the match count and first row are fully shown β `nearest` leaves a stale offset.
+ */
+export function scrollSearchSelectionIntoView(
+ root: ParentNode,
+ selectedIndex: number,
+ item: HTMLElement | undefined,
+ itemCount: number,
+): void {
+ if (selectedIndex === 0) {
+ const scroller = findSearchResultsScroller(root);
+ if (scroller) {
+ scroller.scrollTop = 0;
+ return;
+ }
+ }
+ if (item && selectedIndex === itemCount - 1) {
+ item.scrollIntoView({block: 'end'});
+ return;
+ }
+ item?.scrollIntoView({block: 'nearest'});
+}
+
+/** Strip keyboard highlight from a prior modal session. */
+export function clearSearchSelection(root: ParentNode): void {
+ for (const el of Array.from(root.querySelectorAll(`[${SEARCH_SELECTED_ATTR}]`))) {
+ el.removeAttribute(SEARCH_SELECTED_ATTR);
+ }
+}
+
+/** Pagefind keeps results mounted while the dialog is closed β reset scroll position. */
+export function resetSearchResultsScroll(root: ParentNode): void {
+ const scroller = findSearchResultsScroller(root);
+ if (scroller) scroller.scrollTop = 0;
+}
+
+/** Fresh keyboard-nav state when the search dialog closes or reopens. */
+export function resetSearchNavSession(root: ParentNode): KeyboardNavState {
+ clearSearchSelection(root);
+ resetSearchResultsScroll(root);
+ return {...INITIAL_KEYBOARD_NAV_STATE};
+}
+
+export type KeyboardNavMode = 'idle' | 'results' | 'other';
+
+export type KeyboardNavState = {
+ selectedIndex: number;
+ lastFingerprint: string;
+ /** True after the query changes until fresh results are accepted. */
+ awaitingFreshResults: boolean;
+ /** True if Pagefind showed a searching state while awaiting. */
+ sawSearchingWhileAwaiting: boolean;
+ /** True after β/β in the results list β blocks auto-highlight on fresh hits. */
+ userMovedResults: boolean;
+};
+
+export function markAwaitingFreshResults(state: KeyboardNavState): KeyboardNavState {
+ return {
+ ...state,
+ awaitingFreshResults: true,
+ selectedIndex: -1,
+ sawSearchingWhileAwaiting: false,
+ userMovedResults: false,
+ };
+}
+
+/**
+ * Updates selection when the dialog mode / result list fingerprint changes.
+ * While awaiting, selection stays cleared until either the href fingerprint changes
+ * or a searchingβidle cycle completes (same hits after an edit).
+ */
+export function resolveKeyboardSelection(
+ state: KeyboardNavState,
+ mode: KeyboardNavMode,
+ fingerprint: string,
+ itemCount: number,
+ isSearching: boolean,
+): KeyboardNavState {
+ if (mode === 'other') {
+ return {
+ selectedIndex: -1,
+ lastFingerprint: fingerprint,
+ awaitingFreshResults: false,
+ sawSearchingWhileAwaiting: false,
+ userMovedResults: false,
+ };
+ }
+
+ if (mode === 'idle') {
+ if (fingerprint !== state.lastFingerprint) {
+ return {
+ selectedIndex: -1,
+ lastFingerprint: fingerprint,
+ awaitingFreshResults: false,
+ sawSearchingWhileAwaiting: false,
+ userMovedResults: false,
+ };
+ }
+ return {
+ ...state,
+ awaitingFreshResults: false,
+ sawSearchingWhileAwaiting: false,
+ userMovedResults: false,
+ selectedIndex: clampIndex(state.selectedIndex, itemCount),
+ };
+ }
+
+ const sawSearching =
+ state.sawSearchingWhileAwaiting || (state.awaitingFreshResults && isSearching);
+
+ const clearResultsNav = {
+ selectedIndex: -1,
+ userMovedResults: false,
+ };
+
+ // results (including in-flight querying, which still uses this mode)
+ if (fingerprint !== state.lastFingerprint) {
+ if (state.awaitingFreshResults || !state.userMovedResults) {
+ return {
+ ...clearResultsNav,
+ lastFingerprint: fingerprint,
+ awaitingFreshResults: false,
+ sawSearchingWhileAwaiting: false,
+ };
+ }
+ return {
+ selectedIndex: clampIndex(state.selectedIndex, itemCount),
+ lastFingerprint: fingerprint,
+ awaitingFreshResults: false,
+ sawSearchingWhileAwaiting: false,
+ userMovedResults: true,
+ };
+ }
+
+ if (state.awaitingFreshResults) {
+ // Fast searches may never show a searching state β accept once live hits are back.
+ if (!isSearching && itemCount > 0) {
+ return {
+ ...clearResultsNav,
+ lastFingerprint: fingerprint,
+ awaitingFreshResults: false,
+ sawSearchingWhileAwaiting: false,
+ };
+ }
+
+ // Same hits after a visible searching cycle (query tweak, identical results).
+ if (sawSearching && !isSearching) {
+ return {
+ ...clearResultsNav,
+ lastFingerprint: fingerprint,
+ awaitingFreshResults: false,
+ sawSearchingWhileAwaiting: false,
+ };
+ }
+ return {
+ ...state,
+ ...clearResultsNav,
+ sawSearchingWhileAwaiting: sawSearching,
+ };
+ }
+
+ if (!state.userMovedResults) {
+ return {
+ ...state,
+ selectedIndex: -1,
+ sawSearchingWhileAwaiting: false,
+ };
+ }
+
+ return {
+ ...state,
+ selectedIndex: clampIndex(state.selectedIndex, itemCount),
+ sawSearchingWhileAwaiting: false,
+ };
+}
+
+function clampIndex(selectedIndex: number, itemCount: number): number {
+ if (itemCount <= 0) return -1;
+ if (selectedIndex < 0) return selectedIndex;
+ if (selectedIndex >= itemCount) return itemCount - 1;
+ return selectedIndex;
+}
diff --git a/src/components/searchPendingDelay.spec.ts b/src/components/searchPendingDelay.spec.ts
new file mode 100644
index 0000000..1f6f483
--- /dev/null
+++ b/src/components/searchPendingDelay.spec.ts
@@ -0,0 +1,34 @@
+import {test} from 'kizu';
+import {
+ INITIAL_SEARCH_PENDING_DELAY_STATE,
+ resolveSearchPendingDelayState,
+ shouldShowSearchPending,
+} from './searchPendingDelay.js';
+
+test('shouldShowSearchPending only while searching with no settled results', (assert) => {
+ assert.equal(shouldShowSearchPending('searching', false, false), true);
+ assert.equal(shouldShowSearchPending('searching', false, false, false), true);
+ assert.equal(shouldShowSearchPending('querying', false, false), false);
+ assert.equal(shouldShowSearchPending('searching', true, false), false);
+ assert.equal(shouldShowSearchPending('searching', false, true), false);
+ assert.equal(shouldShowSearchPending('results', false, false), false);
+ assert.equal(shouldShowSearchPending('searching', false, false, true), false);
+});
+
+test('resolveSearchPendingDelayState hides immediately when search settles', (assert) => {
+ const armed = resolveSearchPendingDelayState(INITIAL_SEARCH_PENDING_DELAY_STATE, true, false);
+ assert.equal(armed.armed, true);
+ assert.equal(armed.visible, false);
+
+ const visible = resolveSearchPendingDelayState(armed, true, true);
+ assert.equal(visible.visible, true);
+
+ const hidden = resolveSearchPendingDelayState(visible, false, false);
+ assert.equal(hidden, INITIAL_SEARCH_PENDING_DELAY_STATE);
+});
+
+test('resolveSearchPendingDelayState stays visible once shown until cleared', (assert) => {
+ const visible = {armed: false, visible: true};
+ const still = resolveSearchPendingDelayState(visible, true, false);
+ assert.equal(still.visible, true);
+});
diff --git a/src/components/searchPendingDelay.ts b/src/components/searchPendingDelay.ts
new file mode 100644
index 0000000..ab4ce46
--- /dev/null
+++ b/src/components/searchPendingDelay.ts
@@ -0,0 +1,41 @@
+/** Wait before showing the skeleton so fast searches do not flash placeholder chrome. */
+export const SEARCH_PENDING_SHOW_DELAY_MS = 180;
+
+/** Skeleton while Pagefind is searching and the drawer has no hits yet. */
+export function shouldShowSearchPending(
+ phase: string,
+ hasResults: boolean,
+ zeroResults: boolean,
+ holdingStale = false,
+): boolean {
+ if (hasResults || zeroResults || holdingStale) return false;
+ return phase === 'searching';
+}
+
+export type SearchPendingDelayState = {
+ armed: boolean;
+ visible: boolean;
+};
+
+export const INITIAL_SEARCH_PENDING_DELAY_STATE: SearchPendingDelayState = {
+ armed: false,
+ visible: false,
+};
+
+/** Pure delay gate β `delayElapsed` is true once the timer fires. */
+export function resolveSearchPendingDelayState(
+ state: SearchPendingDelayState,
+ wantShow: boolean,
+ delayElapsed: boolean,
+): SearchPendingDelayState {
+ if (!wantShow) {
+ return INITIAL_SEARCH_PENDING_DELAY_STATE;
+ }
+ if (state.visible) {
+ return state;
+ }
+ if (delayElapsed) {
+ return {armed: false, visible: true};
+ }
+ return {armed: true, visible: false};
+}
diff --git a/src/components/searchStaleResults.spec.ts b/src/components/searchStaleResults.spec.ts
new file mode 100644
index 0000000..4bfc843
--- /dev/null
+++ b/src/components/searchStaleResults.spec.ts
@@ -0,0 +1,62 @@
+import {test} from 'kizu';
+import {
+ beginStaleResultsHold,
+ INITIAL_STALE_RESULTS_STATE,
+ resolveStaleResultsHold,
+ shouldDiscardStaleResults,
+ shouldShowStaleResults,
+} from './searchStaleResults.js';
+
+test('shouldShowStaleResults only while holding a snapshot and live results are gone', (assert) => {
+ assert.equal(shouldShowStaleResults(true, false, true, true, false, false), true);
+ assert.equal(shouldShowStaleResults(true, false, false, true, false, false), false);
+ assert.equal(shouldShowStaleResults(true, true, true, true, false, false), false);
+ assert.equal(shouldShowStaleResults(false, false, true, true, false, false), false);
+ assert.equal(shouldShowStaleResults(true, false, true, false, false, false), false);
+ assert.equal(shouldShowStaleResults(true, false, true, true, true, false), false);
+ assert.equal(shouldShowStaleResults(true, false, true, true, false, true), false);
+});
+
+test('shouldDiscardStaleResults when the field resets or search settles empty', (assert) => {
+ assert.equal(shouldDiscardStaleResults(false, false, true), false);
+ assert.equal(shouldDiscardStaleResults(true, false, true), true);
+ assert.equal(shouldDiscardStaleResults(false, true, true), true);
+ assert.equal(shouldDiscardStaleResults(false, false, false), true);
+});
+
+test('beginStaleResultsHold records the live fingerprint', (assert) => {
+ const empty = beginStaleResultsHold(INITIAL_STALE_RESULTS_STATE, '');
+ assert.equal(empty.holding, false);
+
+ const held = beginStaleResultsHold(INITIAL_STALE_RESULTS_STATE, 'a\0b');
+ assert.equal(held.holding, true);
+ assert.equal(held.capturedFingerprint, 'a\0b');
+ assert.equal(held.sawSearchingWhileHolding, false);
+});
+
+test('resolveStaleResultsHold keeps the snapshot until fresh hits land', (assert) => {
+ const holding = beginStaleResultsHold(INITIAL_STALE_RESULTS_STATE, 'a\0b');
+
+ const stillLive = resolveStaleResultsHold(holding, true, 'a\0b', false, false);
+ assert.equal(stillLive.holding, true);
+ assert.equal(stillLive.capturedFingerprint, 'a\0b');
+
+ const clearedLive = resolveStaleResultsHold(holding, false, '', false, false);
+ assert.equal(clearedLive.holding, true);
+ assert.equal(clearedLive.capturedFingerprint, 'a\0b');
+
+ const replaced = resolveStaleResultsHold(holding, true, 'c', false, false);
+ assert.equal(replaced.holding, false);
+
+ const settled = resolveStaleResultsHold(
+ {...holding, sawSearchingWhileHolding: true},
+ true,
+ 'a\0b',
+ false,
+ false,
+ );
+ assert.equal(settled.holding, false);
+
+ const discarded = resolveStaleResultsHold(holding, false, '', false, true);
+ assert.equal(discarded.holding, false);
+});
diff --git a/src/components/searchStaleResults.ts b/src/components/searchStaleResults.ts
new file mode 100644
index 0000000..a6f10c4
--- /dev/null
+++ b/src/components/searchStaleResults.ts
@@ -0,0 +1,126 @@
+export type StaleResultsState = {
+ /** Snapshot kept until Pagefind replaces the live list. */
+ holding: boolean;
+ /** Live-result href fingerprint when the snapshot was taken. */
+ capturedFingerprint: string;
+ /** True once Pagefind shows a searching state while holding. */
+ sawSearchingWhileHolding: boolean;
+};
+
+export const INITIAL_STALE_RESULTS_STATE: StaleResultsState = {
+ holding: false,
+ capturedFingerprint: '',
+ sawSearchingWhileHolding: false,
+};
+
+/** Show the last snapshot while a new query is in flight and Pagefind cleared the live list. */
+export function shouldShowStaleResults(
+ hasStaleSnapshot: boolean,
+ hasLiveResults: boolean,
+ holding: boolean,
+ queryReady: boolean,
+ idle: boolean,
+ zeroResults: boolean,
+): boolean {
+ if (!hasStaleSnapshot || !holding || hasLiveResults || !queryReady || idle || zeroResults) {
+ return false;
+ }
+ return true;
+}
+
+export function liveResultsFingerprint(root: Element): string {
+ const rows = root.querySelectorAll('.pagefind-ui__results > .pagefind-ui__result');
+ return Array.from(rows)
+ .map((row) => row.querySelector('a.pagefind-ui__result-link')?.getAttribute('href') ?? '')
+ .join('\0');
+}
+
+/** Drop the snapshot when the field resets or a completed search settles. */
+export function shouldDiscardStaleResults(
+ idle: boolean,
+ zeroResults: boolean,
+ queryReady: boolean,
+): boolean {
+ return idle || zeroResults || !queryReady;
+}
+
+export function beginStaleResultsHold(
+ state: StaleResultsState,
+ liveFingerprint: string,
+): StaleResultsState {
+ if (!liveFingerprint) return state;
+ return {
+ holding: true,
+ capturedFingerprint: liveFingerprint,
+ sawSearchingWhileHolding: false,
+ };
+}
+
+export function resolveStaleResultsHold(
+ state: StaleResultsState,
+ hasLiveResults: boolean,
+ liveFingerprint: string,
+ isSearching: boolean,
+ discard: boolean,
+): StaleResultsState {
+ if (!state.holding || discard) return INITIAL_STALE_RESULTS_STATE;
+
+ const sawSearching =
+ state.sawSearchingWhileHolding || (state.holding && isSearching);
+
+ if (!hasLiveResults) {
+ return {...state, sawSearchingWhileHolding: sawSearching};
+ }
+
+ if (liveFingerprint !== state.capturedFingerprint) return INITIAL_STALE_RESULTS_STATE;
+
+ if (sawSearching && !isSearching) return INITIAL_STALE_RESULTS_STATE;
+
+ return {...state, sawSearchingWhileHolding: sawSearching};
+}
+
+/** Mount outside Pagefindβs Svelte-managed results block so loading toggles do not drop it. */
+export function ensureStaleResultsHost(root: Element): HTMLElement | null {
+ const drawer = root.querySelector('.pagefind-ui__drawer');
+ if (!drawer) return null;
+
+ const existing = drawer.querySelector('[data-cs-search-stale]');
+ if (existing) return existing;
+
+ const host = document.createElement('div');
+ host.dataset.csSearchStale = '';
+ host.hidden = true;
+ drawer.insertBefore(host, drawer.firstChild);
+ return host;
+}
+
+export function captureStaleResults(root: Element): boolean {
+ const results = root.querySelector('.pagefind-ui__results');
+ if (!results?.querySelector('.pagefind-ui__result')) return false;
+
+ const host = ensureStaleResultsHost(root);
+ if (!host) return false;
+
+ host.replaceChildren(results.cloneNode(true));
+ return true;
+}
+
+export function clearStaleResults(root: Element): void {
+ const host = root.querySelector('[data-cs-search-stale]');
+ if (!host) return;
+ host.replaceChildren();
+ host.hidden = true;
+}
+
+export function syncStaleResults(root: Element, show: boolean, discard: boolean): void {
+ const host = root.querySelector('[data-cs-search-stale]');
+ if (!host) return;
+
+ if (discard) {
+ host.replaceChildren();
+ host.hidden = true;
+ return;
+ }
+
+ host.hidden = !show || host.childElementCount === 0;
+}
diff --git a/src/components/site-footer.css b/src/components/site-footer.css
new file mode 100644
index 0000000..06958b4
--- /dev/null
+++ b/src/components/site-footer.css
@@ -0,0 +1,52 @@
+.site-footer {
+ display: flex;
+ flex-wrap: wrap;
+ align-items: center;
+ justify-content: space-between;
+ gap: 0.65rem 1.5rem;
+ margin-top: 2.75rem;
+ padding-top: 1.15rem;
+ border-top: 1px solid var(--cs-line, var(--sl-color-hairline));
+}
+
+.site-footer__icon,
+.site-footer__icon svg {
+ display: block;
+ width: 1rem;
+ height: 1rem;
+ flex-shrink: 0;
+}
+
+.site-footer__nav {
+ display: flex;
+ flex-wrap: wrap;
+ align-items: center;
+ gap: 0.35rem 1.15rem;
+}
+
+.site-footer__nav a {
+ display: inline-flex;
+ align-items: center;
+ gap: 0.35rem;
+ font-size: 0.9375rem;
+ color: var(--cs-muted, var(--sl-color-gray-3));
+ text-decoration: none;
+}
+
+.site-footer__nav a:hover {
+ color: var(--docs-primary-bg);
+}
+
+.pagination-links + .site-footer {
+ margin-top: 1.75rem;
+}
+
+html:has(.splash-page) .site-footer,
+html:has(.not-found-page) .site-footer {
+ margin-top: 3.25rem;
+ padding-top: 1.35rem;
+}
+
+html:has(.splash-page) .site-footer {
+ border-top: none;
+}
diff --git a/src/components/wrapPagefindSearch.spec.ts b/src/components/wrapPagefindSearch.spec.ts
new file mode 100644
index 0000000..f664380
--- /dev/null
+++ b/src/components/wrapPagefindSearch.spec.ts
@@ -0,0 +1,49 @@
+import {test} from 'kizu';
+import {wrapPagefindSearch} from './wrapPagefindSearch.js';
+
+test('wrapPagefindSearch drops inverted short-prefix hits', async (assert) => {
+ const rawSearch = async (_term: string): Promise<{
+ results: Array<{data: () => Promise<{excerpt?: string; meta?: {title?: string}}>}>;
+ }> => ({
+ results: [
+ {
+ data: async (): Promise<{excerpt: string}> => ({
+ excerpt: 'Fetch from a running server.',
+ }),
+ },
+ {
+ data: async (): Promise<{excerpt: string; meta: {title: string}}> => ({
+ excerpt: 'Enable MCP tools',
+ meta: {title: 'MCP'},
+ }),
+ },
+ ],
+ });
+
+ const search = wrapPagefindSearch(rawSearch);
+ const garbage = await search('adsf');
+ assert.equal(garbage.results.length, 0);
+
+ const useful = await search('mcp');
+ assert.equal(useful.results.length, 1);
+ assert.equal((await useful.results[0]!.data()).meta?.title, 'MCP');
+});
+
+test('wrapPagefindSearch skips Pagefind until query is at least 3 characters', async (assert) => {
+ let calls = 0;
+ const rawSearch = async (): Promise<{results: []}> => {
+ calls += 1;
+ return {results: []};
+ };
+
+ const search = wrapPagefindSearch(rawSearch);
+
+ assert.equal((await search('')).results.length, 0);
+ assert.equal(calls, 0, 'empty query does not hit Pagefind');
+
+ assert.equal((await search('te')).results.length, 0);
+ assert.equal(calls, 0, 'two-character query does not hit Pagefind');
+
+ assert.equal((await search('tes')).results.length, 0);
+ assert.equal(calls, 1, 'three-character query runs Pagefind');
+});
diff --git a/src/components/wrapPagefindSearch.ts b/src/components/wrapPagefindSearch.ts
new file mode 100644
index 0000000..b69cea7
--- /dev/null
+++ b/src/components/wrapPagefindSearch.ts
@@ -0,0 +1,43 @@
+import {isUsefulPagefindMatch, type PagefindMatchData} from './isUsefulPagefindMatch.js';
+import {isDocsSearchQueryReady} from './docsSearchQuery.js';
+
+type PagefindSearchResult = {
+ data: () => Promise;
+};
+
+type PagefindSearchResponse = {
+ results: PagefindSearchResult[];
+ [key: string]: unknown;
+};
+
+type PagefindSearchFn = (
+ term: string,
+ options?: object,
+) => Promise;
+
+/**
+ * Returns a new search function that drops inverted short-prefix hits.
+ * Do not assign over ESM `search` exports β module namespaces are immutable.
+ */
+export function wrapPagefindSearch(rawSearch: PagefindSearchFn): PagefindSearchFn {
+ return async (term, options) => {
+ const query = term?.trim() ?? '';
+ if (!isDocsSearchQueryReady(query)) {
+ return {results: []};
+ }
+
+ try {
+ const res = await rawSearch(term, options);
+ const judged = await Promise.all(
+ res.results.map(async (result) => {
+ const data = await result.data();
+ return isUsefulPagefindMatch(query, data) ? result : null;
+ }),
+ );
+ return {...res, results: judged.filter((result): result is PagefindSearchResult => result !== null)};
+ } catch (err) {
+ console.error('busker docs search failed', err);
+ return {results: []};
+ }
+ };
+}
diff --git a/src/content.config.ts b/src/content.config.ts
new file mode 100644
index 0000000..2542513
--- /dev/null
+++ b/src/content.config.ts
@@ -0,0 +1,9 @@
+import {defineCollection} from 'astro:content';
+import {i18nLoader} from '@astrojs/starlight/loaders';
+import {docsSchema, i18nSchema} from '@astrojs/starlight/schema';
+import {githubFriendlyDocsLoader} from './content/github-friendly-docs-loader';
+
+export const collections = {
+ docs: defineCollection({loader: githubFriendlyDocsLoader(), schema: docsSchema()}),
+ i18n: defineCollection({loader: i18nLoader(), schema: i18nSchema()}),
+};
diff --git a/src/content/docs/api-reference.md b/src/content/docs/api-reference.md
new file mode 100644
index 0000000..13817b2
--- /dev/null
+++ b/src/content/docs/api-reference.md
@@ -0,0 +1,106 @@
+# API reference
+
+```typescript
+import {busk} from 'busker';
+
+const show = busk(root, routine);
+```
+
+## `busk(root, routine)`
+
+Puts on a show inside `root`, an `HTMLElement`. Returns a [`Busker`](#busker). Starts by itself once the root is on screen.
+
+## `Routine`
+
+| Field | Type | Default | What it does |
+|---|---|---|---|
+| `scene` | `string` | none | Scene shown at the top of every loop. |
+| `start` | `[number, number]` | `[0.5, 0.5]` | Where the cursor rests, as a fraction of the root's size. |
+| `steps` | [`Step[]`](#step) | none | A click-driven routine. The loop length comes from it. |
+| `routes` | [`Route[]`](#route) | none | What a click — the cursor's or a visitor's — does. |
+| `duration` | `number` | from `steps` | Loop length in ms. Required if there are no `steps`. |
+| `moves` | [`Move[]`](#move) | none | Hand-timed cursor glides. |
+| `toggles` | [`Toggle[]`](#toggle) | none | Classes held for a slice of the loop. |
+| `typing` | [`Typing[]`](#typing) | none | Text that types itself. |
+| `countdowns` | [`Countdown[]`](#countdown) | none | `m:ss` clocks. |
+| `visibility` | `number` | `1` | How much of the root must be on screen to run, as a fraction. |
+| `freezeAt` | `number` | `0` | Frame to hold under `prefers-reduced-motion`. |
+
+## `Step`
+
+One beat of a click-driven routine. Either a press:
+
+| Field | Type | Default |
+|---|---|---|
+| `click` | `string` | — |
+| `wait` | `number` | `0` |
+| `moveFor` | `number` | `600` |
+| `dwell` | `number` | `250` |
+
+β¦or a drift, which never clicks:
+
+| Field | Type | Default |
+|---|---|---|
+| `to` | `string \| [number, number]` | — |
+| `wait` | `number` | `0` |
+| `moveFor` | `number` | `600` |
+
+Beats run back to back: a step sets off `wait` after the last one finished.
+
+## `Route`
+
+| Field | Type | What it does |
+|---|---|---|
+| `click` | `string` | Selector of the clickable element. |
+| `scene` | `string` | `data-scene` to show when it is clicked. |
+
+Every route target also gets `is-interactive`, which is what makes it look clickable.
+
+## `Move`
+
+A hand-timed glide. See [Hand-timed routines](./timeline.md#moves).
+
+| Field | Type | What it does |
+|---|---|---|
+| `to` | `string \| [number, number]` | Where to glide. |
+| `from` | `number` | When it sets off. |
+| `until` | `number` | When it arrives. |
+| `press` | `number` | Optional. Animates a press. Does **not** click. |
+
+## `Toggle`
+
+| Field | Type | What it does |
+|---|---|---|
+| `target` | `string` | Selector of the element. |
+| `class` | `string` | Class held while the loop is inside `[from, until)`. |
+| `from` | `number` | |
+| `until` | `number` | |
+
+## `Typing`
+
+| Field | Type | What it does |
+|---|---|---|
+| `target` | `string` | Selector. Busker writes its `textContent`. |
+| `text` | `string` | |
+| `from` | `number` | Typing starts. |
+| `until` | `number` | The whole string is on screen. |
+| `clearAt` | `number` | Optional. Wipes it. |
+
+## `Countdown`
+
+| Field | Type | What it does |
+|---|---|---|
+| `target` | `string` | Selector. Busker writes its `textContent`. |
+| `seconds` | `number` | Value at the top of the loop. Stops at zero. |
+
+## `Busker`
+
+| Member | What it does |
+|---|---|
+| `duration` | Loop length in ms, derived from `steps` if you did not give one. |
+| `play()` | Start or resume. A no-op once a visitor has taken over. |
+| `pause()` | Hold where it is. |
+| `stepAside()` | Hand the mock to the visitor: stop for good, hide the cursor. |
+| `destroy()` | Stop everything and remove every class, listener, and observer busker added. |
+
+β [Styling](./styling.md) · Next: [Development](./development.md)
diff --git a/src/content/docs/development.md b/src/content/docs/development.md
new file mode 100644
index 0000000..bfbfde7
--- /dev/null
+++ b/src/content/docs/development.md
@@ -0,0 +1,40 @@
+# Development
+
+```bash
+git clone https://github.com/logfoxai/busker.git
+cd busker
+npm ci
+npm run validate
+```
+
+## Scripts
+
+| Script | What it does |
+|---|---|
+| `npm run build` | `tsc` β `dist/` |
+| `npm test` | [kizu](https://github.com/mhweiner/kizu) specs under c8 coverage |
+| `npm run lint` | `eslint --fix` |
+| `npm run astro:dev` | The docs site at `localhost:4321` |
+| `npm run astro:build` | The docs site β `docs-site/` |
+| `npm run validate` | Everything CI runs, in the same order. Run it before you push. |
+
+## Layout
+
+| Path | What is in it |
+|---|---|
+| `src/timeline.ts` | The pure part: laying a routine out on a timeline, easing, interpolation, text. |
+| `src/busk.ts` | The DOM part: the loop, clicks, observers, and classes. |
+| `src/types.ts` | The public shape of a routine. |
+| `busker.css` | Optional styling, shipped as-is. |
+| `src/content/docs/` | These guides. Same files serve GitHub and the site. |
+| `assets/` | Brand art. Also the docs site's `publicDir`. |
+
+The split is deliberate: everything that can be tested without a DOM lives in `timeline.ts` and is tested exhaustively. `busk.ts` is tested through [happy-dom](https://github.com/capricorn86/happy-dom) with a hand-driven clock, for the behaviours that only exist in a browser — a scripted click not being mistaken for a visitor's, a beat firing exactly once per pass, `destroy()` leaving nothing behind.
+
+## Docs
+
+Guides are plain markdown with a `# Title` and no frontmatter, so they read correctly on GitHub and in the site from the same file. Relative `./page.md` links are rewritten to site slugs at build time.
+
+## Releases
+
+Merges to `main` release through [autorel](https://github.com/mhweiner/autorel): the PR title's conventional-commit type decides the version bump, and the docs site publishes in the same run. Use `feat:` and `fix:` for anything that ships, `docs:` for guides.
diff --git a/src/content/docs/getting-started.md b/src/content/docs/getting-started.md
new file mode 100644
index 0000000..beef149
--- /dev/null
+++ b/src/content/docs/getting-started.md
@@ -0,0 +1,73 @@
+# Getting started
+
+## 1. Install
+
+```bash
+npm i busker
+```
+
+Busker has no dependencies and runs in the browser. It ships types, and works with any framework or none — it only ever touches the element you hand it.
+
+## 2. Write the mock
+
+A mock is ordinary markup. Busker needs three things from it, all `data-` attributes so your class names stay yours:
+
+```html title="index.html"
+
+
+
+
+
Nothing is on fire.
+
+
+
+
Two things are on fire.
+
+
+
+
+```
+
+`[data-scene]` marks each page of the mock, `[data-nav-item]` marks the nav, and `[data-cursor]` is the pointer busker moves. [Markup](./markup.md) has the full contract.
+
+## 3. Put on a show
+
+```typescript title="main.ts"
+import {busk} from 'busker';
+import 'busker/busker.css';
+
+const root = document.querySelector('.app');
+
+if (root) {
+ busk(root, {
+ scene: 'home',
+ steps: [
+ {click: '[data-nav-item="alerts"]', wait: 1200},
+ {click: '[data-nav-item="home"]', wait: 2000},
+ ],
+ routes: [
+ {click: '[data-nav-item="home"]', scene: 'home'},
+ {click: '[data-nav-item="alerts"]', scene: 'alerts'},
+ ],
+ });
+}
+```
+
+That is the whole thing. The cursor glides to the Alerts button, presses it, and the mock changes — because busker really clicks it. There is no separate timeline saying "and at 1.8s, switch to the alerts scene", so there is nothing to fall out of sync when you change a duration.
+
+## 4. Let people play with it
+
+Every selector in `routes` is wired for the visitor too. Click anything the show can click and busker steps aside: the loop stops, the cursor disappears, and the mock is yours. Click something dead and it flashes what *is* clickable.
+
+You get that for free — see [When a visitor takes over](./taking-over.md).
+
+## What busker does not do
+
+- **It does not record or replay.** There is no capture step and no video. The mock is your markup, and the show is a few lines of config.
+- **It does not fake the clicks.** `el.click()` is a real click through your real handlers, so the mock behaves the same whether the cursor pressed the button or a person did.
+- **It does not run off screen.** The loop only runs while the mock is on screen and the tab is in front.
+
+Next: [Markup](./markup.md) · [Click-driven routines](./routines.md)
diff --git a/src/content/docs/markup.md b/src/content/docs/markup.md
new file mode 100644
index 0000000..8199ce5
--- /dev/null
+++ b/src/content/docs/markup.md
@@ -0,0 +1,57 @@
+# Markup
+
+Busker reads your mock through five `data-` attributes and writes back a handful of classes. Nothing else is assumed: no wrapper components, no required class names, no shadow DOM.
+
+## What busker reads
+
+| Attribute | On | What it means |
+|---|---|---|
+| `data-cursor` | one element | The pointer. Busker positions it and shows the press. |
+| `data-scene="home"` | a page of the mock | One is shown at a time. Named in `scene` and in `routes`. |
+| `data-nav="home"` | the same scene element | Which nav item is lit while this scene is up. |
+| `data-nav-item="home"` | a nav button or link | Gets `is-active` when a scene claims it. |
+
+Anything else — rows, buttons, modals, inputs — is just your markup, targeted by whatever selector you like.
+
+## What busker writes
+
+| Class | On | When |
+|---|---|---|
+| `busker` | the root | For as long as busker is running. Everything in `busker.css` hangs off it. |
+| `is-active` | a scene, a nav item | While that scene is the one on screen. |
+| `is-interactive` | every `routes` target | Always. It is what makes clickable things look clickable. |
+| `is-hover` | the current target | From the moment the cursor lands until it sets off again. |
+| `is-pressing` | the cursor | For 200ms as it presses. |
+| `is-ringing` | the cursor | For 500ms — the ripple outlives the press so the click reads. |
+| `is-hint` | every `routes` target | For 1.5s after a visitor clicks something dead. |
+| `is-aside` | the root | Once a visitor has taken over. |
+
+Busker removes all of them on `destroy()`.
+
+## The root element
+
+The root is the element you pass to `busk()`. Two things follow from that:
+
+- **The cursor is positioned against it.** `busker.css` sets `position: relative` on `.busker` for you. If you are writing your own styles, the root needs to be a positioning context.
+- **Visibility is measured on it.** The show runs while the root is on screen, which means the root should be the visible frame of the mock, not a wrapper that is taller than the viewport. See [`visibility`](./api-reference.md#routine) if you want to loosen that.
+
+## Scenes
+
+A scene is one page of the mock. Busker shows one at a time by putting `is-active` on it, and `busker.css` handles the display:
+
+```css
+.busker [data-scene] { display: none; }
+.busker [data-scene].is-active { display: block; }
+```
+
+Override those two rules if you want scenes to cross-fade, slide, or stack.
+
+Scenes never change on a timer. They change because something was clicked — by the cursor or by a visitor — and a [route](./routines.md#routes) said so. That is the whole point: there is one cause, so there is nothing to synchronise.
+
+## The cursor
+
+`[data-cursor]` can be any element. `busker.css` styles it as the soft dot busker's own demos use, sized by `--busker-cursor-size`. To draw your own pointer instead, put an `
+ 
+ 
+
+
+