@twango/twiki 0.0.0-stage → 0.1.0-rc.0

package/site/src/lib/components/popover/link-popovers.ts

@@ -0,0 +1,233 @@
+/** Svelte attachment for cached, anchor-aware previews of internal links. */
+
+import { computePosition, flip, inline, shift } from '@floating-ui/dom';
+import type { Attachment } from 'svelte/attachments';
+import './popover.css';
+
+const SHOW_DELAY_MS = 300;
+const HIDE_DELAY_MS = 150;
+const ANCHOR_SCROLL_OFFSET = 12;
+
+type PopoverContent =
+	| { kind: 'html'; contentType: string; element: HTMLElement }
+	| { kind: 'image'; contentType: string; src: string }
+	| { kind: 'pdf'; contentType: string; src: string };
+
+/** Per-pathname cache of fetched + parsed popover content (module-level: survives navigations). */
+const contentCache = new Map<string, Promise<PopoverContent | null>>();
+
+/**
+ * Rebase relative `href`/`src` attributes of a fetched document against the
+ * target page URL, so links/images inside the popover resolve from the
+ * *current* page. Port of `normalizeRelativeURLs` (quartz/util/path.ts).
+ */
+function normalizeRelativeURLs(root: ParentNode, base: URL): void {
+	const rebase = (el: Element, attr: string) => {
+		const value = el.getAttribute(attr);
+		if (value === null) return;
+		try {
+			const abs = new URL(value, base);
+			el.setAttribute(attr, abs.pathname + abs.search + abs.hash);
+		} catch {
+			/* leave malformed URLs untouched */
+		}
+	};
+	for (const el of root.querySelectorAll('[href=""], [href^="./"], [href^="../"]')) {
+		rebase(el, 'href');
+	}
+	for (const el of root.querySelectorAll('[src=""], [src^="./"], [src^="../"]')) {
+		rebase(el, 'src');
+	}
+}
+
+async function fetchContent(targetUrl: URL): Promise<PopoverContent | null> {
+	const response = await fetch(targetUrl.toString()).catch(() => null);
+	if (!response || !response.ok) return null;
+
+	const contentType = (response.headers.get('Content-Type') ?? '').split(';')[0].trim();
+	if (contentType.startsWith('image/')) {
+		return { kind: 'image', contentType, src: targetUrl.toString() };
+	}
+	if (contentType === 'application/pdf') {
+		return { kind: 'pdf', contentType, src: targetUrl.toString() };
+	}
+	if (!contentType.startsWith('text/html')) return null;
+
+	const doc = new DOMParser().parseFromString(await response.text(), 'text/html');
+	normalizeRelativeURLs(doc, targetUrl);
+	// Prefix every id so popover content never collides with the host page's
+	// heading ids (Quartz `popover-internal-` convention; anchor scroll relies on it).
+	for (const el of doc.querySelectorAll('[id]')) {
+		el.id = `popover-internal-${el.id}`;
+	}
+
+	const article = doc.querySelector<HTMLElement>('article[data-pagefind-body]');
+	if (!article) return null;
+	article.removeAttribute('data-pagefind-body');
+	for (const el of article.querySelectorAll('script, style, link, [data-island]')) el.remove();
+
+	return { kind: 'html', contentType, element: document.importNode(article, true) };
+}
+
+/**
+ * Attachment factory. Apply to the rendered-content container; re-created per
+ * route via the `dep` key (same pattern as `copyButtons`/`calloutFold`).
+ */
+export function linkPopovers(_dep: unknown): Attachment<HTMLElement> {
+	return (node) => {
+		// Hover intent is meaningless on touch; bail entirely (CSS double-guards).
+		if (!window.matchMedia('(hover: hover) and (pointer: fine)').matches) return;
+
+		let popoverEl: HTMLDivElement | null = null;
+		let popoverInner: HTMLDivElement | null = null;
+		let showTimer: ReturnType<typeof setTimeout> | undefined;
+		let hideTimer: ReturnType<typeof setTimeout> | undefined;
+		/** Generation counter: bumping it invalidates in-flight show() work. */
+		let generation = 0;
+
+		function ensurePopover(): { el: HTMLDivElement; inner: HTMLDivElement } {
+			if (popoverEl && popoverInner) return { el: popoverEl, inner: popoverInner };
+			popoverEl = document.createElement('div');
+			popoverEl.className = 'popover';
+			popoverEl.setAttribute('role', 'tooltip');
+			popoverInner = document.createElement('div');
+			popoverInner.className = 'popover-inner';
+			popoverEl.appendChild(popoverInner);
+			// Keep the card open while the pointer is over it (scrollable preview).
+			popoverEl.addEventListener('mouseenter', cancelHide);
+			popoverEl.addEventListener('mouseleave', scheduleHide);
+			document.body.appendChild(popoverEl);
+			return { el: popoverEl, inner: popoverInner };
+		}
+
+		function hide(): void {
+			generation++;
+			clearTimeout(showTimer);
+			clearTimeout(hideTimer);
+			popoverEl?.classList.remove('active-popover');
+		}
+
+		function scheduleHide(): void {
+			clearTimeout(showTimer);
+			clearTimeout(hideTimer);
+			hideTimer = setTimeout(hide, HIDE_DELAY_MS);
+		}
+
+		function cancelHide(): void {
+			clearTimeout(hideTimer);
+		}
+
+		async function show(link: HTMLAnchorElement, coords: { x: number; y: number }) {
+			const myGeneration = ++generation;
+
+			const targetUrl = new URL(link.href);
+			if (targetUrl.origin !== window.location.origin) return;
+			const hash = decodeURIComponent(targetUrl.hash);
+			targetUrl.hash = '';
+			targetUrl.search = '';
+
+			const cacheKey = targetUrl.pathname;
+			let pending = contentCache.get(cacheKey);
+			if (!pending) {
+				pending = fetchContent(targetUrl);
+				contentCache.set(cacheKey, pending);
+				// Don't poison the cache on transient network failure.
+				pending.then((content) => {
+					if (content === null) contentCache.delete(cacheKey);
+				});
+			}
+
+			const content = await pending;
+			if (content === null || myGeneration !== generation) return;
+
+			const { el, inner } = ensurePopover();
+			inner.replaceChildren();
+			inner.scrollTop = 0;
+			inner.dataset.contentType = content.contentType;
+
+			switch (content.kind) {
+				case 'image': {
+					const img = document.createElement('img');
+					img.src = content.src;
+					img.alt = new URL(content.src).pathname;
+					inner.className = 'popover-inner';
+					inner.appendChild(img);
+					break;
+				}
+				case 'pdf': {
+					const iframe = document.createElement('iframe');
+					iframe.src = content.src;
+					iframe.title = new URL(content.src).pathname;
+					inner.className = 'popover-inner';
+					inner.appendChild(iframe);
+					break;
+				}
+				case 'html': {
+					inner.className = 'popover-inner prose prose-sm dark:prose-invert';
+					// Clone so the cached tree is never mutated by the live DOM.
+					inner.appendChild(content.element.cloneNode(true));
+					break;
+				}
+			}
+
+			const { x, y } = await computePosition(link, el, {
+				strategy: 'fixed',
+				middleware: [inline({ x: coords.x, y: coords.y }), shift({ padding: 12 }), flip()]
+			});
+			if (myGeneration !== generation) return;
+			el.style.transform = `translate(${x.toFixed()}px, ${y.toFixed()}px)`;
+			el.classList.add('active-popover');
+
+			if (hash !== '' && content.kind === 'html') {
+				const heading = inner.querySelector<HTMLElement>(
+					`#popover-internal-${CSS.escape(hash.slice(1))}`
+				);
+				if (heading) {
+					inner.scroll({ top: heading.offsetTop - ANCHOR_SCROLL_OFFSET, behavior: 'instant' });
+				}
+			}
+		}
+
+		const onKeydown = (event: KeyboardEvent) => {
+			if (event.key === 'Escape' && popoverEl?.classList.contains('active-popover')) {
+				hide();
+			}
+		};
+		document.addEventListener('keydown', onKeydown);
+
+		const links = Array.from(node.querySelectorAll<HTMLAnchorElement>('a.internal')).filter(
+			(link) => link.dataset.noPopover !== 'true'
+		);
+		const cleanups = links.map((link) => {
+			const onEnter = (event: MouseEvent) => {
+				cancelHide();
+				clearTimeout(showTimer);
+				showTimer = setTimeout(
+					() => void show(link, { x: event.clientX, y: event.clientY }),
+					SHOW_DELAY_MS
+				);
+			};
+			const onLeave = () => {
+				clearTimeout(showTimer);
+				scheduleHide();
+			};
+			link.addEventListener('mouseenter', onEnter);
+			link.addEventListener('mouseleave', onLeave);
+			return () => {
+				link.removeEventListener('mouseenter', onEnter);
+				link.removeEventListener('mouseleave', onLeave);
+			};
+		});
+
+		return () => {
+			generation++;
+			clearTimeout(showTimer);
+			clearTimeout(hideTimer);
+			document.removeEventListener('keydown', onKeydown);
+			cleanups.forEach((fn) => fn());
+			popoverEl?.remove();
+			popoverEl = null;
+			popoverInner = null;
+		};
+	};
+}

package/site/src/lib/components/popover/popover.css

@@ -0,0 +1,82 @@
+/* Fixed positioning keeps previews outside the article layout. */
+
+.popover {
+	position: fixed;
+	top: 0;
+	left: 0;
+	z-index: 60;
+	overflow: visible;
+	padding: 0.75rem; /* hover bridge between the anchor and the card */
+	will-change: transform;
+	visibility: hidden;
+	opacity: 0;
+	transition:
+		opacity 0.2s ease,
+		visibility 0.2s ease;
+}
+
+.popover.active-popover {
+	visibility: visible;
+	opacity: 1;
+}
+
+.popover > .popover-inner {
+	position: relative;
+	width: 28rem;
+	max-width: calc(100vw - 2rem);
+	max-height: 20rem;
+	padding: 0.25rem 1rem 1rem;
+	overflow: auto;
+	overscroll-behavior: contain;
+	white-space: normal;
+	font-family: var(--font-sans);
+	font-weight: initial;
+	font-style: initial;
+	line-height: 1.55;
+	border: 1px solid var(--color-border);
+	background-color: var(--color-bg);
+	border-radius: 0.5rem;
+	box-shadow:
+		0 4px 12px rgb(0 0 0 / 0.08),
+		0 12px 32px rgb(0 0 0 / 0.12);
+	cursor: default;
+}
+
+:root.dark .popover > .popover-inner {
+	box-shadow:
+		0 4px 12px rgb(0 0 0 / 0.35),
+		0 12px 32px rgb(0 0 0 / 0.45);
+}
+
+.popover > .popover-inner h1 {
+	font-size: 1.25rem;
+}
+
+/* Asset previews (internal links can target images / PDFs). */
+.popover > .popover-inner[data-content-type*='image'],
+.popover > .popover-inner[data-content-type*='pdf'] {
+	padding: 0;
+	max-height: 100%;
+}
+
+.popover > .popover-inner[data-content-type*='image'] img {
+	margin: 0;
+	display: block;
+	border-radius: 0.5rem;
+	max-width: 100%;
+}
+
+.popover > .popover-inner[data-content-type*='pdf'] iframe {
+	display: block;
+	width: 100%;
+	height: 20rem;
+	border: 0;
+	border-radius: 0.5rem;
+}
+
+/* Touch / coarse-pointer devices: popovers are disabled in JS too, this is a belt. */
+@media (hover: none), (pointer: coarse) {
+	.popover {
+		display: none !important;
+	}
+}

package/site/src/lib/components/search/SearchButton.svelte

@@ -0,0 +1,57 @@
+<script lang="ts">
+	import { onMount } from 'svelte';
+	import Command from '@lucide/svelte/icons/command';
+	import Search from '@lucide/svelte/icons/search';
+	import type { ClassValue } from 'svelte/elements';
+	import { cn } from '$lib/utils';
+	import IconButton from '../ui/IconButton.svelte';
+	import { openSearch } from './search-state.svelte';
+
+	interface Props {
+		variant?: 'sidebar' | 'icon';
+		class?: ClassValue;
+	}
+
+	const { variant = 'sidebar', class: className }: Props = $props();
+
+	// Resolved after mount so SSR output is deterministic (no hydration mismatch).
+	let isMac = $state(false);
+	let ready = $state(false);
+	onMount(() => {
+		isMac = /Mac|iP(hone|ad|od)/.test(navigator.platform);
+		ready = true;
+	});
+</script>
+
+{#if variant === 'icon'}
+	<IconButton
+		aria-label="Search"
+		title="Search"
+		class={cn('size-8 rounded-md border border-border bg-transparent text-text', className)}
+		onclick={openSearch}
+	>
+		<Search class="size-4" />
+	</IconButton>
+{:else}
+	<button
+		type="button"
+		class={cn(
+			'flex w-full cursor-pointer items-center gap-2 rounded-md border border-border bg-transparent px-2.5 py-1.5 text-sm text-text/60 transition-colors hover:bg-surface focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none',
+			className
+		)}
+		onclick={openSearch}
+		disabled={!ready}
+	>
+		<Search class="size-4" />
+		<span>Search</span>
+		<kbd
+			class="ml-auto rounded border border-border px-1.5 py-0.5 font-sans text-[0.65rem] text-text/60"
+		>
+			<span class="sr-only">{isMac ? 'Command K' : 'Ctrl K'}</span>
+			<span class="flex items-center gap-0.5" aria-hidden="true">
+				{#if isMac}<Command class="size-3" />{:else}Ctrl{/if}
+				<span>K</span>
+			</span>
+		</kbd>
+	</button>
+{/if}

package/site/src/lib/components/search/SearchPalette.svelte

@@ -0,0 +1,189 @@
+<script lang="ts">
+	import { Command, Dialog } from 'bits-ui';
+	import { goto } from '$app/navigation';
+	import Search from '@lucide/svelte/icons/search';
+	import {
+		ensureIndex,
+		resetIndex,
+		searchClient,
+		searchPagefind,
+		type SearchGroup
+	} from './pagefind-client.svelte';
+	import { parseSearchQuery } from './pagefind-query';
+	import { closeSearch, searchState, toggleSearch } from './search-state.svelte';
+
+	let query = $state('');
+	let course = $state('');
+	let tag = $state('');
+	let groups = $state<SearchGroup[]>([]);
+
+	const courseOptions = $derived(Object.entries(searchClient.filters.course ?? {}).sort());
+	const tagOptions = $derived(Object.entries(searchClient.filters.tag ?? {}).sort());
+	const parsedQuery = $derived(parseSearchQuery(query));
+
+	const activeFilters = $derived.by(() => {
+		const f: Record<string, string[]> = {};
+		if (course) f.course = [course];
+		if (parsedQuery.tag) f.tag = [parsedQuery.tag];
+		else if (tag) f.tag = [tag];
+		return f;
+	});
+
+	$effect(() => {
+		const parsed = parsedQuery;
+		const filters = activeFilters;
+		if (searchClient.status !== 'ready' || (parsed.term !== null && parsed.term.length < 2)) {
+			groups = [];
+			return;
+		}
+		void searchPagefind(parsed.term, filters).then((out) => {
+			// null = superseded by a newer keystroke; keep current results.
+			if (out !== null) groups = out;
+		});
+	});
+
+	async function navigate(url: string) {
+		closeSearch();
+		// Heading ids are baked into the prerendered HTML, so a plain goto
+		// lands on the section anchor directly.
+		await goto(url);
+	}
+
+	function isEditable(target: EventTarget | null): boolean {
+		if (!(target instanceof HTMLElement)) return false;
+		return (
+			target instanceof HTMLInputElement ||
+			target instanceof HTMLTextAreaElement ||
+			target instanceof HTMLSelectElement ||
+			target.isContentEditable
+		);
+	}
+
+	function onKeydown(event: KeyboardEvent) {
+		if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'k') {
+			event.preventDefault();
+			toggleSearch();
+			return;
+		}
+		if (
+			event.key === '/' &&
+			!event.metaKey &&
+			!event.ctrlKey &&
+			!event.altKey &&
+			!searchState.open &&
+			!isEditable(event.target)
+		) {
+			event.preventDefault();
+			toggleSearch();
+		}
+	}
+
+	function retry() {
+		resetIndex();
+		void ensureIndex();
+	}
+</script>
+
+<svelte:window onkeydown={onKeydown} />
+
+<Dialog.Root bind:open={searchState.open}>
+	<Dialog.Portal>
+		<Dialog.Overlay class="fixed inset-0 z-50 bg-black/40" />
+		<Dialog.Content
+			class="fixed top-[15vh] left-1/2 z-50 w-full max-w-xl -translate-x-1/2 overflow-hidden rounded-lg border border-border bg-bg shadow-2xl"
+		>
+			<Dialog.Title class="sr-only">Search</Dialog.Title>
+			<Command.Root shouldFilter={false} label="Search site">
+				<div class="flex items-center gap-2 border-b border-border px-3">
+					<Search class="size-4 shrink-0 text-text/60" />
+					<Command.Input
+						bind:value={query}
+						placeholder="Search… or #tag"
+						class="h-11 w-full bg-transparent text-sm text-text outline-none placeholder:text-text/50"
+					/>
+				</div>
+				{#if searchClient.status === 'ready' && (courseOptions.length > 0 || tagOptions.length > 0)}
+					<div class="flex items-center gap-2 border-b border-border px-3 py-2">
+						{#if courseOptions.length > 0}
+							<select
+								bind:value={course}
+								aria-label="Filter by course"
+								class="max-w-[50%] cursor-pointer rounded-md border border-border bg-bg px-2 py-1 text-xs text-text/80 outline-none focus-visible:ring-2 focus-visible:ring-accent"
+							>
+								<option value="">All courses</option>
+								{#each courseOptions as [value, count] (value)}
+									<option {value}>{value} ({count})</option>
+								{/each}
+							</select>
+						{/if}
+						{#if tagOptions.length > 0}
+							<select
+								bind:value={tag}
+								aria-label="Filter by tag"
+								class="max-w-[50%] cursor-pointer rounded-md border border-border bg-bg px-2 py-1 text-xs text-text/80 outline-none focus-visible:ring-2 focus-visible:ring-accent"
+							>
+								<option value="">All tags</option>
+								{#each tagOptions as [value, count] (value)}
+									<option {value}>{value} ({count})</option>
+								{/each}
+							</select>
+						{/if}
+					</div>
+				{/if}
+				<Command.List class="max-h-[60vh] overflow-y-auto p-2">
+					{#if searchClient.status === 'loading' || searchClient.status === 'idle'}
+						<div class="block px-3 py-6 text-center text-sm text-text/60">Loading index…</div>
+					{:else if searchClient.status === 'missing'}
+						<div
+							class="flex flex-col items-center gap-2 px-3 py-6 text-center text-sm text-text/60"
+						>
+							{#if import.meta.env.DEV}
+								<span>No search index in dev — Pagefind indexes the built site.</span>
+								<code class="rounded-sm bg-surface px-1.5 py-0.5 text-xs">bun run build</code>
+							{:else}
+								<span>Couldn't load the search index.</span>
+								<button
+									type="button"
+									class="cursor-pointer rounded-md border border-border px-2.5 py-1 text-text transition-colors hover:bg-surface"
+									onclick={retry}
+								>
+									Retry
+								</button>
+							{/if}
+						</div>
+					{:else}
+						<Command.Empty class="block px-3 py-6 text-center text-sm text-text/60">
+							{parsedQuery.term !== null && parsedQuery.term.length < 2
+								? 'Type at least 2 characters…'
+								: 'No results'}
+						</Command.Empty>
+						{#each groups as group (group.id)}
+							<Command.Group value={group.id}>
+								<Command.GroupHeading class="px-3 pt-3 pb-1 text-xs font-semibold text-text/60">
+									{group.title}
+								</Command.GroupHeading>
+								<Command.GroupItems>
+									{#each group.sections as section, i (`${group.id}:${i}`)}
+										<Command.Item
+											value={`${group.id}:${i}`}
+											onSelect={() => navigate(section.url)}
+											class="flex cursor-pointer flex-col gap-0.5 rounded-md px-3 py-2 data-selected:bg-surface"
+										>
+											<span class="text-sm text-text">{section.title}</span>
+											<span
+												class="truncate text-xs text-text/60 [&_mark]:rounded-sm [&_mark]:bg-accent/20 [&_mark]:text-text"
+											>
+												<!-- eslint-disable-next-line svelte/no-at-html-tags -- Pagefind excerpt over our own prerendered corpus -->
+												{@html section.excerpt}
+											</span>
+										</Command.Item>
+									{/each}
+								</Command.GroupItems>
+							</Command.Group>
+						{/each}
+					{/if}
+				</Command.List>
+			</Command.Root>
+		</Dialog.Content>
+	</Dialog.Portal>
+</Dialog.Root>

package/site/src/lib/components/search/index.ts

@@ -0,0 +1,3 @@
+export { default as SearchButton } from './SearchButton.svelte';
+export { default as SearchPalette } from './SearchPalette.svelte';
+export { closeSearch, openSearch, searchState, toggleSearch } from './search-state.svelte';

package/site/src/lib/components/search/pagefind-client.svelte.ts

@@ -0,0 +1,129 @@
+import { cleanResultUrl } from './pagefind-url';
+
+/**
+ * Lazy Pagefind client (cca's `search-client.svelte.ts` rewired from
+ * minisearch to Pagefind's chunked static index).
+ *
+ * The index is produced AFTER `vite build` by the deployment adapter
+ * (`pagefind --site build/.svelte-kit/cloudflare`), which drops a self-contained
+ * `/pagefind/` bundle into the deployed static assets. We lazy-import its JS
+ * API on first palette open, so search costs nothing until used. The Vite dev
+ * server never has that bundle — `status: 'missing'` drives the dev fallback
+ * message in the palette.
+ */
+
+/* Minimal typings for the Pagefind browser API (no published types). */
+interface PagefindSubResult {
+	title: string;
+	url: string;
+	excerpt: string;
+}
+
+interface PagefindFragment {
+	url: string;
+	excerpt: string;
+	meta: Record<string, string>;
+	sub_results: PagefindSubResult[];
+}
+
+interface PagefindRawResult {
+	id: string;
+	data(): Promise<PagefindFragment>;
+}
+
+interface PagefindModule {
+	init(): Promise<void>;
+	options(opts: Record<string, unknown>): Promise<void>;
+	filters(): Promise<Record<string, Record<string, number>>>;
+	search(
+		query: string | null,
+		options?: { filters?: Record<string, string[]> }
+	): Promise<{ results: PagefindRawResult[] }>;
+	debouncedSearch(
+		query: string,
+		options?: { filters?: Record<string, string[]> },
+		debounceMs?: number
+	): Promise<{ results: PagefindRawResult[] } | null>;
+}
+
+/** One section-level hit (deep link) within a page. */
+export interface SearchSection {
+	title: string;
+	url: string;
+	/** Pagefind-generated excerpt HTML (`<mark>` around matched terms). */
+	excerpt: string;
+}
+
+/** Search hits grouped by page and section. */
+export interface SearchGroup {
+	id: string;
+	title: string;
+	url: string;
+	sections: SearchSection[];
+}
+
+export const searchClient = $state<{
+	status: 'idle' | 'loading' | 'ready' | 'missing';
+	/** filter name -> value -> result count, from the built index. */
+	filters: Record<string, Record<string, number>>;
+}>({ status: 'idle', filters: {} });
+
+let pagefind: PagefindModule | undefined;
+
+export async function ensureIndex(): Promise<void> {
+	if (searchClient.status === 'ready' || searchClient.status === 'loading') return;
+	searchClient.status = 'loading';
+	try {
+		// Runtime URL import — kept out of Vite's module graph on purpose.
+		const bundleUrl = '/pagefind/pagefind.js';
+		pagefind = (await import(/* @vite-ignore */ bundleUrl)) as PagefindModule;
+		await pagefind.init();
+		searchClient.filters = await pagefind.filters();
+		searchClient.status = 'ready';
+	} catch {
+		pagefind = undefined;
+		searchClient.status = 'missing';
+	}
+}
+
+/** Allow the palette's Retry button to re-attempt a failed load. */
+export function resetIndex(): void {
+	if (searchClient.status === 'missing') searchClient.status = 'idle';
+}
+
+const PAGE_LIMIT = 10;
+const SECTIONS_PER_PAGE = 4;
+
+/**
+ * Run a debounced Pagefind query. Returns `null` when this call was
+ * superseded by a newer keystroke (Pagefind's debouncedSearch contract) —
+ * callers must keep previous results in that case.
+ */
+export async function searchPagefind(
+	query: string | null,
+	filters: Record<string, string[]>
+): Promise<SearchGroup[] | null> {
+	if (!pagefind) return [];
+	const opts = Object.keys(filters).length > 0 ? { filters } : undefined;
+	const res =
+		query === null
+			? await pagefind.search(null, opts)
+			: await pagefind.debouncedSearch(query, opts, 120);
+	if (res === null) return null;
+
+	const top = res.results.slice(0, PAGE_LIMIT);
+	const fragments = await Promise.all(top.map((r) => r.data()));
+	return fragments.map((frag, i) => {
+		const url = cleanResultUrl(frag.url);
+		const title = frag.meta?.title || url;
+		let sections: SearchSection[] = (frag.sub_results ?? [])
+			.slice(0, SECTIONS_PER_PAGE)
+			.map((sub) => ({
+				title: sub.title || title,
+				url: cleanResultUrl(sub.url),
+				excerpt: sub.excerpt
+			}));
+		if (sections.length === 0) sections = [{ title, url, excerpt: frag.excerpt }];
+		return { id: top[i].id, title, url, sections };
+	});
+}