Skip to content

Add unified cross-product search to the landing page#56

Merged
willeastcott merged 1 commit into
mainfrom
unified-search
Jul 1, 2026
Merged

Add unified cross-product search to the landing page#56
willeastcott merged 1 commit into
mainfrom
unified-search

Conversation

@willeastcott

Copy link
Copy Markdown
Contributor

What

Adds a global search to the landing page that spans all products, so visitors no longer need to know which product a symbol lives in before they can search for it.

  • build.mjs: new mergeSearchIndexes() step (runs in both full and --landing-only builds) decodes each product''s TypeDoc search index (window.searchData = base64, deflate-compressed JSON containing a serialized lunr 2.3.9 index), prefixes row URLs with the product folder, tags each row with a product-<folder> class, rebuilds a single combined index with TypeDoc-identical builder settings, and writes it to docs/assets/search.js. copySharedAssets() now also copies TypeDoc''s main.js and icons.js from the engine build.
  • index.html: adds TypeDoc 0.28''s stock search trigger/dialog markup and script tags. The hand-rolled inline theme/menu handlers are removed since main.js now drives those elements (same markup contract the landing page already mirrors).
  • assets/landing.css: styles the product-<folder> class as a badge (Engine, PCUI, ...) on each search result, themed via TypeDoc CSS variables.
  • repos-config.json: new optional per-repo search fields — engine gets searchBoost: 1.25 and searchKindBoosts: {128: 2} (restores its TypeDoc searchGroupBoosts class boost, which is baked into the original index and lost on re-merge); engine-v1 is excluded via searchExclude to keep ~4,700 near-duplicate legacy symbols out (its own per-product search is untouched).
  • package.json: adds lunr@2.3.9, pinned to match the version bundled in TypeDoc''s client.

Why reuse TypeDoc''s client instead of writing a custom search UI

The landing page already mirrors TypeDoc''s markup and reuses its stylesheet. Pointing TypeDoc''s own main.js at a combined index in the exact same format gets the dialog UX, ranking, Ctrl+K / / shortcuts, keyboard navigation, a11y, and graceful failure with zero client-side JS to maintain.

Notes for reviewers

  • The combined index is 9,575 rows from 7 products, ~347 KB base64 — comparable to the engine''s own 206 KB per-product index, and loaded async the same way.
  • The merge validates each product''s index (wrapper format + lunr version) and skips it with a build warning instead of failing, so TypeDoc format drift in one upstream repo degrades that product''s coverage rather than breaking the site. The coupling (searchData wrapper, deflate, lunr 2.3.9) is documented in the README.
  • Verified locally against the full built docs/ tree: round-trip decode/query in Node, plus browser checks (search/keyboard shortcuts/theme toggle/mobile menu, light+dark themes, result navigation to /engine/classes/AppBase.html, missing-index failure modes).

🤖 Generated with Claude Code

The landing page had no search and each product's TypeDoc search is
siloed, so finding a symbol required already knowing which product it
lives in. The build now merges every product's TypeDoc search index
(window.searchData: base64, deflate-compressed JSON with a serialized
lunr 2.3.9 index) into a combined docs/assets/search.js, prefixing row
URLs with the product folder and tagging rows with a product-<folder>
class that landing.css styles as a badge. The landing page reuses
TypeDoc's stock search client (main.js, copied from the engine build)
for the dialog, ranking, and keyboard shortcuts, replacing the
hand-rolled inline theme/menu handlers it now drives.

Engine results carry a 1.25x boost plus 2x on classes (mirroring its
TypeDoc searchGroupBoosts); the legacy engine-v1 index is excluded via
searchExclude in repos-config.json. Missing or format-drifted product
indexes are skipped with a warning rather than failing the build.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@willeastcott willeastcott self-assigned this Jul 1, 2026
@willeastcott
willeastcott requested a review from Copilot July 1, 2026 22:38
@willeastcott willeastcott added the enhancement New feature or request label Jul 1, 2026

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a unified, cross-product search experience to the landing page by reusing TypeDoc’s built-in client UI and generating a merged search index during the build.

Changes:

  • Introduces a build-time mergeSearchIndexes() step to decode each product’s TypeDoc search.js, rewrite URLs/classes, and emit a single combined docs/assets/search.js.
  • Updates the landing page to use TypeDoc’s stock search trigger/dialog and loads TypeDoc client assets (main.js, icons.js, merged search.js).
  • Adds per-repo search tuning (searchExclude, searchBoost, searchKindBoosts) and styles per-product result badges.

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated no comments.

Show a summary per file
File Description
build.mjs Adds merged search index generation and copies TypeDoc client assets (main.js, icons.js) into shared landing assets.
index.html Integrates TypeDoc search UI markup and scripts; removes the custom inline handlers now covered by main.js.
assets/landing.css Styles product-<folder> classes as per-product badges in search results.
repos-config.json Adds per-repo search config knobs and excludes engine-v1 from the combined index.
README.md Documents how global search works, what’s merged, and the TypeDoc/lunr coupling.
package.json Pins lunr devDependency to 2.3.9 to match TypeDoc’s client.
package-lock.json Locks lunr@2.3.9 installation details.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@willeastcott
willeastcott merged commit 022ff9d into main Jul 1, 2026
1 check passed
@willeastcott
willeastcott deleted the unified-search branch July 1, 2026 22:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants