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

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}