@shoppexio/builder-contracts 0.1.0 → 0.1.1

package/src/fields.ts

@@ -7,6 +7,11 @@ const FieldBaseSchema = z
     description: z.string().min(1).optional(),
     defaultValue: z.unknown().optional(),
     required: z.boolean().optional(),
+    // Groups settings within the Inspector. "content" (default) shows
+    // under the Block Settings collapsible; "style" shows under a
+    // separate Style collapsible. Themes pick up the value via the
+    // existing block.settings.path lookup — no runtime change.
+    group: z.enum(['content', 'style']).optional(),
   })
   .strict();
 
@@ -30,6 +35,30 @@ const RichTextFieldSchema = FieldBaseSchema.extend({
   allowedMarks: z.array(z.enum(['bold', 'italic', 'link', 'code'])).optional(),
 }).strict();
 
+// Plain-text source code field. Renders a Monaco editor in the
+// Inspector and persists the raw string back into block.settings.
+// Used by the `custom-html` block (and any future block that needs
+// a code-shaped setting). Themes interpret the string however they
+// see fit — sandboxed iframe srcDoc for HTML, etc.
+const CodeFieldTemplateSchema = z
+  .object({
+    label: z.string().min(1),
+    snippet: z.string().min(1),
+    description: z.string().min(1).optional(),
+  })
+  .strict();
+export type CodeFieldTemplate = z.infer<typeof CodeFieldTemplateSchema>;
+
+const CodeFieldSchema = FieldBaseSchema.extend({
+  type: z.literal('code'),
+  language: z.enum(['html', 'css', 'javascript', 'json']).optional(),
+  placeholder: z.string().optional(),
+  maxLength: z.number().int().positive().optional(),
+  // Optional quick-insert chips rendered above the editor. Clicking a
+  // template replaces the field value with the snippet.
+  templates: z.array(CodeFieldTemplateSchema).optional(),
+}).strict();
+
 const ImageFieldSchema = FieldBaseSchema.extend({
   type: z.literal('image'),
   aspectRatio: z.string().min(1).optional(),
@@ -117,6 +146,7 @@ const ListFieldSchema = FieldBaseSchema.extend({
 export const BuilderFieldSchema = z.discriminatedUnion('type', [
   TextFieldSchema,
   RichTextFieldSchema,
+  CodeFieldSchema,
   ImageFieldSchema,
   LinkFieldSchema,
   BooleanFieldSchema,

package/src/index.ts

@@ -1,9 +1,16 @@
 export * from './builder-settings.ts';
+export * from './canonical-settings.ts';
 export * from './events.ts';
 export * from './fields.ts';
 export * from './legacy-manifest.ts';
 export * from './migrations.ts';
+export * from './persistence.ts';
+export * from './preview-boot.ts';
 export * from './preview-protocol.ts';
+export * from './preview-session-resolve.ts';
+export * from './preview-trusted-origins.ts';
+export * from './storefront-initial-data-html.ts';
 export * from './style-slots.ts';
 export * from './theme-manifest.ts';
+export * from './theme-schemes.ts';
 export * from './validation.ts';

package/src/legacy-manifest.ts

@@ -1,6 +1,7 @@
 import * as z from 'zod/v4';
 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 +84,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 +108,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]) => [
@@ -131,6 +148,17 @@ 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);
@@ -158,6 +186,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);
@@ -178,16 +208,22 @@ function createSyntheticPageBlockType(pageId: string): string {
 
 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 +247,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 +291,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,6 +383,28 @@ 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' },

package/src/migrations.ts

@@ -6,6 +6,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 = {
@@ -67,7 +68,7 @@ export function migrateLegacyBuilderSettings(input: LegacyBuilderSettingsInput,
     ...(input.theme?.style_slots ?? {}),
   };
 
-  return BuilderSettingsSchema.parse({
+  return sanitizeBuilderSettingsState(BuilderSettingsSchema.parse({
     version: BUILDER_SETTINGS_VERSION,
     revision,
     theme: {
@@ -77,7 +78,7 @@ export function migrateLegacyBuilderSettings(input: LegacyBuilderSettingsInput,
       pages: [],
       terms: {},
     },
-  });
+  }));
 }
 
 export function applyManifestDefaultLayout(settings: BuilderSettings, manifest: ThemeManifest): BuilderSettings {
@@ -110,13 +111,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 +209,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 +221,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.ts

@@ -0,0 +1,47 @@
+import * as z from 'zod/v4';
+import { BuilderSettingsSchema } from './builder-settings.ts';
+
+export const PREVIEW_BOOT_SIDECAR_PATH = '__shoppex/preview-boot.json';
+
+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(),
+  })
+  .strict();
+
+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);
+}

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