@stapel/search-react 0.11.0 → 0.13.0

package/src/headless/useSearchBox.ts

@@ -21,10 +21,36 @@
  *
  * The suggestion list is asked for the DEBOUNCED prefix, not the draft — one
  * request per pause, not per keystroke, on an endpoint the backend throttles.
+ *
+ * ── The box reaches the CATALOGUE, not only the titles ────────────────────
+ *
+ * stapel-search 0.7.0 answers `/suggest` with two halves. Until it did, typing
+ * a word that names a section of the catalogue answered listing titles and
+ * nothing else: on a live classified deployment the search field could not
+ * reach a category at all, and the owner's own navigation canon rules out both
+ * of the usual workarounds — a picker, and a client-side typeahead over the
+ * whole tree.
+ *
+ * The server's answer is neither, and it carries the one thing a client-side
+ * matcher can never have: the number of LIVE listings behind each destination,
+ * computed as one aggregate over the index and equal to what `/query` reports
+ * for the same category. That number is what tells "Menswear / Shorts" from
+ * "Childrenswear / Shorts".
+ *
+ * Everything here is absent-safe. A server that predates 0.7.0 sends no
+ * `categories` key, `suggestCategories` is empty, and the box behaves exactly
+ * as it did — which is not a hypothetical: the key appeared mid-session on a
+ * stand that was redeployed underneath a running client.
  */
 import { useCallback, useEffect, useRef, useState } from "react";
 import { loadStateFromQuery, mapLoad } from "@stapel/core";
 import type { LoadState } from "@stapel/core";
+import {
+  SUGGEST_DEGRADED_CATEGORIES,
+  SUGGEST_DEGRADED_ROLLUP,
+  suggestTerms,
+} from "../api/types.js";
+import type { SuggestAnswer, SuggestCategory } from "../api/types.js";
 import { useSearchState } from "./SearchStateProvider.js";
 import { useSuggest } from "../model/queries.js";
 import {
@@ -55,6 +81,42 @@ export interface SearchBoxBag {
   readonly suggestState: LoadState<readonly string[]>;
   /** A suggestion request is in flight for a prefix nothing is shown for yet. */
   readonly suggestLoading: boolean;
+  /**
+   * CATEGORY destinations for the typed prefix, server-ranked by live listing
+   * count — the primary half of the answer (stapel-search 0.7.0).
+   *
+   * Empty on a server that sends no `categories` key, and empty when the
+   * server could not reach a category provider: see
+   * {@link SearchBoxBag.categoriesUnavailable} for why a surface must tell
+   * those two apart from "nothing matched".
+   *
+   * A category with a count of `0` is already filtered out — see
+   * {@link SearchBoxBag.categoryCountsUnknown}.
+   */
+  readonly categories: readonly SuggestCategory[];
+  /**
+   * The server HAS no category provider for this answer
+   * (`degraded: ["category_suggestions"]`), so `categories` being empty says
+   * nothing about the catalogue.
+   *
+   * A surface must render no group at all rather than an empty one: a heading
+   * over nothing is the box telling a person the catalogue has no section by
+   * that name, which is a claim this answer did not make. It is deliberately
+   * NOT a banner either — the reader is mid-word, the terms half still
+   * answers, and a provider being down is the operator's business, the same
+   * ruling `degradationAudience` already applies to an engine shortfall.
+   */
+  readonly categoriesUnavailable: boolean;
+  /**
+   * The counts on {@link SearchBoxBag.categories} are not answers
+   * (`degraded: ["category_rollup"]`): with no ancestry every stored path is
+   * one segment long, so every count would read `0` for a mechanical reason.
+   *
+   * The rows are still real destinations and are still offered; a surface
+   * prints the path and omits the number, because a catalogue of zeros is
+   * worse than a list with no counts.
+   */
+  readonly categoryCountsUnknown: boolean;
   /** Characters a prefix needs before the index is asked. */
   readonly minSuggestChars: number;
   readonly maxLength: number;
@@ -65,6 +127,25 @@ export interface SearchBoxBag {
   submit(value?: string): void;
   /** Empty the box AND the search (an empty `q` is a valid browse). */
   clear(): void;
+  /**
+   * Follow a category suggestion: narrow the SERP to that section.
+   *
+   * Two decisions, both load-bearing.
+   *
+   * The `category` parameter is set to the server's own
+   * {@link SuggestCategory.category} string, VERBATIM. The server joins the
+   * ancestry itself precisely so a client cannot invent a different join and
+   * silently miss, so nothing here rebuilds it from the path or the slug.
+   *
+   * The typed text is CLEARED in the same write. The row promised a count —
+   * "Menswear / Shorts, 1 240 listings" — and that number is the
+   * section's, not the section's intersected with a title search for the word
+   * that found it. Keeping `q` would land a person on strictly fewer results
+   * than the row they tapped had just quoted, which is the row lying about
+   * where it goes. One `patch` call, so it is also one history entry: Back
+   * returns to the search the person typed.
+   */
+  chooseCategory(category: SuggestCategory): void;
 }
 
 export interface UseSearchBoxOptions {
@@ -81,8 +162,39 @@ export interface UseSearchBoxOptions {
 /** One frozen empty list, so a render with no suggestions is a stable value. */
 const NO_SUGGESTIONS: readonly string[] = [];
 
+/** The same, for the categories half. */
+const NO_CATEGORIES: readonly SuggestCategory[] = [];
+
+/** Does this answer name a shortfall? Absent-safe on every older server. */
+function degradedWith(answer: SuggestAnswer | undefined, literal: string): boolean {
+  return answer?.degraded?.includes(literal) === true;
+}
+
+/**
+ * The destinations worth offering out of one answer.
+ *
+ * A category with a count of `0` is a section with nothing in it: following it
+ * lands the buyer on an empty SERP, which is a dead end dressed as a
+ * destination — and the server does return those (it reads the count with a
+ * `0` default and ranks them last), so somebody has to drop them.
+ *
+ * The one exception is `category_rollup`, where EVERY count is `0` because the
+ * ancestry never arrived rather than because the sections are empty. Filtering
+ * on the count there would delete the whole group for a reason that has
+ * nothing to do with what is in the catalogue, so the rows are kept and the
+ * numbers are what the surface omits.
+ */
+export function offerableCategories(
+  answer: SuggestAnswer | undefined
+): readonly SuggestCategory[] {
+  const categories = answer?.categories;
+  if (categories === undefined || categories.length === 0) return NO_CATEGORIES;
+  if (degradedWith(answer, SUGGEST_DEGRADED_ROLLUP)) return categories;
+  return categories.filter((category) => category.count > 0);
+}
+
 export function useSearchBox(options: UseSearchBoxOptions = {}): SearchBoxBag {
-  const { state, setText } = useSearchState();
+  const { state, setText, patch } = useSearchState();
   const committed = state.q;
   const debounceMs = options.debounceMs ?? SEARCH_BOX_DEBOUNCE_MS;
 
@@ -168,10 +280,21 @@ export function useSearchBox(options: UseSearchBoxOptions = {}): SearchBoxBag {
     enabled: options.suggest !== false,
   });
 
-  const suggestState = mapLoad(
-    loadStateFromQuery(suggest),
-    (data) => data.items as readonly string[]
-  );
+  const suggestState = mapLoad(loadStateFromQuery(suggest), suggestTerms);
+
+  // The READY answer only. A category row is a navigation control, and one
+  // rendered out of a stale answer would send a person somewhere the current
+  // prefix never named.
+  const answer = suggest.data;
+  const categories = offerableCategories(answer);
+
+  const chooseCategory = (category: SuggestCategory): void => {
+    setDraftState("");
+    cancel();
+    // One write, so one history entry — see `SearchBoxBag.chooseCategory` for
+    // why the text goes with it.
+    patch({ q: "", category: category.category });
+  };
 
   return {
     draft,
@@ -180,10 +303,14 @@ export function useSearchBox(options: UseSearchBoxOptions = {}): SearchBoxBag {
     suggestions: suggestState.status === "ready" ? suggestState.data : NO_SUGGESTIONS,
     suggestState,
     suggestLoading: suggest.isLoading && suggest.fetchStatus === "fetching",
+    categories,
+    categoriesUnavailable: degradedWith(answer, SUGGEST_DEGRADED_CATEGORIES),
+    categoryCountsUnknown: degradedWith(answer, SUGGEST_DEGRADED_ROLLUP),
     minSuggestChars: SUGGEST_MIN_CHARS,
     maxLength: SEARCH_QUERY_MAX_CHARS,
     setDraft,
     submit,
     clear,
+    chooseCategory,
   };
 }

package/src/i18n/es.ts

@@ -40,12 +40,18 @@ export const searchI18nBundleEs: I18nDictionary = {
   "search.results.untitled": "Sin título",
   "search.results.open": "Abrir",
   "search.results.image_alt": "Foto de {title}",
+  "search.results.photo_alt": "Foto {index} de {total}: {title}",
+  "search.results.photos": "Fotos",
+  "search.results.photo_unavailable": "Foto no disponible",
 
   "search.box.label": "Buscar",
   "search.box.placeholder": "¿Qué estás buscando?",
   "search.box.submit": "Buscar",
   "search.box.clear": "Borrar la búsqueda",
   "search.box.suggestions": "Sugerencias",
+  "search.box.categories": "Secciones",
+  "search.box.category_count.one": "{count} anuncio",
+  "search.box.category_count.other": "{count} anuncios",
 
   "search.sort.label": "Orden",
   "search.sort.relevance": "Más relevantes",
@@ -93,6 +99,7 @@ export const searchI18nBundleEs: I18nDictionary = {
   "search.filters.dismiss": "Cerrar los filtros",
   "search.filters.chips_label": "Filtros",
   "search.filters.all": "Todos los filtros",
+  "search.filters.short": "Filtros",
   "search.filters.chip_more": ", +{count}",
 
   "search.category.title": "Categoría",
@@ -150,6 +157,10 @@ export const searchI18nBundleEs: I18nDictionary = {
   "search.ranking.inactive": "No aplicado: {reason}",
   "search.ranking.notes": "Notas",
   "search.ranking.link": "Cómo se ordenan estos resultados",
+
+  "search.nav.results": "Buscar",
+  "search.nav.ranking": "Orden de resultados",
+  "search.nav.ranking.short": "Orden",
 };
 
 /** Register the es bundle. Call AFTER `registerSearchI18n`. */

package/src/i18n/keys.ts

@@ -56,6 +56,16 @@ export const SEARCH_I18N_KEYS = {
   resultsOpen: "search.results.open",
   /** Alt text for the card photo — the card's own title, in a sentence. */
   resultsImageAlt: "search.results.image_alt",
+  /** Alt text for one photo of a GALLERY: its place in the strip, and the
+   * card's title. A row of ten photos all called "Photo of X" is ten
+   * identical announcements. */
+  resultsPhotoAlt: "search.results.photo_alt",
+  /** The photo strip's accessible name. `SkinCarousel` takes its label from
+   * the caller for exactly this reason: the token bridge owns no i18n. */
+  resultsPhotos: "search.results.photos",
+  /** The card stores a reference and nothing resolved it — a sentence gets
+   * the wiring fixed; an empty grey box teaches nobody anything. */
+  resultsPhotoUnavailable: "search.results.photo_unavailable",
 
   // ── the query box ────────────────────────────────────────────────────────
   boxLabel: "search.box.label",
@@ -64,6 +74,22 @@ export const SEARCH_I18N_KEYS = {
   boxClear: "search.box.clear",
   /** Accessible name of the suggestion list under the box. */
   boxSuggestions: "search.box.suggestions",
+  /**
+   * The heading over the CATEGORY half of the type-ahead (stapel-search
+   * 0.7.0). The rows under it are DESTINATIONS — a section of the catalogue —
+   * and not, like everything else in the menu, another set of words to search
+   * for; a group with no heading would read as more of the same.
+   */
+  boxCategories: "search.box.categories",
+  /**
+   * "1 240 listings" beside a category row — how many LIVE listings a buyer
+   * would see there, the same number the SERP reports for it.
+   *
+   * A PLURAL FAMILY: render with `tPlural`, never `t`. It counts a noun in
+   * words, so Russian needs its four endings and a single string would be
+   * right only for 5-20 — the exact defect the results count already fixed.
+   */
+  boxCategoryCount: "search.box.category_count",
 
   // ── sort ─────────────────────────────────────────────────────────────────
   sortLabel: "search.sort.label",
@@ -129,6 +155,9 @@ export const SEARCH_I18N_KEYS = {
   /** The leading, icon-only chip: the whole panel. Icon-only means the name
    * exists ONLY here, so this key is the control's entire accessibility. */
   filtersAll: "search.filters.all",
+  /** The same door, named for a 390px row: the location line's trailing link
+   * sits beside a place name and cannot spend six characters on "All". */
+  filtersShort: "search.filters.short",
   /** A chip filtering on more than one value: "Bosch, +2". Not a plural
    * family — nothing is being counted in words. */
   filtersChipMore: "search.filters.chip_more",
@@ -207,6 +236,34 @@ export const SEARCH_I18N_KEYS = {
   rankingInactive: "search.ranking.inactive",
   rankingNotes: "search.ranking.notes",
   rankingLink: "search.ranking.link",
+
+  // ── nav (the destination's own name, not the page's heading) ─────────────
+  /**
+   * What the MENU calls the results screen.
+   *
+   * Separate from `search.results.title` on purpose. That key captions the
+   * list of matches — a heading over rows, which is why it reads "Results" —
+   * and a menu entry pointing at `/s` labelled "Results" tells a visitor
+   * nothing about where they would be going: results of what? The destination
+   * is the search itself. One key, one job; a translator asked to make
+   * "Results" work as both a page heading and a menu label has to pick which
+   * one to get wrong.
+   */
+  navResults: "search.nav.results",
+  /** The menu name of the P2B disclosure PAGE — see {@link navResults} for
+   * why it is not `search.ranking.title`, which is the page's own heading and
+   * a whole sentence. */
+  navRanking: "search.nav.ranking",
+  /**
+   * The compact form for a phone dock — see `NavEntry.shortLabelKey`. A
+   * five-cell dock at 390px gives a destination roughly ten characters, and
+   * "Ranking disclosure" ellipsizes to a fragment there.
+   *
+   * `search.nav.results` needs no short form: it is already one word in every
+   * locale this pair ships, and declaring a short key identical to the long
+   * one only gives a translator two strings to keep in sync.
+   */
+  navRankingShort: "search.nav.ranking.short",
 } as const;
 
 export type SearchI18nKey =
@@ -233,6 +290,7 @@ export const SEARCH_I18N_PLURAL_KEYS: readonly SearchI18nKey[] = [
   SEARCH_I18N_KEYS.resultsCountExact,
   SEARCH_I18N_KEYS.filtersShowCount,
   SEARCH_I18N_KEYS.filtersShowCountAtLeast,
+  SEARCH_I18N_KEYS.boxCategoryCount,
 ];
 
 /**
@@ -270,12 +328,18 @@ export const searchI18nBundleEn: Record<string, string> = {
   "search.results.untitled": "Untitled",
   "search.results.open": "Open",
   "search.results.image_alt": "Photo of {title}",
+  "search.results.photo_alt": "Photo {index} of {total}: {title}",
+  "search.results.photos": "Photos",
+  "search.results.photo_unavailable": "Photo unavailable",
 
   "search.box.label": "Search",
   "search.box.placeholder": "What are you looking for?",
   "search.box.submit": "Search",
   "search.box.clear": "Clear the search",
   "search.box.suggestions": "Suggestions",
+  "search.box.categories": "Sections",
+  "search.box.category_count.one": "{count} listing",
+  "search.box.category_count.other": "{count} listings",
 
   "search.sort.label": "Sort",
   "search.sort.relevance": "Most relevant",
@@ -323,6 +387,7 @@ export const searchI18nBundleEn: Record<string, string> = {
   "search.filters.dismiss": "Close the filters",
   "search.filters.chips_label": "Filters",
   "search.filters.all": "All filters",
+  "search.filters.short": "Filters",
   "search.filters.chip_more": ", +{count}",
 
   "search.category.title": "Category",
@@ -379,6 +444,10 @@ export const searchI18nBundleEn: Record<string, string> = {
   "search.ranking.inactive": "Not applied: {reason}",
   "search.ranking.notes": "Notes",
   "search.ranking.link": "How these results are ordered",
+
+  "search.nav.results": "Search",
+  "search.nav.ranking": "Ranking disclosure",
+  "search.nav.ranking.short": "Ranking",
 };
 
 /**

package/src/i18n/ru.ts

@@ -63,12 +63,20 @@ export const searchI18nBundleRu: I18nDictionary = {
   "search.results.untitled": "Без названия",
   "search.results.open": "Открыть",
   "search.results.image_alt": "Фото: {title}",
+  "search.results.photo_alt": "Фото {index} из {total}: {title}",
+  "search.results.photos": "Фотографии",
+  "search.results.photo_unavailable": "Фото недоступно",
 
   "search.box.label": "Поиск",
   "search.box.placeholder": "Что ищете?",
   "search.box.submit": "Найти",
   "search.box.clear": "Очистить запрос",
   "search.box.suggestions": "Подсказки",
+  "search.box.categories": "Разделы",
+  "search.box.category_count.one": "{count} объявление",
+  "search.box.category_count.few": "{count} объявления",
+  "search.box.category_count.many": "{count} объявлений",
+  "search.box.category_count.other": "{count} объявления",
 
   "search.sort.label": "Сортировка",
   "search.sort.relevance": "По релевантности",
@@ -120,6 +128,7 @@ export const searchI18nBundleRu: I18nDictionary = {
   "search.filters.dismiss": "Закрыть фильтры",
   "search.filters.chips_label": "Фильтры",
   "search.filters.all": "Все фильтры",
+  "search.filters.short": "Фильтры",
   "search.filters.chip_more": ", +{count}",
 
   "search.category.title": "Категория",
@@ -177,6 +186,10 @@ export const searchI18nBundleRu: I18nDictionary = {
   "search.ranking.inactive": "Не применяется: {reason}",
   "search.ranking.notes": "Примечания",
   "search.ranking.link": "Как упорядочены результаты",
+
+  "search.nav.results": "Поиск",
+  "search.nav.ranking": "Порядок результатов",
+  "search.nav.ranking.short": "Порядок",
 };
 
 /** Register the ru bundle. Call AFTER `registerSearchI18n` so it layers over

package/src/index.ts

@@ -44,7 +44,12 @@
 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 {
+  SEARCH_SORTS,
+  SUGGEST_DEGRADED_CATEGORIES,
+  SUGGEST_DEGRADED_ROLLUP,
+  suggestTerms,
+} from "./api/types.js";
 export type {
   FacetMeta,
   FacetSelection,
@@ -59,6 +64,9 @@ export type {
   SearchQueryState,
   SearchRange,
   SearchResponse,
+  SuggestAnswer,
+  SuggestCategory,
+  SuggestCategoryMatch,
   SuggestParams,
   SuggestResponse,
 } from "./api/types.js";
@@ -100,7 +108,12 @@ export type {
   SearchDegradationAudience,
 } from "./state/degradations.js";
 
-export { buildFacetGroups, facetOptionLabel } from "./state/facets.js";
+export {
+  FACETABLE_FEATURE_TYPES,
+  buildFacetGroups,
+  facetOptionLabel,
+  isFacetableFeature,
+} from "./state/facets.js";
 export type {
   BuildFacetGroupsInput,
   FacetGroup,
@@ -132,6 +145,7 @@ export {
 export { createSearchRuntime } from "./model/runtime.js";
 export type {
   SearchRuntime,
+  SearchImageResolver,
   CreateSearchRuntimeOptions,
 } from "./model/runtime.js";
 export {
@@ -157,8 +171,13 @@ export { SearchResults } from "./headless/SearchResults.js";
 export type { SearchPageInfo, SearchResultsBag } from "./headless/SearchResults.js";
 export { FacetPanel, useFacetPanel } from "./headless/FacetPanel.js";
 export type { FacetPanelBag } from "./headless/FacetPanel.js";
+export { useHostFacetLabels } from "./headless/useFacetLabels.js";
+export type {
+  FacetLabelRequest,
+  FacetLabelResolver,
+} from "./headless/useFacetLabels.js";
 export { useAppliedSort } from "./headless/useAppliedSort.js";
-export { useSearchBox } from "./headless/useSearchBox.js";
+export { offerableCategories, useSearchBox } from "./headless/useSearchBox.js";
 export type { SearchBoxBag, UseSearchBoxOptions } from "./headless/useSearchBox.js";
 export { countQueryState, useSearchCount } from "./headless/useSearchCount.js";
 export type {

package/src/model/queries.ts

@@ -6,7 +6,7 @@ import type {
   RankingResponse,
   SearchQueryState,
   SearchResponse,
-  SuggestResponse,
+  SuggestAnswer,
 } from "../api/types.js";
 import { SUGGEST_MAX_LIMIT, SUGGEST_MIN_CHARS } from "../state/limits.js";
 import { useSearchApi } from "./context.js";
@@ -63,11 +63,12 @@ export function useSearchQuery(
 }
 
 /**
- * Title prefixes from the index, for the search box's typeahead.
+ * What the box offers under the cursor: CATEGORIES and title prefixes.
  *
  * Not from a query log: stapel-search keeps none, which is a privacy decision
- * before it is a product one (`services.suggest`). So the list is what exists
- * in the catalogue, and choosing one is always a search that has results.
+ * before it is a product one (`services.suggest`). So both halves are what
+ * exists in the catalogue — choosing a term is always a search that has
+ * results, and choosing a category is always a section that exists.
  *
  * `enabled` is the debounce's partner, not its replacement: the CALLER holds a
  * debounced prefix (see `useSearchBox`) and this hook refuses to ask about a
@@ -83,7 +84,7 @@ export function useSuggest(params: {
   readonly q: string;
   readonly limit?: number;
   readonly enabled?: boolean;
-}): UseQueryResult<SuggestResponse, StapelApiError> {
+}): UseQueryResult<SuggestAnswer, StapelApiError> {
   const api = useSearchApi();
   const q = params.q.trim();
   const limit = params.limit;

package/src/model/queryKeys.ts

@@ -32,6 +32,22 @@ export const searchQueryKeys: {
   query(
     params: SearchQueryKeyParams
   ): readonly ["search", "query", SearchQueryKeyParams];
+  /**
+   * One group's captions from the HOST's resolver — the seam that names a
+   * vocabulary-backed facet value on a server too old to caption it itself.
+   *
+   * Keyed on the slug, the values asked about and the locale. The values are
+   * SORTED by the caller before they get here: the same group arrives in
+   * count order, and count order changes on every click, so an unsorted key
+   * would re-ask the host for the same words each time a sibling facet moved.
+   * The locale is in the key because a caption is copy — one cache entry per
+   * language, never one shared between two.
+   */
+  facetLabels(
+    slug: string,
+    values: readonly string[],
+    locale?: string
+  ): readonly ["search", "facet-labels", string, readonly string[], string | null];
   /** The P2B disclosure. `type` is optional on the endpoint; normalized to
    * `null` so an absent type and an explicit `undefined` cannot cache twice. */
   ranking(type?: string): readonly ["search", "ranking", string | null];
@@ -43,6 +59,13 @@ export const searchQueryKeys: {
 } = {
   all: [ROOT],
   query: (params) => [ROOT, "query", params],
+  facetLabels: (slug, values, locale) => [
+    ROOT,
+    "facet-labels",
+    slug,
+    values,
+    locale ?? null,
+  ],
   ranking: (type) => [ROOT, "ranking", type ?? null],
   suggest: (type, q, limit) => [ROOT, "suggest", type, q, limit ?? null],
 };

package/src/model/runtime.ts

@@ -1,8 +1,36 @@
 import { createModuleRuntime } from "@stapel/core";
 import type { CreateModuleRuntimeOptions, ModuleRuntime } from "@stapel/core";
+import type { StapelImage } from "@stapel/image";
 import { createSearchApi } from "../api/searchApi.js";
 import type { SearchApi } from "../api/searchApi.js";
 
+/**
+ * Turn a stored CDN reference into something renderable.
+ *
+ * ── Why this is a seam and not a URL builder ───────────────────────────────
+ *
+ * A search card's photo fields (`image`, `images`) hold what the indexed doc
+ * type stores, and in this fleet that is an OPAQUE `<type>/<hash>` reference —
+ * the same unit `Listing.images` holds. No contract here resolves a stranger's
+ * reference: stapel-cdn's `file/exists/` is owner-scoped, so
+ * `@stapel/cdn-react`'s `useCdnRef` answers for a person's OWN draft and can
+ * never render somebody else's gallery. A pair that guessed `${base}/${ref}`
+ * would be writing a contract nobody agreed to, and it would break the first
+ * deployment that signs its media paths.
+ *
+ * So the deployment hands its own knowledge in once, exactly as
+ * `@stapel/listings-react`'s `ListingImageResolver` does — one seam, one
+ * spelling, and a container that already has a resolver passes the SAME
+ * function to both runtimes.
+ *
+ * A `StapelImage` rather than a string is what buys the variant ladder: with
+ * `variants` populated, `@stapel/image`'s `<Image>` measures the slot and
+ * picks a tier. A resolver with nothing for a reference returns `undefined`,
+ * and the skin then says "photo unavailable" instead of drawing a broken
+ * `<img>`.
+ */
+export type SearchImageResolver = (ref: string) => StapelImage | undefined;
+
 /**
  * The wired search runtime — core's `ModuleRuntime` bound to this pair's API
  * (slim wave §21/S2). The returned `client` is what the host injects into
@@ -13,7 +41,10 @@ import type { SearchApi } from "../api/searchApi.js";
  * storefront's catalogue, category and search pages need nothing but:
  *
  * ```tsx
- * const runtime = createSearchRuntime({ baseUrl: "/search/api/v1/" });
+ * const runtime = createSearchRuntime({
+ *   baseUrl: "/search/api/v1/",
+ *   resolveImage: (ref) => myCdn.describe(ref),
+ * });
  * <SearchProvider runtime={runtime}>…</SearchProvider>
  * ```
  *
@@ -22,12 +53,20 @@ import type { SearchApi } from "../api/searchApi.js";
  * calls carry it — this pair neither requires nor waits for one, which is why
  * its read hooks are deliberately not gated on `useActiveSessionReady`.
  */
-export type SearchRuntime = ModuleRuntime<SearchApi>;
+export interface SearchRuntime extends ModuleRuntime<SearchApi> {
+  /** See {@link SearchImageResolver}. Absent = a card that stores references
+   * draws the placeholder and names the reason. */
+  readonly resolveImage: SearchImageResolver | undefined;
+}
 
-export type CreateSearchRuntimeOptions = CreateModuleRuntimeOptions;
+export interface CreateSearchRuntimeOptions extends CreateModuleRuntimeOptions {
+  /** See {@link SearchImageResolver}. */
+  readonly resolveImage?: SearchImageResolver;
+}
 
 export function createSearchRuntime(
   options: CreateSearchRuntimeOptions
 ): SearchRuntime {
-  return createModuleRuntime((client) => createSearchApi(client), options);
+  const base = createModuleRuntime((client) => createSearchApi(client), options);
+  return { ...base, resolveImage: options.resolveImage };
 }

package/src/nav/manifest.ts

@@ -15,13 +15,34 @@
  * `menuVisibleDefault: false` on both: the results page is a navigation TARGET
  * reached from the header's search box, and the ranking disclosure is a
  * footer link. Neither is a menu item — the same treatment `auth.login` gets.
+ *
+ * ── A nav label is not a page heading ─────────────────────────────────────
+ *
+ * Both entries carry their OWN label keys (`search.nav.*`) rather than
+ * borrowing the surfaces' captions. `search.results.title` is the heading over
+ * a list of matches, so it reads "Results" — correct above rows, and useless
+ * in a menu, where "Results" answers nothing about where the link goes. The
+ * destination is the search. `search.ranking.title` is worse in the other
+ * direction: it is a whole sentence ("How these results are ordered"), which
+ * is right on the page it captions and cannot be a menu row.
+ *
+ * Sharing one key would also make the two uses move together forever: a
+ * translator improving the heading would silently rewrite the menu, and there
+ * is no locale in which the best heading and the best menu label are reliably
+ * the same words.
+ *
+ * `shortLabelKey` on the disclosure for the same reason one step smaller: a
+ * five-cell phone dock gives a destination roughly ten characters, and
+ * "Ranking disclosure" ellipsizes there to a fragment a person has to guess
+ * at. `search.results` declares none — its label is already one word in every
+ * locale this pair ships.
  */
 import type { NavEntry } from "@stapel/core";
 
 export const navEntries: readonly NavEntry[] = [
   {
     id: "search.results",
-    labelKey: "search.results.title",
+    labelKey: "search.nav.results",
     icon: "SearchOutlined",
     route: { path: "/s" },
     component: { export: "SearchPage", subpath: "default" },
@@ -40,7 +61,8 @@ export const navEntries: readonly NavEntry[] = [
     // be mistaken — by a person or by `stapel/no-string-paths` — for the API
     // operation of the same name.
     id: "search.ranking",
-    labelKey: "search.ranking.title",
+    labelKey: "search.nav.ranking",
+    shortLabelKey: "search.nav.ranking.short",
     icon: "OrderedListOutlined",
     route: { path: "/ranking-disclosure" },
     component: { export: "RankingDisclosurePane", subpath: "default" },