@shoppexio/builder-contracts 0.1.1 → 0.1.2

package/src/migrations.ts

@@ -1,3 +1,4 @@
+import { migrateDedicatedPageContent, migrateDedicatedPageLayout } from './dedicated-pages.ts';
 import {
   BUILDER_SETTINGS_VERSION,
   type BlockInstance,
@@ -67,13 +68,15 @@ export function migrateLegacyBuilderSettings(input: LegacyBuilderSettingsInput,
     ...mapLegacyTokenOverridesToStyleSlots(tokensOverride),
     ...(input.theme?.style_slots ?? {}),
   };
+  const rawContent = input.theme?.content ?? {};
+  const rawLayout = input.theme?.layout ?? {};
 
   return sanitizeBuilderSettingsState(BuilderSettingsSchema.parse({
     version: BUILDER_SETTINGS_VERSION,
     revision,
     theme: {
-      content: input.theme?.content ?? {},
-      layout: normalizeLegacyLayout(input.theme?.layout ?? {}),
+      content: migrateDedicatedPageContent(rawContent as Record<string, unknown>),
+      layout: migrateDedicatedPageLayout(normalizeLegacyLayout(rawLayout) as Record<string, unknown>),
       style_slots: styleSlots,
       pages: [],
       terms: {},

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-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

@@ -45,6 +45,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 = [

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

package/src/style-slots.ts

@@ -25,9 +25,12 @@ export const ResponsiveStringSchema = z
   .strict();
 export type ResponsiveString = z.infer<typeof ResponsiveStringSchema>;
 
-export const ColorSchema = z
-  .string()
-  .regex(/^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/, 'Expected a hex color');
+const HEX_COLOR_PATTERN = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+
+export const ColorSchema = z.union([
+  z.literal('transparent'),
+  z.string().regex(HEX_COLOR_PATTERN, 'Expected a hex color'),
+]);
 export type Color = z.infer<typeof ColorSchema>;
 
 export const FontWeightSchema = z.union([

package/src/theme-schemes.ts

@@ -7,6 +7,7 @@ export const PUBLIC_BUILDER_THEME_SCHEMES = [
   'starlight',
   'apex',
   'vault',
+  'clean-minimal',
 ] as const;
 
 export const STARTER_BUILDER_THEME_SCHEMES = ['blank'] as const;

package/src/validation.ts

@@ -1,4 +1,5 @@
 import type { BlockInstance, BuilderSettings } from './builder-settings.ts';
+import { mergeCustomPagesIntoManifest } from './custom-pages.ts';
 import { ThemeStyleSlotIdSchema } from './style-slots.ts';
 import type { ThemeManifest } from './theme-manifest.ts';
 
@@ -33,12 +34,13 @@ export function validateBuilderSettingsAgainstManifest(
   settings: BuilderSettings,
   manifest: ThemeManifest,
 ): BuilderManifestValidationIssue[] {
+  const effectiveManifest = mergeCustomPagesIntoManifest(manifest, settings);
   const issues: BuilderManifestValidationIssue[] = [];
 
-  validateGlobalStyleSlots(settings, manifest, issues);
+  validateGlobalStyleSlots(settings, effectiveManifest, issues);
 
   for (const [pageId, layout] of Object.entries(settings.theme.layout)) {
-    const page = manifest.pages[pageId];
+    const page = effectiveManifest.pages[pageId];
     if (!page) {
       issues.push({
         code: 'unknown_page',
@@ -63,7 +65,7 @@ export function validateBuilderSettingsAgainstManifest(
       }
       blockIds.add(block.id);
 
-      const blockDefinition = manifest.blocks[block.type];
+      const blockDefinition = effectiveManifest.blocks[block.type];
       if (!blockDefinition) {
         issues.push({
           code: 'unknown_block_type',
@@ -88,7 +90,7 @@ export function validateBuilderSettingsAgainstManifest(
     }
 
     for (const [blockType, count] of blockTypeCounts.entries()) {
-      const maxInstances = manifest.blocks[blockType]?.maxInstances;
+      const maxInstances = effectiveManifest.blocks[blockType]?.maxInstances;
       if (maxInstances !== undefined && count > maxInstances) {
         issues.push({
           code: 'too_many_block_instances',

package/dist/builder-contracts.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=builder-contracts.test.d.ts.map

package/dist/builder-contracts.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"builder-contracts.test.d.ts","sourceRoot":"","sources":["../src/builder-contracts.test.ts"],"names":[],"mappings":""}