feat(search): client side fts

[larbish]

Summary

Cache policy update written by an AI agent on behalf of @atinux; not yet human-reviewed.

Move search to client-side full-text search: a web worker owns a browser comark-content instance (sqlite-wasm FTS5) hydrated from per-commit snapshot artifacts, replacing the search-sections endpoint that shipped a flat section list on every page hydration.

Built on comarkdown/comark-content#109 (persisted snapshot & manifest artifacts): the webhook parses once per content push and update the cached artifactfs so consumers reuse the cached version.

How it works

Client.

useSearch pins hydration to the production commit via the new /api/content/head endpoint, then a worker fetches /api/content/blob/<sha>/manifest.json and /snapshot/content.json (SHA-pinned, immutable, isr: true cached at the CDN forever) and builds the FTS index through the plugin's cache-first path.

Queries run in the worker: BM25 ranking, heading-weighted scores, snippets.

Server.

The webhook's cache warm becomes warmSnapshot(): one full parse per push, which persists the snapshot artifact into the per-SHA Runtime Cache namespace. The first request on a new SHA is a single cache read, then ISR pins the URL; old SHA URLs simply become unreachable, so search needs no purges. Head-of-branch /blob/<sha> requests reuse the shared prod instance instead of minting a duplicate preview instance. The search-sections plugin, endpoint, route rules, and per-page payload are deleted.

Ref cache.

The production deployment's target-branch pointer has a one-hour fallback TTL and is refreshed by the push webhook before ISR is purged. Preview refs, negative lookups, and preview authorization decisions expire after 600 seconds. This keeps the webhook as the normal refresh path while bounding production staleness after a missed delivery or failed refresh.

Debug mode

On by default in dev; in production via ?debug=search. Both threads log onto one page-relative timeline — fixed-width lines showing stage durations, decoded/wire sizes, and result counts:

[search]    +412ms  manifest              14.2ms     1.3 KB  1.0 KB on the wire
[search]   +1284ms  index:built          118.4ms             net of the snapshot fetch above
[search]   +1290ms  index:rows                                87 results · sections in the FTS table

Next steps to discuss

• Extract the search stack into a plugin — useful for nuxt.com (migration on comark-content in progress).

• Version-aware search — the hydration URLs are already per-SHA (/api/content/blob/<sha>/…), so searching any historical version is just pointing the worker at that commit's artifacts, which the /blob/<sha> routes already serve and self-heal on first request. Would pair with the existing version-history UI; main open question is worker lifecycle when switching versions (one instance per SHA vs. reset + rehydrate).

Summary by CodeRabbit

• New Features

  • Added fast, client-side full-text search across documentation.
  • Organized search results by navigation sections with browse-only support.
  • Added Logos and UnJS icon collections.
  • Added automatic Markdown redirects for supported pages and content paths.
  • Added production content snapshots for faster search and content delivery.

• Bug Fixes

  • Improved content previews, revalidation reliability, cache behavior, and snapshot loading across deployments.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
comark-docs-layer	Ready	Preview	Sep 14, 2026 9:11am UTC
comark-docs-playground	Ready	Preview	Sep 14, 2026 9:11am UTC

[pkg-pr-new]

npm i https://pkg.pr.new/comarkdown/comark-docs@22

commit: e6a75cb