@shoppexio/builder-contracts 0.1.1 → 0.1.3

package/src/persistence.ts

@@ -2,6 +2,12 @@ import {
   type BuilderSettings,
   BuilderSettingsSchema,
 } from './builder-settings.ts';
+import {
+  mapLegacyNestedThemeTypographyToStyleSlots,
+  mapLegacyTokenOverridesToStyleSlots,
+  migrateLegacyBuilderSettings,
+} from './migrations.ts';
+import type { StyleSlots } from './style-slots.ts';
 
 type JsonRecord = Record<string, unknown>;
 const RESERVED_THEME_CONTENT_KEYS = new Set(['layout']);
@@ -36,6 +42,107 @@ export function extractPersistedBuilderSettings(input: unknown): BuilderSettings
   return parsedNested.success ? sanitizeBuilderSettingsState(parsedNested.data) : null;
 }
 
+function parseBuilderSettingsRevision(input: unknown): number {
+  return typeof input === 'number' && Number.isInteger(input) && input >= 0 ? input : 0;
+}
+
+function unwrapBuilderSettingsRecord(input: unknown): JsonRecord | null {
+  if (!isRecord(input)) {
+    return null;
+  }
+
+  if (isRecord(input.builder_settings)) {
+    return input.builder_settings;
+  }
+
+  if ('version' in input || 'revision' in input || 'theme' in input) {
+    return input;
+  }
+
+  return null;
+}
+
+function readStyleSlotsRecord(theme: JsonRecord): StyleSlots {
+  return isRecord(theme.style_slots) ? theme.style_slots as StyleSlots : {};
+}
+
+/**
+ * Single read boundary for builder v2 state: strict extract first, then legacy migration.
+ * Strips invalid keys such as nested `theme.typography` while preserving style_slots and pages.
+ */
+export function coercePersistedBuilderSettings(input: unknown): BuilderSettings | null {
+  const extracted = extractPersistedBuilderSettings(input);
+  if (extracted) {
+    return extracted;
+  }
+
+  if (isRecord(input) && isRecord(input.builder_settings)) {
+    const nestedExtracted = extractPersistedBuilderSettings(input.builder_settings);
+    if (nestedExtracted) {
+      return nestedExtracted;
+    }
+  }
+
+  const blob = unwrapBuilderSettingsRecord(input);
+  if (!blob) {
+    return null;
+  }
+
+  const theme = isRecord(blob.theme) ? blob.theme : {};
+  const tokensOverride = isRecord(theme.tokens_override) ? theme.tokens_override : {};
+  const styleSlots = mapLegacyNestedThemeTypographyToStyleSlots(
+    theme,
+    {
+      ...mapLegacyTokenOverridesToStyleSlots(tokensOverride),
+      ...readStyleSlotsRecord(theme),
+    },
+  );
+
+  const migrated = migrateLegacyBuilderSettings(
+    {
+      theme: {
+        content: isRecord(theme.content) ? theme.content : {},
+        layout: isRecord(theme.layout) ? theme.layout : {},
+        tokens_override: tokensOverride,
+        style_slots: styleSlots,
+      },
+    },
+    parseBuilderSettingsRevision(blob.revision),
+  );
+
+  const merged = BuilderSettingsSchema.safeParse({
+    ...migrated,
+    theme: {
+      ...migrated.theme,
+      pages: Array.isArray(theme.pages) ? theme.pages : migrated.theme.pages,
+      terms: isRecord(theme.terms) ? theme.terms : migrated.theme.terms,
+    },
+  });
+
+  return merged.success ? sanitizeBuilderSettingsState(merged.data) : migrated;
+}
+
+/**
+ * Coerces builder v2 fields for storefront export while preserving non-v2 siblings (seo, appearance, …).
+ */
+export function exportCoercedBuilderSettingsBlob(builderSettingsBlob: unknown): JsonRecord | null {
+  if (!isRecord(builderSettingsBlob)) {
+    return null;
+  }
+
+  const coerced = coercePersistedBuilderSettings(builderSettingsBlob);
+  if (!coerced) {
+    return null;
+  }
+
+  return {
+    ...builderSettingsBlob,
+    version: coerced.version,
+    revision: coerced.revision,
+    theme: coerced.theme,
+  };
+}
+
 export function sanitizeBuilderSettingsState(settings: BuilderSettings): BuilderSettings {
   const content = sanitizeThemeContent(settings.theme.content);
   return BuilderSettingsSchema.parse({

package/src/preview-boot.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from 'bun:test';
+import { mergePreviewBootIntoInitialData, PreviewBootPayloadSchema } from './preview-boot.ts';
+
+describe('PreviewBootPayloadSchema', () => {
+  it('accepts storefront seeds with catalog fields from built theme artifacts', () => {
+    const parsed = PreviewBootPayloadSchema.parse({
+      shopId: 'shop_1',
+      shopSlug: 'florain',
+      builderSettings: {
+        version: 2,
+        revision: 1,
+        theme: {
+          content: {},
+          layout: {},
+          style_slots: {},
+          pages: [],
+          terms: {},
+        },
+      },
+      storefrontSeed: {
+        store: { name: 'Florain' },
+        products: [],
+        items: [{ id: 'item_1' }],
+        categories: [{ id: 'cat_1' }],
+        addons: [{ id: 'addon_1' }],
+        menus: [{ id: 'menu_1' }],
+      },
+    });
+
+    expect(parsed.shopSlug).toBe('florain');
+    expect(parsed.storefrontSeed.items).toEqual([{ id: 'item_1' }]);
+    expect(parsed.storefrontSeed.categories).toEqual([{ id: 'cat_1' }]);
+    expect(parsed.storefrontSeed.addons).toEqual([{ id: 'addon_1' }]);
+    expect(parsed.storefrontSeed.menus).toEqual([{ id: 'menu_1' }]);
+  });
+
+  it('merges preview boot slug into initial data while preserving catalog passthrough fields', () => {
+    const initialData = mergePreviewBootIntoInitialData({
+      shopId: 'shop_1',
+      shopSlug: 'florain',
+      builderSettings: {
+        version: 2,
+        revision: 1,
+        theme: {
+          content: {},
+          layout: {},
+          style_slots: {},
+          pages: [],
+          terms: {},
+        },
+      },
+      storefrontSeed: {
+        store: { name: 'Florain' },
+        products: [],
+        items: [{ id: 'item_1' }],
+        categories: [{ id: 'cat_1' }],
+        addons: [{ id: 'addon_1' }],
+        menus: [{ id: 'menu_1' }],
+      },
+    });
+
+    expect(initialData.store).toMatchObject({
+      id: 'shop_1',
+      slug: 'florain',
+      name: 'Florain',
+    });
+    expect(initialData.items).toEqual([{ id: 'item_1' }]);
+    expect(initialData.categories).toEqual([{ id: 'cat_1' }]);
+    expect(initialData.addons).toEqual([{ id: 'addon_1' }]);
+    expect(initialData.menus).toEqual([{ id: 'menu_1' }]);
+  });
+});

package/src/preview-boot.ts

@@ -3,6 +3,8 @@ import { BuilderSettingsSchema } from './builder-settings.ts';
 
 export const PREVIEW_BOOT_SIDECAR_PATH = '__shoppex/preview-boot.json';
 
+// Artifact HTML seeds include catalog/menu fields beyond the documented minimum.
+// Passthrough keeps them available to the theme runtime in preview boot.
 export const StorefrontSeedSchema = z
   .object({
     store: z.record(z.string(), z.unknown()),
@@ -10,7 +12,7 @@ export const StorefrontSeedSchema = z
     groups: z.array(z.unknown()).optional(),
     pages: z.array(z.unknown()).optional(),
   })
-  .strict();
+  .passthrough();
 
 export type StorefrontSeed = z.infer<typeof StorefrontSeedSchema>;
 

package/src/preview-protocol.test.ts

@@ -5,6 +5,44 @@ import {
 } from './preview-protocol.ts';
 
 describe('PreviewMessageSchema', () => {
+  it('accepts v3 block HTML apply messages', () => {
+    const parsed = PreviewMessageSchema.parse({
+      type: 'APPLY_BLOCK_HTML',
+      revision: 12,
+      pageId: 'product',
+      sourceRevision: 'theme-source-12',
+      renderMode: 'edge-block-engine',
+      blocks: [
+        {
+          blockId: 'product-form-1',
+          html: '<section data-builder-block="product-form-1">Updated</section>',
+        },
+      ],
+    });
+
+    expect(parsed.type).toBe('APPLY_BLOCK_HTML');
+    if (parsed.type === 'APPLY_BLOCK_HTML') {
+      expect(parsed.blocks[0]?.blockId).toBe('product-form-1');
+    }
+  });
+
+  it('rejects v3 block HTML apply messages without sourceRevision', () => {
+    const result = PreviewMessageSchema.safeParse({
+      type: 'APPLY_BLOCK_HTML',
+      revision: 12,
+      pageId: 'product',
+      renderMode: 'edge-block-engine',
+      blocks: [
+        {
+          blockId: 'product-form-1',
+          html: '<section data-builder-block="product-form-1">Updated</section>',
+        },
+      ],
+    });
+
+    expect(result.success).toBe(false);
+  });
+
   it('accepts SET_INTERACTION_MODE with edit/preview', () => {
     for (const mode of ['edit', 'preview'] as const) {
       const parsed = PreviewMessageSchema.parse({
@@ -25,6 +63,58 @@ describe('PreviewMessageSchema', () => {
 });
 
 describe('PreviewResponseSchema', () => {
+  it('accepts READY health for edge block protocol v3', () => {
+    const parsed = PreviewResponseSchema.parse({
+      type: 'READY',
+      revision: 12,
+      health: {
+        edgeBlockEngine: true,
+        blockHtmlReconcile: true,
+        protocolVersion: 3,
+      },
+    });
+
+    expect(parsed.type).toBe('READY');
+    if (parsed.type === 'READY') {
+      expect(parsed.health?.protocolVersion).toBe(3);
+    }
+  });
+
+  it('accepts v3 block HTML applied responses', () => {
+    const parsed = PreviewResponseSchema.parse({
+      type: 'BLOCK_HTML_APPLIED',
+      revision: 12,
+      pageId: 'product',
+      sourceRevision: 'theme-source-12',
+      renderMode: 'edge-block-engine',
+      blocks: [
+        {
+          blockId: 'footer-1',
+          html: '<footer data-builder-block="footer-1">Secure delivery</footer>',
+        },
+      ],
+    });
+
+    expect(parsed.type).toBe('BLOCK_HTML_APPLIED');
+    if (parsed.type === 'BLOCK_HTML_APPLIED') {
+      expect(parsed.renderMode).toBe('edge-block-engine');
+    }
+  });
+
+  it('accepts v3 block HTML failed responses', () => {
+    const parsed = PreviewResponseSchema.parse({
+      type: 'BLOCK_HTML_FAILED',
+      revision: 12,
+      pageId: 'product',
+      sourceRevision: 'theme-source-12',
+      renderMode: 'edge-block-engine',
+      blockIds: ['footer-1'],
+      error: 'Rendered block root does not match block id.',
+    });
+
+    expect(parsed.type).toBe('BLOCK_HTML_FAILED');
+  });
+
   it('accepts BLOCK_RECT with rect', () => {
     const parsed = PreviewResponseSchema.parse({
       type: 'BLOCK_RECT',

package/src/preview-protocol.ts

@@ -24,6 +24,28 @@ export const PreviewApplyStateMessageSchema = z
   })
   .strict();
 
+export const EdgeBlockRenderModeSchema = z.literal('edge-block-engine');
+export type EdgeBlockRenderMode = z.infer<typeof EdgeBlockRenderModeSchema>;
+
+export const PreviewBlockHtmlPatchSchema = z
+  .object({
+    blockId: z.string().min(1),
+    html: z.string().min(1),
+  })
+  .strict();
+export type PreviewBlockHtmlPatch = z.infer<typeof PreviewBlockHtmlPatchSchema>;
+
+export const PreviewApplyBlockHtmlMessageSchema = z
+  .object({
+    type: z.literal('APPLY_BLOCK_HTML'),
+    revision: z.number().int().nonnegative(),
+    pageId: z.string().min(1),
+    sourceRevision: z.string().min(1),
+    renderMode: EdgeBlockRenderModeSchema,
+    blocks: z.array(PreviewBlockHtmlPatchSchema).min(1),
+  })
+  .strict();
+
 export const PreviewReloadMessageSchema = z
   .object({
     type: z.literal('RELOAD'),
@@ -64,6 +86,7 @@ export const PreviewSetInteractionModeMessageSchema = z
 
 export const PreviewMessageSchema = z.discriminatedUnion('type', [
   PreviewApplyStateMessageSchema,
+  PreviewApplyBlockHtmlMessageSchema,
   PreviewReloadMessageSchema,
   PreviewSelectElementMessageSchema,
   PreviewRequestReadyMessageSchema,
@@ -81,18 +104,29 @@ export const PreviewBootstrapOkResponseSchema = z
   })
   .strict();
 
+export const PreviewReadyHealthSchema = z.discriminatedUnion('protocolVersion', [
+  z
+    .object({
+      reactMounted: z.literal(true),
+      builderRuntimeProvider: z.literal(true),
+      protocolVersion: z.literal(2),
+    })
+    .strict(),
+  z
+    .object({
+      edgeBlockEngine: z.literal(true),
+      blockHtmlReconcile: z.literal(true),
+      protocolVersion: z.literal(3),
+    })
+    .strict(),
+]);
+export type PreviewReadyHealth = z.infer<typeof PreviewReadyHealthSchema>;
+
 export const PreviewReadyResponseSchema = z
   .object({
     type: z.literal('READY'),
     revision: z.number().int().nonnegative(),
-    health: z
-      .object({
-        reactMounted: z.literal(true),
-        builderRuntimeProvider: z.literal(true),
-        protocolVersion: z.literal(2),
-      })
-      .strict()
-      .optional(),
+    health: PreviewReadyHealthSchema.optional(),
   })
   .strict();
 
@@ -111,6 +145,29 @@ export const PreviewApplyFailedResponseSchema = z
   })
   .strict();
 
+export const PreviewBlockHtmlAppliedResponseSchema = z
+  .object({
+    type: z.literal('BLOCK_HTML_APPLIED'),
+    revision: z.number().int().nonnegative(),
+    pageId: z.string().min(1),
+    sourceRevision: z.string().min(1),
+    renderMode: EdgeBlockRenderModeSchema,
+    blocks: z.array(PreviewBlockHtmlPatchSchema).min(1),
+  })
+  .strict();
+
+export const PreviewBlockHtmlFailedResponseSchema = z
+  .object({
+    type: z.literal('BLOCK_HTML_FAILED'),
+    revision: z.number().int().nonnegative(),
+    pageId: z.string().min(1),
+    sourceRevision: z.string().min(1).optional(),
+    renderMode: EdgeBlockRenderModeSchema,
+    blockIds: z.array(z.string().min(1)).min(1),
+    error: z.string().min(1),
+  })
+  .strict();
+
 export const PreviewElementClickedResponseSchema = z
   .object({
     type: z.literal('ELEMENT_CLICKED'),
@@ -206,6 +263,8 @@ export const PreviewResponseSchema = z.discriminatedUnion('type', [
   PreviewReadyResponseSchema,
   PreviewAppliedResponseSchema,
   PreviewApplyFailedResponseSchema,
+  PreviewBlockHtmlAppliedResponseSchema,
+  PreviewBlockHtmlFailedResponseSchema,
   PreviewElementClickedResponseSchema,
   PreviewErrorResponseSchema,
   PreviewBlockRectResponseSchema,

package/src/preview-session-resolve.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest';
+import { parseBuilderPreviewResolveResponse } from './preview-session-resolve.ts';
+
+describe('parseBuilderPreviewResolveResponse', () => {
+  it('accepts Elysia API envelope fields without failing strict parsing', () => {
+    const parsed = parseBuilderPreviewResolveResponse({
+      status: 200,
+      data: {
+        sessionId: 'bp_test',
+        shopId: 'shop_1',
+        shopSlug: 'demo-shop',
+        themeId: 'theme_1',
+        artifactPrefix: 'theme-artifacts/shop_1/theme_1/artifact/',
+        builderSettings: {
+          version: 2,
+          revision: 0,
+          theme: {
+            content: {},
+            layout: {},
+            style_slots: {},
+            pages: [],
+            terms: {},
+          },
+        },
+        sourceRevision: 'rev_1',
+      },
+      error: null,
+      message: null,
+      log: null,
+      env: 'development',
+    });
+
+    expect(parsed).not.toBeNull();
+    expect(parsed?.data?.sessionId).toBe('bp_test');
+    expect(parsed?.data?.shopSlug).toBe('demo-shop');
+  });
+});

package/src/preview-session-resolve.ts

@@ -20,9 +20,9 @@ export const BuilderPreviewResolveResponseSchema = z
   .object({
     status: z.number(),
     data: BuilderPreviewResolveDataSchema.nullable(),
-    error: z.string().nullable(),
+    error: z.string().nullable().optional(),
   })
-  .strict();
+  .strip();
 
 export type BuilderPreviewResolveResponse = z.infer<typeof BuilderPreviewResolveResponseSchema>;
 

package/src/storefront-initial-data-html.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from 'bun:test';
 import {
   assertSingleInitialDataScript,
   buildPlainInitialDataScript,
+  buildWrappedStorefrontInitialDataScript,
   countInitialDataScripts,
   findInitialDataPayload,
   injectPreviewInitialData,
@@ -45,6 +46,16 @@ describe('storefront-initial-data-html', () => {
     });
   });
 
+  it('injects slug into artifact HTML that has no initial-data scripts', () => {
+    const html = '<html><head><script src="./assets/main.js"></script></head><body></body></html>';
+    const next = injectPreviewInitialData(html, samplePayload);
+    expect(countInitialDataScripts(next)).toBe(1);
+    assertSingleInitialDataScript(next, 'demo-shop');
+    expect(findInitialDataPayload(next)?.store).toMatchObject({
+      id: 'shop_1',
+      slug: 'demo-shop',
+    });
+  });
   it('throws when assert sees zero or multiple scripts', () => {
     expect(() => assertSingleInitialDataScript('<html></html>', 'demo-shop')).toThrow();
     const html = [
@@ -60,4 +71,11 @@ describe('storefront-initial-data-html', () => {
     const stripped = stripAllInitialDataScripts(`${wrapped}${legacy}`);
     expect(stripped).not.toContain('__SHOPPEX_INITIAL__');
   });
+
+  it('marks wrapped initial data as a deployed theme artifact on friendly storefront paths', () => {
+    const script = buildWrappedStorefrontInitialDataScript('{"store":{"slug":"demo-shop"}}', /^\/themes-live\//);
+
+    expect(script).toContain('window.__SHOPPEX_DEPLOYED_THEME_ARTIFACT__=true');
+    expect(script).toContain('window.__SHOPPEX_INITIAL__={"store":{"slug":"demo-shop"}}');
+  });
 });

package/src/storefront-initial-data-html.ts

@@ -66,7 +66,7 @@ export function buildWrappedStorefrontInitialDataScript(
 ): string {
   return [
     '<!--shoppex-initial-data:start--><script>(function(){',
-    'if(typeof window!=="undefined"){var path=window.location.pathname||"";',
+    'if(typeof window!=="undefined"){window.__SHOPPEX_DEPLOYED_THEME_ARTIFACT__=true;var path=window.location.pathname||"";',
     `if(${deployedThemeEntryPathPattern}.test(path)){window.__SHOPPEX_DEPLOYED_THEME_ARTIFACT_PATH__=path;window.history.replaceState(window.history.state,"","/"+window.location.search+window.location.hash);}}`,
     `window.__SHOPPEX_INITIAL__=${serialized};})();</script><!--shoppex-initial-data:end-->`,
   ].join('');

package/src/storefront-typography-fonts.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  buildStorefrontGoogleFontHref,
+  curatedFontOptionsForValue,
+  getStorefrontGoogleFontHrefs,
+  resolveCuratedFontValue,
+  resolvePrimaryFontFamilyName,
+} from './storefront-typography-fonts.ts';
+
+describe('storefront typography fonts', () => {
+  test('resolves curated and stack values to primary family names', () => {
+    expect(resolvePrimaryFontFamilyName('Manrope, sans-serif')).toBe('Manrope');
+    expect(resolvePrimaryFontFamilyName('"Space Grotesk", sans-serif')).toBe('Space Grotesk');
+    expect(resolveCuratedFontValue(undefined, 'Inter')).toBe('Inter');
+  });
+
+  test('builds google font hrefs for web fonts and skips system fonts', () => {
+    expect(getStorefrontGoogleFontHrefs({
+      bodyFont: 'Manrope',
+      headingFont: 'Georgia, serif',
+    })).toEqual([
+      buildStorefrontGoogleFontHref('Manrope'),
+    ]);
+  });
+
+  test('dedupes body and heading google font requests', () => {
+    expect(getStorefrontGoogleFontHrefs({
+      bodyFont: 'Inter',
+      headingFont: 'Inter, sans-serif',
+    })).toEqual([
+      buildStorefrontGoogleFontHref('Inter'),
+    ]);
+  });
+
+  test('includes custom google font families', () => {
+    expect(getStorefrontGoogleFontHrefs({
+      bodyFont: 'Clash Display',
+    })).toEqual([
+      buildStorefrontGoogleFontHref('Clash Display'),
+    ]);
+  });
+
+  test('keeps unknown custom values selectable in curated options', () => {
+    const options = curatedFontOptionsForValue('Clash Display');
+    expect(options.some((font) => font.value === 'Clash Display')).toBe(true);
+    expect(options.some((font) => font.value === 'Inter')).toBe(true);
+  });
+});

package/src/storefront-typography-fonts.ts

@@ -0,0 +1,108 @@
+export type StorefrontCuratedFont = {
+  value: string;
+  label: string;
+  stack: string;
+};
+
+export const STOREFRONT_SYSTEM_FONTS = new Set(['Arial', 'Georgia', 'System UI']);
+
+export const STOREFRONT_CURATED_FONTS: StorefrontCuratedFont[] = [
+  { value: 'Inter', label: 'Inter', stack: 'Inter, system-ui, sans-serif' },
+  { value: 'Geist', label: 'Geist', stack: 'Geist, system-ui, sans-serif' },
+  { value: 'Manrope', label: 'Manrope', stack: 'Manrope, system-ui, sans-serif' },
+  {
+    value: 'Plus Jakarta Sans',
+    label: 'Plus Jakarta Sans',
+    stack: '"Plus Jakarta Sans", system-ui, sans-serif',
+  },
+  { value: 'DM Sans', label: 'DM Sans', stack: '"DM Sans", system-ui, sans-serif' },
+  {
+    value: 'Space Grotesk',
+    label: 'Space Grotesk',
+    stack: '"Space Grotesk", system-ui, sans-serif',
+  },
+  { value: 'Sora', label: 'Sora', stack: 'Sora, system-ui, sans-serif' },
+  {
+    value: 'IBM Plex Sans',
+    label: 'IBM Plex Sans',
+    stack: '"IBM Plex Sans", system-ui, sans-serif',
+  },
+  { value: 'Arial', label: 'Arial', stack: 'Arial, sans-serif' },
+  { value: 'Georgia', label: 'Georgia', stack: 'Georgia, serif' },
+  { value: 'System UI', label: 'System UI', stack: 'system-ui, sans-serif' },
+];
+
+const GOOGLE_FONT_FAMILY_PATTERN = /^[A-Za-z0-9 +\-_]+$/;
+
+export function resolvePrimaryFontFamilyName(raw: unknown): string | null {
+  if (typeof raw !== 'string') return null;
+  const trimmed = raw.trim();
+  if (!trimmed) return null;
+
+  const exact = STOREFRONT_CURATED_FONTS.find(
+    (font) => font.value === trimmed || font.stack === trimmed,
+  );
+  if (exact) return exact.value;
+
+  const prefix = STOREFRONT_CURATED_FONTS.find((font) => trimmed.startsWith(`${font.value},`));
+  if (prefix) return prefix.value;
+
+  const quoted = trimmed.match(/^["'](.+?)["']/);
+  if (quoted?.[1]) {
+    return quoted[1].trim() || null;
+  }
+
+  const primary = trimmed.split(',')[0]?.trim();
+  return primary && primary.length > 0 ? primary : null;
+}
+
+export function resolveCuratedFontValue(raw: unknown, fallback: string): string {
+  return resolvePrimaryFontFamilyName(raw) ?? fallback;
+}
+
+export function curatedFontOptionsForValue(value: string): StorefrontCuratedFont[] {
+  if (STOREFRONT_CURATED_FONTS.some((font) => font.value === value)) {
+    return STOREFRONT_CURATED_FONTS;
+  }
+
+  return [
+    ...STOREFRONT_CURATED_FONTS,
+    {
+      value,
+      label: value,
+      stack: value.includes(',') ? value : `${value}, system-ui, sans-serif`,
+    },
+  ];
+}
+
+export function findStorefrontCuratedFont(value: string): StorefrontCuratedFont | undefined {
+  return curatedFontOptionsForValue(value).find((font) => font.value === value);
+}
+
+export function isValidGoogleFontFamily(value: unknown): value is string {
+  if (typeof value !== 'string') return false;
+  const trimmed = value.trim();
+  return trimmed.length > 0 && trimmed.length <= 60 && GOOGLE_FONT_FAMILY_PATTERN.test(trimmed);
+}
+
+export function buildStorefrontGoogleFontHref(family: string): string {
+  const familyParam = family.trim().replace(/\s+/g, '+');
+  return `https://fonts.googleapis.com/css2?family=${familyParam}:wght@400;500;600;700&display=swap`;
+}
+
+export function getStorefrontGoogleFontHrefs(input: {
+  bodyFont?: unknown;
+  headingFont?: unknown;
+}): string[] {
+  const families = new Set<string>();
+
+  for (const raw of [input.bodyFont, input.headingFont]) {
+    const family = resolvePrimaryFontFamilyName(raw);
+    if (!family) continue;
+    if (STOREFRONT_SYSTEM_FONTS.has(family)) continue;
+    if (!isValidGoogleFontFamily(family)) continue;
+    families.add(family);
+  }
+
+  return [...families].map((family) => buildStorefrontGoogleFontHref(family));
+}