@stapel/listings-react 0.18.2 → 0.19.0

package/dist/model/queryKeys.d.ts

@@ -1,16 +1,3 @@
-/**
- * Namespaced TanStack Query keys (frontend-standard §2 — namespaced keys).
- * Everything under the `"listings"` root so a host can invalidate the whole
- * module or match a single read. Explicit tuple return types satisfy
- * `--isolatedDeclarations`.
- *
- * THE KEY IS THE REQUEST for the paginated reads: a page is keyed on the very
- * parameter object the client is handed, normalized so that "no cursor" and
- * "an explicitly undefined cursor" cannot cache twice. Two states that
- * produce the same request therefore share a cache entry, and one that
- * produces a different request cannot silently reuse a page — the stale-page
- * bug (new filter, cached rows) is unwritable rather than merely avoided.
- */
 import type { ListingPageParams } from "../api/types.js";
 /** The normalized page cursor a list read is keyed on. */
 export interface ListingPageKey {
@@ -51,5 +38,17 @@ export declare 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];
 };
 //# sourceMappingURL=queryKeys.d.ts.map

package/dist/model/queryKeys.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"queryKeys.d.ts","sourceRoot":"","sources":["../../src/model/queryKeys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,0DAA0D;AAC1D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;wBAEwB;AACxB,wBAAgB,OAAO,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,cAAc,CAMlE;AAID,eAAO,MAAM,iBAAiB,EAAE;IAC9B,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC,UAAU,CAAC,CAAC;IACpC,+BAA+B;IAC/B,IAAI,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC;IAC1E,2BAA2B;IAC3B,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC,UAAU,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC5D;;0EAEsE;IACtE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC,UAAU,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC5D,oCAAoC;IACpC,UAAU,IAAI,SAAS,CAAC,UAAU,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;IACtD,gDAAgD;IAChD,WAAW,CACT,IAAI,EAAE,cAAc,GACnB,SAAS,CAAC,UAAU,EAAE,IAAI,EAAE,WAAW,EAAE,cAAc,CAAC,CAAC;IAC5D,mEAAmE;IACnE,IAAI,CACF,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,cAAc,GACnB,SAAS,CAAC,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC;IACnE;;sCAEkC;IAClC,YAAY,IAAI,SAAS,CAAC,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;IACpE,+DAA+D;IAC/D,OAAO,IAAI,SAAS,CAAC,UAAU,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;IACnD,8DAA8D;IAC9D,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC,UAAU,EAAE,gBAAgB,EAAE,MAAM,CAAC,CAAC;IAC3E;8EAC0E;IAC1E,YAAY,IAAI,SAAS,CAAC,UAAU,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;IACzD,8CAA8C;IAC9C,QAAQ,IAAI,SAAS,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;CAc3C,CAAC"}
+{"version":3,"file":"queryKeys.d.ts","sourceRoot":"","sources":["../../src/model/queryKeys.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,0DAA0D;AAC1D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;wBAEwB;AACxB,wBAAgB,OAAO,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,cAAc,CAMlE;AAID,eAAO,MAAM,iBAAiB,EAAE;IAC9B,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC,UAAU,CAAC,CAAC;IACpC,+BAA+B;IAC/B,IAAI,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC;IAC1E,2BAA2B;IAC3B,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC,UAAU,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC5D;;0EAEsE;IACtE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC,UAAU,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC5D,oCAAoC;IACpC,UAAU,IAAI,SAAS,CAAC,UAAU,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;IACtD,gDAAgD;IAChD,WAAW,CACT,IAAI,EAAE,cAAc,GACnB,SAAS,CAAC,UAAU,EAAE,IAAI,EAAE,WAAW,EAAE,cAAc,CAAC,CAAC;IAC5D,mEAAmE;IACnE,IAAI,CACF,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,cAAc,GACnB,SAAS,CAAC,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC;IACnE;;sCAEkC;IAClC,YAAY,IAAI,SAAS,CAAC,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;IACpE,+DAA+D;IAC/D,OAAO,IAAI,SAAS,CAAC,UAAU,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;IACnD,8DAA8D;IAC9D,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC,UAAU,EAAE,gBAAgB,EAAE,MAAM,CAAC,CAAC;IAC3E;8EAC0E;IAC1E,YAAY,IAAI,SAAS,CAAC,UAAU,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;IACzD,8CAA8C;IAC9C,QAAQ,IAAI,SAAS,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAC1C;;;;;;;;;;OAUG;IACH,UAAU,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC,UAAU,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC;CAejF,CAAC"}

package/dist/model/queryKeys.js

@@ -1,3 +1,17 @@
+/**
+ * Namespaced TanStack Query keys (frontend-standard §2 — namespaced keys).
+ * Everything under the `"listings"` root so a host can invalidate the whole
+ * module or match a single read. Explicit tuple return types satisfy
+ * `--isolatedDeclarations`.
+ *
+ * THE KEY IS THE REQUEST for the paginated reads: a page is keyed on the very
+ * parameter object the client is handed, normalized so that "no cursor" and
+ * "an explicitly undefined cursor" cannot cache twice. Two states that
+ * produce the same request therefore share a cache entry, and one that
+ * 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";
 /** Normalize a page's parameters into its key. Exported because a test that
  * asserts "these two states hit one cache entry" must build the key the same
  * way the hook does. */
@@ -22,5 +36,6 @@ export const listingsQueryKeys = {
     validateDraft: (id) => [ROOT, "validate-draft", id],
     allFavorites: () => [ROOT, "my", "favorites"],
     allLists: () => [ROOT, "list"],
+    engagement: (ids) => [ROOT, "engagement", engagementIds(ids).join(",")],
 };
 //# sourceMappingURL=queryKeys.js.map

package/dist/model/queryKeys.js.map

@@ -1 +1 @@
-{"version":3,"file":"queryKeys.js","sourceRoot":"","sources":["../../src/model/queryKeys.ts"],"names":[],"mappings":"AAsBA;;wBAEwB;AACxB,MAAM,UAAU,OAAO,CAAC,MAA0B;IAChD,OAAO;QACL,MAAM,EAAE,MAAM,EAAE,MAAM,IAAI,IAAI;QAC9B,SAAS,EAAE,MAAM,EAAE,SAAS,IAAI,IAAI;QACpC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,IAAI;KAC7B,CAAC;AACJ,CAAC;AAED,MAAM,IAAI,GAAG,UAAmB,CAAC;AAEjC,MAAM,CAAC,MAAM,iBAAiB,GAkC1B;IACF,GAAG,EAAE,CAAC,IAAI,CAAC;IACX,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC;IACpC,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC;IACpC,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC;IACpC,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,CAAC;IAC1C,WAAW,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC;IACtD,IAAI,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,IAAI,CAAC;IACxD,YAAY,EAAE,GAAG,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,CAAC;IACxD,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,CAAC;IACvC,aAAa,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,gBAAgB,EAAE,EAAE,CAAC;IACnD,YAAY,EAAE,GAAG,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC;IAC7C,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC;CAC/B,CAAC"}
+{"version":3,"file":"queryKeys.js","sourceRoot":"","sources":["../../src/model/queryKeys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAUhD;;wBAEwB;AACxB,MAAM,UAAU,OAAO,CAAC,MAA0B;IAChD,OAAO;QACL,MAAM,EAAE,MAAM,EAAE,MAAM,IAAI,IAAI;QAC9B,SAAS,EAAE,MAAM,EAAE,SAAS,IAAI,IAAI;QACpC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,IAAI;KAC7B,CAAC;AACJ,CAAC;AAED,MAAM,IAAI,GAAG,UAAmB,CAAC;AAEjC,MAAM,CAAC,MAAM,iBAAiB,GA8C1B;IACF,GAAG,EAAE,CAAC,IAAI,CAAC;IACX,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC;IACpC,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC;IACpC,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC;IACpC,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,CAAC;IAC1C,WAAW,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC;IACtD,IAAI,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,IAAI,CAAC;IACxD,YAAY,EAAE,GAAG,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,CAAC;IACxD,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,CAAC;IACvC,aAAa,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,gBAAgB,EAAE,EAAE,CAAC;IACnD,YAAY,EAAE,GAAG,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC;IAC7C,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC;IAC9B,UAAU,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,YAAY,EAAE,aAAa,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;CACxE,CAAC"}

package/llms.txt

@@ -1,6 +1,6 @@
-# @stapel/listings-react 0.18.2
+# @stapel/listings-react 0.19.0
 
-Headless React flow pair for stapel-listings (contract >=0.12 <0.13) — business + state, zero visual opinion.
+Headless React flow pair for stapel-listings (contract >=0.17 <0.18) — business + state, zero visual opinion.
 Built on @stapel/core: typed client + StapelApiError envelope, auth token refresh,
 verification-403 interception, i18n engine, analytics facade, TanStack Query layer.
 
@@ -25,6 +25,7 @@ Paths are relative to `/listings/api/v1/`.
 - listings_api_v1_listings_complete_create: POST /listings/{id}/complete/
 - listings_api_v1_listings_create: POST /listings/
 - listings_api_v1_listings_destroy: DELETE /listings/{id}/
+- listings_api_v1_listings_engagement_retrieve: GET /listings/engagement/
 - listings_api_v1_listings_favorite_create: POST /listings/{id}/favorite/
 - listings_api_v1_listings_list: GET /listings/
 - listings_api_v1_listings_my_counters_retrieve: GET /listings/my/counters/
@@ -47,6 +48,7 @@ Paths are relative to `/listings/api/v1/`.
 - useFavoriteListing (mutation) → favorite+unfavorite
 - useListing (query) → retrieve
 - useListingCards (query) → list
+- useListingEngagement (query) → engagement
 - useListingStatus (query) → status
 - useMyCounters (query) → myCounters
 - useMyFavorites (query) → myFavorites
@@ -55,7 +57,7 @@ Paths are relative to `/listings/api/v1/`.
 - useValidateDraft (query) → validateDraft
 
 ## Errors (render t(code, params); UX from remediation)
-66 keys (full catalog: manifest.json §errors). By remediation: fix_input 37 · retry 16 · verify 5 · wait_and_retry 5 · contact_support 2 · reauthenticate 1.
+68 keys (full catalog: manifest.json §errors). By remediation: fix_input 39 · retry 16 · verify 5 · wait_and_retry 5 · contact_support 2 · reauthenticate 1.
 Param-bearing keys (interpolation slots matter):
 - error.400.description_too_long [400] → fix_input {max_length}
 - error.400.description_too_short [400] → fix_input {min_length}
@@ -109,6 +111,7 @@ const { tracked } = useTracked();
 - listings.card → <ListingCard> [default|saved|visitor|grid cell|list row|no-photo]  demo/ListingCard.demo.tsx
 - listings.composer → <ListingComposerPage> [default|unwired|photos-in-flight|unsupported-type]  demo/ListingComposer.demo.tsx
 - listings.detail → <ListingDetailPane> [default|contact-unwired|owner|not-found]  demo/ListingDetail.demo.tsx
+- listings.engagement-scope → <ListingEngagementScope> [default|unscoped|visitor|failed]  demo/ListingEngagementScope.demo.tsx
 - listings.favorites → <FavoritesPane> [default|paged|empty|failed|visitor]  demo/Favorites.demo.tsx
 - listings.feed-card → <ListingFeedCard> [default|tile|visitor|wide]  demo/ListingFeedCard.demo.tsx
 - listings.mine → <MyListingsPane> [default|no-editor|taken-down|visitor|failed]  demo/MyListings.demo.tsx

package/manifest.json

@@ -1,10 +1,10 @@
 {
   "$generated": "by scripts/gen-manifest.mjs — do not edit; drift-gated (pnpm gen:manifest:check)",
   "package": "@stapel/listings-react",
-  "version": "0.18.2",
+  "version": "0.19.0",
   "backend": {
     "module": "stapel-listings",
-    "contract": ">=0.12 <0.13"
+    "contract": ">=0.17 <0.18"
   },
   "layers": [
     "api",
@@ -44,6 +44,13 @@
       "request": null,
       "response": "DeleteResponse"
     },
+    "listings_api_v1_listings_engagement_retrieve": {
+      "method": "GET",
+      "path": "/listings/api/v1/listings/engagement/",
+      "tag": "listings",
+      "request": null,
+      "response": "ListingEngagementBatch"
+    },
     "listings_api_v1_listings_favorite_create": {
       "method": "POST",
       "path": "/listings/api/v1/listings/{id}/favorite/",
@@ -211,6 +218,15 @@
         "{page}"
       ]
     },
+    "useListingEngagement": {
+      "kind": "query",
+      "operation": "engagement",
+      "queryKey": [
+        "listings",
+        "engagement",
+        "{…}"
+      ]
+    },
     "useListingStatus": {
       "kind": "query",
       "operation": "status",
@@ -479,6 +495,16 @@
       ],
       "remediation": "fix_input"
     },
+    "error.400.listing_location_required": {
+      "status": 400,
+      "params": [],
+      "remediation": "fix_input"
+    },
+    "error.400.listing_zero_price_not_allowed": {
+      "status": 400,
+      "params": [],
+      "remediation": "fix_input"
+    },
     "error.400.publish_validation_failed": {
       "status": 400,
       "params": [],
@@ -713,6 +739,26 @@
       ],
       "source": "demo/ListingDetail.demo.tsx"
     },
+    {
+      "id": "listings.engagement-scope",
+      "title": "Engagement overlay",
+      "description": "One request for a whole page of cards, read by every card in it. A storefront's feed and SERP are drawn from the search index, whose stored document can carry neither a per-reader flag nor a fast-moving counter — so without this scope the already-seen rows and the saved ones are indistinguishable from the rest, on exactly the two screens the state exists for. The container opens a scope with the ids it just rendered, GET /listings/engagement/ answers once, and each card looks itself up and lays the entry over its own row. No scope, a missing id, a read in flight and a read that FAILED are all the same silent no-op: the card draws from its row and the grid keeps working.",
+      "component": "ListingEngagementScope",
+      "covers": [
+        "ListingEngagementContext",
+        "ListingsProvider"
+      ],
+      "tokens": [
+        "text-muted"
+      ],
+      "variants": [
+        "default",
+        "unscoped",
+        "visitor",
+        "failed"
+      ],
+      "source": "demo/ListingEngagementScope.demo.tsx"
+    },
     {
       "id": "listings.favorites",
       "title": "Favourites",
@@ -869,6 +915,8 @@
     "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",
@@ -983,6 +1031,7 @@
     "listings.detail.stock",
     "listings.detail.take_down",
     "listings.detail.unreadable_features",
+    "listings.detail.views",
     "listings.detail.withdrawn",
     "listings.error.unknown",
     "listings.favorites.empty",
@@ -1051,6 +1100,7 @@
       "Favorites",
       "IMAGES_FIELD",
       "LISTINGS_ELEVATION_ACTIONS",
+      "LISTINGS_ENGAGEMENT_BATCH_LIMIT",
       "LISTINGS_ERRORS",
       "LISTINGS_ERROR_CODES",
       "LISTINGS_FLOWS",
@@ -1064,6 +1114,8 @@
       "LOCATION_FIELD",
       "ListingComposer",
       "ListingDetail",
+      "ListingEngagementContext",
+      "ListingEngagementScope",
       "ListingsProvider",
       "ListingsRuntimeContext",
       "MODERATION_STATUSES",
@@ -1085,6 +1137,8 @@
       "draftValuesFromWire",
       "droppedFeatureSlugs",
       "emptyDraftValues",
+      "engagementFor",
+      "engagementIds",
       "envelopeFieldErrors",
       "explainListingsError",
       "failedResults",
@@ -1094,10 +1148,12 @@
       "featuresFromDaoList",
       "flowEndpoints",
       "isBatchValid",
+      "isListingViewed",
       "isPubliclyVisible",
       "lifecycleCaption",
       "listingFieldErrors",
       "listingStatusView",
+      "listingViewCount",
       "listingsErrorBundleEn",
       "listingsI18nBundleEn",
       "listingsQueryKeys",
@@ -1120,6 +1176,8 @@
       "useCreateDraft",
       "useDeleteListing",
       "useElevatableMandateGate",
+      "useEngagedListing",
+      "useEngagementOverlay",
       "useFavoriteListing",
       "useFavoriteToggle",
       "useFavorites",
@@ -1128,6 +1186,9 @@
       "useListingCards",
       "useListingComposer",
       "useListingDetail",
+      "useListingEngagement",
+      "useListingEngagementOverlay",
+      "useListingEngagementScope",
       "useListingStatus",
       "useListingsAnalytics",
       "useListingsApi",
@@ -1138,7 +1199,8 @@
       "useMyListings",
       "usePublishListing",
       "useSaveDraft",
-      "useValidateDraft"
+      "useValidateDraft",
+      "withEngagement"
     ],
     "types": [
       "ComposeStage",
@@ -1165,6 +1227,11 @@
       "ListingDraftLimits",
       "ListingDraftPatch",
       "ListingDraftValues",
+      "ListingEngagement",
+      "ListingEngagementBag",
+      "ListingEngagementBatch",
+      "ListingEngagementFields",
+      "ListingEngagementScopeProps",
       "ListingFeatureDao",
       "ListingFeatureDaoUnion",
       "ListingFeatureType",
@@ -1204,6 +1271,7 @@
       "UseFavoritesOptions",
       "UseListingComposerOptions",
       "UseListingDetailOptions",
+      "UseListingEngagementOverlayOptions",
       "UseMyListingsOptions"
     ]
   }

package/nav-manifest.json

@@ -1,6 +1,6 @@
 {
   "package": "@stapel/listings-react",
-  "version": "0.18.2",
+  "version": "0.19.0",
   "entries": [
     {
       "id": "listings.detail",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stapel/listings-react",
-  "version": "0.18.2",
+  "version": "0.19.0",
   "description": "Headless React pair for stapel-listings: a typed client over the draft twin, the composer that turns a category schema into a submittable listing, and the owner's dashboard. Two independent axes are rendered as two — lifecycle `status` decides visibility and `moderation_status` decides nothing about it, so an edit to a live listing stays live and says 'under review' instead of vanishing. Feature values are drawn and mirrored by @stapel/attributes-react; photos arrive as an injected upload bag whose `refs` ARE `images_draft` and whose `settled` gates the submit; a publish refusal is routed onto the control that caused it by slug. Zero visual opinion in the main entry; an opt-in /default subpath ships the antd skin.",
   "license": "MIT",
   "repository": {
@@ -48,14 +48,14 @@
   ],
   "size-limit": [
     {
-      "name": "index — the headless pair (client + status axes + draft model + hooks): no antd. Raised 11 -> 12 KB for the elevation gate (useElevatableMandateGate + core's useElevation): the anonymous arm can now mint an identity for a named action instead of refusing, and that is a state hook the gate did not previously carry. Raised 11.5 -> 12 KB for envelopeFieldErrors and its API-field -> control table: a save-draft/create 400 names its field in the envelope rather than in a publish batch, and without the table the refusal had nowhere to land — which is how one over-precise coordinate painted two unreadable banners and left every control clean. Thirty-six bytes of routing table is what a legible refusal costs. Raised 12 -> 13 KB for two seams the mobile wave needed in the HEADLESS half: the category-feature copy source in model/features.ts (the option table a stored select does not carry, so a published listing prints \"Second-hand\" and not \"b-u\"), and firstUnsatisfied (the field a \"10 required details are still empty\" count actually points at, in the order the form asks). Both are model, not skin: a headless host renders its own controls and needs the same two answers",
+      "name": "index — the headless pair (client + status axes + draft model + hooks): no antd. Raised 11 -> 12 KB for the elevation gate (useElevatableMandateGate + core's useElevation): the anonymous arm can now mint an identity for a named action instead of refusing, and that is a state hook the gate did not previously carry. Raised 11.5 -> 12 KB for envelopeFieldErrors and its API-field -> control table: a save-draft/create 400 names its field in the envelope rather than in a publish batch, and without the table the refusal had nowhere to land — which is how one over-precise coordinate painted two unreadable banners and left every control clean. Thirty-six bytes of routing table is what a legible refusal costs. Raised 12 -> 13 KB for two seams the mobile wave needed in the HEADLESS half: the category-feature copy source in model/features.ts (the option table a stored select does not carry, so a published listing prints \"Second-hand\" and not \"b-u\"), and firstUnsatisfied (the field a \"10 required details are still empty\" count actually points at, in the order the form asks). Both are model, not skin: a headless host renders its own controls and needs the same two answers. Raised 13 -> 14 KB (measured 12.91) for the engagement overlay: a batch read, its normalized key, and the scope that runs it once for a page and hands every card its own entry. It is a whole new READ rather than a flag — and it is the read that makes the viewed/saved state visible at all on a feed and a SERP, which come from the search index and carry no per-viewer field. Landing at 12.91 of 13 would have been a budget passed by rounding",
       "path": "dist/index.js",
-      "limit": "13 KB"
+      "limit": "14 KB"
     },
     {
-      "name": "default — the antd skin (three cards, detail, composer, dashboard, the named slots and the delete confirmation) must stay out of the main bundle. Raised 17 -> 19 KB for the mobile wave: <ListingSerpCard> (photo strip + price-first block + action rail), <ListingFeedCard> and <FeedGrid> are two more card surfaces on the same shared target/favourite/photo parts, not three copies of one Raised 19 -> 20 KB for the desktop wave of the detail page: layout=\"split\" is a second ASSEMBLY of the money page (the sticky buy column, the two-column spec table, the widened measure) over the same parts, and GateReasonPopover is the blocked heart's third volume — the reason and the door disclosed on interaction, with the visually-hidden copy that keeps the refusal in the accessibility tree. Both are geometry and wiring, not new widgets",
+      "name": "default — the antd skin (three cards, detail, composer, dashboard, the named slots and the delete confirmation) must stay out of the main bundle. Raised 17 -> 19 KB for the mobile wave: <ListingSerpCard> (photo strip + price-first block + action rail), <ListingFeedCard> and <FeedGrid> are two more card surfaces on the same shared target/favourite/photo parts, not three copies of one Raised 19 -> 20 KB for the desktop wave of the detail page: layout=\"split\" is a second ASSEMBLY of the money page (the sticky buy column, the two-column spec table, the widened measure) over the same parts, and GateReasonPopover is the blocked heart's third volume — the reason and the door disclosed on interaction, with the visually-hidden copy that keeps the refusal in the accessibility tree. Both are geometry and wiring, not new widgets. Raised 20 -> 21 KB (measured 20.22) for the engagement wave, which is four small things and no new component: the disclosure became a controlled open/close so a pointer that hovers and then clicks does not shut the only explanation the control has; the heart draws a filled accent when saved and states a failed save through the shared ErrorAlert; an already-seen card dims through one rule in the sheet all three cards already hoist; and the listing page gained a view-count row. 216 bytes is what a control that reports its own outcome costs",
       "path": "dist/default/index.js",
-      "limit": "20 KB"
+      "limit": "21 KB"
     },
     {
       "name": "i18n/ru — the Russian bundle is opt-in, not carried by the main entry",
@@ -102,13 +102,13 @@
     "size-limit": "^11.2.0",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
-    "@stapel/attributes-react": "^0.12.1",
-    "@stapel/currencies-react": "^0.3.0",
+    "@stapel/attributes-react": "^0.13.0",
     "@stapel/core": "^0.23.1",
+    "@stapel/currencies-react": "^0.3.0",
     "@stapel/image": "^0.4.2",
     "@stapel/showcase": "^0.3.0",
     "@stapel/tokens": "^0.7.0",
-    "@stapel/tokens-antd": "^0.15.0"
+    "@stapel/tokens-antd": "^0.16.0"
   },
   "engines": {
     "node": ">=22"

package/src/analytics/generated/events.json

@@ -1,7 +1,7 @@
 {
   "$generated": "by scripts/gen-events.mjs — do not edit; drift-gated (pnpm gen:events:check)",
   "package": "@stapel/listings-react",
-  "version": "0.18.2",
+  "version": "0.19.0",
   "defined": [],
   "flows": []
 }

package/src/api/generated/schema.ts

@@ -45,15 +45,25 @@ export interface paths {
             cookie?: never;
         };
         /**
-         * @description Listings CRUD plus owner lifecycle actions and favorites.
+         * @description Read one listing — and count the open.
          *
-         *     Read and write live in one class, so the guest wall
-         *     (:func:`anonymous_write_refusal`, the ``ALLOW_ANONYMOUS_WRITES`` switch)
-         *     is applied per ACTION and never as a class permission: an anonymous
-         *     session must keep browsing and keep its favorites, and only the
-         *     authorship actions — ``create``, ``update``/``partial_update``,
-         *     ``save-draft``, ``publish`` — are the ones that turn a caller into a
-         *     seller.
+         *     A GET with a side effect, deliberately, because "opening a listing"
+         *     IS the event and a storefront that had to POST it separately would
+         *     report a different number than the page it drew (and would stop
+         *     reporting at all the moment a client forgot the second call).
+         *
+         *     The side effect is bounded on both ends. It cannot lie: the owner's
+         *     own opens and unattributable ones are refused inside
+         *     ``record_view``. And it cannot become a write per read: every repeat
+         *     open inside ``VIEW_DEDUP_WINDOW_SECONDS`` is one cache hit and no
+         *     query. The response is therefore safe to give a private cache and
+         *     must never be given a shared one — which is the pre-existing rule
+         *     for an authenticated read anyway.
+         *
+         *     ``viewed`` is annotated BEFORE the recording, so the open that first
+         *     sees a listing answers ``false`` and the next one answers ``true``.
+         *     A card that greyed itself out on the very read that discovered it
+         *     would be telling the reader they had already been here.
          *
          *     **Permissions:** `IsAuthenticatedOrReadOnly`
          */
@@ -308,6 +318,32 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/listings/api/v1/listings/engagement/": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * @description The per-viewer overlay for a page of cards, in one call.
+         *
+         *     ``AllowAny`` on purpose: ``view_count`` is public, and an anonymous
+         *     caller gets it with both per-viewer flags answering ``null``. A
+         *     storefront therefore makes the same request whether or not anyone is
+         *     signed in, and a guest's grid is not a second code path.
+         *
+         *     **Permissions:** `AllowAny`
+         */
+        get: operations["listings_api_v1_listings_engagement_retrieve"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/listings/api/v1/listings/my/counters/": {
         parameters: {
             query?: never;
@@ -522,8 +558,8 @@ export interface components {
             favorited: boolean;
             listing_id: number;
         };
-        FeatureDao: components["schemas"]["IntDao"] | components["schemas"]["FloatDao"] | components["schemas"]["StringDao"] | components["schemas"]["BoolDao"] | components["schemas"]["HexColorDao"] | components["schemas"]["SelectDao"] | components["schemas"]["DateDao"] | components["schemas"]["HeaderDao"] | components["schemas"]["HierarchicalSelectDao"] | components["schemas"]["ConvertibleUnitDao"] | components["schemas"]["RefSelectDao"] | components["schemas"]["RefHierarchicalSelectDao"] | components["schemas"]["GroupDao"];
-        FeatureDto: components["schemas"]["IntDto"] | components["schemas"]["FloatDto"] | components["schemas"]["StringDto"] | components["schemas"]["BoolDto"] | components["schemas"]["HexColorDto"] | components["schemas"]["SelectDto"] | components["schemas"]["DateDto"] | components["schemas"]["HeaderDto"] | components["schemas"]["HierarchicalSelectDto"] | components["schemas"]["ConvertibleUnitDto"] | components["schemas"]["RefSelectDto"] | components["schemas"]["RefHierarchicalSelectDto"] | components["schemas"]["GroupDto"];
+        FeatureDao: components["schemas"]["RefSelectDao"] | components["schemas"]["IntDao"] | components["schemas"]["FloatDao"] | components["schemas"]["StringDao"] | components["schemas"]["BoolDao"] | components["schemas"]["HexColorDao"] | components["schemas"]["SelectDao"] | components["schemas"]["DateDao"] | components["schemas"]["HeaderDao"] | components["schemas"]["HierarchicalSelectDao"] | components["schemas"]["ConvertibleUnitDao"] | components["schemas"]["RefHierarchicalSelectDao"] | components["schemas"]["GroupDao"];
+        FeatureDto: components["schemas"]["RefSelectDto"] | components["schemas"]["IntDto"] | components["schemas"]["FloatDto"] | components["schemas"]["StringDto"] | components["schemas"]["BoolDto"] | components["schemas"]["HexColorDto"] | components["schemas"]["SelectDto"] | components["schemas"]["DateDto"] | components["schemas"]["HeaderDto"] | components["schemas"]["HierarchicalSelectDto"] | components["schemas"]["ConvertibleUnitDto"] | components["schemas"]["RefHierarchicalSelectDto"] | components["schemas"]["GroupDto"];
         /** @description Serializer for FeatureValidationResult. */
         FeatureValidationResult: {
             id?: unknown;
@@ -738,7 +774,7 @@ export interface components {
             readonly id: number;
             title?: string;
             /** Format: decimal */
-            price?: string;
+            price?: string | null;
             /** Format: decimal */
             price_base?: string | null;
             currency?: string;
@@ -784,6 +820,8 @@ export interface components {
             stock_quantity?: number | null;
             status?: components["schemas"]["StatusD41Enum"];
             readonly is_favorited: boolean | null;
+            readonly viewed: boolean | null;
+            readonly view_count: number;
         };
         /** @description Full listing detail. */
         ListingDetail: {
@@ -795,7 +833,7 @@ export interface components {
             description?: string;
             language?: string;
             /** Format: decimal */
-            price?: string;
+            price?: string | null;
             /** Format: decimal */
             price_base?: string | null;
             currency?: string;
@@ -868,6 +906,8 @@ export interface components {
             /** Format: date-time */
             readonly updated_at: string;
             readonly is_favorited: boolean | null;
+            readonly viewed: boolean | null;
+            readonly view_count: number;
         };
         /**
          * @description Create/update the draft twin fields.
@@ -907,6 +947,30 @@ export interface components {
             /** Format: date-time */
             readonly updated_at: string;
         };
+        /**
+         * @description The per-viewer overlay for ONE listing in a batch read.
+         *
+         *     Exists because a storefront's grid does not come from this module: the
+         *     SERP is served by the search index, whose stored card can carry neither a
+         *     flag that differs per reader nor a counter that moves faster than a
+         *     document re-indexed on a listing event. So the grid draws the card from
+         *     search and asks HERE, once for the whole page, for the three things that
+         *     are about the person looking.
+         */
+        ListingEngagement: {
+            /** @description Distinct viewers who have opened this listing. Public — it is the same number for every reader. */
+            view_count: number;
+            /** @description Whether the CALLER has opened this listing before. `null` for an anonymous caller: nothing is remembered for a stranger, and `false` would be a claim rather than an absence. */
+            viewed: boolean | null;
+            /** @description Whether the CALLER has favorited it. `null` for anonymous, same reason. */
+            is_favorited: boolean | null;
+        };
+        /** @description ``{listing id: overlay}``. An id with no listing is simply absent. */
+        ListingEngagementBatch: {
+            items: {
+                [key: string]: components["schemas"]["ListingEngagement"];
+            };
+        };
         /** @description Lightweight status view (mirrors the listings.status comm Function). */
         ListingStatus: {
             status: components["schemas"]["StatusD41Enum"];
@@ -954,7 +1018,7 @@ export interface components {
             readonly id: number;
             title?: string;
             /** Format: decimal */
-            price?: string;
+            price?: string | null;
             /** Format: decimal */
             price_base?: string | null;
             currency?: string;
@@ -1000,6 +1064,8 @@ export interface components {
             stock_quantity?: number | null;
             status?: components["schemas"]["StatusD41Enum"];
             readonly is_favorited: boolean | null;
+            readonly viewed: boolean | null;
+            readonly view_count: number;
             moderation_status?: components["schemas"]["ModerationStatusEnum"];
             title_draft?: string;
             /** Format: decimal */
@@ -1641,6 +1707,28 @@ export interface operations {
             };
         };
     };
+    listings_api_v1_listings_engagement_retrieve: {
+        parameters: {
+            query: {
+                /** @description Listing ids, comma-separated or the parameter repeated. Capped at ENGAGEMENT_BATCH_LIMIT ids per call — one page of cards, not a crawl of the board. */
+                ids: string[];
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ListingEngagementBatch"];
+                };
+            };
+        };
+    };
     listings_api_v1_listings_my_counters_retrieve: {
         parameters: {
             query?: never;

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),