feat(site-search): add semantic handling for search queries

[rbcorrales]

Summary

Adds an off by default site search surface that can handle eligible WordPress ?s= queries with semantic ranking from wpvdb-search.

Depends on Automattic/wpvdb-search#3.

1. Adds a Smart Search settings page with an enable toggle, dense default mode, pool size, fallback toggle, post type selection, and cache clear action.
2. Marks eligible front end main search queries and short circuits them through posts_pre_query.
3. Uses a transient cached pre visibility pool, then applies perm => readable on each request before hydration.
4. Bypasses unsupported constraints, non default fields, REST, feeds, previews, WPML, and Polylang in v1.
5. Falls back to WordPress keyword search only when the ranker itself returns no candidates and fallback is enabled.

Manual test plan

1. Install this branch with wpvdb, wpvdb-search, and the dependency PR active on a site with indexed posts.
2. Visit Settings, then WPVDB Smart Search, and confirm site search handling is off by default, mode defaults to dense, fallback is enabled, and posts plus pages are selected.
3. Enable site search handling, save settings, and run a front end /?s= search from the theme search form.
4. Confirm the normal theme search page renders semantically ranked posts, not the standalone /smart-search/ page.
5. Open page 2 for the same search and confirm pagination uses the same ranked pool rather than mixing in keyword ranked results.
6. Use a small pre_get_posts snippet to set post_status to any, then confirm posts the current visitor cannot read are filtered out before display and before the result count is calculated.
7. Switch to sparse mode with fallback enabled and use a query that produces no sparse candidates. Confirm the request falls through to default WordPress keyword search.
8. Disable fallback and repeat the same sparse no candidate query. Confirm the theme shows zero results instead of keyword fallback results.
9. Add a temporary query constraint such as fields => ids, a taxonomy query, or a date query. Confirm the plugin bypasses semantic handling and lets WordPress search run normally.
10. Use the Clear site search cache action and confirm the settings page shows the cache cleared notice.

[Copilot]

Pull request overview

Adds an off-by-default “native” site search surface that intercepts eligible front-end ?s= main queries and replaces WordPress keyword search with semantic ranking from wpvdb-search, configurable via a new Settings page.

Changes:

• Introduces a Settings page (enable toggle, mode, pool size, fallback, post types, cache clear) and cache versioning for invalidation.
• Adds a native search surface that flags eligible main queries and short-circuits them via posts_pre_query, using a transient-cached ranked pool plus per-request readability filtering.
• Adds unit tests for settings normalization and native search behavior; updates README and translation catalogs.

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
wpvdb-smart-search.php	Loads new Settings and native search surface; initializes them on plugins_loaded.
includes/class-settings.php	New admin settings page + sanitization + cache version bumping/clear action.
includes/surfaces/class-native-search.php	New native search interception + caching + pagination + visibility filtering logic.
tests/bootstrap.php	Extends the test WP stubs to support options/transients/search behavior used by the new code.
tests/Unit/SettingsTest.php	Covers settings defaults and sanitization behavior.
tests/Unit/NativeSearchTest.php	Covers native search eligibility, caching, pagination, and fallback behavior.
README.md	Documents the optional native site search surface.
languages/wpvdb-smart-search.pot	Adds new translatable strings and references.
languages/wpvdb-smart-search-es_ES.po	Updates Spanish catalog for new strings.

---

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

[Copilot]

Pull request overview

Copilot reviewed 10 out of 11 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 11 changed files in this pull request and generated no new comments.