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

package/CHANGELOG.md

@@ -1,12 +1,12 @@
 # @akinon/pz-theme
 
-## 2.0.98-beta.0
+## 2.0.98
 
 ### Patch Changes
 
-- Updated dependencies [cbbbfd757]
-  - @akinon/next@2.0.98-beta.0
-  - @akinon/theme-contract@2.0.98-beta.0
+- 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-beta.0",
+  "version": "2.0.98",
   "license": "MIT",
   "main": "src/index.ts",
   "scripts": {
     "test": "jest"
   },
   "peerDependencies": {
-    "@akinon/next": "2.0.98-beta.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-beta.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-beta.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('');
+  });
+});

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

@@ -0,0 +1,52 @@
+import 'server-only';
+
+import { getThemeConfig } from './theme-config-source';
+import { buildCustomFontFaceCss } from '../utils/custom-fonts';
+
+/**
+ * The route body behind THEME_FONTS_CSS_PATH: the theme's uploaded faces as a
+ * real stylesheet.
+ *
+ * Mount it in the brand app as `app/api/theme-fonts/route.ts`:
+ *
+ * ```ts
+ * import { themeFontsCssResponse } from '@akinon/pz-theme/src/chrome/theme-fonts-css';
+ *
+ * export const GET = () => themeFontsCssResponse();
+ * ```
+ *
+ * Answered with a weak ETag over the CSS so a designer's upload invalidates it
+ * immediately while a shopper browsing the store revalidates in one round trip
+ * instead of re-downloading the faces per page.
+ */
+export const themeFontsCssResponse = async (
+  request?: Request
+): Promise<Response> => {
+  const { settings } = await getThemeConfig();
+  const css = buildCustomFontFaceCss(settings);
+
+  // A cheap, order-stable digest — enough to tell one upload from the next.
+  let hash = 0;
+  for (let index = 0; index < css.length; index += 1) {
+    hash = (hash * 31 + css.charCodeAt(index)) | 0;
+  }
+  const etag = `W/"pz-fonts-${css.length.toString(36)}-${(hash >>> 0).toString(
+    36
+  )}"`;
+
+  const headers = {
+    'Content-Type': 'text/css; charset=utf-8',
+    // Revalidated on every navigation, served from cache when unchanged: the
+    // faces are large and change only when the designer uploads. An EMPTY
+    // answer is never cached — it means the theme has no uploads yet, or that
+    // the widget read failed, and neither should stick to the browser.
+    'Cache-Control': css ? 'public, max-age=0, must-revalidate' : 'no-store',
+    ETag: etag
+  };
+
+  if (request?.headers.get('if-none-match') === etag) {
+    return new Response(null, { status: 304, headers });
+  }
+
+  return new Response(css, { status: 200, headers });
+};

package/src/chrome/theme-fonts-link.tsx

@@ -0,0 +1,44 @@
+import * as React from 'react';
+
+/**
+ * Where a brand mounts the theme's font stylesheet.
+ *
+ * The faces a designer uploads are base64 blobs in the theme settings, and they
+ * used to reach the browser only through an effect that appended `<style>` tags
+ * on mount. That made the brand's typography depend on hydration having run,
+ * and hydration does not always run: a history navigation can be served a
+ * cached copy of the document whose React tree never comes up, and the page
+ * then paints every word in the fallback face (ZERO-5004).
+ *
+ * A stylesheet has neither problem. It is part of the document, the browser
+ * fetches it before first paint, and it is cached across pages instead of being
+ * serialized into every response.
+ */
+export const THEME_FONTS_CSS_PATH = '/api/theme-fonts';
+
+/**
+ * Rendered by every placeholder; React keeps ONE of them, matched by `href`,
+ * and hoists it into the head.
+ */
+export const ThemeFontsLink = ({
+  settings
+}: {
+  settings: Record<string, unknown> | null;
+}) => {
+  const fonts = settings?.customFonts;
+
+  // Nothing uploaded: no request to make. A theme that adds its first face
+  // later gets the link on that page's next render.
+  if (!Array.isArray(fonts) || fonts.length === 0) return null;
+
+  return (
+    <link
+      rel="stylesheet"
+      href={THEME_FONTS_CSS_PATH}
+      // Read by the client font effect, which stands down when the document
+      // already links the faces.
+      data-pz-theme-fonts="true"
+      precedence="pz-theme-fonts"
+    />
+  );
+};

package/src/chrome/theme-restore-guard.tsx

@@ -0,0 +1,148 @@
+/**
+ * A back/forward navigation can be served the document out of the HTTP cache
+ * (Chrome does this even for `Cache-Control: no-cache`), and the copy it
+ * replays does not always finish hydrating: the markup paints, no effect ever
+ * runs, and everything the client owns is missing — the uploaded fonts, the
+ * theme colours, every interaction. A page whose body is client-rendered (the
+ * 404 shell, a data-driven composition) comes back blank (ZERO-5004).
+ *
+ * Nothing inside React can notice that, because React is exactly what did not
+ * start. So the check ships as plain markup: on a `back_forward` entry it waits
+ * for the mount below to announce itself and reloads once if that never
+ * happens. `sessionStorage` keeps it to one reload per history entry, and a
+ * normal navigation clears the mark so a later restore can still recover.
+ */
+export const RESTORE_GUARD_TIMEOUT_MS = 1500;
+
+/**
+ * Arms the check. Self-contained on purpose: it is also shipped as a string
+ * (see `buildRestoreGuardScript`), so it may not reference anything in this
+ * module's scope.
+ *
+ * The natural home is the brand's `instrumentation-client.ts`, which Next
+ * bundles into the framework scripts:
+ *
+ * ```ts
+ * import { armHistoryRestoreGuard } from '@akinon/pz-theme/src/chrome/theme-restore-guard';
+ *
+ * armHistoryRestoreGuard();
+ * ```
+ *
+ * A `<script>` rendered by a component of ours would not do. On an error or 404
+ * document React streams the whole body — head scripts included — through the
+ * RSC payload, so the tag exists only as payload text that the restored copy
+ * never executes. That is the document that came back blank, and the framework
+ * bundles are the only code the browser still runs there.
+ */
+/**
+ * Whether the restored document has anything on screen to lose.
+ *
+ * Two very different restores, and waiting the same grace period for both is
+ * what made the fix visible: a page that came back with its server markup looks
+ * right while it waits, but the 404 and error shells have no markup at all —
+ * their body only exists once React runs — so the visitor watched a white
+ * screen for as long as the timer.
+ */
+export const isEmptyRestoredDocument = (doc: Document = document): boolean => {
+  if (doc.getElementById('__next_error__')) return true;
+
+  const body = doc.body;
+  if (!body) return true;
+
+  // `innerText` is layout-aware in a browser and undefined in some test
+  // realms; the text content is the honest fallback.
+  const text = body.innerText ?? body.textContent ?? '';
+
+  return text.trim().length === 0;
+};
+
+export const armHistoryRestoreGuard = (timeoutMs: number = 1500) => {
+  try {
+    const w = window as unknown as Record<string, unknown>;
+    if (w.__pzRestoreGuardArmed) return;
+    w.__pzRestoreGuardArmed = 1;
+
+    // Read defensively: not every environment exposes the performance entry
+    // API on `window` (a jsdom test realm is one), and without the navigation
+    // type there is nothing to decide.
+    const perf =
+      (window as unknown as { performance?: Performance }).performance ??
+      (globalThis as unknown as { performance?: Performance }).performance;
+    const entry =
+      perf && typeof perf.getEntriesByType === 'function'
+        ? (perf.getEntriesByType('navigation')[0] as
+            | { type?: string }
+            | undefined)
+        : undefined;
+    const key = 'pz-restore-reload:' + window.location.href;
+
+    // Not a restore: clear the mark so a LATER restore of this entry can still
+    // recover.
+    if (!entry || entry.type !== 'back_forward') {
+      try {
+        window.sessionStorage.removeItem(key);
+      } catch {
+        /* private mode */
+      }
+      return;
+    }
+
+    try {
+      // Already reloaded once for this entry — never loop.
+      if (window.sessionStorage.getItem(key)) return;
+    } catch {
+      /* private mode */
+    }
+
+    const reload = () => {
+      if ((window as unknown as Record<string, unknown>).__pzThemeHydrated) {
+        return;
+      }
+
+      try {
+        window.sessionStorage.setItem(key, '1');
+      } catch {
+        /* private mode */
+      }
+
+      window.location.reload();
+    };
+
+    // Two very different restores, and waiting the same grace period for both
+    // is what made the fix visible: a page that came back with its server
+    // markup looks right while it waits, but the 404 and error shells have no
+    // markup at all — their body only exists once React runs — so the visitor
+    // watched a white screen for as long as the timer. When there is nothing on
+    // screen to lose, reload at once.
+    const armGrace = () => {
+      if (isEmptyRestoredDocument()) {
+        reload();
+        return;
+      }
+
+      window.setTimeout(reload, timeoutMs);
+    };
+
+    if (document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', armGrace, { once: true });
+    } else {
+      armGrace();
+    }
+  } catch {
+    // A browser without the performance entry API loses the recovery, not the
+    // page.
+  }
+};
+
+/**
+ * The same check as an inline script, for a brand that would rather put it in
+ * its layout than in `instrumentation-client.ts`. Prefer the latter: a script
+ * a component renders is payload text on the very documents that need this.
+ */
+export const buildRestoreGuardScript = (
+  timeoutMs: number = RESTORE_GUARD_TIMEOUT_MS
+): string =>
+  `(${armHistoryRestoreGuard.toString()})(${Math.max(
+    0,
+    Math.trunc(timeoutMs)
+  )});`;

package/src/index.ts

@@ -4,8 +4,14 @@
 export { default as ThemePlaceholder } from './theme-placeholder';
 export { default as ThemeSection } from './theme-section';
 export { default as ThemeBlock } from './theme-block';
-export { ThemeSettingsProvider, useThemeSettingsContext } from './theme-settings-context';
-export { ThemePageContextProvider, useThemePageContext } from './theme-page-context';
+export {
+  ThemeSettingsProvider,
+  useThemeSettingsContext
+} from './theme-settings-context';
+export {
+  ThemePageContextProvider,
+  useThemePageContext
+} from './theme-page-context';
 export {
   registerPlaceholder,
   unregisterPlaceholder
@@ -25,6 +31,16 @@ export type { Section } from './theme-section';
 export type { Block } from './theme-block';
 
 export { default as ChromeSlot } from './chrome/chrome-slot';
+export {
+  ThemeFontsLink,
+  THEME_FONTS_CSS_PATH
+} from './chrome/theme-fonts-link';
+export { buildCustomFontFaceCss } from './utils/custom-fonts';
+export {
+  armHistoryRestoreGuard,
+  buildRestoreGuardScript,
+  RESTORE_GUARD_TIMEOUT_MS
+} from './chrome/theme-restore-guard';
 export { default as ComposableRegion } from './chrome/composable-region';
 export { ChromeFallback } from './chrome/chrome-fallback';
 export { CodeOwnedRegion } from './chrome/code-owned-region';

package/src/theme-placeholder-wrapper.tsx

@@ -28,6 +28,26 @@ import { PreviewToEditorMessageType } from '@akinon/theme-contract';
 import { parseEditorMessage, postToEditor } from './editor-bridge';
 import { useBrowseMode } from './browse-mode';
 import { neutralizeStyleTagBreakout } from './utils/css-safety';
+import { buildCustomFontFaceCss } from './utils/custom-fonts';
+
+// Re-exported for the tests and for a brand that builds the faces itself; it
+// lives in ./utils/custom-fonts because a server route has to call it too and
+// this module is client-only.
+export { buildCustomFontFaceCss };
+export {
+  armHistoryRestoreGuard,
+  buildRestoreGuardScript,
+  RESTORE_GUARD_TIMEOUT_MS
+} from './chrome/theme-restore-guard';
+
+/**
+ * Whether this document already links the theme's font stylesheet. When it
+ * does, the faces are the browser's business and the client must not inline
+ * them a second time.
+ */
+const themeFontsLinked = () =>
+  typeof document !== 'undefined' &&
+  Boolean(document.querySelector('link[data-pz-theme-fonts]'));
 
 // One pageshow listener per page, not per placeholder — see the effect below.
 let bfcacheReloadListenerArmed = false;
@@ -353,10 +373,17 @@ export default function ThemePlaceholderWrapper({
   // does not reliably survive the freeze, and the page comes back with its
   // data-driven sections blank until a manual refresh. Reloading once on a
   // persisted pageshow trades the bfcache speedup for a page that is correct.
+  // The editor used to be exempt, on the assumption that a designer would
+  // rather keep the frozen canvas than lose it to a reload. What they actually
+  // got was a blank canvas after every back/forward (ZERO-5004): the same
+  // client-fetched data goes missing, and the editor cannot repaint what the
+  // page never re-fetched. A reload recovers by itself — the storefront
+  // announces its placeholders on the new document and the editor answers with
+  // the theme it holds, so nothing unsaved is lost.
+  //
   // Guarded at module level — a page hosts several placeholders and one
   // listener is enough.
   useEffect(() => {
-    if (isDesigner) return;
     if (bfcacheReloadListenerArmed) return;
     bfcacheReloadListenerArmed = true;
 
@@ -369,7 +396,14 @@ export default function ThemePlaceholderWrapper({
       window.removeEventListener('pageshow', onPageShow);
       bfcacheReloadListenerArmed = false;
     };
-  }, [isDesigner]);
+  }, []);
+
+  // What the restore guard above waits for: proof that this document's React
+  // tree actually came up.
+  useEffect(() => {
+    (window as unknown as { __pzThemeHydrated?: boolean }).__pzThemeHydrated =
+      true;
+  }, []);
   const [dataSources, setDataSources] = useState<any[]>(initialDataSources);
   const [themeSettings, setThemeSettings] = useState<Record<
     string,
@@ -486,7 +520,9 @@ export default function ThemePlaceholderWrapper({
       context.order.items.length > 0
     ) {
       const order = context.order;
-      const totalAmount = Number(String(order.totalAmount ?? '').replace(',', '.'));
+      const totalAmount = Number(
+        String(order.totalAmount ?? '').replace(',', '.')
+      );
       emitOnce(String(order.number ?? order.id ?? ''), 'purchase', {
         currency: readItemsCurrency(order),
         ...(Number.isFinite(totalAmount) ? { value: totalAmount } : null),
@@ -507,7 +543,14 @@ export default function ThemePlaceholderWrapper({
     }
   }, [themeSettings]);
 
-  // Inject custom fonts from theme settings
+  // Inject custom fonts from theme settings.
+  //
+  // The faces normally arrive as the stylesheet the server linked
+  // (chrome/theme-fonts-css.ts), which is what makes them survive a document
+  // that never hydrates (ZERO-5004). This is the safety net for the two cases
+  // the stylesheet cannot cover: a brand that has not mounted the route, and a
+  // theme-config read that failed while answering it. Either way the family is
+  // then not declared anywhere, and the check below is what notices.
   useEffect(() => {
     if (!themeSettings?.customFonts) return;
     const customFonts = themeSettings.customFonts as {
@@ -515,9 +558,9 @@ export default function ThemePlaceholderWrapper({
       sources: { dataUrl: string; format: string }[];
     }[];
 
-    customFonts.forEach((font) => {
+    const inject = (font: typeof customFonts[number]) => {
       if (
-        !font.name ||
+        !font?.name ||
         !Array.isArray(font.sources) ||
         font.sources.length === 0
       )
@@ -526,18 +569,63 @@ export default function ThemePlaceholderWrapper({
       const styleId = `custom-font-${font.name
         .replace(/\s+/g, '-')
         .toLowerCase()}`;
-      const existing = document.getElementById(styleId);
-      if (existing) existing.remove(); // Re-inject in case sources changed
 
       const src = font.sources
         .map((s) => `url('${s.dataUrl}') format('${s.format}')`)
         .join(', ');
 
+      const existing = document.getElementById(styleId);
+      if (existing) existing.remove(); // Re-inject in case sources changed
+
       const style = document.createElement('style');
       style.id = styleId;
       style.textContent = `@font-face { font-family: '${font.name}'; src: ${src}; font-display: swap; }`;
       document.head.appendChild(style);
-    });
+    };
+
+    if (!themeFontsLinked()) {
+      customFonts.forEach(inject);
+      return;
+    }
+
+    let cancelled = false;
+    const injectWhateverIsMissing = () => {
+      if (cancelled) return;
+
+      customFonts.forEach((font) => {
+        if (!font?.name) return;
+
+        // Declared, not loaded: a face the stylesheet carries stays
+        // `unloaded` until some text asks for it, and `document.fonts.check`
+        // answers false for exactly that state — asking it here re-inlined
+        // every face on every page.
+        try {
+          const declared = Array.from(
+            document.fonts as unknown as Iterable<FontFace>
+          ).some(
+            (face) => face.family?.replace(/^['"]|['"]$/g, '') === font.name
+          );
+
+          if (declared) return;
+        } catch {
+          // No font API to ask: fall through and inline, which is what this
+          // effect did before the stylesheet existed.
+        }
+
+        inject(font);
+      });
+    };
+
+    const ready = document.fonts?.ready;
+    if (ready && typeof ready.then === 'function') {
+      ready.then(injectWhateverIsMissing, injectWhateverIsMissing);
+    } else {
+      injectWhateverIsMissing();
+    }
+
+    return () => {
+      cancelled = true;
+    };
   }, [themeSettings]);
 
   useEffect(() => {
@@ -912,18 +1000,20 @@ export default function ThemePlaceholderWrapper({
     // has to sit above the rendered sections or every data-driven block
     // falls back to its empty state.
     <ThemePageContextProvider value={resolvedPageContext}>
-    <ThemeSettingsProvider value={themeSettings}>
-      {/*
+      <ThemeSettingsProvider value={themeSettings}>
+        {/*
         Pins are released while browsing — a button frozen in its hover state
         is not what the live site looks like. The editor re-sends the pinned
         state when the designer comes back, so the panel and the canvas agree.
       */}
-      <PartStatePreview isDesigner={isEditing} />
-      {themeBackgroundCSS && (
-        <style dangerouslySetInnerHTML={{ __html: themeBackgroundCSS }} />
-      )}
-      {dynamicCSS && <style dangerouslySetInnerHTML={{ __html: dynamicCSS }} />}
-      {/*
+        <PartStatePreview isDesigner={isEditing} />
+        {themeBackgroundCSS && (
+          <style dangerouslySetInnerHTML={{ __html: themeBackgroundCSS }} />
+        )}
+        {dynamicCSS && (
+          <style dangerouslySetInnerHTML={{ __html: dynamicCSS }} />
+        )}
+        {/*
         Deliberately unpainted. This wrapper sits behind every section of the
         slot, so any colour on it showed through a section that asked for
         `background-color: transparent` — the shipped default. That is why a
@@ -932,68 +1022,70 @@ export default function ThemePlaceholderWrapper({
         (see buildThemeBackgroundCss), which paints the same pixels everywhere
         the slot does not overlap something else.
       */}
-      <div data-placeholder={slug} className="theme-placeholder">
-        {renderedSections
-          .sort((a, b) => a.order - b.order)
-          .filter(
-            (section) =>
-              !section.hidden &&
-              (isEditing ||
-                isPublishWindowVisible(section.properties?.['publish-window']))
-          )
-          .map((section) => (
-            <SectionErrorBoundary key={section.id} sectionId={section.id}>
-              <ThemeSection
-                section={section}
-                placeholderId={placeholderSlug}
-                pageContext={resolvedPageContext}
-                isDesigner={isEditing}
-                isSelected={selectedSectionId === section.id}
-                selectedBlockId={selectedBlockId}
-                currentBreakpoint={currentBreakpoint}
-                onSelect={setSelectedSectionId}
-                onMoveUp={() =>
-                  sendAction('MOVE_SECTION_UP', {
-                    placeholderId: placeholderSlug,
-                    sectionId: section.id
-                  })
-                }
-                onMoveDown={() =>
-                  sendAction('MOVE_SECTION_DOWN', {
-                    placeholderId: placeholderSlug,
-                    sectionId: section.id
-                  })
-                }
-                onDuplicate={() =>
-                  sendAction('DUPLICATE_SECTION', {
-                    placeholderId: placeholderSlug,
-                    sectionId: section.id
-                  })
-                }
-                onToggleVisibility={() =>
-                  sendAction('TOGGLE_SECTION_VISIBILITY', {
-                    placeholderId: placeholderSlug,
-                    sectionId: section.id
-                  })
-                }
-                onDelete={() =>
-                  sendAction('DELETE_SECTION', {
-                    placeholderId: placeholderSlug,
-                    sectionId: section.id
-                  })
-                }
-                onRename={(newLabel) =>
-                  sendAction('RENAME_SECTION', {
-                    placeholderId: placeholderSlug,
-                    sectionId: section.id,
-                    label: newLabel
-                  })
-                }
-              />
-            </SectionErrorBoundary>
-          ))}
-      </div>
-    </ThemeSettingsProvider>
+        <div data-placeholder={slug} className="theme-placeholder">
+          {renderedSections
+            .sort((a, b) => a.order - b.order)
+            .filter(
+              (section) =>
+                !section.hidden &&
+                (isEditing ||
+                  isPublishWindowVisible(
+                    section.properties?.['publish-window']
+                  ))
+            )
+            .map((section) => (
+              <SectionErrorBoundary key={section.id} sectionId={section.id}>
+                <ThemeSection
+                  section={section}
+                  placeholderId={placeholderSlug}
+                  pageContext={resolvedPageContext}
+                  isDesigner={isEditing}
+                  isSelected={selectedSectionId === section.id}
+                  selectedBlockId={selectedBlockId}
+                  currentBreakpoint={currentBreakpoint}
+                  onSelect={setSelectedSectionId}
+                  onMoveUp={() =>
+                    sendAction('MOVE_SECTION_UP', {
+                      placeholderId: placeholderSlug,
+                      sectionId: section.id
+                    })
+                  }
+                  onMoveDown={() =>
+                    sendAction('MOVE_SECTION_DOWN', {
+                      placeholderId: placeholderSlug,
+                      sectionId: section.id
+                    })
+                  }
+                  onDuplicate={() =>
+                    sendAction('DUPLICATE_SECTION', {
+                      placeholderId: placeholderSlug,
+                      sectionId: section.id
+                    })
+                  }
+                  onToggleVisibility={() =>
+                    sendAction('TOGGLE_SECTION_VISIBILITY', {
+                      placeholderId: placeholderSlug,
+                      sectionId: section.id
+                    })
+                  }
+                  onDelete={() =>
+                    sendAction('DELETE_SECTION', {
+                      placeholderId: placeholderSlug,
+                      sectionId: section.id
+                    })
+                  }
+                  onRename={(newLabel) =>
+                    sendAction('RENAME_SECTION', {
+                      placeholderId: placeholderSlug,
+                      sectionId: section.id,
+                      label: newLabel
+                    })
+                  }
+                />
+              </SectionErrorBoundary>
+            ))}
+        </div>
+      </ThemeSettingsProvider>
     </ThemePageContextProvider>
   );
 }

package/src/theme-placeholder.tsx

@@ -1,6 +1,7 @@
 import 'server-only';
 
 import ThemePlaceholderWrapper from './theme-placeholder-wrapper';
+import { ThemeFontsLink } from './chrome/theme-fonts-link';
 import { loadPlaceholderSections } from './load-placeholder-sections';
 import { generateThemeCSS } from './utils';
 
@@ -24,6 +25,7 @@ export default async function ThemePlaceholder({
 
   return (
     <>
+      <ThemeFontsLink settings={themeSettings} />
       {themeCSS && <style dangerouslySetInnerHTML={{ __html: themeCSS }} />}
       <ThemePlaceholderWrapper
         slug={slug}

package/src/utils/custom-fonts.ts

@@ -0,0 +1,59 @@
+import { neutralizeStyleTagBreakout } from './css-safety';
+
+/**
+ * The designer's uploaded faces as real CSS, emitted from the same render that
+ * produced the markup.
+ *
+ * They used to exist only as `<style>` tags an effect appended on mount, which
+ * made the brand's typography depend on hydration having run. It does not
+ * always run: a history navigation (back, then forward) can hand the browser a
+ * cached copy of the document whose React tree never hydrates, and the page
+ * then paints every word in the fallback face — the Jost stack behind
+ * `GantModernV2` — with no error anywhere (ZERO-5004). Emitted with the markup,
+ * the faces are part of the document itself and survive any restore, and the
+ * first paint no longer swaps fonts a frame later.
+ *
+ * The effect below still runs: it is what applies a font the editor uploads
+ * mid-session, and it skips faces this CSS already covers.
+ */
+export const buildCustomFontFaceCss = (
+  settings: Record<string, unknown> | null
+): string => {
+  const fonts = settings?.customFonts;
+
+  if (!Array.isArray(fonts)) return '';
+
+  return fonts
+    .map((font) => {
+      const name = (font as { name?: unknown })?.name;
+      const sources = (font as { sources?: unknown })?.sources;
+
+      if (typeof name !== 'string' || !name.trim() || !Array.isArray(sources)) {
+        return '';
+      }
+
+      const src = sources
+        .map((source) => {
+          const dataUrl = (source as { dataUrl?: unknown })?.dataUrl;
+          const format = (source as { format?: unknown })?.format;
+
+          if (typeof dataUrl !== 'string' || !dataUrl) return '';
+
+          return typeof format === 'string' && format
+            ? `url('${dataUrl}') format('${format}')`
+            : `url('${dataUrl}')`;
+        })
+        .filter(Boolean)
+        .join(', ');
+
+      if (!src) return '';
+
+      // Editor-controlled values on their way into a <style> tag — the same
+      // breakout neutralization the generated section CSS goes through.
+      return `@font-face{font-family:'${neutralizeStyleTagBreakout(
+        name.trim()
+      )}';src:${neutralizeStyleTagBreakout(src)};font-display:swap;}`;
+    })
+    .filter(Boolean)
+    .join('');
+};