@bearmenu/ui 0.8.20 → 0.8.22

package/dist/components/coach-marks.d.ts

@@ -25,15 +25,50 @@ import * as React from 'react';
  * side, re-measure on scroll and resize) and the keys (Escape closes, the
  * arrows step). `onProgress` reports the current stop for a toolbar label.
  *
- * Rendered into `document.body`: a page wrapper with an opacity or transform
- * transition is a stacking context, and the tour must sit above everything
- * the page and its chrome draw, whatever wraps the consumer.
+ * The spotlight is a hole in the dimming, in hit-testing as well as in
+ * paint: a tap on the ringed control reaches it. A gold ring around a real,
+ * un-dimmed control is an invitation, and a tour that swallowed the tap
+ * would be lying. Acting ends the tour — the thing the reader opened is the
+ * lesson, and whatever it opened would otherwise sit under or over an
+ * `aria-modal` dialog that promises the page beneath is inert. The consumer
+ * has already heard the stop through `onProgress`, so a "N new" door can
+ * pick the tour up later. The dimmed page itself does not close the tour: a
+ * thumb resting on it while reading is not a decision.
+ *
+ * A target is scrolled into view only when it is not already in it. The
+ * page's fixed chrome (`inset`) narrows what "in view" means, and a stop can
+ * opt out of scrolling altogether (`scroll: false`): `scrollIntoView` on a
+ * pinned rail scrolls the document to the rail's in-flow position, which is
+ * the top of whatever it pins over, and a reader mid-feed loses their place.
+ *
+ * Rendered into `document.body` above every drawer, sheet and dialog: a page
+ * wrapper with an opacity or transform transition is a stacking context, and
+ * the tour must sit above everything the page and its chrome draw, whatever
+ * wraps the consumer.
  */
 type CoachMarkStop = {
     /** Matches the target's `data-coach-mark` attribute. */
     id: string;
     title: string;
     body: string;
+    /**
+     * A `control` (a button, a field, a toggle) wears the gold ring; a `region`
+     * (a list, a rail, a block) is defined by the cut-out's edge alone. Stated,
+     * not inferred: a toggle group is a div of buttons and a results region a
+     * list of links. Defaults to `control`.
+     */
+    kind?: "control" | "region";
+    /**
+     * Never scroll to this target — for a control pinned to the viewport, whose
+     * box says where it is but whose in-flow position is somewhere else.
+     * Defaults to scrolling when the target is out of view.
+     */
+    scroll?: boolean;
+};
+/** The viewport's fixed chrome: what a target must clear to count as in view. */
+type CoachMarksInset = {
+    top?: number;
+    bottom?: number;
 };
 type CoachMarksLabels = {
     /** "Step 2 of 4". */
@@ -47,7 +82,7 @@ type CoachMarksLabels = {
 type CoachMarksProps = {
     open: boolean;
     stops: CoachMarkStop[];
-    /** Skip, Done, Escape and a tap on the dimmed page all end here. */
+    /** Skip, Done, Escape and a tap on the spotlit target all end here. */
     onClose: () => void;
     /**
      * 1-based position, the count of stops the page actually has, and the
@@ -56,8 +91,10 @@ type CoachMarksProps = {
      */
     onProgress?: (step: number, total: number, stop: CoachMarkStop) => void;
     labels: CoachMarksLabels;
+    /** The page's fixed header and bottom bar, in px; the callout keeps clear of them too. */
+    inset?: CoachMarksInset;
     className?: string;
 };
-declare function CoachMarks({ open, stops, onClose, onProgress, labels, className }: CoachMarksProps): React.ReactPortal | null;
+declare function CoachMarks({ open, stops, onClose, onProgress, labels, inset, className, }: CoachMarksProps): React.ReactPortal | null;
 
-export { type CoachMarkStop, CoachMarks, type CoachMarksLabels, type CoachMarksProps };
+export { type CoachMarkStop, CoachMarks, type CoachMarksInset, type CoachMarksLabels, type CoachMarksProps };

package/dist/components/coach-marks.js

@@ -3,7 +3,7 @@ import '../chunk-RIH2IS7X.js';
 import '../chunk-5YNIQ2BL.js';
 import { cn } from '../chunk-FEK5XGZW.js';
 import '../chunk-MMUBH76A.js';
-import { useState, useLayoutEffect, useCallback, useEffect } from 'react';
+import { useState, useLayoutEffect, useCallback, useRef, useEffect } from 'react';
 import { createPortal } from 'react-dom';
 import { Lightbulb, ArrowRight } from 'lucide-react';
 import { jsxs, jsx } from 'react/jsx-runtime';
@@ -13,7 +13,15 @@ var CALLOUT_WIDTH = 320;
 var CALLOUT_GAP = 14;
 var CALLOUT_ROOM = 280;
 var EDGE = 12;
+var PIN_SIZE = 32;
+var PIN_SNAP = 56;
+var CARET_MARGIN = 16;
 var PIN = "pointer-events-none absolute z-[1] flex h-8 w-8 -translate-x-1/2 -translate-y-1/2 items-center justify-center rounded-full bg-[oklch(0.26_0.03_60)] text-[13px] font-extrabold text-[oklch(0.82_0.15_85)] ring-2 ring-[oklch(0.82_0.15_85)] shadow-[0_2px_8px_oklch(0.16_0.012_55_/_0.45)] transition-[top,left] duration-300 motion-reduce:transition-none";
+function dimClip(spot, viewport) {
+  const right = spot.left + spot.width;
+  const bottom = spot.top + spot.height;
+  return `polygon(evenodd, 0 0, ${viewport.width}px 0, ${viewport.width}px ${viewport.height}px, 0 ${viewport.height}px, 0 0, ${spot.left}px ${spot.top}px, ${spot.left}px ${bottom}px, ${right}px ${bottom}px, ${right}px ${spot.top}px, ${spot.left}px ${spot.top}px)`;
+}
 function findTarget(id) {
   if (typeof document === "undefined") return null;
   const candidates = document.querySelectorAll(`[data-coach-mark="${id}"]`);
@@ -26,7 +34,22 @@ function measure(element) {
   const box = element.getBoundingClientRect();
   return { top: box.top, left: box.left, width: box.width, height: box.height };
 }
-function CoachMarks({ open, stops, onClose, onProgress, labels, className }) {
+function inView(element, inset) {
+  var _a, _b;
+  const box = element.getBoundingClientRect();
+  return box.top - PAD >= ((_a = inset.top) != null ? _a : 0) && box.bottom + PAD <= window.innerHeight - ((_b = inset.bottom) != null ? _b : 0);
+}
+var NO_INSET = {};
+function CoachMarks({
+  open,
+  stops,
+  onClose,
+  onProgress,
+  labels,
+  inset = NO_INSET,
+  className
+}) {
+  var _a, _b;
   const [available, setAvailable] = useState([]);
   const [index, setIndex] = useState(0);
   const [rect, setRect] = useState(null);
@@ -34,36 +57,57 @@ function CoachMarks({ open, stops, onClose, onProgress, labels, className }) {
   const itinerary = stops.map((stop) => stop.id).join("|");
   useLayoutEffect(() => {
     if (!open) return;
-    const present = stops.filter((stop) => findTarget(stop.id));
+    const present = stops.filter((stop) => findTarget(stop.id)).map((stop) => stop.id);
     setAvailable(present);
     setIndex(0);
     if (present.length === 0) onClose();
   }, [open, itinerary]);
-  const current = available[index];
-  const currentId = current == null ? void 0 : current.id;
+  const currentId = available[index];
+  const current = currentId ? stops.find((stop) => stop.id === currentId) : void 0;
+  const scrolls = (current == null ? void 0 : current.scroll) !== false;
+  const insetTop = (_a = inset.top) != null ? _a : 0;
+  const insetBottom = (_b = inset.bottom) != null ? _b : 0;
   const remeasure = useCallback(() => {
     const element = currentId ? findTarget(currentId) : null;
     setRect(element ? measure(element) : null);
     setViewport({ width: window.innerWidth, height: window.innerHeight });
   }, [currentId]);
   useLayoutEffect(() => {
-    if (!open || !current) return;
-    const element = findTarget(current.id);
+    if (!open || !currentId) return;
+    const element = findTarget(currentId);
     if (!element) {
-      const forward = available.findIndex((stop, at) => at > index && findTarget(stop.id));
+      const forward = available.findIndex((id, at) => at > index && findTarget(id));
       if (forward !== -1) setIndex(forward);
       else onClose();
       return;
     }
-    element.scrollIntoView({ block: "center", behavior: "smooth", inline: "nearest" });
+    if (scrolls) {
+      const band = window.innerHeight - insetTop - insetBottom;
+      const tall = element.getBoundingClientRect().height + PAD * 2 > band;
+      const visible = inView(element, { top: insetTop, bottom: insetBottom });
+      element.style.scrollMarginTop = `${insetTop + PAD}px`;
+      element.scrollIntoView({
+        block: visible ? "nearest" : tall ? "start" : "center",
+        behavior: "smooth",
+        inline: "nearest"
+      });
+    }
     remeasure();
     const settle = setTimeout(remeasure, 400);
-    return () => clearTimeout(settle);
-  }, [open, current, index, available, remeasure, onClose]);
+    return () => {
+      clearTimeout(settle);
+      element.style.scrollMarginTop = "";
+    };
+  }, [open, currentId, scrolls, index, available, insetTop, insetBottom, remeasure, onClose]);
+  const progressRef = useRef(onProgress);
+  useLayoutEffect(() => {
+    progressRef.current = onProgress;
+  });
   useEffect(() => {
+    var _a2;
     if (!open || !current) return;
-    onProgress == null ? void 0 : onProgress(index + 1, available.length, current);
-  }, [open, current, index, available.length, onProgress]);
+    (_a2 = progressRef.current) == null ? void 0 : _a2.call(progressRef, index + 1, available.length, current);
+  }, [open, currentId, index, available.length]);
   useEffect(() => {
     if (!open) return;
     window.addEventListener("resize", remeasure);
@@ -73,73 +117,105 @@ function CoachMarks({ open, stops, onClose, onProgress, labels, className }) {
       if (event.key === "ArrowRight") setIndex((at) => Math.min(at + 1, available.length - 1));
       if (event.key === "ArrowLeft") setIndex((at) => Math.max(at - 1, 0));
     };
+    const onClick = (event) => {
+      const target = currentId ? findTarget(currentId) : null;
+      if (target && event.target instanceof Node && target.contains(event.target)) onClose();
+    };
     window.addEventListener("keydown", onKey);
+    window.addEventListener("click", onClick, true);
     return () => {
       window.removeEventListener("resize", remeasure);
       window.removeEventListener("scroll", remeasure, true);
       window.removeEventListener("keydown", onKey);
+      window.removeEventListener("click", onClick, true);
     };
-  }, [open, remeasure, onClose, available.length]);
+  }, [open, currentId, remeasure, onClose, available.length]);
   if (!open || !current || !rect) return null;
   const last = index === available.length - 1;
+  const region = current.kind === "region";
   const spot = {
     top: rect.top - PAD,
     left: rect.left - PAD,
     width: rect.width + PAD * 2,
     height: rect.height + PAD * 2
   };
-  const roomBelow = viewport.height - (spot.top + spot.height);
+  const small = rect.width <= PIN_SNAP || rect.height <= PIN_SNAP;
+  const pinLeft = small ? spot.left : rect.left - 2;
+  const pinTop = spot.top - PIN_SIZE / 2 < insetTop + EDGE ? spot.top + spot.height : small ? spot.top : rect.top - 2;
+  const bandTop = insetTop;
+  const bandBottom = viewport.height - insetBottom;
+  const roomBelow = bandBottom - (spot.top + spot.height);
+  const roomAbove = spot.top - bandTop;
   const calloutLeft = Math.min(
     Math.max(spot.left, EDGE),
     Math.max(EDGE, viewport.width - CALLOUT_WIDTH - EDGE)
   );
-  const calloutPlace = roomBelow > CALLOUT_ROOM ? { top: spot.top + spot.height + CALLOUT_GAP, left: calloutLeft } : spot.top > CALLOUT_ROOM ? { bottom: viewport.height - spot.top + CALLOUT_GAP, left: calloutLeft } : { bottom: EDGE, left: calloutLeft };
+  const side = roomBelow > CALLOUT_ROOM ? "below" : roomAbove > CALLOUT_ROOM ? "above" : "edge";
+  const calloutPlace = side === "below" ? { top: spot.top + spot.height + CALLOUT_GAP, left: calloutLeft } : side === "above" ? { bottom: viewport.height - spot.top + CALLOUT_GAP, left: calloutLeft } : { bottom: viewport.height - bandBottom + EDGE, left: calloutLeft };
+  const calloutWidth = Math.min(CALLOUT_WIDTH, viewport.width - EDGE * 2);
+  const caretLeft = Math.min(
+    Math.max(spot.left + spot.width / 2 - calloutLeft, CARET_MARGIN),
+    calloutWidth - CARET_MARGIN
+  );
   return createPortal(
     /* @__PURE__ */ jsxs(
       "div",
       {
-        className: cn("fixed inset-0 z-[80]", className),
+        className: cn("pointer-events-none fixed inset-0 z-[1100]", className),
         role: "dialog",
         "aria-modal": true,
         "aria-label": current.title,
         children: [
           /* @__PURE__ */ jsx(
-            "button",
+            "div",
             {
-              type: "button",
-              "aria-label": labels.skip,
-              onClick: onClose,
-              className: "absolute inset-0 cursor-default"
+              "aria-hidden": true,
+              className: "pointer-events-auto absolute inset-0",
+              style: { clipPath: dimClip(spot, viewport) }
             }
           ),
           /* @__PURE__ */ jsx(
             "div",
             {
               "aria-hidden": true,
-              className: "pointer-events-none absolute rounded-[18px] shadow-[0_0_0_9999px_oklch(0.16_0.012_55_/_0.55)] ring-2 ring-[oklch(0.82_0.15_85)] transition-[top,left,width,height] duration-300 motion-reduce:transition-none",
+              className: cn(
+                "pointer-events-none absolute shadow-[0_0_0_9999px_oklch(0.16_0.012_55_/_0.55)] transition-[top,left,width,height] duration-300 motion-reduce:transition-none",
+                region ? "rounded-2xl" : "rounded-[18px] ring-2 ring-[oklch(0.82_0.15_85)]"
+              ),
               style: spot
             }
           ),
-          /* @__PURE__ */ jsx("span", { "aria-hidden": true, className: PIN, style: { top: rect.top - 2, left: rect.left - 2 }, children: index + 1 }),
+          /* @__PURE__ */ jsx("span", { "aria-hidden": true, className: PIN, style: { top: pinTop, left: pinLeft }, children: index + 1 }),
           /* @__PURE__ */ jsxs(
             "div",
             {
-              className: "absolute z-[2] w-[min(320px,calc(100vw-24px))] rounded-2xl border border-border bg-card p-4 text-card-foreground shadow-xl",
+              className: "pointer-events-auto absolute z-[2] w-[min(320px,calc(100vw-24px))] rounded-2xl border border-border bg-card p-4 text-card-foreground shadow-[var(--shadow-overlay)]",
               style: calloutPlace,
               children: [
-                /* @__PURE__ */ jsxs("span", { className: "inline-flex items-center gap-1.5 rounded-full bg-[oklch(0.82_0.15_85)] px-2.5 py-1 text-[10.5px] font-extrabold uppercase tracking-[0.08em] text-[oklch(0.26_0.03_60)]", children: [
+                side !== "edge" && /* @__PURE__ */ jsx(
+                  "span",
+                  {
+                    "aria-hidden": true,
+                    className: cn(
+                      "absolute h-3 w-3 -translate-x-1/2 rotate-45 border-border bg-card",
+                      side === "below" ? "-top-[7px] border-l border-t" : "-bottom-[7px] border-b border-r"
+                    ),
+                    style: { left: caretLeft }
+                  }
+                ),
+                /* @__PURE__ */ jsxs("span", { className: "inline-flex items-center gap-1.5 rounded-full bg-[oklch(0.82_0.15_85)] px-2.5 py-1 text-xs font-extrabold uppercase tracking-[0.08em] text-[oklch(0.26_0.03_60)]", children: [
                   /* @__PURE__ */ jsx(Lightbulb, { className: "h-3 w-3", "aria-hidden": true }),
                   labels.progress(index + 1, available.length)
                 ] }),
-                /* @__PURE__ */ jsx("p", { className: "mt-3 text-[15px] font-bold leading-snug", children: current.title }),
+                /* @__PURE__ */ jsx("p", { className: "mt-3 text-base font-semibold leading-snug", children: current.title }),
                 /* @__PURE__ */ jsx("p", { className: "mt-1.5 text-sm leading-relaxed text-muted-foreground", children: current.body }),
                 /* @__PURE__ */ jsxs("div", { className: "mt-4 flex items-center gap-2", children: [
-                  index > 0 && /* @__PURE__ */ jsx(Button, { type: "button", variant: "ghost", size: "sm", onClick: () => setIndex(index - 1), children: labels.back }),
+                  index > 0 && /* @__PURE__ */ jsx(Button, { type: "button", variant: "ghost", size: "pill", onClick: () => setIndex(index - 1), children: labels.back }),
                   /* @__PURE__ */ jsxs(
                     Button,
                     {
                       type: "button",
-                      size: "sm",
+                      size: "pill",
                       onClick: () => last ? onClose() : setIndex(index + 1),
                       children: [
                         last ? labels.done : labels.next,
@@ -147,7 +223,17 @@ function CoachMarks({ open, stops, onClose, onProgress, labels, className }) {
                       ]
                     }
                   ),
-                  /* @__PURE__ */ jsx(Button, { type: "button", variant: "link", size: "sm", className: "ml-auto", onClick: onClose, children: labels.skip })
+                  /* @__PURE__ */ jsx(
+                    Button,
+                    {
+                      type: "button",
+                      variant: "link",
+                      size: "sm",
+                      className: "ml-auto min-h-11",
+                      onClick: onClose,
+                      children: labels.skip
+                    }
+                  )
                 ] })
               ]
             }

package/dist/components/menu-filter-chips.d.ts

@@ -39,22 +39,25 @@ type MenuFilterChipsProps = {
     onToggle: (key: string) => void;
     /** The unit and the current total, composed by the caller, e.g. "KITCHENS · 247". */
     unitLabel?: string;
-    /** Opens the full filter sheet. Omit for a row where every facet is a chip. */
+    /** Opens the full filter panel. Omit for a row where every facet is a chip. */
     onMore?: () => void;
     moreLabel?: string;
     /**
-     * A glyph for the phone's icon-only "more filters" button.
+     * The glyph on the "more filters" pill.
      *
-     * The label is the widest fixed element in the row — "More filters" is ~80px
-     * of a 358px viewport, and it is the one thing that never scrolls, so it eats
-     * the chips' runway on every phone. Given an icon, the button collapses to a
-     * square below `lg` and keeps `moreLabel` as its accessible name.
+     * The pill is a chip like the others in the row — same border, same height —
+     * so the way out of the row reads as part of the row, not as a link beside
+     * it. The label is the widest fixed element in the row ("More filters" is
+     * ~80px of a 358px viewport) and the one thing that never scrolls, so below
+     * `lg` the pill collapses to a square carrying only the glyph, with
+     * `moreLabel` as its accessible name; from `lg` it shows both.
      *
      * A node rather than a name because the app owns its iconography, and this
      * one is animated on press — the DS neither knows the glyph nor drives it.
+     * Without a glyph the pill shows the label at every width.
      */
     moreIcon?: React.ReactNode;
-    /** Press handler for the icon button, e.g. to replay the glyph's animation. */
+    /** Press handler for the pill, e.g. to replay the glyph's animation. */
     onMorePointerDown?: () => void;
     /** Locale-aware integer formatter for the counts. Defaults to `String`. */
     formatCount?: (value: number) => string;

package/dist/components/menu-filter-chips.js

@@ -3,7 +3,7 @@ import { Skeleton } from '../chunk-XBBEX4SF.js';
 import { cn } from '../chunk-FEK5XGZW.js';
 import '../chunk-MMUBH76A.js';
 import { X } from 'lucide-react';
-import { jsxs, jsx, Fragment } from 'react/jsx-runtime';
+import { jsxs, jsx } from 'react/jsx-runtime';
 
 function MenuFilterChips({
   chips,
@@ -39,36 +39,28 @@ function MenuFilterChips({
         )) })
       }
     ),
-    onMore && /* @__PURE__ */ jsxs(Fragment, { children: [
-      moreIcon && /* @__PURE__ */ jsx(
-        "button",
-        {
-          type: "button",
-          onClick: onMore,
-          onPointerDown: onMorePointerDown,
-          "aria-label": moreLabel,
-          "aria-haspopup": "dialog",
-          className: cn(
-            "inline-flex shrink-0 items-center justify-center rounded-full border border-border text-accent transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring motion-reduce:transition-none lg:hidden",
-            // The one control that never scrolls keeps the chips' height.
-            chipSize === "lg" ? "size-11" : "size-10"
-          ),
-          children: moreIcon
-        }
-      ),
-      /* @__PURE__ */ jsx(
-        "button",
-        {
-          type: "button",
-          onClick: onMore,
-          className: cn(
-            "shrink-0 rounded-md pl-2 text-[12.5px] font-bold text-accent transition-colors hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring motion-reduce:transition-none",
-            moreIcon && "hidden lg:inline"
-          ),
-          children: moreLabel
-        }
-      )
-    ] })
+    onMore && /* @__PURE__ */ jsxs(
+      "button",
+      {
+        type: "button",
+        onClick: onMore,
+        onPointerDown: onMorePointerDown,
+        "aria-label": moreLabel,
+        "aria-haspopup": "dialog",
+        className: cn(
+          // The chip's own chrome, so the pinned control and the scrolling
+          // chips read as one row. `shrink-0` against the scrolling chips.
+          "inline-flex shrink-0 items-center justify-center gap-1.5 whitespace-nowrap rounded-full border border-border bg-card text-sm text-foreground transition-colors hover:border-accent/40 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring motion-reduce:transition-none",
+          chipSize === "lg" ? "h-11" : "h-9",
+          // With a glyph: a square below `lg`, the glyph and the label from it.
+          moreIcon ? chipSize === "lg" ? "w-11 lg:w-auto lg:px-4" : "w-9 lg:w-auto lg:px-4" : "px-4"
+        ),
+        children: [
+          moreIcon,
+          /* @__PURE__ */ jsx("span", { className: cn(moreIcon && "hidden lg:inline"), children: moreLabel })
+        ]
+      }
+    )
   ] });
 }
 function Chip({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bearmenu/ui",
-  "version": "0.8.20",
+  "version": "0.8.22",
   "description": "BearMenu design system — shared UI tokens, primitives, and components",
   "license": "UNLICENSED",
   "repository": {

package/src/components/coach-marks.stories.tsx

@@ -12,7 +12,7 @@ const meta: Meta<typeof CoachMarks> = {
     docs: {
       description: {
         component:
-          "A guided tour drawn over the real page: the page dims, the current step's target is cut out in a spotlight with its step number on the corner, one callout says what the target is. Targets are `data-coach-mark` attributes on the page's own elements.",
+          "A guided tour drawn over the real page: the page dims, the current step's target is cut out in a spotlight with its step number on the corner, one callout says what the target is. Targets are `data-coach-mark` attributes on the page's own elements. The spotlight is a hole in the dimming: a tap on the ringed control reaches it and ends the tour. A `region` stop (a list, a rail) is cut out without the ring; a pinned control passes `scroll: false`; `inset` names the page's fixed chrome.",
       },
     },
   },
@@ -37,14 +37,23 @@ const STOPS: CoachMarkStop[] = [
     title: "Cards, or rows",
     body: "The same menu items either way: rows fit three times as many.",
   },
+  {
+    id: "results",
+    kind: "region",
+    title: "What matched",
+    body: "A region is cut out without the ring; tapping a row inside it navigates, and the tour steps out of the way.",
+  },
 ];
 
 function Demo() {
   const [open, setOpen] = useState(true);
+  const [taps, setTaps] = useState(0);
   return (
     <div className="min-h-[720px] bg-background p-8 text-foreground">
       <div className="flex items-center gap-3">
-        <Button data-coach-mark="search">Search and filter</Button>
+        <Button data-coach-mark="search" onClick={() => setTaps((count) => count + 1)}>
+          Search and filter{taps > 0 ? ` · tapped ${taps}` : ""}
+        </Button>
         <Button variant="outline" data-coach-mark="view">
           Rows
         </Button>
@@ -57,9 +66,16 @@ function Demo() {
         <span>Centru ×</span>
       </div>
       <p className="mt-10 max-w-[60ch] text-sm text-muted-foreground">
-        The page beneath the tour. Nothing here re-renders; the overlay measures the three targets
-        and draws over them.
+        The page beneath the tour. Nothing here re-renders; the overlay measures the targets and
+        draws over them. Tap the spotlit button: the tap lands, and the tour ends.
       </p>
+      <ul data-coach-mark="results" className="mt-6 max-w-md divide-y divide-border rounded-2xl border border-border">
+        {["Papanași", "Ciorbă de burtă", "Sarmale"].map((name) => (
+          <li key={name} className="px-4 py-3 text-sm">
+            {name}
+          </li>
+        ))}
+      </ul>
       <CoachMarks
         open={open}
         stops={STOPS}

package/src/components/coach-marks.test.tsx

@@ -1,4 +1,5 @@
-import { describe, expect, it, vi } from "vitest";
+import { useState } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { fireEvent, render, screen } from "@testing-library/react";
 import { CoachMarks, type CoachMarkStop } from "./coach-marks";
 
@@ -55,8 +56,10 @@ function pins(): string[] {
 }
 
 // jsdom has no layout: every rect is zero, which is enough to render. A
-// target has boxes when it is in the document, none when it is not.
-Element.prototype.scrollIntoView = vi.fn();
+// target has boxes when it is in the document, none when it is not. The
+// scroll mock sits on HTMLElement, where the test setup's stub is.
+const scrollIntoView = vi.fn();
+HTMLElement.prototype.scrollIntoView = scrollIntoView;
 Element.prototype.getClientRects = function () {
   return (this.isConnected ? [{}] : []) as unknown as DOMRectList;
 };
@@ -121,13 +124,185 @@ describe("CoachMarks", () => {
     expect(onClose).not.toHaveBeenCalled();
   });
 
-  it("Skip, Escape and the dimmed page all close", () => {
+  it("Skip and Escape close; the dimmed page does not", () => {
     const onClose = vi.fn();
     render(<Page onClose={onClose} />);
     fireEvent.click(screen.getByText("Skip"));
     fireEvent.keyDown(window, { key: "Escape" });
-    fireEvent.click(screen.getAllByRole("button", { name: "Skip" })[0]);
-    expect(onClose).toHaveBeenCalledTimes(3);
+    expect(onClose).toHaveBeenCalledTimes(2);
+    expect(screen.getAllByRole("button", { name: "Skip" })).toHaveLength(1);
+    const dim = screen.getByRole("dialog").firstElementChild;
+    fireEvent.click(dim as Element);
+    expect(onClose).toHaveBeenCalledTimes(2);
+  });
+
+  it("a tap on the spotlit target reaches it and ends the tour", () => {
+    const onClose = vi.fn();
+    const onTarget = vi.fn();
+    render(
+      <>
+        <button type="button" data-coach-mark="a" onClick={onTarget}>
+          a
+        </button>
+        <button type="button" data-coach-mark="b">
+          b
+        </button>
+        <CoachMarks open stops={STOPS.slice(0, 2)} onClose={onClose} labels={labels} />
+      </>
+    );
+    fireEvent.click(screen.getByRole("button", { name: "b" }));
+    expect(onClose).not.toHaveBeenCalled();
+    fireEvent.click(screen.getByRole("button", { name: "a" }));
+    expect(onTarget).toHaveBeenCalledTimes(1);
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("hears a tap on a target that stops propagation", () => {
+    const onClose = vi.fn();
+    render(
+      <>
+        <div data-coach-mark="a">
+          <button type="button" onClick={(event) => event.stopPropagation()}>
+            inner
+          </button>
+        </div>
+        <CoachMarks open stops={STOPS.slice(0, 1)} onClose={onClose} labels={labels} />
+      </>
+    );
+    fireEvent.click(screen.getByRole("button", { name: "inner" }));
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("settles when the consumer rebuilds its stops and inset on every render", () => {
+    const onProgress = vi.fn();
+    function Consumer() {
+      const [progress, setProgress] = useState<string>("");
+      return (
+        <>
+          <button type="button" data-coach-mark="a">
+            a
+          </button>
+          <span data-testid="progress">{progress}</span>
+          <CoachMarks
+            open
+            stops={STOPS.slice(0, 1).map((stop) => ({ ...stop }))}
+            inset={{ top: 68 }}
+            onClose={vi.fn()}
+            onProgress={(step, total, stop) => {
+              onProgress(step, total, stop);
+              setProgress(`${step}/${total}`);
+            }}
+            labels={labels}
+          />
+        </>
+      );
+    }
+    render(<Consumer />);
+    expect(screen.getByTestId("progress")).toHaveTextContent("1/1");
+    expect(onProgress).toHaveBeenCalledTimes(1);
+  });
+
+  it("a region is cut out without the control's ring", () => {
+    const { rerender } = render(<Page onClose={vi.fn()} />);
+    const spotlight = () => screen.getByRole("dialog").children[1];
+    expect(spotlight().className).toContain("ring-2");
+    rerender(<Page onClose={vi.fn()} stops={STOPS.map((stop) => ({ ...stop, kind: "region" }))} />);
+    expect(spotlight().className).not.toContain("ring-2");
+  });
+
+  describe("scrolling to the target", () => {
+    /** A page whose targets sit at `top`, `height` 40, in an 800px viewport. */
+    function placeTargets(top: number) {
+      vi.spyOn(window, "innerHeight", "get").mockReturnValue(800);
+      vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockReturnValue({
+        top,
+        bottom: top + 40,
+        left: 0,
+        right: 100,
+        width: 100,
+        height: 40,
+        x: 0,
+        y: top,
+        toJSON: () => ({}),
+      });
+    }
+
+    beforeEach(() => scrollIntoView.mockClear());
+    afterEach(() => vi.restoreAllMocks());
+
+    it("centres a target out of view", () => {
+      placeTargets(900);
+      render(<Page onClose={vi.fn()} />);
+      expect(scrollIntoView).toHaveBeenCalledWith(expect.objectContaining({ block: "center" }));
+    });
+
+    it("leaves the page where it is when the target is already in view", () => {
+      placeTargets(300);
+      render(<Page onClose={vi.fn()} />);
+      // Still a request — it aborts the previous stop's smooth scroll — but
+      // one that moves nothing.
+      expect(scrollIntoView).toHaveBeenCalledWith(expect.objectContaining({ block: "nearest" }));
+    });
+
+    it("aligns a target taller than the band to its top, clear of the chrome", () => {
+      vi.spyOn(window, "innerHeight", "get").mockReturnValue(800);
+      vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockReturnValue({
+        top: 900,
+        bottom: 2400,
+        left: 0,
+        right: 100,
+        width: 100,
+        height: 1500,
+        x: 0,
+        y: 900,
+        toJSON: () => ({}),
+      });
+      render(
+        <>
+          <button type="button" data-coach-mark="a">
+            a
+          </button>
+          <CoachMarks
+            open
+            stops={STOPS.slice(0, 1)}
+            onClose={vi.fn()}
+            labels={labels}
+            inset={{ top: 68 }}
+          />
+        </>
+      );
+      expect(scrollIntoView).toHaveBeenCalledWith(expect.objectContaining({ block: "start" }));
+      expect(screen.getByRole("button", { name: "a" }).style.scrollMarginTop).toBe("76px");
+    });
+
+    it("counts the fixed chrome as out of view", () => {
+      placeTargets(20);
+      const { unmount } = render(<Page onClose={vi.fn()} />);
+      expect(scrollIntoView).toHaveBeenCalledWith(expect.objectContaining({ block: "nearest" }));
+      unmount();
+      scrollIntoView.mockClear();
+      render(
+        <>
+          <button type="button" data-coach-mark="a">
+            a
+          </button>
+          <CoachMarks
+            open
+            stops={STOPS.slice(0, 1)}
+            onClose={vi.fn()}
+            labels={labels}
+            inset={{ top: 68 }}
+          />
+        </>
+      );
+      expect(scrollIntoView).toHaveBeenCalledWith(expect.objectContaining({ block: "center" }));
+    });
+
+    it("never scrolls a stop that opted out — a pinned control", () => {
+      placeTargets(900);
+      render(<Page onClose={vi.fn()} stops={STOPS.map((stop) => ({ ...stop, scroll: false }))} />);
+      expect(scrollIntoView).not.toHaveBeenCalled();
+    });
   });
 
   it("closes at once when no stop has a target, and renders nothing while closed", () => {

package/src/components/coach-marks.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback, useEffect, useLayoutEffect, useState } from "react";
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
 import { createPortal } from "react-dom";
 import { ArrowRight, Lightbulb } from "lucide-react";
 import { cn } from "../lib/utils";
@@ -31,9 +31,26 @@ import { Button } from "./button";
  * side, re-measure on scroll and resize) and the keys (Escape closes, the
  * arrows step). `onProgress` reports the current stop for a toolbar label.
  *
- * Rendered into `document.body`: a page wrapper with an opacity or transform
- * transition is a stacking context, and the tour must sit above everything
- * the page and its chrome draw, whatever wraps the consumer.
+ * The spotlight is a hole in the dimming, in hit-testing as well as in
+ * paint: a tap on the ringed control reaches it. A gold ring around a real,
+ * un-dimmed control is an invitation, and a tour that swallowed the tap
+ * would be lying. Acting ends the tour — the thing the reader opened is the
+ * lesson, and whatever it opened would otherwise sit under or over an
+ * `aria-modal` dialog that promises the page beneath is inert. The consumer
+ * has already heard the stop through `onProgress`, so a "N new" door can
+ * pick the tour up later. The dimmed page itself does not close the tour: a
+ * thumb resting on it while reading is not a decision.
+ *
+ * A target is scrolled into view only when it is not already in it. The
+ * page's fixed chrome (`inset`) narrows what "in view" means, and a stop can
+ * opt out of scrolling altogether (`scroll: false`): `scrollIntoView` on a
+ * pinned rail scrolls the document to the rail's in-flow position, which is
+ * the top of whatever it pins over, and a reader mid-feed loses their place.
+ *
+ * Rendered into `document.body` above every drawer, sheet and dialog: a page
+ * wrapper with an opacity or transform transition is a stacking context, and
+ * the tour must sit above everything the page and its chrome draw, whatever
+ * wraps the consumer.
  */
 
 export type CoachMarkStop = {
@@ -41,6 +58,25 @@ export type CoachMarkStop = {
   id: string;
   title: string;
   body: string;
+  /**
+   * A `control` (a button, a field, a toggle) wears the gold ring; a `region`
+   * (a list, a rail, a block) is defined by the cut-out's edge alone. Stated,
+   * not inferred: a toggle group is a div of buttons and a results region a
+   * list of links. Defaults to `control`.
+   */
+  kind?: "control" | "region";
+  /**
+   * Never scroll to this target — for a control pinned to the viewport, whose
+   * box says where it is but whose in-flow position is somewhere else.
+   * Defaults to scrolling when the target is out of view.
+   */
+  scroll?: boolean;
+};
+
+/** The viewport's fixed chrome: what a target must clear to count as in view. */
+export type CoachMarksInset = {
+  top?: number;
+  bottom?: number;
 };
 
 export type CoachMarksLabels = {
@@ -56,7 +92,7 @@ export type CoachMarksLabels = {
 export type CoachMarksProps = {
   open: boolean;
   stops: CoachMarkStop[];
-  /** Skip, Done, Escape and a tap on the dimmed page all end here. */
+  /** Skip, Done, Escape and a tap on the spotlit target all end here. */
   onClose: () => void;
   /**
    * 1-based position, the count of stops the page actually has, and the
@@ -65,6 +101,8 @@ export type CoachMarksProps = {
    */
   onProgress?: (step: number, total: number, stop: CoachMarkStop) => void;
   labels: CoachMarksLabels;
+  /** The page's fixed header and bottom bar, in px; the callout keeps clear of them too. */
+  inset?: CoachMarksInset;
   className?: string;
 };
 
@@ -76,11 +114,28 @@ const CALLOUT_GAP = 14;
 /** The room a side needs before the callout goes there. */
 const CALLOUT_ROOM = 280;
 const EDGE = 12;
+/** The pin's disc. */
+const PIN_SIZE = 32;
+/** A target this small has its pin on the spotlight's corner, not over its own. */
+const PIN_SNAP = 56;
+/** The caret's inset from the callout's ends. */
+const CARET_MARGIN = 16;
 
 /** The step number, an inverted disc on the spotlight's corner: dark on the gold ring. */
 const PIN =
   "pointer-events-none absolute z-[1] flex h-8 w-8 -translate-x-1/2 -translate-y-1/2 items-center justify-center rounded-full bg-[oklch(0.26_0.03_60)] text-[13px] font-extrabold text-[oklch(0.82_0.15_85)] ring-2 ring-[oklch(0.82_0.15_85)] shadow-[0_2px_8px_oklch(0.16_0.012_55_/_0.45)] transition-[top,left] duration-300 motion-reduce:transition-none";
 
+/**
+ * The dimming with the spotlight cut out of it: one polygon drawn around the
+ * viewport and again around the spot, even-odd, so the spot is a hole in
+ * hit-testing as much as in paint.
+ */
+function dimClip(spot: Rect, viewport: { width: number; height: number }): string {
+  const right = spot.left + spot.width;
+  const bottom = spot.top + spot.height;
+  return `polygon(evenodd, 0 0, ${viewport.width}px 0, ${viewport.width}px ${viewport.height}px, 0 ${viewport.height}px, 0 0, ${spot.left}px ${spot.top}px, ${spot.left}px ${bottom}px, ${right}px ${bottom}px, ${right}px ${spot.top}px, ${spot.left}px ${spot.top}px)`;
+}
+
 /** The visible element carrying the id — a `display: none` twin has no boxes. */
 function findTarget(id: string): HTMLElement | null {
   if (typeof document === "undefined") return null;
@@ -96,11 +151,31 @@ function measure(element: HTMLElement): Rect {
   return { top: box.top, left: box.left, width: box.width, height: box.height };
 }
 
-export function CoachMarks({ open, stops, onClose, onProgress, labels, className }: CoachMarksProps) {
+/** Whole target inside the band the chrome leaves, with its breathing room. */
+function inView(element: HTMLElement, inset: CoachMarksInset): boolean {
+  const box = element.getBoundingClientRect();
+  return (
+    box.top - PAD >= (inset.top ?? 0) &&
+    box.bottom + PAD <= window.innerHeight - (inset.bottom ?? 0)
+  );
+}
+
+const NO_INSET: CoachMarksInset = {};
+
+export function CoachMarks({
+  open,
+  stops,
+  onClose,
+  onProgress,
+  labels,
+  inset = NO_INSET,
+  className,
+}: CoachMarksProps) {
   // The stops the page can show, fixed when the tour opens or the itinerary
   // changes — by its ids, so a consumer rebuilding the array each render does
-  // not send the tour back to the first stop.
-  const [available, setAvailable] = useState<CoachMarkStop[]>([]);
+  // not send the tour back to the first stop. The words are read live from
+  // `stops`, so a consumer may reword a stop without restarting the tour.
+  const [available, setAvailable] = useState<string[]>([]);
   const [index, setIndex] = useState(0);
   const [rect, setRect] = useState<Rect | null>(null);
   const [viewport, setViewport] = useState({ width: 0, height: 0 });
@@ -108,7 +183,7 @@ export function CoachMarks({ open, stops, onClose, onProgress, labels, className
 
   useLayoutEffect(() => {
     if (!open) return;
-    const present = stops.filter((stop) => findTarget(stop.id));
+    const present = stops.filter((stop) => findTarget(stop.id)).map((stop) => stop.id);
     setAvailable(present);
     setIndex(0);
     if (present.length === 0) onClose();
@@ -116,8 +191,13 @@ export function CoachMarks({ open, stops, onClose, onProgress, labels, className
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [open, itinerary]);
 
-  const current = available[index];
-  const currentId = current?.id;
+  const currentId = available[index];
+  const current = currentId ? stops.find((stop) => stop.id === currentId) : undefined;
+  const scrolls = current?.scroll !== false;
+  // Primitives, so a consumer passing `inset={{ top: 68 }}` inline — or
+  // rebuilding `stops` each render — does not re-run the effects below.
+  const insetTop = inset.top ?? 0;
+  const insetBottom = inset.bottom ?? 0;
 
   const remeasure = useCallback(() => {
     const element = currentId ? findTarget(currentId) : null;
@@ -125,28 +205,54 @@ export function CoachMarks({ open, stops, onClose, onProgress, labels, className
     setViewport({ width: window.innerWidth, height: window.innerHeight });
   }, [currentId]);
 
-  // Bring the current target into view, then measure it — again once the
-  // smooth scroll has settled.
+  // Bring the current target into view when it is not, then measure it —
+  // again once the smooth scroll has settled.
   useLayoutEffect(() => {
-    if (!open || !current) return;
-    const element = findTarget(current.id);
+    if (!open || !currentId) return;
+    const element = findTarget(currentId);
     if (!element) {
       // The page changed under the tour: move on, or end when nothing is left.
-      const forward = available.findIndex((stop, at) => at > index && findTarget(stop.id));
+      const forward = available.findIndex((id, at) => at > index && findTarget(id));
       if (forward !== -1) setIndex(forward);
       else onClose();
       return;
     }
-    element.scrollIntoView({ block: "center", behavior: "smooth", inline: "nearest" });
+    if (scrolls) {
+      // Always a scroll request, even for a target already in view: a new
+      // request aborts the previous stop's smooth scroll, which would
+      // otherwise carry on under this one and leave it off screen. A target
+      // taller than the band aligns to the band's top — centring a
+      // three-screen region scrolls into its middle — with `scroll-margin`
+      // standing in for the chrome, which `scrollIntoView` cannot see.
+      const band = window.innerHeight - insetTop - insetBottom;
+      const tall = element.getBoundingClientRect().height + PAD * 2 > band;
+      const visible = inView(element, { top: insetTop, bottom: insetBottom });
+      element.style.scrollMarginTop = `${insetTop + PAD}px`;
+      element.scrollIntoView({
+        block: visible ? "nearest" : tall ? "start" : "center",
+        behavior: "smooth",
+        inline: "nearest",
+      });
+    }
     remeasure();
     const settle = setTimeout(remeasure, 400);
-    return () => clearTimeout(settle);
-  }, [open, current, index, available, remeasure, onClose]);
+    return () => {
+      clearTimeout(settle);
+      element.style.scrollMarginTop = "";
+    };
+  }, [open, currentId, scrolls, index, available, insetTop, insetBottom, remeasure, onClose]);
 
+  // Reported once per stop — not once per rewording of it, nor once per
+  // consumer render when the callback is written inline.
+  const progressRef = useRef(onProgress);
+  useLayoutEffect(() => {
+    progressRef.current = onProgress;
+  });
   useEffect(() => {
     if (!open || !current) return;
-    onProgress?.(index + 1, available.length, current);
-  }, [open, current, index, available.length, onProgress]);
+    progressRef.current?.(index + 1, available.length, current);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [open, currentId, index, available.length]);
 
   useEffect(() => {
     if (!open) return;
@@ -157,91 +263,144 @@ export function CoachMarks({ open, stops, onClose, onProgress, labels, className
       if (event.key === "ArrowRight") setIndex((at) => Math.min(at + 1, available.length - 1));
       if (event.key === "ArrowLeft") setIndex((at) => Math.max(at - 1, 0));
     };
+    // The reader acted, and the tour steps out of the way. Capture phase: a
+    // control that stops propagation (a button nested in a larger tap
+    // target) would otherwise never be heard. The target's own handler still
+    // runs — closing the tour changes nothing under it.
+    const onClick = (event: MouseEvent) => {
+      const target = currentId ? findTarget(currentId) : null;
+      if (target && event.target instanceof Node && target.contains(event.target)) onClose();
+    };
     window.addEventListener("keydown", onKey);
+    window.addEventListener("click", onClick, true);
     return () => {
       window.removeEventListener("resize", remeasure);
       window.removeEventListener("scroll", remeasure, true);
       window.removeEventListener("keydown", onKey);
+      window.removeEventListener("click", onClick, true);
     };
-  }, [open, remeasure, onClose, available.length]);
+  }, [open, currentId, remeasure, onClose, available.length]);
 
   if (!open || !current || !rect) return null;
 
   const last = index === available.length - 1;
+  const region = current.kind === "region";
   const spot = {
     top: rect.top - PAD,
     left: rect.left - PAD,
     width: rect.width + PAD * 2,
     height: rect.height + PAD * 2,
   };
+  // The pin sits on the spotlight's corner for a small target — over its own
+  // corner it would cover a quarter of a 44px disc — and drops to the bottom
+  // corner when the top one would sit under the page's chrome.
+  const small = rect.width <= PIN_SNAP || rect.height <= PIN_SNAP;
+  const pinLeft = small ? spot.left : rect.left - 2;
+  const pinTop =
+    spot.top - PIN_SIZE / 2 < insetTop + EDGE
+      ? spot.top + spot.height
+      : small
+        ? spot.top
+        : rect.top - 2;
   // Below the target when there is room for the callout, else above it; a
-  // target taller than the viewport leaves room on neither side, and the
-  // callout then sits at the bottom edge, over the target's lower part.
-  const roomBelow = viewport.height - (spot.top + spot.height);
+  // target taller than the band leaves room on neither side, and the callout
+  // then sits at the band's bottom edge, over the target's lower part. The
+  // band is the viewport less the page's fixed chrome.
+  const bandTop = insetTop;
+  const bandBottom = viewport.height - insetBottom;
+  const roomBelow = bandBottom - (spot.top + spot.height);
+  const roomAbove = spot.top - bandTop;
   const calloutLeft = Math.min(
     Math.max(spot.left, EDGE),
     Math.max(EDGE, viewport.width - CALLOUT_WIDTH - EDGE)
   );
+  const side: "below" | "above" | "edge" =
+    roomBelow > CALLOUT_ROOM ? "below" : roomAbove > CALLOUT_ROOM ? "above" : "edge";
   const calloutPlace =
-    roomBelow > CALLOUT_ROOM
+    side === "below"
       ? { top: spot.top + spot.height + CALLOUT_GAP, left: calloutLeft }
-      : spot.top > CALLOUT_ROOM
+      : side === "above"
         ? { bottom: viewport.height - spot.top + CALLOUT_GAP, left: calloutLeft }
-        : { bottom: EDGE, left: calloutLeft };
+        : { bottom: viewport.height - bandBottom + EDGE, left: calloutLeft };
+  // The caret points at the spot's centre: a disc at the right edge leaves
+  // the callout 260px from its target with nothing between them otherwise.
+  const calloutWidth = Math.min(CALLOUT_WIDTH, viewport.width - EDGE * 2);
+  const caretLeft = Math.min(
+    Math.max(spot.left + spot.width / 2 - calloutLeft, CARET_MARGIN),
+    calloutWidth - CARET_MARGIN
+  );
 
   return createPortal(
     <div
-      className={cn("fixed inset-0 z-[80]", className)}
+      className={cn("pointer-events-none fixed inset-0 z-[1100]", className)}
       role="dialog"
       aria-modal
       aria-label={current.title}
     >
-      {/* The dimming is the spotlight's shadow: one element, cut out where
-          the target is, so the target stays fully visible and the rest of the
-          page falls back. A tap on the dim closes the tour. */}
-      <button
-        type="button"
-        aria-label={labels.skip}
-        onClick={onClose}
-        className="absolute inset-0 cursor-default"
+      {/* The dimming: one layer blocking the page, with the spotlight cut out
+          of it, so the target stays fully visible AND tappable. The scrim is
+          drawn by the spotlight's shadow beneath. */}
+      <div
+        aria-hidden
+        className="pointer-events-auto absolute inset-0"
+        style={{ clipPath: dimClip(spot, viewport) }}
       />
       <div
         aria-hidden
-        className="pointer-events-none absolute rounded-[18px] shadow-[0_0_0_9999px_oklch(0.16_0.012_55_/_0.55)] ring-2 ring-[oklch(0.82_0.15_85)] transition-[top,left,width,height] duration-300 motion-reduce:transition-none"
+        className={cn(
+          "pointer-events-none absolute shadow-[0_0_0_9999px_oklch(0.16_0.012_55_/_0.55)] transition-[top,left,width,height] duration-300 motion-reduce:transition-none",
+          region ? "rounded-2xl" : "rounded-[18px] ring-2 ring-[oklch(0.82_0.15_85)]"
+        )}
         style={spot}
       />
 
       {/* The step number on the spotlight's corner; the callout says the rest. */}
-      <span aria-hidden className={PIN} style={{ top: rect.top - 2, left: rect.left - 2 }}>
+      <span aria-hidden className={PIN} style={{ top: pinTop, left: pinLeft }}>
         {index + 1}
       </span>
 
       {/* The callout. */}
       <div
-        className="absolute z-[2] w-[min(320px,calc(100vw-24px))] rounded-2xl border border-border bg-card p-4 text-card-foreground shadow-xl"
+        className="pointer-events-auto absolute z-[2] w-[min(320px,calc(100vw-24px))] rounded-2xl border border-border bg-card p-4 text-card-foreground shadow-[var(--shadow-overlay)]"
         style={calloutPlace}
       >
-        <span className="inline-flex items-center gap-1.5 rounded-full bg-[oklch(0.82_0.15_85)] px-2.5 py-1 text-[10.5px] font-extrabold uppercase tracking-[0.08em] text-[oklch(0.26_0.03_60)]">
+        {side !== "edge" && (
+          <span
+            aria-hidden
+            className={cn(
+              "absolute h-3 w-3 -translate-x-1/2 rotate-45 border-border bg-card",
+              side === "below" ? "-top-[7px] border-l border-t" : "-bottom-[7px] border-b border-r"
+            )}
+            style={{ left: caretLeft }}
+          />
+        )}
+        <span className="inline-flex items-center gap-1.5 rounded-full bg-[oklch(0.82_0.15_85)] px-2.5 py-1 text-xs font-extrabold uppercase tracking-[0.08em] text-[oklch(0.26_0.03_60)]">
           <Lightbulb className="h-3 w-3" aria-hidden />
           {labels.progress(index + 1, available.length)}
         </span>
-        <p className="mt-3 text-[15px] font-bold leading-snug">{current.title}</p>
+        <p className="mt-3 text-base font-semibold leading-snug">{current.title}</p>
         <p className="mt-1.5 text-sm leading-relaxed text-muted-foreground">{current.body}</p>
         <div className="mt-4 flex items-center gap-2">
           {index > 0 && (
-            <Button type="button" variant="ghost" size="sm" onClick={() => setIndex(index - 1)}>
+            <Button type="button" variant="ghost" size="pill" onClick={() => setIndex(index - 1)}>
               {labels.back}
             </Button>
           )}
           <Button
             type="button"
-            size="sm"
+            size="pill"
             onClick={() => (last ? onClose() : setIndex(index + 1))}
           >
             {last ? labels.done : labels.next}
             {!last && <ArrowRight aria-hidden />}
           </Button>
-          <Button type="button" variant="link" size="sm" className="ml-auto" onClick={onClose}>
+          <Button
+            type="button"
+            variant="link"
+            size="sm"
+            className="ml-auto min-h-11"
+            onClick={onClose}
+          >
             {labels.skip}
           </Button>
         </div>

package/src/components/menu-filter-chips.stories.tsx

@@ -2,6 +2,7 @@ import { useState } from "react";
 import type { Meta, StoryObj } from "@storybook/react";
 import { Clock, Leaf, MapPin, Moon, Sun, Wallet } from "lucide-react";
 import { MenuFilterChips, MenuFilterSummary } from "./menu-filter-chips";
+import { MotionSliders } from "./motion-icon-controls";
 import { mockFilterChips } from "./menu-mocks";
 
 const icons: Record<string, React.ReactNode> = {
@@ -30,7 +31,7 @@ const meta: Meta<typeof MenuFilterChips> = {
     docs: {
       description: {
         component:
-          "Every chip counts KITCHENS, whatever facet is behind it — a dietary chip reads *has a vegetarian dish* and counts venues, not dishes. The unit is stated once at the head of the row and never again; the earlier version mixed venue counts and item counts and you could not tell what a number meant without re-reading the label that produced it. One line in every state: the chips scroll under a `ScrollFade`, and *More filters* is pinned opposite the unit label rather than wrapping.",
+          "Every chip counts KITCHENS, whatever facet is behind it — a dietary chip reads *has a vegetarian dish* and counts venues, not dishes. The unit is stated once at the head of the row and never again; the earlier version mixed venue counts and item counts and you could not tell what a number meant without re-reading the label that produced it. One line in every state: the chips scroll under a `ScrollFade`, and *More filters* is a chip-shaped pill pinned opposite the unit label rather than wrapping — a square carrying only its glyph below `lg`, glyph and label from it.",
       },
     },
   },
@@ -41,6 +42,7 @@ type Story = StoryObj<typeof MenuFilterChips>;
 
 function Interactive({ initial }: { initial: typeof chips }) {
   const [state, setState] = useState(initial);
+  const [replayToken, setReplayToken] = useState(0);
   const active = state.filter((chip) => chip.active).length;
 
   return (
@@ -49,6 +51,8 @@ function Interactive({ initial }: { initial: typeof chips }) {
         chips={state}
         unitLabel="KITCHENS · 247"
         moreLabel="More filters"
+        moreIcon={<MotionSliders replayToken={replayToken} className="size-4" />}
+        onMorePointerDown={() => setReplayToken((n) => n + 1)}
         onMore={() => {}}
         ariaLabel="Filter kitchens"
         onToggle={(key) =>

package/src/components/menu-filter-chips.test.tsx

@@ -0,0 +1,63 @@
+import { describe, it, expect, vi } from "vitest";
+import { fireEvent, render, screen } from "@testing-library/react";
+import { MenuFilterChips } from "./menu-filter-chips";
+import { mockFilterChips } from "./menu-mocks";
+
+describe("MenuFilterChips", () => {
+  /**
+   * The "more filters" control is ONE button at every width, shaped like the
+   * chips beside it. It used to be two elements — an icon square below `lg`
+   * and a bare text link from it — and the link read as a footnote rather
+   * than as the row's last chip.
+   */
+  it("renders the more control as a single chip-shaped pill carrying the glyph and the label", () => {
+    const onMore = vi.fn();
+    const onMorePointerDown = vi.fn();
+    render(
+      <MenuFilterChips
+        chips={mockFilterChips}
+        onToggle={() => {}}
+        moreLabel="More filters"
+        moreIcon={<svg data-testid="glyph" />}
+        onMore={onMore}
+        onMorePointerDown={onMorePointerDown}
+      />
+    );
+
+    const pills = screen.getAllByRole("button", { name: "More filters" });
+    expect(pills).toHaveLength(1);
+    const [pill] = pills;
+    expect(pill).toHaveAttribute("aria-haspopup", "dialog");
+    expect(pill.className).toContain("rounded-full");
+    expect(pill.className).toContain("border-border");
+    expect(pill.className).toContain("h-9");
+    expect(pill.className).toContain("lg:px-4");
+    expect(pill.querySelector("[data-testid='glyph']")).not.toBeNull();
+    expect(pill.querySelector("span")?.className).toContain("hidden lg:inline");
+
+    fireEvent.pointerDown(pill);
+    fireEvent.click(pill);
+    expect(onMorePointerDown).toHaveBeenCalledTimes(1);
+    expect(onMore).toHaveBeenCalledTimes(1);
+  });
+
+  it("shows the label at every width when no glyph is given", () => {
+    render(
+      <MenuFilterChips
+        chips={mockFilterChips}
+        onToggle={() => {}}
+        moreLabel="More filters"
+        onMore={() => {}}
+      />
+    );
+
+    const pill = screen.getByRole("button", { name: "More filters" });
+    expect(pill.className).toContain("px-4");
+    expect(pill.querySelector("span")?.className ?? "").not.toContain("hidden");
+  });
+
+  it("renders no more control without a handler", () => {
+    render(<MenuFilterChips chips={mockFilterChips} onToggle={() => {}} moreLabel="More filters" />);
+    expect(screen.queryByRole("button", { name: "More filters" })).toBeNull();
+  });
+});

package/src/components/menu-filter-chips.tsx

@@ -40,22 +40,25 @@ export type MenuFilterChipsProps = {
   onToggle: (key: string) => void;
   /** The unit and the current total, composed by the caller, e.g. "KITCHENS · 247". */
   unitLabel?: string;
-  /** Opens the full filter sheet. Omit for a row where every facet is a chip. */
+  /** Opens the full filter panel. Omit for a row where every facet is a chip. */
   onMore?: () => void;
   moreLabel?: string;
   /**
-   * A glyph for the phone's icon-only "more filters" button.
+   * The glyph on the "more filters" pill.
    *
-   * The label is the widest fixed element in the row — "More filters" is ~80px
-   * of a 358px viewport, and it is the one thing that never scrolls, so it eats
-   * the chips' runway on every phone. Given an icon, the button collapses to a
-   * square below `lg` and keeps `moreLabel` as its accessible name.
+   * The pill is a chip like the others in the row — same border, same height —
+   * so the way out of the row reads as part of the row, not as a link beside
+   * it. The label is the widest fixed element in the row ("More filters" is
+   * ~80px of a 358px viewport) and the one thing that never scrolls, so below
+   * `lg` the pill collapses to a square carrying only the glyph, with
+   * `moreLabel` as its accessible name; from `lg` it shows both.
    *
    * A node rather than a name because the app owns its iconography, and this
    * one is animated on press — the DS neither knows the glyph nor drives it.
+   * Without a glyph the pill shows the label at every width.
    */
   moreIcon?: React.ReactNode;
-  /** Press handler for the icon button, e.g. to replay the glyph's animation. */
+  /** Press handler for the pill, e.g. to replay the glyph's animation. */
   onMorePointerDown?: () => void;
   /** Locale-aware integer formatter for the counts. Defaults to `String`. */
   formatCount?: (value: number) => string;
@@ -117,39 +120,24 @@ export function MenuFilterChips({
       </ScrollFade>
 
       {onMore && (
-        <>
-          {/* One control, two shapes. On a phone it is a 40px square carrying
-              the caller's glyph, with `moreLabel` as its accessible name; from
-              `lg` it is the text link it has always been. Two elements rather
-              than one so neither has to carry the other's padding, and both
-              stay `shrink-0` against the scrolling chips. */}
-          {moreIcon && (
-            <button
-              type="button"
-              onClick={onMore}
-              onPointerDown={onMorePointerDown}
-              aria-label={moreLabel}
-              aria-haspopup="dialog"
-              className={cn(
-                "inline-flex shrink-0 items-center justify-center rounded-full border border-border text-accent transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring motion-reduce:transition-none lg:hidden",
-                // The one control that never scrolls keeps the chips' height.
-                chipSize === "lg" ? "size-11" : "size-10"
-              )}
-            >
-              {moreIcon}
-            </button>
+        <button
+          type="button"
+          onClick={onMore}
+          onPointerDown={onMorePointerDown}
+          aria-label={moreLabel}
+          aria-haspopup="dialog"
+          className={cn(
+            // The chip's own chrome, so the pinned control and the scrolling
+            // chips read as one row. `shrink-0` against the scrolling chips.
+            "inline-flex shrink-0 items-center justify-center gap-1.5 whitespace-nowrap rounded-full border border-border bg-card text-sm text-foreground transition-colors hover:border-accent/40 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring motion-reduce:transition-none",
+            chipSize === "lg" ? "h-11" : "h-9",
+            // With a glyph: a square below `lg`, the glyph and the label from it.
+            moreIcon ? (chipSize === "lg" ? "w-11 lg:w-auto lg:px-4" : "w-9 lg:w-auto lg:px-4") : "px-4"
           )}
-          <button
-            type="button"
-            onClick={onMore}
-            className={cn(
-              "shrink-0 rounded-md pl-2 text-[12.5px] font-bold text-accent transition-colors hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring motion-reduce:transition-none",
-              moreIcon && "hidden lg:inline"
-            )}
-          >
-            {moreLabel}
-          </button>
-        </>
+        >
+          {moreIcon}
+          <span className={cn(moreIcon && "hidden lg:inline")}>{moreLabel}</span>
+        </button>
       )}
     </div>
   );