@stapel/listings-react 0.18.2 → 0.20.0

package/src/api/listingsApi.ts

@@ -4,6 +4,7 @@ import type {
   FavoriteToggleResponse,
   ListingActionResponse,
   ListingDetail,
+  ListingEngagementBatch,
   ListingDraft,
   ListingDraftPatch,
   ListingPageParams,
@@ -15,6 +16,7 @@ import type {
   PublishResponse,
 } from "./types.js";
 import type { ValidationBatchResult } from "@stapel/attributes-react";
+import { engagementIds } from "./types.js";
 
 /**
  * The pair's typed operation surface — one method per stapel-listings endpoint
@@ -123,6 +125,33 @@ export interface ListingsApi {
     options?: { readonly signal?: AbortSignal }
   ): Promise<PaginatedListingCards>;
 
+  /**
+   * The per-viewer OVERLAY for a whole page of cards, in one call.
+   *
+   * `{listing id: {view_count, viewed, is_favorited}}`, with an id that has
+   * no listing simply absent. This is the endpoint that makes the engagement
+   * flags visible on the two surfaces that matter: a storefront's feed and
+   * its SERP are served by the SEARCH index, whose stored card cannot hold a
+   * flag that differs per reader or a counter that moves faster than a
+   * re-index, so the grid draws the card from search and asks HERE for the
+   * three things that are about the person looking.
+   *
+   * `AllowAny` upstream, deliberately: `view_count` is public and both
+   * per-viewer flags answer `null` for a guest, so a storefront makes the
+   * same request signed in or not and a guest's grid is not a second code
+   * path.
+   *
+   * Ids are normalized by `engagementIds` before they get here — sorted,
+   * de-duplicated and capped at `LISTINGS_ENGAGEMENT_BATCH_LIMIT`, because
+   * the server TRUNCATES a longer list rather than refusing it and a short
+   * answer to a long question is the kind of absence this pair does not
+   * render.
+   */
+  engagement(
+    ids: readonly number[],
+    options?: { readonly signal?: AbortSignal }
+  ): Promise<ListingEngagementBatch>;
+
   /**
    * Start a draft. `category_id` is the only required member: the server
    * forces `owner=request.user` and `status=draft` in `perform_create`, so a
@@ -254,6 +283,16 @@ export function createListingsApi(client: StapelClient): ListingsApi {
         ...signal(options),
       }),
 
+    // One comma-separated value rather than a repeated parameter, for the
+    // reason `statusQuery` gives: both spellings are accepted upstream
+    // (`getlist("ids")` then splits on commas), and this one survives every
+    // `query` serializer a host's own StapelClient might carry.
+    engagement: (ids, options) =>
+      client.get(`${COLLECTION}engagement/`, {
+        query: { ids: engagementIds(ids).join(",") },
+        ...signal(options),
+      }),
+
     createDraft: (body) => client.post(COLLECTION, body),
 
     saveDraft: (id, body) => client.post(`${listingPath(id)}save-draft/`, body),

package/src/api/types.ts

@@ -38,11 +38,110 @@ import type { components } from "./generated/schema.js";
 /** The generated schema table — the one source of truth for wire shapes. */
 export type Schemas = components["schemas"];
 
+/**
+ * The engagement fields, named off the GENERATED row so a rename upstream
+ * breaks the build here rather than going quiet on a grid.
+ *
+ * These were hand-written mirrors while this pair's contract pin sat at
+ * `>=0.12 <0.13` and the emitted schema could not see stapel-listings
+ * 0.16/0.17. The pin has landed, so the mirrors are gone and the names come
+ * from `Schemas["ListingCard"]`. What is kept is the OPTIONALITY, and that is
+ * not laziness:
+ *
+ * **A generated type is a promise about the contract, not about the bytes a
+ * particular deployment sends.** The schema says every card carries `viewed`
+ * and `view_count`; a storefront pointed at a server still running 0.15 gets
+ * rows without them, and the two surfaces this feature exists for — a feed
+ * and a SERP — are served by the SEARCH index, whose stored document carries
+ * neither by construction. `Partial` is what keeps `model/engagement.ts`
+ * allowed to ask, and every reader there answers "absent" with the same
+ * silence it answers `null` with.
+ */
+export type ListingEngagementFields = Partial<
+  Pick<Schemas["ListingCard"], "viewed" | "view_count">
+>;
+
+/** A generated row with its engagement fields relaxed to optional — see
+ * {@link ListingEngagementFields} for why every row type below is spelled
+ * this way rather than taken from `Schemas` whole. */
+type WithOptionalEngagement<Row extends ListingEngagementFields> = Omit<
+  Row,
+  keyof ListingEngagementFields
+> &
+  ListingEngagementFields;
+
+/**
+ * The per-viewer overlay for ONE listing, as the batch read answers it.
+ *
+ * Note what is REQUIRED here and optional on the row: the overlay always
+ * carries all three keys, because it is the answer to a question that was
+ * actually asked. A row that carries none of them was serialized by a build
+ * that had never heard of them.
+ */
+export type ListingEngagement = Schemas["ListingEngagement"];
+
+/**
+ * `GET /listings/engagement/?ids=…` 200 — `{listing id: overlay}`.
+ *
+ * The keys are the ids as STRINGS (a DRF `DictField`), and an id with no
+ * listing is simply absent rather than present-and-empty. Both facts are why
+ * `model/engagement.ts` looks entries up through one function instead of
+ * indexing the object at call sites.
+ */
+export type ListingEngagementBatch = Schemas["ListingEngagementBatch"];
+
+/**
+ * The most ids one overlay call may carry — `ENGAGEMENT_BATCH_LIMIT`
+ * upstream, which silently TRUNCATES anything longer ("one page of cards, not
+ * a crawl of the board").
+ *
+ * Mirrored here so the truncation happens where it can be seen and named
+ * rather than in a response that quietly came back short. A page of more than
+ * a hundred cards is not a page; a caller that has one should ask per screen.
+ */
+export const LISTINGS_ENGAGEMENT_BATCH_LIMIT = 100;
+
+/**
+ * Normalize the ids on a page into the exact list the request sends.
+ *
+ * Sorted, de-duplicated, non-integer values dropped, capped at
+ * {@link LISTINGS_ENGAGEMENT_BATCH_LIMIT}. Sorting is what makes the cache
+ * key honest: the answer is a MAP keyed by id, so two renders that ask for
+ * the same ids in different orders are asking the identical question and must
+ * not buy two cache entries and two requests. De-duplication is the same
+ * argument for a grid that shows one listing twice (a promoted slot above the
+ * organic result it also occupies).
+ *
+ * `queryKeys.engagement` and `api.engagement` are both built from THIS, so
+ * the key cannot drift from the request it stands for.
+ */
+export function engagementIds(ids: readonly number[]): readonly number[] {
+  const seen = new Set<number>();
+  for (const id of ids) {
+    if (Number.isInteger(id)) seen.add(id);
+  }
+  return [...seen].sort((a, b) => a - b).slice(0, LISTINGS_ENGAGEMENT_BATCH_LIMIT);
+}
+
 /** `GET /listings/{pk}/` 200 — everything a detail page reads. */
-export type ListingDetail = Schemas["ListingDetail"];
+export type ListingDetail = WithOptionalEngagement<Schemas["ListingDetail"]>;
 
-/** One row of a card list (`GET /listings/`, `GET /listings/my/favorites/`). */
-export type ListingCard = Schemas["ListingCard"];
+/**
+ * One row of a card list (`GET /listings/`, `GET /listings/my/favorites/`) —
+ * and the PROP every card component in this pair takes, which is why its
+ * engagement fields are optional where the schema makes them required.
+ *
+ * The schema is right about this module's own responses: `GET /listings/`
+ * carries `viewed` and `view_count` on every row. But the card components are
+ * handed rows from elsewhere, and the most important elsewhere is the SEARCH
+ * index — `@stapel/search-react` fills `renderCard` with a stored document
+ * that cannot hold a per-reader flag by construction. Requiring the fields on
+ * the prop would make the pair's primary consumer unable to satisfy its own
+ * type, for data no one can supply; it is precisely the case
+ * `<ListingEngagementScope>` exists to answer. A deployment running a server
+ * older than 0.16 is the same shape of fact.
+ */
+export type ListingCard = WithOptionalEngagement<Schemas["ListingCard"]>;
 
 /** `POST /listings/` request+response and `POST /{pk}/save-draft/` response —
  * the draft twin. Every user-editable field is a `*_draft` one, promoted onto
@@ -74,7 +173,12 @@ export type DeleteResponse = Schemas["DeleteResponse"];
 
 /** The keyset envelope both public card lists come back in
  * (`IDAnchorPagination`). */
-export type PaginatedListingCards = Schemas["PaginatedListingCardList"];
+export type PaginatedListingCards = Omit<
+  Schemas["PaginatedListingCardList"],
+  "items"
+> & {
+  items: ListingCard[];
+};
 
 /**
  * One row of `GET /listings/my/listings/` — the OWNER's card.
@@ -93,12 +197,17 @@ export type PaginatedListingCards = Schemas["PaginatedListingCardList"];
  *    tab keyed off them is a column of blank rows. `myListingTitle` /
  *    `myListingPrice` (`model/mine.ts`) are the one place the fallback lives.
  */
-export type MyListingCard = Schemas["MyListingCard"];
+export type MyListingCard = WithOptionalEngagement<Schemas["MyListingCard"]>;
 
 /** The keyset envelope `GET /listings/my/listings/` comes back in — the same
  * `IDAnchorPagination` shape as {@link PaginatedListingCards}, over the owner
  * row. */
-export type PaginatedMyListingCards = Schemas["PaginatedMyListingCardList"];
+export type PaginatedMyListingCards = Omit<
+  Schemas["PaginatedMyListingCardList"],
+  "items"
+> & {
+  items: MyListingCard[];
+};
 
 /**
  * The nine lifecycle states, as `models.ListingStatus` declares them.

package/src/default/GateReasonPopover.tsx

@@ -26,11 +26,47 @@
  * screen (see `ListingCardBlockedReason`). The rule's disables below are the
  * documented decision §2.4 asks for, not a hole.
  *
+ * ── Why the disclosure is CONTROLLED, and why activation PINS it ──────────
+ *
+ * An uncontrolled popover triggered by hover AND click treats the click as a
+ * TOGGLE, so the natural pointer gesture — rest on the control, then press it
+ * — opens the disclosure on the hover and closes it again on the press. The
+ * overlay comes back marked `ant-popover-hidden` and the person has pressed
+ * the one control that was supposed to explain itself and watched it go
+ * blank. Reproduced in jsdom and gated by `test/favoriteGesture.test.tsx`.
+ *
+ * So `open` is this component's own state. The first version of that made
+ * activation MONOTONIC for the duration of the click's own dispatch — a flag
+ * set in the capture phase and dropped a microtask later — and it closed the
+ * toggle, which was the half of the problem a synthetic click can show.
+ *
+ * It was not the half a THUMB meets, and the deployed measurement (walker
+ * D72, pass 7, the whole timeline in `logs-fp8/fp8-d72-diag3.json`) is
+ * unambiguous about which half that is. A real tap DOES open this: the
+ * overlay loses `ant-popover-hidden` 7 ms after `click`. Then the emulated
+ * hover the tap carried ENDS — a finger that has lifted is hovering nothing —
+ * `mouseleave` arrives ~10 ms later, antd's `mouseLeaveDelay` runs its 0.1 s,
+ * the leave motion runs, and the overlay is hidden again ~260 ms after it
+ * appeared. A quarter-second flash on a phone is indistinguishable from a
+ * control that did nothing, which is exactly how six passes read it. The
+ * microtask flag could not see this: the closer is not the click's toggle,
+ * it is a TIMER two hundred milliseconds behind the gesture.
+ *
+ * A disclosure that a person deliberately opened therefore PINS: once
+ * activated it stays open until it is dismissed, and hover-out, blur and the
+ * trigger's own toggle may no longer close it. Dismissal is the two gestures
+ * that mean "I am done reading" — a pointer down outside the control and
+ * outside the overlay, or `Escape` — and this component listens for both
+ * itself, because refusing antd's close is what takes them away.
+ *
+ * Hover keeps its old, unpinned behaviour: a cursor that rests on the control
+ * opens it and a cursor that leaves closes it, with no click involved.
+ *
  * Deliberately NOT exported from `src/default/index.ts`: it is how this
  * pair's own gated hearts speak, not a control a host composes with — the
  * same standing `favorite.tsx` has.
  */
-import { useId } from "react";
+import { useCallback, useEffect, useId, useRef, useState } from "react";
 import type { ReactElement, ReactNode } from "react";
 import { Flex, Typography } from "antd";
 // eslint-disable-next-line stapel/no-tooltip-in-skin -- interaction disclosure, not a hover: opens on click/tap and focus too, anchored to a non-disabled control, with the reason kept in the a11y tree via aria-describedby (see this file's header)
@@ -64,6 +100,59 @@ export interface GateReasonPopoverProps {
 
 export function GateReasonPopover(props: GateReasonPopoverProps): ReactElement {
   const reasonId = useId();
+  const [open, setOpen] = useState(false);
+  // Set by an ACTIVATION and cleared only by a dismissal. While it is set,
+  // every close antd asks for — the click's own toggle, the hover-out timer,
+  // a blur — is refused; see the file header.
+  const pinned = useRef(false);
+  // The two regions a dismissing gesture must NOT land in: the control itself
+  // (pressing it again restates the refusal) and the overlay (the sign-in
+  // door lives in there, and closing on its own pointerdown would take the
+  // link away before the click that follows it).
+  const anchorRef = useRef<HTMLDivElement | null>(null);
+  const overlayRef = useRef<HTMLDivElement | null>(null);
+
+  const dismiss = useCallback((): void => {
+    pinned.current = false;
+    setOpen(false);
+  }, []);
+
+  const handleOpenChange = useCallback((next: boolean): void => {
+    if (!next && pinned.current) return;
+    setOpen(next);
+  }, []);
+
+  const activate = useCallback((): void => {
+    pinned.current = true;
+    setOpen(true);
+  }, []);
+
+  // Antd closes an unpinned popover on an outside click of its own; a pinned
+  // one has to be given those gestures back, or it would be a panel with no
+  // way out on the one device that most needs the pin.
+  useEffect(() => {
+    if (!open) return undefined;
+    const doc = anchorRef.current?.ownerDocument ?? document;
+    const outside = (target: EventTarget | null): boolean =>
+      target instanceof Node &&
+      anchorRef.current?.contains(target) !== true &&
+      overlayRef.current?.contains(target) !== true;
+    const onPointerDown = (event: Event): void => {
+      if (outside(event.target)) dismiss();
+    };
+    const onKeyDown = (event: KeyboardEvent): void => {
+      if (event.key === "Escape") dismiss();
+    };
+    // Capture, so a handler that stops propagation on its own container
+    // cannot leave this stuck open.
+    doc.addEventListener("pointerdown", onPointerDown, true);
+    doc.addEventListener("keydown", onKeyDown, true);
+    return () => {
+      doc.removeEventListener("pointerdown", onPointerDown, true);
+      doc.removeEventListener("keydown", onKeyDown, true);
+    };
+  }, [open, dismiss]);
+
   return (
     <>
       {/* The floor: the reason reaches AT without a pointer, popover or no
@@ -75,11 +164,15 @@ export function GateReasonPopover(props: GateReasonPopoverProps): ReactElement {
       {/* eslint-disable-next-line stapel/no-tooltip-in-skin -- interaction disclosure, not a hover: click/tap and focus open it too, and the reason stays in the a11y tree (header) */}
       <Popover
         trigger={["hover", "focus", "click"]}
+        open={open}
+        onOpenChange={handleOpenChange}
         content={
-          <Flex vertical gap={spacing[1]} data-testid={props.testId}>
-            <Typography.Text>{props.reason}</Typography.Text>
-            <SignInLink cta={props.cta} testId={props.signInTestId} />
-          </Flex>
+          <div ref={overlayRef}>
+            <Flex vertical gap={spacing[1]} data-testid={props.testId}>
+              <Typography.Text>{props.reason}</Typography.Text>
+              <SignInLink cta={props.cta} testId={props.signInTestId} />
+            </Flex>
+          </div>
         }
       >
         {/* A plain wrapper takes the props Popover clones onto its direct
@@ -87,8 +180,22 @@ export function GateReasonPopover(props: GateReasonPopoverProps): ReactElement {
             OVERWRITES that child's `aria-describedby` in both states. With
             the wrapper in between, the control keeps its own wiring to the
             hidden copy whether the disclosure is open or closed, and the
-            events still arrive: hover, focus and click all bubble. */}
-        <div>{props.children({ "aria-describedby": reasonId })}</div>
+            events still arrive: hover, focus and click all bubble.
+
+            The two capture listeners are the tap's half of the fix. `click`
+            covers a mouse and a thumb; `keydown` covers Enter and Space,
+            which a browser does NOT turn into a click on a button carrying
+            `aria-disabled` in every engine. Capture, so they run before the
+            popover's own toggle sees the same event. */}
+        <div
+          ref={anchorRef}
+          onClickCapture={activate}
+          onKeyDownCapture={(event) => {
+            if (event.key === "Enter" || event.key === " ") activate();
+          }}
+        >
+          {props.children({ "aria-describedby": reasonId })}
+        </div>
       </Popover>
     </>
   );

package/src/default/ListingCard.tsx

@@ -93,7 +93,11 @@
  * `<GatedControl>`, which renders it as text linked by `aria-describedby` —
  * a disabled antd button receives no pointer events and is not focusable, so
  * the `Tooltip` this component used to offer as a "quieter" volume was a
- * reason nobody could read on any device. That arm is gone; `blockedReason`
+ * reason nobody could read on any device. The heart itself is never
+ * html-`disabled` in ANY volume for the same reason: it carries
+ * `aria-disabled` and a live handler, and refuses on ACTIVATION (the gate
+ * makes `toggle` a no-op). An inert control cannot be tapped, cannot be
+ * focused, and cannot disclose anything. That arm is gone; `blockedReason`
  * is "text" (reason + door), "line" (reason alone, for a grid), or
  * "popover" — the reason and the door disclosed on the heart itself, with
  * the reason still in the accessibility tree. The third arm is NOT the old
@@ -103,7 +107,7 @@
 import type { CSSProperties, ReactElement, ReactNode } from "react";
 import { Card, Flex, Typography, theme as antdTheme } from "antd";
 import { SkinButton as Button } from "@stapel/tokens-antd/skin";
-import { GatedControl, SkinTheme } from "@stapel/tokens-antd/skin";
+import { ErrorAlert, GatedControl, SkinTheme } from "@stapel/tokens-antd/skin";
 import { useActionGate, useT } from "@stapel/core";
 import type { LinkComponent, SignInCtaProp } from "@stapel/core";
 import { spacing } from "@stapel/tokens";
@@ -112,6 +116,8 @@ import type { ListingCard as ListingCardData } from "../api/types.js";
 import { asFeatureDaoList, featuresDtoFromDaoList, featuresFromDaoList } from "../model/features.js";
 import type { FeatureCopySource } from "../model/features.js";
 import { lifecycleCaption } from "../model/status.js";
+import { isListingViewed } from "../model/engagement.js";
+import { useEngagedListing } from "../headless/Engagement.js";
 import { useFavoriteToggle } from "../headless/Favorites.js";
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
 import { GateReasonPopover } from "./GateReasonPopover.js";
@@ -211,6 +217,35 @@ export const CARD_MAIN_CLASS = "stapel-listing-card-main";
  * (`<ListingCard>`), so the row arm gets the inset the stacked arm does not. */
 export const CARD_BLEED_CLASS = "stapel-listing-card-bleed";
 
+/**
+ * The class an ALREADY-SEEN card carries — the mark every mature classified
+ * puts on a result you have opened before, and the reason a shopper on their
+ * third evening of the same search is not re-reading the same twenty offers.
+ *
+ * All three card surfaces take it, and all three take it on their OUTER box,
+ * so the rule below can reach the photo and the reading column while leaving
+ * the favourite heart at full strength: a dimmed heart reads as a disabled
+ * heart, and the one control on the card must not look switched off because
+ * the card behind it is old news.
+ */
+export const CARD_VIEWED_CLASS = "stapel-listing-card-seen";
+
+/**
+ * How far a seen card is dimmed.
+ *
+ * OPACITY and not a colour, which is the whole reason this needs no dark-mode
+ * arm: opacity composites the card against whatever ground the theme painted,
+ * so the same number is a grey card on a white page and a dim card on a black
+ * one. A `color` here would have to be picked twice, and the second pick is
+ * the one nobody photographs. 0.55 is far enough to sort seen from unseen at
+ * a glance and not so far that the price stops being readable — a seen
+ * listing is still a listing, not a disabled control.
+ *
+ * A host that wants another value sets `--listing-viewed-opacity` on any
+ * ancestor; the rule reads the property and falls back to this.
+ */
+export const LISTING_VIEWED_OPACITY = 0.55;
+
 /** The `href` the hoisted card stylesheet is deduplicated by. */
 export const CARD_TARGET_STYLE_HREF = "stapel-listings-card-target";
 
@@ -276,6 +311,12 @@ export function cardTargetCss(): string {
       `${bleed}{padding-block:var(--listing-card-inset);` +
       `padding-inline-start:var(--listing-card-inset)}` +
       `}`,
+    // Already seen. The photo and everything inside the card's anchor dim
+    // together; the heart is outside the anchor and stays as it was — see
+    // CARD_VIEWED_CLASS.
+    `.${CARD_VIEWED_CLASS} .${CARD_TARGET_CLASS},` +
+      `.${CARD_VIEWED_CLASS} .${CARD_MEDIA_CLASS}` +
+      `{opacity:var(--listing-viewed-opacity,${String(LISTING_VIEWED_OPACITY)})}`,
   ].join("");
 }
 
@@ -413,7 +454,10 @@ export function CardTarget(
 
 export function ListingCard(props: ListingCardProps): ReactElement {
   const t = useT();
-  const { listing } = props;
+  // The engagement scope's answer laid over the row, when a container opened
+  // one — the same object otherwise. A card fed by search carries no
+  // `viewed`/`is_favorited` of its own; see `headless/Engagement.tsx`.
+  const listing = useEngagedListing(props.listing);
   const favorite = useFavoriteToggle(listing.id, listing.is_favorited);
   const { token } = antdTheme.useToken();
 
@@ -433,6 +477,18 @@ export function ListingCard(props: ListingCardProps): ReactElement {
 
   const favoriteGate = useActionGate(favorite.gate);
   const blockedReason = props.blockedReason ?? "text";
+  // Absent on every response the fleet answers today, and a plain `false`
+  // when it is — no dimming, no attribute, nothing said about it.
+  const viewed = isListingViewed(listing);
+  // A saved heart is a SOLID accent shape; an unsaved one is the outline it
+  // has always been. `is_favorited: null` reads as unsaved (`favorite`
+  // resolves the third state), never as a look of its own.
+  const heartIcon = (
+    <HeartIcon
+      filled={favorite.favorited}
+      {...(favorite.favorited ? { color: token.colorPrimary } : {})}
+    />
+  );
 
   const favoriteLabel = t(
     favorite.favorited
@@ -521,6 +577,11 @@ export function ListingCard(props: ListingCardProps): ReactElement {
         {...(status !== undefined
           ? { "data-listing-status": status.status }
           : {})}
+        // Both only when the server actually said so: absent and `null` leave
+        // the card byte-identical to what it renders today.
+        {...(viewed
+          ? { className: CARD_VIEWED_CLASS, "data-listing-viewed": "true" }
+          : {})}
         // The body's own padding is zero because the frame fills the card and
         // the photo runs edge to edge when it is stacked: padding here would
         // be a strip of card around a picture. The text block inside the
@@ -588,7 +649,7 @@ export function ListingCard(props: ListingCardProps): ReactElement {
                             data-analytics="none"
                             data-analytics-reason="business action — host app wraps with its own tracked()"
                             onClick={favorite.toggle}
-                            icon={<HeartIcon filled={favorite.favorited} />}
+                            icon={heartIcon}
                           />
                         </Flex>
                       )}
@@ -603,11 +664,12 @@ export function ListingCard(props: ListingCardProps): ReactElement {
                         {(bind) => (
                           <Flex justify="flex-end" style={{ width: "100%" }}>
                             <Button
-                              disabled={bind.disabled}
-                              data-disabled-reason="the enclosing <GatedControl> renders the gate's reason beside this button"
-                              {...(bind["aria-describedby"] !== undefined
-                                ? { "aria-describedby": bind["aria-describedby"] }
-                                : {})}
+                              // The substrate's binding, spread whole: it now
+                              // owns "never inert" for the whole fleet —
+                              // `disabled` stays false, `aria-disabled` and
+                              // `tabIndex` come from it, and the reason is
+                              // wired by `aria-describedby`.
+                              {...bind}
                               aria-label={favoriteLabel}
                               aria-pressed={favorite.favorited}
                               data-testid="listings-card-favorite"
@@ -615,7 +677,7 @@ export function ListingCard(props: ListingCardProps): ReactElement {
                               data-analytics="none"
                               data-analytics-reason="business action — host app wraps with its own tracked()"
                               onClick={favorite.toggle}
-                              icon={<HeartIcon filled={favorite.favorited} />}
+                              icon={heartIcon}
                             />
                           </Flex>
                         )}
@@ -637,6 +699,18 @@ export function ListingCard(props: ListingCardProps): ReactElement {
                       )}
                     </>
                   )}
+
+                  {/* A save that did not save. The heart has already rolled
+                      back to what it was, which is the honest picture but a
+                      silent one — a person who watched the icon flip and flip
+                      back deserves the sentence too. The pair's one error
+                      surface, in its inline volume, because a boxed alert
+                      inside a grid cell would re-lay the whole row. */}
+                  <ErrorAlert
+                    testId="listings-card-favorite-error"
+                    thrown={favorite.error}
+                    variant="inline"
+                  />
                 </div>
               )}
             </div>