@stapel/listings-react 0.25.9 → 0.26.0

package/src/default/ListingCard.tsx

@@ -118,6 +118,11 @@ import { isListingViewed } from "../model/engagement.js";
 import { useEngagedListing } from "../headless/Engagement.js";
 import { useFavoriteToggle } from "../headless/Favorites.js";
 import { FavoriteHeart } from "./favorite.js";
+import {
+  LISTING_ACTIONS_CLASS,
+  LISTING_ACTIONS_OVERLAY_CLASS,
+  LISTING_CARD_ACTION_CLASS,
+} from "./actionRow.js";
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
 import { CardBadges, CardSpecLine } from "./CardBadges.js";
 import { SignInLink } from "./SignInLink.js";
@@ -330,7 +335,10 @@ export function cardTargetCss(): string {
     // of pictures with a torn right edge. One radius, stated by the card,
     // applied to the box that holds the pictures; the slides inside it are
     // square because the well is what has the shape.
-    `${media}{min-inline-size:0;overflow:hidden;` +
+    // `position:relative` is the containing block the favourite overlay is
+    // pinned inside (see `LISTING_ACTIONS_OVERLAY_CLASS`). A `relative` with
+    // no offsets moves no pixel of what is already in the well.
+    `${media}{position:relative;min-inline-size:0;overflow:hidden;` +
       `border-start-start-radius:var(--listing-card-radius);` +
       `border-start-end-radius:var(--listing-card-radius)}`,
     `${media} .${SKIN_CAROUSEL_SLIDE_CLASS}{border-radius:0}`,
@@ -670,53 +678,84 @@ export function ListingCard(props: ListingCardProps): ReactElement {
                   ? { linkComponent: props.linkComponent }
                   : {})}
               />
-            </div>
-
-            <div className={CARD_MAIN_CLASS}>
-              <CardTarget {...props} listingId={listing.id} label={targetLabel}>
-                {content}
-              </CardTarget>
 
-              {/* The heart, and only the heart, is a separate CONTROL outside the
-                  anchor: a button inside a link is neither valid HTML nor operable.
-                  Its refusal gets a line of its own here, which is the whole reason
-                  it is a row under the card rather than a glyph floating on the
-                  photograph. */}
+              {/* THE HEART IS ON THE PHOTOGRAPH (owner, 2026-09-06).
+                  It used to be a row UNDER the card, on the argument that a
+                  blocked visitor's reason needs a line of text to live on and
+                  there is nowhere to put one on top of a picture. Half of
+                  that survived: the reason and the door still stand in their
+                  own row below (see the block after this one), and only the
+                  CONTROL moved. What it buys is the ergonomics every
+                  reference classified has and this card did not — the heart
+                  in the corner of the picture, where a thumb already is,
+                  reachable without opening the listing and without the eye
+                  travelling past a price, a title, a spec line and a place to
+                  find it.
+
+                  Top-trailing is the one free corner: the strip's dots own
+                  the bottom centre and the "3 of 16" counter owns the bottom
+                  trailing corner (`cardGalleryCss`).
+
+                  `stopPropagation` on the bubble phase, not the capture: the
+                  heart is already a SIBLING of the slide anchors rather than
+                  a child, so nothing should reach the card from here — but a
+                  press that did would open the listing instead of saving it,
+                  and a capture-phase stop would swallow the disclosure's own
+                  activation on the way in. */}
               {props.showFavorite === false ? null : (
                 <div
-                  style={{
-                    paddingInline: token.paddingSM,
-                    paddingBlockEnd: token.paddingSM,
+                  className={`${LISTING_ACTIONS_CLASS} ${LISTING_ACTIONS_OVERLAY_CLASS}`}
+                  data-testid="listings-card-favorite-overlay"
+                  onClick={(event) => {
+                    event.stopPropagation();
                   }}
                 >
                   {/* THE SHARED HEART, not a second copy of it.
                       This card drew its own — a `<Button aria-disabled>` in
                       the popover arm with `onClick={favorite.toggle}` behind
                       it — and that copy stopped tracking `<FavoriteHeart>` the
-                      day the door landed (D431): on the desktop GRID a
-                      visitor's press reached a no-op toggle, announced itself
-                      as unavailable, and went nowhere, while the same press on
-                      the SERP row and the feed card opened the sign-in door.
-                      One control, one refusal shape, one door.
+                      day the door landed (D431). One control, one refusal
+                      shape, one door.
 
                       The two derived ids are pinned to what this card has
                       always published, because a rename is a breaking change
                       dressed as a refactor. */}
-                  <Flex justify="flex-end" style={{ width: "100%" }}>
-                    <FavoriteHeart
-                      listingId={listing.id}
-                      favorited={listing.is_favorited}
-                      testId="listings-card-favorite"
-                      gateTestId="listings-card-actions"
-                      signInTestId="listings-card-sign-in"
-                      style={{ width: "100%" }}
-                      {...(blockedReason === "popover"
-                        ? { blockedReason: "popover" as const }
-                        : {})}
-                      {...(props.signIn !== undefined ? { signIn: props.signIn } : {})}
-                    />
-                  </Flex>
+                  <FavoriteHeart
+                    listingId={listing.id}
+                    favorited={listing.is_favorited}
+                    testId="listings-card-favorite"
+                    gateTestId="listings-card-actions"
+                    signInTestId="listings-card-sign-in"
+                    className={LISTING_CARD_ACTION_CLASS}
+                    {...(blockedReason === "popover"
+                      ? { blockedReason: "popover" as const }
+                      : {})}
+                    {...(props.signIn !== undefined ? { signIn: props.signIn } : {})}
+                  />
+                </div>
+              )}
+            </div>
 
+            <div className={CARD_MAIN_CLASS}>
+              <CardTarget {...props} listingId={listing.id} label={targetLabel}>
+                {content}
+              </CardTarget>
+
+              {/* THE REFUSAL'S OWN LINE, which is all that is left down here.
+                  The control moved onto the photograph; the sentence a
+                  blocked visitor needs cannot follow it there, so it keeps
+                  the row it has always had — and the row is drawn only when
+                  there is something to put in it, rather than as an empty
+                  strip of padding under every card on the page. */}
+              {props.showFavorite === false ||
+              favoriteGate.reason === undefined ||
+              blockedReason !== "text" ? null : (
+                <div
+                  style={{
+                    paddingInline: token.paddingSM,
+                    paddingBlockEnd: token.paddingSM,
+                  }}
+                >
                   {/* The DOOR AS A STANDING LINE, which is this card's own
                       decision and not the heart's: `blockedReason="line"`
                       drops it (twenty-four doors to one place is not
@@ -724,15 +763,12 @@ export function ListingCard(props: ListingCardProps): ReactElement {
                       put it inside the disclosure. The press itself routes
                       through the door in every arm — that part is the heart's.
                       */}
-                  {favoriteGate.reason === undefined ||
-                  blockedReason !== "text" ? null : (
-                    <Typography.Text
-                      type="secondary"
-                      data-testid="listings-card-favorite-blocked"
-                    >
-                      <SignInLink cta={props.signIn} testId="listings-card-sign-in" />
-                    </Typography.Text>
-                  )}
+                  <Typography.Text
+                    type="secondary"
+                    data-testid="listings-card-favorite-blocked"
+                  >
+                    <SignInLink cta={props.signIn} testId="listings-card-sign-in" />
+                  </Typography.Text>
                 </div>
               )}
             </div>

package/src/default/ListingDetailPane.tsx

@@ -50,6 +50,7 @@
  * that knows the viewport it granted, never a media query guessed in a leaf —
  * and the default `"column"` renders exactly what existing hosts already get.
  */
+import { isValidElement } from "react";
 import type { ReactElement, ReactNode } from "react";
 import { Descriptions, Divider, Flex, Typography, theme as antdTheme } from "antd";
 import { SkinButton as Button } from "@stapel/tokens-antd/skin";
@@ -68,14 +69,19 @@ import {
   useT,
 } from "@stapel/core";
 import type { SignInCta } from "@stapel/core";
-import { spacing } from "@stapel/tokens";
+import { cssVar, spacing } from "@stapel/tokens";
 import { isRedactedValue } from "@stapel/attributes-react";
 import { useListingDetail } from "../headless/ListingDetail.js";
 import { useListingActions } from "../headless/ListingActions.js";
 import { asFeatureDaoList, featureValuesForDisplay } from "../model/features.js";
 import { formatSpecValue } from "../model/featureText.js";
 import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
+import type { ShareChannel } from "../headless/Share.js";
 import { GateReasonPopover } from "./GateReasonPopover.js";
+import { ListingActions } from "./ListingActions.js";
+import type { ListingActionsConfig } from "./ListingActions.js";
+import { LISTING_ACTION_CLASS } from "./actionRow.js";
+import { useNotice } from "./notice.js";
 import { ListingSpecColumns, ListingSpecList } from "./ListingSpecList.js";
 import { SignInLink } from "./SignInLink.js";
 import { HeartIcon } from "./icons.js";
@@ -114,6 +120,28 @@ export const DETAIL_SPLIT_ASIDE = "380px";
  * postage stamp on the other. */
 export const DETAIL_PHOTO_MIN = "14rem";
 
+/**
+ * THE GUTTER BETWEEN TWO PHOTOGRAPHS, and it is the page's own (D418).
+ *
+ * The gallery painted a flat `spacing[3]` — 12px on a 390px phone and 12px on
+ * a 1280px desktop — while the page around it had already decided that its
+ * edge is 4px on a phone and 24px on a desktop. Measured on the live listing:
+ * `getComputedStyle(gallery).gap` answered `12px` at both widths, so neither
+ * of the two declared numbers was ever on screen and the tiles sat closer
+ * together than the page edge on a desktop and three times further apart than
+ * it on a phone.
+ *
+ * `--stapel-page-gutter` is a RESPONSIVE token role (`@stapel/tokens`: 4px
+ * phone, 8px tablet, 24px desktop, declared once with its own media arms), and
+ * reading it as a VAR rather than computing a number is the load-bearing half:
+ * a value picked in JS is applied at render, so a window resized between
+ * renders keeps the gutter it was drawn with, where a var reflows. Written
+ * through `cssVar` so a renamed role fails to compile instead of silently
+ * resolving to nothing, with the flat value this grid used before as the
+ * fallback for a host that loads no token stylesheet.
+ */
+export const DETAIL_GALLERY_GUTTER: string = `${cssVar("page-gutter").slice(0, -1)}, ${String(spacing[3])}px)`;
+
 export interface ListingDetailPaneProps
   extends ThemeModeProp,
     CategoryFeaturesProp {
@@ -184,10 +212,59 @@ export interface ListingDetailPaneProps
   /** Open the composer on this listing — the owner's primary. Absent is a real
    * answer: the button then states that this app has no editing screen. */
   readonly onEdit?: (id: number) => void;
-  /** Extra chrome beside the primary (the seller's profile link, a share
-   * button). Cross-pair navigation is the container's job (spec §6.2 item 5),
-   * so this pair takes nodes rather than routes. */
-  readonly actions?: ReactNode;
+  /**
+   * TWO THINGS UNDER ONE NAME, and the type tells them apart.
+   *
+   *  - a NODE — extra chrome beside the primary (the seller's profile link, a
+   *    control from another pair). What this prop has always been, unchanged,
+   *    and still rendered at the end of the buy box. Cross-pair navigation is
+   *    the container's job (spec §6.2 item 5), so this pair takes nodes
+   *    rather than routes.
+   *  - a CONFIG — `{ share: false }` / `{ favorite: false }`, switching off
+   *    one of the page's own two reader actions.
+   *
+   * A union rather than a second prop, because they are the same question
+   * ("what is in the action row") asked from two sides, and it is
+   * unambiguous at runtime: a plain object that is not a React element was
+   * never a legal `ReactNode` in the first place — React refuses to render
+   * one — so `{ share: false }` cannot be a node that somebody meant.
+   */
+  readonly actions?: ReactNode | ListingActionsConfig;
+  /**
+   * The listing's CANONICAL address, for the share sheet — the route the
+   * container built (`/l/7`, or an absolute URL), not the address bar.
+   *
+   * Absent, sharing falls back to `window.location.href`, which is honest for
+   * a bare mount and wrong for a real app: the address a visitor is standing
+   * on carries the SERP query they arrived from, the page anchor and whatever
+   * tracking parameters came with them, and none of that belongs in a link
+   * somebody sends to a friend. See `useShare`.
+   */
+  readonly shareUrl?: string;
+  /** Analytics: which channel a completed share went through. */
+  readonly onShared?: (channel: ShareChannel) => void;
+  /**
+   * How many people saved this listing, when the host was told by something
+   * else. The listings wire carries `is_favorited` — a per-reader boolean —
+   * and no aggregate at all, so this pair never invents the number and never
+   * draws a zero in place of "nobody counted".
+   */
+  readonly favoriteCount?: number;
+  /**
+   * WHERE THE READER'S TWO ACTIONS SIT.
+   *
+   *  - `"header"` (default) — beside the title, at the trailing edge of the
+   *    heading row, which is where the reference classified puts them and
+   *    where a person looks for them on both a phone and a desktop;
+   *  - `"gallery"` — pinned over the photographs' trailing top corner, for a
+   *    phone-first host that wants them on the picture. The corner is chosen
+   *    rather than free: the dots own the bottom centre of the strip and the
+   *    photo counter owns the bottom trailing corner;
+   *  - `"buy-box"` — inside `listings-detail-actions`, beside "message the
+   *    seller", which is where the favourite alone used to live. The escape
+   *    hatch for a host whose page was laid out around it.
+   */
+  readonly actionsPlacement?: "header" | "gallery" | "buy-box";
   /**
    * The container's sign-in door, rendered beside the favourite's refusal —
    * the same `SignInCta` seam the three card skins already take. The pane was
@@ -221,8 +298,28 @@ export interface ListingDetailPaneProps
   readonly footer?: ReactNode;
 }
 
+/**
+ * Which arm of `actions` this is.
+ *
+ * A plain object that is not a React element and not an array was never a
+ * legal `ReactNode` — React throws on rendering one — so there is no value a
+ * caller could have meant as chrome that lands here. `null` and `undefined`
+ * are nodes (the empty ones) and stay on the node side.
+ */
+function isActionsConfig(
+  value: ReactNode | ListingActionsConfig
+): value is ListingActionsConfig {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    !isValidElement(value)
+  );
+}
+
 export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
   const t = useT();
+  const notice = useNotice();
   const { locale } = useI18n();
   const { token } = antdTheme.useToken();
   const bag = useListingDetail(props.id, {
@@ -238,6 +335,16 @@ export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
   // leaves rendering the reason to `<GatedControl>`, which computes its own.
   const favoriteView = useActionGate(bag.favoriteGate);
   const split = props.layout === "split";
+  const placement = props.actionsPlacement ?? "header";
+  // The two arms of `actions` — see `isActionsConfig`.
+  const actionsConfig: ListingActionsConfig | undefined = isActionsConfig(
+    props.actions
+  )
+    ? props.actions
+    : undefined;
+  const actionsNode: ReactNode = isActionsConfig(props.actions)
+    ? null
+    : props.actions;
 
   const favoriteLabel = t(
     bag.isFavorited
@@ -253,6 +360,29 @@ export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
       {...(bag.isFavorited ? { color: token.colorPrimary } : {})}
     />
   );
+  /**
+   * The press, and the sentence it earns.
+   *
+   * The heart on this page is icon-only (§23: the reference draws a 44×44
+   * glyph where this pane drew a 152px button with a word in it), so the
+   * only thing a person reads back off the gesture is a fill changing colour
+   * in the corner of a row. That is enough to SEE and not enough to be sure
+   * of, which is what the toast is for — raised from the state the icon is
+   * about to draw, so both arrive together. A write that then fails rolls the
+   * icon back and says so through `listings-detail-favorite-error`.
+   */
+  const pressFavorite = (): void => {
+    const next = !bag.isFavorited;
+    bag.toggleFavorite();
+    if (!bag.favoriteGate.available) return;
+    notice(
+      t(
+        next
+          ? LISTINGS_I18N_KEYS.favoriteAdded
+          : LISTINGS_I18N_KEYS.favoriteRemoved
+      )
+    );
+  };
 
   return (
     <SkinTheme
@@ -338,6 +468,108 @@ export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
               </>
             );
 
+            /* THE READER'S TWO ACTIONS, as one cluster — see
+               `<ListingActions>` and `actionsPlacement`.
+
+               The heart is handed IN rather than mounted by the cluster:
+               this page's favourite is driven by `useListingDetail`'s own
+               optimistic bag (it holds the whole listing and flips the row it
+               already has), not by `useFavoriteToggle` against a card row.
+               One control, two hooks, one geometry.
+
+               The OWNER gets the share button and no heart: favouriting your
+               own listing is not a thing anyone does, and sending somebody
+               your own listing is the first thing a seller does. */
+            const favoriteControl =
+              owner ? null : props.blockedReason === "popover" &&
+                favoriteView.reason !== undefined ? (
+                  /* The cards' third volume, verbatim: nothing standing, the
+                     reason and the door disclosed on the heart. `aria-disabled`
+                     rather than `disabled`, so the disclosure's hover, focus
+                     and tap all arrive — and the click is a safe no-op, because
+                     `toggleFavorite` refuses while the gate is blocked. */
+                  <GateReasonPopover
+                    reason={favoriteView.reason}
+                    cta={props.signIn}
+                    testId="listings-detail-favorite-reason"
+                  signInTestId="listings-detail-sign-in"
+                >
+                  {(bind) => (
+                    <Button
+                      shape="circle"
+                      aria-disabled
+                      {...bind}
+                      className={LISTING_ACTION_CLASS}
+                      aria-label={favoriteLabel}
+                      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={pressFavorite}
+                    />
+                  )}
+                </GateReasonPopover>
+              ) : (
+                <Flex vertical gap={spacing[1]}>
+                  <GatedControl
+                    gate={bag.favoriteGate}
+                    testId="listings-detail-favorite-gate"
+                  >
+                    {(bind) => (
+                      <Button
+                        shape="circle"
+                        // See `<ListingCard>`: the binding, spread whole.
+                        {...bind}
+                        className={LISTING_ACTION_CLASS}
+                        aria-label={favoriteLabel}
+                        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={pressFavorite}
+                      />
+                    )}
+                  </GatedControl>
+                  {/* The door. `GatedControl` prints the reason; where a
+                      visitor signs in is the container's, and arrives as
+                      `signIn` — the cards' own pattern, verbatim. */}
+                  {bag.favoriteGate.available ? null : (
+                    <Typography.Text
+                      type="secondary"
+                      data-testid="listings-detail-favorite-blocked"
+                    >
+                      <SignInLink cta={props.signIn} testId="listings-detail-sign-in" />
+                    </Typography.Text>
+                  )}
+                </Flex>
+              );
+
+            const readerActions = (
+              <ListingActions
+                listingId={props.id}
+                favorite={favoriteControl}
+                testId="listings-detail-reader-actions"
+                placement={placement === "gallery" ? "overlay" : "inline"}
+                actions={{
+                  ...actionsConfig,
+                  // The owner keeps the share button and loses the heart.
+                  ...(owner ? { favorite: false } : {}),
+                }}
+                {...(props.favoriteCount !== undefined && !owner
+                  ? { favoriteCount: props.favoriteCount }
+                  : {})}
+                {...(props.shareUrl !== undefined ? { shareUrl: props.shareUrl } : {})}
+                {...(listing.title !== undefined && listing.title !== null
+                  ? { shareTitle: listing.title }
+                  : {})}
+                {...(props.onShared !== undefined ? { onShared: props.onShared } : {})}
+              />
+            );
+
             /* Element-width tiles: the grid decides how many fit, the
                photos fill them. */
             const gallery = (
@@ -346,7 +578,13 @@ export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
                 style={{
                   display: "grid",
                   gridTemplateColumns: `repeat(auto-fit, minmax(${DETAIL_PHOTO_MIN}, 1fr))`,
-                  gap: spacing[3],
+                  // The page's own edge, per breakpoint — see
+                  // `DETAIL_GALLERY_GUTTER` (D418).
+                  gap: DETAIL_GALLERY_GUTTER,
+                  // The containing block the overlay arm is pinned to. A
+                  // `relative` with no offsets moves no pixel of what is
+                  // already in it — the same trick `cardGalleryCss` uses.
+                  position: "relative",
                 }}
               >
                 {bag.images.length === 0 ? (
@@ -366,17 +604,30 @@ export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
                     />
                   ))
                 )}
+                {placement === "gallery" ? readerActions : null}
               </div>
             );
 
             const heading = (
               <>
-                <Typography.Title
-                  level={props.headingLevel ?? 3}
-                  data-testid="listings-detail-title"
-                >
-                  {listing.title ?? ""}
-                </Typography.Title>
+                {/* THE TITLE AND THE TWO ACTIONS SHARE A LINE (§23).
+                    The reference classified puts save-and-share at the
+                    trailing edge of the heading, on a phone and on a desktop
+                    alike, and that is the only place on this page where a
+                    person looks for them. `align-items:flex-start` so a
+                    two-line title does not drag the glyphs down its second
+                    line; `minWidth:0` so a long unbroken word wraps instead
+                    of pushing them off the pane. */}
+                <Flex align="flex-start" justify="space-between" gap={spacing[3]}>
+                  <Typography.Title
+                    level={props.headingLevel ?? 3}
+                    data-testid="listings-detail-title"
+                    style={{ minWidth: 0, flex: "1 1 auto" }}
+                  >
+                    {listing.title ?? ""}
+                  </Typography.Title>
+                  {placement === "header" ? readerActions : null}
+                </Flex>
 
                 {/* The `show_at_title` projection, formatted from the stored
                     DAOs — no category read needed (see model/features.ts). */}
@@ -487,76 +738,12 @@ export function ListingDetailPane(props: ListingDetailPaneProps): ReactElement {
                   </div>
                 )}
 
-                {/* Favouriting your own listing is not a thing anyone does;
-                    for everyone else it is the secondary it always was. */}
-                {owner ? null : props.blockedReason === "popover" &&
-                  favoriteView.reason !== undefined ? (
-                  /* The cards' third volume, verbatim: nothing standing, the
-                     reason and the door disclosed on the heart. `aria-disabled`
-                     rather than `disabled`, so the disclosure's hover, focus
-                     and tap all arrive — and the click is a safe no-op, because
-                     `toggleFavorite` refuses while the gate is blocked. */
-                  <GateReasonPopover
-                    reason={favoriteView.reason}
-                    cta={props.signIn}
-                    testId="listings-detail-favorite-reason"
-                    signInTestId="listings-detail-sign-in"
-                  >
-                    {(bind) => (
-                      <Button
-                        aria-disabled
-                        {...bind}
-                        aria-label={favoriteLabel}
-                        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}
-                      >
-                        {favoriteLabel}
-                      </Button>
-                    )}
-                  </GateReasonPopover>
-                ) : (
-                  <Flex vertical gap={spacing[1]}>
-                    <GatedControl
-                      gate={bag.favoriteGate}
-                      testId="listings-detail-favorite-gate"
-                    >
-                      {(bind) => (
-                        <Button
-                          // See `<ListingCard>`: the binding, spread whole.
-                          {...bind}
-                          aria-label={favoriteLabel}
-                          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}
-                        >
-                          {favoriteLabel}
-                        </Button>
-                      )}
-                    </GatedControl>
-                    {/* The door. `GatedControl` prints the reason; where a
-                        visitor signs in is the container's, and arrives as
-                        `signIn` — the cards' own pattern, verbatim. */}
-                    {bag.favoriteGate.available ? null : (
-                      <Typography.Text
-                        type="secondary"
-                        data-testid="listings-detail-favorite-blocked"
-                      >
-                        <SignInLink cta={props.signIn} testId="listings-detail-sign-in" />
-                      </Typography.Text>
-                    )}
-                  </Flex>
-                )}
+                {/* The reader's two actions live in the cluster now (see
+                    `actionsPlacement`); the buy box keeps them only when a
+                    host asks for the layout this page used to have. */}
+                {placement === "buy-box" ? readerActions : null}
 
-                {props.actions}
+                {actionsNode}
               </Flex>
             );
 

package/src/default/ListingFeedCard.tsx

@@ -66,6 +66,7 @@ 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 { LISTING_CARD_ACTION_CLASS } from "./actionRow.js";
 import {
   CARD_TARGET_STYLE_HREF,
   CARD_VIEWED_CLASS,
@@ -246,6 +247,7 @@ export function ListingFeedCard(props: ListingFeedCardProps): ReactElement {
             listingId={listing.id}
             favorited={listing.is_favorited}
             testId="listings-feed-favorite"
+            className={LISTING_CARD_ACTION_CLASS}
             blockedReason={props.blockedReason ?? "popover"}
             {...(props.signIn !== undefined ? { signIn: props.signIn } : {})}
             style={HEART}

package/src/default/ListingPhoto.tsx

@@ -32,6 +32,7 @@ import { radii, spacing } from "@stapel/tokens";
 import { useListingsRuntime } from "../model/context.js";
 import {
   CARD_GALLERY_CLASS,
+  CARD_GALLERY_COUNTER_CLASS,
   CARD_GALLERY_STYLE_HREF,
   cardGalleryCss,
   useCardGallery,
@@ -312,6 +313,33 @@ export function ListingPhotoStrip(props: {
               )
             )}
       </SkinCarousel>
+
+      {/* HOW MANY PHOTOGRAPHS THERE ARE, and which one this is.
+
+          The dots say WHERE in the strip a reader is and stop being countable
+          at about five; only a number says there are sixteen. The mobile walk
+          measured the card with dots and no counter beside a reference that
+          leads with "1 of 16", and on a phone — where the whole strip is one
+          photograph wide — the count is the only thing that says a swipe is
+          worth making.
+
+          `aria-live="polite"` because it changes without the reader doing
+          anything a screen reader would otherwise report: a swipe scrolls the
+          strip natively and this text is the only announcement of the move.
+          One photograph gets none of it, exactly as it gets no dots and no
+          peek — there is nothing to count. */}
+      {many ? (
+        <span
+          className={CARD_GALLERY_COUNTER_CLASS}
+          data-testid={`${props.testId}-counter`}
+          aria-live="polite"
+        >
+          {t(LISTINGS_I18N_KEYS.cardPhotoCounter, {
+            index: gallery.active + 1,
+            total: images.length,
+          })}
+        </span>
+      ) : null}
     </div>
   );
 }