@akinon/pz-theme 2.0.147-beta.0 → 2.0.147

package/CHANGELOG.md

@@ -1,12 +1,12 @@
 # @akinon/pz-theme
 
-## 2.0.147-beta.0
+## 2.0.147
 
 ### Patch Changes
 
-- Updated dependencies [cbbbfd757]
-  - @akinon/next@2.0.147-beta.0
-  - @akinon/theme-contract@2.0.147-beta.0
+- 0ff4179: ZERO-5177: place the video block's play/pause and sound buttons by Button Position and two distances, and paint the default inset per breakpoint from the first frame
+  - @akinon/next@2.0.147
+  - @akinon/theme-contract@2.0.147
 
 ## 2.0.146
 

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

package/src/__tests__/custom-catalog-announce.test.ts

@@ -377,7 +377,8 @@ describe('PLACEHOLDERS_AVAILABLE announce', () => {
     // rename would silently break.
     expect(frames()[0].actionCapabilities).toEqual([
       'add-to-cart-after-add',
-      'localized-video'
+      'localized-video',
+      'video-control-position'
     ]);
   });
 
@@ -418,8 +419,8 @@ describe('PLACEHOLDERS_AVAILABLE announce', () => {
     // panel back to "On Click" halfway through a session.
     expect(postMessage).toHaveBeenCalledTimes(2);
     expect(frames().map((frame) => frame.actionCapabilities)).toEqual([
-      ['add-to-cart-after-add', 'localized-video'],
-      ['add-to-cart-after-add', 'localized-video']
+      ['add-to-cart-after-add', 'localized-video', 'video-control-position'],
+      ['add-to-cart-after-add', 'localized-video', 'video-control-position']
     ]);
 
     // The reporting list rides every frame for the same reason: the editor

package/src/action-capabilities.ts

@@ -16,6 +16,12 @@
  *                             "On Click", to trim the option list, and to stop
  *                             offering Focus and Pressed root chips on a
  *                             wrapper that is no longer a control.
+ *  - `video-control-position` the Video block places its play/pause and sound
+ *                             buttons by `controlPosition`, `controlOffsetX`
+ *                             and `controlOffsetY`. The editor offers those
+ *                             controls only to a storefront that says so —
+ *                             on an older theme they would save and move
+ *                             nothing.
  *
  * Names rather than a version number, for the reason the state pins are: the
  * editor must not have to know which release added what. A build that does not
@@ -31,9 +37,13 @@
  * the placeholder registry announces this, and it must not have to pull a
  * client component in to say one list of strings.
  */
-export type ActionCapability = 'add-to-cart-after-add' | 'localized-video';
+export type ActionCapability =
+  | 'add-to-cart-after-add'
+  | 'localized-video'
+  | 'video-control-position';
 
 export const ACTION_CAPABILITIES: readonly ActionCapability[] = [
   'add-to-cart-after-add',
-  'localized-video'
+  'localized-video',
+  'video-control-position'
 ];

package/src/blocks/__tests__/scoped-style-text.test.tsx

@@ -91,6 +91,7 @@ import ProductGalleryBlock from '../product-gallery-block';
 import ProductGridBlock from '../product-grid-block';
 import ProductRecommendationsBlock from '../product-recommendations-block';
 import StoreLocatorBlock from '../store-locator-block';
+import VideoBlock from '../video-block';
 import { ThemePageContextProvider } from '../../theme-page-context';
 
 const block = (
@@ -138,6 +139,20 @@ const iconGroup = (id: string) =>
     styles: { size: { desktop: '24' } }
   });
 
+/** A file-backed video drawing its own control layer, which is what writes the placement sheet. */
+const videoBlock = (id: string, controlPosition?: unknown) =>
+  block(
+    id,
+    'video',
+    {
+      controls: { desktop: false },
+      customPlayPause: { desktop: true },
+      ...(controlPosition ? { controlPosition } : {})
+    },
+    [],
+    { value: 'https://cdn.example.com/campaign.mp4' }
+  );
+
 const withPage = (value: Record<string, unknown> | null, element: React.ReactElement) => (
   <ThemePageContextProvider value={value}>{element}</ThemePageContextProvider>
 );
@@ -290,6 +305,20 @@ const cases: Array<[string, () => React.ReactElement, string[]]> = [
     [
       '[data-store-locator-id="nearby-stores"]{grid-template-columns:repeat(2,minmax(0,1fr));}'
     ]
+  ],
+  [
+    'video control placement',
+    () => (
+      <VideoBlock
+        {...base}
+        block={videoBlock('campaign-film', { desktop: 'top-left' })}
+      />
+    ),
+    [
+      ':where([data-pz-video-controls="campaign-film"]){padding:24px 24px!important;justify-content:flex-start!important}',
+      ':where([data-pz-video-controls="campaign-film"]>div){justify-content:flex-start!important}',
+      '@media (max-width:1023px){:where([data-pz-video-controls="campaign-film"]){padding:18px 18px!important}'
+    ]
   ]
 ];
 
@@ -336,7 +365,11 @@ describe('an id that tries to close the tag stays inside the sheet', () => {
       )
     ],
     ['icon button', () => <IconButtonBlock {...base} block={iconButton(HOSTILE_ID)} />],
-    ['icon group', () => <IconGroupBlock {...base} block={iconGroup(HOSTILE_ID)} />]
+    ['icon group', () => <IconGroupBlock {...base} block={iconGroup(HOSTILE_ID)} />],
+    [
+      'video controls',
+      () => <VideoBlock {...base} block={videoBlock(HOSTILE_ID)} />
+    ]
   ])('%s', (_name, element) => {
     // The collapsible's `<noscript>` copy is a separate raw-text context this
     // change did not touch, so only the sheets outside it are asserted.

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

@@ -1,7 +1,10 @@
 import React from 'react';
 import { act, render, screen } from '@testing-library/react';
-import { renderToStaticMarkup } from 'react-dom/server';
+import { renderToStaticMarkup, renderToString } from 'react-dom/server';
+import { hydrateRoot } from 'react-dom/client';
 import VideoBlock from '../video-block';
+import { __resetBrowseModeForTests } from '../../browse-mode';
+import { registerCustomBreakpoints } from '../../utils/breakpoints';
 
 /**
  * Stand the test in a viewport band.
@@ -1601,3 +1604,696 @@ describe('properties the editor stores per breakpoint', () => {
     expect(video.loop).toBe(true);
   });
 });
+
+/**
+ * WHERE THE CONTROL LAYER SITS (ZERO-5177).
+ *
+ * Button Position and the two distances are per-breakpoint properties, and
+ * they reach the page as a stylesheet rather than as inline values resolved at
+ * `currentBreakpoint` — that prop is `'desktop'` on the server and through a
+ * phone's first render, so an inline answer paints every phone with the
+ * desktop corner first. What is pinned here is the sheet itself: where it
+ * sits, what each band writes, and what it may never take away.
+ */
+describe('where the control layer sits', () => {
+  const FILE = 'https://cdn.example.com/campaign.mp4';
+  const customControls = {
+    controls: { desktop: false },
+    customPlayPause: { desktop: true }
+  };
+
+  const renderControls = (
+    properties: Record<string, unknown> = {},
+    options: {
+      id?: string | null;
+      isDesigner?: boolean;
+      currentBreakpoint?: string;
+      value?: string;
+      styles?: Record<string, unknown>;
+    } = {}
+  ) =>
+    render(
+      <VideoBlock
+        block={
+          {
+            id: options.id === null ? undefined : options.id ?? 'campaign-film',
+            value: options.value ?? FILE,
+            properties: { ...customControls, ...properties },
+            styles: options.styles
+          } as any
+        }
+        placeholderId="p1"
+        sectionId="s1"
+        isDesigner={options.isDesigner ?? false}
+        currentBreakpoint={options.currentBreakpoint ?? 'desktop'}
+      />
+    );
+
+  const sheetOf = (container: HTMLElement) =>
+    container.querySelector('style')?.innerHTML ?? '';
+
+  const scope = '[data-pz-video-controls="campaign-film"]';
+  const overlayRule = (declarations: string) =>
+    `:where(${scope}){${declarations}}`;
+  const columnRule = (declarations: string) =>
+    `:where(${scope}>div){${declarations}}`;
+  const railRule = (declarations: string) =>
+    `:where(${scope} [data-part="control-rail"]){${declarations}}`;
+  const MOBILE = '@media (max-width:1023px)';
+  const TABLET = '@media (min-width:768px) and (max-width:1023px)';
+
+  describe('the sheet and the element it styles', () => {
+    it('sits right before the overlay, which stays the last child', () => {
+      // The generator's root hover rule reaches the buttons through
+      // `> div:last-child button`; a sheet appended after the overlay would
+      // have taken that away from every video with a hover colour.
+      const { container } = renderControls();
+      const { overlay } = controlBoxes(container);
+      const sheet = container.querySelector('style') as HTMLStyleElement;
+
+      expect(sheet).not.toBeNull();
+      expect(sheet.nextElementSibling).toBe(overlay);
+      expect(overlay.parentElement?.lastElementChild).toBe(overlay);
+    });
+
+    it('names the overlay by the block id the selectors use', () => {
+      const { container } = renderControls();
+      expect(
+        controlBoxes(container).overlay.getAttribute('data-pz-video-controls')
+      ).toBe('campaign-film');
+      expect(sheetOf(container)).toContain(scope);
+    });
+
+    it('keeps the raw id on the element and escapes it only in the selector', () => {
+      const { container } = renderControls({}, { id: 'film"x' });
+
+      expect(
+        controlBoxes(container).overlay.getAttribute('data-pz-video-controls')
+      ).toBe('film"x');
+      expect(sheetOf(container)).toContain(
+        '[data-pz-video-controls="film\\"x"]'
+      );
+    });
+
+    it('is only there when the custom control is', () => {
+      expect(
+        renderControls({ controls: { desktop: true } }).container.querySelector(
+          'style'
+        )
+      ).toBeNull();
+      expect(
+        renderControls({
+          customPlayPause: { desktop: false }
+        }).container.querySelector('style')
+      ).toBeNull();
+      // An embed never draws the custom control at all.
+      expect(
+        renderControls(
+          {},
+          { value: 'https://www.youtube.com/watch?v=abc123' }
+        ).container.querySelector('style')
+      ).toBeNull();
+    });
+
+    it('outranks only the inline styles and unflagged rules, never an authored !important', () => {
+      // Specificity 0 (`:where`) with `!important`: beats the inline defaults,
+      // loses to every authored `!important` with any specificity — the
+      // Control Overlay part keys and a brand's own override alike.
+      const sheet = sheetOf(
+        renderControls({
+          controlPosition: { desktop: 'top-left', mobile: 'middle-center' },
+          controlOffsetX: { desktop: 40 }
+        }).container
+      );
+      const rules = sheet
+        .replace(/@media[^{]*\{/g, '')
+        .split('}')
+        .filter((rule) => rule.includes('{'));
+
+      expect(rules.length).toBeGreaterThan(0);
+      rules.forEach((rule) => {
+        const [selector, body] = rule.split('{');
+        expect(selector.startsWith(':where(')).toBe(true);
+        body.split(';').forEach((declaration) => {
+          expect(declaration.endsWith('!important')).toBe(true);
+        });
+      });
+    });
+
+    it('leaves the inline styles exactly as they were', () => {
+      const { overlay, column, rail } = controlBoxes(
+        renderControls({
+          controlPosition: { desktop: 'top-left' },
+          controlOffsetY: { desktop: 60 }
+        }).container
+      );
+
+      expect(overlay.style.justifyContent).toBe('flex-end');
+      expect(overlay.style.padding).toBe('24px');
+      expect(column.style.justifyContent).toBe('flex-end');
+      expect(rail.style.position).toBe('sticky');
+      expect(rail.style.bottom).toBe('24px');
+    });
+  });
+
+  describe('with nothing authored', () => {
+    it('writes the inset per band, so a phone paints 18px from the first frame', () => {
+      const sheet = sheetOf(renderControls().container);
+
+      expect(sheet).toBe(
+        overlayRule('padding:24px 24px!important') +
+          railRule('bottom:24px!important') +
+          `${MOBILE}{` +
+          overlayRule('padding:18px 18px!important') +
+          railRule('bottom:18px!important') +
+          '}'
+      );
+    });
+
+    it('writes no corner and no direction of its own', () => {
+      // Nothing to move, so nothing that could take a merchant's Custom CSS
+      // `flex-direction` (which wins today: the rail inlines none) away.
+      const sheet = sheetOf(renderControls().container);
+
+      expect(sheet).not.toContain('justify-content');
+      expect(sheet).not.toContain('flex-direction');
+    });
+
+    it('reaches the server HTML, not only the client', () => {
+      const html = renderToStaticMarkup(
+        <VideoBlock
+          block={
+            {
+              id: 'campaign-film',
+              value: FILE,
+              properties: customControls
+            } as any
+          }
+          placeholderId="p1"
+          sectionId="s1"
+          isDesigner={false}
+        />
+      );
+
+      expect(html).toContain(
+        `${MOBILE}{${overlayRule('padding:18px 18px!important')}`
+      );
+    });
+  });
+
+  describe('Button Position', () => {
+    it.each([
+      ['top-left', 'flex-start', 'flex-start', true],
+      ['top-center', 'center', 'flex-start', false],
+      ['top-right', 'flex-end', 'flex-start', false],
+      ['middle-left', 'flex-start', 'center', true],
+      ['middle-center', 'center', 'center', false],
+      ['middle-right', 'flex-end', 'center', false],
+      ['bottom-left', 'flex-start', 'flex-end', true],
+      ['bottom-center', 'center', 'flex-end', false],
+      ['bottom-right', 'flex-end', 'flex-end', false]
+    ])('places %s', (position, justify, align, mirrored) => {
+      const sheet = sheetOf(
+        renderControls({ controlPosition: { desktop: position } }).container
+      );
+      const desktop = sheet.split('@media')[0];
+
+      expect(desktop).toContain(
+        overlayRule(
+          `padding:24px 24px!important;justify-content:${justify}!important`
+        )
+      );
+      expect(desktop).toContain(
+        columnRule(`justify-content:${align}!important`)
+      );
+      if (mirrored) {
+        // play/pause keeps the outer corner on either side; reading-flow keeps
+        // the Tab order with what the eye sees.
+        expect(desktop).toContain(
+          railRule(
+            'bottom:24px!important;flex-direction:row-reverse!important;reading-flow:flex-visual!important'
+          )
+        );
+      } else {
+        expect(sheet).not.toContain('flex-direction');
+      }
+    });
+
+    it('moves the buttons on a phone without touching desktop', () => {
+      const sheet = sheetOf(
+        renderControls({
+          controlPosition: { desktop: 'top-left', mobile: 'bottom-center' }
+        }).container
+      );
+      const [desktop, mobile] = sheet.split(MOBILE);
+
+      expect(desktop).toContain('justify-content:flex-start!important');
+      expect(mobile).toContain(
+        overlayRule(
+          'padding:18px 18px!important;justify-content:center!important'
+        )
+      );
+      expect(mobile).toContain(
+        columnRule('justify-content:flex-end!important')
+      );
+      // The desktop mirror is undone where the phone is not on the left.
+      expect(mobile).toContain(
+        'flex-direction:row!important;reading-flow:normal!important'
+      );
+    });
+
+    it('writes a band only where it differs from the one it inherits', () => {
+      const sheet = sheetOf(
+        renderControls({ controlPosition: { desktop: 'top-right' } }).container
+      );
+      const mobile = sheet.split(MOBILE)[1];
+
+      // Mobile inherits the corner; only its own inset is written.
+      expect(mobile).not.toContain('justify-content');
+      expect(sheet).not.toContain(TABLET);
+    });
+
+    it('gives a tablet the phone answer unless it has its own', () => {
+      const inherited = sheetOf(
+        renderControls({ controlPosition: { mobile: 'top-left' } }).container
+      );
+      expect(inherited).not.toContain(TABLET);
+
+      const own = sheetOf(
+        renderControls({
+          controlPosition: { mobile: 'top-left', tablet: 'top-right' }
+        }).container
+      );
+      // The order is the answer: both bands are specificity 0 and !important,
+      // so a tablet only gets its own value because its query comes AFTER the
+      // phone's (which also matches 768-1023px).
+      expect(own).toBe(
+        overlayRule(
+          'padding:24px 24px!important;justify-content:flex-end!important'
+        ) +
+          columnRule('justify-content:flex-end!important') +
+          railRule('bottom:24px!important') +
+          `${MOBILE}{` +
+          overlayRule(
+            'padding:18px 18px!important;justify-content:flex-start!important'
+          ) +
+          columnRule('justify-content:flex-start!important') +
+          railRule(
+            'bottom:18px!important;flex-direction:row-reverse!important;reading-flow:flex-visual!important'
+          ) +
+          '}' +
+          `${TABLET}{` +
+          overlayRule('justify-content:flex-end!important') +
+          railRule(
+            'flex-direction:row!important;reading-flow:normal!important'
+          ) +
+          '}'
+      );
+    });
+
+    it('reads a flat value, the shape templates write', () => {
+      expect(
+        sheetOf(renderControls({ controlPosition: 'middle-center' }).container)
+      ).toContain(columnRule('justify-content:center!important'));
+    });
+
+    it('treats anything it does not know as the corner it always had', () => {
+      const sheet = sheetOf(
+        renderControls({ controlPosition: { desktop: 'sideways-up' } })
+          .container
+      );
+      expect(sheet).toContain('justify-content:flex-end!important');
+      expect(sheet).toContain(columnRule('justify-content:flex-end!important'));
+    });
+  });
+
+  describe('the two distances', () => {
+    it('sets each axis on its own', () => {
+      const sheet = sheetOf(
+        renderControls({
+          controlOffsetX: { desktop: 40 },
+          controlOffsetY: { desktop: 12 }
+        }).container
+      );
+
+      expect(sheet).toContain(overlayRule('padding:12px 40px!important'));
+      // The same vertical distance is kept from the screen's foot while the
+      // rail follows a tall clip — one value for resting and travelling.
+      expect(sheet).toContain(railRule('bottom:12px!important'));
+    });
+
+    it('reads numeric strings, the shape a template, an import or a hand-edited theme carries', () => {
+      expect(
+        sheetOf(renderControls({ controlOffsetX: { desktop: '40' } }).container)
+      ).toContain(overlayRule('padding:24px 40px!important'));
+    });
+
+    it('keeps an authored 0', () => {
+      expect(
+        sheetOf(renderControls({ controlOffsetY: { desktop: 0 } }).container)
+      ).toContain(overlayRule('padding:0px 24px!important'));
+    });
+
+    it('clamps to the range the editor offers', () => {
+      expect(
+        sheetOf(renderControls({ controlOffsetX: { desktop: 999 } }).container)
+      ).toContain('padding:24px 200px!important');
+      expect(
+        sheetOf(renderControls({ controlOffsetX: { desktop: -8 } }).container)
+      ).toContain('padding:24px 0px!important');
+    });
+
+    it('falls back to the inset for a value it cannot read', () => {
+      expect(
+        sheetOf(
+          renderControls({ controlOffsetX: { desktop: 'wide' } }).container
+        )
+      ).toContain(overlayRule('padding:24px 24px!important'));
+    });
+
+    it('keeps the desktop inset when only the phone was set', () => {
+      // The authoring order that broke a breakpoint-object default in the
+      // panel: phone first, then desktop looked at.
+      const sheet = sheetOf(
+        renderControls({ controlOffsetX: { mobile: '10' } }).container
+      );
+      const [desktop, mobile] = sheet.split(MOBILE);
+
+      expect(desktop).toContain(overlayRule('padding:24px 24px!important'));
+      expect(mobile).toContain(overlayRule('padding:18px 10px!important'));
+    });
+
+    it('lets a narrower band inherit a desktop distance, the way every style does', () => {
+      const sheet = sheetOf(
+        renderControls({ controlOffsetX: { desktop: 40 } }).container
+      );
+      expect(sheet.split(MOBILE)[1]).toContain(
+        overlayRule('padding:18px 40px!important')
+      );
+    });
+  });
+
+  describe('in the editor', () => {
+    it('writes the one band the editor is forcing, without a query', () => {
+      const sheet = sheetOf(
+        renderControls(
+          { controlPosition: { desktop: 'top-left', mobile: 'middle-center' } },
+          { isDesigner: true, currentBreakpoint: 'mobile' }
+        ).container
+      );
+
+      expect(sheet).not.toContain('@media');
+      expect(sheet).toContain(
+        overlayRule(
+          'padding:18px 18px!important;justify-content:center!important'
+        )
+      );
+      expect(sheet).toContain(columnRule('justify-content:center!important'));
+    });
+
+    it('answers for the storefront the same way whatever breakpoint the prop says', () => {
+      // The server and a phone's first render both say 'desktop'; a sheet that
+      // listened to the prop would not hydrate.
+      const atDesktop = sheetOf(
+        renderControls(
+          { controlPosition: { mobile: 'top-left' } },
+          { currentBreakpoint: 'desktop' }
+        ).container
+      );
+      const atMobile = sheetOf(
+        renderControls(
+          { controlPosition: { mobile: 'top-left' } },
+          { currentBreakpoint: 'mobile' }
+        ).container
+      );
+
+      expect(atMobile).toBe(atDesktop);
+    });
+  });
+
+  describe('mirroring follows where the rail actually ends up', () => {
+    it('follows a Control Overlay Horizontal Corner over the preset', () => {
+      // The part key outranks the preset's justify-content, so a preset Left
+      // under a stored Right puts the rail on the right — and mirroring by the
+      // preset would hand the sound button the corner.
+      const rightAfterAll = sheetOf(
+        renderControls(
+          { controlPosition: { desktop: 'bottom-left' } },
+          { styles: { 'controls/justify-content': { desktop: 'flex-end' } } }
+        ).container
+      );
+      expect(rightAfterAll).not.toContain('row-reverse');
+
+      const leftAfterAll = sheetOf(
+        renderControls(
+          { controlPosition: { desktop: 'bottom-right' } },
+          { styles: { 'controls/justify-content': { desktop: 'flex-start' } } }
+        ).container
+      );
+      expect(leftAfterAll).toContain('flex-direction:row-reverse!important');
+    });
+
+    it('leaves a block with nothing but a legacy Left in the order it renders today', () => {
+      const sheet = sheetOf(
+        renderControls(
+          {},
+          { styles: { 'controls/justify-content': { desktop: 'flex-start' } } }
+        ).container
+      );
+      expect(sheet).not.toContain('flex-direction');
+    });
+  });
+
+  describe('in browse mode', () => {
+    afterEach(() => __resetBrowseModeForTests());
+
+    it('still writes the one band the editor forces', () => {
+      // Blocks get isDesigner false while browsing, but the canvas is still
+      // the editor's zoomed frame, where WebKit answers a real media query by
+      // the zoomed width — a phone answer on a desktop canvas.
+      (
+        window as { __themeEditorBrowseMode?: boolean }
+      ).__themeEditorBrowseMode = true;
+
+      const sheet = sheetOf(
+        renderControls({}, { isDesigner: false, currentBreakpoint: 'desktop' })
+          .container
+      );
+
+      expect(sheet).not.toContain('@media');
+      expect(sheet).toContain(overlayRule('padding:24px 24px!important'));
+    });
+  });
+
+  describe('a block with no id', () => {
+    it('still scopes its own sheet, apart from every other', () => {
+      const first = controlBoxes(
+        renderControls({}, { id: null }).container
+      ).overlay;
+      const second = controlBoxes(
+        renderControls({}, { id: null }).container
+      ).overlay;
+      const firstScope = first.getAttribute('data-pz-video-controls') ?? '';
+      const secondScope = second.getAttribute('data-pz-video-controls') ?? '';
+
+      expect(firstScope).not.toBe('');
+      expect(firstScope).not.toBe('undefined');
+      expect(secondScope).not.toBe(firstScope);
+      // The sheet has to name the scope the element carries, or it styles
+      // nothing at all.
+      [first, second].forEach((overlay, index) => {
+        const scope = index === 0 ? firstScope : secondScope;
+        const sheet =
+          (overlay.previousElementSibling as HTMLStyleElement | null)
+            ?.innerHTML ?? '';
+        expect(sheet).toContain(`[data-pz-video-controls="${scope}"]`);
+      });
+    });
+  });
+
+  describe('mirroring and undoing it between bands', () => {
+    it('writes exactly this for a desktop left and a phone right', () => {
+      const sheet = sheetOf(
+        renderControls({
+          controlPosition: { desktop: 'bottom-left', mobile: 'bottom-right' }
+        }).container
+      );
+
+      expect(sheet).toBe(
+        overlayRule(
+          'padding:24px 24px!important;justify-content:flex-start!important'
+        ) +
+          columnRule('justify-content:flex-end!important') +
+          railRule(
+            'bottom:24px!important;flex-direction:row-reverse!important;reading-flow:flex-visual!important'
+          ) +
+          `${MOBILE}{` +
+          overlayRule(
+            'padding:18px 18px!important;justify-content:flex-end!important'
+          ) +
+          railRule(
+            'bottom:18px!important;flex-direction:row!important;reading-flow:normal!important'
+          ) +
+          '}'
+      );
+    });
+
+    it('leaves a merchant’s own flex-direction alone on a block anchored right', () => {
+      // The rail inlines no flex-direction, so Custom CSS that stacks the
+      // buttons works today; only a left anchor (or undoing one) may touch it.
+      const sheet = sheetOf(
+        renderControls({
+          controlPosition: { desktop: 'top-right', mobile: 'bottom-center' },
+          customCss: {
+            desktop: '& [data-part="control-rail"] { flex-direction: column; }'
+          }
+        }).container
+      );
+
+      expect(sheet).not.toContain('flex-direction');
+    });
+  });
+
+  describe('custom breakpoints in the editor', () => {
+    beforeEach(() =>
+      registerCustomBreakpoints([
+        { name: 'wide', label: 'Wide', width: 1440, minWidth: 1440 },
+        {
+          name: 'phablet',
+          label: 'Phablet',
+          width: 600,
+          minWidth: 600,
+          maxWidth: 767
+        }
+      ])
+    );
+    afterEach(() => registerCustomBreakpoints([]));
+
+    it('draws the built-in band a custom breakpoint stands on, which is all the storefront sheet carries', () => {
+      // Live has no custom band for this sheet, so a value stored under the
+      // custom key would show in the canvas and never on the page.
+      const wide = sheetOf(
+        renderControls(
+          { controlPosition: { desktop: 'bottom-right', wide: 'top-left' } },
+          { isDesigner: true, currentBreakpoint: 'wide' }
+        ).container
+      );
+      expect(wide).toBe(
+        overlayRule(
+          'padding:24px 24px!important;justify-content:flex-end!important'
+        ) +
+          columnRule('justify-content:flex-end!important') +
+          railRule('bottom:24px!important')
+      );
+
+      const phablet = sheetOf(
+        renderControls(
+          { controlPosition: { mobile: 'bottom-center', phablet: 'top-left' } },
+          { isDesigner: true, currentBreakpoint: 'phablet' }
+        ).container
+      );
+      expect(phablet).toContain(
+        overlayRule(
+          'padding:18px 18px!important;justify-content:center!important'
+        )
+      );
+      expect(phablet).not.toContain('flex-direction');
+    });
+  });
+
+  describe('across the server and the client', () => {
+    const element = (id: string | undefined, currentBreakpoint = 'desktop') => (
+      <VideoBlock
+        block={
+          {
+            id,
+            value: FILE,
+            properties: {
+              ...customControls,
+              soundToggle: { desktop: true },
+              controlPosition: { desktop: 'bottom-right', mobile: 'top-left' },
+              controlOffsetX: { desktop: 40 }
+            }
+          } as any
+        }
+        placeholderId="p1"
+        sectionId="s1"
+        isDesigner={false}
+        currentBreakpoint={currentBreakpoint}
+      />
+    );
+
+    it.each([
+      ['with a block id', 'campaign-film'],
+      ['without one, on the useId scope', undefined]
+    ])('hydrates %s, sheet and scope byte for byte', async (_label, id) => {
+      const container = document.createElement('div');
+      container.innerHTML = renderToString(element(id));
+      const serverSheet = container.querySelector('style')?.innerHTML;
+      const serverScope = container
+        .querySelector('[data-part="controls"]')
+        ?.getAttribute('data-pz-video-controls');
+      document.body.appendChild(container);
+
+      const recoverable: unknown[] = [];
+      const errors = jest.spyOn(console, 'error').mockImplementation(() => {});
+      let root: ReturnType<typeof hydrateRoot> | undefined;
+      await act(async () => {
+        root = hydrateRoot(container, element(id), {
+          onRecoverableError: (error) => recoverable.push(error)
+        });
+      });
+
+      expect(recoverable).toEqual([]);
+      expect(errors).not.toHaveBeenCalled();
+      expect(container.querySelector('style')?.innerHTML).toBe(serverSheet);
+      expect(
+        container
+          .querySelector('[data-part="controls"]')
+          ?.getAttribute('data-pz-video-controls')
+      ).toBe(serverScope);
+      expect(serverSheet).toContain(
+        `[data-pz-video-controls="${serverScope}"]`
+      );
+
+      // A phone corrects the prop after mount; the storefront sheet never
+      // listened to it, so nothing moves.
+      await act(async () => root?.render(element(id, 'mobile')));
+      expect(container.querySelector('style')?.innerHTML).toBe(serverSheet);
+
+      errors.mockRestore();
+      await act(async () => root?.unmount());
+      container.remove();
+    });
+  });
+
+  it('survives the layer coming and going', () => {
+    // Nothing here is a hook: VideoBlock returns early after its hooks, so a
+    // hook added beside the overlay would change the count whenever the custom
+    // control or the source kind changes.
+    const view = renderControls({ controlPosition: { desktop: 'top-left' } });
+    const rerender = (properties: Record<string, unknown>, value = FILE) =>
+      view.rerender(
+        <VideoBlock
+          block={
+            {
+              id: 'campaign-film',
+              value,
+              properties: { ...customControls, ...properties }
+            } as any
+          }
+          placeholderId="p1"
+          sectionId="s1"
+          isDesigner={false}
+        />
+      );
+
+    expect(() => {
+      rerender({ customPlayPause: { desktop: false } });
+      rerender({ customPlayPause: { desktop: true } });
+      rerender({}, 'https://www.youtube.com/watch?v=abc123');
+      rerender({});
+    }).not.toThrow();
+    expect(view.container.querySelector('style')).not.toBeNull();
+  });
+});

package/src/blocks/video-block.tsx

@@ -1,13 +1,21 @@
 'use client';
 
-import React, { useEffect, useRef, useState } from 'react';
+import React, { useEffect, useId, useRef, useState } from 'react';
+import { useBrowseMode } from '../browse-mode';
 import {
   BREAKPOINTS,
+  MOBILE_MEDIA_QUERY_COMPACT,
   PHONE_AND_TABLET_MEDIA_CONDITION,
+  TABLET_MEDIA_QUERY_COMPACT,
+  builtInBreakpointOf,
   getResponsiveValue,
   isNarrowBreakpoint,
   partAttrs
 } from '../utils';
+import {
+  escapeCssAttributeValue,
+  neutralizeStyleTagBreakout
+} from '../utils/css-safety';
 import { BlockRendererProps } from './block-renderer-registry';
 import {
   resolveLocalizedValue,
@@ -59,6 +67,16 @@ interface VideoProperties {
   useDifferentMobileVideo?: unknown;
   mobileUrl?: unknown;
   mobilePoster?: unknown;
+  /**
+   * Where the control layer sits, per breakpoint: `top|middle|bottom` and
+   * `left|center|right`, joined (`bottom-right`). Absent means bottom-right,
+   * the corner it has always had.
+   */
+  controlPosition?: unknown;
+  /** px from the side it is anchored to, per breakpoint. Absent means the inset. */
+  controlOffsetX?: unknown;
+  /** px from the top or bottom edge, and from the screen's foot while it follows. */
+  controlOffsetY?: unknown;
 }
 
 /**
@@ -155,9 +173,22 @@ const SoundOnIcon = () => (
  */
 const VISIBILITY_PLAY_THRESHOLD = 0.1;
 
-/** The inset the control sits at, from the two corners it is anchored to. */
-const CONTROL_INSET_DESKTOP = '24px';
-const CONTROL_INSET_NARROW = '18px';
+/**
+ * The inset the control sits at, from the two corners it is anchored to, and
+ * the ceiling an authored distance is clamped to. The placement sheet paints
+ * these; the editor's distance sliders stop at the same 200 and show these two
+ * numbers for a breakpoint nothing was set at (`VIDEO_CONTROL_INSET` in
+ * pz-dynamic-widget) — change them together.
+ */
+const CONTROL_INSET_PX = { desktop: 24, narrow: 18 };
+const CONTROL_INSET_MAX_PX = 200;
+
+/**
+ * The same inset as the inline fallback the sheet overrides — what the control
+ * still sits at where the sheet does not reach (a browser without `:where()`).
+ */
+const CONTROL_INSET_DESKTOP = `${CONTROL_INSET_PX.desktop}px`;
+const CONTROL_INSET_NARROW = `${CONTROL_INSET_PX.narrow}px`;
 
 /**
  * Asked at the moment it matters rather than held in state: the answer is only
@@ -338,12 +369,226 @@ const firstUrlAtAnyBreakpoint = (value: unknown): string => {
   return '';
 };
 
+/** One half of `controlPosition`, as the flex keyword that puts the rail there. */
+const CONTROL_JUSTIFY: Record<string, string> = {
+  left: 'flex-start',
+  center: 'center',
+  right: 'flex-end'
+};
+const CONTROL_ALIGN: Record<string, string> = {
+  top: 'flex-start',
+  middle: 'center',
+  bottom: 'flex-end'
+};
+
+const isOwnKey = (record: Record<string, string>, key: string | undefined) =>
+  key !== undefined && Object.prototype.hasOwnProperty.call(record, key);
+
+/**
+ * The side a Control Overlay `justify-content` part key puts the rail on, or
+ * `undefined` when none is authored (or it is not a side this can name).
+ */
+const sideOfJustify = (value: unknown): string | undefined => {
+  if (value === 'flex-start' || value === 'start' || value === 'left') {
+    return 'left';
+  }
+  if (value === 'center') return 'center';
+  if (value === 'flex-end' || value === 'end' || value === 'right') {
+    return 'right';
+  }
+  return undefined;
+};
+
+/** `bottom-right` and its eight siblings; anything else is the corner it always had. */
+const readControlPosition = (value: unknown) => {
+  const [vertical, horizontal] =
+    typeof value === 'string' ? value.split('-') : [];
+  return {
+    vertical: isOwnKey(CONTROL_ALIGN, vertical) ? vertical : 'bottom',
+    horizontal: isOwnKey(CONTROL_JUSTIFY, horizontal) ? horizontal : 'right'
+  };
+};
+
+/**
+ * An authored distance in px, or the fallback.
+ *
+ * Numbers and numeric strings alike — the editor writes numbers, but a
+ * template, an import or a hand-edited theme can carry `'40'`, and a reader
+ * that only took `typeof === 'number'` would drop every one of them silently.
+ * A 0 is a distance, not an absence. Clamped to what the editor offers, so the
+ * page never draws a distance the panel cannot show.
+ */
+const readControlInset = (value: unknown, fallback: number): number => {
+  if (value === undefined || value === null || value === '') return fallback;
+  const parsed = typeof value === 'number' ? value : parseFloat(String(value));
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.min(CONTROL_INSET_MAX_PX, Math.max(0, Math.round(parsed)));
+};
+
+/** What one breakpoint band asks of the control layer. */
+interface ControlBand {
+  /** Overlay padding: the distance from the edges it is anchored to. */
+  padding: string;
+  /** The rail's sticky offset — the same distance, kept from the screen's foot. */
+  bottom: string;
+  /** Overlay `justify-content` (horizontal), only once a position is authored. */
+  justify?: string;
+  /** Column `justify-content` (vertical), only once a position is authored. */
+  align?: string;
+  /** Left anchors mirror the pair so play/pause keeps the outer corner. */
+  mirrored?: boolean;
+}
+
+const controlBandAt = (
+  properties: VideoProperties,
+  styles: Record<string, unknown> | undefined,
+  band: string,
+  placed: boolean
+): ControlBand => {
+  const inset = isNarrowBreakpoint(band)
+    ? CONTROL_INSET_PX.narrow
+    : CONTROL_INSET_PX.desktop;
+  const x = readControlInset(
+    getResponsiveValue(properties.controlOffsetX, band, undefined),
+    inset
+  );
+  const y = readControlInset(
+    getResponsiveValue(properties.controlOffsetY, band, undefined),
+    inset
+  );
+  const result: ControlBand = { padding: `${y}px ${x}px`, bottom: `${y}px` };
+  if (!placed) return result;
+
+  const { vertical, horizontal } = readControlPosition(
+    getResponsiveValue(properties.controlPosition, band, undefined)
+  );
+  result.justify = CONTROL_JUSTIFY[horizontal];
+  result.align = CONTROL_ALIGN[vertical];
+  /*
+   * Mirrored by the side the rail actually ends up on. A Horizontal Corner
+   * stored on the Control Overlay part outranks the preset's justify-content,
+   * so mirroring by the preset alone would put the sound button in the corner
+   * on exactly the blocks that have one. Only once a position is authored,
+   * though: a block that has nothing but a legacy Left keeps the order it
+   * renders in today.
+   */
+  const side =
+    sideOfJustify(
+      getResponsiveValue(styles?.['controls/justify-content'], band, undefined)
+    ) ?? horizontal;
+  if (side === 'left') result.mirrored = true;
+  return result;
+};
+
+/**
+ * The rules one band writes — only what differs from the band it inherits in
+ * the cascade, so a phone value equal to the desktop one is not written twice.
+ */
+const controlBandRules = (
+  scope: string,
+  band: ControlBand,
+  inherited?: ControlBand
+): string => {
+  const changed = (key: keyof ControlBand) =>
+    !inherited || band[key] !== inherited[key];
+
+  const overlay: string[] = [];
+  const column: string[] = [];
+  const rail: string[] = [];
+
+  if (changed('padding')) overlay.push(`padding:${band.padding}!important`);
+  if (band.justify && changed('justify')) {
+    overlay.push(`justify-content:${band.justify}!important`);
+  }
+  if (band.align && changed('align')) {
+    column.push(`justify-content:${band.align}!important`);
+  }
+  if (changed('bottom')) rail.push(`bottom:${band.bottom}!important`);
+  if (band.mirrored && changed('mirrored')) {
+    rail.push(
+      'flex-direction:row-reverse!important',
+      'reading-flow:flex-visual!important'
+    );
+  } else if (!band.mirrored && inherited?.mirrored) {
+    // Undo a wider band's mirror. Never written otherwise: the rail carries no
+    // inline flex-direction, so a merchant's own Custom CSS one wins today and
+    // an unconditional `row` here would silently take that away.
+    rail.push('flex-direction:row!important', 'reading-flow:normal!important');
+  }
+
+  const root = `[data-pz-video-controls="${scope}"]`;
+  return (
+    (overlay.length ? `:where(${root}){${overlay.join(';')}}` : '') +
+    (column.length ? `:where(${root}>div){${column.join(';')}}` : '') +
+    (rail.length
+      ? `:where(${root} [data-part="control-rail"]){${rail.join(';')}}`
+      : '')
+  );
+};
+
+/**
+ * WHERE THE CONTROL LAYER SITS, AS A STYLESHEET (ZERO-5177).
+ *
+ * `controlPosition` and the two distances are properties stored per
+ * breakpoint, and resolving them at `currentBreakpoint` into the inline styles
+ * would paint a phone with the desktop answer: that prop is `'desktop'` on the
+ * server and through a phone's first render. So they become CSS — every band at
+ * once with real media queries on the storefront, and the one band the editor
+ * is forcing whenever it is attached, editing or browsing (a custom breakpoint
+ * as the built-in band it stands on, since the storefront sheet only carries
+ * the built-in three — the canvas must not show what the page will not).
+ *
+ * Every selector is wrapped in `:where()` and every declaration is
+ * `!important`: specificity 0 beats nothing, so what this outranks is the
+ * renderer's own inline defaults — which no stylesheet rule can reach otherwise
+ * — and, for the properties it writes, any rule without `!important`, exactly
+ * as those inline values already did. Everything authored with an
+ * `!important` of its own still wins — the Control Overlay part keys
+ * (`[data-block-id] [data-part]`, 0,2,0), which are the fine-tuning on top of
+ * this, and any brand override that beats the inline styles today. The one
+ * property it writes that is NOT inline, the rail's flex-direction (with
+ * reading-flow), is therefore written only around a left anchor.
+ *
+ * The distances are written whatever was authored, because the default inset
+ * is per band too: the inline 24px is chosen from `currentBreakpoint` and a
+ * phone used to paint it before jumping to 18px.
+ */
+export const buildVideoControlSheet = (
+  scope: string,
+  properties: VideoProperties,
+  styles: Record<string, unknown> | undefined,
+  designerBand?: string
+): string => {
+  const placed = setAtAnyBreakpoint(properties.controlPosition);
+
+  if (designerBand) {
+    return controlBandRules(
+      scope,
+      controlBandAt(properties, styles, designerBand, placed)
+    );
+  }
+
+  const desktop = controlBandAt(properties, styles, 'desktop', placed);
+  const mobile = controlBandAt(properties, styles, 'mobile', placed);
+  const tablet = controlBandAt(properties, styles, 'tablet', placed);
+  const mobileRules = controlBandRules(scope, mobile, desktop);
+  // Tablet is written after mobile and inherits it, the generator's cascade.
+  const tabletRules = controlBandRules(scope, tablet, mobile);
+
+  return (
+    controlBandRules(scope, desktop) +
+    (mobileRules ? `${MOBILE_MEDIA_QUERY_COMPACT}{${mobileRules}}` : '') +
+    (tabletRules ? `${TABLET_MEDIA_QUERY_COMPACT}{${tabletRules}}` : '')
+  );
+};
+
 /**
  * A video: a YouTube or Vimeo embed, or a file the browser plays itself.
  *
  * Properties: url (on `block.value`), controls, autoplay, loop, muted,
  * playsInline, poster, sourceType, preload, playWhenVisible, customPlayPause,
- * soundToggle. Style: `aspect-ratio`.
+ * soundToggle, controlPosition, controlOffsetX, controlOffsetY. Style:
+ * `aspect-ratio`.
  */
 const VideoBlock = ({
   block,
@@ -351,6 +596,20 @@ const VideoBlock = ({
   currentBreakpoint = 'desktop'
 }: BlockRendererProps) => {
   const valueLocale = useValueLocale();
+  /*
+   * Two reads for the placement sheet, taken here with the other hooks:
+   * VideoBlock returns early further down (no URL, an embed, no custom
+   * control), so a hook beside the sheet would change the count whenever one
+   * of those flips.
+   *
+   * Browse mode is the editor still attached with its affordances off. Blocks
+   * get `isDesigner === false` there, but the canvas is still the editor's
+   * zoomed frame, and WebKit lays a zoomed desktop frame out at its zoomed
+   * width — a real media query answers "phone" on a desktop canvas. False on
+   * the server and through hydration, so it cannot split the markup.
+   */
+  const browsing = useBrowseMode();
+  const fallbackControlScope = useId();
   const localizedValue = resolveLocalizedValue(block.value, valueLocale);
   const desktopUrl = (
     typeof localizedValue === 'string' ? localizedValue : block.value
@@ -1011,6 +1270,13 @@ const VideoBlock = ({
   /**
    * THE CONTROL LAYER — BOTTOM RIGHT, AND STILL THERE ON A TALL CLIP.
    *
+   * Bottom right is the default, and what the inline styles below still draw.
+   * An author can move it (Button Position and the two distances, ZERO-5177):
+   * that arrives as the placement sheet, which overrides these inline values —
+   * see `buildVideoControlSheet`. A middle anchor keeps the sticky rail, so it
+   * rides the viewport floor until its own spot scrolls into view; a top
+   * anchor is already at the top of its column, where sticky has no room.
+   *
    * Still no wrapper around the VIDEO: `[data-block-id]` (rendered by
    * `WithDesignerFeatures`) is already `position: relative` and already carries
    * whatever height/position the author's block styles give it — a full-bleed
@@ -1032,7 +1298,8 @@ const VideoBlock = ({
    * being watched. Sticky keeps it the same inset above the viewport floor
    * until the real bottom comes into range, then parks it there. Where an
    * ancestor's `overflow: hidden` defeats sticky, it degrades to its static
-   * position, which is the bottom-right corner it was going to sit in anyway.
+   * position — the anchor it was placed at anyway (bottom right unless Button
+   * Position says otherwise).
    *
    * Both outer boxes are `pointer-events: none` — the overlay covers the whole
    * player, and the shopper must still be able to click a link sitting under
@@ -1062,11 +1329,37 @@ const VideoBlock = ({
     pointerEvents: 'auto'
   };
 
+  /*
+   * Where the author put the layer — see `buildVideoControlSheet`. Scoped by
+   * the block id the way every other scoped sheet in this package is: data, so
+   * the server and the first client render name the same scope. A block with
+   * no id (only tests and hand-built trees render one) falls back to `useId`,
+   * so two of them never share a sheet. The raw id goes on the element and the
+   * escaped one in the selector.
+   *
+   * The `<style>` sits BEFORE the overlay so the overlay stays the wrapper's
+   * last child — the generator's root hover rule reaches the buttons through
+   * `> div:last-child button`.
+   */
+  const controlScope = String(block.id || fallbackControlScope);
+  const controlSheet = buildVideoControlSheet(
+    escapeCssAttributeValue(controlScope),
+    properties,
+    block.styles as Record<string, unknown> | undefined,
+    isDesigner || browsing ? builtInBreakpointOf(currentBreakpoint) : undefined
+  );
+
   return (
     <>
       {videoElement}
+      <style
+        dangerouslySetInnerHTML={{
+          __html: neutralizeStyleTagBreakout(controlSheet)
+        }}
+      />
       <div
         {...partAttrs('controls')}
+        data-pz-video-controls={controlScope}
         style={{
           position: 'absolute',
           inset: 0,