@stapel/listings-react 0.18.2 → 0.19.0

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,33 @@
  * screen (see `ListingCardBlockedReason`). The rule's disables below are the
  * documented decision §2.4 asks for, not a hole.
  *
+ * ── Why the disclosure is CONTROLLED: hover opened it, the click shut 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`.
+ *
+ * It needs the DELAY to reproduce, which is the interesting part: antd opens
+ * a hover popover after 0.1s, so two events fired back to back (a thumb's
+ * emulated `mouseenter` + `click`) land while nothing is open yet and the
+ * click opens it correctly. A cursor that lingers is past the delay, and its
+ * click closes what the hover opened. The suite was green throughout because
+ * every existing test fired `click` alone — a synthetic click carries no
+ * hover in front of it, so it exercised the one ordering that worked.
+ *
+ * So `open` is this component's own state and activation is MONOTONIC: a
+ * click may only open the disclosure, never close it. Hover-out, blur and a
+ * click outside still close it, because those arrive as an `onOpenChange`
+ * that no activation is claiming.
+ *
  * 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, 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 +86,28 @@ export interface GateReasonPopoverProps {
 
 export function GateReasonPopover(props: GateReasonPopoverProps): ReactElement {
   const reasonId = useId();
+  const [open, setOpen] = useState(false);
+  // Set in the capture phase of a click, i.e. BEFORE the popover's own
+  // handler runs on the same event, and dropped once that event is fully
+  // dispatched. While it is set, "close" is the tap's own toggle and is
+  // refused; see the file header.
+  const activating = useRef(false);
+
+  const handleOpenChange = useCallback((next: boolean): void => {
+    if (!next && activating.current) return;
+    setOpen(next);
+  }, []);
+
+  const activate = useCallback((): void => {
+    activating.current = true;
+    setOpen(true);
+    // A microtask runs after the whole event dispatch, so the flag covers
+    // exactly this gesture and no later hover-out.
+    queueMicrotask(() => {
+      activating.current = false;
+    });
+  }, []);
+
   return (
     <>
       {/* The floor: the reason reaches AT without a pointer, popover or no
@@ -75,6 +119,8 @@ 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>
@@ -87,8 +133,21 @@ 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
+          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>

package/src/default/ListingDetailPane.tsx

@@ -51,7 +51,7 @@
  * and the default `"column"` renders exactly what existing hosts already get.
  */
 import type { ReactElement, ReactNode } from "react";
-import { Descriptions, Divider, Flex, Typography } from "antd";
+import { Descriptions, Divider, Flex, Typography, theme as antdTheme } from "antd";
 import { SkinButton as Button } from "@stapel/tokens-antd/skin";
 import {
   ErrorAlert,
@@ -175,6 +175,7 @@ export interface ListingDetailPaneProps
 export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
   const t = useT();
   const { locale } = useI18n();
+  const { token } = antdTheme.useToken();
   const bag = useListingDetail(props.id, {
     ...(props.viewerId !== undefined ? { viewerId: props.viewerId } : {}),
     ...(props.categoryFeatures !== undefined
@@ -190,10 +191,19 @@ export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
   const split = props.layout === "split";
 
   const favoriteLabel = t(
-    bag.isFavorited === true
+    bag.isFavorited
       ? LISTINGS_I18N_KEYS.cardFavoriteRemove
       : LISTINGS_I18N_KEYS.cardFavoriteAdd
   );
+  // Saved is a SOLID accent shape; not-saved (and `is_favorited: null`, which
+  // is "nobody asked", not "no") is the outline. The bag flips it on the
+  // gesture and rolls it back if the write fails — see `useListingDetail`.
+  const heartIcon = (
+    <HeartIcon
+      filled={bag.isFavorited}
+      {...(bag.isFavorited ? { color: token.colorPrimary } : {})}
+    />
+  );
 
   return (
     <SkinTheme
@@ -416,9 +426,10 @@ export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
                         aria-disabled
                         {...bind}
                         aria-label={favoriteLabel}
-                        aria-pressed={bag.isFavorited === true}
-                        icon={<HeartIcon filled={bag.isFavorited === true} />}
+                        aria-pressed={bag.isFavorited}
+                        icon={heartIcon}
                         data-testid="listings-detail-favorite"
+                        data-favorited={String(bag.isFavorited)}
                         data-analytics="none"
                         data-analytics-reason="business action — host app wraps with its own tracked()"
                         onClick={bag.toggleFavorite}
@@ -435,15 +446,13 @@ export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
                     >
                       {(bind) => (
                         <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"] }
-                            : {})}
+                          // See `<ListingCard>`: the binding, spread whole.
+                          {...bind}
                           aria-label={favoriteLabel}
-                          aria-pressed={bag.isFavorited === true}
-                          icon={<HeartIcon filled={bag.isFavorited === true} />}
+                          aria-pressed={bag.isFavorited}
+                          icon={heartIcon}
                           data-testid="listings-detail-favorite"
+                          data-favorited={String(bag.isFavorited)}
                           data-analytics="none"
                           data-analytics-reason="business action — host app wraps with its own tracked()"
                           onClick={bag.toggleFavorite}
@@ -470,14 +479,26 @@ export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
               </Flex>
             );
 
-            const actionError =
-              actions.error !== undefined && actions.error !== null ? (
+            const actionError = (
+              <>
+                {actions.error !== undefined && actions.error !== null ? (
+                  <ErrorAlert
+                    testId="listings-detail-action-error"
+                    thrown={actions.error}
+                    variant="inline"
+                  />
+                ) : null}
+                {/* A save that did not save. The heart has already rolled
+                    back to the state the tap started from — that is the
+                    honest picture and a silent one, so the sentence goes
+                    beside it. `ErrorAlert` renders nothing for nothing. */}
                 <ErrorAlert
-                  testId="listings-detail-action-error"
-                  thrown={actions.error}
+                  testId="listings-detail-favorite-error"
+                  thrown={bag.favoriteError}
                   variant="inline"
                 />
-              ) : null;
+              </>
+            );
 
             const description = (
               <>
@@ -585,6 +606,17 @@ export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
                     {listing.location_label}
                   </Descriptions.Item>
                 ) : null}
+                {/* How many people opened it. `bag.viewCount` is `undefined`
+                    for a response that carries no such field — which is every
+                    response today — so this row simply is not there, and no
+                    zero stands in for the absence. */}
+                {bag.viewCount !== undefined ? (
+                  <Descriptions.Item label={t(LISTINGS_I18N_KEYS.detailViews)}>
+                    <span data-testid="listings-detail-views">
+                      {bag.viewCount}
+                    </span>
+                  </Descriptions.Item>
+                ) : null}
               </Descriptions>
             );
 

package/src/default/ListingFeedCard.tsx

@@ -24,13 +24,27 @@
  * has no line to spare. A full row of "Sign in to save this" under every one
  * of twenty tiles is not twenty pieces of help — it is the feed.
  *
- * The fleet already has the mechanism for exactly this and it is not "hide the
- * reason": `GateReasonScopeContext` / `<PaneGate>` pool identical reasons and
- * render each ONCE for everything inside the scope, with every control's
- * `aria-describedby` still pointing at that single copy. **A container drawing
- * a feed should wrap `<FeedGrid>` in a `<PaneGate>`.** Unscoped, the reason
- * still renders — over the photo, visible, never behind a hover — because a
- * reason a person cannot read is the one outcome the doctrine forbids.
+ * The answer this card ships with is the INTERACTION DISCLOSURE the grid card
+ * and the SERP card were given in the desktop and mobile fix packs, and it is
+ * this card's DEFAULT rather than an opt-in — a two-column tile is the one
+ * surface in the pair with no line to put a sentence on, so a standing volume
+ * here has to overprint the photograph to exist at all.
+ *
+ * That default is a fix, not a preference. Measured on a live home feed: this
+ * was the last surface still printing "Sign in to do this" as standing copy,
+ * over the picture, under every tile — and the heart under it was html-
+ * `disabled`, so the one gesture that could have replaced the caption was
+ * swallowed by the control. Both halves are gone: nothing stands in the tile,
+ * and a tap on the heart discloses the reason and the container's sign-in
+ * door (`signIn`) while a visually-hidden copy keeps the refusal in the
+ * accessibility tree. A host that genuinely wants the standing sentence back
+ * asks for it by name with `blockedReason="text"`.
+ *
+ * `GateReasonScopeContext` / `<PaneGate>` remain the answer for the STANDING
+ * arm: they pool identical reasons and render each ONCE for everything inside
+ * the scope, with every control's `aria-describedby` still pointing at that
+ * single copy. A container drawing a feed in that arm should wrap
+ * `<FeedGrid>` in a `<PaneGate>`.
  *
  * ── Two lines of title, and then it stops ─────────────────────────────────
  *
@@ -43,14 +57,18 @@
 import type { CSSProperties, ReactElement, ReactNode } from "react";
 import { Flex, Typography } from "antd";
 import { SkinTheme } from "@stapel/tokens-antd/skin";
+import type { SignInCta } from "@stapel/core";
 import { useT } from "@stapel/core";
 import { radii, spacing } from "@stapel/tokens";
 import type { ListingCard as ListingCardData } from "../api/types.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 { FavoriteHeart } from "./favorite.js";
 import {
   CARD_TARGET_STYLE_HREF,
+  CARD_VIEWED_CLASS,
   CardTarget,
   cardTargetCss,
 } from "./ListingCard.js";
@@ -118,18 +136,32 @@ export interface ListingFeedCardBaseProps extends ThemeModeProp {
   /** Hide the favourite entirely — for a surface where it makes no sense.
    * NOT a way to hide it from visitors. */
   readonly showFavorite?: boolean;
+  /**
+   * How loudly a blocked heart states its refusal. **`"popover"` by default
+   * on this card, unlike the other two** — a feed tile has no line to print a
+   * sentence on, so the standing arm can only overprint the photograph. See
+   * the file header for the measurement that made it the default.
+   */
+  readonly blockedReason?: "text" | "popover";
+  /** The container's sign-in door, rendered INSIDE the disclosure. Absent:
+   * the disclosure holds the reason alone. */
+  readonly signIn?: SignInCta;
 }
 
 export type ListingFeedCardProps = ListingFeedCardBaseProps & ListingCardOpenProps;
 
 export function ListingFeedCard(props: ListingFeedCardProps): ReactElement {
   const t = useT();
-  const { listing } = props;
+  // See `<ListingCard>`: the scope's overlay over the row, or the row. This
+  // is the surface it matters most on — a home feed is drawn from search.
+  const listing = useEngagedListing(props.listing);
   const status =
     listing.status === undefined ? undefined : lifecycleCaption(listing.status);
   const title = listing.title ?? "";
   const targetLabel =
     title.length > 0 ? title : t(LISTINGS_I18N_KEYS.cardUntitled);
+  // Already seen — `false` for every response that carries no such field.
+  const viewed = isListingViewed(listing);
 
   return (
     <SkinTheme
@@ -149,6 +181,9 @@ export function ListingFeedCard(props: ListingFeedCardProps): ReactElement {
         {...(status !== undefined
           ? { "data-listing-status": status.status }
           : {})}
+        {...(viewed
+          ? { className: CARD_VIEWED_CLASS, "data-listing-viewed": "true" }
+          : {})}
       >
         {/* One anchor over the whole tile. The photo is a still `<img>`, so
             unlike the SERP card's swipeable strip it is safe inside a link —
@@ -211,6 +246,8 @@ export function ListingFeedCard(props: ListingFeedCardProps): ReactElement {
             listingId={listing.id}
             favorited={listing.is_favorited}
             testId="listings-feed-favorite"
+            blockedReason={props.blockedReason ?? "popover"}
+            {...(props.signIn !== undefined ? { signIn: props.signIn } : {})}
             style={HEART}
           />
         )}