@stapel/listings-react 0.18.1 → 0.19.0

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();

package/src/i18n/es.ts

@@ -102,6 +102,7 @@ export const listingsI18nBundleEs: I18nDictionary = {
   "listings.detail.published_at": "Publicado el {date}",
   "listings.detail.expires_at": "A la venta hasta el {date}",
   "listings.detail.stock": "Disponibles",
+  "listings.detail.views": "Visitas",
   "listings.detail.edit": "Editar el anuncio",
   "listings.detail.take_down": "Retirarlo",
 
@@ -206,6 +207,12 @@ export const listingsI18nBundleEs: I18nDictionary = {
   "listings.favorites.sign_in_hint":
     "Los favoritos se guardan en tu cuenta, así que te siguen entre dispositivos.",
 
+  // Las dos comprobaciones de publicación que llegaron con el contrato 0.17.
+  "error.400.listing_location_required":
+    "Indica dónde está el artículo antes de publicarlo",
+  "error.400.listing_zero_price_not_allowed":
+    "En esta categoría no se permite un precio de 0. Deja el precio vacío para «precio no indicado».",
+
   "listings.blocked.sign_in": "Inicia sesión para hacer esto",
   "listings.blocked.guest":
     "Esta cuenta todavía no puede hacerlo — termina de configurarla primero",

package/src/i18n/generated/errors.es.gen.ts

@@ -8,7 +8,7 @@ import type { ListingsErrorCode } from "./errors.gen.js";
 /**
  * `es` texts for the backend error codes this catalog carries.
  *
- * PARTIAL, and deliberately typed to say so: 24 key(s) owned by
+ * PARTIAL, and deliberately typed to say so: 26 key(s) owned by
  * stapel_attributes, stapel_listings are absent, because that owner ships no locale catalog
  * (ERRORS_LOCALE_EXEMPT_OWNERS). English for them still comes from the registry
  * artifact via the en bundle; the pair layers its own authored `es`

package/src/i18n/generated/errors.gen.ts

@@ -68,6 +68,8 @@ export const LISTINGS_ERRORS = {
   "error.400.invalid_ad_id": { status: 400, params: [], remediation: "fix_input", en: "Invalid advertisement ID" },
   "error.400.listing_feature_not_allowed": { status: 400, params: ["feature"], remediation: "fix_input", en: "Feature '{feature}' is not allowed for this category" },
   "error.400.listing_invalid_status_filter": { status: 400, params: ["status"], remediation: "fix_input", en: "Unknown listing status '{status}'" },
+  "error.400.listing_location_required": { status: 400, params: [], remediation: "fix_input", en: "Choose where the item is before publishing" },
+  "error.400.listing_zero_price_not_allowed": { status: 400, params: [], remediation: "fix_input", en: "A price of 0 is not allowed in this category. Leave the price empty for \"price not stated\"." },
   "error.400.publish_validation_failed": { status: 400, params: [], remediation: "fix_input", en: "Listing validation failed" },
   "error.400.validation_error": { status: 400, params: [], remediation: "fix_input", en: "Validation error" },
   "error.400.verification_failed": { status: 400, params: [], remediation: "verify", en: "Verification failed" },
@@ -140,6 +142,8 @@ export const LISTINGS_ERROR_CODES: readonly ListingsErrorCode[] = [
   "error.400.invalid_ad_id",
   "error.400.listing_feature_not_allowed",
   "error.400.listing_invalid_status_filter",
+  "error.400.listing_location_required",
+  "error.400.listing_zero_price_not_allowed",
   "error.400.publish_validation_failed",
   "error.400.validation_error",
   "error.400.verification_failed",
@@ -214,6 +218,8 @@ export const listingsErrorBundleEn: Record<ListingsErrorCode, string> = {
   "error.400.invalid_ad_id": "Invalid advertisement ID",
   "error.400.listing_feature_not_allowed": "Feature '{feature}' is not allowed for this category",
   "error.400.listing_invalid_status_filter": "Unknown listing status '{status}'",
+  "error.400.listing_location_required": "Choose where the item is before publishing",
+  "error.400.listing_zero_price_not_allowed": "A price of 0 is not allowed in this category. Leave the price empty for \"price not stated\".",
   "error.400.publish_validation_failed": "Listing validation failed",
   "error.400.validation_error": "Validation error",
   "error.400.verification_failed": "Verification failed",

package/src/i18n/generated/errors.json

@@ -286,6 +286,20 @@
     "remediation": "fix_input",
     "en": "Unknown listing status '{status}'"
   },
+  {
+    "code": "error.400.listing_location_required",
+    "status": 400,
+    "params": [],
+    "remediation": "fix_input",
+    "en": "Choose where the item is before publishing"
+  },
+  {
+    "code": "error.400.listing_zero_price_not_allowed",
+    "status": 400,
+    "params": [],
+    "remediation": "fix_input",
+    "en": "A price of 0 is not allowed in this category. Leave the price empty for \"price not stated\"."
+  },
   {
     "code": "error.400.publish_validation_failed",
     "status": 400,

package/src/i18n/generated/errors.ru.gen.ts

@@ -8,7 +8,7 @@ import type { ListingsErrorCode } from "./errors.gen.js";
 /**
  * `ru` texts for the backend error codes this catalog carries.
  *
- * PARTIAL, and deliberately typed to say so: 24 key(s) owned by
+ * PARTIAL, and deliberately typed to say so: 26 key(s) owned by
  * stapel_attributes, stapel_listings are absent, because that owner ships no locale catalog
  * (ERRORS_LOCALE_EXEMPT_OWNERS). English for them still comes from the registry
  * artifact via the en bundle; the pair layers its own authored `ru`

package/src/i18n/keys.ts

@@ -114,6 +114,13 @@ export const LISTINGS_I18N_KEYS = {
    * quantity in the value cell, so this key carries no `{count}` — it used to,
    * and the live page printed the placeholder. */
   detailStock: "listings.detail.stock",
+  /**
+   * The VIEWS row's label. Same shape as the stock row and for the same
+   * reason: `<Descriptions>` renders the label cell and the number separately,
+   * so the key carries no `{count}` — a key that did printed the placeholder
+   * on a live page once already.
+   */
+  detailViews: "listings.detail.views",
   /** The owner's two primaries on their own listing page. */
   detailEdit: "listings.detail.edit",
   detailTakeDown: "listings.detail.take_down",
@@ -318,6 +325,7 @@ export const listingsI18nBundleEn: Record<string, string> = {
   "listings.detail.published_at": "Published {date}",
   "listings.detail.expires_at": "Listed until {date}",
   "listings.detail.stock": "In stock",
+  "listings.detail.views": "Views",
   "listings.detail.edit": "Edit listing",
   "listings.detail.take_down": "Take it down",
 

package/src/i18n/ru.ts

@@ -118,6 +118,7 @@ export const listingsI18nBundleRu: I18nDictionary = {
   "listings.detail.published_at": "Опубликовано {date}",
   "listings.detail.expires_at": "В продаже до {date}",
   "listings.detail.stock": "В наличии",
+  "listings.detail.views": "Просмотры",
   "listings.detail.edit": "Редактировать объявление",
   "listings.detail.take_down": "Снять с публикации",
 
@@ -225,6 +226,14 @@ export const listingsI18nBundleRu: I18nDictionary = {
   "listings.favorites.sign_in_hint":
     "Избранное хранится в аккаунте, поэтому переходит с вами на другие устройства.",
 
+  // The two publish checks the 0.17 contract brought with it: a place is
+  // required, and a zero price in such a category is an empty field rather
+  // than "free".
+  "error.400.listing_location_required":
+    "Перед публикацией укажите, где находится товар",
+  "error.400.listing_zero_price_not_allowed":
+    "В этой категории цена 0 недопустима. Оставьте поле пустым — это и есть «цена не указана».",
+
   "listings.blocked.sign_in": "Войдите, чтобы сделать это",
   "listings.blocked.guest":
     "Этот аккаунт пока так не может — сначала завершите настройку",

package/src/index.ts

@@ -67,7 +67,9 @@ export type { ListingsApi } from "./api/listingsApi.js";
 export {
   DEFAULT_LISTING_CURRENCY,
   LISTING_STATUSES,
+  LISTINGS_ENGAGEMENT_BATCH_LIMIT,
   MODERATION_STATUSES,
+  engagementIds,
 } from "./api/types.js";
 export type {
   DeleteResponse,
@@ -80,6 +82,9 @@ export type {
   ListingDetail as ListingDetailData,
   ListingDraft,
   ListingDraftPatch,
+  ListingEngagement,
+  ListingEngagementBatch,
+  ListingEngagementFields,
   ListingFeatureDao,
   ListingFeatureDaoUnion,
   ListingFeatureType,
@@ -155,6 +160,14 @@ export {
 } from "./model/features.js";
 export type { FeatureCopySource } from "./model/features.js";
 
+// ── model: the engagement axis (already-seen / view count / the overlay) ─────
+export {
+  engagementFor,
+  isListingViewed,
+  listingViewCount,
+  withEngagement,
+} from "./model/engagement.js";
+
 // ── model: validation, the mirror and the publish-400 split ──────────────────
 export {
   CATEGORY_FIELD,
@@ -192,6 +205,7 @@ export type { ListingPageKey } from "./model/queryKeys.js";
 export {
   useListing,
   useListingCards,
+  useListingEngagement,
   useListingStatus,
   useMyCounters,
   useMyFavorites,
@@ -241,6 +255,19 @@ export type {
   MyListingsBag,
   UseMyListingsOptions,
 } from "./headless/MyListings.js";
+export {
+  ListingEngagementContext,
+  ListingEngagementScope,
+  useEngagedListing,
+  useEngagementOverlay,
+  useListingEngagementOverlay,
+  useListingEngagementScope,
+} from "./headless/Engagement.js";
+export type {
+  ListingEngagementBag,
+  ListingEngagementScopeProps,
+  UseListingEngagementOverlayOptions,
+} from "./headless/Engagement.js";
 export { Favorites, useFavorites, useFavoriteToggle } from "./headless/Favorites.js";
 export type {
   FavoriteToggleBag,

package/src/model/engagement.ts

@@ -0,0 +1,118 @@
+/**
+ * "Have I already seen this one?" — the engagement axis of a listing row, and
+ * the OVERLAY that is the only way a storefront ever gets an answer.
+ *
+ * A classified's results page is mostly re-reading: the same twenty offers
+ * scrolled past for the third evening in a row. Every mature one marks the
+ * rows you already opened, and a shopper who cannot see which those are is
+ * paying attention to the same card repeatedly. `viewed` is that mark and
+ * `view_count` is the seller-facing counterpart on the listing page.
+ *
+ * ── Why the row alone is not enough, and the overlay is the load-bearing half
+ *
+ * stapel-listings puts `viewed` / `view_count` on its own card and detail
+ * serializers, and on the listing PAGE that is the end of the story. But the
+ * two surfaces a buyer actually scrolls — the home feed and the SERP — are
+ * not served by this module at all: their cards come out of the SEARCH index,
+ * whose stored document can carry neither a flag that differs per reader nor
+ * a counter that moves faster than a re-index. So on exactly the screens the
+ * feature exists for, `viewed` and `is_favorited` never arrive on the row,
+ * every card renders undimmed with an outline heart, and nothing anywhere
+ * reports a problem.
+ *
+ * `GET /listings/engagement/?ids=…` is the answer the backend built for it:
+ * ONE call for a whole page, `{id: {view_count, viewed, is_favorited}}`,
+ * `AllowAny` so a signed-out grid is not a second code path. This module is
+ * the READING side of it — what a row means, how one entry is found in a
+ * batch, and how an entry is laid over a row a container fetched from
+ * somewhere else. The id normalizer both the request and its cache key are
+ * built from lives with the wire types (`engagementIds`), because the cap it
+ * enforces is the server's.
+ *
+ * ── The rule every function here keeps ────────────────────────────────────
+ *
+ * **Absent, `null` and `NaN` all mean "draw nothing extra".** No dimming, no
+ * number, no warning, no log line, and — for a failed overlay — no banner
+ * over a grid that is otherwise working. A pair that printed "0 views" for a
+ * field the server never sent would be inventing a fact about a seller's
+ * listing; a pair that turned a decoration's 500 into an error state would
+ * have taken a working results page away from a shopper over a flag. A grid
+ * that renders is worth more than a flag.
+ */
+import type {
+  ListingCard,
+  ListingEngagement,
+  ListingEngagementBatch,
+  ListingEngagementFields,
+} from "../api/types.js";
+
+/**
+ * Has this reader already opened this listing?
+ *
+ * `true` and only `true`. `null` is "we did not ask on this person's behalf"
+ * — the same third state `is_favorited` carries for an anonymous read — and a
+ * row nobody asked about is not a row somebody has seen.
+ */
+export function isListingViewed(
+  row: ListingEngagementFields | undefined
+): boolean {
+  return row?.viewed === true;
+}
+
+/**
+ * How many times the listing has been opened, or `undefined` where there is
+ * no number to show.
+ *
+ * `Number.isFinite` rather than `typeof === "number"`: a JSON `NaN` cannot
+ * arrive, but a count computed by a host from something absent can, and
+ * "NaN views" on a seller's page is worse than no line at all. Zero IS a
+ * number and is rendered — "0 views" is a true and useful thing to tell a
+ * seller, and the case it must not be confused with (the field is missing) is
+ * already `undefined` here.
+ */
+export function listingViewCount(
+  row: ListingEngagementFields | undefined
+): number | undefined {
+  const raw = row?.view_count;
+  return typeof raw === "number" && Number.isFinite(raw) ? raw : undefined;
+}
+
+/**
+ * One listing's entry out of a batch answer, or `undefined`.
+ *
+ * The wire keys are STRINGS and an id with no listing is simply absent, so
+ * this is a lookup rather than an index: `batch.items[id]` would be a type
+ * error today and a silent `undefined` tomorrow.
+ */
+export function engagementFor(
+  batch: ListingEngagementBatch | undefined,
+  id: number
+): ListingEngagement | undefined {
+  return batch?.items[String(id)];
+}
+
+/**
+ * Lay an overlay entry over a row, so a card reads ONE object whatever its
+ * provenance.
+ *
+ * The overlay wins where it speaks, and it speaks about all three of its
+ * fields at once — it is the answer to a question that was actually asked on
+ * this reader's behalf, and the row (a search document, or a card serialized
+ * before the fields existed) is at best older and at worst silent. Where
+ * there is no overlay entry the row is returned UNCHANGED, by identity: a
+ * missing id, an overlay that has not loaded, and an overlay that failed are
+ * the same "we know nothing more than the row does", and none of them may
+ * fabricate a `false`.
+ */
+export function withEngagement(
+  row: ListingCard,
+  overlay: ListingEngagement | undefined
+): ListingCard {
+  if (overlay === undefined) return row;
+  return {
+    ...row,
+    viewed: overlay.viewed,
+    view_count: overlay.view_count,
+    is_favorited: overlay.is_favorited,
+  };
+}

package/src/model/queries.ts

@@ -5,11 +5,13 @@ import type { StapelApiError } from "@stapel/core";
 import type { ValidationBatchResult } from "@stapel/attributes-react";
 import type {
   ListingDetail,
+  ListingEngagementBatch,
   ListingPageParams,
   ListingStatusInfo,
   MyCounters,
   PaginatedListingCards,
 } from "../api/types.js";
+import { engagementIds } from "../api/types.js";
 import { useListingsApi } from "./context.js";
 import { listingsQueryKeys, pageKey } from "./queryKeys.js";
 
@@ -148,3 +150,42 @@ export function useValidateDraft(
     retry: false,
   });
 }
+
+/**
+ * The per-viewer ENGAGEMENT overlay for one page of ids, in one request.
+ *
+ * `AllowAny` upstream, so it joins the ungated regime described at the top of
+ * this file: a signed-out grid asks exactly the same question and is told
+ * `null` for both per-viewer flags. Gating it on the session substrate would
+ * make a shop window wait for a login bootstrap in order to decorate itself.
+ *
+ * ── Every failure mode here is a NO-OP, on purpose ────────────────────────
+ *
+ * `retry: false`, no error surface, and `enabled` false for an empty page.
+ * This read decorates a grid that has already rendered from somewhere else:
+ * if it 500s, times out, or is never wired at all, the cards must draw
+ * exactly as they drew before it existed. Retrying a decoration three times
+ * spends a person's connection on a flag, and an error banner over a working
+ * results page trades the thing they came for against the thing they did not
+ * ask about. `useEngagementOverlay` therefore reads only `data`, and the
+ * failure is available to a host that wants it and rendered by nobody.
+ *
+ * `placeholderData: keepPreviousData` for the paging case: a grid whose cards
+ * un-dim for a moment on every page change is reporting a state change that
+ * did not happen. The previous answer is still true about the previous ids,
+ * and `withEngagement` only ever reads the entries whose ids it asked for.
+ */
+export function useListingEngagement(
+  ids: readonly number[],
+  options?: { readonly enabled?: boolean }
+): UseQueryResult<ListingEngagementBatch, StapelApiError> {
+  const api = useListingsApi();
+  const wanted = engagementIds(ids);
+  return useQuery({
+    queryKey: listingsQueryKeys.engagement(wanted),
+    queryFn: ({ signal }) => api.engagement(wanted, { signal }),
+    enabled: (options?.enabled ?? true) && wanted.length > 0,
+    placeholderData: keepPreviousData,
+    retry: false,
+  });
+}

package/src/model/queryKeys.ts

@@ -11,6 +11,7 @@
  * produces a different request cannot silently reuse a page — the stale-page
  * bug (new filter, cached rows) is unwritable rather than merely avoided.
  */
+import { engagementIds } from "../api/types.js";
 import type { ListingPageParams } from "../api/types.js";
 
 /** The normalized page cursor a list read is keyed on. */
@@ -67,6 +68,18 @@ export const listingsQueryKeys: {
   allFavorites(): readonly ["listings", "my", "favorites"];
   /** Every published-card PAGE, same reason. */
   allLists(): readonly ["listings", "list"];
+  /**
+   * The per-viewer overlay for one page of ids.
+   *
+   * Keyed on the NORMALIZED list (`engagementIds`: sorted, de-duplicated,
+   * capped) and joined into one string, which is the same value the request
+   * sends. The doctrine at the top of this file applied to a batch read: two
+   * renders asking for the same ids in a different order are asking the
+   * identical question — the answer is a map keyed by id and carries no order
+   * of its own — so they must share one cache entry and cost one request.
+   * Keyed on the raw array they would cost two, per re-render, per grid.
+   */
+  engagement(ids: readonly number[]): readonly ["listings", "engagement", string];
 } = {
   all: [ROOT],
   list: (page) => [ROOT, "list", page],
@@ -80,4 +93,5 @@ export const listingsQueryKeys: {
   validateDraft: (id) => [ROOT, "validate-draft", id],
   allFavorites: () => [ROOT, "my", "favorites"],
   allLists: () => [ROOT, "list"],
+  engagement: (ids) => [ROOT, "engagement", engagementIds(ids).join(",")],
 };