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

package/CHANGELOG.md

@@ -1,12 +1,12 @@
 # @akinon/pz-theme
 
-## 2.0.118-beta.0
+## 2.0.118
 
 ### Patch Changes
 
-- Updated dependencies [cbbbfd757]
-  - @akinon/next@2.0.118-beta.0
-  - @akinon/theme-contract@2.0.118-beta.0
+- a58283b: Give a phone the mobile video at the first paint: let the player fill the box the stylesheet already shaped instead of re-declaring it from a breakpoint the server cannot know, and name the single file the viewport needs on the client, so a block with a separate mobile clip no longer ships the desktop one to every phone
+  - @akinon/next@2.0.118
+  - @akinon/theme-contract@2.0.118
 
 ## 2.0.117
 

package/jest/setup.ts

@@ -25,6 +25,17 @@ if (hasWindow) {
   window.scrollTo = (() => {}) as typeof window.scrollTo;
 }
 
+// jsdom declares the media methods but implements none of them: calling one
+// prints a "Not implemented" error through the virtual console, which turns any
+// component that drives a player on mount into noise in an otherwise passing
+// run. No test asserts on playback itself — only on which file the element was
+// pointed at — so no-ops are the honest shim.
+if (hasWindow && typeof HTMLMediaElement !== 'undefined') {
+  HTMLMediaElement.prototype.load = () => {};
+  HTMLMediaElement.prototype.play = () => Promise.resolve();
+  HTMLMediaElement.prototype.pause = () => {};
+}
+
 // `react-dom/server` builds a MessageChannel at module scope, and jsdom has
 // none — importing it in a jsdom suite throws before a single test runs. Node's
 // own MessageChannel is not the answer: its ports keep the event loop alive, so

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

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

@@ -1,7 +1,36 @@
 import React from 'react';
 import { render, screen } from '@testing-library/react';
+import { renderToStaticMarkup } from 'react-dom/server';
 import VideoBlock from '../video-block';
 
+/**
+ * Stand the test in a viewport band.
+ *
+ * Outside the editor the VIEWPORT decides which file plays, not the breakpoint
+ * prop — the prop is still `'desktop'` when a phone paints for the first time,
+ * which is exactly what used to put the landscape clip in every phone's HTML.
+ * jsdom's `matchMedia` shim always answers `false`, so a storefront test has to
+ * say which band it is standing in.
+ */
+const withViewport = (narrow: boolean, run: () => void) => {
+  const original = window.matchMedia;
+  window.matchMedia = ((query: string) => ({
+    matches: narrow && query.includes('max-width'),
+    media: query,
+    onchange: null,
+    addListener: () => {},
+    removeListener: () => {},
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    dispatchEvent: () => false
+  })) as unknown as typeof window.matchMedia;
+  try {
+    run();
+  } finally {
+    window.matchMedia = original;
+  }
+};
+
 const renderBlock = (value: any, properties?: any, styles?: any) =>
   render(
     <VideoBlock
@@ -440,14 +469,22 @@ describe('VideoBlock', () => {
       expect(iframe.style.height).toBe('auto');
     });
 
-    it('shapes a direct file too', () => {
+    it('leaves a direct file to the box the stylesheet already shaped', () => {
+      // The opposite of the iframe above, and deliberately so. A file player
+      // sits inside `[data-block-id]`, and `generateThemeCSS` has already put
+      // the author's ratio THERE, per breakpoint, as a real media query — right
+      // at the first paint with no JavaScript. Re-resolving it here at
+      // `currentBreakpoint` (the literal 'desktop' on the server and through a
+      // phone's first render) and inlining it is what beat that media query and
+      // left a 9/16 box 693px tall holding a 192px player over 500px of white.
       const { container } = renderBlock(
         'https://cdn.example.com/clip.mp4',
         undefined,
         { 'aspect-ratio': { desktop: '9/16' } }
       );
       const video = container.querySelector('video') as HTMLVideoElement;
-      expect(video.style.aspectRatio).toBe('9/16');
+      expect(video.style.getPropertyValue('aspect-ratio')).toBe('');
+      expect(video.style.height).toBe('100%');
       expect(video.style.objectFit).toBe('cover');
     });
   });
@@ -468,6 +505,18 @@ describe('VideoBlock', () => {
       expect(video.style.height).toBe('100%');
     });
 
+    it('fills its box unconditionally, without asking the breakpoint', () => {
+      // Measured in WebKit, Gecko and Blink: where nothing sizes the wrapper a
+      // percentage height resolves to `auto`, so an unsized block behaves
+      // exactly as it always did. Asking `currentBreakpoint` whether the box
+      // was sized would reintroduce the defect, because the answer differs
+      // between the server and the phone's first paint.
+      const { container } = renderBlock('https://cdn.example.com/clip.mp4');
+      const video = container.querySelector('video') as HTMLVideoElement;
+      expect(video.style.height).toBe('100%');
+      expect(video.style.getPropertyValue('aspect-ratio')).toBe('');
+    });
+
     it('defaults Object Fit to cover even without an authored aspect ratio', () => {
       const { container } = renderBlock('https://cdn.example.com/clip.mp4');
       const video = container.querySelector('video') as HTMLVideoElement;
@@ -519,36 +568,146 @@ describe('VideoBlock', () => {
       ).toBe('https://cdn.example.com/desktop.mp4');
     });
 
-    it('plays the mobile file on mobile when useDifferentMobileVideo is on', () => {
-      const { container } = renderAt(
-        'https://cdn.example.com/desktop.mp4',
-        {
-          useDifferentMobileVideo: true,
-          mobileUrl: 'https://cdn.example.com/mobile.mp4'
-        },
-        'mobile'
-      );
-      expect(
-        (container.querySelector('video') as HTMLVideoElement).src
-      ).toBe('https://cdn.example.com/mobile.mp4');
+    it('plays the mobile file on a phone when useDifferentMobileVideo is on', () => {
+      withViewport(true, () => {
+        const { container } = renderAt(
+          'https://cdn.example.com/desktop.mp4',
+          {
+            useDifferentMobileVideo: true,
+            mobileUrl: 'https://cdn.example.com/mobile.mp4'
+          },
+          'mobile'
+        );
+        expect(
+          (container.querySelector('video') as HTMLVideoElement).src
+        ).toBe('https://cdn.example.com/mobile.mp4');
+      });
     });
 
     it('plays the mobile file on a tablet too, the way the CSS already does', () => {
       // The mobile media query is max-width: 1023px, so at 800px every style
-      // around this player is already the mobile one. Reading the source with
-      // `=== 'mobile'` left the tablet on the landscape clip inside a layout
-      // that had gone vertical.
-      const { container } = renderAt(
-        'https://cdn.example.com/desktop.mp4',
-        {
-          useDifferentMobileVideo: true,
-          mobileUrl: 'https://cdn.example.com/mobile.mp4'
-        },
-        'tablet'
+      // around this player is already the mobile one. The condition the source
+      // is chosen with is that same band, so a tablet cannot drift off it.
+      withViewport(true, () => {
+        const { container } = renderAt(
+          'https://cdn.example.com/desktop.mp4',
+          {
+            useDifferentMobileVideo: true,
+            mobileUrl: 'https://cdn.example.com/mobile.mp4'
+          },
+          'tablet'
+        );
+        expect((container.querySelector('video') as HTMLVideoElement).src).toBe(
+          'https://cdn.example.com/mobile.mp4'
+        );
+      });
+    });
+
+    it('keeps the desktop file on a desktop viewport', () => {
+      withViewport(false, () => {
+        const { container } = renderAt(
+          'https://cdn.example.com/desktop.mp4',
+          {
+            useDifferentMobileVideo: true,
+            mobileUrl: 'https://cdn.example.com/mobile.mp4'
+          },
+          'desktop'
+        );
+        expect(
+          (container.querySelector('video') as HTMLVideoElement).src
+        ).toBe('https://cdn.example.com/desktop.mp4');
+      });
+    });
+
+    it('ships no source at all from the server when the files differ', () => {
+      // THE DEFECT THIS EXISTS TO PIN. The server has no viewport, and the page
+      // is statically generated, so it cannot get one from the request either.
+      // Naming a file in the markup therefore names the WRONG one for every
+      // phone: ~16MB fetched and thrown away on this brand's homepage, plus a
+      // visible swap. So when the two addresses genuinely differ, the server
+      // ships the player empty and the client names the single file it needs.
+      const html = renderToStaticMarkup(
+        <VideoBlock
+          block={
+            {
+              value: 'https://cdn.example.com/desktop.mp4',
+              properties: {
+                useDifferentMobileVideo: true,
+                mobileUrl: 'https://cdn.example.com/mobile.mp4'
+              }
+            } as any
+          }
+          placeholderId="p1"
+          sectionId="s1"
+          isDesigner={false}
+        />
       );
-      expect((container.querySelector('video') as HTMLVideoElement).src).toBe(
-        'https://cdn.example.com/mobile.mp4'
+      expect(html).toContain('<video');
+      expect(html).not.toContain('desktop.mp4');
+      expect(html).not.toContain('mobile.mp4');
+    });
+
+    it('still ships the source from the server for a single-file block', () => {
+      // The gate has to leave every composition that never authored a mobile
+      // override byte-identical — including its parse-time head start.
+      const html = renderToStaticMarkup(
+        <VideoBlock
+          block={{ value: 'https://cdn.example.com/only.mp4' } as any}
+          placeholderId="p1"
+          sectionId="s1"
+          isDesigner={false}
+        />
       );
+      expect(html).toContain('https://cdn.example.com/only.mp4');
+    });
+
+    it('reads the override however the editor happened to store it', () => {
+      // The live composition that reported this bug stores BOTH keys under
+      // `desktop` only — `{"useDifferentMobileVideo":{"desktop":true}}` and
+      // `{"mobileUrl":{"desktop":"..."}}`. A gate resolved at the breakpoint
+      // would answer differently on the server and on the phone and the player
+      // would not hydrate, so the gate ignores the breakpoint entirely.
+      withViewport(true, () => {
+        const { container } = renderAt(
+          'https://cdn.example.com/desktop.mp4',
+          {
+            useDifferentMobileVideo: { desktop: true },
+            mobileUrl: { desktop: 'https://cdn.example.com/mobile.mp4' }
+          },
+          'mobile'
+        );
+        expect(
+          (container.querySelector('video') as HTMLVideoElement).src
+        ).toBe('https://cdn.example.com/mobile.mp4');
+      });
+    });
+
+    it('follows the editor device instead of the viewport inside the canvas', () => {
+      // The canvas draws a phone preview inside a desktop-wide iframe, so the
+      // viewport is the wrong thing to ask there. It must also keep working in
+      // BROWSE MODE, where the `isDesigner` a block receives is already false
+      // while the editor is still attached — hence the window flag rather than
+      // the prop.
+      (window as { __themeEditorDesigner?: boolean }).__themeEditorDesigner =
+        true;
+      try {
+        withViewport(false, () => {
+          const { container } = renderAt(
+            'https://cdn.example.com/desktop.mp4',
+            {
+              useDifferentMobileVideo: true,
+              mobileUrl: 'https://cdn.example.com/mobile.mp4'
+            },
+            'mobile'
+          );
+          expect(
+            (container.querySelector('video') as HTMLVideoElement).src
+          ).toBe('https://cdn.example.com/mobile.mp4');
+        });
+      } finally {
+        delete (window as { __themeEditorDesigner?: boolean })
+          .__themeEditorDesigner;
+      }
     });
 
     it('takes the mobile poster on a tablet for the same reason', () => {

package/src/blocks/video-block.tsx

@@ -1,7 +1,12 @@
 'use client';
 
-import React, { useRef, useState } from 'react';
-import { getResponsiveValue, isNarrowBreakpoint } from '../utils';
+import React, { useEffect, useRef, useState } from 'react';
+import {
+  BREAKPOINTS,
+  PHONE_AND_TABLET_MEDIA_CONDITION,
+  getResponsiveValue,
+  isNarrowBreakpoint
+} from '../utils';
 import { BlockRendererProps } from './block-renderer-registry';
 
 /**
@@ -181,6 +186,36 @@ export const parseVideoSource = (
   return null;
 };
 
+/**
+ * Is this per-breakpoint value filled in at ANY breakpoint?
+ *
+ * Deliberately breakpoint-INDEPENDENT, and that is the whole point of it.
+ * `currentBreakpoint` is the literal `'desktop'` on the server and stays
+ * `'desktop'` through a phone's FIRST client render, so a gate that read it
+ * would answer one thing in the server HTML and another a paint later — the
+ * markup would not hydrate, and the element would be rebuilt rather than
+ * adopted. This question has one answer at every width.
+ */
+const setAtAnyBreakpoint = (value: unknown): boolean => {
+  if (value === null || value === undefined || value === '') return false;
+  if (typeof value !== 'object') return Boolean(value);
+  if (Array.isArray(value)) return false;
+  const perBreakpoint = value as Record<string, unknown>;
+  return BREAKPOINTS.some((breakpoint) => Boolean(perBreakpoint[breakpoint]));
+};
+
+/** The first address a per-breakpoint value carries, asked the same way. */
+const firstUrlAtAnyBreakpoint = (value: unknown): string => {
+  if (typeof value === 'string') return value;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return '';
+  const perBreakpoint = value as Record<string, unknown>;
+  for (const breakpoint of BREAKPOINTS) {
+    const candidate = perBreakpoint[breakpoint];
+    if (typeof candidate === 'string' && candidate !== '') return candidate;
+  }
+  return '';
+};
+
 /**
  * A video: a YouTube or Vimeo embed, or a file the browser plays itself.
  *
@@ -248,6 +283,21 @@ const VideoBlock = ({
 
   const parsed = parseVideoSource(videoUrl, { ...properties, sourceType });
 
+  /**
+   * Does this block really ship two DIFFERENT files?
+   *
+   * Asked without the breakpoint, for the reason `setAtAnyBreakpoint` records:
+   * the answer has to be identical on the server and in the phone's first
+   * render or the player would not hydrate. When it is yes, the server ships
+   * the element with no source at all and the effect below names the one file
+   * this viewport needs — see it for why the server cannot decide this.
+   */
+  const mobileUrlAnywhere = firstUrlAtAnyBreakpoint(properties.mobileUrl);
+  const hasDistinctMobileVideo =
+    setAtAnyBreakpoint(properties.useDifferentMobileVideo) &&
+    !!mobileUrlAnywhere &&
+    mobileUrlAnywhere !== desktopUrl;
+
   /**
    * Read through the breakpoint, the way `aspect-ratio` already is.
    *
@@ -306,6 +356,77 @@ const VideoBlock = ({
     }
   };
 
+  /**
+   * THE FILE, NAMED BY THE SIDE THAT KNOWS THE VIEWPORT.
+   *
+   * `videoUrl` above is chosen from `currentBreakpoint`, and on the storefront
+   * that value is a lie for the first paint: `theme-placeholder-wrapper.tsx`
+   * seeds it with the literal `'desktop'` and corrects it only in a post-mount
+   * effect. So the HTML every phone received named the DESKTOP clip; the phone
+   * began downloading the landscape film — 15.7MB of it on this brand's
+   * homepage — and threw it away a paint later when the portrait one the
+   * merchant uploaded replaced it.
+   *
+   * The server cannot answer this by looking. It has no viewport, and the page
+   * this runs on is statically generated with `revalidate`, so reading the
+   * request headers would not vary the cache — it would only take the route out
+   * of static generation and still answer "not mobile" for everyone.
+   *
+   * `<source media>` would let the browser choose during parsing, earlier than
+   * this. Measured on WebKit, Gecko and Blink it works and the skipped
+   * candidate is never requested — but a shopper's browser version is not
+   * something this package can audit, and where the attribute is ignored the
+   * cost lands as a whole wasted film on the phone, which is the connection
+   * that can least afford it. So the choice is made here instead: one code
+   * path, one download, on every browser.
+   */
+  useEffect(() => {
+    if (!hasDistinctMobileVideo) return;
+
+    const el = videoRef.current;
+    if (!el) return;
+
+    /*
+     * Inside the canvas the breakpoint is FORCED by the editor rather than read
+     * off the viewport, and that has to keep working in browse mode — where the
+     * `isDesigner` a block receives is already false while the editor is still
+     * attached. `__themeEditorDesigner` is the flag that answers "is the editor
+     * attached" and survives that toggle; see browse-mode.ts.
+     */
+    const editorAttached =
+      typeof window !== 'undefined' &&
+      (window as { __themeEditorDesigner?: boolean }).__themeEditorDesigner ===
+        true;
+
+    /*
+     * The breakpoint prop is the fallback, not the answer: it is still
+     * `'desktop'` when this effect first runs on a phone (a child's effect
+     * commits before the placeholder's own breakpoint effect above it), which
+     * is the whole defect. It is only reached if a browser somehow has no
+     * `matchMedia` — better a stale first guess that a later render corrects
+     * than a TypeError that takes the player out entirely.
+     */
+    const viewportIsNarrow =
+      typeof window.matchMedia === 'function'
+        ? window.matchMedia(PHONE_AND_TABLET_MEDIA_CONDITION).matches
+        : isNarrowBreakpoint(currentBreakpoint);
+
+    const wantsMobile = editorAttached
+      ? isNarrowBreakpoint(currentBreakpoint)
+      : viewportIsNarrow;
+
+    const next = wantsMobile ? mobileUrlAnywhere : desktopUrl;
+    if (!next || el.getAttribute('src') === next) return;
+
+    el.setAttribute('src', next);
+    el.load();
+  }, [
+    hasDistinctMobileVideo,
+    currentBreakpoint,
+    mobileUrlAnywhere,
+    desktopUrl
+  ]);
+
   /**
    * The author's choice wins; a Short supplies its own when they made none.
    * With neither, the historic fixed height is kept, so every composition
@@ -331,11 +452,6 @@ const VideoBlock = ({
    * `<video>` inside it stayed `height: auto` — sized by its own aspect
    * ratio, not by the box it was placed in.
    */
-  const heightStyle = getResponsiveValue(
-    block.styles?.height,
-    currentBreakpoint,
-    'auto'
-  ) as string;
   const objectFit = getResponsiveValue(
     block.styles?.['object-fit'],
     currentBreakpoint,
@@ -404,7 +520,7 @@ const VideoBlock = ({
   const videoElement = (
     <video
       ref={videoRef}
-      src={parsed.src}
+      src={hasDistinctMobileVideo ? undefined : parsed.src}
       controls={nativeControls}
       autoPlay={properties.autoplay}
       loop={properties.loop}
@@ -420,21 +536,35 @@ const VideoBlock = ({
       playsInline={properties.playsInline !== false}
       onPlay={() => setIsPlaying(true)}
       onPause={() => setIsPlaying(false)}
-      style={
-        ratio
-          ? {
-              width: '100%',
-              aspectRatio: ratio,
-              objectFit,
-              borderRadius: 'inherit'
-            }
-          : {
-              width: '100%',
-              height: heightStyle,
-              objectFit,
-              borderRadius: 'inherit'
-            }
-      }
+      /*
+       * THE PLAYER FILLS ITS BOX; IT DOES NOT RE-DECLARE IT.
+       *
+       * `video` is not an inner-root type, so `generateThemeCSS` already writes
+       * the author's `aspect-ratio` and `height` onto the block's WRAPPER, and
+       * on the storefront it writes them as a real cascade — the box is the
+       * right shape at the first paint with no JavaScript at all. Re-resolving
+       * those same keys at `currentBreakpoint` and inlining them here is what
+       * broke it: the stored ratio is often mobile-only, `currentBreakpoint` is
+       * `'desktop'` for the server and the first client render, so the player
+       * shipped `height: auto` — and an inline style outranks the media query
+       * that had just sized the wrapper correctly. A 9/16 box 693px tall got a
+       * 192px player and 500px of white.
+       *
+       * `height: 100%` is unconditional on purpose. Measured in WebKit, Gecko
+       * and Blink: where nothing sizes the wrapper a percentage height resolves
+       * to `auto`, byte-identical to the old behaviour, so an unsized block is
+       * untouched. Where the author DID size it the player now fills it — which
+       * also ends the overflow a fixed pixel height used to produce.
+       *
+       * `aspect-ratio` stays inline for the `<iframe>` branch above, because a
+       * Short's ratio is derived from the URL and the stylesheet cannot know it.
+       */
+      style={{
+        width: '100%',
+        height: '100%',
+        objectFit,
+        borderRadius: 'inherit'
+      }}
     />
   );