@stapel/search-react 0.11.0 → 0.13.0

package/src/default/SearchBox.tsx

@@ -16,6 +16,16 @@
  *    the catalogue — never a query log, because stapel-search keeps none — so
  *    every suggestion is a search that has results. The endpoint was typed and
  *    unreachable for three releases (S-8).
+ *  - **Reaches the CATALOGUE, not only the titles.** stapel-search 0.7.0
+ *    answers with CATEGORIES too, and they render as their own group above the
+ *    terms: on a live classified deployment, typing a word that names a
+ *    section answered listing titles and nothing else, so the search field
+ *    could not reach a category at all. Each row prints the ancestor path
+ *    (three catalogues have a "Shorts"; only the path tells them apart) and
+ *    the live listing count, and follows the server's own `category` string.
+ *    See
+ *    `useSearchBox` for why the group is absent rather than empty when the
+ *    server says it had no provider.
  *  - **Never grows a "no results" dropdown.** With nothing to suggest the menu
  *    stays shut: an empty popover under a half-typed word says "there is
  *    nothing" about a search that has not run.
@@ -28,16 +38,43 @@
  * as everything else; a header outside one renders `<SearchPage>`'s copy.
  */
 import { useState } from "react";
-import type { ReactElement } from "react";
-import { AutoComplete, Button, Flex, Input } from "antd";
-import { useT } from "@stapel/core";
+import type { ReactElement, ReactNode } from "react";
+import { AutoComplete, Button, Flex, Input, Typography } from "antd";
+import { useT, useTPlural } from "@stapel/core";
 import { SkinTheme } from "@stapel/tokens-antd/skin";
 import { spacing } from "@stapel/tokens";
 import { useSearchBox } from "../headless/useSearchBox.js";
 import type { UseSearchBoxOptions } from "../headless/useSearchBox.js";
+import type { SuggestCategory } from "../api/types.js";
 import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
 import type { ThemeModeProp } from "./types.js";
 
+/**
+ * The separator between the ancestor names of a category row.
+ *
+ * The same one the vocabulary and hierarchical formatters use fleet-wide, so a
+ * path reads identically in the box, on a card and in the composer.
+ */
+const PATH_SEPARATOR = " / ";
+
+/** Marks a menu row as a DESTINATION rather than a search term.
+ *
+ * The kind travels on the option OBJECT and never inside its `value`: a
+ * category's `category` string and a title prefix are both strings, and
+ * telling them apart by sniffing the text is how a term that happens to look
+ * like a path silently navigates somewhere. */
+interface BoxOption {
+  readonly value: string;
+  readonly label?: ReactNode;
+  readonly stapelCategory?: SuggestCategory;
+}
+
+/** A labelled group of rows — antd renders the label as a group heading. */
+interface BoxOptionGroup {
+  readonly label: ReactNode;
+  readonly options: BoxOption[];
+}
+
 export interface SearchBoxProps extends ThemeModeProp, UseSearchBoxOptions {
   /** Override the placeholder — a category page says what it searches. */
   readonly placeholder?: string;
@@ -47,6 +84,33 @@ export interface SearchBoxProps extends ThemeModeProp, UseSearchBoxOptions {
   readonly autoFocus?: boolean;
 }
 
+/** One destination row: the ancestor path, and how many live listings are
+ * behind it. */
+function CategoryRow(props: {
+  readonly category: SuggestCategory;
+  readonly showCount: boolean;
+}): ReactElement {
+  const tPlural = useTPlural();
+  const { category } = props;
+  return (
+    <Flex
+      justify="space-between"
+      align="center"
+      gap={spacing[2]}
+      data-testid={`search-box-category-${category.category}`}
+    >
+      {/* The whole path, not the leaf: three catalogues have a "Shorts", and
+          the path is the only thing that says which one this is. */}
+      <span>{category.path.join(PATH_SEPARATOR)}</span>
+      {props.showCount && (
+        <Typography.Text type="secondary">
+          {tPlural(SEARCH_I18N_KEYS.boxCategoryCount, { count: category.count })}
+        </Typography.Text>
+      )}
+    </Flex>
+  );
+}
+
 export function SearchBox(props: SearchBoxProps): ReactElement {
   const t = useT();
   const {
@@ -59,7 +123,62 @@ export function SearchBox(props: SearchBoxProps): ReactElement {
   const box = useSearchBox(boxOptions);
   const [open, setOpen] = useState(false);
 
-  const options = box.suggestions.map((value) => ({ value }));
+  const categoryOptions: BoxOption[] = box.categories.map(
+    (category) => ({
+      // The server's own string, verbatim — it is unique per row and it is
+      // exactly what the SERP's `category` parameter takes.
+      value: category.category,
+      label: (
+        <CategoryRow
+          category={category}
+          showCount={!box.categoryCountsUnknown}
+        />
+      ),
+      stapelCategory: category,
+    })
+  );
+  const termOptions: BoxOption[] = box.suggestions.map((value) => ({ value }));
+
+  /*
+   * Destinations FIRST, then terms.
+   *
+   * A classified's box is a navigation control before it is a text filter:
+   * the person who typed a section's name wants the section, and the titles
+   * that happen to contain the word are the fallback, not the answer. The
+   * server ranks the destinations by live listing count and this list keeps
+   * that order.
+   *
+   * The group is absent — not empty — when the server had no category
+   * provider, which falls out of `box.categories` being empty: a heading over
+   * nothing would be the box claiming the catalogue has no such section, a
+   * claim the answer never made. See `useSearchBox`.
+   */
+  const options: (BoxOption | BoxOptionGroup)[] =
+    categoryOptions.length > 0
+      ? [
+          {
+            label: (
+              <span data-testid="search-box-categories-heading">
+                {t(SEARCH_I18N_KEYS.boxCategories)}
+              </span>
+            ),
+            options: categoryOptions,
+          },
+          ...(termOptions.length > 0
+            ? [
+                {
+                  label: (
+                    <span data-testid="search-box-terms-heading">
+                      {t(SEARCH_I18N_KEYS.boxSuggestions)}
+                    </span>
+                  ),
+                  options: termOptions,
+                },
+              ]
+            : []),
+        ]
+      : termOptions;
+  const hasOptions = categoryOptions.length > 0 || termOptions.length > 0;
 
   return (
     <SkinTheme
@@ -75,10 +194,19 @@ export function SearchBox(props: SearchBoxProps): ReactElement {
           // open state is the skin's, not antd's: the prop that reports the
           // menu opening was renamed between antd 5 and 6 and this package
           // supports both, so nothing here asks antd when to open.
-          open={open && options.length > 0}
+          open={open && hasOptions}
           style={{ flex: 1, minWidth: 0 }}
-          onSelect={(value: string) => {
+          onSelect={(value: string, option: BoxOption | BoxOptionGroup) => {
             setOpen(false);
+            // A destination navigates; a term searches. The kind is read off
+            // the option OBJECT, never sniffed out of the text — see
+            // `BoxOption`.
+            const category =
+              "stapelCategory" in option ? option.stapelCategory : undefined;
+            if (category !== undefined) {
+              box.chooseCategory(category);
+              return;
+            }
             box.submit(value);
           }}
           onChange={(value: string) => {

package/src/default/SearchPage.tsx

@@ -71,6 +71,7 @@ import type { FeatureDef } from "@stapel/attributes-react";
 import { SearchStateProvider, useSearchState } from "../headless/SearchStateProvider.js";
 import type { SearchParamsAdapter } from "../headless/SearchStateProvider.js";
 import { useFacetPanel } from "../headless/FacetPanel.js";
+import type { FacetLabelResolver } from "../headless/useFacetLabels.js";
 import { useAppliedCount } from "../headless/useAppliedCount.js";
 import type { ParseSearchStateOptions } from "../state/urlState.js";
 import type { SearchGeo } from "../api/types.js";
@@ -147,13 +148,40 @@ export interface SearchPageProps extends ThemeModeProp, ParseSearchStateOptions
   readonly renderCard?: SearchCardRenderer;
   readonly categoryFeatures?: readonly FeatureDef[];
   readonly locale?: string;
+  /**
+   * Name the facet values neither the answer nor the category schema names —
+   * see {@link FacetLabelResolver}.
+   *
+   * Set once here and it reaches BOTH filter surfaces, the desktop panel and
+   * the phone chip row, the same way `geoLabel` does. It is the seam a
+   * `ref_select` facet needs: its config carries a pointer to a vocabulary and
+   * no option table, the vocabulary is a service this pair does not talk to,
+   * and a server older than stapel-search 0.4.0 sends no `facet_labels` to
+   * cover for it — so without this the chips print `apple` and `128-gb`.
+   */
+  readonly resolveFacetLabels?: FacetLabelResolver;
   /** Render the query box at the top. `false` for a container whose HEADER
    * already mounts `<SearchBox>` — one box per screen, not two. */
   readonly searchBox?: boolean;
   /** BCP-47 tags this deployment indexes, for the language filter. */
   readonly languages?: readonly string[];
-  /** The catalogue picker slot — see {@link FacetPanelPaneProps}. */
+  /**
+   * The catalogue picker slot — see {@link FacetPanelPaneProps}.
+   *
+   * It reaches TWO surfaces: the filter panel's category row, and — on the
+   * phone — the LEADING chip of the filter row, which opens the same control
+   * in the same kind of sheet as every other chip. The owner's navigation
+   * model chooses levels 1-2 from tiles and everything deeper as a
+   * characteristic, and on a result list that is what a chip is.
+   */
   readonly renderCategoryFilter?: (slot: CategoryFilterSlotProps) => ReactNode;
+  /**
+   * What the current category is CALLED — the chip's own text. The pair holds
+   * a path of slugs and no way to turn one into a catalogue name; absent, the
+   * chip states the path's last segment. See
+   * {@link FilterChipsProps.categoryLabel}.
+   */
+  readonly categoryLabel?: ReactNode;
   /** The location control slot (`geo-react`). */
   readonly renderGeoFilter?: (slot: GeoFilterSlotProps) => ReactNode;
   /**
@@ -273,9 +301,11 @@ interface SearchPageBodyProps {
   readonly renderCard?: SearchCardRenderer;
   readonly categoryFeatures?: readonly FeatureDef[];
   readonly locale?: string;
+  readonly resolveFacetLabels?: FacetLabelResolver;
   readonly searchBox?: boolean;
   readonly languages?: readonly string[];
   readonly renderCategoryFilter?: (slot: CategoryFilterSlotProps) => ReactNode;
+  readonly categoryLabel?: ReactNode;
   readonly renderGeoFilter?: (slot: GeoFilterSlotProps) => ReactNode;
   readonly geoLabel?: ReactNode;
   readonly footer?: ReactNode;
@@ -301,11 +331,12 @@ interface SearchPageBodyProps {
 function SearchPageBody(props: SearchPageBodyProps): ReactElement {
   const t = useT();
   const tPlural = useTPlural();
-  const { categoryFeatures, locale, filtersHeader } = props;
+  const { categoryFeatures, locale, resolveFacetLabels, filtersHeader } = props;
   const { state } = useSearchState();
   const facets = useFacetPanel({
     ...(categoryFeatures !== undefined ? { categoryFeatures } : {}),
     ...(locale !== undefined ? { locale } : {}),
+    ...(resolveFacetLabels !== undefined ? { resolveFacetLabels } : {}),
   });
   const applied = useAppliedCount();
   const surface = useDialogSurface();
@@ -379,6 +410,7 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
           {...(layout === "sheet" ? { heading: null } : {})}
           {...(categoryFeatures !== undefined ? { categoryFeatures } : {})}
           {...(locale !== undefined ? { locale } : {})}
+          {...(resolveFacetLabels !== undefined ? { resolveFacetLabels } : {})}
           {...(props.languages !== undefined ? { languages: props.languages } : {})}
           {...(props.renderCategoryFilter !== undefined
             ? { renderCategoryFilter: props.renderCategoryFilter }
@@ -392,9 +424,32 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
     </Flex>
   );
 
-  // The toolbar over the results: how they are ARRANGED, how they are ORDERED,
-  // how many per page — and the surface's own action at the trailing end.
-  const toolbar = (
+  /*
+   * The toolbar over the results: how they are ARRANGED, how they are ORDERED,
+   * how many per page — and the surface's own action at the trailing end.
+   *
+   * TWO shapes, because at 390px the desktop shape is not a smaller version of
+   * itself, it is four stacked rows. The phone form is the reference's own
+   * sort row: the ordering at one end, the surface's action at the other, one
+   * line, nothing else. `pageSize` is already the surface's call; the view
+   * switch draws nothing for a single view and stays in the row for the
+   * surfaces that offer two.
+   */
+  const phoneToolbar = layout === "sheet";
+  const toolbar = phoneToolbar ? (
+    <Flex
+      align="center"
+      justify="space-between"
+      gap={spacing[2]}
+      style={{ width: "100%" }}
+    >
+      <Flex align="center" gap={spacing[2]} style={{ minWidth: 0 }}>
+        <ViewSwitch views={views} value={view.id} onChange={changeView} />
+        <SortSelect compact />
+      </Flex>
+      {props.resultsAction}
+    </Flex>
+  ) : (
     <Flex align="center" wrap gap={spacing[3]}>
       <ViewSwitch views={views} value={view.id} onChange={changeView} />
       <SortSelect />
@@ -406,6 +461,7 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
   const results = (
     <SearchResultsPane
       toolbar={toolbar}
+      {...(phoneToolbar ? { header: "compact" as const } : {})}
       headingLevel={props.resultsHeadingLevel ?? 1}
       {...(view.render !== undefined ? { renderResults: view.render } : {})}
       {...(view.layout !== undefined ? { layout: view.layout } : {})}
@@ -456,10 +512,24 @@ function SearchPageBody(props: SearchPageBodyProps): ReactElement {
             }}
             {...(categoryFeatures !== undefined ? { categoryFeatures } : {})}
             {...(locale !== undefined ? { locale } : {})}
+            {...(resolveFacetLabels !== undefined ? { resolveFacetLabels } : {})}
+            /* The catalogue picker becomes the row's leading chip. The panel
+               behind the circle keeps its own copy of the control; both write
+               the same `category` parameter, so they cannot disagree. */
+            {...(props.renderCategoryFilter !== undefined
+              ? { renderCategoryFilter: props.renderCategoryFilter }
+              : {})}
+            {...(props.categoryLabel !== undefined
+              ? { categoryLabel: props.categoryLabel }
+              : {})}
             {...(props.renderGeoFilter !== undefined
               ? { renderGeoFilter: props.renderGeoFilter }
               : {})}
             {...(props.geoLabel !== undefined ? { geoLabel: props.geoLabel } : {})}
+            /* The row above already states the location and opens its own
+               sheet, so the chip would be the second control over one filter
+               — see `FilterChipsProps.geoChip`. */
+            {...(props.resultsHeader !== undefined ? { geoChip: false } : {})}
           />
           <SkinDialog
             open={sheetOpen}
@@ -512,9 +582,11 @@ export function SearchPage(props: SearchPageProps): ReactElement {
     renderCard,
     categoryFeatures,
     locale,
+    resolveFacetLabels,
     searchBox,
     languages,
     renderCategoryFilter,
+    categoryLabel,
     renderGeoFilter,
     geoLabel,
     defaultGeo,
@@ -543,9 +615,11 @@ export function SearchPage(props: SearchPageProps): ReactElement {
           {...(renderCard !== undefined ? { renderCard } : {})}
           {...(categoryFeatures !== undefined ? { categoryFeatures } : {})}
           {...(locale !== undefined ? { locale } : {})}
+          {...(resolveFacetLabels !== undefined ? { resolveFacetLabels } : {})}
           {...(searchBox !== undefined ? { searchBox } : {})}
           {...(languages !== undefined ? { languages } : {})}
           {...(renderCategoryFilter !== undefined ? { renderCategoryFilter } : {})}
+          {...(categoryLabel !== undefined ? { categoryLabel } : {})}
           {...(renderGeoFilter !== undefined ? { renderGeoFilter } : {})}
           {...(geoLabel !== undefined ? { geoLabel } : {})}
           {...(footer !== undefined ? { footer } : {})}

package/src/default/SearchResultCard.tsx

@@ -18,11 +18,14 @@
  *
  * ── Two things this card used to get wrong ────────────────────────────────
  *
- * 1. **It declared `image_url` and drew nothing.** A text-only card in a
- *    classifieds search is not a card; the field was in `GENERIC_CARD_FIELDS`
- *    and in no render path. It is drawn now, through `@stapel/image`, so the
- *    aspect box lands before the network does and a dead URL renders a named
- *    placeholder instead of the browser's torn-page icon.
+ * 1. **It read a photo shape nothing in this fleet emits.** `card.image` was
+ *    read as an object with a `url` key and `card.image_url` as the fallback;
+ *    what the fleet actually stores is a `<type>/<hash>` CDN reference, and
+ *    where it does store an object that object carries `ref` + `variants[]`
+ *    and no top-level `url`. So every consumer that did not pass its own
+ *    `renderCard` got a card with no photo at all. `cardPhotos.ts` reads the
+ *    real shapes, through the runtime's `resolveImage` seam, and the whole
+ *    `images[]` gallery rather than one photo.
  * 2. **The marking's EXPLANATION was in a `Tooltip`.** Touch has no hover, so
  *    on the device most of this traffic arrives from, the sentence the law is
  *    actually about was unreachable — the tag said "Promoted" and nothing on
@@ -47,11 +50,14 @@ import { useMemo } from "react";
 import type { CSSProperties, ReactElement, ReactNode } from "react";
 import { Card, Flex, Typography } from "antd";
 import { Image } from "@stapel/image";
-import type { StapelImage } from "@stapel/image";
+import { SkinCarousel } from "@stapel/tokens-antd/skin";
 import { useFormat, useT } from "@stapel/core";
 import type { Format } from "@stapel/core";
 import { cssVar, fontSize, fontWeight, radii, spacing } from "@stapel/tokens";
 import type { SearchItem } from "../api/types.js";
+import { useSearchRuntime } from "../model/context.js";
+import { readCardPhotos } from "./cardPhotos.js";
+import type { CardPhotos } from "./cardPhotos.js";
 import { SEARCH_I18N_KEYS } from "../i18n/keys.js";
 
 /** What the card slot is handed. */
@@ -78,7 +84,11 @@ export const GENERIC_CARD_FIELDS: readonly string[] = [
   "price",
   "currency",
   "location",
-  "image_url",
+  // The gallery, and the singular first photo the projection keeps beside it
+  // (`images[0]`). Both hold CDN references; see `cardPhotos.ts`. The old
+  // `image_url` is gone — no backend in this fleet ever wrote it.
+  "images",
+  "image",
   "url",
 ];
 
@@ -150,41 +160,130 @@ const PROMOTED_TAG: CSSProperties = {
   whiteSpace: "nowrap",
 };
 
-/** The photo's box: a 4:3 well the image fills, drawn before it loads. */
-const PHOTO: CSSProperties = {
+/**
+ * The shape of one photo well, everywhere on this card. Declared once so the
+ * placeholder and the loaded photo cannot drift into two different crops, and
+ * so the well is on screen before the network answers.
+ */
+const CARD_PHOTO_ASPECT = "4 / 3";
+
+/** The placeholder well: the box the photo would have occupied. */
+const PHOTO_ABSENT: CSSProperties = {
+  display: "flex",
+  flexDirection: "column",
+  alignItems: "center",
+  justifyContent: "center",
+  gap: spacing[1],
   width: "100%",
-  aspectRatio: "4 / 3",
+  aspectRatio: CARD_PHOTO_ASPECT,
   overflow: "hidden",
   borderRadius: radii.md,
   background: cssVar("surface-sunken"),
+  color: cssVar("text-muted"),
 };
 
+/** The slide's own fill — the strip's well owns the shape. */
+const PHOTO_FILL: CSSProperties = { width: "100%", height: "100%" };
+
+/** A camera outline in `currentColor` — no icon dependency, and it inherits
+ * the theme rather than carrying a colour. `aria-hidden` because the sentence
+ * beside it is the label. */
+function CameraGlyph(): ReactElement {
+  return (
+    <svg
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M3 8.5A2.5 2.5 0 0 1 5.5 6h1.7l1.2-2h6.2l1.2 2h1.7A2.5 2.5 0 0 1 20 8.5v8A2.5 2.5 0 0 1 17.5 19h-11A2.5 2.5 0 0 1 4 16.5z" />
+      <circle cx="12" cy="12.5" r="3.2" />
+    </svg>
+  );
+}
+
 /**
- * A plain `image_url` as the descriptor `<Image>` consumes.
+ * The card's photos — the whole gallery, as a swipeable strip.
+ *
+ * ── Why the strip is OUTSIDE the card's anchor ────────────────────────────
+ *
+ * `<SkinCarousel>` is a scroll container with its own tab stop, and a
+ * horizontal swipe that ends inside an `<a>` is a swipe the browser may
+ * deliver as a click. Inside the anchor, every attempt to look at photo two
+ * would navigate to the result — the defect that makes phone galleries
+ * unusable. So it sits above the anchor as a sibling, exactly as
+ * `<ListingSerpCard>` does it, and the anchor still covers everything a
+ * person reads.
  *
- * A doc type that stores a bare URL has no variant ladder and no dimensions —
- * `source: "link"` is exactly that case, and `<Image>` degrades to the single
- * URL rather than pretending to shop a tier. A doc type that stores the whole
- * `StapelImage` snapshot (`card.image`) gets the ladder, blur-up and all.
+ * Three states, and they are three different facts. No photo FIELD at all —
+ * a doc type that indexes text — draws nothing, because reserving a 4:3 well
+ * for a corpus that has no photos is a hole in every row. A field with
+ * nothing behind it draws the well and says the photo is unavailable: that is
+ * usually an unwired `resolveImage`, and a sentence gets it fixed where an
+ * empty grey box does not. Anything else is the strip.
  */
-function cardImage(card: Readonly<Record<string, unknown>>): StapelImage | undefined {
-  const rich = card["image"];
-  if (rich !== null && typeof rich === "object" && "url" in rich) {
-    return rich as StapelImage;
+function CardPhotoStrip(props: {
+  photos: CardPhotos;
+  title: string;
+}): ReactElement | null {
+  const t = useT();
+  const { photos, title } = props;
+  if (photos.stored === 0) return null;
+
+  if (photos.images.length === 0) {
+    const caption = t(SEARCH_I18N_KEYS.resultsPhotoUnavailable);
+    return (
+      <div
+        role="img"
+        aria-label={caption}
+        data-testid="search-result-photo-absent"
+        style={PHOTO_ABSENT}
+      >
+        <CameraGlyph />
+        <Typography.Text type="secondary" style={{ fontSize: fontSize.xs.fontSize }}>
+          {caption}
+        </Typography.Text>
+      </div>
+    );
   }
-  const url = text(card["image_url"]);
-  if (url === undefined) return undefined;
-  return {
-    source: "link",
-    url,
-    mime: null,
-    width: null,
-    height: null,
-    aspect: null,
-    square: false,
-    preview_b64: null,
-    variants: [],
-  };
+
+  const total = photos.images.length;
+  // A one-photo strip gets neither a peek nor dots: the sliver of a next
+  // slide is an affordance for something that is there.
+  const many = total > 1;
+  return (
+    <SkinCarousel
+      label={t(SEARCH_I18N_KEYS.resultsPhotos)}
+      aspectRatio={CARD_PHOTO_ASPECT}
+      peek={many}
+      dots={many}
+      data-testid="search-result-photos"
+    >
+      {photos.images.map((image, index) => (
+        <Image
+          key={`${String(index)}:${image.url}`}
+          meta={image}
+          alt={
+            many
+              ? t(SEARCH_I18N_KEYS.resultsPhotoAlt, {
+                  index: index + 1,
+                  total,
+                  title,
+                })
+              : t(SEARCH_I18N_KEYS.resultsImageAlt, { title })
+          }
+          fit="cover"
+          data-testid="search-result-photo"
+          style={PHOTO_FILL}
+        />
+      ))}
+    </SkinCarousel>
+  );
 }
 
 /**
@@ -208,6 +307,7 @@ export function SearchResultCard(props: SearchCardProps): ReactElement {
   const t = useT();
   const format = useFormat();
   const card = props.item.card;
+  const resolve = useSearchRuntime().resolveImage;
   const title = text(card["title"]) ?? t(SEARCH_I18N_KEYS.resultsUntitled);
   const price = formatCardPrice(format, text(card["price"]), text(card["currency"]));
   const href = text(card["url"]);
@@ -218,48 +318,32 @@ export function SearchResultCard(props: SearchCardProps): ReactElement {
           km: props.item.distance_km.toFixed(1),
         })
       : undefined;
-  // Memoised on the two fields it reads: a fresh `meta` identity every render
-  // is a load `<Image>` has to decide is or is not the same one.
-  const image = useMemo(() => cardImage(card), [card]);
+  // Memoised on the card and the resolver: a host resolver is a plain
+  // function returning a fresh object, so resolving inline hands `<Image>` a
+  // new `meta` identity on every render — a load it then has to decide is or
+  // is not the same one.
+  const photos = useMemo(() => readCardPhotos(card, resolve), [card, resolve]);
 
   const body = (
-    <Flex vertical gap={spacing[2]}>
-      {image !== undefined && (
-        <div style={PHOTO} data-testid="search-result-photo">
-          {/* The WELL owns the shape (4:3, drawn before the network answers),
-              so the image is told to fill it. Without an explicit box the
-              image's own container reserves height only from the snapshot's
-              `aspect` — which a doc type storing a bare `image_url` does not
-              have — and a `cover` image inside a zero-height parent is a
-              photo that loaded and was never seen. */}
-          <Image
-            meta={image}
-            alt={t(SEARCH_I18N_KEYS.resultsImageAlt, { title })}
-            fit="cover"
-            style={{ width: "100%", height: "100%" }}
-          />
-        </div>
+    <Flex vertical gap={spacing[1]}>
+      <Typography.Text strong>{title}</Typography.Text>
+      {/* The price is the strongest line on a catalogue card: it is what the
+          eye scans a grid for. It used to share a type step with the location
+          and sit under a disclosure three times its size. */}
+      {price !== undefined && (
+        <Typography.Text
+          strong
+          style={{ fontSize: fontSize.lg.fontSize }}
+          data-testid="search-result-price"
+        >
+          {price}
+        </Typography.Text>
+      )}
+      {(location !== undefined || distance !== undefined) && (
+        <Typography.Text type="secondary">
+          {[location, distance].filter((v) => v !== undefined).join(" · ")}
+        </Typography.Text>
       )}
-      <Flex vertical gap={spacing[1]}>
-        <Typography.Text strong>{title}</Typography.Text>
-        {/* The price is the strongest line on a catalogue card: it is what
-            the eye scans a grid for. It used to share a type step with the
-            location and sit under a disclosure three times its size. */}
-        {price !== undefined && (
-          <Typography.Text
-            strong
-            style={{ fontSize: fontSize.lg.fontSize }}
-            data-testid="search-result-price"
-          >
-            {price}
-          </Typography.Text>
-        )}
-        {(location !== undefined || distance !== undefined) && (
-          <Typography.Text type="secondary">
-            {[location, distance].filter((v) => v !== undefined).join(" · ")}
-          </Typography.Text>
-        )}
-      </Flex>
     </Flex>
   );
 
@@ -272,6 +356,8 @@ export function SearchResultCard(props: SearchCardProps): ReactElement {
       styles={{ body: { padding: spacing[3] } }}
     >
       <Flex vertical gap={spacing[2]}>
+        {/* A SIBLING of the anchor, never a child — see `CardPhotoStrip`. */}
+        <CardPhotoStrip photos={photos} title={title} />
         {href === undefined ? (
           body
         ) : (