@shoppexio/builder-contracts 0.1.0

package/src/preview-protocol.ts

@@ -0,0 +1,93 @@
+import * as z from 'zod/v4';
+import { BuilderSettingsSchema } from './builder-settings.ts';
+
+export const BuilderSelectionSchema = z
+  .object({
+    pageId: z.string().min(1).optional(),
+    blockId: z.string().min(1).optional(),
+    blockType: z.string().min(1).optional(),
+    contentPath: z.string().min(1).optional(),
+    slotId: z.string().min(1).optional(),
+    elementType: z.enum(['block', 'text', 'image', 'link', 'button', 'style']).optional(),
+    href: z.string().optional(),
+    target: z.string().optional(),
+    rel: z.string().optional(),
+  })
+  .strict();
+export type BuilderSelection = z.infer<typeof BuilderSelectionSchema>;
+
+export const PreviewApplyStateMessageSchema = z
+  .object({
+    type: z.literal('APPLY_STATE'),
+    revision: z.number().int().nonnegative(),
+    state: BuilderSettingsSchema,
+  })
+  .strict();
+
+export const PreviewReloadMessageSchema = z
+  .object({
+    type: z.literal('RELOAD'),
+    revision: z.number().int().nonnegative(),
+    reason: z.enum(['manifest-change', 'source-change']),
+  })
+  .strict();
+
+export const PreviewSelectElementMessageSchema = z
+  .object({
+    type: z.literal('SELECT_ELEMENT'),
+    revision: z.number().int().nonnegative().optional(),
+    selection: BuilderSelectionSchema,
+  })
+  .strict();
+
+export const PreviewRequestReadyMessageSchema = z
+  .object({
+    type: z.literal('REQUEST_READY'),
+  })
+  .strict();
+
+export const PreviewMessageSchema = z.discriminatedUnion('type', [
+  PreviewApplyStateMessageSchema,
+  PreviewReloadMessageSchema,
+  PreviewSelectElementMessageSchema,
+  PreviewRequestReadyMessageSchema,
+]);
+export type PreviewMessage = z.infer<typeof PreviewMessageSchema>;
+
+export const PreviewReadyResponseSchema = z
+  .object({
+    type: z.literal('READY'),
+    revision: z.number().int().nonnegative(),
+  })
+  .strict();
+
+export const PreviewAppliedResponseSchema = z
+  .object({
+    type: z.literal('APPLIED'),
+    revision: z.number().int().nonnegative(),
+  })
+  .strict();
+
+export const PreviewApplyFailedResponseSchema = z
+  .object({
+    type: z.literal('APPLY_FAILED'),
+    revision: z.number().int().nonnegative(),
+    error: z.string().min(1),
+  })
+  .strict();
+
+export const PreviewElementClickedResponseSchema = z
+  .object({
+    type: z.literal('ELEMENT_CLICKED'),
+    revision: z.number().int().nonnegative().optional(),
+    selection: BuilderSelectionSchema,
+  })
+  .strict();
+
+export const PreviewResponseSchema = z.discriminatedUnion('type', [
+  PreviewReadyResponseSchema,
+  PreviewAppliedResponseSchema,
+  PreviewApplyFailedResponseSchema,
+  PreviewElementClickedResponseSchema,
+]);
+export type PreviewResponse = z.infer<typeof PreviewResponseSchema>;

package/src/style-slots.ts

@@ -0,0 +1,111 @@
+import * as z from 'zod/v4';
+
+export const BreakpointSchema = z.enum(['base', 'sm', 'md', 'lg', 'xl']);
+export type Breakpoint = z.infer<typeof BreakpointSchema>;
+
+export const ResponsiveNumberSchema = z
+  .object({
+    base: z.number().finite(),
+    sm: z.number().finite().optional(),
+    md: z.number().finite().optional(),
+    lg: z.number().finite().optional(),
+    xl: z.number().finite().optional(),
+  })
+  .strict();
+export type ResponsiveNumber = z.infer<typeof ResponsiveNumberSchema>;
+
+export const ResponsiveStringSchema = z
+  .object({
+    base: z.string().min(1),
+    sm: z.string().min(1).optional(),
+    md: z.string().min(1).optional(),
+    lg: z.string().min(1).optional(),
+    xl: z.string().min(1).optional(),
+  })
+  .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');
+export type Color = z.infer<typeof ColorSchema>;
+
+export const FontWeightSchema = z.union([
+  z.literal(100),
+  z.literal(200),
+  z.literal(300),
+  z.literal(400),
+  z.literal(500),
+  z.literal(600),
+  z.literal(700),
+  z.literal(800),
+  z.literal(900),
+]);
+export type FontWeight = z.infer<typeof FontWeightSchema>;
+
+export const StyleSlotIdSchema = z.enum([
+  'button.radius',
+  'button.background',
+  'button.foreground',
+  'button.border',
+  'button.font.weight',
+  'input.radius',
+  'input.height',
+  'input.border',
+  'input.background',
+  'input.foreground',
+  'card.radius',
+  'card.background',
+  'card.border',
+  'section.padding.y',
+  'section.padding.x',
+  'container.width',
+  'color.primary',
+  'color.accent',
+  'color.background',
+  'color.foreground',
+  'color.muted',
+  'link.color',
+  'typography.heading.weight',
+  'typography.body.size',
+]);
+export type StyleSlotId = z.infer<typeof StyleSlotIdSchema>;
+
+export const CORE_STYLE_SLOT_IDS = StyleSlotIdSchema.options;
+
+export const StyleSlotsSchema = z
+  .object({
+    'button.radius': ResponsiveNumberSchema.optional(),
+    'button.background': ColorSchema.optional(),
+    'button.foreground': ColorSchema.optional(),
+    'button.border': ColorSchema.optional(),
+    'button.font.weight': FontWeightSchema.optional(),
+    'input.radius': ResponsiveNumberSchema.optional(),
+    'input.height': ResponsiveNumberSchema.optional(),
+    'input.border': ColorSchema.optional(),
+    'input.background': ColorSchema.optional(),
+    'input.foreground': ColorSchema.optional(),
+    'card.radius': ResponsiveNumberSchema.optional(),
+    'card.background': ColorSchema.optional(),
+    'card.border': ColorSchema.optional(),
+    'section.padding.y': ResponsiveNumberSchema.optional(),
+    'section.padding.x': ResponsiveNumberSchema.optional(),
+    'container.width': ResponsiveNumberSchema.optional(),
+    'color.primary': ColorSchema.optional(),
+    'color.accent': ColorSchema.optional(),
+    'color.background': ColorSchema.optional(),
+    'color.foreground': ColorSchema.optional(),
+    'color.muted': ColorSchema.optional(),
+    'link.color': ColorSchema.optional(),
+    'typography.heading.weight': FontWeightSchema.optional(),
+    'typography.body.size': ResponsiveNumberSchema.optional(),
+  })
+  .strict();
+export type StyleSlots = z.infer<typeof StyleSlotsSchema>;
+
+export const StyleSlotDefaultsSchema = StyleSlotsSchema;
+export type StyleSlotDefaults = StyleSlots;
+
+export function parseStyleSlots(input: unknown): StyleSlots {
+  return StyleSlotsSchema.parse(input);
+}

package/src/theme-manifest.ts

@@ -0,0 +1,140 @@
+import * as z from 'zod/v4';
+import { BlockSettingsSchema } from './fields.ts';
+import { StyleSlotDefaultsSchema, StyleSlotIdSchema } from './style-slots.ts';
+
+export const ThemeIdSchema = z.string().min(1).regex(/^[a-z0-9][a-z0-9-_.]*$/);
+export type ThemeId = z.infer<typeof ThemeIdSchema>;
+
+export const BlockVariantSchema = z
+  .object({
+    id: z.string().min(1),
+    label: z.string().min(1),
+    previewImage: z.string().url().optional(),
+  })
+  .strict();
+export type BlockVariant = z.infer<typeof BlockVariantSchema>;
+
+export const DefaultBlockSchema = z
+  .object({
+    type: z.string().min(1),
+    variant: z.string().min(1).optional(),
+    settings: z.record(z.string().min(1), z.unknown()).optional(),
+  })
+  .strict();
+export type DefaultBlock = z.infer<typeof DefaultBlockSchema>;
+
+export const ManifestPageSchema = z
+  .object({
+    label: z.string().min(1),
+    previewPath: z.string().min(1).optional(),
+    allowedBlocks: z.array(z.string().min(1)).default([]),
+    defaultBlocks: z.array(DefaultBlockSchema).default([]),
+  })
+  .strict();
+export type ManifestPage = z.infer<typeof ManifestPageSchema>;
+
+export const BlockPresetSchema = z
+  .object({
+    id: z.string().min(1),
+    label: z.string().min(1),
+    variant: z.string().min(1).optional(),
+    settings: z.record(z.string().min(1), z.unknown()).default({}),
+    style_overrides: StyleSlotDefaultsSchema.optional(),
+  })
+  .strict();
+export type BlockPreset = z.infer<typeof BlockPresetSchema>;
+
+export const ManifestBlockSchema = z
+  .object({
+    label: z.string().min(1),
+    description: z.string().min(1).optional(),
+    category: z.string().min(1).optional(),
+    maxInstances: z.number().int().positive().optional(),
+    variants: z.array(BlockVariantSchema).default([]),
+    settings: BlockSettingsSchema.default({}),
+    exposedStyleSlots: z.array(StyleSlotIdSchema).default([]),
+    presets: z.array(BlockPresetSchema).default([]),
+  })
+  .strict();
+export type ManifestBlock = z.infer<typeof ManifestBlockSchema>;
+
+export const ThemePresetSchema = z
+  .object({
+    label: z.string().min(1),
+    description: z.string().min(1).optional(),
+    content: z.record(z.string().min(1), z.unknown()).default({}),
+    layout: z.record(z.string().min(1), z.unknown()).default({}),
+    style_slots: StyleSlotDefaultsSchema.default({}),
+  })
+  .strict();
+export type ThemePreset = z.infer<typeof ThemePresetSchema>;
+
+export const ThemeManifestSchema = z
+  .object({
+    id: ThemeIdSchema,
+    name: z.string().min(1),
+    version: z.string().min(1),
+    pages: z.record(z.string().min(1), ManifestPageSchema),
+    blocks: z.record(z.string().min(1), ManifestBlockSchema),
+    styleSlots: StyleSlotDefaultsSchema.default({}),
+    presets: z.record(z.string().min(1), ThemePresetSchema).default({}),
+  })
+  .strict()
+  .superRefine((manifest, ctx) => {
+    for (const [pageId, page] of Object.entries(manifest.pages)) {
+      for (const blockType of page.allowedBlocks) {
+        if (!manifest.blocks[blockType]) {
+          ctx.addIssue({
+            code: 'custom',
+            path: ['pages', pageId, 'allowedBlocks'],
+            message: `Page "${pageId}" allows unknown block "${blockType}"`,
+          });
+        }
+      }
+
+      for (const [index, block] of page.defaultBlocks.entries()) {
+        if (!manifest.blocks[block.type]) {
+          ctx.addIssue({
+            code: 'custom',
+            path: ['pages', pageId, 'defaultBlocks', index, 'type'],
+            message: `Page "${pageId}" defaults unknown block "${block.type}"`,
+          });
+          continue;
+        }
+
+        if (!page.allowedBlocks.includes(block.type)) {
+          ctx.addIssue({
+            code: 'custom',
+            path: ['pages', pageId, 'defaultBlocks', index, 'type'],
+            message: `Page "${pageId}" defaults block "${block.type}" without allowing it`,
+          });
+        }
+
+        const blockDefinition = manifest.blocks[block.type];
+        if (block.variant && !blockDefinition.variants.some((variant) => variant.id === block.variant)) {
+          ctx.addIssue({
+            code: 'custom',
+            path: ['pages', pageId, 'defaultBlocks', index, 'variant'],
+            message: `Block "${block.type}" does not expose variant "${block.variant}"`,
+          });
+        }
+      }
+    }
+
+    for (const [blockType, block] of Object.entries(manifest.blocks)) {
+      for (const preset of block.presets) {
+        if (preset.variant && !block.variants.some((variant) => variant.id === preset.variant)) {
+          ctx.addIssue({
+            code: 'custom',
+            path: ['blocks', blockType, 'presets', preset.id, 'variant'],
+            message: `Block preset "${preset.id}" references unknown variant "${preset.variant}"`,
+          });
+        }
+      }
+    }
+  });
+export type ThemeManifest = z.infer<typeof ThemeManifestSchema>;
+
+export function parseThemeManifest(input: unknown): ThemeManifest {
+  return ThemeManifestSchema.parse(input);
+}

package/src/validation.ts

@@ -0,0 +1,196 @@
+import type { BlockInstance, BuilderSettings } from './builder-settings.ts';
+import type { ThemeManifest } from './theme-manifest.ts';
+
+export type BuilderManifestValidationIssueCode =
+  | 'unknown_page'
+  | 'duplicate_block_id'
+  | 'unknown_block_type'
+  | 'block_not_allowed'
+  | 'too_many_block_instances'
+  | 'unknown_block_variant'
+  | 'unknown_block_setting'
+  | 'unexposed_style_slot';
+
+export type BuilderManifestValidationIssue = {
+  code: BuilderManifestValidationIssueCode;
+  path: string;
+  message: string;
+};
+
+export class BuilderManifestValidationError extends Error {
+  readonly issues: BuilderManifestValidationIssue[];
+
+  constructor(issues: BuilderManifestValidationIssue[]) {
+    super(formatBuilderManifestValidationIssues(issues));
+    this.name = 'BuilderManifestValidationError';
+    this.issues = issues;
+  }
+}
+
+export function validateBuilderSettingsAgainstManifest(
+  settings: BuilderSettings,
+  manifest: ThemeManifest,
+): BuilderManifestValidationIssue[] {
+  const issues: BuilderManifestValidationIssue[] = [];
+
+  for (const [pageId, layout] of Object.entries(settings.theme.layout)) {
+    const page = manifest.pages[pageId];
+    if (!page) {
+      issues.push({
+        code: 'unknown_page',
+        path: `theme.layout.${pageId}`,
+        message: `Unknown builder page "${pageId}"`,
+      });
+      continue;
+    }
+
+    const blockIds = new Set<string>();
+    const blockTypeCounts = new Map<string, number>();
+
+    for (const [index, block] of layout.blocks.entries()) {
+      const blockPath = `theme.layout.${pageId}.blocks.${index}`;
+
+      if (blockIds.has(block.id)) {
+        issues.push({
+          code: 'duplicate_block_id',
+          path: `${blockPath}.id`,
+          message: `Duplicate block id "${block.id}" on page "${pageId}"`,
+        });
+      }
+      blockIds.add(block.id);
+
+      const blockDefinition = manifest.blocks[block.type];
+      if (!blockDefinition) {
+        issues.push({
+          code: 'unknown_block_type',
+          path: `${blockPath}.type`,
+          message: `Unknown builder block type "${block.type}"`,
+        });
+        continue;
+      }
+
+      if (!page.allowedBlocks.includes(block.type)) {
+        issues.push({
+          code: 'block_not_allowed',
+          path: `${blockPath}.type`,
+          message: `Block "${block.type}" is not allowed on page "${pageId}"`,
+        });
+      }
+
+      blockTypeCounts.set(block.type, (blockTypeCounts.get(block.type) ?? 0) + 1);
+      validateBlockVariant(block, blockDefinition.variants, blockPath, issues);
+      validateBlockSettings(block, Object.keys(blockDefinition.settings), blockPath, issues);
+      validateBlockStyleOverrides(block, blockDefinition.exposedStyleSlots, blockPath, issues);
+    }
+
+    for (const [blockType, count] of blockTypeCounts.entries()) {
+      const maxInstances = manifest.blocks[blockType]?.maxInstances;
+      if (maxInstances !== undefined && count > maxInstances) {
+        issues.push({
+          code: 'too_many_block_instances',
+          path: `theme.layout.${pageId}.blocks`,
+          message: `Page "${pageId}" has ${count} "${blockType}" blocks but the manifest allows ${maxInstances}`,
+        });
+      }
+    }
+  }
+
+  return issues;
+}
+
+export function assertBuilderSettingsMatchManifest(
+  settings: BuilderSettings,
+  manifest: ThemeManifest,
+): void {
+  const issues = validateBuilderSettingsAgainstManifest(settings, manifest);
+  if (issues.length > 0) {
+    throw new BuilderManifestValidationError(issues);
+  }
+}
+
+export function formatBuilderManifestValidationIssues(
+  issues: BuilderManifestValidationIssue[],
+): string {
+  if (issues.length === 0) {
+    return 'Builder settings match the theme manifest';
+  }
+
+  const [firstIssue] = issues;
+  const suffix = issues.length === 1 ? '' : ` (+${issues.length - 1} more)`;
+  return `${firstIssue.message}${suffix}`;
+}
+
+function validateBlockSettings(
+  block: BlockInstance,
+  settingPaths: string[],
+  blockPath: string,
+  issues: BuilderManifestValidationIssue[],
+): void {
+  if (settingPaths.length === 0 && Object.keys(block.settings).length === 0) {
+    return;
+  }
+
+  const allowedSettings = new Set<string>();
+  for (const path of settingPaths) {
+    allowedSettings.add(path);
+    allowedSettings.add(getShortSettingKey(path));
+  }
+
+  for (const key of Object.keys(block.settings)) {
+    if (allowedSettings.has(key)) {
+      continue;
+    }
+
+    issues.push({
+      code: 'unknown_block_setting',
+      path: `${blockPath}.settings.${key}`,
+      message: `Block "${block.id}" stores unknown setting "${key}"`,
+    });
+  }
+}
+
+function validateBlockVariant(
+  block: BlockInstance,
+  variants: Array<{ id: string }>,
+  blockPath: string,
+  issues: BuilderManifestValidationIssue[],
+): void {
+  if (!block.variant) {
+    return;
+  }
+
+  if (!variants.some((variant) => variant.id === block.variant)) {
+    issues.push({
+      code: 'unknown_block_variant',
+      path: `${blockPath}.variant`,
+      message: `Block "${block.id}" uses unknown variant "${block.variant}"`,
+    });
+  }
+}
+
+function getShortSettingKey(path: string): string {
+  const parts = path.split('.').filter(Boolean);
+  return parts.at(-1) ?? path;
+}
+
+function validateBlockStyleOverrides(
+  block: BlockInstance,
+  exposedStyleSlots: string[],
+  blockPath: string,
+  issues: BuilderManifestValidationIssue[],
+): void {
+  if (!block.style_overrides) {
+    return;
+  }
+
+  const exposed = new Set(exposedStyleSlots);
+  for (const slotId of Object.keys(block.style_overrides)) {
+    if (!exposed.has(slotId)) {
+      issues.push({
+        code: 'unexposed_style_slot',
+        path: `${blockPath}.style_overrides.${slotId}`,
+        message: `Block "${block.id}" cannot override unexposed style slot "${slotId}"`,
+      });
+    }
+  }
+}