@shoppexio/builder-contracts 0.1.0 → 0.1.2

package/src/builder-contracts.test.ts

@@ -1,7 +1,10 @@
 import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import {
   BuilderEventSchema,
   BuilderSettingsSchema,
+  PreviewResponseSchema,
   PreviewMessageSchema,
   StyleSlotsSchema,
   ThemeManifestSchema,
@@ -10,8 +13,13 @@ import {
   createBlockInstance,
   createEmptyBuilderSettings,
   convertLegacyThemeManifest,
+  extractPersistedBuilderSettings,
+  canonicalizeBuilderSettingsForManifestWithReport,
+  mergeBuilderSettingsIntoThemeSettings,
   migrateLegacyBuilderSettings,
+  listThemeManifestPresets,
 } from './index.ts';
+import { ColorSchema } from './style-slots.ts';
 
 describe('@shoppex/builder-contracts', () => {
   test('accepts an empty builder settings document', () => {
@@ -39,6 +47,16 @@ describe('@shoppex/builder-contracts', () => {
     expect(result.success).toBe(false);
   });
 
+  test('accepts theme-scoped style slots', () => {
+    const result = StyleSlotsSchema.safeParse({
+      'button.radius': { base: 10 },
+      'theme.hero.overlay.opacity': 0.72,
+      'theme.product.badge.background': '#111827',
+    });
+
+    expect(result.success).toBe(true);
+  });
+
   test('rejects invalid colors', () => {
     const result = StyleSlotsSchema.safeParse({
       'color.primary': 'tomato',
@@ -93,6 +111,32 @@ describe('@shoppex/builder-contracts', () => {
     expect(result.success).toBe(true);
   });
 
+  test('accepts preview READY health and runtime error responses', () => {
+    expect(PreviewResponseSchema.safeParse({
+      type: 'READY',
+      revision: 3,
+      health: {
+        reactMounted: true,
+        builderRuntimeProvider: true,
+        protocolVersion: 2,
+      },
+    }).success).toBe(true);
+
+    expect(PreviewResponseSchema.safeParse({
+      type: 'PREVIEW_ERROR',
+      revision: 3,
+      message: 'useBuilderRuntime must be used inside BuilderRuntimeProvider',
+      stack: 'Error: useBuilderRuntime must be used inside BuilderRuntimeProvider',
+      source: 'error',
+    }).success).toBe(true);
+
+    expect(PreviewResponseSchema.safeParse({
+      type: 'PREVIEW_ERROR',
+      message: 'Theme bootstrap failed before React mounted',
+      source: 'bootstrap',
+    }).success).toBe(true);
+  });
+
   test('accepts block add events', () => {
     const result = BuilderEventSchema.safeParse({
       id: 'evt_1',
@@ -112,6 +156,20 @@ describe('@shoppex/builder-contracts', () => {
     expect(result.success).toBe(true);
   });
 
+  test('accepts preset apply events', () => {
+    const result = BuilderEventSchema.safeParse({
+      id: 'evt_preset',
+      type: 'preset.apply',
+      revision: 7,
+      createdAt: '2026-05-16T12:00:00.000Z',
+      source: 'dashboard',
+      pageId: 'home',
+      presetId: 'launch',
+    });
+
+    expect(result.success).toBe(true);
+  });
+
   test('migrates legacy content and token overrides', () => {
     const migrated = migrateLegacyBuilderSettings(
       {
@@ -122,6 +180,14 @@ describe('@shoppex/builder-contracts', () => {
           tokens_override: {
             'buttons.borderRadius': 12,
             'colors.primary': '#ff5500',
+            typography: {
+              fontSize: 18,
+              fontFamily: 'Manrope, sans-serif',
+              headingFont: 'Georgia, serif',
+            },
+            header: {
+              height: 64,
+            },
           },
         },
       },
@@ -132,6 +198,68 @@ describe('@shoppex/builder-contracts', () => {
     expect(migrated.theme.content['hero.title']).toBe('Summer sale');
     expect(migrated.theme.style_slots['button.radius']).toEqual({ base: 12 });
     expect(migrated.theme.style_slots['color.primary']).toBe('#ff5500');
+    expect(migrated.theme.style_slots['typography.body.size']).toEqual({ base: 18 });
+    expect(migrated.theme.style_slots['theme.typography.font.family']).toBe('Manrope, sans-serif');
+    expect(migrated.theme.style_slots['theme.typography.heading.font']).toBe('Georgia, serif');
+    expect(migrated.theme.style_slots['theme.header.height']).toEqual({ base: 64 });
+  });
+
+  test('persists builder v2 state inside theme settings without losing non-builder siblings', () => {
+    const settings = createEmptyBuilderSettings(4);
+    const persisted = mergeBuilderSettingsIntoThemeSettings({
+      builder_settings: {
+        seo: {
+          default_title: 'Keep this title',
+        },
+      },
+    }, settings);
+
+    expect((persisted.builder_settings as Record<string, unknown>).seo).toEqual({
+      default_title: 'Keep this title',
+    });
+    expect(extractPersistedBuilderSettings(persisted)).toEqual(settings);
+  });
+
+  test('removes reserved content keys from persisted builder v2 state', () => {
+    const settings = BuilderSettingsSchema.parse({
+      ...createEmptyBuilderSettings(5),
+      theme: {
+        ...createEmptyBuilderSettings(5).theme,
+        content: {
+          layout: {
+            home: {
+              blocks: [
+                {
+                  id: 'old-hero',
+                  type: 'hero',
+                  visible: true,
+                  settings: { title: 'Old title' },
+                },
+              ],
+            },
+          },
+          'hero.eyebrow': 'Fresh content',
+        },
+        layout: {
+          home: {
+            blocks: [
+              {
+                id: 'new-hero',
+                type: 'hero',
+                visible: true,
+                settings: { title: 'New title' },
+              },
+            ],
+          },
+        },
+      },
+    });
+
+    const persisted = mergeBuilderSettingsIntoThemeSettings({}, settings);
+    const extracted = extractPersistedBuilderSettings(persisted);
+
+    expect(extracted?.theme.content).toEqual({ 'hero.eyebrow': 'Fresh content' });
+    expect(extracted?.theme.layout.home?.blocks[0]?.settings).toEqual({ title: 'New title' });
   });
 
   test('converts legacy theme manifests into the v2 manifest contract', () => {
@@ -139,6 +267,17 @@ describe('@shoppex/builder-contracts', () => {
       id: 'default',
       name: 'Default Theme',
       version: '1.0.0',
+      author: 'Shoppex',
+      description: 'Legacy theme metadata',
+      preview: 'preview.png',
+      features: ['Builder-ready'],
+      techStack: ['Vite', 'React'],
+      templates: ['Home'],
+      createdAt: '2026-05-16',
+      demoUrl: 'https://demo.example',
+      audience: 'Digital sellers',
+      tags: ['minimal'],
+      hotfixPaths: ['src/hooks/**'],
       presets: [
         {
           id: 'gaming',
@@ -192,16 +331,53 @@ describe('@shoppex/builder-contracts', () => {
             ],
           },
         },
+        linkGroups: [
+          {
+            path: 'navigation.header.links',
+            label: 'Header links',
+            pageIds: ['navigation'],
+          },
+        ],
+        defaultLinkItems: {
+          'navigation.header.links': [
+            { label: 'FAQ', href: '/faq' },
+          ],
+        },
       },
     });
 
     expect(manifest.pages.home.allowedBlocks).toEqual(['hero', 'faq']);
+    expect(manifest).toMatchObject({
+      author: 'Shoppex',
+      description: 'Legacy theme metadata',
+      preview: 'preview.png',
+      features: ['Builder-ready'],
+      techStack: ['Vite', 'React'],
+      templates: ['Home'],
+      createdAt: '2026-05-16',
+      demoUrl: 'https://demo.example',
+      audience: 'Digital sellers',
+      tags: ['minimal'],
+      hotfixPaths: ['src/hooks/**'],
+    });
     expect(manifest.pages.home.defaultBlocks).toEqual([{ type: 'hero' }, { type: 'faq' }]);
     expect(manifest.blocks.hero.settings['hero.title']).toMatchObject({ type: 'text', label: 'Title' });
     expect(manifest.blocks.hero.settings['hero.style']).toMatchObject({ type: 'select' });
     expect(manifest.blocks.faq.settings['faq.items']).toMatchObject({ type: 'list' });
     expect(manifest.blocks['page-contact-page'].settings['pages.contact.title']).toMatchObject({ type: 'text' });
     expect(manifest.pages['contact-page'].allowedBlocks).toEqual(['page-contact-page']);
+    expect(manifest.linkGroups).toEqual([
+      {
+        path: 'navigation.header.links',
+        label: 'Header links',
+        pageIds: ['navigation'],
+      },
+    ]);
+    expect(manifest.defaultLinkItems).toEqual({
+      'navigation.header.links': [
+        { label: 'FAQ', href: '/faq' },
+      ],
+    });
     expect(manifest.presets.gaming).toMatchObject({
       label: 'Gaming Store',
       description: 'Gaming copy preset',
@@ -211,6 +387,117 @@ describe('@shoppex/builder-contracts', () => {
     });
   });
 
+  test('accepts canonical theme manifests without legacy conversion', () => {
+    const manifest = convertLegacyThemeManifest({
+      id: 'default',
+      name: 'Default Theme',
+      version: '2.0.0',
+      author: 'Shoppex',
+      description: 'Canonical theme metadata',
+      preview: 'preview.png',
+      pages: {
+        home: {
+          label: 'Home',
+          previewPath: '/',
+          allowedBlocks: ['hero'],
+          defaultBlocks: [{ type: 'hero' }],
+        },
+      },
+      blocks: {
+        hero: {
+          label: 'Hero',
+          settings: {
+            title: { type: 'text', label: 'Title' },
+          },
+          variants: [],
+          exposedStyleSlots: [],
+          presets: [],
+        },
+      },
+      styleSlots: {},
+      presets: {},
+    });
+
+    expect(manifest.pages.home.allowedBlocks).toEqual(['hero']);
+    expect(manifest.author).toBe('Shoppex');
+    expect(manifest.description).toBe('Canonical theme metadata');
+    expect(manifest.preview).toBe('preview.png');
+    expect(manifest.blocks.hero.settings.title).toMatchObject({
+      type: 'text',
+      label: 'Title',
+    });
+  });
+
+  test('normalizes canonical and legacy theme presets for theme library readers', () => {
+    expect(listThemeManifestPresets({
+      id: 'default',
+      name: 'Default Theme',
+      version: '2.0.0',
+      pages: {
+        home: {
+          label: 'Home',
+          previewPath: '/',
+          allowedBlocks: ['hero'],
+          defaultBlocks: [{ type: 'hero' }],
+        },
+      },
+      blocks: {
+        hero: {
+          label: 'Hero',
+          settings: {},
+          variants: [],
+          exposedStyleSlots: [],
+          presets: [],
+        },
+      },
+      styleSlots: {},
+      presets: {
+        launch: {
+          label: 'Launch Store',
+          description: 'Launch copy',
+          preview: 'presets/launch.png',
+          content: { 'hero.title': 'Instant access' },
+          layout: {},
+          style_slots: { 'button.radius': { base: 12 } },
+        },
+      },
+    })).toEqual([
+      {
+        id: 'launch',
+        name: 'Launch Store',
+        description: 'Launch copy',
+        preview: 'presets/launch.png',
+        overrides: {
+          content: { 'hero.title': 'Instant access' },
+          style_slots: { 'button.radius': { base: 12 } },
+        },
+      },
+    ]);
+
+    expect(listThemeManifestPresets({
+      id: 'legacy',
+      name: 'Legacy Theme',
+      version: '1.0.0',
+      presets: [
+        {
+          id: 'tokens',
+          name: 'Tokens',
+          overrides: {
+            tokens: { buttons: { borderRadius: 18 } },
+          },
+        },
+      ],
+    })).toEqual([
+      {
+        id: 'tokens',
+        name: 'Tokens',
+        overrides: {
+          tokens: { buttons: { borderRadius: 18 } },
+        },
+      },
+    ]);
+  });
+
   test('applies manifest default blocks to empty builder settings', () => {
     const settings = applyManifestDefaultLayout(createEmptyBuilderSettings(2), {
       id: 'default',
@@ -347,7 +634,48 @@ describe('@shoppex/builder-contracts', () => {
     expect(issues.map((issue) => issue.code)).toContain('unexposed_style_slot');
   });
 
-  test('accepts full and short block setting keys declared by the manifest', () => {
+  test('requires theme-scoped global style slots to be declared by the manifest', () => {
+    const settings = BuilderSettingsSchema.parse({
+      version: 2,
+      revision: 1,
+      theme: {
+        content: {},
+        layout: {},
+        style_slots: {
+          'color.primary': '#ff5500',
+          'theme.hero.overlay.opacity': 0.72,
+        },
+        pages: [],
+        terms: {},
+      },
+    });
+    const manifest = {
+      id: 'default',
+      name: 'Default',
+      version: '2.0.0',
+      pages: {},
+      blocks: {},
+      styleSlots: {},
+      presets: {},
+    };
+
+    expect(validateBuilderSettingsAgainstManifest(settings, manifest)).toEqual([
+      {
+        code: 'unknown_style_slot',
+        path: 'theme.style_slots.theme.hero.overlay.opacity',
+        message: 'Theme style slot "theme.hero.overlay.opacity" is not declared by the manifest',
+      },
+    ]);
+
+    expect(validateBuilderSettingsAgainstManifest(settings, {
+      ...manifest,
+      styleSlots: {
+        'theme.hero.overlay.opacity': 0.5,
+      },
+    })).toEqual([]);
+  });
+
+  test('canonicalizes unique short block setting aliases before strict validation', () => {
     const settings = BuilderSettingsSchema.parse({
       version: 2,
       revision: 1,
@@ -374,7 +702,7 @@ describe('@shoppex/builder-contracts', () => {
       },
     });
 
-    const issues = validateBuilderSettingsAgainstManifest(settings, {
+    const manifest = {
       id: 'default',
       name: 'Default',
       version: '2.0.0',
@@ -398,8 +726,93 @@ describe('@shoppex/builder-contracts', () => {
       },
       styleSlots: {},
       presets: {},
+    };
+
+    const result = canonicalizeBuilderSettingsForManifestWithReport(settings, manifest);
+
+    expect(result.migratedAliases).toBe(0);
+    expect(result.removedAliases).toBe(1);
+    expect(result.conflicts).toEqual([]);
+    expect(result.settings.theme.layout.home.blocks[0].settings).toEqual({
+      'hero.title': 'Launch sale',
     });
+    expect(validateBuilderSettingsAgainstManifest(result.settings, manifest)).toEqual([]);
+  });
+
+  test('canonicalizes block-prefixed aliases when the manifest declares short block fields', () => {
+    const settings = BuilderSettingsSchema.parse({
+      version: 2,
+      revision: 1,
+      theme: {
+        content: {},
+        layout: {
+          home: {
+            blocks: [
+              {
+                id: 'home-hero-1',
+                type: 'hero',
+                visible: true,
+                settings: {
+                  'hero.title': 'Launch sale',
+                },
+              },
+            ],
+          },
+        },
+        style_slots: {},
+        pages: [],
+        terms: {},
+      },
+    });
+
+    const manifest = {
+      id: 'starlight',
+      name: 'Starlight',
+      version: '1.0.0',
+      pages: {
+        home: {
+          label: 'Home',
+          allowedBlocks: ['hero'],
+          defaultBlocks: [{ type: 'hero' }],
+        },
+      },
+      blocks: {
+        hero: {
+          label: 'Hero',
+          settings: {
+            title: { type: 'text', label: 'Title' },
+          },
+          variants: [],
+          exposedStyleSlots: [],
+          presets: [],
+        },
+      },
+      styleSlots: {},
+      presets: {},
+    };
+
+    const result = canonicalizeBuilderSettingsForManifestWithReport(settings, manifest);
+
+    expect(result.migratedAliases).toBe(1);
+    expect(result.removedAliases).toBe(1);
+    expect(result.settings.theme.layout.home.blocks[0].settings).toEqual({
+      title: 'Launch sale',
+    });
+    expect(validateBuilderSettingsAgainstManifest(result.settings, manifest)).toEqual([]);
+  });
+
+  test('accepts transparent color literals used by theme manifests', () => {
+    expect(ColorSchema.parse('transparent')).toBe('transparent');
+    expect(ColorSchema.parse('#ffffff')).toBe('#ffffff');
+    expect(ColorSchema.parse('#00000080')).toBe('#00000080');
+  });
 
-    expect(issues).toEqual([]);
+  test('parses official theme manifests with transparent contact-form backgrounds', () => {
+    const repoRoot = join(import.meta.dir, '../../..');
+    for (const theme of ['default', 'nebula', 'classic', 'pulse', 'starlight', 'vault', 'phantom', 'apex']) {
+      const manifestPath = join(repoRoot, 'themes', theme, 'theme.manifest.json');
+      const raw = JSON.parse(readFileSync(manifestPath, 'utf8'));
+      expect(ThemeManifestSchema.safeParse(raw).success, `${theme} manifest should validate`).toBe(true);
+    }
   });
 });

package/src/builder-settings.ts

@@ -31,11 +31,14 @@ export const PageLayoutSchema = z
   .strict();
 export type PageLayout = z.infer<typeof PageLayoutSchema>;
 
+export const CustomPageSlugSchema = z.string().min(1).regex(/^[a-z0-9][a-z0-9-_]*$/);
+export type CustomPageSlug = z.infer<typeof CustomPageSlugSchema>;
+
 export const CustomPageSchema = z
   .object({
     id: PageIdSchema,
     title: z.string().min(1),
-    slug: z.string().min(1).regex(/^[a-z0-9][a-z0-9-_/]*$/),
+    slug: CustomPageSlugSchema,
     visible: z.boolean().default(true),
     layout: PageLayoutSchema.default({ blocks: [] }),
     seo: z

package/src/canonical-settings.ts

@@ -0,0 +1,156 @@
+import type { BlockInstance, BuilderSettings } from './builder-settings.ts';
+import { sanitizeBuilderSettingsState } from './persistence.ts';
+import type { ThemeManifest } from './theme-manifest.ts';
+
+export type BuilderSettingsCanonicalizationConflict = {
+  pageId: string;
+  blockId: string;
+  blockType: string;
+  alias: string;
+  canonicalPath: string;
+};
+
+export type BuilderSettingsCanonicalizationResult = {
+  settings: BuilderSettings;
+  migratedAliases: number;
+  removedAliases: number;
+  conflicts: BuilderSettingsCanonicalizationConflict[];
+};
+
+export function canonicalizeBuilderSettingsForManifest(
+  settings: BuilderSettings,
+  manifest: ThemeManifest,
+): BuilderSettings {
+  return canonicalizeBuilderSettingsForManifestWithReport(settings, manifest).settings;
+}
+
+export function canonicalizeBuilderSettingsForManifestWithReport(
+  settings: BuilderSettings,
+  manifest: ThemeManifest,
+): BuilderSettingsCanonicalizationResult {
+  const next = sanitizeBuilderSettingsState(cloneBuilderSettings(settings));
+  const conflicts: BuilderSettingsCanonicalizationConflict[] = [];
+  let migratedAliases = 0;
+  let removedAliases = 0;
+
+  for (const [pageId, layout] of Object.entries(next.theme.layout)) {
+    for (const block of layout.blocks) {
+      const blockDefinition = manifest.blocks[block.type];
+      if (!blockDefinition) continue;
+
+      const result = canonicalizeBlockSettings(pageId, block, Object.keys(blockDefinition.settings));
+      migratedAliases += result.migratedAliases;
+      removedAliases += result.removedAliases;
+      conflicts.push(...result.conflicts);
+    }
+  }
+
+  return {
+    settings: next,
+    migratedAliases,
+    removedAliases,
+    conflicts,
+  };
+}
+
+function canonicalizeBlockSettings(
+  pageId: string,
+  block: BlockInstance,
+  settingPaths: string[],
+): Omit<BuilderSettingsCanonicalizationResult, 'settings'> {
+  const aliases = buildAliasMap(block.type, settingPaths);
+  const conflicts: BuilderSettingsCanonicalizationConflict[] = [];
+  let migratedAliases = 0;
+  let removedAliases = 0;
+
+  for (const [alias, canonicalPaths] of aliases.entries()) {
+    if (!Object.prototype.hasOwnProperty.call(block.settings, alias)) {
+      continue;
+    }
+
+    const aliasValue = block.settings[alias];
+    if (canonicalPaths.length === 1) {
+      const canonicalPath = canonicalPaths[0];
+      if (!Object.prototype.hasOwnProperty.call(block.settings, canonicalPath)) {
+        block.settings[canonicalPath] = aliasValue;
+        migratedAliases += 1;
+      } else if (!isJsonEqual(block.settings[canonicalPath], aliasValue)) {
+        conflicts.push({
+          pageId,
+          blockId: block.id,
+          blockType: block.type,
+          alias,
+          canonicalPath,
+        });
+      }
+
+      delete block.settings[alias];
+      removedAliases += 1;
+      continue;
+    }
+
+    const everyCanonicalExists = canonicalPaths.every((canonicalPath) =>
+      Object.prototype.hasOwnProperty.call(block.settings, canonicalPath),
+    );
+    if (everyCanonicalExists) {
+      delete block.settings[alias];
+      removedAliases += 1;
+    }
+  }
+
+  return {
+    migratedAliases,
+    removedAliases,
+    conflicts,
+  };
+}
+
+function buildAliasMap(blockType: string, settingPaths: string[]): Map<string, string[]> {
+  const aliases = new Map<string, Set<string>>();
+  const canonicalPaths = new Set(settingPaths);
+
+  for (const canonicalPath of settingPaths) {
+    for (const alias of getLegacyAliases(blockType, canonicalPath)) {
+      if (alias === canonicalPath || canonicalPaths.has(alias)) continue;
+      const canonicalAliases = aliases.get(alias) ?? new Set<string>();
+      canonicalAliases.add(canonicalPath);
+      aliases.set(alias, canonicalAliases);
+    }
+  }
+
+  return new Map(
+    Array.from(aliases.entries()).map(([alias, paths]) => [alias, Array.from(paths).sort()]),
+  );
+}
+
+function getLegacyAliases(blockType: string, canonicalPath: string): string[] {
+  const aliases = new Set<string>();
+  const shortKey = getShortSettingKey(canonicalPath);
+
+  if (shortKey && shortKey !== canonicalPath) {
+    aliases.add(shortKey);
+  }
+
+  if (!canonicalPath.includes('.')) {
+    aliases.add(`${blockType}.${canonicalPath}`);
+  }
+
+  return Array.from(aliases);
+}
+
+function getShortSettingKey(path: string): string {
+  const parts = path.split('.').filter(Boolean);
+  return parts.at(-1) ?? path;
+}
+
+function cloneBuilderSettings(settings: BuilderSettings): BuilderSettings {
+  if (typeof structuredClone === 'function') {
+    return structuredClone(settings);
+  }
+
+  return JSON.parse(JSON.stringify(settings)) as BuilderSettings;
+}
+
+function isJsonEqual(left: unknown, right: unknown): boolean {
+  return JSON.stringify(left) === JSON.stringify(right);
+}