@akinon/pz-theme 2.0.101-rc.0 → 2.0.102-beta.0

package/CHANGELOG.md

@@ -1,38 +1,20 @@
 # @akinon/pz-theme
 
-## 2.0.101-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.101-rc.0
-  - @akinon/theme-contract@2.0.101-rc.0
+## 2.0.102-beta.0
+
+### Patch Changes
+
+- Updated dependencies [cbbbfd757]
+  - @akinon/next@2.0.102-beta.0
+  - @akinon/theme-contract@2.0.102-beta.0
+
+## 2.0.101
+
+### Patch Changes
+
+- aa1754c0: ZERO-5018: Hold any state still for the designer, and apply every value one saves — a state can now be pinned on the element a root rule lands on (a block wrapper or a section band, not just a named part inside one), `overlay-open` and `docked` gained the page-level levers they have always been advertised with and never had, `opacity` authored in a state reaches the stylesheet instead of being dropped as a helper key, a state rule routed to a renderer's own root carries `!important` so it beats the inline styles that element already has, an unknown state name is refused rather than written into the element's own rule as an invalid declaration, part and state keys no longer leak into React inline styles, and the input block marks its control as its root so its border, background and focus ring reach the control rather than the transparent wrapper around it. The announce tells the editor which of these pins this build can perform, so an editor serving a storefront on an older theme keeps exactly the behaviour it has today.
+  - @akinon/next@2.0.101
+  - @akinon/theme-contract@2.0.101
 
 ## 2.0.100
 

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.101-rc.0",
+  "version": "2.0.102-beta.0",
   "license": "MIT",
   "main": "src/index.ts",
   "scripts": {
     "test": "jest"
   },
   "peerDependencies": {
-    "@akinon/next": "2.0.101-rc.0",
+    "@akinon/next": "2.0.102-beta.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/theme-contract": "2.0.101-rc.0",
+    "@akinon/theme-contract": "2.0.102-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.101-rc.0",
+    "@akinon/next": "2.0.102-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__/force-open.test.tsx

@@ -80,10 +80,35 @@ const blockProps = {
   currentBreakpoint: 'desktop'
 };
 
+/**
+ * The pin listener checks its origin like every other inbound listener in the
+ * package, so a bare same-window dispatch is refused. A localhost origin on a
+ * port that is not jsdom's own is trusted outside production without any
+ * allowlist — the same allowance local editor + storefront development runs on.
+ */
+const EDITOR_ORIGIN = 'http://localhost:4400';
+
+beforeAll(() => {
+  Object.defineProperty(window, 'parent', {
+    configurable: true,
+    value: { postMessage: () => undefined }
+  });
+});
+
+beforeEach(() => {
+  process.env.NEXT_PUBLIC_THEME_EDITOR_ORIGINS = EDITOR_ORIGIN;
+});
+
+afterEach(() => {
+  delete process.env.NEXT_PUBLIC_THEME_EDITOR_ORIGINS;
+});
+
 const pin = (blockId: string, partName: string, state: string | null) =>
   act(() => {
     window.dispatchEvent(
       new MessageEvent('message', {
+        origin: EDITOR_ORIGIN,
+        source: window.parent as Window,
         data: {
           type: 'PREVIEW_PART_STATE',
           data: { blockId, partName, state }
@@ -243,16 +268,17 @@ describe('SearchBoxBlock under force-open', () => {
     expect(document.querySelector('[data-search-backdrop]')).toBeNull();
     expect(document.querySelector('[data-part="body"]')).toBeNull();
     // And with no backdrop the panel makes no claim about the page behind it.
-    expect(
-      document.querySelector('[data-search-overlay]')
-    ).not.toHaveAttribute('aria-modal');
+    expect(document.querySelector('[data-search-overlay]')).not.toHaveAttribute(
+      'aria-modal'
+    );
   });
 
   it('moves focus into the field on open and hands it back on close', () => {
     renderBox(false, {});
 
-    const trigger = document.querySelector('[data-part="trigger"]') as
-      HTMLElement;
+    const trigger = document.querySelector(
+      '[data-part="trigger"]'
+    ) as HTMLElement;
     trigger.focus();
     fireEvent.click(trigger);
 
@@ -270,8 +296,9 @@ describe('SearchBoxBlock under force-open', () => {
   it('leaves focus on the icon when the composition turned it off', () => {
     renderBox(false, {}, { autoFocus: false });
 
-    const trigger = document.querySelector('[data-part="trigger"]') as
-      HTMLElement;
+    const trigger = document.querySelector(
+      '[data-part="trigger"]'
+    ) as HTMLElement;
     trigger.focus();
     fireEvent.click(trigger);
 
@@ -363,7 +390,9 @@ describe('MegaMenuBlock under force-open', () => {
     try {
       renderMenu(true, { forceOpen: true });
 
-      fireEvent.mouseLeave(document.querySelector('[data-mega-menu]') as Element);
+      fireEvent.mouseLeave(
+        document.querySelector('[data-mega-menu]') as Element
+      );
       act(() => {
         jest.advanceTimersByTime(2000);
       });
@@ -450,7 +479,10 @@ describe('NavMenuBlock under force-open', () => {
 });
 
 describe('HotspotBlock under force-open', () => {
-  const renderHotspot = (isDesigner: boolean, styles: Record<string, unknown>) =>
+  const renderHotspot = (
+    isDesigner: boolean,
+    styles: Record<string, unknown>
+  ) =>
     render(
       <HotspotBlock
         block={mkBlock('hotspot', { title: 'Hot Title' }, styles)}
@@ -468,9 +500,7 @@ describe('HotspotBlock under force-open', () => {
   it('leaves the popup mounted when the close button is clicked', () => {
     const { container } = renderHotspot(true, { forceOpen: true });
 
-    fireEvent.click(
-      container.querySelector('.text-gray-400') as Element
-    );
+    fireEvent.click(container.querySelector('.text-gray-400') as Element);
 
     expect(screen.getByText('Hot Title')).toBeInTheDocument();
   });
@@ -553,7 +583,9 @@ describe('PanelBlock under force-open', () => {
   it('leaves the panel mounted when the close button is clicked', () => {
     renderPanel(true, { forceOpen: true });
 
-    fireEvent.click(document.querySelector('[data-size-guide-close]') as Element);
+    fireEvent.click(
+      document.querySelector('[data-size-guide-close]') as Element
+    );
 
     expect(
       document.querySelector('[data-part="modal"][data-state="open"]')

package/src/blocks/input-block.tsx

@@ -3,6 +3,11 @@
 import React, { useEffect, useMemo, useState } from 'react';
 import { useLocalization } from '@akinon/next/hooks';
 import { getResponsiveValue, resolveThemeCssVariables } from '../utils';
+import {
+  isPartStyleKey,
+  isRootStateKey,
+  partAttrs
+} from '../utils/part-styles';
 import { BlockRendererProps } from './block-renderer-registry';
 import { useThemeSettingsContext } from '../theme-settings-context';
 
@@ -68,6 +73,13 @@ const InputBlock = ({
     }
 
     Object.keys(block.styles).forEach((key) => {
+      // Routing, not a property: `:focus/border-color` names this control in a
+      // state and is turned into a real rule by the generated stylesheet. Left
+      // in, it becomes the React style prop `:focus/borderColor` — a warning
+      // and dead weight. This loop builds its own object rather than calling
+      // `getCSSStyles`, so it has to say so itself.
+      if (isPartStyleKey(key) || isRootStateKey(key)) return;
+
       const styleValue = getResponsiveValue(
         block.styles[key],
         currentBreakpoint
@@ -114,6 +126,16 @@ const InputBlock = ({
       disabled={disabled}
       style={inputStyles}
       onChange={handleChange}
+      /*
+       * The block's REAL root, and the reason this type is in
+       * INNER_ROOT_BLOCK_TYPES: everything a designer sets on an Input — the
+       * border, the radius, the background, the focus ring — belongs to this
+       * control, not to the transparent div the designer wrapper draws around
+       * it. Marking it routes the generated root rule here instead of onto the
+       * wrapper, which is also what lets a state at the root match anything at
+       * all: a div is never focused and never disabled.
+       */
+      {...partAttrs('root')}
     />
   );
 };

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

@@ -157,9 +157,7 @@ describe('the chrome slot scroll signal', () => {
 
     unmount();
     expect(observers[0].disconnected).toBe(true);
-    expect(
-      document.querySelector('[data-scroll-state-sentinel]')
-    ).toBeNull();
+    expect(document.querySelector('[data-scroll-state-sentinel]')).toBeNull();
   });
 
   it('keeps the observer while one of several slots unmounts', () => {
@@ -188,11 +186,36 @@ describe('the chrome slot scroll signal', () => {
   });
 });
 
+/**
+ * The pin listener checks its origin like every other inbound listener in the
+ * package, so a bare same-window dispatch is refused. A localhost origin on a
+ * port that is not jsdom's own is trusted outside production without any
+ * allowlist — the same allowance local editor + storefront development runs on.
+ */
+const EDITOR_ORIGIN = 'http://localhost:4400';
+
+beforeAll(() => {
+  Object.defineProperty(window, 'parent', {
+    configurable: true,
+    value: { postMessage: () => undefined }
+  });
+});
+
+beforeEach(() => {
+  process.env.NEXT_PUBLIC_THEME_EDITOR_ORIGINS = EDITOR_ORIGIN;
+});
+
+afterEach(() => {
+  delete process.env.NEXT_PUBLIC_THEME_EDITOR_ORIGINS;
+});
+
 describe('previewing the scroll state in the designer', () => {
   const previewState = (state: string | null) =>
     fireEvent(
       window,
       new MessageEvent('message', {
+        origin: EDITOR_ORIGIN,
+        source: window.parent as Window,
         data: { type: 'PREVIEW_PART_STATE', data: { state } }
       })
     );

package/src/chrome/chrome-mode.ts

@@ -51,11 +51,45 @@ export const setChromeMode = (mode: ChromeMode): (() => void) => {
   const { body } = document;
   const previous = body.getAttribute(CHROME_MODE_ATTRIBUTE);
 
-  if (mode === null) body.removeAttribute(CHROME_MODE_ATTRIBUTE);
-  else body.setAttribute(CHROME_MODE_ATTRIBUTE, mode);
+  observedMode = mode;
+  writeChromeMode(pinnedMode ?? observedMode);
 
   return () => {
-    if (previous === null) body.removeAttribute(CHROME_MODE_ATTRIBUTE);
-    else body.setAttribute(CHROME_MODE_ATTRIBUTE, previous);
+    observedMode = previous === CHROME_MODE_DOCKED ? CHROME_MODE_DOCKED : null;
+    writeChromeMode(pinnedMode ?? observedMode);
   };
 };
+
+/**
+ * What the brand asked for, and what the designer asked to SEE instead.
+ *
+ * Kept apart because they answer different questions and change on different
+ * clocks. `setChromeMode` above is the brand's setter and its cleanup restores
+ * the mode as it stood when it was called — correct for a route transition,
+ * wrong for a pin, because the brand is free to change routes while a pin is
+ * held and the restore would silently write the pin away.
+ */
+let observedMode: ChromeMode = null;
+let pinnedMode: ChromeMode = null;
+
+const writeChromeMode = (mode: ChromeMode) => {
+  if (typeof document === 'undefined') return;
+
+  if (mode === null) document.body.removeAttribute(CHROME_MODE_ATTRIBUTE);
+  else document.body.setAttribute(CHROME_MODE_ATTRIBUTE, mode);
+};
+
+/**
+ * The designer's override, released with `null`.
+ *
+ * Which mode a route gets is the one thing a composition cannot ask about —
+ * only the brand knows which of its routes carry a hero — so this is also the
+ * only way a designer can ever SEE the docked half of the header they are
+ * styling. Mirrors `pinScrollState`: a layer over what the brand set, never a
+ * capture of it.
+ */
+export const pinChromeMode = (mode: ChromeMode): void => {
+  if (pinnedMode === mode) return;
+  pinnedMode = mode;
+  writeChromeMode(pinnedMode ?? observedMode);
+};

package/src/components/__tests__/part-state-preview-scope.test.tsx

@@ -67,10 +67,35 @@ const accordion = (id: string, inner?: unknown) => ({
   ]
 });
 
+/**
+ * The pin listener checks its origin like every other inbound listener in the
+ * package, so a bare same-window dispatch is refused. A localhost origin on a
+ * port that is not jsdom's own is trusted outside production without any
+ * allowlist — the same allowance local editor + storefront development runs on.
+ */
+const EDITOR_ORIGIN = 'http://localhost:4400';
+
+beforeAll(() => {
+  Object.defineProperty(window, 'parent', {
+    configurable: true,
+    value: { postMessage: () => undefined }
+  });
+});
+
+beforeEach(() => {
+  process.env.NEXT_PUBLIC_THEME_EDITOR_ORIGINS = EDITOR_ORIGIN;
+});
+
+afterEach(() => {
+  delete process.env.NEXT_PUBLIC_THEME_EDITOR_ORIGINS;
+});
+
 const pin = (blockId: string, partName: string, state: string | null) =>
   act(() => {
     window.dispatchEvent(
       new MessageEvent('message', {
+        origin: EDITOR_ORIGIN,
+        source: window.parent as Window,
         data: {
           type: 'PREVIEW_PART_STATE',
           data: { blockId, partName, state }

package/src/components/__tests__/root-state-pin.test.tsx

@@ -0,0 +1,219 @@
+import React from 'react';
+import { act, render } from '@testing-library/react';
+import { CHROME_MODE_ATTRIBUTE, setChromeMode } from '../../chrome/chrome-mode';
+import { OVERLAY_STATE_ATTRIBUTE } from '../../hooks/use-overlay';
+import ThemeBlock from '../../theme-block';
+import { PartStatePreview } from '../part-state-preview';
+
+/**
+ * Pinning a state on a ROOT, and on the page.
+ *
+ * The editor may now offer a state chip on any element that can really be in
+ * that state — a card that lights up under the pointer, a link that shows its
+ * focus ring — and a chip is only honest if the canvas can hold the state
+ * still while the colour is picked. Three of those pins did not exist:
+ *
+ *  - a root address stamped nothing at all, because the handler demanded a
+ *    part name and then searched the block's DESCENDANTS for it;
+ *  - `overlay-open` and `docked` stamped the element while their selectors
+ *    read `body`, so both chips have been decoration since they shipped.
+ */
+
+const EDITOR_ORIGIN = 'http://localhost:4400';
+
+beforeAll(() => {
+  Object.defineProperty(window, 'parent', {
+    configurable: true,
+    value: { postMessage: () => undefined }
+  });
+});
+
+const pin = (blockId: string, partName: string, state: string | null): void => {
+  act(() => {
+    window.dispatchEvent(
+      new MessageEvent('message', {
+        origin: EDITOR_ORIGIN,
+        source: window.parent as Window,
+        data: {
+          type: 'PREVIEW_PART_STATE',
+          data: { blockId, partName, state }
+        }
+      })
+    );
+  });
+};
+
+const text = (id: string) => ({
+  id,
+  type: 'text',
+  label: 'Text',
+  value: '<p>copy</p>',
+  properties: {},
+  styles: {},
+  order: 0,
+  hidden: false
+});
+
+const group = (id: string, children: unknown[]) => ({
+  id,
+  type: 'group',
+  label: 'Group',
+  properties: {},
+  styles: {},
+  order: 0,
+  hidden: false,
+  blocks: children
+});
+
+const stateOf = (root: HTMLElement, id: string): string | null =>
+  root
+    .querySelector<HTMLElement>(`[data-block-id="${id}"]`)
+    ?.getAttribute('data-state') ?? null;
+
+const renderCanvas = (block: unknown) =>
+  render(
+    <>
+      <PartStatePreview isDesigner />
+      <ThemeBlock block={block as never} isDesigner />
+    </>
+  );
+
+afterEach(() => {
+  document.body.removeAttribute(OVERLAY_STATE_ATTRIBUTE);
+  document.body.removeAttribute(CHROME_MODE_ATTRIBUTE);
+});
+
+describe('pinning a state on the element the root rule lands on', () => {
+  it('stamps the block wrapper when no part is named', () => {
+    const { container } = renderCanvas(group('grp', [text('grp-copy')]));
+
+    pin('grp', '', 'hover');
+
+    expect(stateOf(container, 'grp')).toBe('hover');
+  });
+
+  it('releases it again', () => {
+    const { container } = renderCanvas(group('grp', [text('grp-copy')]));
+
+    pin('grp', '', 'hover');
+    pin('grp', '', null);
+
+    expect(stateOf(container, 'grp')).toBeNull();
+  });
+
+  it('swaps one state for another without leaving the first behind', () => {
+    const { container } = renderCanvas(group('grp', [text('grp-copy')]));
+
+    pin('grp', '', 'hover');
+    pin('grp', '', 'focus');
+
+    expect(stateOf(container, 'grp')).toBe('focus');
+  });
+
+  // The wrapper is the element the rule names, and a block inside it marks a
+  // wrapper of its own. Stamping both would light up rules that belong to the
+  // nested block.
+  it('stamps only the addressed block, not the ones inside it', () => {
+    const { container } = renderCanvas(
+      group('outer', [group('inner', [text('inner-copy')])])
+    );
+
+    pin('outer', '', 'hover');
+
+    expect(stateOf(container, 'outer')).toBe('hover');
+    expect(stateOf(container, 'inner')).toBeNull();
+  });
+
+  it('does nothing for an address the canvas cannot resolve', () => {
+    const { container } = renderCanvas(group('grp', [text('grp-copy')]));
+
+    pin('gone', '', 'hover');
+
+    expect(container.querySelectorAll('[data-state]')).toHaveLength(0);
+  });
+});
+
+/**
+ * The two page states. Neither is a fact about the element: both are matched
+ * through an attribute on `body`, so stamping the element lights nothing up.
+ */
+describe('pinning a state that belongs to the page', () => {
+  it('holds the overlay state on the body', () => {
+    renderCanvas(group('grp', [text('grp-copy')]));
+
+    pin('', '', 'overlay-open');
+
+    expect(document.body.getAttribute(OVERLAY_STATE_ATTRIBUTE)).toBe('open');
+  });
+
+  it('holds the docked mode on the body', () => {
+    renderCanvas(group('grp', [text('grp-copy')]));
+
+    pin('', '', 'docked');
+
+    expect(document.body.getAttribute(CHROME_MODE_ATTRIBUTE)).toBe('docked');
+  });
+
+  it('releases one page state when another is asked for', () => {
+    renderCanvas(group('grp', [text('grp-copy')]));
+
+    pin('', '', 'overlay-open');
+    pin('', '', 'docked');
+
+    expect(document.body.getAttribute(OVERLAY_STATE_ATTRIBUTE)).toBeNull();
+    expect(document.body.getAttribute(CHROME_MODE_ATTRIBUTE)).toBe('docked');
+  });
+
+  it('releases a page state when an element state is asked for', () => {
+    const { container } = renderCanvas(group('grp', [text('grp-copy')]));
+
+    pin('', '', 'docked');
+    pin('grp', '', 'hover');
+
+    expect(document.body.getAttribute(CHROME_MODE_ATTRIBUTE)).toBeNull();
+    expect(stateOf(container, 'grp')).toBe('hover');
+  });
+
+  // The brand owns the mode; the pin only layers over it. Restoring what the
+  // pin captured would write away a route change made while it was held.
+  it('gives the brand its mode back when the pin is released', () => {
+    renderCanvas(group('grp', [text('grp-copy')]));
+    setChromeMode('docked');
+
+    pin('', '', 'overlay-open');
+    pin('', '', null);
+
+    expect(document.body.getAttribute(CHROME_MODE_ATTRIBUTE)).toBe('docked');
+    setChromeMode(null);
+  });
+
+  it('leaves the page clean when the canvas unmounts', () => {
+    const view = renderCanvas(group('grp', [text('grp-copy')]));
+
+    pin('', '', 'overlay-open');
+    view.unmount();
+
+    expect(document.body.getAttribute(OVERLAY_STATE_ATTRIBUTE)).toBeNull();
+  });
+});
+
+describe('an untrusted frame', () => {
+  it('cannot pin anything', () => {
+    const { container } = renderCanvas(group('grp', [text('grp-copy')]));
+
+    act(() => {
+      window.dispatchEvent(
+        new MessageEvent('message', {
+          origin: 'http://evil.example',
+          source: window.parent as Window,
+          data: {
+            type: 'PREVIEW_PART_STATE',
+            data: { blockId: 'grp', partName: '', state: 'hover' }
+          }
+        })
+      );
+    });
+
+    expect(stateOf(container, 'grp')).toBeNull();
+  });
+});

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

@@ -2,7 +2,10 @@
 
 import { useEffect } from 'react';
 
+import { CHROME_MODE_DOCKED, pinChromeMode } from '../chrome/chrome-mode';
 import { SCROLL_STYLE_STATE, pinScrollState } from '../chrome/scroll-state';
+import { isTrustedEditorEvent } from '../editor-bridge';
+import { OVERLAY_PIN_STATE, pinOverlayState } from '../hooks/use-overlay';
 
 /**
  * Pins a part's state open while the designer styles it.
@@ -43,34 +46,92 @@ export const PartStatePreview = ({ isDesigner }: { isDesigner: boolean }) => {
         });
     };
 
+    const releasePagePins = () => {
+      pinScrollState(null);
+      pinOverlayState(false);
+      pinChromeMode(null);
+    };
+
     const handleMessage = (event: MessageEvent) => {
+      // The only designer listener in this package that did not check. Same
+      // guard as every other inbound message: a wrong origin, or a protocol the
+      // other side has moved past, is refused rather than acted on.
+      if (!isTrustedEditorEvent(event)) return;
       if (event.data?.type !== 'PREVIEW_PART_STATE') return;
 
       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.
+      // A PAGE state is not a fact about the element. `scrolled` is matched
+      // through `data-scroll-state` on the chrome slot; `overlay-open` and
+      // `docked` through attributes on `body`. Stamping any of the three onto
+      // the element lights nothing up — which is exactly how two of the three
+      // chips the editor has been showing came to be decoration. Each now has a
+      // lever of its own, and every message releases the ones it is not asking
+      // for, so the canvas is never left frozen in a state the designer has
+      // moved on from.
+      //
+      // These branches stay ABOVE the address check, as `scrolled` always has:
+      // a page state needs no element, which is also why a root chip appeared
+      // to work for `scrolled` while sending an empty address.
       if (state === SCROLL_STYLE_STATE) {
+        pinOverlayState(false);
+        pinChromeMode(null);
         pinScrollState('scrolled');
         return;
       }
 
-      pinScrollState(null);
+      if (state === OVERLAY_PIN_STATE) {
+        pinScrollState(null);
+        pinChromeMode(null);
+        pinOverlayState(true);
+        return;
+      }
 
-      if (!blockId || !partName || !state) return;
+      if (state === CHROME_MODE_DOCKED) {
+        pinScrollState(null);
+        pinOverlayState(false);
+        pinChromeMode(CHROME_MODE_DOCKED);
+        return;
+      }
 
-      const block = document.querySelector<HTMLElement>(
-        `[data-block-id="${CSS.escape(String(blockId))}"]`
+      releasePagePins();
+
+      if (!blockId || !state) return;
+
+      const id = CSS.escape(String(blockId));
+      // A block wrapper or a section band: the generated root-state rule names
+      // one element by id either way, and a section owns parts too. Resolving
+      // both here is what lets the editor address a section without the message
+      // growing a field — the payload already carries everything it needs.
+      const host = document.querySelector<HTMLElement>(
+        `[data-block-id="${id}"], [data-section-id="${id}"]`
       );
-      if (!block) return;
+      if (!host) return;
+
+      const pinOn = (element: HTMLElement) => {
+        const existing = element.getAttribute('data-state') || '';
+        // The pinned token is remembered, not the whole value: the renderer
+        // is free to change the element's real state while it is pinned.
+        element.setAttribute(PREVIEW_ATTRIBUTE, String(state));
+        element.setAttribute(
+          'data-state',
+          existing ? `${existing} ${state}` : String(state)
+        );
+      };
+
+      // No part named: the ROOT was addressed, and a root-state rule lands on
+      // this element itself. A block whose renderer draws its own root is
+      // addressed as the part "root" instead — that is where the generator
+      // routes the rule — and the branch below already reaches exactly that
+      // element, ownership guard included.
+      if (!partName) {
+        pinOn(host);
+        return;
+      }
 
       Array.from(
-        block.querySelectorAll<HTMLElement>(
+        host.querySelectorAll<HTMLElement>(
           `[data-part="${CSS.escape(String(partName))}"]`
         )
       )
@@ -78,27 +139,24 @@ export const PartStatePreview = ({ isDesigner }: { isDesigner: boolean }) => {
         // search also finds the identically-named part of a block nested
         // inside this one. A part belongs to its closest `[data-block-id]`
         // ancestor — the same rule a click already uses to decide which part
-        // it selected (hooks/use-designer-features). Stamping a nested block's
-        // part would fire that block's own state rules and show the author a
-        // canvas that disagrees with the storefront.
-        .filter((element) => element.closest('[data-block-id]') === block)
-        .forEach((element) => {
-          const existing = element.getAttribute('data-state') || '';
-          // The pinned token is remembered, not the whole value: the renderer
-          // is free to change the element's real state while it is pinned.
-          element.setAttribute(PREVIEW_ATTRIBUTE, String(state));
-          element.setAttribute(
-            'data-state',
-            existing ? `${existing} ${state}` : String(state)
-          );
-        });
+        // it selected (hooks/use-designer-features). A SECTION's own part is
+        // one with no block between it and the band; both readings are the
+        // guard the generator already emits.
+        .filter((element) => {
+          const owner = element.closest('[data-block-id]');
+          return owner === host || !(owner && host.contains(owner));
+        })
+        .forEach(pinOn);
     };
 
     window.addEventListener('message', handleMessage);
     return () => {
       window.removeEventListener('message', handleMessage);
       clear();
-      pinScrollState(null);
+      // All three, not just the scroll pin: a module-level attribute that
+      // outlived the editor session would follow the user into the storefront
+      // they browse in that same tab.
+      releasePagePins();
     };
   }, [isDesigner]);
 

package/src/hooks/use-overlay.ts

@@ -67,19 +67,53 @@ const stackListeners = new Set<() => void>();
 export const OVERLAY_STATE_ATTRIBUTE = 'data-overlay-state';
 export const OVERLAY_STYLE_STATE = 'open';
 
+/**
+ * The STYLE-STATE name this signal answers to, which is NOT the attribute value.
+ *
+ * `data-overlay-state="open"` is what the selector matches; `overlay-open` is
+ * what the style key says and what the editor puts on the wire. They have
+ * always been two different strings, and a pin that compared against
+ * OVERLAY_STYLE_STATE would look right and never fire once.
+ */
+export const OVERLAY_PIN_STATE = 'overlay-open';
+
+/**
+ * The designer's override of the overlay state.
+ *
+ * A layer OVER the stack rather than a fake push, exactly as
+ * `chrome/scroll-state.tsx` layers a pinned state over its observer. A fake
+ * push would be popped by the next real overlay to close, and a pin a shopper
+ * interaction can cancel is worse than no pin at all.
+ *
+ * It has to exist because the canvas can never reach this state by itself: the
+ * push effect is gated on `active = open && !isDesigner`, so a panel
+ * force-opened for styling pushes nothing. A designer asking to see "while a
+ * panel is open" is therefore the only way this attribute is ever set in the
+ * editor.
+ */
+let pinnedOverlay = false;
+
 const syncOverlayStateAttribute = () => {
   if (typeof document === 'undefined') return;
 
   // Driven off the stack rather than off each open/close call: two overlays
   // closing in either order must leave exactly one attribute state behind, and
-  // the stack is already the thing that knows whether anything is left.
-  if (overlayStack.length > 0) {
+  // the stack is already the thing that knows whether anything is left. The
+  // designer pin rides on top of it and never disturbs it, so releasing the pin
+  // restores whatever the page was really doing.
+  if (pinnedOverlay || overlayStack.length > 0) {
     document.body.setAttribute(OVERLAY_STATE_ATTRIBUTE, OVERLAY_STYLE_STATE);
   } else {
     document.body.removeAttribute(OVERLAY_STATE_ATTRIBUTE);
   }
 };
 
+export const pinOverlayState = (pinned: boolean): void => {
+  if (pinnedOverlay === pinned) return;
+  pinnedOverlay = pinned;
+  syncOverlayStateAttribute();
+};
+
 const notifyStack = () => {
   syncOverlayStateAttribute();
   stackListeners.forEach((listener) => listener());
@@ -606,7 +640,8 @@ export function useOverlay<T extends HTMLElement = HTMLElement>(
     return () => document.removeEventListener('keydown', handleKeyDown);
   }, [active, closeOnEscape, isTopmost]);
 
-  const ariaModal = active && modal && claimsPage ? ('true' as const) : undefined;
+  const ariaModal =
+    active && modal && claimsPage ? ('true' as const) : undefined;
 
   const overlayProps = useMemo(
     () => ({ ref: panelRef, 'aria-modal': ariaModal }),

package/src/placeholder-registry.ts

@@ -1,5 +1,9 @@
 import { getCatalogVendor, getCustomCatalog } from './custom/catalog';
 import { getCustomSectionCatalog } from './custom/section-catalog';
+import {
+  STATE_PIN_CAPABILITIES,
+  type StatePinCapability
+} from './state-pin-capabilities';
 import type { CustomSectionCatalog } from './custom/section-types';
 import type { CustomCatalog } from './custom/types';
 import { isTrustedEditorEvent, postToEditor } from './editor-bridge';
@@ -52,6 +56,22 @@ interface PlaceholdersAvailablePayload {
    * with it.
    */
   customSections?: CustomSectionCatalog;
+
+  /**
+   * Which kinds of state pin THIS build can perform, so the editor can offer
+   * exactly the state chips this storefront is able to hold still.
+   *
+   * Additive, and deliberately a list of capability NAMES rather than a version
+   * number: the editor must not have to know which release added what, and one
+   * Omnitron serves channels whose storefronts pin their own theme version.
+   *
+   * A build that does not send it is read as the baseline every shipped version
+   * can do — pinning the scroll state — so a storefront that has not upgraded
+   * keeps exactly the chip row it has today rather than losing it to a
+   * handshake it has never heard of. `scroll` is therefore not listed here:
+   * listing it would make an old storefront look LESS capable than it is.
+   */
+  statePins?: StatePinCapability[];
 }
 
 const isFramed = (): boolean =>
@@ -103,6 +123,8 @@ const flush = () => {
 
     const customSections = getCustomSectionCatalog(getCatalogVendor());
     if (customSections) data.customSections = customSections;
+
+    data.statePins = STATE_PIN_CAPABILITIES;
   }
 
   postToEditor({

package/src/state-pin-capabilities.ts

@@ -0,0 +1,28 @@
+/**
+ * What this build can hold still for a designer, announced to the editor.
+ *
+ * The editor offers a state chip only where it can also SHOW the state, so it
+ * has to be told what the storefront in front of it is able to pin — one
+ * Omnitron serves channels whose storefronts pin their own theme version, and
+ * "the repo has it" is not a fact the editor may assume.
+ *
+ *  - `element`     a state is stamped on the addressed element, a block wrapper
+ *                  and a section band included.
+ *  - `overlay`     `overlay-open` is held on the page.
+ *  - `chrome-mode` `docked` is held on the page.
+ *
+ * `scroll` is absent on purpose: every version that ever shipped could do it
+ * and the editor assumes it, so listing it would make an old storefront look
+ * less capable than it is.
+ *
+ * Its own module rather than a constant beside the component that implements
+ * it: the placeholder registry announces this, and it must not have to pull a
+ * client component in to say one list of strings.
+ */
+export type StatePinCapability = 'element' | 'overlay' | 'chrome-mode';
+
+export const STATE_PIN_CAPABILITIES: readonly StatePinCapability[] = [
+  'element',
+  'overlay',
+  'chrome-mode'
+];

package/src/utils/__tests__/inner-root-styles.test.tsx

@@ -37,7 +37,7 @@ const blockOf = (overrides: Partial<Block>): Block =>
     styles: {},
     blocks: [],
     ...overrides
-  }) as Block;
+  } as Block);
 
 const sectionWith = (block: Partial<Block>) =>
   [
@@ -75,9 +75,10 @@ describe('a renderer that draws its own root', () => {
     expect(css).not.toContain('[data-part="root"]');
   });
 
-  it('covers the three renderers that mark their root', () => {
+  it('covers exactly the renderers that mark their root', () => {
     expect([...INNER_ROOT_BLOCK_TYPES].sort()).toEqual([
       'button',
+      'input',
       'link',
       'text'
     ]);

package/src/utils/__tests__/root-state-values.test.ts

@@ -0,0 +1,158 @@
+import { generateThemeCSS, getCSSStyles } from '../index';
+
+/**
+ * The values a root state saves, and where they are allowed to end up.
+ *
+ * A root state used to be reachable on a chrome band and nowhere else, so three
+ * holes in this path stayed dormant. Offering states on every element opens all
+ * three at once: an authored value that produces no declaration, a routing key
+ * turned into a React style prop, and an unknown state name written into the
+ * element's own rule as junk.
+ */
+
+const block = (id: string, styles: Record<string, unknown>) => ({
+  id,
+  type: 'group',
+  label: 'Group',
+  properties: {},
+  styles,
+  order: 0,
+  hidden: false,
+  blocks: []
+});
+
+const section = (
+  id: string,
+  styles: Record<string, unknown>,
+  blocks: unknown[] = []
+) => ({
+  id,
+  type: 'custom',
+  label: 'Section',
+  properties: {},
+  styles,
+  order: 0,
+  blocks
+});
+
+const css = (styles: Record<string, unknown>) =>
+  generateThemeCSS([section('sec', {}, [block('blk', styles)]) as never]);
+
+describe('a value authored in a state', () => {
+  /**
+   * `opacity` is a HELPER key on a block root — it feeds the hover/alpha maths
+   * rather than being emitted. In a STATE bucket it is a real CSS property, as
+   * it has always been on a part, and the panel offers a slider for it.
+   */
+  it('emits opacity, which the panel has always offered and the sheet dropped', () => {
+    expect(css({ ':hover/opacity': '50' })).toContain('opacity');
+  });
+
+  it('emits an ordinary property in the same bucket', () => {
+    expect(css({ ':hover/background-color': '#00ff00' })).toContain(
+      '[data-block-id="blk"]:hover'
+    );
+  });
+
+  // The alternative selector IS the pin hook: the canvas writes the token onto
+  // the element and the same rule applies, which is what lets the author see
+  // what they are picking.
+  it('matches the pinned token beside the real pseudo-class', () => {
+    expect(css({ ':hover/background-color': '#00ff00' })).toContain(
+      '[data-block-id="blk"][data-state~="hover"]'
+    );
+  });
+});
+
+describe('the full CSS surface in a state', () => {
+  /**
+   * The editor offers every CSS property inside a transient state, on the
+   * grounds that nothing written into a hover outlives the hover. That is only
+   * true if the generator writes them — a property it dropped would be a
+   * control that saves and does nothing.
+   */
+  it.each([
+    'clip-path',
+    'backdrop-filter',
+    'mix-blend-mode',
+    'letter-spacing',
+    'z-index'
+  ])('emits %s authored in a state', (property) => {
+    const sheet = css({ [`:hover/${property}`]: 'inherit' });
+
+    expect(sheet).toContain('[data-block-id="blk"]:hover');
+    expect(sheet).toContain(`${property}: inherit`);
+  });
+});
+
+describe('a state name this build does not know', () => {
+  it('is refused rather than written into the element rule', () => {
+    // `:visited` is the deliberate absence: a link really has it, but the
+    // preview cannot put an element into it, so it is refused rather than
+    // offered against a canvas that can never show it.
+    const sheet = css({
+      ':visited/color': '#123456',
+      color: '#000000'
+    });
+
+    expect(sheet).not.toContain('visited');
+    // The rest of the element's rule is untouched.
+    expect(sheet).toContain('color: #000000');
+  });
+
+  it('is refused for a section band too', () => {
+    const sheet = generateThemeCSS([
+      section('sec', { ':visited/color': '#123456' }) as never
+    ]);
+
+    expect(sheet).not.toContain(':visited/color');
+  });
+});
+
+describe('a routing key never becomes an inline style', () => {
+  /**
+   * `panel/color` means "the panel, in the base state" and `:hover/color` means
+   * "this element, while hovered". Both become real rules against selectors an
+   * inline object cannot express; passed through they are React style props
+   * named `panel/color` and `:hover/color` — a dev warning and dead weight, and
+   * on the inner-root path a token-valued one would be inlined onto the exact
+   * element the generated rule targets.
+   */
+  it('drops root-state and part keys, and keeps the real ones', () => {
+    expect(
+      getCSSStyles({
+        ':hover/background-color': '#00ff00',
+        'panel/color': '#ff0000',
+        'background-color': '#0000ff'
+      })
+      // Composited through the background-opacity maths, as any real property
+      // on this path is — the point here is that it is the ONLY key left.
+    ).toEqual({ backgroundColor: 'rgba(0, 0, 255, 1)' });
+  });
+
+  it('drops an unknown state key as well, since it is still routing', () => {
+    expect(getCSSStyles({ ':visited/color': '#123456' })).toEqual({});
+  });
+});
+
+/**
+ * The focus a CONTAINER has.
+ *
+ * A wrapper is not focusable, so `focus` never matches it, and the input's own
+ * `focus` paints the control rather than the box around it. This is the one
+ * state a container can genuinely be in that no tag gives it — and the
+ * commonest form pattern there is.
+ */
+describe('a container whose contents are focused', () => {
+  it('emits the real pseudo-class', () => {
+    expect(css({ ':focus-within/border-color': '#00ff00' })).toContain(
+      '[data-block-id="blk"]:focus-within'
+    );
+  });
+
+  it('matches the pinned token too, so the canvas can hold it', () => {
+    expect(css({ ':focus-within/border-color': '#00ff00' })).toContain(
+      '[data-block-id="blk"][data-state~="focus-within"]'
+    );
+  });
+});

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

@@ -23,7 +23,11 @@ import type { Section } from '../../theme-section';
 
 const SLOT = '[data-scroll-state~="scrolled"]';
 
-const section = (id: string, styles: Record<string, unknown>, blocks: unknown[] = []) =>
+const section = (
+  id: string,
+  styles: Record<string, unknown>,
+  blocks: unknown[] = []
+) =>
   ({
     id,
     type: 'custom',
@@ -32,9 +36,13 @@ const section = (id: string, styles: Record<string, unknown>, blocks: unknown[]
     order: 0,
     hidden: false,
     blocks
-  }) as unknown as Section;
+  } as unknown as Section);
 
-const block = (id: string, styles: Record<string, unknown>, type = 'group') => ({
+const block = (
+  id: string,
+  styles: Record<string, unknown>,
+  type = 'group'
+) => ({
   id,
   type,
   label: 'Block',
@@ -177,13 +185,30 @@ describe('the block and section root rules', () => {
     // or it would style the transparent designer wrapper the block sits in.
     // Ownership guard included: a routed root rule is a descendant selector,
     // and a nested block marks a root of its own.
+    //
+    // `!important` on this path only, exactly as a part rule carries it and for
+    // the identical reason: the routed element is the one the renderer inlines
+    // its own styles onto, and inline outranks any stylesheet. A stock button
+    // is seeded a background colour that way, so without this a state colour
+    // would be written, saved, shown in the panel and never seen.
     expect(css).toContain(
       `${SLOT} [data-block-id="blk-1"] [data-part="root"]` +
         `:not(:where([data-block-id="blk-1"] [data-block-id] *))` +
-        ` {\n  color: #111111;\n}`
+        ` {\n  color: #111111 !important;\n}`
     );
   });
 
+  it('leaves the wrapper path unforced, so custom CSS can still win', () => {
+    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}`
+    );
+    expect(css).not.toContain('color: #111111 !important');
+  });
+
   it('never emits the raw key as a declaration', () => {
     const css = generateThemeCSS([
       section('sec-1', { ':scrolled/background-color': '#ffffff' })

package/src/utils/index.ts

@@ -9,6 +9,8 @@ import {
   buildInnerRootSelectors,
   buildPartSelectors,
   buildRootStateSelectors,
+  isPartStyleKey,
+  isRootStateKey,
   splitPartStyles
 } from './part-styles';
 import { buildCustomCss, buildPartCustomCss } from './custom-css';
@@ -172,8 +174,7 @@ export const colorToRgba = (color: string, alpha: number): string | null => {
     const g = Number(commaRgb[2]);
     const b = Number(commaRgb[3]);
     if ([r, g, b].some((v) => Number.isNaN(v))) return null;
-    const authored =
-      commaRgb[4] !== undefined ? Number(commaRgb[4]) : 1;
+    const authored = commaRgb[4] !== undefined ? Number(commaRgb[4]) : 1;
     const effective = Number.isNaN(authored) ? alpha : authored * alpha;
     return `rgba(${r}, ${g}, ${b}, ${effective})`;
   }
@@ -545,7 +546,12 @@ const resolveSectionMaxWidthTokens = <T extends Record<string, unknown>>(
 export const INNER_ROOT_BLOCK_TYPES: ReadonlySet<string> = new Set([
   'text',
   'link',
-  'button'
+  'button',
+  // The block's root IS a form control. Until this, its styles landed twice —
+  // on the wrapper through the sheet and on the control through the renderer's
+  // own inline styles — and no state at its root could match anything, because
+  // the element the rule reached was a div.
+  'input'
 ]);
 
 /**
@@ -668,6 +674,21 @@ export const getCSSStyles = (
     : null;
 
   Object.keys(styles).forEach((key) => {
+    // Part and root-state keys carry ROUTING, not a property: `panel/color`
+    // means "the panel, in the base state" and `:hover/background-color` means
+    // "this element, while hovered". Both are turned into real rules by
+    // `generatePartCSS` / `generateRootStateCSS` against selectors an inline
+    // object cannot express. Passed through, they become React style props
+    // named `panel/color` and `:hover/backgroundColor` — a dev warning, dead
+    // weight, and on the inner-root path a token-valued one would be inlined
+    // onto the exact element the generated rule targets.
+    //
+    // Harmless until now only because a root-state key could be authored on a
+    // chrome band and nowhere else. It is checked here rather than in each of
+    // the renderers that inline this output, because this is where they all
+    // converge.
+    if (isPartStyleKey(key) || isRootStateKey(key)) return;
+
     const value = getResponsiveValue(styles[key], breakpoint);
     if (value === undefined || value === null) return;
 
@@ -1439,13 +1460,22 @@ export const generatePartCSS = (
 /**
  * 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.
+ * `!important` ONLY on the inner-root path, and the split is the whole point.
+ * A block wrapper and a section band carry no renderer inline styles, so the
+ * only rule a state there has to beat is the plain root rule emitted a few
+ * lines earlier — which it already beats on specificity, a state selector
+ * being strictly longer. Forcing it would buy nothing and would cost the
+ * custom-CSS hatch its `!important`, the designer's documented way to win an
+ * argument with a generated rule.
+ *
+ * The INNER root is the opposite case and always was. That element carries
+ * `getInnerRootInlineStyles()` — every token-carrying value, plus `color` once
+ * text-opacity has been composited into it — and inline outranks any
+ * stylesheet. `mergeButtonStylesWithThemeDefaults` seeds a background colour
+ * onto every button the editor creates, so without this a hover background on
+ * a stock button was authored against an inline style it could never beat. It
+ * is the same trade `generatePartCSS` has made since it was written, for the
+ * identical reason, and the same replacement is used so the two cannot drift.
  */
 const generateRootStateCSS = (
   elementSelector: string,
@@ -1471,11 +1501,29 @@ const generateRootStateCSS = (
       : buildRootStateSelectors(elementSelector, bucket.state);
     if (selectors.length === 0) return;
 
-    css += generateElementCSS(
+    const rules = generateElementCSS(
       selectors.join(',\n'),
       bucket.styles as ResponsiveStyles,
-      targetBreakpoint
+      targetBreakpoint,
+      // `opacity` is a HELPER key on a block ROOT — it feeds the hover/alpha
+      // maths rather than being emitted — so without this flag every
+      // `:<state>/opacity` the editor offers is dropped on the floor. A state
+      // BUCKET has no such helper: there it is a real CSS property, exactly as
+      // it is on a part, which is why `generatePartCSS` has always passed this.
+      { treatHelperKeysAsCss: true }
     );
+
+    if (!rules) return;
+
+    css += targetsInnerRoot
+      ? rules.replace(
+          /^(\s*)([a-z-]+):\s*([^;\n]+);/gm,
+          (line, indent, property, value) =>
+            value.includes('!important')
+              ? line
+              : `${indent}${property}: ${value} !important;`
+        )
+      : rules;
   });
 
   return css;

package/src/utils/part-styles.ts

@@ -39,6 +39,22 @@
 const STATE_SELECTORS: Record<string, string[]> = {
   hover: [':hover', '[data-state~="hover"]'],
   focus: [':focus-visible', ':focus', '[data-state~="focus"]'],
+  /**
+   * The focus a CONTAINER has: something inside it is focused.
+   *
+   * The one state a wrapper can genuinely be in that no tag gives it, and the
+   * commonest form control pattern there is — a field whose box lights up while
+   * the input inside it has the caret. Without it a Group holding an Input, an
+   * auth field and a card wrapping a link were all unstyleable on focus: the
+   * wrapper is not focusable, so `focus` never matches it, and the input's own
+   * `focus` paints the control rather than the box around it.
+   *
+   * It was left out once on the grounds that the renderer had no entry for it,
+   * which was true and is a circle. The pin token is what makes it offerable
+   * rather than merely emittable: `:focus-within` cannot be held while the
+   * designer reaches for a colour picker, exactly as `:hover` cannot.
+   */
+  'focus-within': [':focus-within', '[data-state~="focus-within"]'],
   active: [':active', '[data-state~="active"]'],
   // Native controls, ARIA and our own data-state all mean the same thing here,
   // so each is covered rather than forcing renderers into one convention.
@@ -213,6 +229,18 @@ export const parsePartStyleKey = (key: string): ParsedPartKey | null => {
 export const isPartStyleKey = (key: string): boolean =>
   parsePartStyleKey(key) !== null;
 
+/**
+ * Whether the key addresses this element IN A STATE, known state or not.
+ *
+ * Deliberately the marker rather than `parseRootStateKey`, because the callers
+ * are asking "is this routing?" and not "can I render it?". An unknown state
+ * name is still routing — it is simply routing nobody can honour — and the one
+ * thing it must never become is a declaration or a React style prop. No real
+ * CSS property begins with the marker, so nothing legitimate answers yes.
+ */
+export const isRootStateKey = (key: string): boolean =>
+  Boolean(key) && key[0] === ROOT_STATE_MARKER;
+
 /** Builds the style key a descriptor writes into. */
 export const buildPartStyleKey = (
   part: string,
@@ -337,6 +365,15 @@ export const splitPartStyles = (
       return;
     }
 
+    // A key that LOOKS like a root state and is not one: an unknown state name,
+    // reaching here from a brand catalog this build does not know, from an
+    // editor that has shipped ahead of this storefront, or from a hand-edited
+    // theme. Left on the root bucket it is emitted as the declaration
+    // `:focus-within/color: #123456` inside the element's BASE rule — invalid,
+    // silently dropped by the browser, invisible to everyone. Dropped here it
+    // is simply not written.
+    if (isRootStateKey(key)) return;
+
     const parsed = parsePartStyleKey(key);
 
     if (!parsed) {