@akinon/pz-theme 2.0.98-rc.0 → 2.0.98

package/CHANGELOG.md

@@ -1,38 +1,12 @@
 # @akinon/pz-theme
 
-## 2.0.98-rc.0
-
-### Patch Changes
-
-- Updated dependencies [86187b1c]
-- Updated dependencies [0cf9ea239]
-- Updated dependencies [324f97d55]
-- Updated dependencies [51ea06888]
-- Updated dependencies
-- Updated dependencies [2fea41430]
-- Updated dependencies [b55acb768]
-- Updated dependencies [760258c1c]
-- Updated dependencies [143be2b9d]
-- Updated dependencies [7889b08fe]
-- Updated dependencies [9f8cd3bc5]
-- Updated dependencies [bfafa3f49]
-- Updated dependencies [57d7eb305]
-- Updated dependencies [d99a6a7d5]
-- Updated dependencies [9db81a714]
-- Updated dependencies [591e345e1]
-- Updated dependencies [4de5303c5]
-- Updated dependencies [95b139dc1]
-- Updated dependencies [1d00f2d06]
-- Updated dependencies [4ac7b2a1e]
-- Updated dependencies [e9598c71d]
-- Updated dependencies [4998a9631]
-- Updated dependencies [804d2bd6c]
-- Updated dependencies [3909d3224]
-- Updated dependencies [6a3d8a631]
-- Updated dependencies [e18836b20]
-- Updated dependencies [b1111d7b]
-  - @akinon/next@2.0.98-rc.0
-  - @akinon/theme-contract@2.0.98-rc.0
+## 2.0.98
+
+### Patch Changes
+
+- 23fde979: ZERO-5004: implement theme font management and restore guard
+  - @akinon/next@2.0.98
+  - @akinon/theme-contract@2.0.98
 
 ## 2.0.97
 

package/jest/setup.ts

@@ -1,8 +1,14 @@
 import '@testing-library/jest-dom';
 
+// A suite can opt into the node environment (`@jest-environment node`) when it
+// tests server-only code — a route handler needs the real `Request`/`Response`,
+// which jsdom does not have. There is no `window` there, and everything below
+// is a jsdom shim, so it stands down instead of throwing before the first test.
+const hasWindow = typeof window !== 'undefined';
+
 // jsdom does not implement these; provide no-op shims so components that touch
 // them on mount don't crash under test.
-if (!window.matchMedia) {
+if (hasWindow && !window.matchMedia) {
   window.matchMedia = ((query: string) => ({
     matches: false,
     media: query,
@@ -15,7 +21,9 @@ if (!window.matchMedia) {
   })) as unknown as typeof window.matchMedia;
 }
 
-window.scrollTo = (() => {}) as typeof window.scrollTo;
+if (hasWindow) {
+  window.scrollTo = (() => {}) as typeof window.scrollTo;
+}
 
 // `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
@@ -76,8 +84,11 @@ class NoopObserver {
   }
 }
 
-(window as unknown as Record<string, unknown>).IntersectionObserver =
-  (window as unknown as Record<string, unknown>).IntersectionObserver ||
-  NoopObserver;
-(window as unknown as Record<string, unknown>).ResizeObserver =
-  (window as unknown as Record<string, unknown>).ResizeObserver || NoopObserver;
+if (hasWindow) {
+  (window as unknown as Record<string, unknown>).IntersectionObserver =
+    (window as unknown as Record<string, unknown>).IntersectionObserver ||
+    NoopObserver;
+  (window as unknown as Record<string, unknown>).ResizeObserver =
+    (window as unknown as Record<string, unknown>).ResizeObserver ||
+    NoopObserver;
+}

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

package/src/__tests__/history-restore-recovery.test.tsx

@@ -0,0 +1,452 @@
+import React from 'react';
+import { render, act } from '@testing-library/react';
+// The Node build, not the browser one: it is the path a storefront actually
+// server-renders through, and the browser build wants a MessageChannel jsdom
+// does not have.
+import { renderToStaticMarkup } from 'react-dom/server.node';
+
+import ThemePlaceholderWrapper, {
+  armHistoryRestoreGuard,
+  buildCustomFontFaceCss,
+  buildRestoreGuardScript
+} from '../theme-placeholder-wrapper';
+import {
+  ThemeFontsLink,
+  THEME_FONTS_CSS_PATH
+} from '../chrome/theme-fonts-link';
+import { isEmptyRestoredDocument } from '../chrome/theme-restore-guard';
+import type { Section } from '../theme-section';
+
+/**
+ * ZERO-5004 — a page came back from a back/forward navigation with its brand
+ * font replaced by the fallback stack, and pages whose body is client-rendered
+ * came back blank.
+ *
+ * The cause is not in any one page: a history navigation can be served the
+ * document out of the HTTP cache, and that copy does not always finish
+ * hydrating. Everything the client owned was then missing — the uploaded
+ * fonts, the theme colours, every effect — while the server markup still
+ * painted, so the page looked "loaded" but wrong.
+ *
+ * Three things have to hold for that to be recoverable:
+ *   1. the faces ship with the markup, so typography never depends on effects;
+ *   2. a document that did not hydrate reloads itself once, from plain markup;
+ *   3. a frozen (bfcache) restore reloads in the editor too, where the canvas
+ *      used to be left blank on purpose.
+ */
+
+// This jsdom has no performance entry API at all, so the navigation type the
+// guard reads is provided rather than spied on.
+const originalPerformance = window.performance;
+
+// The whole object, not a property on it: reading `window.performance` in this
+// environment does not hand back something you can define a property on.
+const setNavigationType = (type: string) => {
+  Object.defineProperty(window, 'performance', {
+    configurable: true,
+    writable: true,
+    value: {
+      getEntriesByType: (kind: string) =>
+        kind === 'navigation' ? [{ type }] : []
+    }
+  });
+};
+
+const restorePerformance = () => {
+  Object.defineProperty(window, 'performance', {
+    configurable: true,
+    writable: true,
+    value: originalPerformance
+  });
+};
+
+const stubReload = () => {
+  // jsdom refuses to redefine `location.reload`, so the whole location object
+  // is swapped for one that carries a spy and answers `href` the same way.
+  const reload = jest.fn();
+  const original = window.location;
+  // A plain object, not one created from the real Location: its `href` getter
+  // throws when it is read off a derived object, and the guard reads `href`.
+  const stub = {
+    href: original.href,
+    origin: original.origin,
+    pathname: original.pathname,
+    reload
+  } as unknown as Location;
+
+  beforeAll(() => {
+    Object.defineProperty(window, 'location', {
+      configurable: true,
+      writable: true,
+      value: stub
+    });
+  });
+
+  afterAll(() => {
+    Object.defineProperty(window, 'location', {
+      configurable: true,
+      writable: true,
+      value: original
+    });
+  });
+
+  return reload;
+};
+
+const CUSTOM_FONTS = [
+  {
+    name: 'GantModernV2-Regular',
+    sources: [{ dataUrl: 'data:font/woff2;base64,AAAA', format: 'woff2' }]
+  },
+  {
+    name: 'GantSerif-MediumCondensed',
+    sources: [
+      { dataUrl: 'data:font/woff2;base64,BBBB', format: 'woff2' },
+      { dataUrl: 'data:font/woff;base64,CCCC', format: 'woff' }
+    ]
+  }
+];
+
+const THEME_SETTINGS = {
+  backgroundColor: '#ffffff',
+  customFonts: CUSTOM_FONTS
+};
+
+const section = {
+  id: 'body-section',
+  type: 'generic-section',
+  name: 'body',
+  label: 'Body',
+  order: 0,
+  hidden: false,
+  properties: {},
+  styles: {},
+  blocks: []
+} as unknown as Section;
+
+const slot = (
+  settings: Record<string, unknown> | null = THEME_SETTINGS,
+  isDesignMode = false
+) => (
+  <ThemePlaceholderWrapper
+    slug="page-iletisim"
+    initialSections={[section]}
+    initialPlaceholderId="page-iletisim"
+    isDesignMode={isDesignMode}
+    initialThemeSettings={settings}
+  />
+);
+
+// What a page actually carries: the link the placeholder renders, then the
+// placeholder itself.
+const composedPage = (
+  settings: Record<string, unknown> | null = THEME_SETTINGS
+) => (
+  <>
+    <ThemeFontsLink settings={settings} />
+    {slot(settings)}
+  </>
+);
+
+describe('uploaded faces reach the browser without hydration', () => {
+  afterEach(() => {
+    document
+      .querySelectorAll('link[data-pz-theme-fonts], style[id^="custom-font-"]')
+      .forEach((node) => node.remove());
+  });
+
+  it('builds one @font-face per uploaded face', () => {
+    const css = buildCustomFontFaceCss(THEME_SETTINGS);
+
+    expect(css.match(/@font-face/g)).toHaveLength(2);
+    expect(css).toContain("font-family:'GantModernV2-Regular'");
+    expect(css).toContain("font-family:'GantSerif-MediumCondensed'");
+    expect(css).toContain("url('data:font/woff2;base64,AAAA') format('woff2')");
+    expect(css).toContain('font-display:swap');
+  });
+
+  it('keeps both sources of a face, in order', () => {
+    const css = buildCustomFontFaceCss(THEME_SETTINGS);
+    const serif = css.split('@font-face').find((r) => r.includes('GantSerif'));
+
+    expect(serif).toContain(
+      "url('data:font/woff2;base64,BBBB') format('woff2'), url('data:font/woff;base64,CCCC') format('woff')"
+    );
+  });
+
+  it('skips entries with no name or no usable source', () => {
+    expect(
+      buildCustomFontFaceCss({
+        customFonts: [
+          { name: '', sources: [{ dataUrl: 'data:x', format: 'woff2' }] },
+          { name: 'NoSources', sources: [] },
+          { name: 'Broken', sources: [{ format: 'woff2' }] }
+        ]
+      })
+    ).toBe('');
+  });
+
+  it('cannot break out of the style tag', () => {
+    const css = buildCustomFontFaceCss({
+      customFonts: [
+        {
+          name: 'Evil</style><script>alert(1)</script>',
+          sources: [{ dataUrl: 'data:font/woff2;base64,AAAA', format: 'woff2' }]
+        }
+      ]
+    });
+
+    // Only `</style` can end the element, and it comes out escaped; the rest
+    // of the crafted name stays inert text inside the stylesheet.
+    expect(css).not.toMatch(/<\/style/i);
+    expect(css).toContain('<\\/style>');
+  });
+
+  it('has nothing to build for a theme with no uploads', () => {
+    expect(buildCustomFontFaceCss(null)).toBe('');
+    expect(buildCustomFontFaceCss({ backgroundColor: '#fff' })).toBe('');
+  });
+
+  it('links the stylesheet from the server render, so a page that never hydrates still has the faces', () => {
+    const html = renderToStaticMarkup(composedPage());
+
+    expect(html).toContain(`href="${THEME_FONTS_CSS_PATH}"`);
+    expect(html).toContain('data-pz-theme-fonts="true"');
+    // The blobs stay out of the document: they are the stylesheet's payload,
+    // cached across pages instead of serialized into every response.
+    expect(html).not.toContain('base64,AAAA');
+  });
+
+  it('links nothing for a theme with no uploads', () => {
+    expect(
+      renderToStaticMarkup(composedPage({ backgroundColor: '#fff' }))
+    ).not.toContain('data-pz-theme-fonts');
+    expect(renderToStaticMarkup(<ThemeFontsLink settings={null} />)).toBe('');
+  });
+
+  const linkTheStylesheet = () => {
+    const link = document.createElement('link');
+    link.setAttribute('data-pz-theme-fonts', 'true');
+    link.setAttribute('href', THEME_FONTS_CSS_PATH);
+    document.head.appendChild(link);
+  };
+
+  // The real FontFaceSet is iterable and lists every declared face, loaded or
+  // not; `check()` is deliberately not part of the stub, because asking it was
+  // the bug (it answers false for a declared-but-unloaded face).
+  const stubFontApi = (declared: string[]) => {
+    Object.defineProperty(document, 'fonts', {
+      configurable: true,
+      writable: true,
+      value: {
+        ready: Promise.resolve(),
+        [Symbol.iterator]: () =>
+          declared
+            .map((family) => ({ family, status: 'unloaded' }))
+            [Symbol.iterator]()
+      }
+    });
+  };
+
+  it('does not inline the faces from the client when the stylesheet delivered them', async () => {
+    linkTheStylesheet();
+    stubFontApi(['GantModernV2-Regular', '"GantSerif-MediumCondensed"']);
+
+    const { unmount } = render(slot());
+    // The check waits for `document.fonts.ready`.
+    await act(async () => {});
+
+    expect(document.querySelectorAll('style[id^="custom-font-"]').length).toBe(
+      0
+    );
+
+    unmount();
+  });
+
+  it('inlines them when the stylesheet is linked but delivered nothing', async () => {
+    // A brand-side route that 404s, or a theme-config read that failed while
+    // answering it: the family ends up declared nowhere, and the page would
+    // otherwise render in the fallback face.
+    linkTheStylesheet();
+    stubFontApi([]);
+
+    const { unmount } = render(slot());
+    await act(async () => {});
+
+    expect(document.querySelectorAll('style[id^="custom-font-"]').length).toBe(
+      2
+    );
+
+    unmount();
+  });
+
+  it('still inlines them when the brand has not mounted the route', () => {
+    // The fallback path: without the stylesheet the faces would otherwise be
+    // missing entirely, so the effect keeps its old job.
+    const { unmount } = render(slot());
+
+    expect(document.querySelectorAll('style[id^="custom-font-"]').length).toBe(
+      2
+    );
+
+    unmount();
+  });
+});
+
+describe('a document that did not hydrate reloads itself once', () => {
+  const reload = stubReload();
+
+  const runGuard = (navType: string) => {
+    // A restored page that still shows its server markup: the guard waits for
+    // hydration rather than reloading on the spot.
+    document.body.innerHTML = '<main>Restored server markup</main>';
+    Object.defineProperty(document.body, 'innerText', {
+      configurable: true,
+      value: 'Restored server markup'
+    });
+    jest.useFakeTimers();
+    reload.mockClear();
+    window.sessionStorage.clear();
+    delete (window as Record<string, unknown>).__pzRestoreGuardArmed;
+    setNavigationType(navType);
+
+    armHistoryRestoreGuard(1500);
+    jest.advanceTimersByTime(2000);
+    jest.useRealTimers();
+  };
+
+  beforeEach(() => {
+    // A render earlier in this file set the flag; the guard must be judged on
+    // what THIS document announced.
+    delete (window as Record<string, unknown>).__pzThemeHydrated;
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+    delete (performance as unknown as Record<string, unknown>).getEntriesByType;
+    delete (window as Record<string, unknown>).__pzThemeHydrated;
+  });
+
+  it('reloads a back/forward entry that never announced a mount', () => {
+    runGuard('back_forward');
+
+    expect(reload).toHaveBeenCalledTimes(1);
+  });
+
+  it('leaves a hydrated restore alone', () => {
+    (window as Record<string, unknown>).__pzThemeHydrated = true;
+    runGuard('back_forward');
+
+    expect(reload).not.toHaveBeenCalled();
+  });
+
+  it('leaves a normal navigation alone', () => {
+    runGuard('navigate');
+
+    expect(reload).not.toHaveBeenCalled();
+  });
+
+  it('treats a shell with no markup as nothing to wait for', () => {
+    // The 404 and error documents have no server markup — their body only
+    // exists once React runs — so the guard reloads them on the spot instead
+    // of showing a white screen for the length of the grace period.
+    const empty = new DOMParser().parseFromString(
+      '<html id="__next_error__"><body></body></html>',
+      'text/html'
+    );
+    const painted = new DOMParser().parseFromString(
+      '<html><body><main>Restored server markup</main></body></html>',
+      'text/html'
+    );
+
+    expect(isEmptyRestoredDocument(empty)).toBe(true);
+    expect(isEmptyRestoredDocument(painted)).toBe(false);
+    expect(
+      isEmptyRestoredDocument(
+        new DOMParser().parseFromString(
+          '<html><body>   </body></html>',
+          'text/html'
+        )
+      )
+    ).toBe(true);
+  });
+
+  it('does not reload the same entry twice', () => {
+    runGuard('back_forward');
+    expect(reload).toHaveBeenCalledTimes(1);
+
+    // Second visit to the same history entry: the mark from the first reload
+    // is still in sessionStorage, so the guard stands down instead of looping.
+    reload.mockClear();
+    delete (window as Record<string, unknown>).__pzRestoreGuardArmed;
+    jest.useFakeTimers();
+    setNavigationType('back_forward');
+    armHistoryRestoreGuard(1500);
+    jest.advanceTimersByTime(2000);
+    jest.useRealTimers();
+
+    expect(reload).not.toHaveBeenCalled();
+  });
+
+  it('ships with the framework bundles, not inside our tree', () => {
+    // Deliberately NOT rendered by a component of ours: on an error or 404
+    // document React streams the body — head scripts included — through the
+    // RSC payload, where a script tag is text and never runs. See
+    // theme-restore-guard.tsx; the brand arms it from instrumentation-client.
+    expect(renderToStaticMarkup(composedPage())).not.toContain(
+      'pz-restore-guard'
+    );
+  });
+
+  it('can also be shipped as an inline script, same logic', () => {
+    const script = buildRestoreGuardScript(1200);
+
+    expect(script).toContain('__pzThemeHydrated');
+    expect(script).toContain('back_forward');
+    expect(script).toContain('.reload()');
+    expect(script.trimEnd().endsWith('(1200);')).toBe(true);
+  });
+});
+
+describe('a mounted placeholder announces itself', () => {
+  it('sets the flag the guard waits for', () => {
+    delete (window as Record<string, unknown>).__pzThemeHydrated;
+    const { unmount } = render(slot());
+
+    expect((window as Record<string, unknown>).__pzThemeHydrated).toBe(true);
+    unmount();
+  });
+});
+
+describe('a frozen restore recovers in the editor too', () => {
+  const reload = stubReload();
+
+  beforeEach(() => reload.mockClear());
+
+  const firePageShow = (persisted: boolean) => {
+    act(() => {
+      const event = new Event('pageshow') as Event & { persisted?: boolean };
+      Object.defineProperty(event, 'persisted', { value: persisted });
+      window.dispatchEvent(event);
+    });
+  };
+
+  it('reloads the canvas the editor is attached to', () => {
+    // The designer used to be exempt and got a blank canvas instead.
+    const { unmount } = render(slot(THEME_SETTINGS, true));
+
+    firePageShow(true);
+    expect(reload).toHaveBeenCalledTimes(1);
+
+    unmount();
+  });
+
+  it('still ignores a normal pageshow', () => {
+    const { unmount } = render(slot(THEME_SETTINGS, true));
+
+    firePageShow(false);
+    expect(reload).not.toHaveBeenCalled();
+
+    unmount();
+  });
+});

package/src/chrome/__tests__/theme-fonts-css.test.ts

@@ -0,0 +1,109 @@
+/**
+ * @jest-environment node
+ */
+// The route runs on the server, where `Request`/`Response` are globals; the
+// default jsdom environment has neither.
+jest.mock('server-only', () => ({}));
+
+const getThemeConfig = jest.fn();
+jest.mock('../theme-config-source', () => ({
+  getThemeConfig: () => getThemeConfig()
+}));
+
+import { themeFontsCssResponse } from '../theme-fonts-css';
+
+/**
+ * The route behind the font stylesheet. It exists so the faces stop depending
+ * on hydration having run (ZERO-5004) and stop being serialized into every
+ * page: a stylesheet is fetched once and revalidated, not shipped per response.
+ */
+const SETTINGS = {
+  customFonts: [
+    {
+      name: 'GantModernV2-Regular',
+      sources: [{ dataUrl: 'data:font/woff2;base64,AAAA', format: 'woff2' }]
+    }
+  ]
+};
+
+describe('the theme font stylesheet route', () => {
+  beforeEach(() => {
+    getThemeConfig.mockReset();
+    getThemeConfig.mockResolvedValue({
+      settings: SETTINGS,
+      dataSources: [],
+      modals: []
+    });
+  });
+
+  it('answers with the faces as CSS', async () => {
+    const response = await themeFontsCssResponse();
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get('content-type')).toBe(
+      'text/css; charset=utf-8'
+    );
+    await expect(response.text()).resolves.toContain(
+      "@font-face{font-family:'GantModernV2-Regular'"
+    );
+  });
+
+  it('is cacheable but revalidated, so an upload is never stale', async () => {
+    const response = await themeFontsCssResponse();
+
+    expect(response.headers.get('cache-control')).toBe(
+      'public, max-age=0, must-revalidate'
+    );
+    expect(response.headers.get('etag')).toMatch(/^W\/"pz-fonts-/);
+  });
+
+  it('answers 304 for a browser that already has this version', async () => {
+    const first = await themeFontsCssResponse();
+    const etag = first.headers.get('etag') as string;
+
+    const second = await themeFontsCssResponse(
+      new Request('http://localhost/api/theme-fonts', {
+        headers: { 'if-none-match': etag }
+      })
+    );
+
+    expect(second.status).toBe(304);
+    await expect(second.text()).resolves.toBe('');
+  });
+
+  it('changes its tag when the designer uploads a different face', async () => {
+    const before = (await themeFontsCssResponse()).headers.get('etag');
+
+    getThemeConfig.mockResolvedValue({
+      settings: {
+        customFonts: [
+          {
+            name: 'GantModernV2-Regular',
+            sources: [
+              { dataUrl: 'data:font/woff2;base64,ZZZZ', format: 'woff2' }
+            ]
+          }
+        ]
+      },
+      dataSources: [],
+      modals: []
+    });
+
+    expect((await themeFontsCssResponse()).headers.get('etag')).not.toBe(
+      before
+    );
+  });
+
+  it('answers empty CSS for a theme with no uploads', async () => {
+    getThemeConfig.mockResolvedValue({
+      settings: { backgroundColor: '#fff' },
+      dataSources: [],
+      modals: []
+    });
+
+    const response = await themeFontsCssResponse();
+
+    expect(response.status).toBe(200);
+    await expect(response.text()).resolves.toBe('');
+  });
+});