@akinon/pz-theme 2.0.131-rc.0 → 2.0.131

package/CHANGELOG.md

@@ -1,40 +1,12 @@
 # @akinon/pz-theme
 
-## 2.0.131-rc.0
-
-### Patch Changes
-
-- Updated dependencies [86187b1c2]
-- Updated dependencies [0cf9ea239]
-- Updated dependencies [324f97d55]
-- Updated dependencies [51ea06888]
-- Updated dependencies
-- Updated dependencies [2fea41430]
-- Updated dependencies [b55acb768]
-- Updated dependencies [760258c1c]
-- Updated dependencies [143be2b9d]
-- Updated dependencies [7889b08fe]
-- Updated dependencies [9f8cd3bc5]
-- Updated dependencies [bfafa3f49]
-- Updated dependencies [57d7eb305]
-- Updated dependencies [d99a6a7d5]
-- Updated dependencies [9db81a714]
-- Updated dependencies [591e345e1]
-- Updated dependencies [4de5303c5]
-- Updated dependencies [95b139dc1]
-- Updated dependencies [1d00f2d06]
-- Updated dependencies [4ac7b2a1e]
-- Updated dependencies [e9598c71d]
-- Updated dependencies [4998a9631]
-- Updated dependencies [804d2bd6c]
-- Updated dependencies [3909d3224]
-- Updated dependencies [6a3d8a631]
-- Updated dependencies [e18836b20]
-- Updated dependencies [b1111d7b1]
-- Updated dependencies [1595d458]
-- Updated dependencies [dca12811]
-  - @akinon/next@2.0.131-rc.0
-  - @akinon/theme-contract@2.0.131-rc.0
+## 2.0.131
+
+### Patch Changes
+
+- cea66db: ZERO-5160: Report slide changes and slider controls as theme events
+  - @akinon/next@2.0.131
+  - @akinon/theme-contract@2.0.131
 
 ## 2.0.130
 

package/package.json

@@ -1,19 +1,19 @@
 {
   "name": "@akinon/pz-theme",
   "description": "Theme package for Project Zero Next — ThemePlaceholder system and theme editor infrastructure",
-  "version": "2.0.131-rc.0",
+  "version": "2.0.131",
   "license": "MIT",
   "main": "src/index.ts",
   "scripts": {
     "test": "jest"
   },
   "peerDependencies": {
-    "@akinon/next": "2.0.131-rc.0",
+    "@akinon/next": "2.0.131",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/theme-contract": "2.0.131-rc.0",
+    "@akinon/theme-contract": "2.0.131",
     "clsx": "2.1.1",
     "lottie-web": "^5.13.0",
     "react-multi-carousel": "2.8.4",
@@ -21,7 +21,7 @@
     "zod": "4.4.1"
   },
   "devDependencies": {
-    "@akinon/next": "2.0.131-rc.0",
+    "@akinon/next": "2.0.131",
     "@testing-library/jest-dom": "5.16.4",
     "@testing-library/react": "16.3.2",
     "@testing-library/user-event": "14.1.1",

package/src/blocks/__tests__/slider-block-signals.test.tsx

@@ -0,0 +1,429 @@
+import React from 'react';
+import { fireEvent, render } from '@testing-library/react';
+
+// Same passthrough stand-in the sibling suite uses: the library is ESM and
+// DOM-heavy, and every assertion here is either about the prop object it is
+// handed or about markup the block draws itself.
+const mockCarouselProps: Record<string, any>[] = [];
+jest.mock('react-multi-carousel', () => ({
+  __esModule: true,
+  default: (carouselProps: any) => {
+    mockCarouselProps.push(carouselProps);
+    return <div data-testid="carousel">{carouselProps.children}</div>;
+  }
+}));
+
+let themeBlockRenders = 0;
+jest.mock('../../theme-block', () => ({
+  __esModule: true,
+  default: ({ block }: { block: { id: string } }) => {
+    themeBlockRenders += 1;
+    return <div data-testid="tb" data-id={block.id} />;
+  }
+}));
+
+import SliderBlock, { authoredSlideIndex } from '../slider-block';
+import {
+  __resetThemeSignalsForTests,
+  subscribeToThemeSignals,
+  type ThemeSignalDetail
+} from '../../utils/theme-signal';
+
+declare global {
+  interface Window {
+    __themeEditorDesigner?: boolean;
+  }
+}
+
+const child = (id: string, over: Record<string, unknown> = {}): any => ({
+  id,
+  type: 'text',
+  label: id,
+  value: '',
+  properties: {},
+  styles: {},
+  order: 0,
+  hidden: false,
+  ...over
+});
+
+const slides = (count: number) =>
+  Array.from({ length: count }, (_unused, index) =>
+    child(`slide-${index}`, { order: index })
+  );
+
+/**
+ * The arrows only reach the DOM when they are placed OUTSIDE the track (an
+ * authored top/bottom); inside the track they are handed to the carousel as
+ * props, which the stand-in above drops.
+ */
+const arrowIcon = (label: string) =>
+  child(label, {
+    type: 'icon',
+    label,
+    value: { url: '/a.svg' },
+    styles: { top: '0px' }
+  });
+
+const withOutsideArrows = () => ({
+  properties: {
+    'show-arrows': { desktop: true, mobile: true },
+    'items-per-slide': { desktop: 1, mobile: 1 }
+  },
+  blocks: [
+    arrowIcon('Left Arrow Icon'),
+    ...slides(3),
+    arrowIcon('Right Arrow Icon')
+  ]
+});
+
+const props = (over: Record<string, unknown> = {}, blockOver = {}) =>
+  ({
+    block: {
+      id: 'slider',
+      type: 'slider',
+      label: 'slider',
+      value: '',
+      properties: {},
+      styles: {},
+      order: 0,
+      hidden: false,
+      blocks: slides(6),
+      ...blockOver
+    },
+    placeholderId: 'home-body',
+    sectionId: 'section-h3k9q',
+    isDesigner: false,
+    ...over
+  } as any);
+
+/** Autoplay is what turns the carousel infinite, so it is what clones it. */
+const autoplaying = (blockOver = {}) =>
+  props(
+    {},
+    {
+      properties: { autoplay: { desktop: true, mobile: true } },
+      ...blockOver
+    }
+  );
+
+const lastCarouselProps = () => mockCarouselProps[mockCarouselProps.length - 1];
+
+describe('slider events (ZERO-5160)', () => {
+  let received: ThemeSignalDetail[];
+  let detach: () => void;
+
+  beforeEach(() => {
+    mockCarouselProps.length = 0;
+    themeBlockRenders = 0;
+    received = [];
+    detach = subscribeToThemeSignals((detail) => received.push(detail));
+    __resetThemeSignalsForTests();
+    delete window.__themeEditorDesigner;
+  });
+
+  afterEach(() => {
+    detach();
+    delete window.__themeEditorDesigner;
+  });
+
+  describe('the change callback is attached to every slider', () => {
+    it('reports on an autoplaying slider, which can never have a lead-in', () => {
+      // useLeadIn requires !useInfinite, and autoplay makes it infinite — so
+      // hanging the report off the lead-in spread would have left exactly the
+      // loudest sliders silent.
+      render(<SliderBlock {...autoplaying()} />);
+
+      expect(typeof lastCarouselProps().beforeChange).toBe('function');
+
+      lastCarouselProps().beforeChange(3, { slidesToShow: 1 });
+
+      expect(received).toHaveLength(1);
+      expect(received[0].name).toBe('slide.changed');
+    });
+
+    it('leaves the lead-in transform off a slider that did not opt in', () => {
+      render(<SliderBlock {...props()} />);
+
+      expect('additionalTransfrom' in lastCarouselProps()).toBe(false);
+    });
+
+    it('does not re-render the slides on a change it was not asked to track', () => {
+      // The lead-in's state write stays behind its own condition: without
+      // this, every slider re-renders itself and every slide under it on each
+      // autoplay tick, to move a transform nothing reads.
+      render(<SliderBlock {...autoplaying()} />);
+      const before = themeBlockRenders;
+
+      lastCarouselProps().beforeChange(3, { slidesToShow: 1 });
+
+      expect(themeBlockRenders).toBe(before);
+    });
+  });
+
+  describe('the index is the authored one, not the clone one', () => {
+    it('maps a cloned index back to the slide the merchant sees', () => {
+      render(<SliderBlock {...autoplaying()} />);
+
+      // Six slides, one in view: the library starts at 2, so its 3 is the
+      // merchant's second slide and its 7 is the last one.
+      lastCarouselProps().beforeChange(3, { slidesToShow: 1 });
+      lastCarouselProps().beforeChange(7, { slidesToShow: 1 });
+
+      expect(received.map((detail) => detail.index)).toEqual([1, 5]);
+      expect(received.every((detail) => detail.total === 6)).toBe(true);
+    });
+
+    it('maps a trailing clone back to the slide it is a copy of', () => {
+      render(<SliderBlock {...autoplaying()} />);
+
+      // Past the end the track shows the leading slides again as clones.
+      lastCarouselProps().beforeChange(8, { slidesToShow: 1 });
+      lastCarouselProps().beforeChange(9, { slidesToShow: 1 });
+
+      expect(received.map((detail) => detail.index)).toEqual([0, 1]);
+    });
+
+    it('reports a finite slider index unchanged', () => {
+      render(<SliderBlock {...props()} />);
+
+      lastCarouselProps().beforeChange(2, { slidesToShow: 2 });
+
+      expect(received[0]).toMatchObject({ index: 2, total: 6 });
+    });
+
+    it('handles the short-list clone shape', () => {
+      // Three slides with two in view are cloned by concatenation, so the
+      // table is a modulo rather than the windowed form.
+      expect(authoredSlideIndex(4, 3, 2)).toBe(1);
+      expect(authoredSlideIndex(0, 3, 2)).toBe(0);
+    });
+
+    it('reports nothing before the library has measured itself', () => {
+      // slidesToShow is 0 until mount; the clone table branches on it, so an
+      // index resolved against it would be a guess.
+      render(<SliderBlock {...autoplaying()} />);
+
+      lastCarouselProps().beforeChange(3, { slidesToShow: 0 });
+
+      expect(received).toEqual([]);
+    });
+  });
+
+  describe('what rides on the change', () => {
+    it('carries the measured slides in view, not the block breakpoint guess', () => {
+      render(
+        <SliderBlock
+          {...props(
+            { currentBreakpoint: 'mobile' },
+            { properties: { 'items-per-slide': { desktop: 4, mobile: 1 } } }
+          )}
+        />
+      );
+
+      lastCarouselProps().beforeChange(2, { slidesToShow: 3 });
+
+      expect(received[0].slidesInView).toBe(3);
+    });
+
+    it('omits slides in view rather than reporting zero', () => {
+      render(<SliderBlock {...props()} />);
+
+      lastCarouselProps().beforeChange(1, { slidesToShow: 0 });
+
+      expect(received[0]).not.toHaveProperty('slidesInView');
+    });
+
+    it('counts the slides a shopper can see, not the hidden ones', () => {
+      render(
+        <SliderBlock
+          {...props(
+            {},
+            {
+              blocks: [
+                child('a', { order: 0 }),
+                child('b', { order: 1, hidden: true }),
+                child('c', { order: 2 }),
+                child('d', { order: 3 })
+              ]
+            }
+          )}
+        />
+      );
+
+      lastCarouselProps().beforeChange(2, { slidesToShow: 1 });
+
+      expect(received[0]).toMatchObject({ index: 2, total: 3 });
+    });
+
+    it('carries the identity of the slider that reported', () => {
+      render(<SliderBlock {...props()} />);
+
+      lastCarouselProps().beforeChange(1, { slidesToShow: 1 });
+
+      expect(received[0]).toMatchObject({
+        placeholderId: 'home-body',
+        sectionId: 'section-h3k9q',
+        blockId: 'slider',
+        blockType: 'slider'
+      });
+    });
+
+    it('says nothing about the cause when it cannot know it', () => {
+      // Autoplay, the keyboard and an undragged flick all arrive the same way.
+      render(<SliderBlock {...props()} />);
+
+      lastCarouselProps().beforeChange(1, { slidesToShow: 1 });
+
+      expect(received[0]).not.toHaveProperty('via');
+    });
+  });
+
+  describe('controls', () => {
+    it('reports an arrow placed outside the track once per click', () => {
+      const { container } = render(
+        <SliderBlock {...props({}, withOutsideArrows())} />
+      );
+
+      fireEvent.click(
+        container.querySelector('button[aria-label="Previous"]') as HTMLElement
+      );
+
+      const controls = received.filter(
+        (detail) => detail.name === 'slide.control'
+      );
+      expect(controls).toHaveLength(1);
+      expect(controls[0]).toMatchObject({
+        control: 'arrow',
+        direction: 'previous'
+      });
+    });
+
+    it('reports an arrow inside the track once, not twice', () => {
+      // Inside the track the click runs the library's own handler AND the
+      // block's; only the library's move survives its throttle, and only one
+      // report may leave.
+      render(<SliderBlock {...props()} />);
+
+      const arrow = lastCarouselProps().customRightArrow;
+      const { container } = render(
+        React.cloneElement(arrow, { onClick: jest.fn() })
+      );
+
+      fireEvent.click(
+        container.querySelector('button[aria-label="Next"]') as HTMLElement
+      );
+
+      const controls = received.filter(
+        (detail) => detail.name === 'slide.control'
+      );
+      expect(controls).toHaveLength(1);
+      expect(controls[0]).toMatchObject({ direction: 'next' });
+    });
+
+    it('attributes the change that follows a dot to the dot', () => {
+      render(<SliderBlock {...props()} />);
+
+      const dot = lastCarouselProps().customDot;
+      dot.props.onSelect(2);
+      lastCarouselProps().beforeChange(2, { slidesToShow: 1 });
+
+      expect(received.map((detail) => detail.name)).toEqual([
+        'slide.control',
+        'slide.changed'
+      ]);
+      expect(received[0]).toMatchObject({ control: 'dot', dotIndex: 2 });
+      expect(received[1]).toMatchObject({ via: 'dot', index: 2 });
+    });
+
+    it('clears the attribution so the next change does not inherit it', () => {
+      render(<SliderBlock {...props()} />);
+
+      lastCarouselProps().customDot.props.onSelect(1);
+      lastCarouselProps().beforeChange(1, { slidesToShow: 1 });
+      lastCarouselProps().beforeChange(2, { slidesToShow: 1 });
+
+      const changes = received.filter(
+        (detail) => detail.name === 'slide.changed'
+      );
+      expect(changes[0].via).toBe('dot');
+      expect(changes[1]).not.toHaveProperty('via');
+    });
+  });
+
+  describe('volume', () => {
+    it('caps an autoplaying slider well below the route budget', () => {
+      render(<SliderBlock {...autoplaying()} />);
+
+      for (let tick = 0; tick < 30; tick += 1) {
+        lastCarouselProps().beforeChange(3 + (tick % 6), { slidesToShow: 1 });
+      }
+
+      expect(received).toHaveLength(5);
+    });
+
+    it('still reports a shopper control after the timer has used its budget', () => {
+      // The two go on separate tally keys, so a carousel spinning below the
+      // fold cannot silence the arrow the shopper actually pressed.
+      render(<SliderBlock {...autoplaying()} />);
+
+      for (let tick = 0; tick < 30; tick += 1) {
+        lastCarouselProps().beforeChange(3, { slidesToShow: 1 });
+      }
+      received.length = 0;
+
+      lastCarouselProps().customDot.props.onSelect(1);
+      lastCarouselProps().beforeChange(4, { slidesToShow: 1 });
+
+      expect(received.map((detail) => detail.name)).toEqual([
+        'slide.control',
+        'slide.changed'
+      ]);
+    });
+
+    it('gives each slider on the page its own budget', () => {
+      const { unmount } = render(<SliderBlock {...autoplaying()} />);
+      for (let tick = 0; tick < 30; tick += 1) {
+        lastCarouselProps().beforeChange(3, { slidesToShow: 1 });
+      }
+      unmount();
+      received.length = 0;
+
+      render(
+        <SliderBlock {...autoplaying({ id: 'slider-two', type: 'slider' })} />
+      );
+      lastCarouselProps().beforeChange(3, { slidesToShow: 1 });
+
+      expect(received).toHaveLength(1);
+    });
+  });
+
+  describe('the editor', () => {
+    it('reports nothing while the editor is attached, browse mode included', () => {
+      // Browse mode hands the block isDesigner={false} while the editor is
+      // still attached; the emitter reads the raw flag, so the call sites
+      // below carry no guard of their own.
+      window.__themeEditorDesigner = true;
+
+      const { container } = render(
+        <SliderBlock {...props({}, withOutsideArrows())} />
+      );
+
+      fireEvent.click(
+        container.querySelector('button[aria-label="Previous"]') as HTMLElement
+      );
+      lastCarouselProps().beforeChange(2, { slidesToShow: 1 });
+      lastCarouselProps().customDot.props.onSelect(1);
+
+      expect(received).toEqual([]);
+    });
+
+    it('hands the canvas the same change callback the storefront gets', () => {
+      // The canvas must exercise the carousel the shopper gets; gating the
+      // prop itself would make the two configurations diverge.
+      render(<SliderBlock {...props({ isDesigner: true })} />);
+
+      expect(typeof lastCarouselProps().beforeChange).toBe('function');
+    });
+  });
+});

package/src/blocks/slider-block.tsx

@@ -15,6 +15,7 @@ import {
 } from '../utils';
 import { DESKTOP_MIN_WIDTH, isNarrowBreakpoint } from '../utils/breakpoints';
 import { useCarouselSsr } from '../utils/carousel-ssr';
+import { useThemeSignal } from '../hooks/use-theme-signal';
 import {
   CAROUSEL_MINIMUM_TOUCH_DRAG,
   carouselDragStyle,
@@ -67,7 +68,61 @@ const clampNumber = (value: number, min: number, max: number) =>
  * render would unmount and remount all of them on each slide change — taking
  * the focus of a keyboard user who had just tabbed to one.
  */
-const CustomDot = ({ index, active, onClick }: any) => (
+/**
+ * How many unattributed slide changes one slider may report per page view.
+ *
+ * An autoplaying carousel changes slide every few seconds for as long as the
+ * tab is open, and nothing in the callback says whether a change was the timer
+ * or a shopper. Those go on their own tally key with this much lower ceiling,
+ * so a carousel spinning below the fold can neither drown the arrow clicks of
+ * the same slider nor eat the whole route's budget and silence every other
+ * moment on the page.
+ */
+const UNATTRIBUTED_SLIDE_CHANGE_CEILING = 5;
+
+/**
+ * The authored slide ordinal behind the index the library reports.
+ *
+ * In infinite mode the carousel prepends and appends clones, so `beforeChange`
+ * counts in clone space: a six-slide hero starts at 2 and climbs to 9 before
+ * the library silently teleports back. Reporting that raw would give
+ * `index: 9, total: 6` and would never mention slides 0 and 1 at all.
+ *
+ * This is the same mapping the library's own dots use to resolve which one is
+ * active (`getOriginalIndexLookupTableByClones`), written out rather than
+ * imported: the helper is not on the package's export surface, only its
+ * internal deep path, and four lines of arithmetic is a smaller liability than
+ * an import that a minor version can move.
+ *
+ * `slidesToShow` must be the MEASURED value off the callback's state — the
+ * table branches on it, so the block's own breakpoint guess would silently
+ * select a different table. Before mount the library reports 0, which cannot
+ * resolve anything, so the change is not reported at all rather than guessed.
+ */
+export const authoredSlideIndex = (
+  reportedIndex: number,
+  total: number,
+  slidesToShow: number
+): number | null => {
+  if (!Number.isFinite(reportedIndex) || total <= 0) return null;
+  if (slidesToShow <= 0) return null;
+
+  const span = 2 * slidesToShow;
+  let authored: number;
+
+  if (total > span) {
+    if (reportedIndex < span) authored = total - span + reportedIndex;
+    else if (reportedIndex < total + span) authored = reportedIndex - span;
+    else authored = reportedIndex - (total + span);
+  } else {
+    // Short lists are cloned by concatenation, so the table is a modulo.
+    authored = ((reportedIndex % total) + total) % total;
+  }
+
+  return authored >= 0 && authored < total ? authored : null;
+};
+
+const CustomDot = ({ index, active, onClick, onSelect }: any) => (
   <li
     className={clsx(
       'react-multi-carousel-dot',
@@ -89,7 +144,13 @@ const CustomDot = ({ index, active, onClick }: any) => (
        * swallowing it here would have made the Dot panel this change exists to
        * offer unreachable by clicking the dot.
        */
-      onClick={() => onClick?.()}
+      onClick={() => {
+        // Reported before the library moves: the change callback fires
+        // synchronously inside `onClick`, and it reads the note to say what
+        // caused the change.
+        onSelect?.(index);
+        onClick?.();
+      }}
     />
   </li>
 );
@@ -109,6 +170,12 @@ const SliderBlock: React.FC<BlockRendererProps> = ({
   onRename
 }) => {
   const themeSettings = useThemeSettingsContext();
+  const signal = useThemeSignal({
+    placeholderId,
+    sectionId,
+    blockId: block.id,
+    blockType: block.type
+  });
   const carouselRef = React.useRef<Carousel>(null);
   const containerRef = React.useRef<HTMLDivElement>(null);
   /**
@@ -293,7 +360,11 @@ const SliderBlock: React.FC<BlockRendererProps> = ({
   // Arrows that only appear while the slider is hovered. Off by default, so a
   // slider that never authored it renders exactly as before.
   const arrowsOnHover = Boolean(
-    getResponsiveValue(getConfigEntry('arrows-on-hover'), currentBreakpoint, false)
+    getResponsiveValue(
+      getConfigEntry('arrows-on-hover'),
+      currentBreakpoint,
+      false
+    )
   );
   const useAutoPlay = getResponsiveValue(
     getConfigEntry('autoplay'),
@@ -928,10 +999,80 @@ const SliderBlock: React.FC<BlockRendererProps> = ({
     rightArrowButtonStyle.top !== undefined ||
     rightArrowButtonStyle.bottom !== undefined;
 
+  /**
+   * What the shopper did, read and cleared by the change report below.
+   *
+   * The library's change callback carries no cause: an arrow, a dot, a drag,
+   * the autoplay timer and the keyboard all reach it through the same two
+   * methods. Only the two the block owns can be attributed honestly, so those
+   * two leave a note and everything else reports no cause at all rather than
+   * a guessed one.
+   */
+  const lastControlRef = React.useRef<'arrow' | 'dot' | null>(null);
+
+  const noteControl = (control: 'arrow' | 'dot') => {
+    lastControlRef.current = control;
+  };
+
+  /**
+   * One slide change, in authored terms.
+   *
+   * `index` and `total` count the slides the SHOPPER can see: the arrow icons
+   * are not slides, and a hidden slide is dropped on the storefront while the
+   * canvas keeps it. A slide switched off by its publish window is still
+   * counted here — it occupies a track position and a dot today, blank; that
+   * is existing behaviour and its own ticket.
+   */
+  const reportSlideChange = (
+    reportedIndex: number,
+    state?: { slidesToShow?: number }
+  ) => {
+    const measuredInView = Number(state?.slidesToShow) || 0;
+    const index = useInfinite
+      ? authoredSlideIndex(reportedIndex, visibleCount, measuredInView)
+      : reportedIndex;
+
+    if (index === null || index === undefined) return;
+
+    const via = lastControlRef.current;
+    lastControlRef.current = null;
+
+    signal(
+      'slide.changed',
+      {
+        index,
+        total: visibleCount,
+        // The library's measured value, not the block's breakpoint guess:
+        // "slide 2 of 6" means a different thing with one in view than with
+        // four. Absent before mount rather than reported as zero.
+        ...(measuredInView > 0 ? { slidesInView: measuredInView } : null),
+        ...(via ? { via } : null)
+      },
+      via
+        ? { key: block.id }
+        : {
+            key: `${block.id}:unattributed`,
+            ceiling: UNATTRIBUTED_SLIDE_CHANGE_CEILING
+          }
+    );
+  };
+
   const handleLeftArrowClick = (e: React.MouseEvent) => {
     e.preventDefault();
     e.stopPropagation();
 
+    // Both arrow paths land here — the one the library renders inside the
+    // track and the one the block draws when the arrows are placed outside it
+    // — so the control is reported exactly once per click either way.
+    noteControl('arrow');
+    signal(
+      'slide.control',
+      { control: 'arrow', direction: 'previous' },
+      {
+        key: block.id
+      }
+    );
+
     carouselRef.current?.previous?.(1);
   };
 
@@ -939,9 +1080,33 @@ const SliderBlock: React.FC<BlockRendererProps> = ({
     e.preventDefault();
     e.stopPropagation();
 
+    noteControl('arrow');
+    signal(
+      'slide.control',
+      { control: 'arrow', direction: 'next' },
+      {
+        key: block.id
+      }
+    );
+
     carouselRef.current?.next?.(1);
   };
 
+  /**
+   * A dot carries its own ordinal, which is NOT the slide ordinal whenever
+   * more than one slide moves at a time — the library derives the target from
+   * it. So the dot reports which dot was pressed and lets the change report
+   * that follows carry the slide it landed on.
+   */
+  const handleDotSelect = (dotIndex: number) => {
+    noteControl('dot');
+    signal(
+      'slide.control',
+      { control: 'dot', dotIndex: Number(dotIndex) || 0 },
+      { key: block.id }
+    );
+  };
+
   /**
    * ONE ARROW, DRAWN IN ONE PLACE.
    *
@@ -1033,10 +1198,19 @@ const SliderBlock: React.FC<BlockRendererProps> = ({
     );
   };
 
+  /*
+   * The note is left BEFORE the library's own handler runs, because that call
+   * moves the carousel synchronously and the change report reads the note on
+   * the way past. The order of the two calls is otherwise untouched: the
+   * library's `previous()`/`next()` moves by the authored step, and the
+   * block's own call behind it is swallowed by the library's throttle —
+   * swapping them would change how far one click travels.
+   */
   const CustomLeftArrow = ({ onClick }: any) =>
     renderArrowButton('left', (e) => {
       e.stopPropagation();
       if (!isDesigner) {
+        noteControl('arrow');
         onClick?.();
       }
       handleLeftArrowClick(e);
@@ -1046,6 +1220,7 @@ const SliderBlock: React.FC<BlockRendererProps> = ({
     renderArrowButton('right', (e) => {
       e.stopPropagation();
       if (!isDesigner) {
+        noteControl('arrow');
         onClick?.();
       }
       handleRightArrowClick(e);
@@ -1071,12 +1246,8 @@ const SliderBlock: React.FC<BlockRendererProps> = ({
       {...carouselSsr.gateProps}
       // Focus rides along with the pointer so the arrows are reachable by
       // keyboard; both events bubble in React, so tabbing INTO an arrow counts.
-      onMouseEnter={
-        arrowsOnHover ? () => setPointerInside(true) : undefined
-      }
-      onMouseLeave={
-        arrowsOnHover ? () => setPointerInside(false) : undefined
-      }
+      onMouseEnter={arrowsOnHover ? () => setPointerInside(true) : undefined}
+      onMouseLeave={arrowsOnHover ? () => setPointerInside(false) : undefined}
       onFocus={arrowsOnHover ? () => setPointerInside(true) : undefined}
       onBlur={arrowsOnHover ? () => setPointerInside(false) : undefined}
     >
@@ -1125,7 +1296,7 @@ const SliderBlock: React.FC<BlockRendererProps> = ({
                 visibleCount > itemsShown
           }
           showDots={Boolean(showDots)}
-          customDot={<CustomDot />}
+          customDot={<CustomDot onSelect={handleDotSelect} />}
           renderDotsOutside={Boolean(showDots)}
           infinite={Boolean(useInfinite)}
           rewind={Boolean(useInfinite)}
@@ -1134,16 +1305,30 @@ const SliderBlock: React.FC<BlockRendererProps> = ({
           autoPlaySpeed={autoPlaySpeed}
           containerClass={`slider-carousel ${carouselSsr.scopeClass}`}
           dotListClass="slider-dots"
+          /*
+           * Reported on every slider, not only the ones with a lead-in: an
+           * autoplaying hero is infinite, an infinite slider can never have a
+           * lead-in, and those are precisely the sliders whose changes are
+           * worth counting.
+           *
+           * The lead-in's own state write stays behind its condition. Calling
+           * it unconditionally would add a re-render of this block and every
+           * slide under it on each change — three seconds apart, forever,
+           * under autoplay — to move a transform nothing else reads.
+           */
+          beforeChange={(
+            nextSlide: number,
+            state: { slidesToShow?: number }
+          ) => {
+            if (useLeadIn) setSlidePosition(nextSlide);
+
+            reportSlideChange(nextSlide, state);
+          }}
           /*
            * Spread conditionally so a slider that has not opted in is handed
-           * the identical prop object it was handed before.
+           * the identical transform prop it was handed before.
            */
-          {...(useLeadIn
-            ? {
-                additionalTransfrom: edgeOffset,
-                beforeChange: (nextSlide: number) => setSlidePosition(nextSlide)
-              }
-            : {})}
+          {...(useLeadIn ? { additionalTransfrom: edgeOffset } : {})}
           customLeftArrow={
             !isDesigner &&
             showArrows &&