@stapel/listings-react 0.18.2 → 0.19.0

package/src/default/ListingPrice.tsx

@@ -37,8 +37,19 @@ import {
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
 
 export interface ListingPriceProps {
-  /** The amount as the wire spells it — a decimal string. */
-  readonly amount: string | undefined;
+  /**
+   * The amount as the wire spells it — a decimal string, or `null` for a
+   * listing that carries no price at all.
+   *
+   * `null` is in the TYPE since stapel-listings 0.17 spelled it in the
+   * schema (`price?: string | null`, D51: a blank price stays null
+   * server-side). It was always in the DATA — `hasAmount` below has guarded
+   * for it from the start, with a comment saying the serializer hands it
+   * through an unguarded `string | undefined`. Now the type says what the
+   * runtime already knew, and the guard stops being a defence against its
+   * own signature.
+   */
+  readonly amount: string | null | undefined;
   /** The code the amount is quoted in (`Listing.currency`). */
   readonly currency?: string | undefined;
 }

package/src/default/ListingSerpCard.tsx

@@ -88,6 +88,8 @@ import {
 } 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 { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
 import { PriceTrendIcon } from "./icons.js";
 import { FavoriteHeart } from "./favorite.js";
@@ -97,6 +99,7 @@ import {
   CARD_MEDIA_CLASS,
   CARD_QUERY_CLASS,
   CARD_TARGET_STYLE_HREF,
+  CARD_VIEWED_CLASS,
   CardTarget,
   cardTargetCss,
 } from "./ListingCard.js";
@@ -172,7 +175,9 @@ const BODY: CSSProperties = { flex: "1 1 auto", minWidth: 0 };
 
 export function ListingSerpCard(props: ListingSerpCardProps): ReactElement {
   const t = useT();
-  const { listing, priceTrend } = props;
+  const { priceTrend } = props;
+  // See `<ListingCard>`: the scope's overlay over the row, or the row.
+  const listing = useEngagedListing(props.listing);
   const { token } = antdTheme.useToken();
 
   const badgeDaos = asFeatureDaoList(listing.features_badges);
@@ -200,6 +205,8 @@ export function ListingSerpCard(props: ListingSerpCardProps): ReactElement {
   const photos = listing.images ?? [];
   const currency =
     listing.currency !== undefined ? { currency: listing.currency } : {};
+  // Already seen — `false` for every response that carries no such field.
+  const viewed = isListingViewed(listing);
 
   const rail =
     props.actionsRail !== undefined || props.showFavorite !== false ? (
@@ -240,6 +247,9 @@ export function ListingSerpCard(props: ListingSerpCardProps): ReactElement {
         {...(status !== undefined
           ? { "data-listing-status": status.status }
           : {})}
+        {...(viewed
+          ? { className: CARD_VIEWED_CLASS, "data-listing-viewed": "true" }
+          : {})}
         styles={{ body: { minWidth: 0, padding: token.paddingSM } }}
         style={{ ["--listing-card-focus" as string]: token.colorPrimary }}
       >

package/src/default/favorite.tsx

@@ -26,8 +26,9 @@
  * list or a grid of these cards should wrap it in one.
  */
 import type { CSSProperties, ReactElement } from "react";
+import { theme as antdTheme } from "antd";
 import { SkinButton as Button } from "@stapel/tokens-antd/skin";
-import { GatedControl } from "@stapel/tokens-antd/skin";
+import { ErrorAlert, GatedControl } from "@stapel/tokens-antd/skin";
 import type { SignInCta } from "@stapel/core";
 import { useActionGate, useT } from "@stapel/core";
 import { useFavoriteToggle } from "../headless/Favorites.js";
@@ -70,22 +71,49 @@ export interface FavoriteHeartProps {
  * (`signIn`) is the surface's business, not this control's — a disabled antd
  * button fires no pointer events, so a tooltip here would be a reason nobody
  * could read on any device (`stapel/no-tooltip-in-skin`).
+ *
+ * ── It is never html-`disabled`, in either volume ─────────────────────────
+ *
+ * `aria-disabled` plus a live handler, always. The refusal happens on
+ * ACTIVATION — `useFavoriteToggle().toggle` is a no-op while the gate is
+ * blocked, so the click cannot write anything — and that is the only shape of
+ * refusal a person can interrogate. A `disabled` DOM button is inert: it
+ * takes no focus, receives no pointer events, and swallows the very tap that
+ * was supposed to explain it. Measured on a phone: a signed-out visitor's
+ * heart produced no toast, no reason and no navigation, and on a touch device
+ * there is no hover to fall back on.
  */
 export function FavoriteHeart(props: FavoriteHeartProps): ReactElement {
   const t = useT();
+  const { token } = antdTheme.useToken();
   const favorite = useFavoriteToggle(props.listingId, props.favorited);
   const label = t(
     favorite.favorited
       ? LISTINGS_I18N_KEYS.cardFavoriteRemove
       : LISTINGS_I18N_KEYS.cardFavoriteAdd
   );
+  // Saved is a SOLID accent shape, not-saved is the outline. `is_favorited:
+  // null` — an anonymous read's "nobody asked" — resolves to not-saved in the
+  // bag, so it draws the outline and never a third look of its own.
+  const icon = (
+    <HeartIcon
+      filled={favorite.favorited}
+      {...(favorite.favorited ? { color: token.colorPrimary } : {})}
+    />
+  );
   // The RESOLVED sentence, not the gate's key — `useActionGate` is the one
   // place a blocked reason becomes words in this fleet.
   const reason = useActionGate(favorite.gate).reason;
+  // A failed save, stated where the heart is. The rollback already put the
+  // icon back; this says why it went back.
+  const failure = (
+    <ErrorAlert
+      testId={`${props.testId}-error`}
+      thrown={favorite.error}
+      variant="inline"
+    />
+  );
   if (props.blockedReason === "popover" && reason !== undefined) {
-    // `aria-disabled`, never `disabled`: the gate already refuses the action
-    // (`toggle` is a no-op while blocked), and an html-disabled button
-    // swallows the hover, the focus and the tap the disclosure opens on.
     return (
       <GateReasonPopover
         reason={reason}
@@ -105,7 +133,7 @@ export function FavoriteHeart(props: FavoriteHeartProps): 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={icon}
             {...(props.style !== undefined ? { style: props.style } : {})}
           />
         )}
@@ -120,22 +148,22 @@ export function FavoriteHeart(props: FavoriteHeartProps): ReactElement {
       {...(props.style !== undefined ? { style: props.style } : {})}
     >
       {(bind) => (
-        <Button
-          shape="circle"
-          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"] }
-            : {})}
-          aria-label={label}
-          aria-pressed={favorite.favorited}
-          data-testid={props.testId}
-          data-favorited={String(favorite.favorited)}
-          data-analytics="none"
-          data-analytics-reason="business action — host app wraps with its own tracked()"
-          onClick={favorite.toggle}
-          icon={<HeartIcon filled={favorite.favorited} />}
-        />
+        <>
+          <Button
+            shape="circle"
+            // See `<ListingCard>`: the substrate's binding, spread whole.
+            {...bind}
+            aria-label={label}
+            aria-pressed={favorite.favorited}
+            data-testid={props.testId}
+            data-favorited={String(favorite.favorited)}
+            data-analytics="none"
+            data-analytics-reason="business action — host app wraps with its own tracked()"
+            onClick={favorite.toggle}
+            icon={icon}
+          />
+          {failure}
+        </>
       )}
     </GatedControl>
   );

package/src/default/icons.tsx

@@ -13,14 +13,32 @@
  */
 import type { ReactElement } from "react";
 
-export function HeartIcon(props: { filled: boolean }): ReactElement {
+export interface HeartIconProps {
+  /** Saved: the glyph is a solid shape rather than an outline. THE state a
+   * person reads off a card, so it is the one prop this icon has. */
+  readonly filled: boolean;
+  /**
+   * The accent a SAVED heart is painted in — an antd theme token the caller
+   * resolved (`token.colorPrimary`), never a literal.
+   *
+   * The icon stays `currentColor` by default, which is what keeps it
+   * theme-neutral in every other state; this is the one place a colour is
+   * warranted, because "filled" and "outline" of the same neutral grey is a
+   * difference a person reads at a glance on a mock-up and misses entirely on
+   * a 170px feed tile in daylight.
+   */
+  readonly color?: string;
+}
+
+export function HeartIcon(props: HeartIconProps): ReactElement {
+  const paint = props.color ?? "currentColor";
   return (
     <svg
       width="16"
       height="16"
       viewBox="0 0 24 24"
-      fill={props.filled ? "currentColor" : "none"}
-      stroke="currentColor"
+      fill={props.filled ? paint : "none"}
+      stroke={paint}
       strokeWidth="2"
       strokeLinecap="round"
       strokeLinejoin="round"

package/src/default/index.ts

@@ -39,6 +39,10 @@ export {
   // threshold (and for a test that measures it). See `<ListingCard>`'s header.
   LISTING_CARD_ROW_MIN,
   LISTING_CARD_ROW_MEDIA,
+  // The already-seen mark, for a container that wants to dim its own chrome
+  // on the same rule (and for a test that reads it). All three cards take it.
+  CARD_VIEWED_CLASS,
+  LISTING_VIEWED_OPACITY,
 } from "./ListingCard.js";
 export type {
   ListingCardProps,

package/src/headless/Engagement.tsx

@@ -0,0 +1,177 @@
+/**
+ * The ENGAGEMENT OVERLAY as a scope: one request for a page of cards, read by
+ * every card in it without a single extra prop.
+ *
+ * ── The problem this shape exists to solve ────────────────────────────────
+ *
+ * `viewed`, `view_count` and `is_favorited` are on stapel-listings' own card
+ * and detail serializers, so a listing PAGE and this module's own card list
+ * carry them and need nothing here. The two surfaces a buyer actually
+ * scrolls do not: a storefront's home feed and its SERP are drawn by
+ * `@stapel/search-react` from the search index, whose stored document can
+ * hold neither a flag that differs per reader nor a counter that moves faster
+ * than a re-index. Those rows reach `<ListingCard>` with no engagement fields
+ * at all — so without this, every card on the two screens the feature was
+ * built for renders undimmed with an outline heart no matter what the person
+ * has done, and nothing anywhere reports a fault.
+ *
+ * ── Why a SCOPE and not a prop ────────────────────────────────────────────
+ *
+ * Because the cost is per PAGE and the reader is per CARD, and a design that
+ * puts those in the same place gets one of them wrong. A `engagement` prop on
+ * the card would make each card responsible for its own answer, and the
+ * shortest way to satisfy that is one request per card — forty requests for a
+ * decoration, which is the exact N+1 the batch endpoint exists to prevent.
+ * The container knows the page; the card knows its id. So the container opens
+ * a scope with the ids it just rendered, ONE query runs, and each card looks
+ * itself up. It is the arrangement `GateReasonScopeContext` / `<PaneGate>`
+ * already use in this fleet for the same shape of problem.
+ *
+ * ```tsx
+ * <ListingEngagementScope ids={items.map((item) => item.id)}>
+ *   <FeedGrid>
+ *     {items.map((item) => <ListingFeedCard key={item.id} listing={item.card} … />)}
+ *   </FeedGrid>
+ * </ListingEngagementScope>
+ * ```
+ *
+ * ── No scope is a first-class answer ──────────────────────────────────────
+ *
+ * A card outside a scope fires NOTHING and draws from its row exactly as it
+ * did before this module existed — which is right for this module's own card
+ * list and for the listing page, whose rows already carry the fields. Absent,
+ * empty, in-flight and FAILED are all the same silent no-op: no dimming, no
+ * count, no banner over a grid that is otherwise working. A grid that renders
+ * is worth more than a flag.
+ */
+import { createContext, useContext, useMemo } from "react";
+import type { Context, ReactElement, ReactNode } from "react";
+import { loadFailed, loadLoading, loadReady } from "@stapel/core";
+import type { LoadState } from "@stapel/core";
+import type {
+  ListingCard,
+  ListingEngagement,
+  ListingEngagementBatch,
+} from "../api/types.js";
+import { engagementIds } from "../api/types.js";
+import { useListingEngagement } from "../model/queries.js";
+import { engagementFor, withEngagement } from "../model/engagement.js";
+
+/** What the scope publishes: the batch, however it is doing. */
+export interface ListingEngagementBag {
+  /** This listing's entry, or `undefined` for an id the answer did not carry
+   * — which includes "the read has not landed" and "the read failed". */
+  overlayFor(id: number): ListingEngagement | undefined;
+  /** The read's own state, for a host that wants to know. NOTHING in this
+   * pair renders the failed arm: see the file header. */
+  readonly state: LoadState<ListingEngagementBatch>;
+  /** The normalized ids actually asked for — after the sort, the de-dupe and
+   * the server's own cap. A caller can compare it with what it handed in to
+   * see that a hundred-and-forty-card page was truncated. */
+  readonly ids: readonly number[];
+}
+
+const NO_OVERLAY: ListingEngagementBag = {
+  overlayFor: () => undefined,
+  state: loadLoading(),
+  ids: [],
+};
+
+/**
+ * The scope. `null` outside a provider — and `null` is not an error, it is a
+ * container that never opted in.
+ */
+export const ListingEngagementContext: Context<ListingEngagementBag | null> =
+  createContext<ListingEngagementBag | null>(null);
+
+export interface UseListingEngagementOverlayOptions {
+  /** Hold the request (a grid that has not resolved its rows yet). */
+  readonly enabled?: boolean;
+}
+
+/**
+ * Run the batch read for a page of ids and get the bag back.
+ *
+ * The headless half: a host rendering its own visuals over its own grid calls
+ * this directly. A host using this pair's cards wraps them in
+ * {@link ListingEngagementScope} instead, which calls this once and puts the
+ * bag where the cards can find it.
+ */
+export function useListingEngagementOverlay(
+  ids: readonly number[],
+  options: UseListingEngagementOverlayOptions = {}
+): ListingEngagementBag {
+  const query = useListingEngagement(
+    ids,
+    options.enabled !== undefined ? { enabled: options.enabled } : {}
+  );
+  const wanted = useMemo(() => engagementIds(ids), [ids]);
+  const batch = query.data;
+  return useMemo(
+    () => ({
+      overlayFor: (id: number) => engagementFor(batch, id),
+      state:
+        query.status === "error"
+          ? loadFailed(query.error)
+          : batch !== undefined
+            ? loadReady(batch)
+            : loadLoading(),
+      ids: wanted,
+    }),
+    [batch, query.status, query.error, wanted]
+  );
+}
+
+export interface ListingEngagementScopeProps
+  extends UseListingEngagementOverlayOptions {
+  /** The listing ids on this page — normalized before the request, so the
+   * caller may hand them in any order and need not de-duplicate. */
+  readonly ids: readonly number[];
+  readonly children: ReactNode;
+}
+
+/**
+ * One request for the page, one lookup for every card inside it.
+ *
+ * Renderless: it draws no element of its own, so it can be wrapped around a
+ * grid without entering its layout.
+ */
+export function ListingEngagementScope(
+  props: ListingEngagementScopeProps
+): ReactElement {
+  const bag = useListingEngagementOverlay(
+    props.ids,
+    props.enabled !== undefined ? { enabled: props.enabled } : {}
+  );
+  return (
+    <ListingEngagementContext.Provider value={bag}>
+      {props.children}
+    </ListingEngagementContext.Provider>
+  );
+}
+
+/** The scope's bag, or a permanently-empty one outside a scope. Never throws:
+ * a card must render everywhere, wired or not. */
+export function useListingEngagementScope(): ListingEngagementBag {
+  return useContext(ListingEngagementContext) ?? NO_OVERLAY;
+}
+
+/** One listing's overlay entry, or `undefined`. */
+export function useEngagementOverlay(
+  id: number
+): ListingEngagement | undefined {
+  return useListingEngagementScope().overlayFor(id);
+}
+
+/**
+ * A row with the scope's answer laid over it — what every card in this pair
+ * actually reads.
+ *
+ * Outside a scope, or for an id the batch did not carry, this returns the
+ * SAME object it was given, so a card that never opted in re-renders exactly
+ * as often as it used to.
+ */
+export function useEngagedListing(row: ListingCard): ListingCard {
+  const overlay = useEngagementOverlay(row.id);
+  return useMemo(() => withEngagement(row, overlay), [row, overlay]);
+}

package/src/headless/Favorites.tsx

@@ -1,4 +1,4 @@
-import { useState } from "react";
+import { useEffect, useState } from "react";
 import type { ReactElement, ReactNode } from "react";
 import {
   actionAvailable,
@@ -27,7 +27,25 @@ import {
  */
 
 export interface FavoriteToggleBag {
+  /**
+   * What the heart must DRAW: the predicted state while a toggle is in
+   * flight, the row's own answer otherwise. Never `null` — see
+   * {@link FavoriteToggleBag.known} for the question `null` answers.
+   */
   readonly favorited: boolean;
+  /**
+   * Whether the row is AUTHORITATIVE about this reader's saved state.
+   *
+   * `is_favorited` is `boolean | null` and the null is not a `false`: it is
+   * "nobody asked on this person's behalf", which is what every anonymous
+   * read of a card list sends. Both draw the outline heart — an unsaved
+   * listing and an unasked one look the same, and a third mystery look would
+   * be a state nobody could name — but a caller deciding whether it may
+   * TRUST the row (a favourites count, a "you saved this" line) must be able
+   * to tell them apart, and squeezing that into the boolean is how it stops
+   * being tellable.
+   */
+  readonly known: boolean;
   /** Blocked with the reason for a visitor, a guest, an unknown mandate, or
    * while the previous toggle is still in flight. Never a hidden heart: a
    * control that disappears for a visitor teaches them nothing, and the CTA
@@ -38,6 +56,12 @@ export interface FavoriteToggleBag {
   readonly error: unknown;
 }
 
+/** An outstanding prediction, tagged with the listing it is about. */
+interface FavoritePrediction {
+  readonly id: number;
+  readonly value: boolean;
+}
+
 /**
  * The heart on one card.
  *
@@ -46,6 +70,38 @@ export interface FavoriteToggleBag {
  * reader (`with_favorited` annotates `Value(None)`), which is a THIRD state
  * and not `false`: "we did not ask" versus "not saved". The gate is what
  * renders it, so the distinction never has to be squeezed into the boolean.
+ *
+ * ── The toggle is OPTIMISTIC, and this is the pair's only such write ───────
+ *
+ * Measured on a live deployment: a signed-in person taps the heart and
+ * nothing on screen moves. The write went out and the invalidation landed,
+ * but the row this hook was handed is a PROP — it belongs to a list query one
+ * or two components up, and until that query has refetched and re-rendered
+ * the grid, the icon is still drawing the state from before the tap. On a
+ * phone that is a second or more of a control that looks broken, and the
+ * usual response to a control that looks broken is to press it again.
+ *
+ * So the state the heart draws is the PREDICTION while the write is in
+ * flight, and the prediction is allowed here for the reason `mutations.ts`
+ * argues at its own hook: the truth is a single boolean the caller already
+ * holds, so guessing it is arithmetic rather than invention. Everything else
+ * in the pair moves a lifecycle whose next state is the server's to decide.
+ *
+ * Three ways the prediction ends, and all three are wired:
+ *
+ *  - the write SUCCEEDS  → the server's own `favorited` replaces it, so a
+ *                          server that disagreed with the guess wins;
+ *  - the write FAILS     → it rolls back to the state the tap started from,
+ *                          and `error` carries the failure for the surface to
+ *                          show. A heart that stayed filled over a save that
+ *                          never happened is worse than one that never moved;
+ *  - the MINT fails      → `elevation.run` never reaches the write, so there
+ *                          is nothing to roll back FROM; the prediction is
+ *                          dropped the moment the mint's failure appears.
+ *
+ * And it is tagged with the listing id, because a virtualised grid reuses a
+ * hook instance across rows: an untagged prediction would move one card's
+ * heart onto its neighbour on scroll.
  */
 export function useFavoriteToggle(
   id: number,
@@ -55,6 +111,24 @@ export function useFavoriteToggle(
     LISTINGS_ELEVATION_ACTIONS.favorite
   );
   const mutation = useFavoriteListing();
+  const [predicted, setPredicted] = useState<FavoritePrediction | undefined>(
+    undefined
+  );
+
+  const mintError = elevation.error;
+  useEffect(() => {
+    // The mint failed, so `run` never reached the write — the prediction has
+    // nothing behind it and no `onError` coming to retire it.
+    if (mintError !== undefined && mintError !== null) setPredicted(undefined);
+  }, [mintError]);
+
+  const mine = predicted !== undefined && predicted.id === id ? predicted : undefined;
+  const shown = mine !== undefined ? mine.value : favorited === true;
+  // The row caught up: the prediction has become an opinion about the past.
+  // Retiring it here (rather than in the success callback) is what stops a
+  // stale guess from shadowing a row that changed for some other reason.
+  if (mine !== undefined && favorited === mine.value) setPredicted(undefined);
+
   const gate = firstBlock(
     mandate,
     mutation.isPending || elevation.pending
@@ -62,14 +136,30 @@ export function useFavoriteToggle(
       : actionAvailable()
   );
   return {
-    favorited: favorited === true,
+    favorited: shown,
+    known: favorited === true || favorited === false,
     gate,
     // On a host with auto-anonymous wired, the first heart an anonymous
     // visitor presses mints their account and then saves — one press, no
     // form, nothing said about it. Everywhere else `run` performs directly.
     toggle: () => {
       if (!gate.available) return;
-      elevation.run(() => mutation.mutate({ id, favorited: favorited !== true }));
+      const next = !shown;
+      const before = shown;
+      setPredicted({ id, value: next });
+      elevation.run(() => {
+        mutation.mutate(
+          { id, favorited: next },
+          {
+            onSuccess: (data) => {
+              setPredicted({ id, value: data.favorited ?? next });
+            },
+            onError: () => {
+              setPredicted({ id, value: before });
+            },
+          }
+        );
+      });
     },
     inFlight: mutation.isPending || elevation.pending,
     error: mutation.error ?? elevation.error,

package/src/headless/ListingDetail.tsx

@@ -1,4 +1,4 @@
-import { useMemo } from "react";
+import { useEffect, useMemo, useState } from "react";
 import type { ReactElement, ReactNode } from "react";
 import {
   actionAvailable,
@@ -19,6 +19,7 @@ import type {
 import { useListing, useListingStatus } from "../model/queries.js";
 import { useFavoriteListing } from "../model/mutations.js";
 import { asFeatureDaoList, featuresFromDaoList, unreadableFeatureCount } from "../model/features.js";
+import { isListingViewed, listingViewCount } from "../model/engagement.js";
 import type { FeatureCopySource } from "../model/features.js";
 import { listingStatusView } from "../model/status.js";
 import type { ListingStatusView } from "../model/status.js";
@@ -104,12 +105,32 @@ export interface ListingDetailBag {
    * (`resolveImage`), because no contract in this fleet resolves a
    * stranger's reference — see `model/runtime.ts`. */
   readonly images: readonly string[];
-  readonly isFavorited: boolean | undefined;
+  /**
+   * What the heart must DRAW — the prediction while a toggle is in flight,
+   * the row's own answer otherwise, and never `null`. See
+   * {@link ListingDetailBag.favoriteKnown} for the fact `null` carried.
+   */
+  readonly isFavorited: boolean;
+  /**
+   * Whether the row is AUTHORITATIVE about the reader's saved state.
+   * `is_favorited: null` is an anonymous read's "nobody asked", not a
+   * `false`; both draw the outline heart, and only this tells them apart.
+   */
+  readonly favoriteKnown: boolean;
   /** Saving a favourite needs a mandate; the block says which of the four
    * reasons applies. */
   readonly favoriteGate: ActionAvailability;
   toggleFavorite(): void;
   readonly favoriteInFlight: boolean;
+  /** The last favourite write's failure, for the surface to state. The heart
+   * has already rolled back by the time this is set. */
+  readonly favoriteError: unknown;
+  /** Has this reader already opened this listing? See `model/engagement.ts`
+   * — absent on every response today, and `false` when it is. */
+  readonly isViewed: boolean;
+  /** How many times it has been opened, or `undefined` where the server sent
+   * no number. Never a zero standing in for an absence. */
+  readonly viewCount: number | undefined;
   refetch(): void;
 }
 
@@ -220,7 +241,25 @@ export function useListingDetail(
     [detail.data, copy]
   );
 
-  const isFavorited = detail.data?.is_favorited ?? undefined;
+  // The row's own answer, and the third state it is allowed to be in: `null`
+  // means the read was anonymous and nobody asked on this person's behalf.
+  const rowFavorited = detail.data?.is_favorited ?? undefined;
+  const [predicted, setPredicted] = useState<boolean | undefined>(undefined);
+
+  const mintError = elevation.error;
+  useEffect(() => {
+    // A failed mint never reached the write, so no `onError` is coming to
+    // retire the prediction — see `useFavoriteToggle` for the whole argument.
+    if (mintError !== undefined && mintError !== null) setPredicted(undefined);
+  }, [mintError]);
+
+  const isFavorited = predicted ?? rowFavorited === true;
+  // The detail refetch caught up; the prediction is now an opinion about the
+  // past and must stop shadowing a row that may have changed for some other
+  // reason.
+  if (predicted !== undefined && rowFavorited === predicted) {
+    setPredicted(undefined);
+  }
 
   const favoriteGate = firstBlock(
     mandate,
@@ -250,14 +289,35 @@ export function useListingDetail(
     ),
     images: detail.data?.images ?? NO_IMAGES,
     isFavorited,
+    favoriteKnown: rowFavorited === true || rowFavorited === false,
     favoriteGate,
     toggleFavorite: () => {
       if (!favoriteGate.available) return;
+      const next = !isFavorited;
+      const before = isFavorited;
+      // The icon flips on the gesture; the invalidation below is what makes
+      // it true, and the two callbacks are what make it honest if it is not.
+      setPredicted(next);
       // Mints the anonymous account first where the host permits it for this
       // action; a direct call everywhere else.
-      elevation.run(() => favorite.mutate({ id, favorited: isFavorited !== true }));
+      elevation.run(() => {
+        favorite.mutate(
+          { id, favorited: next },
+          {
+            onSuccess: (data) => {
+              setPredicted(data.favorited ?? next);
+            },
+            onError: () => {
+              setPredicted(before);
+            },
+          }
+        );
+      });
     },
     favoriteInFlight: favorite.isPending || elevation.pending,
+    favoriteError: favorite.error ?? elevation.error,
+    isViewed: isListingViewed(detail.data),
+    viewCount: listingViewCount(detail.data),
     refetch: () => {
       void detail.refetch();
       void probe.refetch();