@akinon/pz-theme 2.0.54-rc.0 → 2.0.55-beta.0

package/CHANGELOG.md

@@ -1,36 +1,20 @@
 # @akinon/pz-theme
 
-## 2.0.54-rc.0
-
-### Patch Changes
-
-- Updated dependencies [0cf9ea239]
-- Updated dependencies [324f97d55]
-- Updated dependencies [51ea0688]
-- Updated dependencies
-- Updated dependencies [2fea4143]
-- Updated dependencies [b55acb768]
-- Updated dependencies [760258c1c]
-- Updated dependencies [143be2b9d]
-- Updated dependencies [7889b08fe]
-- Updated dependencies [9f8cd3bc5]
-- Updated dependencies [bfafa3f49]
-- Updated dependencies [57d7eb30]
-- Updated dependencies [d99a6a7d5]
-- Updated dependencies [9db81a71]
-- Updated dependencies [591e345e1]
-- Updated dependencies [4de5303c5]
-- Updated dependencies [95b139dc1]
-- Updated dependencies [1d00f2d0]
-- Updated dependencies [4ac7b2a1]
-- Updated dependencies [e9598c71]
-- Updated dependencies [4998a963]
-- Updated dependencies [804d2bd6]
-- Updated dependencies [3909d3224]
-- Updated dependencies [6a3d8a63]
-- Updated dependencies [e18836b2]
-  - @akinon/next@2.0.54-rc.0
-  - @akinon/theme-contract@2.0.54-rc.0
+## 2.0.55-beta.0
+
+### Patch Changes
+
+- Updated dependencies [cbbbfd75]
+  - @akinon/next@2.0.55-beta.0
+  - @akinon/theme-contract@2.0.55-beta.0
+
+## 2.0.54
+
+### Patch Changes
+
+- 2de849f: ZERO-4749: Publish a scroll state on chrome slots and add a `scrolled` style state
+  - @akinon/next@2.0.54
+  - @akinon/theme-contract@2.0.54
 
 ## 2.0.53
 

package/package.json

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

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

@@ -0,0 +1,227 @@
+import React from 'react';
+import { fireEvent, render } from '@testing-library/react';
+
+import {
+  ChromeScrollState,
+  SCROLL_STATE_ATTRIBUTE,
+  SCROLL_STATE_THRESHOLD,
+  pinScrollState
+} from '../scroll-state';
+import { PartStatePreview } from '../../components/part-state-preview';
+
+/**
+ * The scroll signal a composition styles against.
+ *
+ * Two properties matter more than the attribute itself. The first is that the
+ * storefront pays nothing for it: this has to be an IntersectionObserver, not a
+ * scroll handler running on the main thread for every frame of every scroll on
+ * every page that mounts a slot. The second is that the designer can see the
+ * state, which for a page-level fact means pinning the page rather than
+ * stamping an element — the mechanism every other state uses does not reach it.
+ */
+
+type ObserverRecord = {
+  callback: IntersectionObserverCallback;
+  observed: Element[];
+  disconnected: boolean;
+};
+
+const observers: ObserverRecord[] = [];
+
+class RecordingIntersectionObserver {
+  private readonly record: ObserverRecord;
+
+  constructor(callback: IntersectionObserverCallback) {
+    this.record = { callback, observed: [], disconnected: false };
+    observers.push(this.record);
+  }
+
+  observe(target: Element) {
+    this.record.observed.push(target);
+  }
+
+  unobserve() {}
+
+  disconnect() {
+    this.record.disconnected = true;
+  }
+
+  takeRecords() {
+    return [];
+  }
+}
+
+/** Drives the newest observer as the browser would when the sentinel crosses. */
+const crossViewportEdge = (isIntersecting: boolean) => {
+  const record = observers[observers.length - 1];
+  record.callback(
+    [{ isIntersecting } as IntersectionObserverEntry],
+    null as unknown as IntersectionObserver
+  );
+};
+
+const slotState = (slug = 'header') =>
+  document
+    .querySelector(`div[data-chrome-slot="${slug}"]`)
+    ?.getAttribute(SCROLL_STATE_ATTRIBUTE);
+
+const renderSlot = (slug = 'header') =>
+  render(
+    <div data-chrome-slot={slug}>
+      <ChromeScrollState />
+    </div>
+  );
+
+const originalObserver = window.IntersectionObserver;
+
+beforeEach(() => {
+  observers.length = 0;
+  window.IntersectionObserver =
+    RecordingIntersectionObserver as unknown as typeof IntersectionObserver;
+});
+
+afterEach(() => {
+  pinScrollState(null);
+  window.IntersectionObserver = originalObserver;
+});
+
+describe('the chrome slot scroll signal', () => {
+  it('stamps the state on every slot and follows the sentinel', () => {
+    renderSlot();
+
+    // Present from the first paint: a slot whose attribute only appeared on the
+    // first crossing would leave `[data-scroll-state~="scrolled"]` unmatchable
+    // and the authored default unexplained.
+    expect(slotState()).toBe('top');
+
+    crossViewportEdge(false);
+    expect(slotState()).toBe('scrolled');
+
+    crossViewportEdge(true);
+    expect(slotState()).toBe('top');
+  });
+
+  it('observes a zero-height sentinel on the body, at the threshold', () => {
+    renderSlot();
+
+    const sentinel = document.querySelector<HTMLElement>(
+      '[data-scroll-state-sentinel]'
+    );
+
+    expect(sentinel).not.toBeNull();
+    // On the body rather than in the slot: the element that wants this state is
+    // usually fixed or sticky, and a sentinel inside it would travel with it and
+    // never leave the viewport.
+    expect(sentinel?.parentElement).toBe(document.body);
+    expect(sentinel?.style.height).toBe('0px');
+    expect(sentinel?.style.top).toBe(`${SCROLL_STATE_THRESHOLD}px`);
+    expect(observers[0].observed).toEqual([sentinel]);
+  });
+
+  it('adds no scroll listener anywhere on the storefront path', () => {
+    const onWindow = jest.spyOn(window, 'addEventListener');
+    const onDocument = jest.spyOn(document, 'addEventListener');
+
+    renderSlot();
+    crossViewportEdge(false);
+
+    const listened = [...onWindow.mock.calls, ...onDocument.mock.calls].map(
+      ([type]) => type
+    );
+
+    expect(listened).not.toContain('scroll');
+
+    onWindow.mockRestore();
+    onDocument.mockRestore();
+  });
+
+  it('serves every slot from one observer and takes it down with the last', () => {
+    const { unmount } = render(
+      <>
+        <div data-chrome-slot="header">
+          <ChromeScrollState />
+        </div>
+        <div data-chrome-slot="footer">
+          <ChromeScrollState />
+        </div>
+      </>
+    );
+
+    // Both slots read the same scroll position, so a second observer would be
+    // a second answer to a question that has one.
+    expect(observers).toHaveLength(1);
+
+    crossViewportEdge(false);
+    expect(slotState('header')).toBe('scrolled');
+    expect(slotState('footer')).toBe('scrolled');
+
+    unmount();
+    expect(observers[0].disconnected).toBe(true);
+    expect(
+      document.querySelector('[data-scroll-state-sentinel]')
+    ).toBeNull();
+  });
+
+  it('keeps the observer while one of several slots unmounts', () => {
+    const { unmount } = renderSlot('footer');
+    renderSlot('header');
+
+    unmount();
+
+    expect(observers[0].disconnected).toBe(false);
+    crossViewportEdge(false);
+    expect(slotState('header')).toBe('scrolled');
+  });
+});
+
+describe('previewing the scroll state in the designer', () => {
+  const previewState = (state: string | null) =>
+    fireEvent(
+      window,
+      new MessageEvent('message', {
+        data: { type: 'PREVIEW_PART_STATE', data: { state } }
+      })
+    );
+
+  it('pins the page rather than the part, and releases it again', () => {
+    render(
+      <>
+        <PartStatePreview isDesigner />
+        <div data-chrome-slot="header">
+          <ChromeScrollState />
+        </div>
+      </>
+    );
+
+    expect(slotState()).toBe('top');
+
+    // The canvas is at the top of the page and the designer cannot both hold it
+    // scrolled and reach the colour picker — the pin is the whole point.
+    previewState('scrolled');
+    expect(slotState()).toBe('scrolled');
+
+    // Moving to any other state releases it: a canvas left frozen mid-page
+    // disagrees with the storefront for every style typed after it.
+    previewState('hover');
+    expect(slotState()).toBe('top');
+  });
+
+  it('lets the observer win again once the pin is released', () => {
+    render(
+      <>
+        <PartStatePreview isDesigner />
+        <div data-chrome-slot="header">
+          <ChromeScrollState />
+        </div>
+      </>
+    );
+
+    crossViewportEdge(false);
+    previewState('scrolled');
+    previewState(null);
+
+    // Released to what the sentinel actually reports, not to 'top': the
+    // designer may have scrolled the canvas while the pin was held.
+    expect(slotState()).toBe('scrolled');
+  });
+});

package/src/chrome/chrome-slot.tsx

@@ -4,6 +4,7 @@ import { warnAboutUncomposedSlot } from './composition-state';
 import { getSlugCompositionState } from './composition-source';
 import { getThemeConfig } from './theme-config-source';
 import { ChromeFallback } from './chrome-fallback';
+import { ChromeScrollState } from './scroll-state';
 import {
   resolveSlotSticky,
   slotStickyStyle,
@@ -116,6 +117,9 @@ export default async function ChromeSlot({
         ) : emptyZoneBand ? (
           <ChromeFallback slug={slug} emptyZone initiallyOverridden />
         ) : 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 />
         {pinned && <StickySlotOverflow />}
         <ThemePlaceholder slug={slug} pageContext={pageContext} />
       </div>
@@ -139,6 +143,7 @@ export default async function ChromeSlot({
         // live site keeps rendering nothing.
         <ChromeFallback slug={slug} emptyZone />
       ) : null}
+      <ChromeScrollState />
       {pinned && <StickySlotOverflow />}
       {/* Empty until the designer overrides this area from the editor */}
       <ThemePlaceholder slug={slug} pageContext={pageContext} />

package/src/chrome/scroll-state.tsx

@@ -0,0 +1,162 @@
+'use client';
+
+import { useEffect } from 'react';
+
+/**
+ * "The page has scrolled away from the top", published as a styling signal.
+ *
+ * A header that floats transparently over a hero has to turn opaque once the
+ * shopper scrolls past it, and no rung of the composition could say that: a
+ * style value is static per breakpoint, and the only scroll listener this
+ * package ships repositions the designer's own toolbar. The signal is published
+ * as an attribute on the slot — `data-scroll-state="top" | "scrolled"` — so the
+ * CSS generator can match it through an ancestor selector and no block renderer
+ * has to know the state exists at all (see utils/part-styles.ts).
+ *
+ * Deliberately an IntersectionObserver over a sentinel rather than a scroll
+ * handler. A scroll handler runs on the main thread for every frame of every
+ * scroll, on every page that mounts a slot, whether or not the composition
+ * styles the state — the observer costs nothing until the sentinel crosses the
+ * viewport edge. Pinned by test.
+ *
+ * The sentinel lives on `document.body`, not inside the slot. The element that
+ * wants this state is almost always the one that is `position: fixed` or
+ * `sticky`, and a sentinel inside it would travel with it and never leave the
+ * viewport. Absolutely positioned at the threshold instead, "no longer
+ * intersecting" reads as exactly `scrollY > threshold` — the same reading brand
+ * sticky-header hooks take from `window.scrollY`.
+ *
+ * One observer serves the whole document: every slot on the page reaches the
+ * same conclusion about the same scroll position. Slots register, and the last
+ * one to unmount takes the sentinel down with it.
+ */
+
+/** The attribute the renderer's `scrolled` selector matches on. */
+export const SCROLL_STATE_ATTRIBUTE = 'data-scroll-state';
+
+/** The style-state name this signal answers to (see utils/part-styles.ts). */
+export const SCROLL_STYLE_STATE = 'scrolled';
+
+/**
+ * How far the page scrolls before it counts as scrolled, in px. Matches the
+ * threshold brand sticky-header hooks already use, so a composition that
+ * replaces one flips at the same place the hand-written header did.
+ */
+export const SCROLL_STATE_THRESHOLD = 100;
+
+export type ScrollState = 'top' | 'scrolled';
+
+/** Every chrome slot carries the state; the selector is half of the contract. */
+const CHROME_SLOT_SELECTOR = 'div[data-chrome-slot]';
+
+let sentinel: HTMLElement | null = null;
+let observer: IntersectionObserver | null = null;
+let registrations = 0;
+let observedState: ScrollState = 'top';
+let pinnedState: ScrollState | null = null;
+
+const stampSlots = () => {
+  if (typeof document === 'undefined') return;
+
+  const state = pinnedState ?? observedState;
+
+  document
+    .querySelectorAll<HTMLElement>(CHROME_SLOT_SELECTOR)
+    .forEach((slot) => slot.setAttribute(SCROLL_STATE_ATTRIBUTE, state));
+};
+
+const createSentinel = (): HTMLElement => {
+  const element = document.createElement('div');
+
+  element.setAttribute('data-scroll-state-sentinel', '');
+  element.setAttribute('aria-hidden', 'true');
+  // Zero-sized and out of the pointer's way: it exists to be observed, never to
+  // be seen, hit or to take part in layout. `top` carries the threshold, which
+  // is what makes the crossing happen at the scroll position that flips state
+  // rather than at zero.
+  element.style.position = 'absolute';
+  element.style.top = `${SCROLL_STATE_THRESHOLD}px`;
+  element.style.left = '0px';
+  element.style.width = '0px';
+  element.style.height = '0px';
+  element.style.pointerEvents = 'none';
+
+  return element;
+};
+
+const start = () => {
+  if (observer || typeof document === 'undefined') return;
+  // A browser without IntersectionObserver is not worth a scroll handler
+  // fallback: the state simply stays at its authored default, which is the
+  // unscrolled look the page loads with.
+  if (typeof IntersectionObserver === 'undefined') return;
+
+  sentinel = createSentinel();
+  document.body.appendChild(sentinel);
+
+  observer = new IntersectionObserver((entries) => {
+    const entry = entries[entries.length - 1];
+    if (!entry) return;
+
+    observedState = entry.isIntersecting ? 'top' : 'scrolled';
+    stampSlots();
+  });
+
+  observer.observe(sentinel);
+};
+
+const stop = () => {
+  observer?.disconnect();
+  observer = null;
+  sentinel?.remove();
+  sentinel = null;
+  observedState = 'top';
+};
+
+/**
+ * Registers one slot with the shared observer and returns the release its
+ * effect has to run.
+ */
+export const observeScrollState = (): (() => 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();
+
+  return () => {
+    registrations -= 1;
+
+    if (registrations <= 0) {
+      registrations = 0;
+      stop();
+    }
+  };
+};
+
+/**
+ * Holds the page in a scroll state while the designer styles it.
+ *
+ * Every other style state is a fact about an element, so the canvas pins it by
+ * writing `data-state` onto that element. This one is a fact about the page and
+ * is matched through an ancestor, so there is nothing on the element to write —
+ * and a designer cannot hold the canvas scrolled and reach the colour picker at
+ * the same time any more than they can hold a hover. Pinning here overrides
+ * what the observer sees until it is released with `null`.
+ */
+export const pinScrollState = (state: ScrollState | null): void => {
+  pinnedState = state;
+  stampSlots();
+};
+
+/**
+ * Mounted by every ChromeSlot. Renders nothing: the slot element it stamps is
+ * the server-rendered wrapper it sits inside.
+ */
+export const ChromeScrollState = () => {
+  useEffect(() => observeScrollState(), []);
+
+  return null;
+};
+
+export default ChromeScrollState;

package/src/components/part-state-preview.tsx

@@ -2,6 +2,8 @@
 
 import { useEffect } from 'react';
 
+import { SCROLL_STYLE_STATE, pinScrollState } from '../chrome/scroll-state';
+
 /**
  * Pins a part's state open while the designer styles it.
  *
@@ -47,6 +49,19 @@ export const PartStatePreview = ({ isDesigner }: { isDesigner: boolean }) => {
       const { blockId, partName, state } = event.data.data || {};
       clear();
 
+      // One state is not a fact about the element: `scrolled` is matched
+      // through `data-scroll-state` on the chrome slot, so writing it onto the
+      // part would light nothing up and the designer would type a colour into
+      // a canvas that never changes. The page is pinned instead — and released
+      // on every other message, so the canvas never stays frozen in a scrolled
+      // state after the designer has moved on to a different one.
+      if (state === SCROLL_STYLE_STATE) {
+        pinScrollState('scrolled');
+        return;
+      }
+
+      pinScrollState(null);
+
       if (!blockId || !partName || !state) return;
 
       const block = document.querySelector<HTMLElement>(
@@ -83,6 +98,7 @@ export const PartStatePreview = ({ isDesigner }: { isDesigner: boolean }) => {
     return () => {
       window.removeEventListener('message', handleMessage);
       clear();
+      pinScrollState(null);
     };
   }, [isDesigner]);
 

package/src/index.ts

@@ -28,6 +28,14 @@ export { default as ChromeSlot } from './chrome/chrome-slot';
 export { default as ComposableRegion } from './chrome/composable-region';
 export { ChromeFallback } from './chrome/chrome-fallback';
 export { CodeOwnedRegion } from './chrome/code-owned-region';
+// Brand CSS following the same signal a composition's `scrolled` state follows
+// needs the attribute name itself, not a second copy of the string.
+export {
+  ChromeScrollState,
+  SCROLL_STATE_ATTRIBUTE,
+  SCROLL_STATE_THRESHOLD,
+  SCROLL_STYLE_STATE
+} from './chrome/scroll-state';
 export { PreviewAuthStateReporter } from './chrome/preview-auth-state';
 export { LiveBasketPageContext } from './chrome/live-basket-page-context';
 export {

package/src/utils/__tests__/scrolled-state-styles.test.ts

@@ -0,0 +1,206 @@
+import { generateThemeCSS } from '../index';
+import { stripHidingStyles } from '../checkout-safety';
+import {
+  buildPartSelectors,
+  buildRootStateKey,
+  parseRootStateKey,
+  splitPartStyles
+} from '../part-styles';
+import type { Section } from '../../theme-section';
+
+/**
+ * `scrolled` as a style state, at all three rungs it has to reach.
+ *
+ * Every other state is a fact about an element and matches on the element, so
+ * it can be expressed as a selector SUFFIX. This one is a fact about the page,
+ * published on the chrome slot, so its selector is ancestor-conditioned — which
+ * is why the part-selector builder had to learn a placeholder, and why the
+ * root path (block wrapper, section band) needed a key grammar at all: the
+ * first thing a designer wants from a scroll state is a whole header band
+ * changing colour, and a band is a section, not a part inside one.
+ */
+
+const SLOT = '[data-scroll-state~="scrolled"]';
+
+const section = (id: string, styles: Record<string, unknown>, blocks: unknown[] = []) =>
+  ({
+    id,
+    type: 'custom',
+    properties: {},
+    styles,
+    order: 0,
+    hidden: false,
+    blocks
+  }) as unknown as Section;
+
+const block = (id: string, styles: Record<string, unknown>, type = 'group') => ({
+  id,
+  type,
+  label: 'Block',
+  properties: {},
+  styles,
+  order: 0,
+  hidden: false,
+  blocks: []
+});
+
+describe('the part rule', () => {
+  it('conditions the part on the slot without losing the ownership guard', () => {
+    const [selector] = buildPartSelectors('[data-block-id="blk-1"]', {
+      part: 'logo',
+      state: 'scrolled',
+      styles: {}
+    });
+
+    expect(selector).toBe(
+      `${SLOT} [data-block-id="blk-1"] [data-part="logo"]` +
+        ':not(:where([data-block-id="blk-1"] [data-block-id] *))'
+    );
+  });
+
+  it('still refuses to reach a nested block that names the same part', () => {
+    const [selector] = buildPartSelectors('[data-block-id="outer"]', {
+      part: 'logo',
+      state: 'scrolled',
+      styles: {}
+    });
+
+    document.body.innerHTML =
+      '<div data-chrome-slot="header" data-scroll-state="scrolled">' +
+      '<div data-block-id="outer">' +
+      '<img id="own" data-part="logo" />' +
+      '<div data-block-id="inner"><img id="nested" data-part="logo" /></div>' +
+      '</div>' +
+      '</div>';
+
+    expect(
+      Array.from(document.querySelectorAll(selector)).map((el) => el.id)
+    ).toEqual(['own']);
+  });
+
+  it('matches nothing while the page is at the top', () => {
+    const [selector] = buildPartSelectors('[data-block-id="blk-1"]', {
+      part: 'logo',
+      state: 'scrolled',
+      styles: {}
+    });
+
+    document.body.innerHTML =
+      '<div data-chrome-slot="header" data-scroll-state="top">' +
+      '<div data-block-id="blk-1"><img data-part="logo" /></div>' +
+      '</div>';
+
+    expect(document.querySelectorAll(selector)).toHaveLength(0);
+  });
+});
+
+describe('the root-state key grammar', () => {
+  it('reads `:state/property` and refuses anything else', () => {
+    expect(parseRootStateKey(':scrolled/background-color')).toEqual({
+      state: 'scrolled',
+      property: 'background-color'
+    });
+    expect(parseRootStateKey(buildRootStateKey('hover', 'color'))).toEqual({
+      state: 'hover',
+      property: 'color'
+    });
+
+    // A bare property, a part key and an unknown state all stay where they are.
+    expect(parseRootStateKey('background-color')).toBeNull();
+    expect(parseRootStateKey('logo/background-color')).toBeNull();
+    expect(parseRootStateKey(':wobble/background-color')).toBeNull();
+  });
+
+  it('cannot be confused with a part that happens to be named after a state', () => {
+    const { root, parts, rootStates } = splitPartStyles({
+      'background-color': '#fff',
+      'scrolled/background-color': '#eee',
+      ':scrolled/background-color': '#000'
+    });
+
+    expect(root).toEqual({ 'background-color': '#fff' });
+    expect(parts).toEqual([
+      { part: 'scrolled', state: null, styles: { 'background-color': '#eee' } }
+    ]);
+    expect(rootStates).toEqual([
+      { state: 'scrolled', styles: { 'background-color': '#000' } }
+    ]);
+  });
+});
+
+describe('the block and section root rules', () => {
+  it('emits a scrolled rule for a section band, after its plain rule', () => {
+    const css = generateThemeCSS([
+      section('sec-1', {
+        'background-color': 'transparent',
+        ':scrolled/background-color': '#ffffff'
+      })
+    ]);
+
+    expect(css).toContain(
+      '[data-section-id="sec-1"] {\n  background-color: transparent;\n}'
+    );
+    // Through the same background-opacity path a plain root colour takes, so a
+    // state value is composed exactly like the value it overrides.
+    expect(css).toContain(
+      `${SLOT} [data-section-id="sec-1"] {\n  background-color: rgba(255, 255, 255, 1);\n}`
+    );
+    // Order is the tie-breaker the whole cascade in this file relies on; the
+    // state also carries more specificity, but it must never be written first.
+    expect(css.indexOf('[data-section-id="sec-1"] {')).toBeLessThan(
+      css.indexOf(`${SLOT} [data-section-id="sec-1"] {`)
+    );
+  });
+
+  it('emits a scrolled rule for a block wrapper', () => {
+    const css = generateThemeCSS([
+      section('sec-1', {}, [block('blk-1', { ':scrolled/color': '#111111' })])
+    ]);
+
+    expect(css).toContain(
+      `${SLOT} [data-block-id="blk-1"] {\n  color: #111111;\n}`
+    );
+  });
+
+  it('follows a block that routes its root styles to its real root part', () => {
+    const css = generateThemeCSS([
+      section('sec-1', {}, [
+        {
+          ...block('blk-1', { ':scrolled/color': '#111111' }),
+          stylesTargetRoot: true
+        }
+      ])
+    ]);
+
+    // The state has to land on the same element the stateless root rule does,
+    // or it would style the transparent designer wrapper the block sits in.
+    expect(css).toContain(
+      `${SLOT} [data-block-id="blk-1"] [data-part="root"] {\n  color: #111111;\n}`
+    );
+  });
+
+  it('never emits the raw key as a declaration', () => {
+    const css = generateThemeCSS([
+      section('sec-1', { ':scrolled/background-color': '#ffffff' })
+    ]);
+
+    expect(css).not.toContain(':scrolled/background-color:');
+  });
+});
+
+describe('checkout safety', () => {
+  it('strips a hiding declaration written into a root state', () => {
+    // Without the root-state key being read for its property, `display: none`
+    // would arrive under a name nothing recognises and sail through the one
+    // filter that stands between a composition and an unorderable checkout.
+    expect(
+      stripHidingStyles(
+        {
+          ':scrolled/display': 'none',
+          ':scrolled/background-color': '#ffffff'
+        },
+        'root-only'
+      )
+    ).toEqual({ ':scrolled/background-color': '#ffffff' });
+  });
+});

package/src/utils/checkout-safety.ts

@@ -28,7 +28,7 @@
  * subtracts the values that end ordering.
  */
 
-import { parsePartStyleKey } from './part-styles';
+import { parsePartStyleKey, parseRootStateKey } from './part-styles';
 
 export const CHECKOUT_FLOW_OUTLET_TYPE = 'checkout-flow-outlet';
 
@@ -142,6 +142,11 @@ export const stripHidingStyles = (
 
   Object.entries(styles || {}).forEach(([key, value]) => {
     const parsed = parsePartStyleKey(key);
+    // A root-state key (`:scrolled/display`) addresses the element's own root,
+    // so it is guarded exactly as a bare root key is. Reading the property out
+    // of it is what makes that true: left as the whole key, `display: none`
+    // would arrive here under a name nothing recognises and sail through.
+    const rootState = parsed ? null : parseRootStateKey(key);
 
     const guarded = parsed
       ? partScope === 'critical-parts' &&
@@ -153,7 +158,7 @@ export const stripHidingStyles = (
       return;
     }
 
-    const property = parsed ? parsed.property : key;
+    const property = (parsed ?? rootState)?.property ?? key;
     const kept = stripHidingFromValue(property, value);
 
     if (kept !== undefined) safe[key] = kept;

package/src/utils/index.ts

@@ -5,7 +5,11 @@ import {
   neutralizeStyleTagBreakout,
   escapeCssAttributeValue
 } from './css-safety';
-import { buildPartSelectors, splitPartStyles } from './part-styles';
+import {
+  buildPartSelectors,
+  buildRootStateSelectors,
+  splitPartStyles
+} from './part-styles';
 import { buildCustomCss, buildPartCustomCss } from './custom-css';
 import {
   CHECKOUT_FLOW_OUTLET_TYPE,
@@ -1278,6 +1282,41 @@ const generatePartCSS = (
   return css;
 };
 
+/**
+ * Rules for a block or section's own root in a state.
+ *
+ * Not `!important`, unlike the part rules above. Those need it because the
+ * element they target carries the renderer's own inline styles; a block wrapper
+ * or a section band does not, and the only rule this has to beat is the plain
+ * root rule emitted a few lines earlier — which it already does on specificity,
+ * a state selector being strictly longer than the stateless one. Forcing it
+ * would buy nothing and cost the custom-CSS hatch its `!important`, which is
+ * the designer's documented way to win an argument with a generated rule.
+ */
+const generateRootStateCSS = (
+  elementSelector: string,
+  styles: Record<string, unknown>,
+  targetBreakpoint?: string
+): string => {
+  const { rootStates } = splitPartStyles(styles);
+  if (rootStates.length === 0) return '';
+
+  let css = '';
+
+  rootStates.forEach((bucket) => {
+    const selectors = buildRootStateSelectors(elementSelector, bucket.state);
+    if (selectors.length === 0) return;
+
+    css += generateElementCSS(
+      selectors.join(',\n'),
+      bucket.styles as ResponsiveStyles,
+      targetBreakpoint
+    );
+  });
+
+  return css;
+};
+
 const collectBlockCSS = (
   blocks: Block[],
   targetBreakpoint?: string
@@ -1308,21 +1347,24 @@ const collectBlockCSS = (
       // block wrapper (a padding meant for the dropdown would otherwise
       // reposition the whole block).
       const { root } = splitPartStyles(blockStyles);
+      // `data-block-id` sits on the designer wrapper, not on the element the
+      // renderer actually draws — so a padding or border set on a functional
+      // block stopped at a transparent div and never reached the control.
+      // A block that names its real root with `data-part="root"` gets its
+      // own styles routed there instead. Blocks that do not are untouched,
+      // which is what keeps published compositions rendering as before.
+      const rootSelector = block.stylesTargetRoot
+        ? `${selector} [data-part="root"]`
+        : selector;
 
       if (Object.keys(root).length > 0) {
-        // `data-block-id` sits on the designer wrapper, not on the element the
-        // renderer actually draws — so a padding or border set on a functional
-        // block stopped at a transparent div and never reached the control.
-        // A block that names its real root with `data-part="root"` gets its
-        // own styles routed there instead. Blocks that do not are untouched,
-        // which is what keeps published compositions rendering as before.
-        const rootSelector = block.stylesTargetRoot
-          ? `${selector} [data-part="root"]`
-          : selector;
-
         css += generateElementCSS(rootSelector, root, targetBreakpoint);
       }
 
+      // After the plain root rule, and against the same element: a state has to
+      // be able to override what the stateless value painted.
+      css += generateRootStateCSS(rootSelector, blockStyles, targetBreakpoint);
+
       css += generatePartCSS(selector, blockStyles, targetBreakpoint);
     }
 
@@ -1393,6 +1435,12 @@ export const generateThemeCSS = (
         );
       }
 
+      css += generateRootStateCSS(
+        sectionSelector,
+        sectionStyles,
+        targetBreakpoint
+      );
+
       css += generatePartCSS(
         sectionSelector,
         sectionStyles,

package/src/utils/part-styles.ts

@@ -24,12 +24,17 @@
  */
 
 /**
- * State segment -> the selector suffixes that express it.
+ * State segment -> the selector expressions that express it.
  *
  * Every state also matches `[data-state~="…"]`, including the ones that are
  * really pseudo-classes. That is what lets the editor pin a state open: a
  * designer cannot hover an element while typing a hover colour, so the canvas
  * writes the state onto the element and the same rule applies.
+ *
+ * An expression is normally a SUFFIX appended to the styled element's selector.
+ * One containing `&` is a pattern instead, and `&` is where that selector goes
+ * — the only way to express a state that is matched on an ANCESTOR rather than
+ * on the element itself.
  */
 const STATE_SELECTORS: Record<string, string[]> = {
   hover: [':hover', '[data-state~="hover"]'],
@@ -63,14 +68,38 @@ const STATE_SELECTORS: Record<string, string[]> = {
   // "unavailable" never satisfies the "available" selector.
   available: ['[data-state~="available"]'],
   unavailable: ['[data-state~="unavailable"]'],
-  unknown: ['[data-state~="unknown"]']
+  unknown: ['[data-state~="unknown"]'],
+  // The odd one out: every state above is a fact about the ELEMENT and matches
+  // on the element itself. This one is a fact about the PAGE — the chrome slot
+  // carries `data-scroll-state` (see chrome/scroll-state.tsx) — so it is
+  // matched through an ancestor and no renderer has to stamp anything for it to
+  // apply. That is what lets a header become opaque on scroll, which nothing in
+  // a composition could previously say.
+  scrolled: ['[data-scroll-state~="scrolled"] &']
 };
 
 export const PART_STYLE_STATES = Object.keys(STATE_SELECTORS);
 
+/** Marks where the styled element's selector goes in an ancestor-matched state. */
+const STATE_ELEMENT_PLACEHOLDER = '&';
+
+/**
+ * Places the styled element's selector into a state expression.
+ *
+ * A suffix is appended, which is what every element-matched state needs. A
+ * pattern is substituted into, which is what an ancestor-matched state needs.
+ */
+const applyStateExpression = (element: string, expression: string): string =>
+  expression.includes(STATE_ELEMENT_PLACEHOLDER)
+    ? expression.split(STATE_ELEMENT_PLACEHOLDER).join(element)
+    : `${element}${expression}`;
+
 /** Keys are `part/prop` or `part/state/prop`; `/` never appears in a CSS property. */
 const PART_KEY_DELIMITER = '/';
 
+/** Leads a root-state key (`:scrolled/background-color`); see below. */
+const ROOT_STATE_MARKER = ':';
+
 export type ParsedPartKey = {
   part: string;
   state: string | null;
@@ -79,6 +108,11 @@ export type ParsedPartKey = {
 
 export const parsePartStyleKey = (key: string): ParsedPartKey | null => {
   if (!key || key.indexOf(PART_KEY_DELIMITER) === -1) return null;
+  // A root-state key has the same two segments as a part key, so without this
+  // it parses as a part literally named ":scrolled" — which is not merely wrong
+  // output: `stripHidingStyles` reads part keys as belonging to a nested part
+  // and would wave a `display: none` on the checkout wrapper straight through.
+  if (key[0] === ROOT_STATE_MARKER) return null;
 
   const segments = key.split(PART_KEY_DELIMITER).filter(Boolean);
 
@@ -108,6 +142,47 @@ export const buildPartStyleKey = (
     ? [part, state, property].join(PART_KEY_DELIMITER)
     : [part, property].join(PART_KEY_DELIMITER);
 
+/**
+ * The same states, on the element's OWN root rather than on a part inside it.
+ *
+ * A part key could already say "this dropdown, while scrolled", but a block or
+ * section root could not say anything of the kind: its keys are bare CSS
+ * properties with nowhere to put a state. That leaves the most obvious thing a
+ * designer wants from a scroll state — a whole header band changing its
+ * background and text colour — unreachable, since the band is the section, not
+ * a part inside it.
+ *
+ * Root-state keys are `:<state>/<property>`. The leading marker is what keeps
+ * them unambiguous: a bare `scrolled/background` would be indistinguishable
+ * from a part literally named `scrolled`, and `:` cannot appear in a part name
+ * (`sanitizePartName` strips it), so nothing that parses as one can ever parse
+ * as the other.
+ */
+export type ParsedRootStateKey = {
+  state: string;
+  property: string;
+};
+
+export const parseRootStateKey = (key: string): ParsedRootStateKey | null => {
+  if (!key || key[0] !== ROOT_STATE_MARKER) return null;
+
+  const segments = key
+    .slice(ROOT_STATE_MARKER.length)
+    .split(PART_KEY_DELIMITER)
+    .filter(Boolean);
+
+  if (segments.length !== 2) return null;
+
+  const [state, property] = segments;
+  if (!STATE_SELECTORS[state]) return null;
+
+  return { state, property };
+};
+
+/** Builds the style key a root-state descriptor writes into. */
+export const buildRootStateKey = (state: string, property: string): string =>
+  `${ROOT_STATE_MARKER}${state}${PART_KEY_DELIMITER}${property}`;
+
 /**
  * `data-part` plus the states the renderer wants stylable. Renderers spread
  * this onto the element instead of hand-writing the attributes, so the
@@ -142,18 +217,45 @@ export type PartStyleBucket = {
   styles: Record<string, unknown>;
 };
 
+/** A root/state bucket of styles, ready for the CSS generator. */
+export type RootStateBucket = {
+  state: string;
+  styles: Record<string, unknown>;
+};
+
 /**
- * Splits a block's styles into the root bucket and one bucket per
- * part/state pair, preserving insertion order so generated CSS is stable
+ * Splits a block's styles into the root bucket, one bucket per part/state pair
+ * and one per root state, preserving insertion order so generated CSS is stable
  * (a moving stylesheet would defeat caching and make diffs unreadable).
  */
 export const splitPartStyles = (
   styles: Record<string, unknown> | undefined | null
-): { root: Record<string, unknown>; parts: PartStyleBucket[] } => {
+): {
+  root: Record<string, unknown>;
+  parts: PartStyleBucket[];
+  rootStates: RootStateBucket[];
+} => {
   const root: Record<string, unknown> = {};
   const buckets = new Map<string, PartStyleBucket>();
+  const rootStateBuckets = new Map<string, RootStateBucket>();
 
   Object.entries(styles || {}).forEach(([key, value]) => {
+    // Before the part parse: a root-state key is not a part key, and left to
+    // the root bucket it would be emitted as the invalid declaration
+    // `:scrolled/background-color:`.
+    const rootState = parseRootStateKey(key);
+
+    if (rootState) {
+      const bucket = rootStateBuckets.get(rootState.state) ?? {
+        state: rootState.state,
+        styles: {}
+      };
+
+      bucket.styles[rootState.property] = value;
+      rootStateBuckets.set(rootState.state, bucket);
+      return;
+    }
+
     const parsed = parsePartStyleKey(key);
 
     if (!parsed) {
@@ -172,7 +274,11 @@ export const splitPartStyles = (
     buckets.set(bucketKey, bucket);
   });
 
-  return { root, parts: Array.from(buckets.values()) };
+  return {
+    root,
+    parts: Array.from(buckets.values()),
+    rootStates: Array.from(rootStateBuckets.values())
+  };
 };
 
 /** Only `[A-Za-z0-9_-]` survives, so a part name cannot break out of the selector. */
@@ -226,10 +332,35 @@ export const buildPartSelectors = (
 
   if (!bucket.state) return [`${base}${owned}`];
 
-  const suffixes = STATE_SELECTORS[bucket.state];
-  if (!suffixes) return [];
+  const expressions = STATE_SELECTORS[bucket.state];
+  if (!expressions) return [];
+
+  return expressions.map((expression) =>
+    expression.includes(STATE_ELEMENT_PLACEHOLDER)
+      ? // An ancestor-matched state substitutes the whole compound, guard
+        // included, so the rule can no more leak into a nested block than the
+        // stateless one can.
+        applyStateExpression(`${base}${owned}`, expression)
+      : `${base}${expression}${owned}`
+  );
+};
+
+/**
+ * Selectors for a block or section's OWN root in a state.
+ *
+ * No ownership guard here, and none is needed: the selector already names one
+ * element by id, so there is nothing for it to leak into.
+ */
+export const buildRootStateSelectors = (
+  elementSelector: string,
+  state: string
+): string[] => {
+  const expressions = STATE_SELECTORS[state];
+  if (!expressions) return [];
 
-  return suffixes.map((suffix) => `${base}${suffix}${owned}`);
+  return expressions.map((expression) =>
+    applyStateExpression(elementSelector, expression)
+  );
 };
 
 /**