fix(docs): polish Command-K search states

[vyctorbrzezowski]

Summary

This PR polishes the docs Command-K search experience without changing authored docs content.

• Reworks the search modal states so initial, loading, results, no-results, and missing-index states each have a clear visual treatment.
• Keeps Ask Molty available from the search footer, including Ask Molty about <query> and the Command+Enter affordance.
• Makes search results easier to scan with category/section metadata, two-line snippets, keyboard-active result styling, hover states, and a subtle bottom fade for scroll context.
• Restores the Molty avatar and hover animation as docs-site shell assets so future docs content syncs do not delete them.

Details and decisions

Search lifecycle

Typing still uses a 240ms debounce before running Pagefind. Suggestions intentionally run immediately because they are explicit user actions.

The loading state now keeps the spinner node mounted while the user keeps typing, so its animation does not restart on every keystroke. The old header shimmer was removed because the spinner is the loading indicator.

Pagefind load failures are treated as transient. If the search bundle is unavailable during a preview rebuild, the next search retries the import instead of keeping Search index unavailable cached for the rest of the browser session.

Results behavior

Results are keyboard navigable with ArrowUp/ArrowDown and Enter. The active/hover state is neutral and uses the docs shell surface tokens rather than a brand-orange outline. Inactive rows stay flat; rounded treatment appears only on hover/focus/active.

Each result can show category / section Pagefind metadata. That metadata is generated by the docs-site build from the existing navigation structure, not fetched at search time, so it does not add runtime lookup latency.

Empty, loading, and unavailable states

The initial empty state is compact and uses:

Search setup, commands, integrations, and config docs.

No-results uses No matches for “query” plus the Command+Enter badge for asking Molty directly.

The unavailable-index state remains available for local preview or transient Pagefind failures, but it no longer masks later successful loads in the same session.

Ask Molty integration

The footer stays visible while results scroll. When a query is present, it shows Ask Molty about <query> with a subtle shimmer on the query term. Command+Enter closes search and opens Molty with the query.

For unauthenticated users, the pending Molty question is stored only for the auth handoff and resumes only when the callback returns with molty_resume=1. Empty Ask Molty actions clear stale pending questions so old localStorage state cannot reopen an unrelated prompt.

Responsive behavior

Mobile and narrow layouts keep the search panel centered, use a 16px input font to avoid awkward oversized placeholder rendering, hide cramped shortcut affordances, and keep the footer visible without forcing the modal to occupy most of the viewport.

Screenshots

Desktop

Initial search state:

Loading state:

Results with hover/active state and fixed Molty footer:

No results state:

Search index unavailable state:

Ask Molty footer close-up:

Command-K header affordance close-up:

Tablet

Mobile

Initial centered search state:

Mobile results:

Verification

• node --check scripts/docs-site/assets.mjs
• node --check scripts/docs-site/build.mjs
• node --check scripts/docs-site/smoke.mjs
• node --check scripts/docs-site/visual-smoke.mjs
• npm run docs:build:preview
• node scripts/docs-site/search-index.mjs
• npx pagefind --site dist/docs-site --output-path dist/docs-site/pagefind
• node scripts/docs-site/pagefind-normalize.mjs
• node --check dist/docs-site/assets/docs-site.js
• git diff --check origin/main..HEAD
• Playwright smoke against the preview build for Command-K open/focus, debounced typing, result navigation, close/reset, mobile containment, Molty footer visibility, transient Pagefind retry, and spinner persistence while typing.

Not run: full docs build/smoke over the complete docs corpus. This was intentionally kept to the 30-page preview build to avoid the full 11k-page docs build during this review.