refactor: fetch orama-db.json when search triggered

[canerakdas]

Description

Since we're not using Orama Cloud with doc-kit, the generated files end up being quite large. With this change, we'll fetch the required file only when search is triggered, avoiding downloading this large file unnecessarily.

For example, on the https://nodejs.org/learn page, the total download size is around ≈ 470kB, and about ≈ 250kB of that comes from orama-db.json. Considering that it's not certain whether the user will even use the search feature, this overhead feels quite significant;

Validation

Everything should work smoothly in the preview. It would be good to throttle the network (e.g., simulate a slow connection) and verify that there are no noticeable slowdowns.

Check List

• I have read the Contributing Guidelines and made commit messages that follow the guideline.
• I have run node --run test and all tests passed.
• I have check code formatting with node --run format & node --run lint.
• I've covered new added functionality with unit tests if necessary.

[cursor]

PR Summary

Medium Risk
Changes the search client to load orama-db.json on-demand and makes db.search asynchronous, which could affect search responsiveness and error behavior if loading fails or is slow.

Overview
Defers downloading and loading orama-db.json until the first search is executed, instead of fetching it during hook initialization.

Overrides the Orama client’s db.search to await a shared ensureLoaded() promise (stored in a useRef) so the DB loads only once and retries after failures.

^{Reviewed by Cursor Bugbot for commit a855996. Bugbot is set up for automated code reviews on this repo. Configure here.}

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
api-docs-tooling	Ready	Preview	Apr 10, 2026 11:42am

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 78.43%. Comparing base (2765300) to head (a855996).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #759   +/-   ##
=======================================
  Coverage   78.42%   78.43%           
=======================================
  Files         157      157           
  Lines       13959    13963    +4     
  Branches     1152     1152           
=======================================
+ Hits        10948    10952    +4     
  Misses       3006     3006           
  Partials        5        5           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit a855996. Configure here.}