@akinon/pz-theme 2.0.78-rc.2 → 2.0.79-beta.0

package/src/theme-section.tsx

@@ -6,6 +6,7 @@ import { twMerge } from 'tailwind-merge';
 import clsx from 'clsx';
 import { useEffect, useMemo, useRef } from 'react';
 import SectionWrapper from './sections/section-wrapper';
+import { resolveSectionPartName } from './hooks/use-designer-features';
 import sectionRendererRegistry from './sections/section-renderer-registry';
 import {
   buildIteratorBlock,
@@ -22,6 +23,10 @@ import {
 import { safeDeepClone } from './utils/safe-clone';
 
 import { isTrustedEditorEvent, postToEditor } from './editor-bridge';
+import { DesignerPlaceholder } from './blocks/product-block-utils';
+import { CustomSectionHost } from './custom/section-host';
+import { getCustomSectionDefinition } from './custom/section-definitions';
+import { isCustomThemeType } from './custom/types';
 import { ThemeSectionDataProvider } from './theme-section-data-context';
 import { PreviewToEditorMessageType } from '@akinon/theme-contract';
 export interface Section {
@@ -159,12 +164,22 @@ export default function ThemeSection({
       e.stopPropagation();
       onSelect(effectiveSection.id);
 
+      // The same helper the wrapper uses. A generic section carries no
+      // developer-authored parts today, but the two paths posting different
+      // payload shapes for one message is how a receiver ends up written
+      // against whichever one its author happened to read.
+      const partName = resolveSectionPartName(
+        e.target as Element | null,
+        e.currentTarget as Element
+      );
+
       if (window.parent) {
         postToEditor({
           type: 'SELECT_SECTION',
           data: {
             placeholderId,
-            sectionId: effectiveSection.id
+            sectionId: effectiveSection.id,
+            ...(partName ? { partName } : {})
           }
         });
       }
@@ -456,6 +471,135 @@ export default function ThemeSection({
     return null;
   };
 
+  // A DEVELOPER-AUTHORED SECTION WINS OVER EVERYTHING BELOW, including the tab
+  // hatch two lines down. That hatch claims any section containing a `tab`
+  // block, and a custom section's regions may legitimately contain one — a tab
+  // strip inside a brand's own product page is ordinary content, and letting
+  // TabsSection take the whole section over it would replace the brand's markup
+  // with a tab strip and nothing would say why.
+  //
+  // It renders inside the SAME `SectionWrapper` a registered renderer gets.
+  // That wrapper is what supplies `<section data-section-id>`, the designer
+  // outline, the action toolbar and the `data-section-content` element the
+  // content-width rule targets — i.e. it is exactly what gives a custom section
+  // the full section root panel, which is the whole reason this is a section
+  // rather than a block.
+  //
+  // The blocks inside it get the SAME resolution the generic loop gives its own
+  // top-level blocks. This branch used to skip it on the reasoning that no
+  // registered renderer resolves bindings either — which read the situation
+  // backwards. A registered renderer draws its own content; a custom section's
+  // regions and slots hold the MERCHANT's blocks, the same blocks they authored
+  // under a generic section root. Skipping the pass meant a `{{...}}` token, a
+  // `properties.dataBinding` and an `isIterator` block all fell back to their
+  // authored value the moment a brand rewrote a working composed header as a
+  // custom section — no console output in the designer, none on the storefront,
+  // nothing in the diff. `useThemePageContext()` is still how the section's own
+  // JSX reads commerce data; it was never a route for the merchant's blocks.
+  if (isCustomThemeType(effectiveSection.type)) {
+    const sectionDefinition = getCustomSectionDefinition(
+      effectiveSection.type
+    );
+
+    if (!sectionDefinition) {
+      devWarn(
+        'ThemeSection',
+        `No renderer registered for custom section type: "${effectiveSection.type}". ` +
+          `The composition holds a section this build cannot draw — check that the barrel calling ` +
+          `registerCustomSections() is imported from the CLIENT ROOT, and that the section name ` +
+          `still matches. Nothing is rendered in its place.`
+      );
+
+      // Never the generic block loop. A section whose type this build does not
+      // register would otherwise spill its seeded region blocks onto the page
+      // as loose top-level content, in an order the developer never chose.
+      // The designer still gets a selectable, deletable band.
+      return isDesigner ? (
+        <SectionWrapper
+          section={effectiveSection}
+          placeholderId={placeholderId}
+          isDesigner={isDesigner}
+          isSelected={isSelected}
+          onSelect={onSelect}
+          onMoveUp={onMoveUp}
+          onMoveDown={onMoveDown}
+          onDuplicate={onDuplicate}
+          onToggleVisibility={onToggleVisibility}
+          onDelete={onDelete}
+          onRename={onRename}
+        >
+          <DesignerPlaceholder
+            label={`${effectiveSection.label || effectiveSection.type} — this build does not register this section`}
+          />
+        </SectionWrapper>
+      ) : null;
+    }
+
+    // ONE RESOLVED BLOCK PER AUTHORED BLOCK, and the top-level count must not
+    // change. `findRegionChild` matches by `properties.regionName` over
+    // `section.blocks`, so a pass that spliced siblings in would slide every
+    // later region onto the wrong block. `resolveIteratorsRecursively` and
+    // `resolveBlockBindings` are both block-in/block-out — a repeat is expanded
+    // INSIDE the iterator block, never beside it — so `.map` is the whole
+    // guarantee. Written as a plain `.map` rather than `useMemo` because this
+    // sits after a conditional return and a hook here would be conditional.
+    //
+    // BINDINGS RUN UNCONDITIONALLY, where the generic path below gates them on
+    // `shouldApplyGenericBindings`. That gate asks "is this section type
+    // literally `custom`, or is there a page-context source, or a page
+    // context?" — and a `custom:vendor:name` type is not the string `custom`,
+    // so reusing the gate would silently drop bindings for a custom section
+    // whose data comes from a collection or static source. The gate exists to
+    // avoid resolving where there is nothing to resolve against, and
+    // `resolveBlockBindings` already answers that itself: with no binding root
+    // it walks the tree and returns it unchanged. Unconditional is therefore
+    // the reading that keeps a merchant's binding working wherever it worked
+    // before the area was rewritten, which is the regression this fixes.
+    const resolvedSection = {
+      ...effectiveSection,
+      blocks: effectiveSection.blocks.map((block) =>
+        resolveBlockBindings({
+          block: resolveIteratorsRecursively(block),
+          sectionDataSource: effectiveSection.dataSource,
+          pageContext,
+          isDesigner,
+          currency: storefrontCurrency
+        })
+      )
+    };
+
+    return (
+      <SectionWrapper
+        // The wrapper reads the section's id, type, label and styles and never
+        // its children, so it keeps the object it always had; only the host,
+        // which is what `ThemeRegion`/`ThemeSlot` read their children out of,
+        // is handed the resolved one.
+        section={effectiveSection}
+        placeholderId={placeholderId}
+        isDesigner={isDesigner}
+        isSelected={isSelected}
+        onSelect={onSelect}
+        onMoveUp={onMoveUp}
+        onMoveDown={onMoveDown}
+        onDuplicate={onDuplicate}
+        onToggleVisibility={onToggleVisibility}
+        onDelete={onDelete}
+        onRename={onRename}
+      >
+        <CustomSectionHost
+          type={effectiveSection.type}
+          label={effectiveSection.label || effectiveSection.type}
+          definition={sectionDefinition}
+          section={resolvedSection}
+          placeholderId={placeholderId}
+          isDesigner={Boolean(isDesigner)}
+          selectedBlockId={selectedBlockId}
+          currentBreakpoint={currentBreakpoint}
+        />
+      </SectionWrapper>
+    );
+  }
+
   const hasTabBlocks = effectiveSection.blocks.some(
     (block) => block.type === 'tab'
   );
@@ -515,7 +659,22 @@ export default function ThemeSection({
     );
   }
 
-  const resolveIteratorsRecursively = (block: Block): Block => {
+  /*
+   * A FUNCTION DECLARATION, NOT A `const` ARROW, AND THAT IS LOAD-BEARING.
+   *
+   * The developer-authored-section branch above needs this resolver, and that
+   * branch has to stay ABOVE the `hasTabBlocks` hatch: the hatch claims any
+   * section holding a `tab` block, and a custom section's regions may
+   * legitimately hold one. Moving the custom return down here to reach the
+   * resolver would hand a brand's own product page to TabsSection; moving this
+   * body up would relocate ~450 lines of related/upsell normalisation into the
+   * middle of the branch chain. A declaration is hoisted to the top of the
+   * component body, so the branch can call it where it stands and neither
+   * order has to change. Everything it closes over — `effectiveSection`,
+   * `pageContext`, `isDesigner`, `currentBreakpoint` — is initialised long
+   * before either call site, so there is no temporal-dead-zone read.
+   */
+  function resolveIteratorsRecursively(block: Block): Block {
     const normalizedType = String(effectiveSection.type || '').toLowerCase();
     const normalizedVariant = String(
       effectiveSection.properties?.dataSourceVariant || ''
@@ -965,7 +1124,7 @@ export default function ThemeSection({
       ...resolvedBlock,
       blocks: resolvedBlock.blocks.map(resolveIteratorsRecursively)
     };
-  };
+  }
 
   return (
     <ThemeSectionDataProvider items={sectionDataItems}>

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

@@ -0,0 +1,249 @@
+import { generateThemeCSS } from '../index';
+import {
+  PART_STYLE_STATES,
+  buildPartSelectors,
+  buildRootStateSelectors,
+  parseRootStateKey,
+  splitPartStyles
+} from '../part-styles';
+import type { Section } from '../../theme-section';
+
+/**
+ * `docked` — the third page-level style state, beside `scrolled` and
+ * `overlay-open`.
+ *
+ * It exists for the header with two appearances: over the home page's hero it
+ * is transparent with light content, and everywhere else it sits above the
+ * page, solid, with dark content. Which one applies is a fact about the ROUTE,
+ * and a route is the one thing a composition cannot ask about — so the brand
+ * stamps `data-chrome-mode` on `body` and the composition styles against it.
+ *
+ * The thing worth pinning is not that the state works. It is the `body` in its
+ * selector.
+ *
+ * ON AN INNER PAGE BOTH STATES MATCH AT ONCE. The shopper scrolls a docked
+ * header, so `[data-scroll-state~="scrolled"]` and `body[data-chrome-mode~=
+ * "docked"]` are both true of the same band, and both rules set the same
+ * property. Every other ancestor-matched state weighs (0,2,0) against an
+ * element selector; the `body` makes this one (0,2,1), so the mode wins on
+ * specificity rather than on whichever rule the generator happened to write
+ * last. That is the right answer and not merely a chosen one: `scrolled`
+ * describes how far the page has slid under a bar that floats over it, and once
+ * the bar is docked the question has no meaning.
+ *
+ * WHY THERE IS NO `getComputedStyle` TEST BELOW, and why adding one would make
+ * this file worse: jsdom has no cascade worth the name. Its `getComputedStyle`
+ * resolves competing rules by SOURCE ORDER ALONE and ignores specificity
+ * entirely — measured here, an `#id` rule loses to a later `div` rule. A
+ * cascade test would therefore assert the opposite of what a browser does, pass
+ * today for the wrong reason, and keep passing after someone deleted the very
+ * qualifier it was written to protect. So the weight is asserted directly.
+ */
+
+const DOCKED = 'body[data-chrome-mode~="docked"]';
+const SCROLLED = '[data-scroll-state~="scrolled"]';
+const SECTION = '[data-section-id="sec-1"]';
+
+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: []
+});
+
+/**
+ * Weighs the two selectors this file is about, and nothing else.
+ *
+ * Deliberately naive: it counts attribute selectors and leading type selectors,
+ * which is all either selector contains. A general specificity parser would be
+ * a second implementation to get wrong, and the honest alternative — asking the
+ * DOM — does not exist here (see the note above).
+ */
+const weigh = (selector: string) => ({
+  attributes: (selector.match(/\[/g) || []).length,
+  types: (selector.match(/(^|[\s>+~])[a-z][a-z0-9-]*/g) || []).length
+});
+
+afterEach(() => {
+  document.body.removeAttribute('data-chrome-mode');
+  document.body.innerHTML = '';
+});
+
+describe('the `body` qualifier is load-bearing — do not tidy it away', () => {
+  it('keeps `body` in the docked selector, which is the only thing that outranks scrolled', () => {
+    const [selector] = buildRootStateSelectors(SECTION, 'docked');
+
+    // Asserted as literal text, because the qualifier reads like a redundant
+    // ancestor to anyone who has not read why it is there.
+    expect(selector).toBe(`${DOCKED} ${SECTION}`);
+  });
+
+  it('outweighs the scrolled selector, which it ties with on attributes alone', () => {
+    const [docked] = buildRootStateSelectors(SECTION, 'docked');
+    const [scrolled] = buildRootStateSelectors(SECTION, 'scrolled');
+
+    // Same attribute count: this is the tie, and it is why order would decide.
+    expect(weigh(docked).attributes).toBe(weigh(scrolled).attributes);
+    // The type selector is the entire margin of victory.
+    expect(weigh(docked).types).toBeGreaterThan(weigh(scrolled).types);
+  });
+
+  it('matches the same band as scrolled on an inner page, so the tie is real', () => {
+    // Not hypothetical: a docked header is scrolled the moment the shopper
+    // moves, and both rules then target one element and one property.
+    document.body.setAttribute('data-chrome-mode', 'docked');
+    document.body.innerHTML =
+      '<div data-chrome-slot="header" data-scroll-state="scrolled">' +
+      '<div data-section-id="sec-1"></div>' +
+      '</div>';
+
+    const [docked] = buildRootStateSelectors(SECTION, 'docked');
+    const [scrolled] = buildRootStateSelectors(SECTION, 'scrolled');
+
+    expect(document.querySelectorAll(docked)).toHaveLength(1);
+    expect(document.querySelectorAll(scrolled)).toHaveLength(1);
+  });
+
+  it('matches nothing when the brand stamps nothing, so overlay stays the default', () => {
+    // Every composition published before this state existed carries no
+    // attribute, and has to render exactly as it did.
+    document.body.innerHTML = '<div data-section-id="sec-1"></div>';
+
+    const [docked] = buildRootStateSelectors(SECTION, 'docked');
+
+    expect(document.querySelectorAll(docked)).toHaveLength(0);
+  });
+
+  it('matches whole tokens only, so `undocked` is not docked', () => {
+    document.body.setAttribute('data-chrome-mode', 'undocked');
+    document.body.innerHTML = '<div data-section-id="sec-1"></div>';
+
+    const [docked] = buildRootStateSelectors(SECTION, 'docked');
+
+    expect(document.querySelectorAll(docked)).toHaveLength(0);
+  });
+});
+
+describe('the generated CSS', () => {
+  it('emits both states for one band, with docked written FIRST', () => {
+    const css = generateThemeCSS([
+      section('sec-1', {
+        'background-color': 'transparent',
+        // Declared before `scrolled` on purpose: source order favours the
+        // scrolled rule, so if this pair ever came out the wrong way round in a
+        // browser, order is not what would be saving it.
+        ':docked/background-color': '#ffffff',
+        ':scrolled/background-color': '#f5f5f5'
+      })
+    ]);
+
+    expect(css).toContain(
+      `${DOCKED} ${SECTION} {\n  background-color: rgba(255, 255, 255, 1);\n}`
+    );
+    expect(css).toContain(
+      `${SCROLLED} ${SECTION} {\n  background-color: rgba(245, 245, 245, 1);\n}`
+    );
+
+    expect(css.indexOf(`${DOCKED} ${SECTION}`)).toBeLessThan(
+      css.indexOf(`${SCROLLED} ${SECTION}`)
+    );
+  });
+
+  it('emits a docked rule for a block wrapper too', () => {
+    const css = generateThemeCSS([
+      section('sec-1', {}, [block('bar', { ':docked/color': '#4a0e26' })])
+    ]);
+
+    expect(css).toContain(
+      `${DOCKED} [data-block-id="bar"] {\n  color: #4a0e26;\n}`
+    );
+  });
+
+  it('never emits the raw key as a declaration', () => {
+    const css = generateThemeCSS([
+      section('sec-1', { ':docked/background-color': '#ffffff' })
+    ]);
+
+    expect(css).not.toContain(':docked/background-color:');
+  });
+});
+
+describe('docked as a part state', () => {
+  it('conditions a part on the page without losing the ownership guard', () => {
+    const [selector] = buildPartSelectors('[data-section-id="sec-1"]', {
+      part: 'bar',
+      state: 'docked',
+      styles: {}
+    });
+
+    // The whole compound, guard included, is substituted into the ancestor
+    // pattern — so a docked rule can no more reach into a nested block than the
+    // stateless one can.
+    //
+    // Asserted as text rather than by querying the DOM on purpose: the guard
+    // uses `:where()`, and the nwsapi build in this workspace's node_modules
+    // cannot parse it (it is the cause of the three known-red suites here). A
+    // DOM assertion would fail for a reason that has nothing to do with docked.
+    expect(selector).toBe(
+      `${DOCKED} [data-section-id="sec-1"] [data-part="bar"]` +
+        ':not(:where([data-section-id="sec-1"] [data-block-id] *))'
+    );
+  });
+
+  it('parses `bar/docked/color` as a part key and buckets it', () => {
+    const { root, parts } = splitPartStyles({
+      color: '#ffffff',
+      'bar/docked/color': '#4a0e26'
+    });
+
+    expect(root).toEqual({ color: '#ffffff' });
+    expect(parts).toEqual([
+      { part: 'bar', state: 'docked', styles: { color: '#4a0e26' } }
+    ]);
+  });
+
+  it('emits the part rule through the generator', () => {
+    const css = generateThemeCSS([
+      section('sec-1', { 'bar/docked/color': '#4a0e26' })
+    ]);
+
+    expect(css).toContain(
+      `${DOCKED} [data-section-id="sec-1"] [data-part="bar"]`
+    );
+  });
+});
+
+describe('the vocabulary', () => {
+  it('lists docked in PART_STYLE_STATES, so a brand may declare it', () => {
+    // `defineCustomSection` validates declared part states against this list
+    // and drops anything absent, so a state missing from it is a control that
+    // silently does nothing.
+    expect(PART_STYLE_STATES).toContain('docked');
+  });
+
+  it('accepts `:docked/<prop>` as a root state key on any element', () => {
+    expect(parseRootStateKey(':docked/background-color')).toEqual({
+      state: 'docked',
+      property: 'background-color'
+    });
+  });
+});

package/src/utils/__tests__/section-content-width.test.ts

@@ -258,6 +258,34 @@ describe('a section that arranges its children keeps arranging them', () => {
     expect(ruleFor(css, BAND_SELECTOR)).toContain('display: flex');
     expect(ruleFor(css, CONTENT_SELECTOR)).toContain('max-width: 1024px');
   });
+
+  it('moves nothing on a developer-authored section either', () => {
+    // The half of the split that is NOT the max-width half. A brand component
+    // draws its own root, so moving `display`/`flex-direction` onto the content
+    // wrapper would make that root a flex ITEM and silently re-lay-out markup
+    // the developer wrote by hand — while the Max Width token beside it still
+    // has to be resolved here, because the component has never heard of it.
+    const css = generateThemeCSS(
+      section(
+        {
+          'content-width': '1024px',
+          'max-width': 'narrow',
+          display: 'flex',
+          'flex-direction': 'column'
+        },
+        { type: 'custom:acme:hero' }
+      )
+    );
+
+    const band = ruleFor(css, BAND_SELECTOR);
+    expect(band).toContain('display: flex');
+    expect(band).toContain('flex-direction: column');
+    expect(band).toContain('max-width: 56rem');
+
+    const content = ruleFor(css, CONTENT_SELECTOR);
+    expect(content).toContain('max-width: 1024px');
+    expect(content).not.toContain('display: flex');
+  });
 });
 
 describe('the setting is additive', () => {

package/src/utils/__tests__/section-max-width.test.ts

@@ -135,6 +135,59 @@ describe('a custom-renderer section keeps resolving its own max-width', () => {
   });
 });
 
+/**
+ * A DEVELOPER-AUTHORED SECTION SPLITS THE ONE PREDICATE IN TWO.
+ *
+ * "Owns the box its children sit in" and "translates the max-width token
+ * itself" were the same question for all 18 built-in renderers, so one boolean
+ * answered both. A brand component answers them differently: it draws a real
+ * container, so the child-layout keys stay on the band — but it has never heard
+ * of `narrow`, so nothing downstream would turn the token into a length.
+ */
+describe('a developer-authored section cannot translate the token itself', () => {
+  const brandSection = (styles: Record<string, unknown>) =>
+    section(styles, { type: 'custom:acme:hero' });
+
+  it('resolves the token to a real length rather than emitting a dropped declaration', () => {
+    // Left unresolved this emits `max-width: narrow`, the browser drops the
+    // declaration, and the section's Max Width control does nothing at all —
+    // the exact failure `resolveSectionMaxWidthTokens` exists to fix,
+    // reintroduced on the newest surface.
+    const css = generateThemeCSS(brandSection({ 'max-width': 'narrow' }));
+
+    expect(css).toContain('max-width: 56rem');
+    expect(css).not.toContain('max-width: narrow');
+  });
+
+  it('centres it, because nothing else will', () => {
+    // A built-in renderer pairs the token with `mx-auto` on the container it
+    // owns. A brand component pairs it with nothing, so the auto margins have
+    // to come from here or a constrained band sits against the left edge.
+    const css = generateThemeCSS(brandSection({ 'max-width': 'normal' }));
+
+    expect(css).toContain('max-width: 80rem');
+    expect(css).toContain('margin-left: auto');
+    expect(css).toContain('margin-right: auto');
+  });
+
+  it('resolves per breakpoint, inside the media query', () => {
+    const css = generateThemeCSS(
+      brandSection({ 'max-width': { desktop: 'narrow', mobile: 'none' } })
+    );
+
+    expect(css).toContain('max-width: 56rem');
+    expect(css).toContain('max-width: none');
+    expect(css).not.toContain('max-width: narrow');
+  });
+
+  it('still leaves a real CSS length the author typed alone', () => {
+    const css = generateThemeCSS(brandSection({ 'max-width': '640px' }));
+
+    expect(css).toContain('max-width: 640px');
+    expect(css).not.toContain('margin-left: auto');
+  });
+});
+
 describe('the scale is one table, not two', () => {
   // The class and the length are the same measurement: Tailwind's max-w-4xl is
   // 56rem and max-w-7xl is 80rem. A test would not catch them drifting if they

package/src/utils/index.ts

@@ -18,6 +18,7 @@ import {
   stripHidingStyles
 } from './checkout-safety';
 import { hasBindingToken } from './iterator-utils';
+import { isCustomThemeType } from '../custom/types';
 import {
   BREAKPOINT_FALLBACKS,
   MOBILE_MEDIA_QUERY,
@@ -707,6 +708,14 @@ interface Block {
 
 interface Section {
   id: string;
+  /**
+   * Read to decide whether the section owns the box its children sit in: a
+   * registered renderer, the tab hatch, or a developer-authored
+   * `custom:<vendor>:<name>` type. Optional because published JSON written by
+   * an older editor may omit it, and `hasCustomSectionRenderer` already treats
+   * a missing type as "generic".
+   */
+  type?: string;
   styles?: ResponsiveStyles;
   properties?: Record<string, unknown>;
   blocks?: Block[];
@@ -1467,7 +1476,26 @@ export const generateThemeCSS = (
       const { root: sectionRoot } = splitPartStyles(sectionStyles);
 
       if (Object.keys(sectionRoot).length > 0) {
-        const customRenderer = hasCustomSectionRenderer(section);
+        // ONE PREDICATE, TWO QUESTIONS, AND A DEVELOPER-AUTHORED SECTION
+        // ANSWERS THEM DIFFERENTLY.
+        //
+        // "Owns the box its children sit in" decides whether the child-layout
+        // keys stay on the band. True for a custom section: its component draws
+        // a real container, so moving `display`/`flex-direction`/`gap` onto the
+        // content wrapper would make the developer's own root a flex item and
+        // silently re-lay-out the authored markup.
+        //
+        // "Translates the max-width token itself" is the opposite. Each of the
+        // 18 built-in renderers turns `narrow`/`normal` into a real length on
+        // the container it owns. A brand component has never heard of the
+        // token, so leaving it unresolved would emit `max-width: narrow`, the
+        // browser would drop the declaration, and the section's Max Width
+        // control would do nothing — with the auto-centring never firing
+        // either. That is the exact failure `resolveSectionMaxWidthTokens`
+        // exists to fix, and it would be reintroduced on the newest surface.
+        const ownsContentBox = hasCustomSectionRenderer(section);
+        const resolvesOwnMaxWidth =
+          ownsContentBox && !isCustomThemeType(section.type);
 
         // The content width leaves the band before anything else is decided
         // about it: it is not a declaration a section ever carries, and on the
@@ -1475,13 +1503,13 @@ export const generateThemeCSS = (
         // utils/section-content-width.ts for why that move exists.
         const { section: band, content } = splitSectionContentWidth(
           sectionRoot,
-          { moveLayout: !customRenderer }
+          { moveLayout: !ownsContentBox }
         );
 
         if (Object.keys(band).length > 0) {
           css += generateElementCSS(
             sectionSelector,
-            customRenderer ? band : resolveSectionMaxWidthTokens(band),
+            resolvesOwnMaxWidth ? band : resolveSectionMaxWidthTokens(band),
             targetBreakpoint
           );
         }

package/src/utils/part-styles.ts

@@ -81,7 +81,23 @@ const STATE_SELECTORS: Record<string, string[]> = {
   // hero, opaque while its menu panel is open. The panel cannot express it —
   // the header is not inside the panel — and the header cannot know it without
   // the page saying so.
-  'overlay-open': ['[data-overlay-state~="open"] &']
+  'overlay-open': ['[data-overlay-state~="open"] &'],
+  /**
+   * The third page-level state: the chrome is DOCKED above the page rather than
+   * sitting over it. `body` carries `data-chrome-mode` (see
+   * chrome/chrome-mode.ts), stamped by the brand, because only the brand knows
+   * which of its routes carry a hero.
+   *
+   * THE `body` QUALIFIER IS A DELIBERATE SPECIFICITY BUMP, not tidiness. Every
+   * other ancestor-matched state weighs (0,2,0) against an element selector,
+   * which ties with `scrolled` — and on an inner page BOTH match at once, so a
+   * tie would be settled by whichever declaration the generator happened to
+   * emit last. Adding the element name makes this (0,2,1), so the mode wins.
+   * That is the correct answer rather than an arbitrary one: `scrolled`
+   * describes how far the page has moved under a bar that floats over it, and
+   * once the bar is docked that question no longer has a meaning.
+   */
+  docked: ['body[data-chrome-mode~="docked"] &']
 };
 
 export const PART_STYLE_STATES = Object.keys(STATE_SELECTORS);