@stapel/search-react 0.1.0

package/src/i18n/generated/errors.ru.gen.ts

@@ -0,0 +1,69 @@
+// AUTO-GENERATED by scripts/gen-errors.mjs — do not edit by hand.
+// Source: stapel-auth canonical errors.json (backend codegen artifact).
+// Regenerate: pnpm gen:errors   ·   Drift gate: pnpm gen:errors:check
+// Locale source: backend translations/errors.ru.json (locale catalog
+// beside the canonical errors.json — i18n-shipping.md §1).
+import type { SearchErrorCode } from "./errors.gen.js";
+
+/**
+ * `ru` texts for every backend error code — complete over the registry by
+ * construction (the generator fails on a gap; the Record type fails compilation
+ * on drift). Import from the pair's `./i18n/ru` subpath, NOT the main
+ * entry, so the locale stays out of hosts that don't ship it.
+ */
+export const searchErrorBundleRu: Record<SearchErrorCode, string> = {
+  "error.400.bad_request": "Некорректный запрос",
+  "error.400.captcha_invalid": "Проверка капчи не пройдена. Пожалуйста, попробуйте ещё раз.",
+  "error.400.captcha_required": "Требуется токен капчи.",
+  "error.400.expected_list": "Ожидался список элементов",
+  "error.400.field.blank": "Поле «{field}» не может быть пустым",
+  "error.400.field.does_not_exist": "«{field}» не существует",
+  "error.400.field.invalid": "Поле «{field}» содержит недопустимое значение",
+  "error.400.field.invalid_choice": "Недопустимый вариант для поля «{field}»",
+  "error.400.field.max_length": "Поле «{field}» должно содержать не более {max_length} символов",
+  "error.400.field.max_value": "Значение поля «{field}» должно быть не больше {max_value}",
+  "error.400.field.min_length": "Поле «{field}» должно содержать не менее {min_length} символов",
+  "error.400.field.min_value": "Значение поля «{field}» должно быть не меньше {min_value}",
+  "error.400.field.null": "Поле «{field}» не может быть null",
+  "error.400.field.required": "Поле «{field}» обязательно",
+  "error.400.field.unique": "Значение поля «{field}» должно быть уникальным",
+  "error.400.invalid_ad_id": "Недопустимый идентификатор объявления",
+  "error.400.search_bad_cursor": "Некорректный курсор постраничной навигации",
+  "error.400.search_bad_geo": "Некорректный географический фильтр: {reason}",
+  "error.400.search_bad_range": "Некорректный диапазон «{slug}»: {reason}",
+  "error.400.search_query_too_long": "Слишком длинный поисковый запрос",
+  "error.400.search_sort_needs_center": "Сортировка по расстоянию требует координат (lat и lon)",
+  "error.400.search_too_many_facets": "Слишком много фильтров-фасетов (предел {limit})",
+  "error.400.search_too_many_ranges": "Слишком много диапазонных фильтров (предел {limit})",
+  "error.400.search_unknown_doc_type": "Неизвестный тип поиска «{doc_type}»",
+  "error.400.search_unknown_sort": "Неизвестная сортировка «{sort}»",
+  "error.400.search_window_exceeded": "Эта страница выдачи выходит за предел в {window} результатов. Уточните запрос вместо перелистывания вглубь.",
+  "error.400.validation_error": "Ошибка валидации",
+  "error.400.verification_failed": "Проверка не пройдена",
+  "error.400.verification_invalid_factor": "Этот способ подтверждения недоступен",
+  "error.401.unauthorized": "Требуется аутентификация",
+  "error.402.payment_required": "Требуется оплата",
+  "error.403.forbidden": "У вас нет прав для выполнения этого действия",
+  "error.403.network_blocked": "Запросы из этой сети не разрешены.",
+  "error.403.search_forbidden": "У вас нет прав управлять поисковым индексом",
+  "error.403.verification_enrollment_required": "Требуется регистрация фактора подтверждения.",
+  "error.403.verification_required": "Требуется дополнительная проверка",
+  "error.404.ad_not_found": "Объявление не найдено",
+  "error.404.not_found": "Запрошенный ресурс не найден",
+  "error.404.verification_challenge_not_found": "Запрос на подтверждение не найден или истёк",
+  "error.405.method_not_allowed": "Метод не разрешён",
+  "error.406.not_acceptable": "Недопустимый формат ответа",
+  "error.408.request_timeout": "Время ожидания запроса истекло",
+  "error.409.conflict": "Ресурс уже существует",
+  "error.410.gone": "Ресурс был безвозвратно удалён",
+  "error.413.payload_too_large": "Тело запроса слишком большое",
+  "error.415.unsupported_media_type": "Неподдерживаемый тип данных",
+  "error.422.unprocessable_entity": "Невозможно обработать данные запроса",
+  "error.423.locked": "Ресурс заблокирован",
+  "error.423.verification_locked": "Слишком много неудачных попыток — подтверждение заблокировано",
+  "error.429.rate_limit": "Слишком много попыток. Повторите попытку через {retry_after_minutes} мин.",
+  "error.429.too_many_requests": "Слишком много запросов. Пожалуйста, повторите попытку позже.",
+  "error.500.internal": "Что-то пошло не так",
+  "error.503.mandate_unavailable": "Не удалось проверить доступ к рабочему пространству",
+  "error.503.search_backend_unavailable": "Поисковый движок недоступен",
+};

package/src/i18n/keys.ts

@@ -0,0 +1,220 @@
+import type { I18nDictionary, I18nEngine } from "@stapel/core";
+import { searchErrorBundleEn } from "./generated/errors.gen.js";
+
+/**
+ * search-react's own translation KEYS (frontend-standard §4.2): headless
+ * components never render literal strings — hosts resolve these via core's
+ * i18n engine (`useT`). Backend error codes flow through the SAME contour: a
+ * `StapelApiError.code` is already a key, so the default bundle below ships
+ * English fallbacks for the 54 backend error codes (generated) plus the
+ * pair's own UI keys. All UI keys live under the `search.` namespace.
+ *
+ * ── What is NOT an i18n key here ───────────────────────────────────────────
+ *
+ * A FACET VALUE is not one. `facets.py` returns `{value: count}` — index
+ * terms, not keys. Their captions come from the category's feature schema
+ * (`config.options[].label`, which IS a key when `translatable_options` is
+ * on) and are resolved by `facetOptionLabel` through
+ * `@stapel/attributes-react`, i.e. through the same formatter the card and
+ * the spec table use. Nothing in this file names a catalogue value, because
+ * a catalogue is a deployment's content, not a library's chrome.
+ */
+export const SEARCH_I18N_KEYS = {
+  unknownError: "search.error.unknown",
+
+  // ── results ──────────────────────────────────────────────────────────────
+  resultsTitle: "search.results.title",
+  resultsLoading: "search.results.loading",
+  resultsLoadFailed: "search.results.load_failed",
+  resultsEmpty: "search.results.empty",
+  resultsRetry: "search.results.retry",
+  /** "About N results" — the sentence for an ESTIMATED count. */
+  resultsCountApproximate: "search.results.count_approximate",
+  /** "N results" — only when `exact_total` is true. */
+  resultsCountExact: "search.results.count_exact",
+  resultsTookMs: "search.results.took_ms",
+  resultsNext: "search.results.next",
+  resultsPrev: "search.results.prev",
+  resultsBlockedAtEnd: "search.results.blocked.at_end",
+  resultsBlockedAtStart: "search.results.blocked.at_start",
+  /** The refusal that must NOT read as "nothing found". */
+  resultsWindowExceeded: "search.results.window_exceeded",
+  resultsPromoted: "search.results.promoted",
+  resultsPromotedHint: "search.results.promoted_hint",
+  resultsDistanceKm: "search.results.distance_km",
+  resultsUntitled: "search.results.untitled",
+  resultsOpen: "search.results.open",
+
+  // ── sort ─────────────────────────────────────────────────────────────────
+  sortLabel: "search.sort.label",
+  sortRelevance: "search.sort.relevance",
+  sortNewest: "search.sort.newest",
+  sortPriceAsc: "search.sort.price_asc",
+  sortPriceDesc: "search.sort.price_desc",
+  sortDistance: "search.sort.distance",
+  sortServerChose: "search.sort.server_chose",
+
+  // ── facets ───────────────────────────────────────────────────────────────
+  facetsTitle: "search.facets.title",
+  facetsLoading: "search.facets.loading",
+  facetsLoadFailed: "search.facets.load_failed",
+  facetsEmpty: "search.facets.empty",
+  facetsClear: "search.facets.clear",
+  facetsClearAll: "search.facets.clear_all",
+  facetsApproximate: "search.facets.approximate",
+  facetsSkipped: "search.facets.skipped",
+  /** Shown INSTEAD of a count for a slug the server did not count. */
+  facetsNotCounted: "search.facets.not_counted",
+  facetsDrillDownHint: "search.facets.drill_down_hint",
+  facetsRangeFrom: "search.facets.range_from",
+  facetsRangeTo: "search.facets.range_to",
+  facetsRangeApply: "search.facets.range_apply",
+
+  // ── geo ──────────────────────────────────────────────────────────────────
+  geoTitle: "search.geo.title",
+  geoRadiusKm: "search.geo.radius_km",
+  geoClear: "search.geo.clear",
+  geoBox: "search.geo.box",
+  geoCenter: "search.geo.center",
+
+  // ── the URL that could not be read ───────────────────────────────────────
+  urlIssuesTitle: "search.url.issues_title",
+  urlIssueNotANumber: "search.url.issue.not_a_number",
+  urlIssueGeoIncomplete: "search.url.issue.geo_incomplete",
+  urlIssueBboxMalformed: "search.url.issue.bbox_malformed",
+  urlIssueRangeMalformed: "search.url.issue.range_malformed",
+
+  // ── degradations (the envelope's `degraded[]`) ───────────────────────────
+  degradedTitle: "search.degraded.title",
+  degradedTypoTolerance: "search.degraded.typo_tolerance",
+  degradedPhraseSynonyms: "search.degraded.phrase_synonyms",
+  degradedExactTotal: "search.degraded.exact_total",
+  degradedExactFacetCounts: "search.degraded.exact_facet_counts",
+  degradedCategoryRollup: "search.degraded.category_rollup",
+  degradedScorer: "search.degraded.scorer",
+  degradedUnknown: "search.degraded.unknown",
+
+  // ── ranking disclosure (P2B Art. 5) ──────────────────────────────────────
+  rankingTitle: "search.ranking.title",
+  rankingIntro: "search.ranking.intro",
+  rankingLoading: "search.ranking.loading",
+  rankingLoadFailed: "search.ranking.load_failed",
+  rankingEmpty: "search.ranking.empty",
+  rankingParameter: "search.ranking.parameter",
+  rankingWeight: "search.ranking.weight",
+  rankingAppliesTo: "search.ranking.applies_to",
+  rankingInactive: "search.ranking.inactive",
+  rankingNotes: "search.ranking.notes",
+  rankingLink: "search.ranking.link",
+} as const;
+
+export type SearchI18nKey =
+  (typeof SEARCH_I18N_KEYS)[keyof typeof SEARCH_I18N_KEYS];
+
+/**
+ * English fallback bundle for search-react UI keys + backend error codes.
+ * The generated backend texts are spread FIRST so coverage of the error
+ * registry is by construction; the pair's own copy follows.
+ */
+export const searchI18nBundleEn: Record<string, string> = {
+  ...searchErrorBundleEn,
+
+  "search.error.unknown": "Something went wrong with the search",
+
+  "search.results.title": "Results",
+  "search.results.loading": "Searching…",
+  "search.results.load_failed": "We could not run this search",
+  "search.results.empty": "Nothing matches this search",
+  "search.results.retry": "Try again",
+  "search.results.count_approximate": "About {count} results",
+  "search.results.count_exact": "{count} results",
+  "search.results.took_ms": "{ms} ms",
+  "search.results.next": "Next page",
+  "search.results.prev": "Previous page",
+  "search.results.blocked.at_end": "This is the last page",
+  "search.results.blocked.at_start": "This is the first page",
+  "search.results.window_exceeded":
+    "This page is deeper than the search can go. Narrow the search instead of paging further.",
+  "search.results.promoted": "Promoted",
+  "search.results.promoted_hint":
+    "This placement is paid for. It is marked because the law requires it, and it does not change what the other results are.",
+  "search.results.distance_km": "{km} km away",
+  "search.results.untitled": "Untitled",
+  "search.results.open": "Open",
+
+  "search.sort.label": "Sort",
+  "search.sort.relevance": "Most relevant",
+  "search.sort.newest": "Newest first",
+  "search.sort.price_asc": "Price: low to high",
+  "search.sort.price_desc": "Price: high to low",
+  "search.sort.distance": "Nearest first",
+  "search.sort.server_chose": "Sorted by {sort}",
+
+  "search.facets.title": "Filters",
+  "search.facets.loading": "Loading filters…",
+  "search.facets.load_failed": "We could not load the filters",
+  "search.facets.empty": "This search offers no filters",
+  "search.facets.clear": "Clear",
+  "search.facets.clear_all": "Clear all filters ({count})",
+  "search.facets.approximate":
+    "Counts are approximate — there were too many candidates to count them all.",
+  "search.facets.skipped":
+    "These filters were not counted for this search: {slugs}",
+  "search.facets.not_counted": "not counted",
+  "search.facets.drill_down_hint":
+    "Each count is what you would get by choosing that value instead of the one you have.",
+  "search.facets.range_from": "From",
+  "search.facets.range_to": "To",
+  "search.facets.range_apply": "Apply",
+
+  "search.geo.title": "Location",
+  "search.geo.radius_km": "Within {km} km",
+  "search.geo.clear": "Anywhere",
+  "search.geo.box": "Inside the shown area",
+  "search.geo.center": "Around {lat}, {lon}",
+
+  "search.url.issues_title": "Part of this link could not be read",
+  "search.url.issue.not_a_number": "{param} is not a number and was ignored",
+  "search.url.issue.geo_incomplete":
+    "the location needs both lat and lon, so it was ignored",
+  "search.url.issue.bbox_malformed":
+    "the area needs four numbers (minLat,minLon,maxLat,maxLon) and was ignored",
+  "search.url.issue.range_malformed":
+    "{param} is not a from..to range and was ignored",
+
+  "search.degraded.title": "What this search could not do",
+  "search.degraded.typo_tolerance":
+    "Typos were not corrected — the search engine in use cannot do it.",
+  "search.degraded.phrase_synonyms":
+    "Synonyms were not expanded — the search engine in use cannot do it.",
+  "search.degraded.exact_total": "The number of results is an estimate.",
+  "search.degraded.exact_facet_counts": "The filter counts are approximate.",
+  "search.degraded.category_rollup":
+    "Subcategories may be missing from these results — the category service did not answer.",
+  "search.degraded.scorer":
+    "The ranking parameter “{scorer}” was not applied — the search engine in use cannot evaluate it.",
+  "search.degraded.unknown":
+    "The search engine reported a limitation this page has no wording for: {raw}",
+
+  "search.ranking.title": "How these results are ordered",
+  "search.ranking.intro":
+    "These are the parameters that determine the order of the results, with their relative weight.",
+  "search.ranking.loading": "Loading the ranking disclosure…",
+  "search.ranking.load_failed": "We could not load the ranking disclosure",
+  "search.ranking.empty": "This deployment declares no ranking parameters",
+  "search.ranking.parameter": "Parameter",
+  "search.ranking.weight": "Weight",
+  "search.ranking.applies_to": "Applies to",
+  "search.ranking.inactive": "Not applied: {reason}",
+  "search.ranking.notes": "Notes",
+  "search.ranking.link": "How these results are ordered",
+};
+
+/**
+ * Register the English bundle into a core i18n engine. Locale bundles ship as
+ * opt-in subpaths (`@stapel/search-react/i18n/ru`, `…/es`) so a host that
+ * needs only English never carries them.
+ */
+export function registerSearchI18n(i18n: I18nEngine): void {
+  i18n.registerBundle("en", searchI18nBundleEn as I18nDictionary);
+}

package/src/i18n/ru.ts

@@ -0,0 +1,126 @@
+import type { I18nDictionary, I18nEngine } from "@stapel/core";
+import { searchErrorBundleRu } from "./generated/errors.ru.gen.js";
+
+export { searchErrorBundleRu } from "./generated/errors.ru.gen.js";
+
+/**
+ * Russian bundle for search-react — the pair's `ru` locale, shipped as the
+ * `@stapel/search-react/i18n/ru` subpath (i18n-shipping.md §2) so the locale
+ * is opt-in: hosts that don't register it never carry these strings (the main
+ * entry does not import this module — gated by size-limit + the bundle-purity
+ * test).
+ *
+ * This is the storefront's DEFAULT language (storefront spec verdict F1:
+ * ru-first), which is why it is the fullest of the three bundles and why the
+ * wording is checked against what a marketplace visitor is actually being
+ * told — "counts are approximate" has to sound like an explanation, not an
+ * apology.
+ *
+ * Composition mirrors `searchI18nBundleEn`: the GENERATED backend error texts
+ * (stapel-search's `translations/errors.ru.json` merged under stapel-core's
+ * cross-cutting catalogue — `pnpm gen:errors`) are spread first for coverage
+ * by construction; the ru UI copy follows.
+ *
+ * PROVENANCE, stated rather than implied: the backend catalogues ship
+ * `origin=seed:authored` and are UNREVIEWED; the pair-authored strings below
+ * are the same grade. Neither is a claim of review.
+ */
+export const searchI18nBundleRu: I18nDictionary = {
+  ...searchErrorBundleRu,
+
+  "search.error.unknown": "Что-то пошло не так при поиске.",
+
+  "search.results.title": "Результаты",
+  "search.results.loading": "Ищем…",
+  "search.results.load_failed": "Не удалось выполнить поиск.",
+  "search.results.empty": "По этому запросу ничего не нашлось.",
+  "search.results.retry": "Повторить",
+  "search.results.count_approximate": "Примерно {count} объявлений",
+  "search.results.count_exact": "{count} объявлений",
+  "search.results.took_ms": "{ms} мс",
+  "search.results.next": "Следующая страница",
+  "search.results.prev": "Предыдущая страница",
+  "search.results.blocked.at_end": "Это последняя страница",
+  "search.results.blocked.at_start": "Это первая страница",
+  "search.results.window_exceeded":
+    "Эта страница глубже, чем поиск умеет выдавать. Уточните запрос вместо перелистывания.",
+  "search.results.promoted": "Продвигается",
+  "search.results.promoted_hint":
+    "Это платное размещение. Мы помечаем его, потому что так требует закон; на остальные результаты это не влияет.",
+  "search.results.distance_km": "{km} км от вас",
+  "search.results.untitled": "Без названия",
+  "search.results.open": "Открыть",
+
+  "search.sort.label": "Сортировка",
+  "search.sort.relevance": "По релевантности",
+  "search.sort.newest": "Сначала новые",
+  "search.sort.price_asc": "Сначала дешевле",
+  "search.sort.price_desc": "Сначала дороже",
+  "search.sort.distance": "Сначала ближние",
+  "search.sort.server_chose": "Отсортировано: {sort}",
+
+  "search.facets.title": "Фильтры",
+  "search.facets.loading": "Загружаем фильтры…",
+  "search.facets.load_failed": "Не удалось загрузить фильтры.",
+  "search.facets.empty": "Для этого поиска фильтров нет.",
+  "search.facets.clear": "Сбросить",
+  "search.facets.clear_all": "Сбросить все фильтры ({count})",
+  "search.facets.approximate":
+    "Счётчики приблизительные — подходящих объявлений слишком много, чтобы пересчитать все.",
+  "search.facets.skipped":
+    "Эти фильтры для текущего поиска не посчитаны: {slugs}",
+  "search.facets.not_counted": "не посчитано",
+  "search.facets.drill_down_hint":
+    "Рядом с каждым значением — сколько будет, если выбрать его вместо текущего.",
+  "search.facets.range_from": "От",
+  "search.facets.range_to": "До",
+  "search.facets.range_apply": "Применить",
+
+  "search.geo.title": "Где искать",
+  "search.geo.radius_km": "В радиусе {km} км",
+  "search.geo.clear": "Везде",
+  "search.geo.box": "В показанной области",
+  "search.geo.center": "Рядом с {lat}, {lon}",
+
+  "search.url.issues_title": "Часть этой ссылки прочитать не удалось",
+  "search.url.issue.not_a_number": "{param} — не число, параметр пропущен",
+  "search.url.issue.geo_incomplete":
+    "для точки нужны и lat, и lon — параметр пропущен",
+  "search.url.issue.bbox_malformed":
+    "для области нужны четыре числа (minLat,minLon,maxLat,maxLon) — параметр пропущен",
+  "search.url.issue.range_malformed":
+    "{param} — не диапазон вида from..to, параметр пропущен",
+
+  "search.degraded.title": "Что этот поиск не смог сделать",
+  "search.degraded.typo_tolerance":
+    "Опечатки не исправлялись — используемый поисковый движок этого не умеет.",
+  "search.degraded.phrase_synonyms":
+    "Синонимы не подставлялись — используемый поисковый движок этого не умеет.",
+  "search.degraded.exact_total": "Число результатов — оценка, а не точный счёт.",
+  "search.degraded.exact_facet_counts": "Счётчики фильтров приблизительные.",
+  "search.degraded.category_rollup":
+    "В выдаче могут отсутствовать подкатегории — сервис категорий не ответил.",
+  "search.degraded.scorer":
+    "Параметр ранжирования «{scorer}» не применялся — используемый движок не умеет его считать.",
+  "search.degraded.unknown":
+    "Поиск сообщил об ограничении, для которого у этой страницы нет формулировки: {raw}",
+
+  "search.ranking.title": "Как упорядочены результаты",
+  "search.ranking.intro":
+    "Ниже — параметры, которые определяют порядок выдачи, и их относительный вес.",
+  "search.ranking.loading": "Загружаем раскрытие ранжирования…",
+  "search.ranking.load_failed": "Не удалось загрузить раскрытие ранжирования.",
+  "search.ranking.empty": "В этой установке параметры ранжирования не объявлены.",
+  "search.ranking.parameter": "Параметр",
+  "search.ranking.weight": "Вес",
+  "search.ranking.applies_to": "Применяется к",
+  "search.ranking.inactive": "Не применяется: {reason}",
+  "search.ranking.notes": "Примечания",
+  "search.ranking.link": "Как упорядочены результаты",
+};
+
+/** Register the ru bundle. Call AFTER `registerSearchI18n` so it layers over
+ * the en floor (merge priority = registration order). */
+export function registerSearchI18nRu(engine: I18nEngine): void {
+  engine.registerBundle("ru", searchI18nBundleRu);
+}

package/src/index.ts

@@ -0,0 +1,154 @@
+/**
+ * `@stapel/search-react` — the headless React pair for stapel-search
+ * (frontend-standard §2). Business + state only, zero visual opinion; the
+ * antd skin lives behind the `./default` subpath and the react-router binding
+ * behind `./router`, so a host that renders its own visuals carries neither.
+ *
+ * ── The one-liner ──────────────────────────────────────────────────────────
+ *
+ * ```tsx
+ * const runtime = createSearchRuntime({ baseUrl: "/search/api/v1/" });
+ * <SearchProvider runtime={runtime}>
+ *   <SearchPage adapter={useRouterSearchParams()} defaultType="listing" />
+ * </SearchProvider>
+ * ```
+ *
+ * No session, no workspace id, no auth client: every endpoint this pair calls
+ * is `AllowAny`, so a storefront's catalogue renders for a visitor who will
+ * never sign in.
+ *
+ * ── The three properties this pair exists to guarantee ─────────────────────
+ *
+ * 1. **The URL is the state.** Text, category, facet filters, ranges, geo,
+ *    sort, page size and the keyset cursor all live in the query string,
+ *    under the BACKEND's own parameter names, and no component keeps a second
+ *    copy. Copying the address into another tab reproduces the page; Back
+ *    removes the last filter; a reload loses nothing. See `state/urlState.ts`.
+ * 2. **The server's honesty survives to the screen.** `facet_meta.approximate`,
+ *    `facet_meta.skipped`, `exact_total` and `degraded[]` are parsed and
+ *    surfaced, never swallowed. A skipped facet's options carry `count: null`,
+ *    not `0` — "we did not count this" and "there are none" are different
+ *    sentences.
+ * 3. **`promoted` is carried, not optional.** DSA Art. 26 marking rides every
+ *    item under every sort; the card slot receives the whole item and the
+ *    default card renders the tag. The P2B Art. 5 ranking disclosure ships as
+ *    a headless bag and a page.
+ *
+ * Layers: api → model → state → headless → i18n. Generated surfaces (the
+ * typed schema, the error map, the manifest, the nav manifest, llms.txt) are
+ * produced by the monorepo `gen:*` drivers from stapel-search's own `docs/`
+ * artifacts and stand under drift gates.
+ */
+
+// ── api ──────────────────────────────────────────────────────────────────────
+export { createSearchApi, searchQueryParams } from "./api/searchApi.js";
+export type { SearchApi } from "./api/searchApi.js";
+export type { Schemas } from "./api/types.js";
+export { SEARCH_SORTS } from "./api/types.js";
+export type {
+  FacetMeta,
+  FacetSelection,
+  RankingResponse,
+  Scorer,
+  SearchDegradation,
+  SearchDegradationKind,
+  SearchGeo,
+  SearchGeoBox,
+  SearchGeoCenter,
+  SearchItem,
+  SearchQueryState,
+  SearchRange,
+  SearchResponse,
+  SuggestParams,
+  SuggestResponse,
+} from "./api/types.js";
+
+// ── state (pure: no React, no router) ────────────────────────────────────────
+export {
+  FILTER_PREFIX,
+  RANGE_PREFIX,
+  SEARCH_PARAM,
+  activeFilterCount,
+  clearFilters,
+  ownsParam,
+  parseSearchState,
+  patchSearchState,
+  setFilterValues,
+  setRangeValue,
+  toggleFilterValue,
+  writeSearchState,
+} from "./state/urlState.js";
+export type {
+  ParseSearchStateOptions,
+  ParsedSearchState,
+  SearchStateIssue,
+  SearchStateIssueCode,
+  SearchStatePatch,
+} from "./state/urlState.js";
+
+export { countIsEstimate, degradationMessageKey, parseDegradations } from "./state/degradations.js";
+
+export { buildFacetGroups, facetOptionLabel } from "./state/facets.js";
+export type {
+  BuildFacetGroupsInput,
+  FacetGroup,
+  FacetOption,
+} from "./state/facets.js";
+
+// ── model (runtime wiring, query keys, context, hooks) ───────────────────────
+export { createSearchRuntime } from "./model/runtime.js";
+export type {
+  SearchRuntime,
+  CreateSearchRuntimeOptions,
+} from "./model/runtime.js";
+export {
+  SearchRuntimeContext,
+  useSearchRuntime,
+  useSearchApi,
+  useSearchAnalytics,
+} from "./model/context.js";
+export { searchQueryKeys } from "./model/queryKeys.js";
+export type { SearchQueryKeyParams } from "./model/queryKeys.js";
+
+export { useRankingDisclosure, useSearchQuery } from "./model/queries.js";
+
+// ── headless (renderless components) ─────────────────────────────────────────
+export { SearchProvider } from "./headless/SearchProvider.js";
+export { SearchStateProvider, useSearchState } from "./headless/SearchStateProvider.js";
+export type {
+  SearchParamsAdapter,
+  SearchStateBag,
+  SearchStateProviderProps,
+} from "./headless/SearchStateProvider.js";
+export { SearchResults } from "./headless/SearchResults.js";
+export type { SearchPageInfo, SearchResultsBag } from "./headless/SearchResults.js";
+export { FacetPanel } from "./headless/FacetPanel.js";
+export type { FacetPanelBag } from "./headless/FacetPanel.js";
+export { RankingDisclosure } from "./headless/RankingDisclosure.js";
+export type { RankingDisclosureBag } from "./headless/RankingDisclosure.js";
+
+// ── nav manifest (the pair's public surface declaration) ─────────────────────
+export { navEntries } from "./nav/manifest.js";
+
+// ── i18n ─────────────────────────────────────────────────────────────────────
+export {
+  SEARCH_I18N_KEYS,
+  searchI18nBundleEn,
+  registerSearchI18n,
+} from "./i18n/keys.js";
+export type { SearchI18nKey } from "./i18n/keys.js";
+
+// ── errors map (code → status/params/remediation/en; generated) ──────────────
+export {
+  SEARCH_ERRORS,
+  SEARCH_ERROR_CODES,
+  SEARCH_BACKEND_UNAVAILABLE,
+  SEARCH_WINDOW_EXCEEDED,
+  searchErrorBundleEn,
+  explainSearchError,
+} from "./i18n/errorsMap.js";
+export type {
+  SearchErrorCode,
+  SearchErrorSpec,
+  Remediation,
+} from "./i18n/errorsMap.js";

package/src/model/context.tsx

@@ -0,0 +1,28 @@
+import type { Context } from "react";
+import { createModuleContext } from "@stapel/core";
+import type { Analytics, ModuleContextKit } from "@stapel/core";
+import type { SearchApi } from "../api/searchApi.js";
+import type { SearchRuntime } from "./runtime.js";
+
+/**
+ * The wired SearchRuntime shared through React context by
+ * `<SearchProvider>`. Hooks in `model/` and `headless/` read the singletons
+ * from here. One reviewed copy of this plumbing lives in `@stapel/core`
+ * (`createModuleContext`, slim wave §21/S2); this module binds it under the
+ * pair's public names.
+ */
+const kit: ModuleContextKit<SearchRuntime> =
+  createModuleContext<SearchRuntime>("Search");
+
+export const SearchRuntimeContext: Context<SearchRuntime | null> =
+  kit.RuntimeContext;
+
+export const useSearchRuntime: () => SearchRuntime = kit.useRuntime;
+
+export const useSearchApi: () => SearchApi = kit.useApi;
+
+export const useSearchAnalytics: () => Analytics | null = kit.useAnalytics;
+
+/** @internal Re-exported as `<SearchProvider>` from `headless/`. */
+export const ModuleProvider: ModuleContextKit<SearchRuntime>["Provider"] =
+  kit.Provider;