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

package/src/blocks/video-block.tsx

@@ -5,7 +5,8 @@ import {
   BREAKPOINTS,
   PHONE_AND_TABLET_MEDIA_CONDITION,
   getResponsiveValue,
-  isNarrowBreakpoint
+  isNarrowBreakpoint,
+  partAttrs
 } from '../utils';
 import { BlockRendererProps } from './block-renderer-registry';
 
@@ -38,27 +39,132 @@ interface VideoProperties {
   sourceType?: string;
   /** Gated on `controls === false` in the editor — it replaces native controls, not add to them. */
   customPlayPause?: unknown;
+  /** Second control beside play/pause. Off by default: an ambient clip is silent furniture. */
+  soundToggle?: unknown;
+  /** One glyph per state the control can be in. Empty means "keep ours". */
+  playIcon?: unknown;
+  pauseIcon?: unknown;
+  soundOnIcon?: unknown;
+  soundOffIcon?: unknown;
+  /** On by default — see the observer effect for what "ambient" means here. */
+  playWhenVisible?: unknown;
+  /** `auto` | `metadata` | `none`, straight through to the element's attribute. */
+  preload?: unknown;
   /** Off by default: mobile plays the same file as desktop unless this is on. */
   useDifferentMobileVideo?: unknown;
   mobileUrl?: unknown;
   mobilePoster?: unknown;
 }
 
-/** Sized for a 20x20 button — the Figma control, not a generic icon glyph. */
+/**
+ * An OUTLINED triangle, not a solid one: one path that fills the triangle and
+ * then cuts a smaller one out of it, so the glyph reads as a hairline at 8px
+ * the way the pause bars beside it do. A solid wedge at this size turns into
+ * an ink blob next to two 1px rules.
+ */
 const PlayIcon = () => (
-  <svg width="6" height="8" viewBox="0 0 6 8" fill="none" aria-hidden="true">
-    <path d="M0.5 0.5L5.5 4L0.5 7.5V0.5Z" fill="currentColor" />
+  <svg width="8" height="8" viewBox="0 0 8 8" fill="none" aria-hidden="true">
+    <path fill="currentColor" d="M7 4 1 8V0zM2 6.13 5.197 4 2 1.868z" />
   </svg>
 );
 
-/** Two 1x8 bars, centered in the button by its own flex layout. */
+/** Two 1x8 bars at the outer edges of the 8x8 box, to the play glyph's weight. */
 const PauseIcon = () => (
-  <svg width="5" height="8" viewBox="0 0 5 8" fill="none" aria-hidden="true">
-    <rect x="0" y="0" width="1" height="8" fill="currentColor" />
-    <rect x="4" y="0" width="1" height="8" fill="currentColor" />
+  <svg width="8" height="8" viewBox="0 0 8 8" fill="currentColor" aria-hidden="true">
+    <path d="M1.5 8h-1V0h1zm6 0h-1V0h1z" />
+  </svg>
+);
+
+/**
+ * AN AUTHORED GLYPH, PAINTED BY WHATEVER THE PANEL PUT ON THE BUTTON.
+ *
+ * A mask rather than an `<img>`, and rather than the SVG-rewriting the icon
+ * block and the slider both do. Those two read a colour off the block's own
+ * styles and bake it into the SVG string before handing it over — which cannot
+ * work here, because this button's colour is a PART style: it is emitted as
+ * CSS (`[data-block-id=…] [data-part="control-button"]{color:…}`) and the
+ * renderer never sees the value. A mask filled with `currentColor` inherits
+ * whatever that rule resolved to, so an authored glyph answers Text Color
+ * exactly the way the four built-in ones do.
+ *
+ * The trade is that a multi-colour icon arrives monochrome. For a 20px control
+ * that is the right way round — the alternative is a glyph that ignores the
+ * brand colour the panel just set, on the one element whose whole job is to be
+ * legible against the film behind it.
+ */
+const AuthoredGlyph = ({ src }: { src: string }) => (
+  <span
+    aria-hidden="true"
+    style={{
+      display: 'block',
+      width: '100%',
+      height: '100%',
+      backgroundColor: 'currentColor',
+      WebkitMaskImage: `url("${src}")`,
+      maskImage: `url("${src}")`,
+      WebkitMaskRepeat: 'no-repeat',
+      maskRepeat: 'no-repeat',
+      WebkitMaskPosition: 'center',
+      maskPosition: 'center',
+      // `contain`, not `cover`: a glyph that overflows its 20px button reads as
+      // a smear, and an author's icon is rarely the same aspect as ours.
+      WebkitMaskSize: 'contain',
+      maskSize: 'contain'
+    }}
+  />
+);
+
+/** Speaker with the sound arc struck through — the clip is silent right now. */
+const SoundOffIcon = () => (
+  <svg width="8" height="8" viewBox="0 0 8 8" fill="none" aria-hidden="true">
+    <path fill="currentColor" d="M0 3h1.4L3.4 1v6L1.4 5H0z" />
+    <path
+      stroke="currentColor"
+      strokeWidth="0.8"
+      strokeLinecap="round"
+      d="m5.2 2.8 2 2.4m0-2.4-2 2.4"
+    />
+  </svg>
+);
+
+/** The same speaker, arc intact. */
+const SoundOnIcon = () => (
+  <svg width="8" height="8" viewBox="0 0 8 8" fill="none" aria-hidden="true">
+    <path fill="currentColor" d="M0 3h1.4L3.4 1v6L1.4 5H0z" />
+    <path
+      stroke="currentColor"
+      strokeWidth="0.8"
+      strokeLinecap="round"
+      d="M5.2 2.5a2.1 2.1 0 0 1 0 3M6.6 1.6a3.6 3.6 0 0 1 0 4.8"
+    />
   </svg>
 );
 
+/**
+ * The share of the player that has to be on screen before it plays, and below
+ * which it pauses again.
+ *
+ * Measured against the reference storefront rather than picked: its own
+ * observer is built with `threshold: 0.1`, and stepping a clip out of view
+ * there confirms the edge — still playing at 15% visible, paused at 8%.
+ */
+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';
+
+/**
+ * Asked at the moment it matters rather than held in state: the answer is only
+ * ever consulted inside an effect, and a shopper who changes this setting
+ * mid-visit is not a case worth a subscription. Same spelling — spaces and all
+ * — as `collapsible-block.tsx`, which is the other runtime reader.
+ */
+const prefersReducedMotion = () =>
+  typeof window !== 'undefined' &&
+  typeof window.matchMedia === 'function' &&
+  window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+
 /** Hosts, not substrings: `evil.com/?u=youtube.com/watch?v=x` is not YouTube. */
 const YOUTUBE_HOSTS = /(^|\.)(youtube\.com|youtube-nocookie\.com|youtu\.be)$/i;
 
@@ -220,10 +326,12 @@ const firstUrlAtAnyBreakpoint = (value: unknown): string => {
  * 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. Style: `aspect-ratio`.
+ * playsInline, poster, sourceType, preload, playWhenVisible, customPlayPause,
+ * soundToggle. Style: `aspect-ratio`.
  */
 const VideoBlock = ({
   block,
+  isDesigner = false,
   currentBreakpoint = 'desktop'
 }: BlockRendererProps) => {
   const desktopUrl = block.value as string;
@@ -343,19 +451,265 @@ const VideoBlock = ({
     !nativeControls &&
     !!getResponsiveValue(properties.customPlayPause, currentBreakpoint, false);
 
+  /**
+   * The four glyphs, each falling back to the built-in one.
+   *
+   * Read per breakpoint like every other authored value, so a brand can carry
+   * a different mark on the phone — the control is 18px from the edge there
+   * rather than 24, and a busier glyph stops reading at that size.
+   */
+  const authoredGlyph = (key: keyof VideoProperties) =>
+    (getResponsiveValue(properties[key], currentBreakpoint, '') as string) || '';
+
+  const glyphFor = (key: keyof VideoProperties, fallback: React.ReactNode) => {
+    const src = authoredGlyph(key);
+    return src ? <AuthoredGlyph src={src} /> : fallback;
+  };
+
+  /** The mute button rides with the play/pause one; it cannot appear alone. */
+  const showSoundToggle =
+    customPlayPause &&
+    !!getResponsiveValue(properties.soundToggle, currentBreakpoint, false);
+
+  /**
+   * DOES THIS CLIP PLAY BY ITSELF?
+   *
+   * `Boolean(properties.autoplay)`, raw and unresolved, on purpose: it is the
+   * SAME expression the `autoPlay` attribute below is written with, and the
+   * point is that the two can never disagree. The note further down records
+   * why that attribute still reads raw — the editor stores `{ desktop: false }`,
+   * an object is truthy, and reading it correctly would switch autoplay off on
+   * every composition already published. Until that is done under its own
+   * ticket, "would this have played on its own?" has exactly one answer, and
+   * asking it any other way here would arm the observer on clips the page does
+   * not currently start, or fail to arm it on the ones it does.
+   */
+  const wantsAutoplay = Boolean(properties.autoplay);
+
+  const playWhenVisible =
+    getResponsiveValue(properties.playWhenVisible, currentBreakpoint, true) !==
+    false;
+
+  /**
+   * "Ambient": a clip the page starts on the shopper's behalf, with no controls
+   * of its own — the campaign film behind a headline. Only those are driven by
+   * the viewport.
+   *
+   * `!nativeControls` is the load-bearing half of that sentence, and leaving it
+   * out was a real regression rather than a nicety. `wantsAutoplay` is truthy
+   * for EVERY block the editor has ever written (see above), so without it the
+   * observer armed on ordinary videos that show the browser's own control bar:
+   * a shopper who pressed pause at 0:30, scrolled the player off screen and
+   * scrolled back would find it playing again, because this observer
+   * deliberately does not remember a manual pause. A player with controls is a
+   * deliberate watch; it is left entirely alone.
+   *
+   * `nativeControls` IS read per breakpoint, so this gate is exact even while
+   * the autoplay read next to it is not.
+   */
+  const ambientPlayback =
+    wantsAutoplay && !nativeControls && playWhenVisible && !isDesigner;
+
   const videoRef = useRef<HTMLVideoElement>(null);
-  const [isPlaying, setIsPlaying] = useState(properties.autoplay === true);
 
-  const togglePlayback = () => {
+  /**
+   * What the GLYPH says, which is not the same as what the author asked for.
+   *
+   * An ambient clip starts at `false` because nothing has started it yet: it
+   * carries no autoplay attribute, and the observer only presses play once the
+   * clip is on screen — the `play` event flips this within a frame of that.
+   * Seeding it `true` there meant the control drew the pause bars and announced
+   * "Pause video" over a clip standing still, and stayed that way for good
+   * wherever playback never began at all: a reduced-motion shopper, an iPhone
+   * in Low Power Mode refusing even a muted start, a 404 on the file. None of
+   * those fire a `pause` event to correct it, because the element was already
+   * paused.
+   *
+   * Everything else keeps the attribute and really does start on its own, so
+   * `wantsAutoplay` is the honest first answer there.
+   */
+  const [isPlaying, setIsPlaying] = useState(
+    ambientPlayback ? false : wantsAutoplay
+  );
+
+  /**
+   * Whether the observer last saw this player on screen.
+   *
+   * A ref rather than state because the only reader is the src-swapping effect
+   * below, and re-rendering the player every time a clip scrolls past would be
+   * a lot of work to change nothing. See that effect for why it has to ask.
+   */
+  const isInViewRef = useRef(false);
+
+  /**
+   * Starts false on the server AND on the first client render, which is what
+   * keeps `preload` hydratable: both sides ship `none`, and only the observer
+   * moves it. See the preload note on the element itself.
+   */
+  const [hasEnteredView, setHasEnteredView] = useState(false);
+
+  const mutedProperty = Boolean(properties.muted);
+  const [isMuted, setIsMuted] = useState(mutedProperty);
+
+  /*
+   * The author flipping Muted has to win over whatever the shopper's sound
+   * button last did. Worth knowing what this can and cannot reach: the stored
+   * value is per-breakpoint for anything the editor wrote, and `Boolean()` of
+   * an object is a constant, so for those blocks this never fires — the same
+   * raw read the autoplay note above explains, and it moves with that ticket.
+   * It does work for the flat booleans templates and HTML import write.
+   */
+  useEffect(() => {
+    setIsMuted(mutedProperty);
+  }, [mutedProperty]);
+
+  /**
+   * `play()` returns a promise that REJECTS when the browser declines — an
+   * unmuted clip with no user gesture, or one interrupted by a `pause()` a
+   * frame later. Every call site swallows it: a refused play is a poster
+   * sitting still, not an error worth an unhandled rejection in the console.
+   */
+  const requestPlay = (el: HTMLVideoElement) => {
+    const started = el.play();
+    if (started && typeof started.catch === 'function') {
+      started.catch(() => undefined);
+    }
+  };
+
+  /**
+   * THE CONTROL IS NOT PART OF THE BLOCK'S ACTION.
+   *
+   * `WithDesignerFeatures` puts the block's own click handler on the
+   * `[data-block-id]` wrapper whenever an Action is set, and `video` is not in
+   * `NATIVELY_INTERACTIVE_BLOCK_TYPES`, so it gets one. A campaign tile built
+   * as a Video block with Action = Link therefore navigated away the moment a
+   * shopper tapped pause: the video paused and the click carried on up. Note
+   * that `pointerEvents: 'auto'` on the buttons governs hit-testing only — it
+   * has never had anything to say about propagation.
+   *
+   * NOT in the designer, though, and that exception is the whole of why this
+   * is a function rather than one call. The canvas resolves which PART was
+   * clicked from a single bubble handler on that same wrapper
+   * (`use-designer-features`), so stopping the click unconditionally meant a
+   * click on the button selected NOTHING — not the Control Button part, not
+   * even the Video block. `hotspot-block.tsx` returns early on `isDesigner`
+   * for exactly this reason, and this follows it.
+   */
+  const stopBubbling = (event: React.MouseEvent) => {
+    if (isDesigner) return;
+    event.stopPropagation();
+  };
+
+  const togglePlayback = (event: React.MouseEvent) => {
+    stopBubbling(event);
     const el = videoRef.current;
     if (!el) return;
     if (el.paused) {
-      el.play();
+      requestPlay(el);
     } else {
       el.pause();
     }
   };
 
+  const toggleSound = (event: React.MouseEvent) => {
+    stopBubbling(event);
+    const el = videoRef.current;
+    const next = !isMuted;
+    setIsMuted(next);
+    // Written straight to the element as well: React sets `muted` as a DOM
+    // PROPERTY and never emits it as an attribute, so a re-render alone is not
+    // guaranteed to reach an element the browser is already playing.
+    if (el) el.muted = next;
+  };
+
+  /**
+   * PLAY WHILE IT IS ON SCREEN; STOP WHEN IT LEAVES.
+   *
+   * An `autoPlay` attribute starts a clip the moment it is parsed, wherever it
+   * sits on the page — so a homepage with three of them decodes three films at
+   * once, two of which nobody has scrolled to. This binds playback to the
+   * viewport instead, which is both the behaviour the reference storefront has
+   * and the reason a long page stays cheap.
+   *
+   * Three things are deliberate:
+   *
+   * - `pause()` on the way out does NOT touch `currentTime`. Scrolling back
+   *   resumes where the clip stopped, measured as the reference behaviour.
+   * - A manual pause is NOT remembered across a scroll-out. The observer is
+   *   authoritative; the button is an override that lasts while the clip is on
+   *   screen. Also measured — pausing by hand, scrolling away and back plays
+   *   again there too.
+   * - It stands down in the designer (`isDesigner`, folded into
+   *   `ambientPlayback`), the way every other observer- or timer-driven
+   *   affordance in this package does. The canvas keeps whatever the `autoPlay`
+   *   attribute already gave it, so authoring is unchanged.
+   *
+   * Both escape hatches below flip `hasEnteredView` before returning. The
+   * element is holding `preload="none"` waiting for this effect, so bailing out
+   * without doing so would leave a clip that never loads at all.
+   */
+  useEffect(() => {
+    if (!ambientPlayback) return undefined;
+
+    const el = videoRef.current;
+    if (!el) return undefined;
+
+    if (typeof IntersectionObserver === 'undefined') {
+      // Nothing else is going to start this clip — an ambient one ships no
+      // `autoplay` attribute precisely so that this effect owns the decision —
+      // so the fallback has to both release the file and press play itself.
+      setHasEnteredView(true);
+      requestPlay(el);
+      return undefined;
+    }
+
+    if (prefersReducedMotion()) {
+      // Release the file so the shopper can still press play; just never start
+      // it for them. `pause()` covers the case where something else already
+      // had it running before this effect re-ran.
+      setHasEnteredView(true);
+      el.pause();
+      return undefined;
+    }
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        // The LAST entry, not the first: a burst delivered after a fast scroll
+        // describes where the element ended up, and acting on the head of it
+        // would play a clip that has already gone.
+        const entry = entries[entries.length - 1];
+        if (!entry) return;
+
+        isInViewRef.current = entry.isIntersecting;
+
+        if (entry.isIntersecting) {
+          setHasEnteredView(true);
+          requestPlay(el);
+        } else {
+          el.pause();
+        }
+      },
+      { threshold: VISIBILITY_PLAY_THRESHOLD }
+    );
+
+    observer.observe(el);
+    return () => {
+      observer.disconnect();
+      isInViewRef.current = false;
+    };
+    /*
+     * `parsed?.kind` is in the list because this effect reads `videoRef.current`
+     * and gives up silently when it is null — and which ELEMENT gets rendered
+     * is breakpoint-dependent. An author who pastes a YouTube link and uploads
+     * an mp4 for phones gets the `<iframe>` branch on the first client render
+     * (currentBreakpoint is the literal 'desktop' until a post-mount effect
+     * says otherwise); the `<video>` only appears on the render after that.
+     * Without this the effect never runs again, and that clip spends the rest
+     * of the page's life at `preload="none"` with nothing watching the
+     * viewport — the feature simply absent, with nothing to show for it.
+     */
+  }, [ambientPlayback, parsed?.kind]);
+
   /**
    * THE FILE, NAMED BY THE SIDE THAT KNOWS THE VIEWPORT.
    *
@@ -420,11 +774,30 @@ const VideoBlock = ({
 
     el.setAttribute('src', next);
     el.load();
+
+    /*
+     * `load()` RESETS THE PLAYER, SO WHOEVER WAS PLAYING HAS TO BE RESTARTED.
+     *
+     * The observer above only speaks when the clip CROSSES its threshold. It
+     * has nothing to say about a clip that was already on screen and stayed
+     * there — which is exactly the case here: this effect runs on mount before
+     * the first intersection is delivered, and again whenever a resize or a
+     * rotation crosses 1024px. Both leave a freshly reset, paused element
+     * sitting in full view with no further intersection coming to start it.
+     *
+     * The `autoPlay` attribute is not a substitute. Its "can autoplay" flag is
+     * cleared the first time the element is paused or played, so a clip that
+     * has already been on screen once does not get a second free start from it.
+     */
+    if (ambientPlayback && isInViewRef.current) {
+      requestPlay(el);
+    }
   }, [
     hasDistinctMobileVideo,
     currentBreakpoint,
     mobileUrlAnywhere,
-    desktopUrl
+    desktopUrl,
+    ambientPlayback
   ]);
 
   /**
@@ -458,6 +831,28 @@ const VideoBlock = ({
     'cover'
   ) as React.CSSProperties['objectFit'];
 
+  /**
+   * HOW MUCH OF THE FILE TO FETCH BEFORE ANYONE ASKS FOR IT.
+   *
+   * The element carried no `preload` at all until now, so every browser fell
+   * back to its own default — in practice `metadata`, and on some builds
+   * `auto` — and a clip five screens down the homepage started downloading
+   * with the page. `metadata` is the new floor: enough for the box and the
+   * first frame, a few kilobytes rather than the film.
+   *
+   * On top of that, an ambient clip ships `none` until the observer above says
+   * it has reached the viewport. That is the whole of the lazy story, and it
+   * costs the poster nothing: `poster` is an image the element paints whatever
+   * `preload` says, so the box is never empty while the file is being skipped.
+   */
+  const authoredPreload = getResponsiveValue(
+    properties.preload,
+    currentBreakpoint,
+    'metadata'
+  ) as string;
+  const preload =
+    ambientPlayback && !hasEnteredView ? 'none' : authoredPreload;
+
   if (!videoUrl || !parsed) {
     return (
       <div
@@ -522,9 +917,28 @@ const VideoBlock = ({
       ref={videoRef}
       src={hasDistinctMobileVideo ? undefined : parsed.src}
       controls={nativeControls}
-      autoPlay={properties.autoplay}
+      /*
+       * ONE STARTER, NOT TWO.
+       *
+       * An ambient clip ships NO autoplay attribute: the observer above starts
+       * it, and this is what makes `preload="none"` beside it mean anything.
+       * The HTML spec lets the autoplay attribute override preload, and both
+       * Blink and Gecko take it — an element carrying both downloaded the whole
+       * film at parse time and deferred only the playing of it, which is the
+       * opposite of the saving this is for. It also ended the fight between two
+       * drivers: `load()` in the src-swapping effect below re-arms the
+       * attribute's can-autoplay flag, which used to restart a clip the
+       * reduced-motion branch had just stood down.
+       *
+       * The cost is that an ambient clip does not start with JavaScript off. It
+       * could never have stopped without it either, and the poster still paints.
+       */
+      autoPlay={ambientPlayback ? undefined : properties.autoplay}
       loop={properties.loop}
-      muted={properties.muted}
+      // Seeded from `Boolean(properties.muted)` — the same truthiness the raw
+      // read had — and thereafter owned by the sound button, when there is one.
+      muted={isMuted}
+      preload={preload}
       poster={posterUrl || undefined}
       // Without it iOS opens the video full screen, which is never what an
       // inline background clip is for. Left reading `properties.playsInline`
@@ -573,13 +987,34 @@ const VideoBlock = ({
   }
 
   /**
-   * No wrapper `<div>` around the video: `[data-block-id]` (rendered by
-   * `WithDesignerFeatures`) is already `position: relative` and already
-   * carries whatever height/position the author's block styles give it — a
-   * full-bleed hero video is sized THERE, not by the `<video>` tag's own
-   * intrinsic box. A wrapper here would only get the video's natural
-   * (usually much shorter) height, so `bottom: 0` landed the button near the
-   * top of the actually-visible video and clipped most of it away.
+   * THE CONTROL LAYER — BOTTOM RIGHT, AND STILL THERE ON A TALL CLIP.
+   *
+   * 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
+   * hero is sized THERE, not by the `<video>` tag's own intrinsic box, and
+   * wrapping the player would hand the controls the player's natural (usually
+   * much shorter) height instead. What is added here is a SIBLING overlay,
+   * `inset: 0` against that same wrapper, so it inherits the authored box
+   * exactly the way the single absolute button used to.
+   *
+   * Three nested boxes, because one absolutely positioned button cannot do it:
+   *
+   *   overlay   inset 0, flex, justify-content flex-end   -> the right edge
+   *     column  flex column, justify-content flex-end     -> the bottom edge
+   *       rail  position: sticky, bottom: <inset>         -> stays reachable
+   *
+   * The sticky rail is what a 2:3 portrait clip needs. At 749px wide that box
+   * is 1123px tall — taller than most laptop viewports — so a control pinned
+   * to the bottom of the block is off screen for the whole time the clip is
+   * 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.
+   *
+   * 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
+   * it. Only the buttons take pointer events back.
    *
    * `zIndex: 2` because a sibling content-overlay block (title/CTA on top of
    * the video) is a full-size `position: absolute; z-index: 1` box — its
@@ -587,39 +1022,88 @@ const VideoBlock = ({
    * higher z-index here the overlay wins hit-testing and swallows the click
    * even where the button is visually on top of it.
    */
-  // Desktop: bottom-left, flush to the bottom edge, inset from the left.
-  // Mobile: top-right instead — the design moves it off the bottom-left
-  // corner entirely rather than just rescaling the same inset.
-  const buttonPosition: React.CSSProperties = isMobile
-    ? { top: '18px', right: '18px' }
-    : { bottom: 0, left: '24px' };
+  const controlInset = isMobile ? CONTROL_INSET_NARROW : CONTROL_INSET_DESKTOP;
+
+  const controlButtonStyle: React.CSSProperties = {
+    width: '20px',
+    height: '20px',
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    background: '#fff',
+    border: 'none',
+    borderRadius: 0,
+    padding: 0,
+    margin: 0,
+    cursor: 'pointer',
+    color: '#000',
+    pointerEvents: 'auto'
+  };
 
   return (
     <>
       {videoElement}
-      <button
-        type="button"
-        onClick={togglePlayback}
-        aria-label={isPlaying ? 'Pause video' : 'Play video'}
-        aria-pressed={isPlaying}
+      <div
+        {...partAttrs('controls')}
         style={{
           position: 'absolute',
-          ...buttonPosition,
+          inset: 0,
           zIndex: 2,
-          width: '20px',
-          height: '20px',
           display: 'flex',
-          alignItems: 'center',
-          justifyContent: 'center',
-          background: 'rgba(255, 255, 255, 0.9)',
-          border: 'none',
-          padding: 0,
-          cursor: 'pointer',
-          color: '#111'
+          justifyContent: 'flex-end',
+          padding: controlInset,
+          pointerEvents: 'none',
+          borderRadius: 'inherit'
         }}
       >
-        {isPlaying ? <PauseIcon /> : <PlayIcon />}
-      </button>
+        <div
+          style={{
+            display: 'flex',
+            flexDirection: 'column',
+            justifyContent: 'flex-end',
+            pointerEvents: 'none'
+          }}
+        >
+          <div
+            {...partAttrs('control-rail')}
+            style={{
+              position: 'sticky',
+              bottom: controlInset,
+              display: 'flex',
+              alignItems: 'center',
+              gap: '8px',
+              pointerEvents: 'none'
+            }}
+          >
+            {showSoundToggle && (
+              <button
+                type="button"
+                {...partAttrs('control-button')}
+                onClick={toggleSound}
+                aria-label={isMuted ? 'Unmute video' : 'Mute video'}
+                aria-pressed={!isMuted}
+                style={controlButtonStyle}
+              >
+                {isMuted
+                  ? glyphFor('soundOffIcon', <SoundOffIcon />)
+                  : glyphFor('soundOnIcon', <SoundOnIcon />)}
+              </button>
+            )}
+            <button
+              type="button"
+              {...partAttrs('control-button')}
+              onClick={togglePlayback}
+              aria-label={isPlaying ? 'Pause video' : 'Play video'}
+              aria-pressed={isPlaying}
+              style={controlButtonStyle}
+            >
+              {isPlaying
+                ? glyphFor('pauseIcon', <PauseIcon />)
+                : glyphFor('playIcon', <PlayIcon />)}
+            </button>
+          </div>
+        </div>
+      </div>
     </>
   );
 };