@akinon/pz-theme 2.0.94-rc.0 → 2.0.95-beta.0

package/CHANGELOG.md

@@ -1,38 +1,21 @@
 # @akinon/pz-theme
 
-## 2.0.94-rc.0
-
-### Patch Changes
-
-- Updated dependencies [86187b1c]
-- 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 [b1111d7b]
-  - @akinon/next@2.0.94-rc.0
-  - @akinon/theme-contract@2.0.94-rc.0
+## 2.0.95-beta.0
+
+### Patch Changes
+
+- Updated dependencies [cbbbfd757]
+  - @akinon/next@2.0.95-beta.0
+  - @akinon/theme-contract@2.0.95-beta.0
+
+## 2.0.94
+
+### Patch Changes
+
+- 6f3189f3: Fix a hydration mismatch on `data-scroll-state`: mounting one chrome slot no longer stamps a sibling slot that has not hydrated yet under Suspense
+- 57e09d65: ZERO-4988: Add mobile video/poster override and a custom play/pause button to the video block, and fix autoplay/loop/muted/controls/playsInline being read as raw per-breakpoint objects instead of resolved values (caused a hydration mismatch on `muted`)
+  - @akinon/next@2.0.94
+  - @akinon/theme-contract@2.0.94
 
 ## 2.0.93
 

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.94-rc.0",
+  "version": "2.0.95-beta.0",
   "license": "MIT",
   "main": "src/index.ts",
   "scripts": {
     "test": "jest"
   },
   "peerDependencies": {
-    "@akinon/next": "2.0.94-rc.0",
+    "@akinon/next": "2.0.95-beta.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/theme-contract": "2.0.94-rc.0",
+    "@akinon/theme-contract": "2.0.95-beta.0",
     "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.94-rc.0",
+    "@akinon/next": "2.0.95-beta.0",
     "@testing-library/jest-dom": "5.16.4",
     "@testing-library/react": "16.3.2",
     "@testing-library/user-event": "14.1.1",

package/src/blocks/__tests__/video-block.test.tsx

@@ -441,12 +441,257 @@ describe('VideoBlock', () => {
     });
   });
 
+  describe('filling a full-bleed hero (block Height + Object Fit)', () => {
+    // Mirrors image-block.tsx: the `<video>` reads the same `height` /
+    // `object-fit` styles as the block wrapper, so setting Height: 100% +
+    // Position: Absolute + inset 0 on the block makes the player actually
+    // fill it — previously the player was stuck at `height: auto`, sized by
+    // its own aspect ratio rather than the box the author placed it in.
+    it('applies the authored height to the player, not just the wrapper', () => {
+      const { container } = renderBlock(
+        'https://cdn.example.com/clip.mp4',
+        undefined,
+        { height: { desktop: '100%' } }
+      );
+      const video = container.querySelector('video') as HTMLVideoElement;
+      expect(video.style.height).toBe('100%');
+    });
+
+    it('defaults Object Fit to cover even without an authored aspect ratio', () => {
+      const { container } = renderBlock('https://cdn.example.com/clip.mp4');
+      const video = container.querySelector('video') as HTMLVideoElement;
+      expect(video.style.objectFit).toBe('cover');
+    });
+
+    it('honors an explicit Object Fit override', () => {
+      const { container } = renderBlock(
+        'https://cdn.example.com/clip.mp4',
+        undefined,
+        { 'object-fit': { desktop: 'contain' } }
+      );
+      const video = container.querySelector('video') as HTMLVideoElement;
+      expect(video.style.objectFit).toBe('contain');
+    });
+  });
+
   describe('non-string value (BUG-4 fix)', () => {
     it('renders the invalid placeholder instead of crashing on a non-string value', () => {
       renderBlock(123 as any);
       expect(screen.getByText('Invalid video URL')).toBeInTheDocument();
     });
   });
+
+  describe('mobile video / poster override', () => {
+    const renderAt = (
+      value: any,
+      properties: any,
+      currentBreakpoint: 'desktop' | 'tablet' | 'mobile'
+    ) =>
+      render(
+        <VideoBlock
+          block={{ value, properties } as any}
+          placeholderId="p1"
+          sectionId="s1"
+          isDesigner={false}
+          currentBreakpoint={currentBreakpoint}
+        />
+      );
+
+    it('plays the desktop file on mobile when useDifferentMobileVideo is off', () => {
+      const { container } = renderAt(
+        'https://cdn.example.com/desktop.mp4',
+        { mobileUrl: 'https://cdn.example.com/mobile.mp4' },
+        'mobile'
+      );
+      expect(
+        (container.querySelector('video') as HTMLVideoElement).src
+      ).toBe('https://cdn.example.com/desktop.mp4');
+    });
+
+    it('plays the mobile file on mobile when useDifferentMobileVideo is on', () => {
+      const { container } = renderAt(
+        'https://cdn.example.com/desktop.mp4',
+        {
+          useDifferentMobileVideo: true,
+          mobileUrl: 'https://cdn.example.com/mobile.mp4'
+        },
+        'mobile'
+      );
+      expect(
+        (container.querySelector('video') as HTMLVideoElement).src
+      ).toBe('https://cdn.example.com/mobile.mp4');
+    });
+
+    it('still plays the desktop file on desktop even when a mobile override is set', () => {
+      const { container } = renderAt(
+        'https://cdn.example.com/desktop.mp4',
+        {
+          useDifferentMobileVideo: true,
+          mobileUrl: 'https://cdn.example.com/mobile.mp4'
+        },
+        'desktop'
+      );
+      expect(
+        (container.querySelector('video') as HTMLVideoElement).src
+      ).toBe('https://cdn.example.com/desktop.mp4');
+    });
+
+    it('uses the mobile poster on mobile when the override is on', () => {
+      const { container } = renderAt(
+        'https://cdn.example.com/desktop.mp4',
+        {
+          poster: 'https://cdn.example.com/desktop.jpg',
+          useDifferentMobileVideo: true,
+          mobilePoster: 'https://cdn.example.com/mobile.jpg'
+        },
+        'mobile'
+      );
+      expect(
+        (container.querySelector('video') as HTMLVideoElement).poster
+      ).toBe('https://cdn.example.com/mobile.jpg');
+    });
+
+    it('falls back to the desktop poster on mobile without an override', () => {
+      const { container } = renderAt(
+        'https://cdn.example.com/desktop.mp4',
+        { poster: 'https://cdn.example.com/desktop.jpg' },
+        'mobile'
+      );
+      expect(
+        (container.querySelector('video') as HTMLVideoElement).poster
+      ).toBe('https://cdn.example.com/desktop.jpg');
+    });
+  });
+
+  describe('custom play/pause button', () => {
+    beforeAll(() => {
+      // jsdom does not implement media playback.
+      window.HTMLMediaElement.prototype.play = jest.fn();
+      window.HTMLMediaElement.prototype.pause = jest.fn();
+    });
+
+    it('is not rendered when native controls are on, even if requested', () => {
+      const { container } = renderBlock('https://cdn.example.com/clip.mp4', {
+        controls: true,
+        customPlayPause: true
+      });
+      expect(container.querySelector('button')).not.toBeInTheDocument();
+    });
+
+    it('is not rendered when controls are off but the toggle is off', () => {
+      const { container } = renderBlock('https://cdn.example.com/clip.mp4', {
+        controls: false,
+        customPlayPause: false
+      });
+      expect(container.querySelector('button')).not.toBeInTheDocument();
+    });
+
+    it('is rendered when controls are off and the toggle is on', () => {
+      const { container } = renderBlock('https://cdn.example.com/clip.mp4', {
+        controls: false,
+        customPlayPause: true
+      });
+      expect(container.querySelector('button')).toBeInTheDocument();
+    });
+
+    it('toggles the underlying video on click', () => {
+      const { container } = renderBlock('https://cdn.example.com/clip.mp4', {
+        controls: false,
+        customPlayPause: true
+      });
+      const button = container.querySelector('button') as HTMLButtonElement;
+      const video = container.querySelector('video') as HTMLVideoElement;
+
+      button.click();
+      expect(video.play).toHaveBeenCalledTimes(1);
+
+      Object.defineProperty(video, 'paused', { value: false, configurable: true });
+      button.click();
+      expect(video.pause).toHaveBeenCalledTimes(1);
+    });
+
+    it('stacks above a sibling content overlay (z-index 2) so its clicks are not swallowed', () => {
+      // A title/CTA content block placed over the video is a full-size
+      // `position: absolute; z-index: 1` box (see pz-theme's group content
+      // pattern) — its transparent area still captures pointer events. Without
+      // an explicit, higher z-index the button was visually and functionally
+      // underneath it, unclickable everywhere it overlapped.
+      const { container } = renderBlock('https://cdn.example.com/clip.mp4', {
+        controls: false,
+        customPlayPause: true
+      });
+      const button = container.querySelector('button') as HTMLButtonElement;
+      expect(Number(button.style.zIndex)).toBeGreaterThan(1);
+    });
+
+    it('matches the design: a 20x20 button, not an oversized icon', () => {
+      const { container } = renderBlock('https://cdn.example.com/clip.mp4', {
+        controls: false,
+        customPlayPause: true
+      });
+      const button = container.querySelector('button') as HTMLButtonElement;
+      expect(button.style.width).toBe('20px');
+      expect(button.style.height).toBe('20px');
+    });
+
+    it('draws the pause icon as two 1x8 bars', () => {
+      const { container } = renderBlock('https://cdn.example.com/clip.mp4', {
+        controls: false,
+        customPlayPause: true,
+        autoplay: true // starts in the "playing" state, so the Pause icon renders
+      });
+      const rects = container.querySelectorAll('button svg rect');
+      expect(rects).toHaveLength(2);
+      rects.forEach(rect => {
+        expect(rect.getAttribute('width')).toBe('1');
+        expect(rect.getAttribute('height')).toBe('8');
+      });
+    });
+
+    it('sits bottom-left, inset from the left edge, on desktop', () => {
+      const { container } = render(
+        <VideoBlock
+          block={
+            {
+              value: 'https://cdn.example.com/clip.mp4',
+              properties: { controls: false, customPlayPause: true }
+            } as any
+          }
+          placeholderId="p1"
+          sectionId="s1"
+          isDesigner={false}
+          currentBreakpoint="desktop"
+        />
+      );
+      const button = container.querySelector('button') as HTMLButtonElement;
+      expect(button.style.bottom).toBe('0px');
+      expect(button.style.left).toBe('24px');
+      expect(button.style.top).toBe('');
+      expect(button.style.right).toBe('');
+    });
+
+    it('moves to the top-right on mobile instead of just rescaling the desktop inset', () => {
+      const { container } = render(
+        <VideoBlock
+          block={
+            {
+              value: 'https://cdn.example.com/clip.mp4',
+              properties: { controls: false, customPlayPause: true }
+            } as any
+          }
+          placeholderId="p1"
+          sectionId="s1"
+          isDesigner={false}
+          currentBreakpoint="mobile"
+        />
+      );
+      const button = container.querySelector('button') as HTMLButtonElement;
+      expect(button.style.top).toBe('18px');
+      expect(button.style.right).toBe('18px');
+      expect(button.style.bottom).toBe('');
+      expect(button.style.left).toBe('');
+    });
+  });
 });
 
 /**

package/src/blocks/video-block.tsx

@@ -1,4 +1,6 @@
-import React from 'react';
+'use client';
+
+import React, { useRef, useState } from 'react';
 import { getResponsiveValue } from '../utils';
 import { BlockRendererProps } from './block-renderer-registry';
 
@@ -29,8 +31,29 @@ interface VideoProperties {
    * `…/watch?ref=clip.mp4` through as a playable file.
    */
   sourceType?: string;
+  /** Gated on `controls === false` in the editor — it replaces native controls, not add to them. */
+  customPlayPause?: unknown;
+  /** Off by default: mobile plays the same file as desktop unless this is on. */
+  useDifferentMobileVideo?: unknown;
+  mobileUrl?: unknown;
+  mobilePoster?: unknown;
 }
 
+/** Sized for a 20x20 button — the Figma control, not a generic icon glyph. */
+const PlayIcon = () => (
+  <svg width="6" height="8" viewBox="0 0 6 8" fill="none" aria-hidden="true">
+    <path d="M0.5 0.5L5.5 4L0.5 7.5V0.5Z" fill="currentColor" />
+  </svg>
+);
+
+/** Two 1x8 bars, centered in the button by its own flex layout. */
+const PauseIcon = () => (
+  <svg width="5" height="8" viewBox="0 0 5 8" fill="none" aria-hidden="true">
+    <rect x="0" y="0" width="1" height="8" fill="currentColor" />
+    <rect x="4" y="0" width="1" height="8" fill="currentColor" />
+  </svg>
+);
+
 /** Hosts, not substrings: `evil.com/?u=youtube.com/watch?v=x` is not YouTube. */
 const YOUTUBE_HOSTS = /(^|\.)(youtube\.com|youtube-nocookie\.com|youtu\.be)$/i;
 
@@ -168,11 +191,86 @@ const VideoBlock = ({
   block,
   currentBreakpoint = 'desktop'
 }: BlockRendererProps) => {
-  const videoUrl = block.value as string;
+  const desktopUrl = block.value as string;
   const properties = (block.properties || {}) as VideoProperties;
 
+  const isMobile = currentBreakpoint === 'mobile';
+  const useDifferentMobileVideo = !!getResponsiveValue(
+    properties.useDifferentMobileVideo,
+    currentBreakpoint,
+    false
+  );
+  const mobileUrl = getResponsiveValue(
+    properties.mobileUrl,
+    currentBreakpoint,
+    ''
+  ) as string;
+  const videoUrl =
+    isMobile && useDifferentMobileVideo && mobileUrl ? mobileUrl : desktopUrl;
+
+  // `properties` handed over RAW, not resolved: `buildEmbedParams` reads
+  // `autoplay`/`loop`/`muted`/`controls` the same way the native `<video>`
+  // below deliberately still does — see the note there.
   const parsed = parseVideoSource(videoUrl, properties);
 
+  /**
+   * Read through the breakpoint, the way `aspect-ratio` already is.
+   *
+   * The editor stores every one of these per breakpoint — `{ desktop: false }`,
+   * not `false`. So `properties.controls !== false` was comparing an OBJECT to
+   * `false`, which is never equal, and controls were on for every video whatever
+   * the merchant chose.
+   *
+   * `poster` had the mirror of the same defect: `typeof properties.poster ===
+   * 'string'` is false for the per-breakpoint object the editor writes, so a
+   * poster a merchant typed was stored, shown in the panel and silently
+   * dropped. Extended here with the mobile override this ticket adds.
+   *
+   * `autoplay`, `loop`, `muted` and `playsInline` are DELIBERATELY left
+   * reading raw, straight off `properties`, in the JSX below. They have the
+   * same defect pointing the other way: their stored value is an object, an
+   * object is truthy, and only the bug makes them true. Reading them
+   * correctly here would switch autoplay and loop OFF on every composition
+   * already published — a behaviour change that needs its own ticket, not a
+   * side effect of this one.
+   */
+  const nativeControls =
+    getResponsiveValue(properties.controls, currentBreakpoint, true) !== false;
+
+  const desktopPoster = getResponsiveValue(
+    properties.poster,
+    currentBreakpoint,
+    ''
+  ) as string;
+  const mobilePoster = getResponsiveValue(
+    properties.mobilePoster,
+    currentBreakpoint,
+    ''
+  ) as string;
+  const posterUrl =
+    isMobile && useDifferentMobileVideo && mobilePoster
+      ? mobilePoster
+      : desktopPoster;
+
+  // The custom button REPLACES native controls — it only ever shows up when
+  // native controls are off, matching the editor's `showWhen`.
+  const customPlayPause =
+    !nativeControls &&
+    !!getResponsiveValue(properties.customPlayPause, currentBreakpoint, false);
+
+  const videoRef = useRef<HTMLVideoElement>(null);
+  const [isPlaying, setIsPlaying] = useState(properties.autoplay === true);
+
+  const togglePlayback = () => {
+    const el = videoRef.current;
+    if (!el) return;
+    if (el.paused) {
+      el.play();
+    } else {
+      el.pause();
+    }
+  };
+
   /**
    * The author's choice wins; a Short supplies its own when they made none.
    * With neither, the historic fixed height is kept, so every composition
@@ -190,6 +288,25 @@ const VideoBlock = ({
       ? parsed.defaultRatio
       : undefined;
 
+  /**
+   * Read the same way `image-block.tsx` reads them, so a full-bleed hero is
+   * built identically for a video and an image: Height 100% + Position
+   * Absolute + inset 0 on the block, Object Fit Cover on the player. Without
+   * this the wrapper could be sized and positioned to fill its Group, but the
+   * `<video>` inside it stayed `height: auto` — sized by its own aspect
+   * ratio, not by the box it was placed in.
+   */
+  const heightStyle = getResponsiveValue(
+    block.styles?.height,
+    currentBreakpoint,
+    'auto'
+  ) as string;
+  const objectFit = getResponsiveValue(
+    block.styles?.['object-fit'],
+    currentBreakpoint,
+    'cover'
+  ) as React.CSSProperties['objectFit'];
+
   if (!videoUrl || !parsed) {
     return (
       <div
@@ -249,70 +366,97 @@ const VideoBlock = ({
     );
   }
 
-  /**
-   * Read through the breakpoint, the way `aspect-ratio` above already is.
-   *
-   * The editor stores every one of these per breakpoint — `{ desktop: false }`,
-   * not `false`. So `properties.controls !== false` was comparing an OBJECT to
-   * `false`, which is never equal, and controls were on for every video whatever
-   * the merchant chose. Nobody saw it because nothing painted a video before
-   * hydration; with the slides now server-rendered, a cold load would paint a
-   * full-width native control bar under the header.
-   *
-   * `poster` had the mirror of the same defect: `typeof properties.poster ===
-   * 'string'` is false for the per-breakpoint object the editor writes, so a
-   * poster a merchant typed was stored, shown in the panel and silently
-   * dropped.
-   *
-   * `autoplay`, `loop` and `muted` are DELIBERATELY left reading raw. They have
-   * the same defect pointing the other way: their stored value is an object,
-   * an object is truthy, and only the bug makes them true. Reading them
-   * correctly here would switch autoplay and loop OFF on every composition
-   * already published — a behaviour change that needs its own ticket, not a
-   * side effect of this one. `buildEmbedParams` reads all four raw for the
-   * same reason, and is left alone with them.
-   *
-   * `playsInline` is a FOURTH exclusion, and named here so its absence reads
-   * as a decision rather than an oversight. Its defect is identical to
-   * `controls` — same shape, same direction, same element — but the
-   * consequence is not: reading it correctly would let a merchant's stored
-   * `false` through, and an iPhone would then take the video fullscreen on
-   * play instead of keeping it in the page. That is a shopper-visible
-   * playback change on every placed composition, which belongs with the
-   * autoplay ticket. The control bar this ticket exists to remove is a
-   * painting problem; fullscreen playback is not.
-   */
-  const controls =
-    getResponsiveValue(properties.controls, currentBreakpoint, true) !== false;
-  const poster = getResponsiveValue(
-    properties.poster,
-    currentBreakpoint,
-    undefined
-  );
-
-  return (
+  const videoElement = (
     <video
+      ref={videoRef}
       src={parsed.src}
-      controls={controls}
+      controls={nativeControls}
       autoPlay={properties.autoplay}
       loop={properties.loop}
       muted={properties.muted}
-      poster={typeof poster === 'string' && poster ? poster : undefined}
+      poster={posterUrl || undefined}
       // Without it iOS opens the video full screen, which is never what an
-      // inline background clip is for.
+      // inline background clip is for. Left reading `properties.playsInline`
+      // raw for the same reason autoplay/loop/muted are above: fixing it
+      // would let a merchant's stored `false` through and take an iPhone
+      // fullscreen on play, on every composition already published — a
+      // shopper-visible playback change that belongs with that same,
+      // separate decision.
       playsInline={properties.playsInline !== false}
+      onPlay={() => setIsPlaying(true)}
+      onPause={() => setIsPlaying(false)}
       style={
         ratio
           ? {
               width: '100%',
               aspectRatio: ratio,
-              objectFit: 'cover',
+              objectFit,
+              borderRadius: 'inherit'
+            }
+          : {
+              width: '100%',
+              height: heightStyle,
+              objectFit,
               borderRadius: 'inherit'
             }
-          : { width: '100%', height: 'auto', borderRadius: 'inherit' }
       }
     />
   );
+
+  if (!customPlayPause) {
+    return videoElement;
+  }
+
+  /**
+   * No wrapper `<div>` around the video: `[data-block-id]` (rendered by
+   * `WithDesignerFeatures`) is already `position: relative` and already
+   * carries whatever height/position the author's block styles give it — a
+   * full-bleed hero video is sized THERE, not by the `<video>` tag's own
+   * intrinsic box. A wrapper here would only get the video's natural
+   * (usually much shorter) height, so `bottom: 0` landed the button near the
+   * top of the actually-visible video and clipped most of it away.
+   *
+   * `zIndex: 2` because a sibling content-overlay block (title/CTA on top of
+   * the video) is a full-size `position: absolute; z-index: 1` box — its
+   * unfilled area is still transparent, but not click-through, so without a
+   * higher z-index here the overlay wins hit-testing and swallows the click
+   * even where the button is visually on top of it.
+   */
+  // Desktop: bottom-left, flush to the bottom edge, inset from the left.
+  // Mobile: top-right instead — the design moves it off the bottom-left
+  // corner entirely rather than just rescaling the same inset.
+  const buttonPosition: React.CSSProperties = isMobile
+    ? { top: '18px', right: '18px' }
+    : { bottom: 0, left: '24px' };
+
+  return (
+    <>
+      {videoElement}
+      <button
+        type="button"
+        onClick={togglePlayback}
+        aria-label={isPlaying ? 'Pause video' : 'Play video'}
+        aria-pressed={isPlaying}
+        style={{
+          position: 'absolute',
+          ...buttonPosition,
+          zIndex: 2,
+          width: '20px',
+          height: '20px',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          background: 'rgba(255, 255, 255, 0.9)',
+          border: 'none',
+          padding: 0,
+          cursor: 'pointer',
+          color: '#111'
+        }}
+      >
+        {isPlaying ? <PauseIcon /> : <PlayIcon />}
+      </button>
+    </>
+  );
 };
 
 export default VideoBlock;

package/src/chrome/__tests__/scroll-state.test.tsx

@@ -68,7 +68,7 @@ const slotState = (slug = 'header') =>
 const renderSlot = (slug = 'header') =>
   render(
     <div data-chrome-slot={slug}>
-      <ChromeScrollState />
+      <ChromeScrollState slug={slug} />
     </div>
   );
 
@@ -172,6 +172,20 @@ describe('the chrome slot scroll signal', () => {
     crossViewportEdge(false);
     expect(slotState('header')).toBe('scrolled');
   });
+
+  it('stamps only its own slot on mount, not a sibling still waiting to hydrate', () => {
+    // Under Suspense, a header and a footer can hydrate at different times.
+    // The footer's `ChromeScrollState` mounting first must not reach into a
+    // header slot that exists in the DOM but has not mounted its own instance
+    // yet — that footer-driven write is exactly what made the header's own
+    // (later) hydration pass find an attribute its server markup never had.
+    render(<div data-chrome-slot="header" />);
+
+    renderSlot('footer');
+
+    expect(slotState('footer')).toBe('top');
+    expect(slotState('header')).toBeNull();
+  });
 });
 
 describe('previewing the scroll state in the designer', () => {

package/src/chrome/chrome-slot.tsx

@@ -127,7 +127,7 @@ export default async function ChromeSlot({
         ) : null}
         {/* Publishes `data-scroll-state` on the wrapper above, so a composition
             can style a header differently once the page is scrolled past it. */}
-        <ChromeScrollState />
+        <ChromeScrollState slug={slug} />
         {pinned && <StickySlotOverflow />}
         <ThemePlaceholder slug={slug} pageContext={pageContext} />
       </div>
@@ -151,7 +151,7 @@ export default async function ChromeSlot({
         // live site keeps rendering nothing.
         <ChromeFallback slug={slug} emptyZone />
       ) : null}
-      <ChromeScrollState />
+      <ChromeScrollState slug={slug} />
       {pinned && <StickySlotOverflow />}
       {/* Empty until the designer overrides this area from the editor */}
       <ThemePlaceholder slug={slug} pageContext={pageContext} />

package/src/chrome/scroll-state.tsx

@@ -65,6 +65,34 @@ const stampSlots = () => {
     .forEach((slot) => slot.setAttribute(SCROLL_STATE_ATTRIBUTE, state));
 };
 
+/**
+ * Stamps one named slot rather than every slot in the document.
+ *
+ * Used only for the stamp a slot gives itself the moment it mounts (see
+ * `observeScrollState` below) — never for the observer's own crossing
+ * callback, which must keep reaching every slot so a header and a footer
+ * mounted together still agree.
+ *
+ * The distinction matters under Suspense: a page can hydrate its slots at
+ * different times (a header outside a boundary, a footer inside one that
+ * still awaits data). The unscoped stamp used to run for every slot the
+ * moment ANY one of them mounted, writing the attribute onto a footer that
+ * had not hydrated yet — its own hydration pass then found an attribute in
+ * the real DOM that the server markup it was reconciling against never had,
+ * which React reports as a hydration mismatch even though nothing was
+ * actually wrong: the footer's own effect was about to write the same value
+ * moments later anyway.
+ */
+const stampSlot = (slug: string) => {
+  if (typeof document === 'undefined') return;
+
+  const state = pinnedState ?? observedState;
+  const slot = document.querySelector<HTMLElement>(
+    `div[data-chrome-slot="${CSS.escape(slug)}"]`
+  );
+  slot?.setAttribute(SCROLL_STATE_ATTRIBUTE, state);
+};
+
 const createSentinel = (): HTMLElement => {
   const element = document.createElement('div');
 
@@ -116,13 +144,22 @@ const stop = () => {
 /**
  * Registers one slot with the shared observer and returns the release its
  * effect has to run.
+ *
+ * `slug` scopes the mount-time stamp to just this slot — pass it whenever the
+ * caller knows which slot it is (`ChromeSlot` always does). Omit it only for
+ * a caller with no slug to give (the public export, used outside a
+ * `ChromeSlot`), which falls back to stamping every slot as before.
  */
-export const observeScrollState = (): (() => void) => {
+export const observeScrollState = (slug?: string): (() => void) => {
   registrations += 1;
   start();
   // A slot that mounted after the last crossing — a client route change, a late
   // hydration — would otherwise carry no attribute until the next one.
-  stampSlots();
+  if (slug) {
+    stampSlot(slug);
+  } else {
+    stampSlots();
+  }
 
   return () => {
     registrations -= 1;
@@ -152,9 +189,14 @@ export const pinScrollState = (state: ScrollState | null): void => {
 /**
  * Mounted by every ChromeSlot. Renders nothing: the slot element it stamps is
  * the server-rendered wrapper it sits inside.
+ *
+ * `slug` is the slot's own `data-chrome-slot` value — `ChromeSlot` always
+ * passes it, so mounting only ever stamps this slot, never one still waiting
+ * to hydrate elsewhere on the page (see `stampSlot`). Left unset only for a
+ * caller outside a `ChromeSlot`, where every slot is stamped as before.
  */
-export const ChromeScrollState = () => {
-  useEffect(() => observeScrollState(), []);
+export const ChromeScrollState = ({ slug }: { slug?: string } = {}) => {
+  useEffect(() => observeScrollState(slug), [slug]);
 
   return null;
 };