@shoppexio/builder-contracts 0.1.0 → 0.1.2

package/src/preview-protocol.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, it } from 'vitest';
+import {
+  PreviewMessageSchema,
+  PreviewResponseSchema,
+} from './preview-protocol.ts';
+
+describe('PreviewMessageSchema', () => {
+  it('accepts SET_INTERACTION_MODE with edit/preview', () => {
+    for (const mode of ['edit', 'preview'] as const) {
+      const parsed = PreviewMessageSchema.parse({
+        type: 'SET_INTERACTION_MODE',
+        mode,
+      });
+      expect(parsed).toEqual({ type: 'SET_INTERACTION_MODE', mode });
+    }
+  });
+
+  it('rejects unknown interaction mode', () => {
+    const result = PreviewMessageSchema.safeParse({
+      type: 'SET_INTERACTION_MODE',
+      mode: 'design',
+    });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe('PreviewResponseSchema', () => {
+  it('accepts BLOCK_RECT with rect', () => {
+    const parsed = PreviewResponseSchema.parse({
+      type: 'BLOCK_RECT',
+      revision: 4,
+      blockId: 'hero-1',
+      rect: { top: 10, left: 20, width: 300, height: 120 },
+    });
+    expect(parsed.type).toBe('BLOCK_RECT');
+    if (parsed.type === 'BLOCK_RECT') {
+      expect(parsed.rect).toEqual({ top: 10, left: 20, width: 300, height: 120 });
+    }
+  });
+
+  it('accepts BLOCK_RECT with null rect to clear toolbar', () => {
+    const parsed = PreviewResponseSchema.parse({
+      type: 'BLOCK_RECT',
+      blockId: 'hero-1',
+      rect: null,
+    });
+    expect(parsed.type).toBe('BLOCK_RECT');
+    if (parsed.type === 'BLOCK_RECT') {
+      expect(parsed.rect).toBeNull();
+    }
+  });
+
+  it('accepts INSERTER_HOVER with null index to clear affordance', () => {
+    const parsed = PreviewResponseSchema.parse({
+      type: 'INSERTER_HOVER',
+      index: null,
+      rect: null,
+    });
+    expect(parsed.type).toBe('INSERTER_HOVER');
+  });
+
+  it('accepts INSERTER_HOVER with index + rect', () => {
+    const parsed = PreviewResponseSchema.parse({
+      type: 'INSERTER_HOVER',
+      index: 2,
+      rect: { top: 100, left: 0, width: 800, height: 16 },
+    });
+    expect(parsed.type).toBe('INSERTER_HOVER');
+    if (parsed.type === 'INSERTER_HOVER') {
+      expect(parsed.index).toBe(2);
+    }
+  });
+
+  it('accepts INLINE_EDIT_COMMIT', () => {
+    const parsed = PreviewResponseSchema.parse({
+      type: 'INLINE_EDIT_COMMIT',
+      blockId: 'hero-1',
+      contentPath: 'hero.title',
+      value: 'Launch sale',
+    });
+    expect(parsed.type).toBe('INLINE_EDIT_COMMIT');
+    if (parsed.type === 'INLINE_EDIT_COMMIT') {
+      expect(parsed.value).toBe('Launch sale');
+    }
+  });
+
+  it('accepts BOOTSTRAP_OK', () => {
+    const parsed = PreviewResponseSchema.parse({
+      type: 'BOOTSTRAP_OK',
+      revision: 3,
+      shopSlug: 'demo-shop',
+      shopId: 'shop_1',
+    });
+    expect(parsed.type).toBe('BOOTSTRAP_OK');
+  });
+
+  it('accepts PREVIEW_ERROR with bootstrap phase', () => {
+    const parsed = PreviewResponseSchema.parse({
+      type: 'PREVIEW_ERROR',
+      message: 'Preview initial data is missing store slug',
+      source: 'bootstrap',
+      phase: 'bootstrap',
+    });
+    expect(parsed.type).toBe('PREVIEW_ERROR');
+    if (parsed.type === 'PREVIEW_ERROR') {
+      expect(parsed.phase).toBe('bootstrap');
+    }
+  });
+
+  it('accepts BOOTSTRAP_OK with artifact stale hint', () => {
+    const parsed = PreviewResponseSchema.parse({
+      type: 'BOOTSTRAP_OK',
+      revision: 3,
+      shopSlug: 'demo-shop',
+      shopId: 'shop_1',
+      artifactStale: true,
+    });
+    expect(parsed.type).toBe('BOOTSTRAP_OK');
+    if (parsed.type === 'BOOTSTRAP_OK') {
+      expect(parsed.artifactStale).toBe(true);
+    }
+  });
+
+  it('rejects INLINE_EDIT_COMMIT without contentPath', () => {
+    const result = PreviewResponseSchema.safeParse({
+      type: 'INLINE_EDIT_COMMIT',
+      blockId: 'hero-1',
+      value: 'foo',
+    });
+    expect(result.success).toBe(false);
+  });
+});

package/src/preview-protocol.ts

@@ -46,18 +46,53 @@ export const PreviewRequestReadyMessageSchema = z
   })
   .strict();
 
+export const InteractionModeSchema = z.enum(['edit', 'preview']);
+export type InteractionMode = z.infer<typeof InteractionModeSchema>;
+
+/**
+ * Dashboard tells the runtime which interaction mode is active:
+ *  - "edit" (default) intercepts clicks for selection.
+ *  - "preview" lets the storefront react to clicks/links normally so
+ *    a merchant can test buy-now flows or anchor links.
+ */
+export const PreviewSetInteractionModeMessageSchema = z
+  .object({
+    type: z.literal('SET_INTERACTION_MODE'),
+    mode: InteractionModeSchema,
+  })
+  .strict();
+
 export const PreviewMessageSchema = z.discriminatedUnion('type', [
   PreviewApplyStateMessageSchema,
   PreviewReloadMessageSchema,
   PreviewSelectElementMessageSchema,
   PreviewRequestReadyMessageSchema,
+  PreviewSetInteractionModeMessageSchema,
 ]);
 export type PreviewMessage = z.infer<typeof PreviewMessageSchema>;
 
+export const PreviewBootstrapOkResponseSchema = z
+  .object({
+    type: z.literal('BOOTSTRAP_OK'),
+    revision: z.number().int().nonnegative(),
+    shopSlug: z.string().min(1),
+    shopId: z.string().min(1),
+    artifactStale: z.boolean().optional(),
+  })
+  .strict();
+
 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(),
   })
   .strict();
 
@@ -84,10 +119,97 @@ export const PreviewElementClickedResponseSchema = z
   })
   .strict();
 
+export const PreviewErrorResponseSchema = z
+  .object({
+    type: z.literal('PREVIEW_ERROR'),
+    revision: z.number().int().nonnegative().optional(),
+    message: z.string().min(1),
+    stack: z.string().optional(),
+    source: z.enum(['bootstrap', 'error', 'unhandledrejection']).optional(),
+    phase: z.enum(['bootstrap', 'runtime']).optional(),
+    diagnostics: z
+      .object({
+        name: z.string().optional(),
+        filename: z.string().optional(),
+        lineno: z.number().optional(),
+        colno: z.number().optional(),
+        href: z.string().optional(),
+        referrer: z.string().optional(),
+        parentOrigin: z.string().optional(),
+        previewMode: z.string().optional(),
+        userAgent: z.string().optional(),
+        localStorage: z.enum(['available', 'blocked', 'unknown']).optional(),
+        sessionStorage: z.enum(['available', 'blocked', 'unknown']).optional(),
+        historyScrollRestoration: z.enum(['available', 'blocked', 'unknown']).optional(),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+
+/**
+ * Geometry of a block inside the preview iframe, expressed in the iframe's
+ * own coordinate space (viewport-relative). The dashboard converts these
+ * coordinates to its own overlay layer when positioning the floating
+ * toolbar / drag handle / insert affordances.
+ */
+export const PreviewRectSchema = z
+  .object({
+    top: z.number().finite(),
+    left: z.number().finite(),
+    width: z.number().finite(),
+    height: z.number().finite(),
+  })
+  .strict();
+export type PreviewRect = z.infer<typeof PreviewRectSchema>;
+
+export const PreviewBlockRectResponseSchema = z
+  .object({
+    type: z.literal('BLOCK_RECT'),
+    revision: z.number().int().nonnegative().optional(),
+    blockId: z.string().min(1),
+    rect: PreviewRectSchema.nullable(),
+  })
+  .strict();
+
+/**
+ * Preview reports a gap between two consecutive blocks that the user is
+ * hovering. The dashboard renders a "+" insert affordance there. When
+ * the user moves away from any gap, `index` is null.
+ */
+export const PreviewInserterHoverResponseSchema = z
+  .object({
+    type: z.literal('INSERTER_HOVER'),
+    revision: z.number().int().nonnegative().optional(),
+    index: z.number().int().nonnegative().nullable(),
+    rect: PreviewRectSchema.nullable(),
+  })
+  .strict();
+
+/**
+ * Inline-edit commit. The runtime captures contenteditable text on
+ * blur/Enter and sends the result back to the dashboard, which writes
+ * it to the corresponding block/content path through the store.
+ */
+export const PreviewInlineEditCommitResponseSchema = z
+  .object({
+    type: z.literal('INLINE_EDIT_COMMIT'),
+    revision: z.number().int().nonnegative().optional(),
+    blockId: z.string().min(1),
+    contentPath: z.string().min(1),
+    value: z.string(),
+  })
+  .strict();
+
 export const PreviewResponseSchema = z.discriminatedUnion('type', [
+  PreviewBootstrapOkResponseSchema,
   PreviewReadyResponseSchema,
   PreviewAppliedResponseSchema,
   PreviewApplyFailedResponseSchema,
   PreviewElementClickedResponseSchema,
+  PreviewErrorResponseSchema,
+  PreviewBlockRectResponseSchema,
+  PreviewInserterHoverResponseSchema,
+  PreviewInlineEditCommitResponseSchema,
 ]);
 export type PreviewResponse = z.infer<typeof PreviewResponseSchema>;

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

@@ -0,0 +1,34 @@
+import * as z from 'zod/v4';
+import { BuilderSettingsSchema } from './builder-settings.ts';
+
+export const BuilderPreviewResolveDataSchema = z
+  .object({
+    sessionId: z.string().min(1),
+    shopId: z.string().min(1),
+    shopSlug: z.string().min(1),
+    themeId: z.string().min(1),
+    artifactPrefix: z.string().min(1),
+    builderSettings: BuilderSettingsSchema,
+    artifactStale: z.boolean().optional(),
+    sourceRevision: z.string().nullable().optional(),
+  })
+  .strict();
+
+export type BuilderPreviewResolveData = z.infer<typeof BuilderPreviewResolveDataSchema>;
+
+export const BuilderPreviewResolveResponseSchema = z
+  .object({
+    status: z.number(),
+    data: BuilderPreviewResolveDataSchema.nullable(),
+    error: z.string().nullable().optional(),
+  })
+  .strip();
+
+export type BuilderPreviewResolveResponse = z.infer<typeof BuilderPreviewResolveResponseSchema>;
+
+export function parseBuilderPreviewResolveResponse(
+  value: unknown,
+): BuilderPreviewResolveResponse | null {
+  const parsed = BuilderPreviewResolveResponseSchema.safeParse(value);
+  return parsed.success ? parsed.data : null;
+}

package/src/preview-trusted-origins.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'bun:test';
+import { isTrustedPreviewParentOrigin } from './preview-trusted-origins.ts';
+
+describe('isTrustedPreviewParentOrigin', () => {
+  it('accepts production dashboard and app origins', () => {
+    expect(isTrustedPreviewParentOrigin('https://dashboard.shoppex.io')).toBe(true);
+    expect(isTrustedPreviewParentOrigin('https://app.shoppex.io')).toBe(true);
+    expect(isTrustedPreviewParentOrigin('https://shoppex-dashboard.vercel.app')).toBe(true);
+  });
+
+  it('accepts local and preview dashboard hosts', () => {
+    expect(isTrustedPreviewParentOrigin('http://localhost:3100')).toBe(true);
+    expect(isTrustedPreviewParentOrigin('http://[::1]:3100')).toBe(true);
+    expect(isTrustedPreviewParentOrigin('https://dashboard.shoppex.test')).toBe(true);
+  });
+
+  it('rejects unknown origins', () => {
+    expect(isTrustedPreviewParentOrigin('https://evil.example')).toBe(false);
+    expect(isTrustedPreviewParentOrigin('https://evil.vercel.app')).toBe(false);
+    expect(isTrustedPreviewParentOrigin('https://shoppex-dashboard.evil.vercel.app')).toBe(false);
+    expect(isTrustedPreviewParentOrigin('https://preview.vercel.run')).toBe(false);
+    expect(isTrustedPreviewParentOrigin('ftp://localhost:3000')).toBe(false);
+  });
+});

package/src/preview-trusted-origins.ts

@@ -0,0 +1,35 @@
+export const TRUSTED_PREVIEW_PARENT_ORIGINS = [
+  'https://app.shoppex.io',
+  'https://dashboard.shoppex.io',
+  'https://dashboard.shoppex.test',
+  'https://shoppex-dashboard.vercel.app',
+  'http://localhost:3000',
+  'http://127.0.0.1:3000',
+] as const;
+
+export type TrustedPreviewParentOrigin = (typeof TRUSTED_PREVIEW_PARENT_ORIGINS)[number];
+
+export function isTrustedPreviewParentOrigin(origin: string): boolean {
+  if (TRUSTED_PREVIEW_PARENT_ORIGINS.includes(origin as TrustedPreviewParentOrigin)) {
+    return true;
+  }
+
+  try {
+    const url = new URL(origin);
+    const hostname = url.hostname.toLowerCase();
+    const isHttp = url.protocol === 'http:' || url.protocol === 'https:';
+    return (
+      isHttp
+      && (
+        hostname === 'dashboard.shoppex.test'
+        || hostname === 'localhost'
+        || hostname === '127.0.0.1'
+        || hostname === '::1'
+        || hostname === '[::1]'
+        || hostname.endsWith('.localhost')
+      )
+    );
+  } catch {
+    return false;
+  }
+}

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

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'bun:test';
+import {
+  assertSingleInitialDataScript,
+  buildPlainInitialDataScript,
+  countInitialDataScripts,
+  findInitialDataPayload,
+  injectPreviewInitialData,
+  stripAllInitialDataScripts,
+} from './storefront-initial-data-html.ts';
+
+const samplePayload = {
+  shopId: 'shop_1',
+  shopSlug: 'demo-shop',
+  builderSettings: {
+    version: 2 as const,
+    revision: 3,
+    theme: {
+      content: {},
+      layout: {},
+      tokens_override: {},
+      style_slots: {},
+    },
+  },
+  storefrontSeed: {
+    store: { name: 'Demo' },
+    products: [],
+  },
+};
+
+describe('storefront-initial-data-html', () => {
+  it('strips duplicate initial-data scripts and injects one slug', () => {
+    const html = [
+      '<html><head></head><body>',
+      '<script>window.__SHOPPEX_INITIAL__={"store":{"id":"shop_1"}};</script>',
+      '<script>window.__SHOPPEX_INITIAL__={"store":{"slug":"stale"}};</script>',
+      '</body></html>',
+    ].join('');
+
+    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('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 = [
+      buildPlainInitialDataScript({ store: { slug: 'a' } }),
+      buildPlainInitialDataScript({ store: { slug: 'b' } }),
+    ].join('');
+    expect(() => assertSingleInitialDataScript(html, 'a')).toThrow(/exactly one/);
+  });
+
+  it('stripAllInitialDataScripts removes wrapped and legacy blocks', () => {
+    const wrapped = '<!--shoppex-initial-data:start--><script>window.__SHOPPEX_INITIAL__={};</script><!--shoppex-initial-data:end-->';
+    const legacy = '<script>window.__SHOPPEX_INITIAL__={};</script>';
+    const stripped = stripAllInitialDataScripts(`${wrapped}${legacy}`);
+    expect(stripped).not.toContain('__SHOPPEX_INITIAL__');
+  });
+});

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

@@ -0,0 +1,112 @@
+import type { PreviewBootPayload } from './preview-boot.ts';
+import { mergePreviewBootIntoInitialData } from './preview-boot.ts';
+
+export const HTML_INITIAL_BLOCK_PATTERN =
+  /<!--shoppex-initial-data:start--><script>\(function\(\)\{[\s\S]*?window\.__SHOPPEX_INITIAL__=([\s\S]*?)(?=;\}\)\(\);<\/script><!--shoppex-initial-data:end-->);\}\)\(\);<\/script><!--shoppex-initial-data:end-->/;
+
+export const LEGACY_HTML_INITIAL_PATTERN =
+  /<script>\s*window\.__SHOPPEX_INITIAL__=([\s\S]*?)<\/script>/;
+
+const HTML_INITIAL_BLOCK_GLOBAL_PATTERN = new RegExp(HTML_INITIAL_BLOCK_PATTERN.source, 'g');
+const LEGACY_HTML_INITIAL_GLOBAL_PATTERN = new RegExp(LEGACY_HTML_INITIAL_PATTERN.source, 'g');
+
+const CLOSING_HEAD_PATTERN = /<\/head>/i;
+
+export type InitialDataScriptMatch = {
+  json: string;
+};
+
+export function stripAllInitialDataScripts(html: string): string {
+  return html
+    .replace(HTML_INITIAL_BLOCK_GLOBAL_PATTERN, '')
+    .replace(LEGACY_HTML_INITIAL_GLOBAL_PATTERN, '');
+}
+
+export function findInitialDataScriptJson(html: string): InitialDataScriptMatch | null {
+  const blockMatch = html.match(HTML_INITIAL_BLOCK_PATTERN);
+  if (blockMatch?.[1]) {
+    return { json: blockMatch[1] };
+  }
+
+  const legacyMatch = html.match(LEGACY_HTML_INITIAL_PATTERN);
+  if (legacyMatch?.[1]) {
+    return { json: legacyMatch[1] };
+  }
+
+  return null;
+}
+
+export function findInitialDataPayload(html: string): Record<string, unknown> | null {
+  const match = findInitialDataScriptJson(html);
+  if (!match) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(match.json.replace(/;\s*$/, '')) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+export function countInitialDataScripts(html: string): number {
+  const blockMatches = html.match(HTML_INITIAL_BLOCK_GLOBAL_PATTERN)?.length ?? 0;
+  const stripped = html.replace(HTML_INITIAL_BLOCK_GLOBAL_PATTERN, '');
+  const legacyMatches = stripped.match(LEGACY_HTML_INITIAL_GLOBAL_PATTERN)?.length ?? 0;
+  return blockMatches + legacyMatches;
+}
+
+export function buildPlainInitialDataScript(initialData: Record<string, unknown>): string {
+  return `<script>window.__SHOPPEX_INITIAL__=${safeJson(initialData)};</script>`;
+}
+
+export function buildWrappedStorefrontInitialDataScript(
+  serialized: string,
+  deployedThemeEntryPathPattern: RegExp,
+): string {
+  return [
+    '<!--shoppex-initial-data:start--><script>(function(){',
+    'if(typeof window!=="undefined"){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('');
+}
+
+export function injectPlainInitialDataBeforeHeadClose(html: string, script: string): string {
+  if (CLOSING_HEAD_PATTERN.test(html)) {
+    return html.replace(CLOSING_HEAD_PATTERN, `${script}\n</head>`);
+  }
+  return `${script}\n${html}`;
+}
+
+export function injectPreviewInitialData(html: string, payload: PreviewBootPayload): string {
+  const withoutScripts = stripAllInitialDataScripts(html);
+  const initialData = mergePreviewBootIntoInitialData(payload);
+  const script = buildPlainInitialDataScript(initialData);
+  return injectPlainInitialDataBeforeHeadClose(withoutScripts, script);
+}
+
+export function assertSingleInitialDataScript(html: string, expectedSlug: string): void {
+  const count = countInitialDataScripts(html);
+  if (count !== 1) {
+    throw new Error(`Expected exactly one initial-data script, found ${count}`);
+  }
+
+  const payload = findInitialDataPayload(html);
+  const store = payload?.store;
+  const slug = typeof store === 'object' && store !== null && !Array.isArray(store)
+    ? (store as Record<string, unknown>).slug
+    : null;
+
+  if (typeof slug !== 'string' || slug.trim().length === 0) {
+    throw new Error('Initial-data script is missing store.slug');
+  }
+
+  if (slug.trim() !== expectedSlug) {
+    throw new Error(`Initial-data slug mismatch: expected ${expectedSlug}, got ${slug}`);
+  }
+}
+
+export function safeJson(value: unknown): string {
+  return JSON.stringify(value).replace(/</g, '\\u003c');
+}

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);
+  });
+});