@shoppexio/builder-contracts 0.1.2 → 0.1.3

package/dist/fields.d.ts

@@ -14,13 +14,13 @@ export declare const ListItemFieldTypeSchema: z.ZodEnum<{
     number: "number";
     boolean: "boolean";
     link: "link";
+    product: "product";
     text: "text";
     richtext: "richtext";
     image: "image";
     range: "range";
     select: "select";
     color: "color";
-    product: "product";
 }>;
 export type ListItemFieldType = z.infer<typeof ListItemFieldTypeSchema>;
 export declare const ListItemFieldSchema: z.ZodObject<{
@@ -38,13 +38,13 @@ export declare const ListItemFieldSchema: z.ZodObject<{
         number: "number";
         boolean: "boolean";
         link: "link";
+        product: "product";
         text: "text";
         richtext: "richtext";
         image: "image";
         range: "range";
         select: "select";
         color: "color";
-        product: "product";
     }>;
     options: z.ZodOptional<z.ZodArray<z.ZodObject<{
         label: z.ZodString;
@@ -266,13 +266,13 @@ export declare const BuilderFieldSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             number: "number";
             boolean: "boolean";
             link: "link";
+            product: "product";
             text: "text";
             richtext: "richtext";
             image: "image";
             range: "range";
             select: "select";
             color: "color";
-            product: "product";
         }>;
         options: z.ZodOptional<z.ZodArray<z.ZodObject<{
             label: z.ZodString;
@@ -495,13 +495,13 @@ export declare const BlockSettingsSchema: z.ZodRecord<z.ZodString, z.ZodDiscrimi
             number: "number";
             boolean: "boolean";
             link: "link";
+            product: "product";
             text: "text";
             richtext: "richtext";
             image: "image";
             range: "range";
             select: "select";
             color: "color";
-            product: "product";
         }>;
         options: z.ZodOptional<z.ZodArray<z.ZodObject<{
             label: z.ZodString;

package/dist/migrations.d.ts

@@ -27,5 +27,6 @@ export declare function createBlockInstance(input: {
 export declare function createPageLayoutFromBlocks(blocks: BlockInstance[]): PageLayout;
 export declare function migrateLegacyBuilderSettings(input: LegacyBuilderSettingsInput, revision?: number): BuilderSettings;
 export declare function applyManifestDefaultLayout(settings: BuilderSettings, manifest: ThemeManifest): BuilderSettings;
+export declare function mapLegacyNestedThemeTypographyToStyleSlots(theme: Record<string, unknown>, baseSlots?: StyleSlots): StyleSlots;
 export declare function mapLegacyTokenOverridesToStyleSlots(tokens: Record<string, unknown>): StyleSlots;
 //# sourceMappingURL=migrations.d.ts.map

package/dist/migrations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../src/migrations.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,eAAe,EAEpB,KAAK,UAAU,EAChB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,MAAM,0BAA0B,GAAG;IACvC,KAAK,CAAC,EAAE;QACN,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACjC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC1C,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACvC,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,wBAAgB,0BAA0B,CAAC,QAAQ,SAAI,GAAG,eAAe,CAYxE;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,eAAe,CAAC,EAAE,UAAU,CAAC;CAC9B,GAAG,aAAa,CAShB;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,UAAU,CAE9E;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,0BAA0B,EAAE,QAAQ,SAAI,GAAG,eAAe,CAoB7G;AAED,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,eAAe,EAAE,QAAQ,EAAE,aAAa,GAAG,eAAe,CAwB9G;AAED,wBAAgB,mCAAmC,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU,CAuC/F"}
+{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../src/migrations.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,eAAe,EAEpB,KAAK,UAAU,EAChB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,MAAM,0BAA0B,GAAG;IACvC,KAAK,CAAC,EAAE;QACN,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACjC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC1C,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACvC,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,wBAAgB,0BAA0B,CAAC,QAAQ,SAAI,GAAG,eAAe,CAYxE;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,eAAe,CAAC,EAAE,UAAU,CAAC;CAC9B,GAAG,aAAa,CAShB;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,UAAU,CAE9E;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,0BAA0B,EAAE,QAAQ,SAAI,GAAG,eAAe,CAoB7G;AAED,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,eAAe,EAAE,QAAQ,EAAE,aAAa,GAAG,eAAe,CAwB9G;AAED,wBAAgB,0CAA0C,CACxD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,SAAS,GAAE,UAAe,GACzB,UAAU,CAkBZ;AAeD,wBAAgB,mCAAmC,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU,CAuC/F"}

package/dist/migrations.js

@@ -69,6 +69,31 @@ export function applyManifestDefaultLayout(settings, manifest) {
     }
     return BuilderSettingsSchema.parse(next);
 }
+export function mapLegacyNestedThemeTypographyToStyleSlots(theme, baseSlots = {}) {
+    const slots = { ...baseSlots };
+    const typography = theme.typography;
+    if (!isRecord(typography)) {
+        return slots;
+    }
+    const bodyFont = readLegacyTypographyString(typography, 'font_family', 'fontFamily');
+    const headingFont = readLegacyTypographyString(typography, 'heading_font', 'headingFont');
+    if (bodyFont && slots['theme.typography.font.family'] === undefined) {
+        slots['theme.typography.font.family'] = bodyFont;
+    }
+    if (headingFont && slots['theme.typography.heading.font'] === undefined) {
+        slots['theme.typography.heading.font'] = headingFont;
+    }
+    return slots;
+}
+function readLegacyTypographyString(typography, ...keys) {
+    for (const key of keys) {
+        const value = typography[key];
+        if (typeof value === 'string' && value.trim().length > 0) {
+            return value.trim();
+        }
+    }
+    return null;
+}
 export function mapLegacyTokenOverridesToStyleSlots(tokens) {
     const slots = {};
     assignResponsiveNumber(tokens, slots, 'buttons.borderRadius', 'button.radius');

package/dist/persistence.d.ts

@@ -1,6 +1,15 @@
 import { type BuilderSettings } from './builder-settings.ts';
 type JsonRecord = Record<string, unknown>;
 export declare function extractPersistedBuilderSettings(input: unknown): BuilderSettings | null;
+/**
+ * Single read boundary for builder v2 state: strict extract first, then legacy migration.
+ * Strips invalid keys such as nested `theme.typography` while preserving style_slots and pages.
+ */
+export declare function coercePersistedBuilderSettings(input: unknown): BuilderSettings | null;
+/**
+ * Coerces builder v2 fields for storefront export while preserving non-v2 siblings (seo, appearance, …).
+ */
+export declare function exportCoercedBuilderSettingsBlob(builderSettingsBlob: unknown): JsonRecord | null;
 export declare function sanitizeBuilderSettingsState(settings: BuilderSettings): BuilderSettings;
 export declare function mergeBuilderSettingsIntoThemeSettings(currentSettings: unknown, builderSettings: BuilderSettings): JsonRecord;
 export {};

package/dist/persistence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../src/persistence.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,eAAe,EAErB,MAAM,uBAAuB,CAAC;AAE/B,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAmB1C,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,GAAG,IAAI,CAYtF;AAED,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,eAAe,GAAG,eAAe,CASvF;AAaD,wBAAgB,qCAAqC,CACnD,eAAe,EAAE,OAAO,EACxB,eAAe,EAAE,eAAe,GAC/B,UAAU,CAaZ"}
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../src/persistence.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,eAAe,EAErB,MAAM,uBAAuB,CAAC;AAQ/B,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAmB1C,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,GAAG,IAAI,CAYtF;AA0BD;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,GAAG,IAAI,CAkDrF;AAED;;GAEG;AACH,wBAAgB,gCAAgC,CAAC,mBAAmB,EAAE,OAAO,GAAG,UAAU,GAAG,IAAI,CAgBhG;AAED,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,eAAe,GAAG,eAAe,CASvF;AAaD,wBAAgB,qCAAqC,CACnD,eAAe,EAAE,OAAO,EACxB,eAAe,EAAE,eAAe,GAC/B,UAAU,CAaZ"}

package/dist/persistence.js

@@ -1,4 +1,5 @@
 import { BuilderSettingsSchema, } from "./builder-settings.js";
+import { mapLegacyNestedThemeTypographyToStyleSlots, mapLegacyTokenOverridesToStyleSlots, migrateLegacyBuilderSettings, } from "./migrations.js";
 const RESERVED_THEME_CONTENT_KEYS = new Set(['layout']);
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -24,6 +25,85 @@ export function extractPersistedBuilderSettings(input) {
     const parsedNested = BuilderSettingsSchema.safeParse(pickBuilderSettingsFields(input.builder_settings));
     return parsedNested.success ? sanitizeBuilderSettingsState(parsedNested.data) : null;
 }
+function parseBuilderSettingsRevision(input) {
+    return typeof input === 'number' && Number.isInteger(input) && input >= 0 ? input : 0;
+}
+function unwrapBuilderSettingsRecord(input) {
+    if (!isRecord(input)) {
+        return null;
+    }
+    if (isRecord(input.builder_settings)) {
+        return input.builder_settings;
+    }
+    if ('version' in input || 'revision' in input || 'theme' in input) {
+        return input;
+    }
+    return null;
+}
+function readStyleSlotsRecord(theme) {
+    return isRecord(theme.style_slots) ? theme.style_slots : {};
+}
+/**
+ * Single read boundary for builder v2 state: strict extract first, then legacy migration.
+ * Strips invalid keys such as nested `theme.typography` while preserving style_slots and pages.
+ */
+export function coercePersistedBuilderSettings(input) {
+    const extracted = extractPersistedBuilderSettings(input);
+    if (extracted) {
+        return extracted;
+    }
+    if (isRecord(input) && isRecord(input.builder_settings)) {
+        const nestedExtracted = extractPersistedBuilderSettings(input.builder_settings);
+        if (nestedExtracted) {
+            return nestedExtracted;
+        }
+    }
+    const blob = unwrapBuilderSettingsRecord(input);
+    if (!blob) {
+        return null;
+    }
+    const theme = isRecord(blob.theme) ? blob.theme : {};
+    const tokensOverride = isRecord(theme.tokens_override) ? theme.tokens_override : {};
+    const styleSlots = mapLegacyNestedThemeTypographyToStyleSlots(theme, {
+        ...mapLegacyTokenOverridesToStyleSlots(tokensOverride),
+        ...readStyleSlotsRecord(theme),
+    });
+    const migrated = migrateLegacyBuilderSettings({
+        theme: {
+            content: isRecord(theme.content) ? theme.content : {},
+            layout: isRecord(theme.layout) ? theme.layout : {},
+            tokens_override: tokensOverride,
+            style_slots: styleSlots,
+        },
+    }, parseBuilderSettingsRevision(blob.revision));
+    const merged = BuilderSettingsSchema.safeParse({
+        ...migrated,
+        theme: {
+            ...migrated.theme,
+            pages: Array.isArray(theme.pages) ? theme.pages : migrated.theme.pages,
+            terms: isRecord(theme.terms) ? theme.terms : migrated.theme.terms,
+        },
+    });
+    return merged.success ? sanitizeBuilderSettingsState(merged.data) : migrated;
+}
+/**
+ * Coerces builder v2 fields for storefront export while preserving non-v2 siblings (seo, appearance, …).
+ */
+export function exportCoercedBuilderSettingsBlob(builderSettingsBlob) {
+    if (!isRecord(builderSettingsBlob)) {
+        return null;
+    }
+    const coerced = coercePersistedBuilderSettings(builderSettingsBlob);
+    if (!coerced) {
+        return null;
+    }
+    return {
+        ...builderSettingsBlob,
+        version: coerced.version,
+        revision: coerced.revision,
+        theme: coerced.theme,
+    };
+}
 export function sanitizeBuilderSettingsState(settings) {
     const content = sanitizeThemeContent(settings.theme.content);
     return BuilderSettingsSchema.parse({

package/dist/preview-protocol.d.ts

@@ -66,6 +66,24 @@ export declare const PreviewApplyStateMessageSchema: z.ZodObject<{
         }, z.core.$strict>;
     }, z.core.$strict>;
 }, z.core.$strict>;
+export declare const EdgeBlockRenderModeSchema: z.ZodLiteral<"edge-block-engine">;
+export type EdgeBlockRenderMode = z.infer<typeof EdgeBlockRenderModeSchema>;
+export declare const PreviewBlockHtmlPatchSchema: z.ZodObject<{
+    blockId: z.ZodString;
+    html: z.ZodString;
+}, z.core.$strict>;
+export type PreviewBlockHtmlPatch = z.infer<typeof PreviewBlockHtmlPatchSchema>;
+export declare const PreviewApplyBlockHtmlMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"APPLY_BLOCK_HTML">;
+    revision: z.ZodNumber;
+    pageId: z.ZodString;
+    sourceRevision: z.ZodString;
+    renderMode: z.ZodLiteral<"edge-block-engine">;
+    blocks: z.ZodArray<z.ZodObject<{
+        blockId: z.ZodString;
+        html: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
 export declare const PreviewReloadMessageSchema: z.ZodObject<{
     type: z.ZodLiteral<"RELOAD">;
     revision: z.ZodNumber;
@@ -164,6 +182,16 @@ export declare const PreviewMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
             }, z.core.$strict>>;
         }, z.core.$strict>;
     }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"APPLY_BLOCK_HTML">;
+    revision: z.ZodNumber;
+    pageId: z.ZodString;
+    sourceRevision: z.ZodString;
+    renderMode: z.ZodLiteral<"edge-block-engine">;
+    blocks: z.ZodArray<z.ZodObject<{
+        blockId: z.ZodString;
+        html: z.ZodString;
+    }, z.core.$strict>>;
 }, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"RELOAD">;
     revision: z.ZodNumber;
@@ -209,14 +237,28 @@ export declare const PreviewBootstrapOkResponseSchema: z.ZodObject<{
     shopId: z.ZodString;
     artifactStale: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
+export declare const PreviewReadyHealthSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    reactMounted: z.ZodLiteral<true>;
+    builderRuntimeProvider: z.ZodLiteral<true>;
+    protocolVersion: z.ZodLiteral<2>;
+}, z.core.$strict>, z.ZodObject<{
+    edgeBlockEngine: z.ZodLiteral<true>;
+    blockHtmlReconcile: z.ZodLiteral<true>;
+    protocolVersion: z.ZodLiteral<3>;
+}, z.core.$strict>], "protocolVersion">;
+export type PreviewReadyHealth = z.infer<typeof PreviewReadyHealthSchema>;
 export declare const PreviewReadyResponseSchema: z.ZodObject<{
     type: z.ZodLiteral<"READY">;
     revision: z.ZodNumber;
-    health: z.ZodOptional<z.ZodObject<{
+    health: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
         reactMounted: z.ZodLiteral<true>;
         builderRuntimeProvider: z.ZodLiteral<true>;
         protocolVersion: z.ZodLiteral<2>;
-    }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        edgeBlockEngine: z.ZodLiteral<true>;
+        blockHtmlReconcile: z.ZodLiteral<true>;
+        protocolVersion: z.ZodLiteral<3>;
+    }, z.core.$strict>], "protocolVersion">>;
 }, z.core.$strict>;
 export declare const PreviewAppliedResponseSchema: z.ZodObject<{
     type: z.ZodLiteral<"APPLIED">;
@@ -227,6 +269,26 @@ export declare const PreviewApplyFailedResponseSchema: z.ZodObject<{
     revision: z.ZodNumber;
     error: z.ZodString;
 }, z.core.$strict>;
+export declare const PreviewBlockHtmlAppliedResponseSchema: z.ZodObject<{
+    type: z.ZodLiteral<"BLOCK_HTML_APPLIED">;
+    revision: z.ZodNumber;
+    pageId: z.ZodString;
+    sourceRevision: z.ZodString;
+    renderMode: z.ZodLiteral<"edge-block-engine">;
+    blocks: z.ZodArray<z.ZodObject<{
+        blockId: z.ZodString;
+        html: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const PreviewBlockHtmlFailedResponseSchema: z.ZodObject<{
+    type: z.ZodLiteral<"BLOCK_HTML_FAILED">;
+    revision: z.ZodNumber;
+    pageId: z.ZodString;
+    sourceRevision: z.ZodOptional<z.ZodString>;
+    renderMode: z.ZodLiteral<"edge-block-engine">;
+    blockIds: z.ZodArray<z.ZodString>;
+    error: z.ZodString;
+}, z.core.$strict>;
 export declare const PreviewElementClickedResponseSchema: z.ZodObject<{
     type: z.ZodLiteral<"ELEMENT_CLICKED">;
     revision: z.ZodOptional<z.ZodNumber>;
@@ -351,11 +413,15 @@ export declare const PreviewResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject
 }, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"READY">;
     revision: z.ZodNumber;
-    health: z.ZodOptional<z.ZodObject<{
+    health: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
         reactMounted: z.ZodLiteral<true>;
         builderRuntimeProvider: z.ZodLiteral<true>;
         protocolVersion: z.ZodLiteral<2>;
-    }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        edgeBlockEngine: z.ZodLiteral<true>;
+        blockHtmlReconcile: z.ZodLiteral<true>;
+        protocolVersion: z.ZodLiteral<3>;
+    }, z.core.$strict>], "protocolVersion">>;
 }, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"APPLIED">;
     revision: z.ZodNumber;
@@ -363,6 +429,24 @@ export declare const PreviewResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject
     type: z.ZodLiteral<"APPLY_FAILED">;
     revision: z.ZodNumber;
     error: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"BLOCK_HTML_APPLIED">;
+    revision: z.ZodNumber;
+    pageId: z.ZodString;
+    sourceRevision: z.ZodString;
+    renderMode: z.ZodLiteral<"edge-block-engine">;
+    blocks: z.ZodArray<z.ZodObject<{
+        blockId: z.ZodString;
+        html: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"BLOCK_HTML_FAILED">;
+    revision: z.ZodNumber;
+    pageId: z.ZodString;
+    sourceRevision: z.ZodOptional<z.ZodString>;
+    renderMode: z.ZodLiteral<"edge-block-engine">;
+    blockIds: z.ZodArray<z.ZodString>;
+    error: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"ELEMENT_CLICKED">;
     revision: z.ZodOptional<z.ZodNumber>;

package/dist/preview-protocol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"preview-protocol.d.ts","sourceRoot":"","sources":["../src/preview-protocol.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAG5B,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;kBAYxB,CAAC;AACZ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAMhC,CAAC;AAEZ,eAAO,MAAM,0BAA0B;;;;;;;kBAM5B,CAAC;AAEZ,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;;;;kBAMnC,CAAC;AAEZ,eAAO,MAAM,gCAAgC;;kBAIlC,CAAC;AAEZ,eAAO,MAAM,qBAAqB;;;EAA8B,CAAC;AACjE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;;;GAKG;AACH,eAAO,MAAM,sCAAsC;;;;;;kBAKxC,CAAC;AAEZ,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAM/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,eAAO,MAAM,gCAAgC;;;;;;kBAQlC,CAAC;AAEZ,eAAO,MAAM,0BAA0B;;;;;;;;kBAa5B,CAAC;AAEZ,eAAO,MAAM,4BAA4B;;;kBAK9B,CAAC;AAEZ,eAAO,MAAM,gCAAgC;;;;kBAMlC,CAAC;AAEZ,eAAO,MAAM,mCAAmC;;;;;;;;;;;;;;;;;;;;;kBAMrC,CAAC;AAEZ,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBA0B5B,CAAC;AAEZ;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;;;kBAOnB,CAAC;AACZ,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,eAAO,MAAM,8BAA8B;;;;;;;;;;kBAOhC,CAAC;AAEZ;;;;GAIG;AACH,eAAO,MAAM,kCAAkC;;;;;;;;;;kBAOpC,CAAC;AAEZ;;;;GAIG;AACH,eAAO,MAAM,qCAAqC;;;;;;kBAQvC,CAAC;AAEZ,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAUhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC"}
+{"version":3,"file":"preview-protocol.d.ts","sourceRoot":"","sources":["../src/preview-protocol.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAG5B,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;kBAYxB,CAAC;AACZ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAMhC,CAAC;AAEZ,eAAO,MAAM,yBAAyB,mCAAiC,CAAC;AACxE,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,eAAO,MAAM,2BAA2B;;;kBAK7B,CAAC;AACZ,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,eAAO,MAAM,kCAAkC;;;;;;;;;;kBASpC,CAAC;AAEZ,eAAO,MAAM,0BAA0B;;;;;;;kBAM5B,CAAC;AAEZ,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;;;;kBAMnC,CAAC;AAEZ,eAAO,MAAM,gCAAgC;;kBAIlC,CAAC;AAEZ,eAAO,MAAM,qBAAqB;;;EAA8B,CAAC;AACjE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;;;GAKG;AACH,eAAO,MAAM,sCAAsC;;;;;;kBAKxC,CAAC;AAEZ,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAO/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,eAAO,MAAM,gCAAgC;;;;;;kBAQlC,CAAC;AAEZ,eAAO,MAAM,wBAAwB;;;;;;;;uCAenC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,eAAO,MAAM,0BAA0B;;;;;;;;;;;;kBAM5B,CAAC;AAEZ,eAAO,MAAM,4BAA4B;;;kBAK9B,CAAC;AAEZ,eAAO,MAAM,gCAAgC;;;;kBAMlC,CAAC;AAEZ,eAAO,MAAM,qCAAqC;;;;;;;;;;kBASvC,CAAC;AAEZ,eAAO,MAAM,oCAAoC;;;;;;;;kBAUtC,CAAC;AAEZ,eAAO,MAAM,mCAAmC;;;;;;;;;;;;;;;;;;;;;kBAMrC,CAAC;AAEZ,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBA0B5B,CAAC;AAEZ;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;;;kBAOnB,CAAC;AACZ,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,eAAO,MAAM,8BAA8B;;;;;;;;;;kBAOhC,CAAC;AAEZ;;;;GAIG;AACH,eAAO,MAAM,kCAAkC;;;;;;;;;;kBAOpC,CAAC;AAEZ;;;;GAIG;AACH,eAAO,MAAM,qCAAqC;;;;;;kBAQvC,CAAC;AAEZ,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAYhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC"}

package/dist/preview-protocol.js

@@ -20,6 +20,23 @@ export const PreviewApplyStateMessageSchema = z
     state: BuilderSettingsSchema,
 })
     .strict();
+export const EdgeBlockRenderModeSchema = z.literal('edge-block-engine');
+export const PreviewBlockHtmlPatchSchema = z
+    .object({
+    blockId: z.string().min(1),
+    html: z.string().min(1),
+})
+    .strict();
+export const PreviewApplyBlockHtmlMessageSchema = z
+    .object({
+    type: z.literal('APPLY_BLOCK_HTML'),
+    revision: z.number().int().nonnegative(),
+    pageId: z.string().min(1),
+    sourceRevision: z.string().min(1),
+    renderMode: EdgeBlockRenderModeSchema,
+    blocks: z.array(PreviewBlockHtmlPatchSchema).min(1),
+})
+    .strict();
 export const PreviewReloadMessageSchema = z
     .object({
     type: z.literal('RELOAD'),
@@ -54,6 +71,7 @@ export const PreviewSetInteractionModeMessageSchema = z
     .strict();
 export const PreviewMessageSchema = z.discriminatedUnion('type', [
     PreviewApplyStateMessageSchema,
+    PreviewApplyBlockHtmlMessageSchema,
     PreviewReloadMessageSchema,
     PreviewSelectElementMessageSchema,
     PreviewRequestReadyMessageSchema,
@@ -68,18 +86,27 @@ export const PreviewBootstrapOkResponseSchema = z
     artifactStale: z.boolean().optional(),
 })
     .strict();
-export const PreviewReadyResponseSchema = z
-    .object({
-    type: z.literal('READY'),
-    revision: z.number().int().nonnegative(),
-    health: z
+export const PreviewReadyHealthSchema = z.discriminatedUnion('protocolVersion', [
+    z
         .object({
         reactMounted: z.literal(true),
         builderRuntimeProvider: z.literal(true),
         protocolVersion: z.literal(2),
     })
-        .strict()
-        .optional(),
+        .strict(),
+    z
+        .object({
+        edgeBlockEngine: z.literal(true),
+        blockHtmlReconcile: z.literal(true),
+        protocolVersion: z.literal(3),
+    })
+        .strict(),
+]);
+export const PreviewReadyResponseSchema = z
+    .object({
+    type: z.literal('READY'),
+    revision: z.number().int().nonnegative(),
+    health: PreviewReadyHealthSchema.optional(),
 })
     .strict();
 export const PreviewAppliedResponseSchema = z
@@ -95,6 +122,27 @@ export const PreviewApplyFailedResponseSchema = z
     error: z.string().min(1),
 })
     .strict();
+export const PreviewBlockHtmlAppliedResponseSchema = z
+    .object({
+    type: z.literal('BLOCK_HTML_APPLIED'),
+    revision: z.number().int().nonnegative(),
+    pageId: z.string().min(1),
+    sourceRevision: z.string().min(1),
+    renderMode: EdgeBlockRenderModeSchema,
+    blocks: z.array(PreviewBlockHtmlPatchSchema).min(1),
+})
+    .strict();
+export const PreviewBlockHtmlFailedResponseSchema = z
+    .object({
+    type: z.literal('BLOCK_HTML_FAILED'),
+    revision: z.number().int().nonnegative(),
+    pageId: z.string().min(1),
+    sourceRevision: z.string().min(1).optional(),
+    renderMode: EdgeBlockRenderModeSchema,
+    blockIds: z.array(z.string().min(1)).min(1),
+    error: z.string().min(1),
+})
+    .strict();
 export const PreviewElementClickedResponseSchema = z
     .object({
     type: z.literal('ELEMENT_CLICKED'),
@@ -183,6 +231,8 @@ export const PreviewResponseSchema = z.discriminatedUnion('type', [
     PreviewReadyResponseSchema,
     PreviewAppliedResponseSchema,
     PreviewApplyFailedResponseSchema,
+    PreviewBlockHtmlAppliedResponseSchema,
+    PreviewBlockHtmlFailedResponseSchema,
     PreviewElementClickedResponseSchema,
     PreviewErrorResponseSchema,
     PreviewBlockRectResponseSchema,

package/dist/storefront-initial-data-html.js

@@ -44,7 +44,7 @@ export function buildPlainInitialDataScript(initialData) {
 export function buildWrappedStorefrontInitialDataScript(serialized, deployedThemeEntryPathPattern) {
     return [
         '<!--shoppex-initial-data:start--><script>(function(){',
-        'if(typeof window!=="undefined"){var path=window.location.pathname||"";',
+        'if(typeof window!=="undefined"){window.__SHOPPEX_DEPLOYED_THEME_ARTIFACT__=true;var path=window.location.pathname||"";',
         `if(${deployedThemeEntryPathPattern}.test(path)){window.__SHOPPEX_DEPLOYED_THEME_ARTIFACT_PATH__=path;window.history.replaceState(window.history.state,"","/"+window.location.search+window.location.hash);}}`,
         `window.__SHOPPEX_INITIAL__=${serialized};})();</script><!--shoppex-initial-data:end-->`,
     ].join('');

package/dist/theme-manifest.d.ts

@@ -252,13 +252,13 @@ export declare const ManifestBlockSchema: z.ZodObject<{
                 number: "number";
                 boolean: "boolean";
                 link: "link";
+                product: "product";
                 text: "text";
                 richtext: "richtext";
                 image: "image";
                 range: "range";
                 select: "select";
                 color: "color";
-                product: "product";
             }>;
             options: z.ZodOptional<z.ZodArray<z.ZodObject<{
                 label: z.ZodString;
@@ -585,13 +585,13 @@ export declare const ThemeManifestSchema: z.ZodObject<{
                     number: "number";
                     boolean: "boolean";
                     link: "link";
+                    product: "product";
                     text: "text";
                     richtext: "richtext";
                     image: "image";
                     range: "range";
                     select: "select";
                     color: "color";
-                    product: "product";
                 }>;
                 options: z.ZodOptional<z.ZodArray<z.ZodObject<{
                     label: z.ZodString;

package/dist/theme-schemes.d.ts

@@ -1,6 +1,6 @@
-export declare const PUBLIC_BUILDER_THEME_SCHEMES: readonly ["default", "classic", "nebula", "pulse", "phantom", "starlight", "apex", "vault", "clean-minimal"];
+export declare const PUBLIC_BUILDER_THEME_SCHEMES: readonly ["default", "classic", "nebula", "pulse", "phantom", "starlight", "apex", "vault", "vortex", "clean-minimal"];
 export declare const STARTER_BUILDER_THEME_SCHEMES: readonly ["blank"];
-export declare const BUILDER_READY_THEME_SCHEMES: readonly ["blank", "default", "classic", "nebula", "pulse", "phantom", "starlight", "apex", "vault", "clean-minimal"];
+export declare const BUILDER_READY_THEME_SCHEMES: readonly ["blank", "default", "classic", "nebula", "pulse", "phantom", "starlight", "apex", "vault", "vortex", "clean-minimal"];
 export type PublicBuilderThemeScheme = (typeof PUBLIC_BUILDER_THEME_SCHEMES)[number];
 export type StarterBuilderThemeScheme = (typeof STARTER_BUILDER_THEME_SCHEMES)[number];
 export type BuilderReadyThemeScheme = (typeof BUILDER_READY_THEME_SCHEMES)[number];

package/dist/theme-schemes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"theme-schemes.d.ts","sourceRoot":"","sources":["../src/theme-schemes.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,4BAA4B,8GAU/B,CAAC;AAEX,eAAO,MAAM,6BAA6B,oBAAqB,CAAC;AAEhE,eAAO,MAAM,2BAA2B,uHAG9B,CAAC;AAEX,MAAM,MAAM,wBAAwB,GAAG,CAAC,OAAO,4BAA4B,CAAC,CAAC,MAAM,CAAC,CAAC;AACrF,MAAM,MAAM,yBAAyB,GAAG,CAAC,OAAO,6BAA6B,CAAC,CAAC,MAAM,CAAC,CAAC;AACvF,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnF,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,wBAAwB,CAE3F;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,yBAAyB,CAE7F;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,uBAAuB,CAEzF"}
+{"version":3,"file":"theme-schemes.d.ts","sourceRoot":"","sources":["../src/theme-schemes.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,4BAA4B,wHAW/B,CAAC;AAEX,eAAO,MAAM,6BAA6B,oBAAqB,CAAC;AAEhE,eAAO,MAAM,2BAA2B,iIAG9B,CAAC;AAEX,MAAM,MAAM,wBAAwB,GAAG,CAAC,OAAO,4BAA4B,CAAC,CAAC,MAAM,CAAC,CAAC;AACrF,MAAM,MAAM,yBAAyB,GAAG,CAAC,OAAO,6BAA6B,CAAC,CAAC,MAAM,CAAC,CAAC;AACvF,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnF,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,wBAAwB,CAE3F;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,yBAAyB,CAE7F;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,uBAAuB,CAEzF"}

package/dist/theme-schemes.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shoppexio/builder-contracts",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Shared Builder v2 contracts for Shoppex dashboard, backend, preview runtime, and themes",
   "type": "module",
   "repository": {

package/src/builder-contracts.test.ts

@@ -13,6 +13,8 @@ import {
   createBlockInstance,
   createEmptyBuilderSettings,
   convertLegacyThemeManifest,
+  coercePersistedBuilderSettings,
+  exportCoercedBuilderSettingsBlob,
   extractPersistedBuilderSettings,
   canonicalizeBuilderSettingsForManifestWithReport,
   mergeBuilderSettingsIntoThemeSettings,
@@ -220,6 +222,52 @@ describe('@shoppex/builder-contracts', () => {
     expect(extractPersistedBuilderSettings(persisted)).toEqual(settings);
   });
 
+  test('coerces polluted v2 theme.typography into style_slots and strips invalid keys', () => {
+    const coerced = coercePersistedBuilderSettings({
+      version: 2,
+      revision: 9,
+      theme: {
+        content: {},
+        layout: {},
+        style_slots: {
+          'theme.typography.font.family': 'Manrope, sans-serif',
+        },
+        typography: {
+          font_family: 'Legacy Body',
+          heading_font: 'Legacy Heading',
+        },
+        pages: [],
+        terms: {},
+      },
+    });
+
+    expect(coerced).not.toBeNull();
+    expect(coerced?.theme.style_slots['theme.typography.font.family']).toBe('Manrope, sans-serif');
+    expect(coerced?.theme.style_slots['theme.typography.heading.font']).toBe('Legacy Heading');
+    expect(coerced?.theme).not.toHaveProperty('typography');
+    expect(() => BuilderSettingsSchema.parse(coerced)).not.toThrow();
+  });
+
+  test('exportCoercedBuilderSettingsBlob preserves non-v2 siblings', () => {
+    const exported = exportCoercedBuilderSettingsBlob({
+      seo: { default_title: 'Keep this title' },
+      version: 2,
+      revision: 4,
+      theme: {
+        content: {},
+        layout: {},
+        style_slots: {},
+        typography: { font_family: 'Inter' },
+        pages: [],
+        terms: {},
+      },
+    });
+
+    expect(exported?.seo).toEqual({ default_title: 'Keep this title' });
+    expect(exported?.theme).not.toHaveProperty('typography');
+    expect(exported?.theme.style_slots['theme.typography.font.family']).toBe('Inter');
+  });
+
   test('removes reserved content keys from persisted builder v2 state', () => {
     const settings = BuilderSettingsSchema.parse({
       ...createEmptyBuilderSettings(5),
@@ -809,7 +857,7 @@ describe('@shoppex/builder-contracts', () => {
 
   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']) {
+    for (const theme of ['default', 'nebula', 'classic', 'pulse', 'starlight', 'vault', 'phantom', 'apex', 'vortex']) {
       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/migrations.ts

@@ -110,6 +110,42 @@ export function applyManifestDefaultLayout(settings: BuilderSettings, manifest:
   return BuilderSettingsSchema.parse(next);
 }
 
+export function mapLegacyNestedThemeTypographyToStyleSlots(
+  theme: Record<string, unknown>,
+  baseSlots: StyleSlots = {},
+): StyleSlots {
+  const slots: StyleSlots = { ...baseSlots };
+  const typography = theme.typography;
+  if (!isRecord(typography)) {
+    return slots;
+  }
+
+  const bodyFont = readLegacyTypographyString(typography, 'font_family', 'fontFamily');
+  const headingFont = readLegacyTypographyString(typography, 'heading_font', 'headingFont');
+
+  if (bodyFont && slots['theme.typography.font.family'] === undefined) {
+    slots['theme.typography.font.family'] = bodyFont;
+  }
+  if (headingFont && slots['theme.typography.heading.font'] === undefined) {
+    slots['theme.typography.heading.font'] = headingFont;
+  }
+
+  return slots;
+}
+
+function readLegacyTypographyString(
+  typography: Record<string, unknown>,
+  ...keys: string[]
+): string | null {
+  for (const key of keys) {
+    const value = typography[key];
+    if (typeof value === 'string' && value.trim().length > 0) {
+      return value.trim();
+    }
+  }
+  return null;
+}
+
 export function mapLegacyTokenOverridesToStyleSlots(tokens: Record<string, unknown>): StyleSlots {
   const slots: StyleSlots = {};
 

package/src/persistence.ts

@@ -2,6 +2,12 @@ import {
   type BuilderSettings,
   BuilderSettingsSchema,
 } from './builder-settings.ts';
+import {
+  mapLegacyNestedThemeTypographyToStyleSlots,
+  mapLegacyTokenOverridesToStyleSlots,
+  migrateLegacyBuilderSettings,
+} from './migrations.ts';
+import type { StyleSlots } from './style-slots.ts';
 
 type JsonRecord = Record<string, unknown>;
 const RESERVED_THEME_CONTENT_KEYS = new Set(['layout']);
@@ -36,6 +42,107 @@ export function extractPersistedBuilderSettings(input: unknown): BuilderSettings
   return parsedNested.success ? sanitizeBuilderSettingsState(parsedNested.data) : null;
 }
 
+function parseBuilderSettingsRevision(input: unknown): number {
+  return typeof input === 'number' && Number.isInteger(input) && input >= 0 ? input : 0;
+}
+
+function unwrapBuilderSettingsRecord(input: unknown): JsonRecord | null {
+  if (!isRecord(input)) {
+    return null;
+  }
+
+  if (isRecord(input.builder_settings)) {
+    return input.builder_settings;
+  }
+
+  if ('version' in input || 'revision' in input || 'theme' in input) {
+    return input;
+  }
+
+  return null;
+}
+
+function readStyleSlotsRecord(theme: JsonRecord): StyleSlots {
+  return isRecord(theme.style_slots) ? theme.style_slots as StyleSlots : {};
+}
+
+/**
+ * Single read boundary for builder v2 state: strict extract first, then legacy migration.
+ * Strips invalid keys such as nested `theme.typography` while preserving style_slots and pages.
+ */
+export function coercePersistedBuilderSettings(input: unknown): BuilderSettings | null {
+  const extracted = extractPersistedBuilderSettings(input);
+  if (extracted) {
+    return extracted;
+  }
+
+  if (isRecord(input) && isRecord(input.builder_settings)) {
+    const nestedExtracted = extractPersistedBuilderSettings(input.builder_settings);
+    if (nestedExtracted) {
+      return nestedExtracted;
+    }
+  }
+
+  const blob = unwrapBuilderSettingsRecord(input);
+  if (!blob) {
+    return null;
+  }
+
+  const theme = isRecord(blob.theme) ? blob.theme : {};
+  const tokensOverride = isRecord(theme.tokens_override) ? theme.tokens_override : {};
+  const styleSlots = mapLegacyNestedThemeTypographyToStyleSlots(
+    theme,
+    {
+      ...mapLegacyTokenOverridesToStyleSlots(tokensOverride),
+      ...readStyleSlotsRecord(theme),
+    },
+  );
+
+  const migrated = migrateLegacyBuilderSettings(
+    {
+      theme: {
+        content: isRecord(theme.content) ? theme.content : {},
+        layout: isRecord(theme.layout) ? theme.layout : {},
+        tokens_override: tokensOverride,
+        style_slots: styleSlots,
+      },
+    },
+    parseBuilderSettingsRevision(blob.revision),
+  );
+
+  const merged = BuilderSettingsSchema.safeParse({
+    ...migrated,
+    theme: {
+      ...migrated.theme,
+      pages: Array.isArray(theme.pages) ? theme.pages : migrated.theme.pages,
+      terms: isRecord(theme.terms) ? theme.terms : migrated.theme.terms,
+    },
+  });
+
+  return merged.success ? sanitizeBuilderSettingsState(merged.data) : migrated;
+}
+
+/**
+ * Coerces builder v2 fields for storefront export while preserving non-v2 siblings (seo, appearance, …).
+ */
+export function exportCoercedBuilderSettingsBlob(builderSettingsBlob: unknown): JsonRecord | null {
+  if (!isRecord(builderSettingsBlob)) {
+    return null;
+  }
+
+  const coerced = coercePersistedBuilderSettings(builderSettingsBlob);
+  if (!coerced) {
+    return null;
+  }
+
+  return {
+    ...builderSettingsBlob,
+    version: coerced.version,
+    revision: coerced.revision,
+    theme: coerced.theme,
+  };
+}
+
 export function sanitizeBuilderSettingsState(settings: BuilderSettings): BuilderSettings {
   const content = sanitizeThemeContent(settings.theme.content);
   return BuilderSettingsSchema.parse({

package/src/preview-protocol.test.ts

@@ -5,6 +5,44 @@ import {
 } from './preview-protocol.ts';
 
 describe('PreviewMessageSchema', () => {
+  it('accepts v3 block HTML apply messages', () => {
+    const parsed = PreviewMessageSchema.parse({
+      type: 'APPLY_BLOCK_HTML',
+      revision: 12,
+      pageId: 'product',
+      sourceRevision: 'theme-source-12',
+      renderMode: 'edge-block-engine',
+      blocks: [
+        {
+          blockId: 'product-form-1',
+          html: '<section data-builder-block="product-form-1">Updated</section>',
+        },
+      ],
+    });
+
+    expect(parsed.type).toBe('APPLY_BLOCK_HTML');
+    if (parsed.type === 'APPLY_BLOCK_HTML') {
+      expect(parsed.blocks[0]?.blockId).toBe('product-form-1');
+    }
+  });
+
+  it('rejects v3 block HTML apply messages without sourceRevision', () => {
+    const result = PreviewMessageSchema.safeParse({
+      type: 'APPLY_BLOCK_HTML',
+      revision: 12,
+      pageId: 'product',
+      renderMode: 'edge-block-engine',
+      blocks: [
+        {
+          blockId: 'product-form-1',
+          html: '<section data-builder-block="product-form-1">Updated</section>',
+        },
+      ],
+    });
+
+    expect(result.success).toBe(false);
+  });
+
   it('accepts SET_INTERACTION_MODE with edit/preview', () => {
     for (const mode of ['edit', 'preview'] as const) {
       const parsed = PreviewMessageSchema.parse({
@@ -25,6 +63,58 @@ describe('PreviewMessageSchema', () => {
 });
 
 describe('PreviewResponseSchema', () => {
+  it('accepts READY health for edge block protocol v3', () => {
+    const parsed = PreviewResponseSchema.parse({
+      type: 'READY',
+      revision: 12,
+      health: {
+        edgeBlockEngine: true,
+        blockHtmlReconcile: true,
+        protocolVersion: 3,
+      },
+    });
+
+    expect(parsed.type).toBe('READY');
+    if (parsed.type === 'READY') {
+      expect(parsed.health?.protocolVersion).toBe(3);
+    }
+  });
+
+  it('accepts v3 block HTML applied responses', () => {
+    const parsed = PreviewResponseSchema.parse({
+      type: 'BLOCK_HTML_APPLIED',
+      revision: 12,
+      pageId: 'product',
+      sourceRevision: 'theme-source-12',
+      renderMode: 'edge-block-engine',
+      blocks: [
+        {
+          blockId: 'footer-1',
+          html: '<footer data-builder-block="footer-1">Secure delivery</footer>',
+        },
+      ],
+    });
+
+    expect(parsed.type).toBe('BLOCK_HTML_APPLIED');
+    if (parsed.type === 'BLOCK_HTML_APPLIED') {
+      expect(parsed.renderMode).toBe('edge-block-engine');
+    }
+  });
+
+  it('accepts v3 block HTML failed responses', () => {
+    const parsed = PreviewResponseSchema.parse({
+      type: 'BLOCK_HTML_FAILED',
+      revision: 12,
+      pageId: 'product',
+      sourceRevision: 'theme-source-12',
+      renderMode: 'edge-block-engine',
+      blockIds: ['footer-1'],
+      error: 'Rendered block root does not match block id.',
+    });
+
+    expect(parsed.type).toBe('BLOCK_HTML_FAILED');
+  });
+
   it('accepts BLOCK_RECT with rect', () => {
     const parsed = PreviewResponseSchema.parse({
       type: 'BLOCK_RECT',

package/src/preview-protocol.ts

@@ -24,6 +24,28 @@ export const PreviewApplyStateMessageSchema = z
   })
   .strict();
 
+export const EdgeBlockRenderModeSchema = z.literal('edge-block-engine');
+export type EdgeBlockRenderMode = z.infer<typeof EdgeBlockRenderModeSchema>;
+
+export const PreviewBlockHtmlPatchSchema = z
+  .object({
+    blockId: z.string().min(1),
+    html: z.string().min(1),
+  })
+  .strict();
+export type PreviewBlockHtmlPatch = z.infer<typeof PreviewBlockHtmlPatchSchema>;
+
+export const PreviewApplyBlockHtmlMessageSchema = z
+  .object({
+    type: z.literal('APPLY_BLOCK_HTML'),
+    revision: z.number().int().nonnegative(),
+    pageId: z.string().min(1),
+    sourceRevision: z.string().min(1),
+    renderMode: EdgeBlockRenderModeSchema,
+    blocks: z.array(PreviewBlockHtmlPatchSchema).min(1),
+  })
+  .strict();
+
 export const PreviewReloadMessageSchema = z
   .object({
     type: z.literal('RELOAD'),
@@ -64,6 +86,7 @@ export const PreviewSetInteractionModeMessageSchema = z
 
 export const PreviewMessageSchema = z.discriminatedUnion('type', [
   PreviewApplyStateMessageSchema,
+  PreviewApplyBlockHtmlMessageSchema,
   PreviewReloadMessageSchema,
   PreviewSelectElementMessageSchema,
   PreviewRequestReadyMessageSchema,
@@ -81,18 +104,29 @@ export const PreviewBootstrapOkResponseSchema = z
   })
   .strict();
 
+export const PreviewReadyHealthSchema = z.discriminatedUnion('protocolVersion', [
+  z
+    .object({
+      reactMounted: z.literal(true),
+      builderRuntimeProvider: z.literal(true),
+      protocolVersion: z.literal(2),
+    })
+    .strict(),
+  z
+    .object({
+      edgeBlockEngine: z.literal(true),
+      blockHtmlReconcile: z.literal(true),
+      protocolVersion: z.literal(3),
+    })
+    .strict(),
+]);
+export type PreviewReadyHealth = z.infer<typeof PreviewReadyHealthSchema>;
+
 export const PreviewReadyResponseSchema = z
   .object({
     type: z.literal('READY'),
     revision: z.number().int().nonnegative(),
-    health: z
-      .object({
-        reactMounted: z.literal(true),
-        builderRuntimeProvider: z.literal(true),
-        protocolVersion: z.literal(2),
-      })
-      .strict()
-      .optional(),
+    health: PreviewReadyHealthSchema.optional(),
   })
   .strict();
 
@@ -111,6 +145,29 @@ export const PreviewApplyFailedResponseSchema = z
   })
   .strict();
 
+export const PreviewBlockHtmlAppliedResponseSchema = z
+  .object({
+    type: z.literal('BLOCK_HTML_APPLIED'),
+    revision: z.number().int().nonnegative(),
+    pageId: z.string().min(1),
+    sourceRevision: z.string().min(1),
+    renderMode: EdgeBlockRenderModeSchema,
+    blocks: z.array(PreviewBlockHtmlPatchSchema).min(1),
+  })
+  .strict();
+
+export const PreviewBlockHtmlFailedResponseSchema = z
+  .object({
+    type: z.literal('BLOCK_HTML_FAILED'),
+    revision: z.number().int().nonnegative(),
+    pageId: z.string().min(1),
+    sourceRevision: z.string().min(1).optional(),
+    renderMode: EdgeBlockRenderModeSchema,
+    blockIds: z.array(z.string().min(1)).min(1),
+    error: z.string().min(1),
+  })
+  .strict();
+
 export const PreviewElementClickedResponseSchema = z
   .object({
     type: z.literal('ELEMENT_CLICKED'),
@@ -206,6 +263,8 @@ export const PreviewResponseSchema = z.discriminatedUnion('type', [
   PreviewReadyResponseSchema,
   PreviewAppliedResponseSchema,
   PreviewApplyFailedResponseSchema,
+  PreviewBlockHtmlAppliedResponseSchema,
+  PreviewBlockHtmlFailedResponseSchema,
   PreviewElementClickedResponseSchema,
   PreviewErrorResponseSchema,
   PreviewBlockRectResponseSchema,

package/src/storefront-initial-data-html.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from 'bun:test';
 import {
   assertSingleInitialDataScript,
   buildPlainInitialDataScript,
+  buildWrappedStorefrontInitialDataScript,
   countInitialDataScripts,
   findInitialDataPayload,
   injectPreviewInitialData,
@@ -70,4 +71,11 @@ describe('storefront-initial-data-html', () => {
     const stripped = stripAllInitialDataScripts(`${wrapped}${legacy}`);
     expect(stripped).not.toContain('__SHOPPEX_INITIAL__');
   });
+
+  it('marks wrapped initial data as a deployed theme artifact on friendly storefront paths', () => {
+    const script = buildWrappedStorefrontInitialDataScript('{"store":{"slug":"demo-shop"}}', /^\/themes-live\//);
+
+    expect(script).toContain('window.__SHOPPEX_DEPLOYED_THEME_ARTIFACT__=true');
+    expect(script).toContain('window.__SHOPPEX_INITIAL__={"store":{"slug":"demo-shop"}}');
+  });
 });

package/src/storefront-initial-data-html.ts

@@ -66,7 +66,7 @@ export function buildWrappedStorefrontInitialDataScript(
 ): string {
   return [
     '<!--shoppex-initial-data:start--><script>(function(){',
-    'if(typeof window!=="undefined"){var path=window.location.pathname||"";',
+    'if(typeof window!=="undefined"){window.__SHOPPEX_DEPLOYED_THEME_ARTIFACT__=true;var path=window.location.pathname||"";',
     `if(${deployedThemeEntryPathPattern}.test(path)){window.__SHOPPEX_DEPLOYED_THEME_ARTIFACT_PATH__=path;window.history.replaceState(window.history.state,"","/"+window.location.search+window.location.hash);}}`,
     `window.__SHOPPEX_INITIAL__=${serialized};})();</script><!--shoppex-initial-data:end-->`,
   ].join('');

package/src/theme-schemes.ts

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