@zalify/storefront-kit 0.1.4 → 0.1.6

package/dist/commerce/google-fonts.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Google Fonts resolution, including the server side of the next/font
+ * pattern: fetch Google's hosted CSS once per process, inline the
+ * @font-face rules into the HTML and preload the latin woff2 files so
+ * the brand font is downloading before first paint (no FOUT) instead
+ * of being discovered through an async stylesheet after paint.
+ *
+ * Lives in /commerce (not /react) because Next.js server components
+ * resolve react with the react-server condition and cannot import the
+ * react entries; layouts call resolveGoogleFontCss() from here and pass
+ * the result to <CssVariables fonts={…}/>.
+ */
+export interface ResolvedFont {
+    family: string;
+    weight: number;
+    style: 'normal' | 'italic';
+}
+/** Parse a Shopify font handle: "work_sans_n4" → Work Sans / 400 / normal. */
+export declare function parseFontHandle(handle: string | undefined): ResolvedFont;
+export declare function googleFontsHref(family: string, axes?: string): string;
+/**
+ * The stylesheet URLs a storefront needs for its font settings
+ * (resolved theme settings: type_body_font/_google etc.).
+ */
+export declare function googleFontsHrefsFromSettings(settings: Record<string, unknown>): string[];
+interface FontSchemaSource {
+    settingsSchema: Array<{
+        settings?: Array<Record<string, unknown>>;
+    }>;
+    settingsData: {
+        current?: string | Record<string, unknown>;
+        presets?: Record<string, Record<string, unknown>>;
+    };
+}
+/**
+ * Resolve theme settings (schema defaults + current preset + app
+ * override) outside the react engine — for server components that
+ * cannot use installTheme()'s store. Same overlay rules as the engine.
+ */
+export declare function fontSettingsFromSchema(schema: FontSchemaSource, override?: Record<string, unknown>): Record<string, unknown>;
+export interface ResolvedGoogleFontCss {
+    /** The @font-face rules, ready to inline in a <style>. */
+    css: string;
+    /** Latin-subset woff2 URLs worth preloading (capped). */
+    preloadUrls: string[];
+}
+/**
+ * Fetch + cache the Google Fonts CSS for the given stylesheet hrefs.
+ * Returns null when any fetch fails, so callers fall back to
+ * <CssVariables/>' async stylesheet loader. Failures are not cached;
+ * the next request retries.
+ */
+export declare function resolveGoogleFontCss(hrefs: string[]): Promise<ResolvedGoogleFontCss | null>;
+export {};

package/dist/commerce/google-fonts.js

@@ -0,0 +1,141 @@
+/**
+ * Google Fonts resolution, including the server side of the next/font
+ * pattern: fetch Google's hosted CSS once per process, inline the
+ * @font-face rules into the HTML and preload the latin woff2 files so
+ * the brand font is downloading before first paint (no FOUT) instead
+ * of being discovered through an async stylesheet after paint.
+ *
+ * Lives in /commerce (not /react) because Next.js server components
+ * resolve react with the react-server condition and cannot import the
+ * react entries; layouts call resolveGoogleFontCss() from here and pass
+ * the result to <CssVariables fonts={…}/>.
+ */
+/** Parse a Shopify font handle: "work_sans_n4" → Work Sans / 400 / normal. */
+export function parseFontHandle(handle) {
+    const fallback = {
+        family: 'Work Sans',
+        weight: 400,
+        style: 'normal',
+    };
+    if (!handle)
+        return fallback;
+    const match = /^(.*)_([nib])(\d)$/.exec(handle);
+    if (!match)
+        return fallback;
+    const family = match[1]
+        .split('_')
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(' ');
+    return {
+        family,
+        weight: Number(match[3]) * 100,
+        style: match[2] === 'i' ? 'italic' : 'normal',
+    };
+}
+export function googleFontsHref(family, axes = 'ital,wght@0,400;0,500;0,700;1,400') {
+    const param = family.trim().replace(/ /g, '+');
+    // display=swap so the brand font always applies once it arrives, even
+    // after first paint (optional was tried and skipped cold loads
+    // entirely). With resolveGoogleFontCss() inlining the @font-face
+    // rules and preloading the woff2 files, the font usually beats first
+    // paint and swap never becomes visible.
+    return `https://fonts.googleapis.com/css2?family=${param}:${axes}&display=swap`;
+}
+/**
+ * The stylesheet URLs a storefront needs for its font settings
+ * (resolved theme settings: type_body_font/_google etc.).
+ */
+export function googleFontsHrefsFromSettings(settings) {
+    const str = (key) => typeof settings[key] === 'string' ? settings[key].trim() : '';
+    const hrefs = [];
+    const bodyGoogle = str('type_body_google');
+    const headingGoogle = str('type_heading_google');
+    const monoGoogle = str('type_mono_google');
+    hrefs.push(googleFontsHref(bodyGoogle || parseFontHandle(str('type_body_font') || undefined).family));
+    const heading = headingGoogle || parseFontHandle(str('type_heading_font') || undefined).family;
+    if (!hrefs[0].includes(heading.replace(/ /g, '+'))) {
+        hrefs.push(googleFontsHref(heading, 'wght@400;500;600;700'));
+    }
+    if (monoGoogle)
+        hrefs.push(googleFontsHref(monoGoogle, 'wght@400;500'));
+    return hrefs;
+}
+/**
+ * Resolve theme settings (schema defaults + current preset + app
+ * override) outside the react engine — for server components that
+ * cannot use installTheme()'s store. Same overlay rules as the engine.
+ */
+export function fontSettingsFromSchema(schema, override) {
+    const defaults = {};
+    for (const group of schema.settingsSchema) {
+        for (const setting of group.settings ?? []) {
+            const id = setting.id;
+            if (!id || setting.type === 'color_scheme_group')
+                continue;
+            if ('default' in setting)
+                defaults[id] = setting.default;
+        }
+    }
+    const current = typeof schema.settingsData.current === 'string'
+        ? (schema.settingsData.presets?.[schema.settingsData.current] ?? {})
+        : (schema.settingsData.current ?? {});
+    return { ...defaults, ...current, ...override };
+}
+// A woff2-capable UA so Google serves unicode-range-subset woff2 CSS
+// (the default CI/node UA gets legacy TTF without subsets).
+const WOFF2_UA = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36';
+const cssCache = new Map();
+async function fetchGoogleCss(href) {
+    try {
+        let signal;
+        try {
+            signal = AbortSignal.timeout(4000);
+        }
+        catch {
+            signal = undefined;
+        }
+        const response = await fetch(href, {
+            headers: { 'user-agent': WOFF2_UA, accept: 'text/css,*/*;q=0.1' },
+            signal,
+        });
+        if (!response.ok)
+            return null;
+        const css = await response.text();
+        // Preload only the latin subset — above-the-fold text is latin, and
+        // extra font preloads compete with the LCP image for bandwidth.
+        const latinUrls = [];
+        const facePattern = /\/\*\s*latin\s*\*\/\s*@font-face\s*\{[^}]*?url\((https:[^)\s]+\.woff2)\)/g;
+        let match;
+        while ((match = facePattern.exec(css)))
+            latinUrls.push(match[1]);
+        return { css, latinUrls };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Fetch + cache the Google Fonts CSS for the given stylesheet hrefs.
+ * Returns null when any fetch fails, so callers fall back to
+ * <CssVariables/>' async stylesheet loader. Failures are not cached;
+ * the next request retries.
+ */
+export async function resolveGoogleFontCss(hrefs) {
+    const parts = await Promise.all(hrefs.map((href) => {
+        let pending = cssCache.get(href);
+        if (!pending) {
+            pending = fetchGoogleCss(href);
+            cssCache.set(href, pending);
+            void pending.then((value) => {
+                if (value === null)
+                    cssCache.delete(href);
+            });
+        }
+        return pending;
+    }));
+    if (parts.some((part) => part === null))
+        return null;
+    const css = parts.map((part) => part.css).join('\n');
+    const preloadUrls = [...new Set(parts.flatMap((part) => part.latinUrls))].slice(0, 4);
+    return { css, preloadUrls };
+}

package/dist/commerce/index.d.ts

@@ -9,3 +9,4 @@ export * from './events';
 export * from './countdown';
 export * from './facets';
 export * from './product';
+export * from './google-fonts';

package/dist/commerce/index.js

@@ -9,3 +9,4 @@ export * from './events';
 export * from './countdown';
 export * from './facets';
 export * from './product';
+export * from './google-fonts';

package/dist/react/engine/CssVariables.d.ts

@@ -1,3 +1,11 @@
-export declare function CssVariables({ nonce }?: {
+import { type ResolvedGoogleFontCss } from '../../commerce/google-fonts.ts';
+/**
+ * The Google Fonts stylesheet URLs for the installed theme's settings.
+ * Server code passes these to resolveGoogleFontCss() (commerce) to
+ * inline the @font-face rules and preload the woff2 files.
+ */
+export declare function googleFontsHrefs(): string[];
+export declare function CssVariables({ nonce, fonts, }?: {
     nonce?: string;
+    fonts?: ResolvedGoogleFontCss | null;
 }): import("react").JSX.Element;

package/dist/react/engine/CssVariables.js

@@ -10,7 +10,7 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
  */
 import { useMemo } from 'react';
 import { colorSchemes, themeSettings } from './settings';
-import { googleFontsHref, parseFontHandle } from './fonts';
+import { googleFontsHrefsFromSettings, parseFontHandle, } from "../../commerce/google-fonts.js";
 function buildCss() {
     const s = themeSettings;
     const bodyGoogle = (s.type_body_google ?? '').trim();
@@ -84,20 +84,13 @@ function buildCss() {
     lines.push('}');
     return lines.join('\n');
 }
-function fontLinks() {
-    const s = themeSettings;
-    const hrefs = [];
-    const bodyGoogle = (s.type_body_google ?? '').trim();
-    const headingGoogle = (s.type_heading_google ?? '').trim();
-    const monoGoogle = (s.type_mono_google ?? '').trim();
-    hrefs.push(googleFontsHref(bodyGoogle || parseFontHandle(s.type_body_font).family));
-    const heading = headingGoogle || parseFontHandle(s.type_heading_font).family;
-    if (!hrefs[0].includes(heading.replace(/ /g, '+'))) {
-        hrefs.push(googleFontsHref(heading, 'wght@400;500;600;700'));
-    }
-    if (monoGoogle)
-        hrefs.push(googleFontsHref(monoGoogle, 'wght@400;500'));
-    return hrefs;
+/**
+ * The Google Fonts stylesheet URLs for the installed theme's settings.
+ * Server code passes these to resolveGoogleFontCss() (commerce) to
+ * inline the @font-face rules and preload the woff2 files.
+ */
+export function googleFontsHrefs() {
+    return googleFontsHrefsFromSettings(themeSettings);
 }
 // Promotes each preloaded font stylesheet to a real stylesheet by
 // flipping rel once its fetch completes (the Filament preload trick).
@@ -112,7 +105,14 @@ const FONT_CSS_LOADER = [
     "x.addEventListener('load',function(){x.rel='stylesheet'},{once:true})",
     '})(l[i])}',
 ].join('');
-export function CssVariables({ nonce } = {}) {
-    const { css, links } = useMemo(() => ({ css: buildCss(), links: fontLinks() }), []);
+export function CssVariables({ nonce, fonts, } = {}) {
+    const { css, links } = useMemo(() => ({ css: buildCss(), links: googleFontsHrefs() }), []);
+    // Server-resolved fonts (the next/font pattern): @font-face rules are
+    // inlined and the latin woff2 files preloaded, so the font downloads
+    // with the HTML and usually beats first paint — no async stylesheet,
+    // no FOUT, no request to fonts.googleapis.com at all.
+    if (fonts) {
+        return (_jsxs(_Fragment, { children: [_jsx("link", { rel: "preconnect", href: "https://fonts.gstatic.com", crossOrigin: "anonymous" }), fonts.preloadUrls.map((href) => (_jsx("link", { rel: "preload", as: "font", type: "font/woff2", href: href, crossOrigin: "anonymous" }, href))), _jsx("style", { dangerouslySetInnerHTML: { __html: fonts.css } }), _jsx("style", { dangerouslySetInnerHTML: { __html: css } })] }));
+    }
     return (_jsxs(_Fragment, { children: [_jsx("link", { rel: "preconnect", href: "https://fonts.googleapis.com" }), _jsx("link", { rel: "preconnect", href: "https://fonts.gstatic.com", crossOrigin: "anonymous" }), links.map((href) => (_jsx("link", { rel: "preload", as: "style", href: href, "data-zfy-font-css": "" }, href))), _jsx("script", { nonce: nonce, dangerouslySetInnerHTML: { __html: FONT_CSS_LOADER } }), _jsx("noscript", { children: links.map((href) => (_jsx("link", { rel: "stylesheet", href: href }, href))) }), _jsx("style", { dangerouslySetInnerHTML: { __html: css } })] }));
 }

package/dist/react/engine/fonts.d.ts

@@ -1,15 +1,6 @@
 /**
- * Font resolution for the mirror. The Liquid theme uses Shopify's
- * font_picker (handles like "work_sans_n4") plus optional Google-font
- * override text settings. Outside Shopify's font CDN we resolve picker
- * handles to the same family served from Google Fonts, keeping the
- * css-variables contract (--font-body--family etc.) identical.
+ * Font resolution moved to commerce/google-fonts.ts so server
+ * components (which cannot import the react entries) can share it.
+ * Re-exported here to keep the react API stable.
  */
-export interface ResolvedFont {
-    family: string;
-    weight: number;
-    style: 'normal' | 'italic';
-}
-/** Parse a Shopify font handle: "work_sans_n4" → Work Sans / 400 / normal. */
-export declare function parseFontHandle(handle: string | undefined): ResolvedFont;
-export declare function googleFontsHref(family: string, axes?: string): string;
+export { googleFontsHref, parseFontHandle, type ResolvedFont, } from '../../commerce/google-fonts.ts';

package/dist/react/engine/fonts.js

@@ -1,38 +1,6 @@
 /**
- * Font resolution for the mirror. The Liquid theme uses Shopify's
- * font_picker (handles like "work_sans_n4") plus optional Google-font
- * override text settings. Outside Shopify's font CDN we resolve picker
- * handles to the same family served from Google Fonts, keeping the
- * css-variables contract (--font-body--family etc.) identical.
+ * Font resolution moved to commerce/google-fonts.ts so server
+ * components (which cannot import the react entries) can share it.
+ * Re-exported here to keep the react API stable.
  */
-/** Parse a Shopify font handle: "work_sans_n4" → Work Sans / 400 / normal. */
-export function parseFontHandle(handle) {
-    const fallback = {
-        family: 'Work Sans',
-        weight: 400,
-        style: 'normal',
-    };
-    if (!handle)
-        return fallback;
-    const match = /^(.*)_([nib])(\d)$/.exec(handle);
-    if (!match)
-        return fallback;
-    const family = match[1]
-        .split('_')
-        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-        .join(' ');
-    return {
-        family,
-        weight: Number(match[3]) * 100,
-        style: match[2] === 'i' ? 'italic' : 'normal',
-    };
-}
-export function googleFontsHref(family, axes = 'ital,wght@0,400;0,500;0,700;1,400') {
-    const param = family.trim().replace(/ /g, '+');
-    // display=optional: the font never swaps in after first paint, so a
-    // late-arriving font file can't reflow text (zero font CLS). With the
-    // stylesheet loaded async (CssVariables), swap would otherwise shift
-    // layout on every cold load; optional shows the fallback first visit
-    // and the brand font from the cache on later views.
-    return `https://fonts.googleapis.com/css2?family=${param}:${axes}&display=optional`;
-}
+export { googleFontsHref, parseFontHandle, } from "../../commerce/google-fonts.js";

package/dist/react/index.d.ts

@@ -19,7 +19,7 @@ export { themeSettings, colorSchemes, getColorScheme } from './engine/settings';
 export { t } from './engine/translate';
 export { ThemeTemplate, SectionGroup, RenderSection, RenderSections, } from './engine/render';
 export { ThemeDataProvider, TemplateProvider, useThemeGlobals, useResource, useSectionData, useTemplateScope, } from './engine/context';
-export { CssVariables } from './engine/CssVariables';
+export { CssVariables, googleFontsHrefs } from './engine/CssVariables';
 export { parseFontHandle, googleFontsHref } from './engine/fonts';
 export { settingImageUrl, imageUrl, imageSrcSet, PlaceholderSvg, } from './engine/images';
 export { AdapterProvider, useAdapter } from './adapter';

package/dist/react/index.js

@@ -19,7 +19,7 @@ export { themeSettings, colorSchemes, getColorScheme } from './engine/settings';
 export { t } from './engine/translate';
 export { ThemeTemplate, SectionGroup, RenderSection, RenderSections, } from './engine/render';
 export { ThemeDataProvider, TemplateProvider, useThemeGlobals, useResource, useSectionData, useTemplateScope, } from './engine/context';
-export { CssVariables } from './engine/CssVariables';
+export { CssVariables, googleFontsHrefs } from './engine/CssVariables';
 export { parseFontHandle, googleFontsHref } from './engine/fonts';
 export { settingImageUrl, imageUrl, imageSrcSet, PlaceholderSvg, } from './engine/images';
 // Adapter seam

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalify/storefront-kit",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "module",
   "description": "The Zalify storefront SDK: framework-agnostic commerce logic (/commerce), the theme contract types and validators (/schemas), the canvas-editor bridge (/editor), and the React theme engine + shared components (/ui, /react/server). Consumed as TypeScript source inside the zalify-storefronts monorepo; published as compiled ESM + d.ts.",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/commerce/google-fonts.ts

@@ -0,0 +1,188 @@
+/**
+ * Google Fonts resolution, including the server side of the next/font
+ * pattern: fetch Google's hosted CSS once per process, inline the
+ * @font-face rules into the HTML and preload the latin woff2 files so
+ * the brand font is downloading before first paint (no FOUT) instead
+ * of being discovered through an async stylesheet after paint.
+ *
+ * Lives in /commerce (not /react) because Next.js server components
+ * resolve react with the react-server condition and cannot import the
+ * react entries; layouts call resolveGoogleFontCss() from here and pass
+ * the result to <CssVariables fonts={…}/>.
+ */
+
+export interface ResolvedFont {
+  family: string;
+  weight: number;
+  style: 'normal' | 'italic';
+}
+
+/** Parse a Shopify font handle: "work_sans_n4" → Work Sans / 400 / normal. */
+export function parseFontHandle(handle: string | undefined): ResolvedFont {
+  const fallback: ResolvedFont = {
+    family: 'Work Sans',
+    weight: 400,
+    style: 'normal',
+  };
+  if (!handle) return fallback;
+  const match = /^(.*)_([nib])(\d)$/.exec(handle);
+  if (!match) return fallback;
+  const family = match[1]
+    .split('_')
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
+  return {
+    family,
+    weight: Number(match[3]) * 100,
+    style: match[2] === 'i' ? 'italic' : 'normal',
+  };
+}
+
+export function googleFontsHref(
+  family: string,
+  axes = 'ital,wght@0,400;0,500;0,700;1,400',
+): string {
+  const param = family.trim().replace(/ /g, '+');
+  // display=swap so the brand font always applies once it arrives, even
+  // after first paint (optional was tried and skipped cold loads
+  // entirely). With resolveGoogleFontCss() inlining the @font-face
+  // rules and preloading the woff2 files, the font usually beats first
+  // paint and swap never becomes visible.
+  return `https://fonts.googleapis.com/css2?family=${param}:${axes}&display=swap`;
+}
+
+/**
+ * The stylesheet URLs a storefront needs for its font settings
+ * (resolved theme settings: type_body_font/_google etc.).
+ */
+export function googleFontsHrefsFromSettings(
+  settings: Record<string, unknown>,
+): string[] {
+  const str = (key: string) =>
+    typeof settings[key] === 'string' ? (settings[key] as string).trim() : '';
+  const hrefs: string[] = [];
+  const bodyGoogle = str('type_body_google');
+  const headingGoogle = str('type_heading_google');
+  const monoGoogle = str('type_mono_google');
+  hrefs.push(
+    googleFontsHref(
+      bodyGoogle || parseFontHandle(str('type_body_font') || undefined).family,
+    ),
+  );
+  const heading =
+    headingGoogle || parseFontHandle(str('type_heading_font') || undefined).family;
+  if (!hrefs[0].includes(heading.replace(/ /g, '+'))) {
+    hrefs.push(googleFontsHref(heading, 'wght@400;500;600;700'));
+  }
+  if (monoGoogle) hrefs.push(googleFontsHref(monoGoogle, 'wght@400;500'));
+  return hrefs;
+}
+
+interface FontSchemaSource {
+  settingsSchema: Array<{settings?: Array<Record<string, unknown>>}>;
+  settingsData: {
+    current?: string | Record<string, unknown>;
+    presets?: Record<string, Record<string, unknown>>;
+  };
+}
+
+/**
+ * Resolve theme settings (schema defaults + current preset + app
+ * override) outside the react engine — for server components that
+ * cannot use installTheme()'s store. Same overlay rules as the engine.
+ */
+export function fontSettingsFromSchema(
+  schema: FontSchemaSource,
+  override?: Record<string, unknown>,
+): Record<string, unknown> {
+  const defaults: Record<string, unknown> = {};
+  for (const group of schema.settingsSchema) {
+    for (const setting of group.settings ?? []) {
+      const id = setting.id as string | undefined;
+      if (!id || setting.type === 'color_scheme_group') continue;
+      if ('default' in setting) defaults[id] = setting.default;
+    }
+  }
+  const current =
+    typeof schema.settingsData.current === 'string'
+      ? (schema.settingsData.presets?.[schema.settingsData.current] ?? {})
+      : (schema.settingsData.current ?? {});
+  return {...defaults, ...current, ...override};
+}
+
+export interface ResolvedGoogleFontCss {
+  /** The @font-face rules, ready to inline in a <style>. */
+  css: string;
+  /** Latin-subset woff2 URLs worth preloading (capped). */
+  preloadUrls: string[];
+}
+
+// A woff2-capable UA so Google serves unicode-range-subset woff2 CSS
+// (the default CI/node UA gets legacy TTF without subsets).
+const WOFF2_UA =
+  'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36';
+
+interface FetchedCss {
+  css: string;
+  latinUrls: string[];
+}
+
+const cssCache = new Map<string, Promise<FetchedCss | null>>();
+
+async function fetchGoogleCss(href: string): Promise<FetchedCss | null> {
+  try {
+    let signal: AbortSignal | undefined;
+    try {
+      signal = AbortSignal.timeout(4000);
+    } catch {
+      signal = undefined;
+    }
+    const response = await fetch(href, {
+      headers: {'user-agent': WOFF2_UA, accept: 'text/css,*/*;q=0.1'},
+      signal,
+    });
+    if (!response.ok) return null;
+    const css = await response.text();
+    // Preload only the latin subset — above-the-fold text is latin, and
+    // extra font preloads compete with the LCP image for bandwidth.
+    const latinUrls: string[] = [];
+    const facePattern =
+      /\/\*\s*latin\s*\*\/\s*@font-face\s*\{[^}]*?url\((https:[^)\s]+\.woff2)\)/g;
+    let match: RegExpExecArray | null;
+    while ((match = facePattern.exec(css))) latinUrls.push(match[1]);
+    return {css, latinUrls};
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Fetch + cache the Google Fonts CSS for the given stylesheet hrefs.
+ * Returns null when any fetch fails, so callers fall back to
+ * <CssVariables/>' async stylesheet loader. Failures are not cached;
+ * the next request retries.
+ */
+export async function resolveGoogleFontCss(
+  hrefs: string[],
+): Promise<ResolvedGoogleFontCss | null> {
+  const parts = await Promise.all(
+    hrefs.map((href) => {
+      let pending = cssCache.get(href);
+      if (!pending) {
+        pending = fetchGoogleCss(href);
+        cssCache.set(href, pending);
+        void pending.then((value) => {
+          if (value === null) cssCache.delete(href);
+        });
+      }
+      return pending;
+    }),
+  );
+  if (parts.some((part) => part === null)) return null;
+  const css = parts.map((part) => part!.css).join('\n');
+  const preloadUrls = [...new Set(parts.flatMap((part) => part!.latinUrls))].slice(
+    0,
+    4,
+  );
+  return {css, preloadUrls};
+}

package/src/commerce/index.ts

@@ -9,3 +9,4 @@ export * from './events';
 export * from './countdown';
 export * from './facets';
 export * from './product';
+export * from './google-fonts';

package/src/react/engine/CssVariables.tsx

@@ -9,7 +9,11 @@
  */
 import {useMemo} from 'react';
 import {colorSchemes, themeSettings} from './settings';
-import {googleFontsHref, parseFontHandle} from './fonts';
+import {
+  googleFontsHrefsFromSettings,
+  parseFontHandle,
+  type ResolvedGoogleFontCss,
+} from '../../commerce/google-fonts.ts';
 
 function buildCss(): string {
   const s = themeSettings;
@@ -103,21 +107,15 @@ function buildCss(): string {
   return lines.join('\n');
 }
 
-function fontLinks(): string[] {
-  const s = themeSettings;
-  const hrefs: string[] = [];
-  const bodyGoogle = (s.type_body_google ?? '').trim();
-  const headingGoogle = (s.type_heading_google ?? '').trim();
-  const monoGoogle = (s.type_mono_google ?? '').trim();
-  hrefs.push(
-    googleFontsHref(bodyGoogle || parseFontHandle(s.type_body_font).family),
+/**
+ * The Google Fonts stylesheet URLs for the installed theme's settings.
+ * Server code passes these to resolveGoogleFontCss() (commerce) to
+ * inline the @font-face rules and preload the woff2 files.
+ */
+export function googleFontsHrefs(): string[] {
+  return googleFontsHrefsFromSettings(
+    themeSettings as unknown as Record<string, unknown>,
   );
-  const heading = headingGoogle || parseFontHandle(s.type_heading_font).family;
-  if (!hrefs[0].includes(heading.replace(/ /g, '+'))) {
-    hrefs.push(googleFontsHref(heading, 'wght@400;500;600;700'));
-  }
-  if (monoGoogle) hrefs.push(googleFontsHref(monoGoogle, 'wght@400;500'));
-  return hrefs;
 }
 
 // Promotes each preloaded font stylesheet to a real stylesheet by
@@ -134,11 +132,43 @@ const FONT_CSS_LOADER = [
   '})(l[i])}',
 ].join('');
 
-export function CssVariables({nonce}: {nonce?: string} = {}) {
+export function CssVariables({
+  nonce,
+  fonts,
+}: {nonce?: string; fonts?: ResolvedGoogleFontCss | null} = {}) {
   const {css, links} = useMemo(
-    () => ({css: buildCss(), links: fontLinks()}),
+    () => ({css: buildCss(), links: googleFontsHrefs()}),
     [],
   );
+
+  // Server-resolved fonts (the next/font pattern): @font-face rules are
+  // inlined and the latin woff2 files preloaded, so the font downloads
+  // with the HTML and usually beats first paint — no async stylesheet,
+  // no FOUT, no request to fonts.googleapis.com at all.
+  if (fonts) {
+    return (
+      <>
+        <link
+          rel="preconnect"
+          href="https://fonts.gstatic.com"
+          crossOrigin="anonymous"
+        />
+        {fonts.preloadUrls.map((href) => (
+          <link
+            key={href}
+            rel="preload"
+            as="font"
+            type="font/woff2"
+            href={href}
+            crossOrigin="anonymous"
+          />
+        ))}
+        <style dangerouslySetInnerHTML={{__html: fonts.css}} />
+        <style dangerouslySetInnerHTML={{__html: css}} />
+      </>
+    );
+  }
+
   return (
     <>
       <link rel="preconnect" href="https://fonts.googleapis.com" />

package/src/react/engine/fonts.ts

@@ -1,47 +1,10 @@
 /**
- * Font resolution for the mirror. The Liquid theme uses Shopify's
- * font_picker (handles like "work_sans_n4") plus optional Google-font
- * override text settings. Outside Shopify's font CDN we resolve picker
- * handles to the same family served from Google Fonts, keeping the
- * css-variables contract (--font-body--family etc.) identical.
+ * Font resolution moved to commerce/google-fonts.ts so server
+ * components (which cannot import the react entries) can share it.
+ * Re-exported here to keep the react API stable.
  */
-
-export interface ResolvedFont {
-  family: string;
-  weight: number;
-  style: 'normal' | 'italic';
-}
-
-/** Parse a Shopify font handle: "work_sans_n4" → Work Sans / 400 / normal. */
-export function parseFontHandle(handle: string | undefined): ResolvedFont {
-  const fallback: ResolvedFont = {
-    family: 'Work Sans',
-    weight: 400,
-    style: 'normal',
-  };
-  if (!handle) return fallback;
-  const match = /^(.*)_([nib])(\d)$/.exec(handle);
-  if (!match) return fallback;
-  const family = match[1]
-    .split('_')
-    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-    .join(' ');
-  return {
-    family,
-    weight: Number(match[3]) * 100,
-    style: match[2] === 'i' ? 'italic' : 'normal',
-  };
-}
-
-export function googleFontsHref(
-  family: string,
-  axes = 'ital,wght@0,400;0,500;0,700;1,400',
-): string {
-  const param = family.trim().replace(/ /g, '+');
-  // display=optional: the font never swaps in after first paint, so a
-  // late-arriving font file can't reflow text (zero font CLS). With the
-  // stylesheet loaded async (CssVariables), swap would otherwise shift
-  // layout on every cold load; optional shows the fallback first visit
-  // and the brand font from the cache on later views.
-  return `https://fonts.googleapis.com/css2?family=${param}:${axes}&display=optional`;
-}
+export {
+  googleFontsHref,
+  parseFontHandle,
+  type ResolvedFont,
+} from '../../commerce/google-fonts.ts';

package/src/react/index.ts

@@ -38,7 +38,7 @@ export {
   useSectionData,
   useTemplateScope,
 } from './engine/context';
-export {CssVariables} from './engine/CssVariables';
+export {CssVariables, googleFontsHrefs} from './engine/CssVariables';
 export {parseFontHandle, googleFontsHref} from './engine/fonts';
 export {
   settingImageUrl,