@shoppexio/builder-contracts 0.1.0 → 0.1.2

package/src/legacy-manifest.ts

@@ -1,6 +1,8 @@
 import * as z from 'zod/v4';
+import { createDedicatedPageBlockType } from './dedicated-pages.ts';
 import { BuilderFieldSchema, type BuilderField } from './fields.ts';
 import { ThemeManifestSchema, type ThemeManifest } from './theme-manifest.ts';
+import { StyleSlotDefaultsSchema } from './style-slots.ts';
 
 const LegacyFieldOptionSchema = z
   .object({
@@ -83,6 +85,17 @@ export const LegacyThemeManifestSchema = z
     id: z.string().min(1),
     name: z.string().min(1),
     version: z.string().min(1),
+    author: z.string().min(1).optional(),
+    description: z.string().min(1).optional(),
+    preview: z.string().min(1).optional(),
+    features: z.array(z.string().min(1)).optional(),
+    techStack: z.array(z.string().min(1)).optional(),
+    templates: z.array(z.string().min(1)).optional(),
+    createdAt: z.string().min(1).optional(),
+    demoUrl: z.string().min(1).optional(),
+    audience: z.string().min(1).optional(),
+    tags: z.array(z.string().min(1)).optional(),
+    hotfixPaths: z.array(z.string().min(1)).optional(),
     presets: z.array(LegacyThemePresetSchema).optional(),
     builder: z
       .object({
@@ -96,6 +109,11 @@ export const LegacyThemeManifestSchema = z
 export type LegacyThemeManifest = z.infer<typeof LegacyThemeManifestSchema>;
 
 export function convertLegacyThemeManifest(input: unknown): ThemeManifest {
+  const canonical = ThemeManifestSchema.safeParse(input);
+  if (canonical.success) {
+    return canonical.data;
+  }
+
   const legacy = LegacyThemeManifestSchema.parse(input);
   const blocks = Object.fromEntries(
     Object.entries(legacy.builder.blocks).map(([blockType, block]) => [
@@ -112,7 +130,7 @@ export function convertLegacyThemeManifest(input: unknown): ThemeManifest {
   );
 
   for (const page of legacy.builder.pages) {
-    const syntheticBlockType = createSyntheticPageBlockType(page.id);
+    const syntheticBlockType = createDedicatedPageBlockType(page.id);
     if ((page.fields?.length ?? 0) === 0 && (page.lists?.length ?? 0) === 0) {
       continue;
     }
@@ -131,9 +149,20 @@ export function convertLegacyThemeManifest(input: unknown): ThemeManifest {
     id: normalizeLegacyThemeId(legacy.id),
     name: legacy.name,
     version: legacy.version,
+    author: legacy.author,
+    description: legacy.description,
+    preview: legacy.preview,
+    features: legacy.features,
+    techStack: legacy.techStack,
+    templates: legacy.templates,
+    createdAt: legacy.createdAt,
+    demoUrl: legacy.demoUrl,
+    audience: legacy.audience,
+    tags: legacy.tags,
+    hotfixPaths: legacy.hotfixPaths,
     pages: Object.fromEntries(
       legacy.builder.pages.map((page) => {
-        const syntheticBlockType = createSyntheticPageBlockType(page.id);
+        const syntheticBlockType = createDedicatedPageBlockType(page.id);
         const hasSyntheticBlock = blocks[syntheticBlockType] !== undefined;
         const allowedBlocks = page.blocks.length > 0
           ? page.blocks
@@ -158,6 +187,8 @@ export function convertLegacyThemeManifest(input: unknown): ThemeManifest {
     blocks,
     styleSlots: {},
     presets: convertLegacyThemePresets(legacy.presets ?? []),
+    linkGroups: Array.isArray(legacy.builder.linkGroups) ? legacy.builder.linkGroups : [],
+    defaultLinkItems: isPlainObject(legacy.builder.defaultLinkItems) ? legacy.builder.defaultLinkItems : {},
   };
 
   return ThemeManifestSchema.parse(converted);
@@ -171,23 +202,24 @@ function normalizeLegacyThemeId(rawId: string): string {
   return `legacy-${lowered || 'theme'}`;
 }
 
-function createSyntheticPageBlockType(pageId: string): string {
-  const normalizedPageId = pageId.toLowerCase().replace(/[^a-z0-9\-_.]+/g, '-').replace(/^[-_.]+/, '');
-  return `page-${normalizedPageId || 'custom'}`;
-}
-
 function convertLegacyThemePresets(presets: LegacyThemePreset[]): ThemeManifest['presets'] {
   return Object.fromEntries(
-    presets.map((preset) => [
-      preset.id,
-      {
-        label: preset.name ?? preset.label ?? preset.id,
-        description: preset.description,
-        content: flattenContentRecord(preset.overrides?.content ?? {}),
-        layout: preset.overrides?.layout ?? {},
-        style_slots: preset.overrides?.style_slots ?? preset.overrides?.styleSlots ?? {},
-      },
-    ]),
+    presets.map((preset) => {
+      const styleSlots = StyleSlotDefaultsSchema.parse(
+        preset.overrides?.style_slots ?? preset.overrides?.styleSlots ?? {},
+      );
+      return [
+        preset.id,
+        {
+          label: preset.name ?? preset.label ?? preset.id,
+          description: preset.description,
+          preview: typeof preset.preview === 'string' ? preset.preview : undefined,
+          content: flattenContentRecord(preset.overrides?.content ?? {}),
+          layout: preset.overrides?.layout ?? {},
+          style_slots: styleSlots,
+        },
+      ];
+    }),
   );
 }
 
@@ -211,20 +243,42 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
 }
 
 function convertLegacyFields(fields: LegacyBuilderField[], lists: LegacyBuilderList[]): Record<string, BuilderField> {
+  // Auto-promote inline `type: 'list'` fields to first-class list entries so
+  // the migrator can emit list-shaped data without separately maintaining a
+  // `lists: []` block-level entry. The promoted list inherits its kind from
+  // the field path (e.g. `header.left_links` → kind `navLinks`).
+  const inlineLists: LegacyBuilderList[] = [];
+  const remainingFields: LegacyBuilderField[] = [];
+  for (const field of fields) {
+    if (field.type === 'list') {
+      inlineLists.push({
+        path: field.path,
+        label: field.label,
+        kind: inferListKindFromPath(field.path),
+        description: field.description,
+      });
+    } else {
+      remainingFields.push(field);
+    }
+  }
+
   const convertedFields = Object.fromEntries(
-    fields.map((field) => [field.path, convertLegacyField(field)]),
+    remainingFields.map((field) => [field.path, convertLegacyField(field)]),
   );
 
+  const allLists = [...inlineLists, ...lists];
   const convertedLists = Object.fromEntries(
-    lists.map((list) => [
-      list.path,
-      {
+    allLists.map((list) => {
+      const inlineField = fields.find((f) => f.type === 'list' && f.path === list.path);
+      const candidate: BuilderField = {
         type: 'list',
         label: list.label,
         description: list.description,
         itemShape: createListItemShape(list.kind),
-      } satisfies BuilderField,
-    ]),
+        ...(inlineField?.defaultValue !== undefined ? { defaultValue: inlineField.defaultValue } : {}),
+      } as BuilderField;
+      return [list.path, candidate];
+    }),
   );
 
   return {
@@ -233,6 +287,17 @@ function convertLegacyFields(fields: LegacyBuilderField[], lists: LegacyBuilderL
   };
 }
 
+function inferListKindFromPath(path: string): string {
+  const suffix = path.split('.').at(-1) ?? '';
+  if (/items$/i.test(suffix)) return 'faqItems';
+  if (/links$/i.test(suffix)) return 'navLinks';
+  if (/images$/i.test(suffix) || /gallery$/i.test(suffix)) return 'galleryItems';
+  if (/features$/i.test(suffix)) return 'featureItems';
+  if (/reviews$/i.test(suffix) || /testimonials$/i.test(suffix)) return 'reviewItems';
+  if (/announcements$/i.test(suffix)) return 'announcementItems';
+  return 'genericItems';
+}
+
 function convertLegacyField(field: LegacyBuilderField): BuilderField {
   const type = normalizeLegacyFieldType(field.type);
   const base = {
@@ -314,8 +379,67 @@ function createListItemShape(kind: string): Extract<BuilderField, { type: 'list'
     };
   }
 
+  if (kind === 'navLinks') {
+    return {
+      text: { type: 'text', label: 'Text' },
+      link: { type: 'link', label: 'Link' },
+    };
+  }
+
+  if (kind === 'featureItems') {
+    return {
+      title: { type: 'text', label: 'Title' },
+      description: { type: 'richtext', label: 'Description' },
+      icon: { type: 'text', label: 'Icon' },
+    };
+  }
+
+  if (kind === 'announcementItems') {
+    return {
+      text: { type: 'text', label: 'Text' },
+      link: { type: 'link', label: 'Link' },
+    };
+  }
+
   return {
     title: { type: 'text', label: 'Title' },
     body: { type: 'richtext', label: 'Body' },
   };
 }
+
+export type ThemePageBlockOrderPage = {
+  allowedBlocks?: string[];
+  defaultBlocks?: Array<{ type?: string }>;
+};
+
+function resolveManifestPagesForBlockOrder(manifest: unknown): Record<string, ThemePageBlockOrderPage> {
+  const canonical = ThemeManifestSchema.safeParse(manifest);
+  if (canonical.success) {
+    return canonical.data.pages;
+  }
+
+  try {
+    return convertLegacyThemeManifest(manifest).pages;
+  } catch {
+    if (typeof manifest === 'object' && manifest !== null && 'pages' in manifest) {
+      const pages = (manifest as { pages?: unknown }).pages;
+      if (typeof pages === 'object' && pages !== null && !Array.isArray(pages)) {
+        return pages as Record<string, ThemePageBlockOrderPage>;
+      }
+    }
+    return {};
+  }
+}
+
+export function getThemePageBlockOrderFromManifest(manifest: unknown, pageId: string): string[] {
+  const page = resolveManifestPagesForBlockOrder(manifest)[pageId];
+  if (!page) {
+    return [];
+  }
+
+  const defaultBlockTypes = (Array.isArray(page.defaultBlocks) ? page.defaultBlocks : [])
+    .map((block) => (typeof block === 'object' && block !== null ? block.type : undefined))
+    .filter((blockType): blockType is string => typeof blockType === 'string' && blockType.length > 0);
+
+  return defaultBlockTypes.length > 0 ? defaultBlockTypes : page.allowedBlocks ?? [];
+}

package/src/migrations.ts

@@ -1,3 +1,4 @@
+import { migrateDedicatedPageContent, migrateDedicatedPageLayout } from './dedicated-pages.ts';
 import {
   BUILDER_SETTINGS_VERSION,
   type BlockInstance,
@@ -6,6 +7,7 @@ import {
   type PageLayout,
 } from './builder-settings.ts';
 import type { StyleSlots } from './style-slots.ts';
+import { sanitizeBuilderSettingsState } from './persistence.ts';
 import type { ThemeManifest } from './theme-manifest.ts';
 
 export type LegacyBuilderSettingsInput = {
@@ -66,18 +68,20 @@ export function migrateLegacyBuilderSettings(input: LegacyBuilderSettingsInput,
     ...mapLegacyTokenOverridesToStyleSlots(tokensOverride),
     ...(input.theme?.style_slots ?? {}),
   };
+  const rawContent = input.theme?.content ?? {};
+  const rawLayout = input.theme?.layout ?? {};
 
-  return BuilderSettingsSchema.parse({
+  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: {},
     },
-  });
+  }));
 }
 
 export function applyManifestDefaultLayout(settings: BuilderSettings, manifest: ThemeManifest): BuilderSettings {
@@ -110,13 +114,39 @@ export function mapLegacyTokenOverridesToStyleSlots(tokens: Record<string, unkno
   const slots: StyleSlots = {};
 
   assignResponsiveNumber(tokens, slots, 'buttons.borderRadius', 'button.radius');
+  assignColor(tokens, slots, 'buttons.background', 'button.background');
+  assignColor(tokens, slots, 'buttons.foreground', 'button.foreground');
+  assignColor(tokens, slots, 'buttons.border', 'button.border');
+  assignFontWeight(tokens, slots, 'buttons.fontWeight', 'button.font.weight');
+
   assignResponsiveNumber(tokens, slots, 'inputs.borderRadius', 'input.radius');
   assignResponsiveNumber(tokens, slots, 'inputs.height', 'input.height');
+  assignColor(tokens, slots, 'inputs.border', 'input.border');
+  assignColor(tokens, slots, 'inputs.background', 'input.background');
+  assignColor(tokens, slots, 'inputs.foreground', 'input.foreground');
+
+  assignResponsiveNumber(tokens, slots, 'cards.borderRadius', 'card.radius');
+  assignColor(tokens, slots, 'cards.background', 'card.background');
+  assignColor(tokens, slots, 'cards.border', 'card.border');
+
+  assignResponsiveNumber(tokens, slots, 'sections.paddingY', 'section.padding.y');
+  assignResponsiveNumber(tokens, slots, 'sections.paddingX', 'section.padding.x');
+  assignResponsiveNumber(tokens, slots, 'container.width', 'container.width');
+
   assignColor(tokens, slots, 'colors.primary', 'color.primary');
   assignColor(tokens, slots, 'colors.accent', 'color.accent');
   assignColor(tokens, slots, 'colors.background', 'color.background');
   assignColor(tokens, slots, 'colors.foreground', 'color.foreground');
   assignColor(tokens, slots, 'colors.muted', 'color.muted');
+  assignColor(tokens, slots, 'links.color', 'link.color');
+
+  assignFontWeight(tokens, slots, 'typography.headingWeight', 'typography.heading.weight');
+  assignResponsiveNumber(tokens, slots, 'typography.fontSize', 'typography.body.size');
+  assignResponsiveNumber(tokens, slots, 'typography.bodySize', 'typography.body.size');
+  assignString(tokens, slots, 'typography.fontFamily', 'theme.typography.font.family');
+  assignString(tokens, slots, 'typography.headingFont', 'theme.typography.heading.font');
+
+  assignResponsiveNumber(tokens, slots, 'header.height', 'theme.header.height');
 
   return slots;
 }
@@ -182,7 +212,7 @@ function assignResponsiveNumber(
   tokenPath: string,
   slotId: keyof StyleSlots,
 ): void {
-  const value = tokens[tokenPath];
+  const value = readLegacyTokenPath(tokens, tokenPath);
   if (typeof value === 'number' && Number.isFinite(value)) {
     slots[slotId] = { base: value } as never;
     return;
@@ -194,12 +224,46 @@ function assignResponsiveNumber(
 }
 
 function assignColor(tokens: Record<string, unknown>, slots: StyleSlots, tokenPath: string, slotId: keyof StyleSlots): void {
-  const value = tokens[tokenPath];
+  const value = readLegacyTokenPath(tokens, tokenPath);
   if (typeof value === 'string') {
     slots[slotId] = value as never;
   }
 }
 
+function assignString(tokens: Record<string, unknown>, slots: StyleSlots, tokenPath: string, slotId: keyof StyleSlots): void {
+  const value = readLegacyTokenPath(tokens, tokenPath);
+  if (typeof value === 'string' && value.trim().length > 0) {
+    slots[slotId] = value as never;
+  }
+}
+
+function assignFontWeight(
+  tokens: Record<string, unknown>,
+  slots: StyleSlots,
+  tokenPath: string,
+  slotId: keyof StyleSlots,
+): void {
+  const value = readLegacyTokenPath(tokens, tokenPath);
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    slots[slotId] = value as never;
+  }
+}
+
+function readLegacyTokenPath(tokens: Record<string, unknown>, tokenPath: string): unknown {
+  if (Object.prototype.hasOwnProperty.call(tokens, tokenPath)) {
+    return tokens[tokenPath];
+  }
+
+  let current: unknown = tokens;
+  for (const segment of tokenPath.split('.')) {
+    if (!isRecord(current)) {
+      return undefined;
+    }
+    current = current[segment];
+  }
+  return current;
+}
+
 function isResponsiveNumber(value: unknown): value is { base: number; sm?: number; md?: number; lg?: number; xl?: number } {
   if (!value || typeof value !== 'object') {
     return false;

package/src/persistence.ts

@@ -0,0 +1,77 @@
+import {
+  type BuilderSettings,
+  BuilderSettingsSchema,
+} from './builder-settings.ts';
+
+type JsonRecord = Record<string, unknown>;
+const RESERVED_THEME_CONTENT_KEYS = new Set(['layout']);
+
+function isRecord(value: unknown): value is JsonRecord {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function pickBuilderSettingsFields(value: unknown): unknown {
+  if (!isRecord(value)) {
+    return null;
+  }
+
+  return {
+    version: value.version,
+    revision: value.revision,
+    theme: value.theme,
+  };
+}
+
+export function extractPersistedBuilderSettings(input: unknown): BuilderSettings | null {
+  const parsedDirect = BuilderSettingsSchema.safeParse(pickBuilderSettingsFields(input));
+  if (parsedDirect.success) {
+    return sanitizeBuilderSettingsState(parsedDirect.data);
+  }
+
+  if (!isRecord(input)) {
+    return null;
+  }
+
+  const parsedNested = BuilderSettingsSchema.safeParse(pickBuilderSettingsFields(input.builder_settings));
+  return parsedNested.success ? sanitizeBuilderSettingsState(parsedNested.data) : null;
+}
+
+export function sanitizeBuilderSettingsState(settings: BuilderSettings): BuilderSettings {
+  const content = sanitizeThemeContent(settings.theme.content);
+  return BuilderSettingsSchema.parse({
+    ...settings,
+    theme: {
+      ...settings.theme,
+      content,
+    },
+  });
+}
+
+function sanitizeThemeContent(content: JsonRecord): JsonRecord {
+  const next: JsonRecord = {};
+  for (const [key, value] of Object.entries(content)) {
+    if (RESERVED_THEME_CONTENT_KEYS.has(key)) {
+      continue;
+    }
+    next[key] = value;
+  }
+  return next;
+}
+
+export function mergeBuilderSettingsIntoThemeSettings(
+  currentSettings: unknown,
+  builderSettings: BuilderSettings,
+): JsonRecord {
+  const root = isRecord(currentSettings) ? { ...currentSettings } : {};
+  const currentBuilderSettings = isRecord(root.builder_settings) ? root.builder_settings : {};
+  const sanitizedBuilderSettings = sanitizeBuilderSettingsState(builderSettings);
+
+  root.builder_settings = {
+    ...currentBuilderSettings,
+    version: sanitizedBuilderSettings.version,
+    revision: sanitizedBuilderSettings.revision,
+    theme: sanitizedBuilderSettings.theme,
+  };
+
+  return root;
+}

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

@@ -0,0 +1,49 @@
+import * as z from 'zod/v4';
+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()),
+    products: z.array(z.unknown()).optional(),
+    groups: z.array(z.unknown()).optional(),
+    pages: z.array(z.unknown()).optional(),
+  })
+  .passthrough();
+
+export type StorefrontSeed = z.infer<typeof StorefrontSeedSchema>;
+
+export const PreviewBootPayloadSchema = z
+  .object({
+    shopId: z.string().min(1),
+    shopSlug: z.string().min(1),
+    builderSettings: BuilderSettingsSchema,
+    storefrontSeed: StorefrontSeedSchema,
+    artifactRevision: z.string().optional(),
+    artifactStale: z.boolean().optional(),
+  })
+  .strict();
+
+export type PreviewBootPayload = z.infer<typeof PreviewBootPayloadSchema>;
+
+export function mergePreviewBootIntoInitialData(
+  payload: PreviewBootPayload,
+): Record<string, unknown> {
+  const existingStore = isRecord(payload.storefrontSeed.store) ? payload.storefrontSeed.store : {};
+  return {
+    ...payload.storefrontSeed,
+    store: {
+      ...existingStore,
+      id: payload.shopId,
+      slug: payload.shopSlug,
+      builder_settings: payload.builderSettings,
+    },
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}