@shoppexio/builder-contracts 0.1.0 → 0.1.1

package/src/preview-protocol.ts

@@ -46,18 +46,53 @@ export const PreviewRequestReadyMessageSchema = z
   })
   .strict();
 
+export const InteractionModeSchema = z.enum(['edit', 'preview']);
+export type InteractionMode = z.infer<typeof InteractionModeSchema>;
+
+/**
+ * Dashboard tells the runtime which interaction mode is active:
+ *  - "edit" (default) intercepts clicks for selection.
+ *  - "preview" lets the storefront react to clicks/links normally so
+ *    a merchant can test buy-now flows or anchor links.
+ */
+export const PreviewSetInteractionModeMessageSchema = z
+  .object({
+    type: z.literal('SET_INTERACTION_MODE'),
+    mode: InteractionModeSchema,
+  })
+  .strict();
+
 export const PreviewMessageSchema = z.discriminatedUnion('type', [
   PreviewApplyStateMessageSchema,
   PreviewReloadMessageSchema,
   PreviewSelectElementMessageSchema,
   PreviewRequestReadyMessageSchema,
+  PreviewSetInteractionModeMessageSchema,
 ]);
 export type PreviewMessage = z.infer<typeof PreviewMessageSchema>;
 
+export const PreviewBootstrapOkResponseSchema = z
+  .object({
+    type: z.literal('BOOTSTRAP_OK'),
+    revision: z.number().int().nonnegative(),
+    shopSlug: z.string().min(1),
+    shopId: z.string().min(1),
+    artifactStale: z.boolean().optional(),
+  })
+  .strict();
+
 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(),
   })
   .strict();
 
@@ -84,10 +119,97 @@ export const PreviewElementClickedResponseSchema = z
   })
   .strict();
 
+export const PreviewErrorResponseSchema = z
+  .object({
+    type: z.literal('PREVIEW_ERROR'),
+    revision: z.number().int().nonnegative().optional(),
+    message: z.string().min(1),
+    stack: z.string().optional(),
+    source: z.enum(['bootstrap', 'error', 'unhandledrejection']).optional(),
+    phase: z.enum(['bootstrap', 'runtime']).optional(),
+    diagnostics: z
+      .object({
+        name: z.string().optional(),
+        filename: z.string().optional(),
+        lineno: z.number().optional(),
+        colno: z.number().optional(),
+        href: z.string().optional(),
+        referrer: z.string().optional(),
+        parentOrigin: z.string().optional(),
+        previewMode: z.string().optional(),
+        userAgent: z.string().optional(),
+        localStorage: z.enum(['available', 'blocked', 'unknown']).optional(),
+        sessionStorage: z.enum(['available', 'blocked', 'unknown']).optional(),
+        historyScrollRestoration: z.enum(['available', 'blocked', 'unknown']).optional(),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+
+/**
+ * Geometry of a block inside the preview iframe, expressed in the iframe's
+ * own coordinate space (viewport-relative). The dashboard converts these
+ * coordinates to its own overlay layer when positioning the floating
+ * toolbar / drag handle / insert affordances.
+ */
+export const PreviewRectSchema = z
+  .object({
+    top: z.number().finite(),
+    left: z.number().finite(),
+    width: z.number().finite(),
+    height: z.number().finite(),
+  })
+  .strict();
+export type PreviewRect = z.infer<typeof PreviewRectSchema>;
+
+export const PreviewBlockRectResponseSchema = z
+  .object({
+    type: z.literal('BLOCK_RECT'),
+    revision: z.number().int().nonnegative().optional(),
+    blockId: z.string().min(1),
+    rect: PreviewRectSchema.nullable(),
+  })
+  .strict();
+
+/**
+ * Preview reports a gap between two consecutive blocks that the user is
+ * hovering. The dashboard renders a "+" insert affordance there. When
+ * the user moves away from any gap, `index` is null.
+ */
+export const PreviewInserterHoverResponseSchema = z
+  .object({
+    type: z.literal('INSERTER_HOVER'),
+    revision: z.number().int().nonnegative().optional(),
+    index: z.number().int().nonnegative().nullable(),
+    rect: PreviewRectSchema.nullable(),
+  })
+  .strict();
+
+/**
+ * Inline-edit commit. The runtime captures contenteditable text on
+ * blur/Enter and sends the result back to the dashboard, which writes
+ * it to the corresponding block/content path through the store.
+ */
+export const PreviewInlineEditCommitResponseSchema = z
+  .object({
+    type: z.literal('INLINE_EDIT_COMMIT'),
+    revision: z.number().int().nonnegative().optional(),
+    blockId: z.string().min(1),
+    contentPath: z.string().min(1),
+    value: z.string(),
+  })
+  .strict();
+
 export const PreviewResponseSchema = z.discriminatedUnion('type', [
+  PreviewBootstrapOkResponseSchema,
   PreviewReadyResponseSchema,
   PreviewAppliedResponseSchema,
   PreviewApplyFailedResponseSchema,
   PreviewElementClickedResponseSchema,
+  PreviewErrorResponseSchema,
+  PreviewBlockRectResponseSchema,
+  PreviewInserterHoverResponseSchema,
+  PreviewInlineEditCommitResponseSchema,
 ]);
 export type PreviewResponse = z.infer<typeof PreviewResponseSchema>;

package/src/preview-session-resolve.ts

@@ -0,0 +1,34 @@
+import * as z from 'zod/v4';
+import { BuilderSettingsSchema } from './builder-settings.ts';
+
+export const BuilderPreviewResolveDataSchema = z
+  .object({
+    sessionId: z.string().min(1),
+    shopId: z.string().min(1),
+    shopSlug: z.string().min(1),
+    themeId: z.string().min(1),
+    artifactPrefix: z.string().min(1),
+    builderSettings: BuilderSettingsSchema,
+    artifactStale: z.boolean().optional(),
+    sourceRevision: z.string().nullable().optional(),
+  })
+  .strict();
+
+export type BuilderPreviewResolveData = z.infer<typeof BuilderPreviewResolveDataSchema>;
+
+export const BuilderPreviewResolveResponseSchema = z
+  .object({
+    status: z.number(),
+    data: BuilderPreviewResolveDataSchema.nullable(),
+    error: z.string().nullable(),
+  })
+  .strict();
+
+export type BuilderPreviewResolveResponse = z.infer<typeof BuilderPreviewResolveResponseSchema>;
+
+export function parseBuilderPreviewResolveResponse(
+  value: unknown,
+): BuilderPreviewResolveResponse | null {
+  const parsed = BuilderPreviewResolveResponseSchema.safeParse(value);
+  return parsed.success ? parsed.data : null;
+}

package/src/preview-trusted-origins.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'bun:test';
+import { isTrustedPreviewParentOrigin } from './preview-trusted-origins.ts';
+
+describe('isTrustedPreviewParentOrigin', () => {
+  it('accepts production dashboard and app origins', () => {
+    expect(isTrustedPreviewParentOrigin('https://dashboard.shoppex.io')).toBe(true);
+    expect(isTrustedPreviewParentOrigin('https://app.shoppex.io')).toBe(true);
+    expect(isTrustedPreviewParentOrigin('https://shoppex-dashboard.vercel.app')).toBe(true);
+  });
+
+  it('accepts local and preview dashboard hosts', () => {
+    expect(isTrustedPreviewParentOrigin('http://localhost:3100')).toBe(true);
+    expect(isTrustedPreviewParentOrigin('http://[::1]:3100')).toBe(true);
+    expect(isTrustedPreviewParentOrigin('https://dashboard.shoppex.test')).toBe(true);
+  });
+
+  it('rejects unknown origins', () => {
+    expect(isTrustedPreviewParentOrigin('https://evil.example')).toBe(false);
+    expect(isTrustedPreviewParentOrigin('https://evil.vercel.app')).toBe(false);
+    expect(isTrustedPreviewParentOrigin('https://shoppex-dashboard.evil.vercel.app')).toBe(false);
+    expect(isTrustedPreviewParentOrigin('https://preview.vercel.run')).toBe(false);
+    expect(isTrustedPreviewParentOrigin('ftp://localhost:3000')).toBe(false);
+  });
+});

package/src/preview-trusted-origins.ts

@@ -0,0 +1,35 @@
+export const TRUSTED_PREVIEW_PARENT_ORIGINS = [
+  'https://app.shoppex.io',
+  'https://dashboard.shoppex.io',
+  'https://dashboard.shoppex.test',
+  'https://shoppex-dashboard.vercel.app',
+  'http://localhost:3000',
+  'http://127.0.0.1:3000',
+] as const;
+
+export type TrustedPreviewParentOrigin = (typeof TRUSTED_PREVIEW_PARENT_ORIGINS)[number];
+
+export function isTrustedPreviewParentOrigin(origin: string): boolean {
+  if (TRUSTED_PREVIEW_PARENT_ORIGINS.includes(origin as TrustedPreviewParentOrigin)) {
+    return true;
+  }
+
+  try {
+    const url = new URL(origin);
+    const hostname = url.hostname.toLowerCase();
+    const isHttp = url.protocol === 'http:' || url.protocol === 'https:';
+    return (
+      isHttp
+      && (
+        hostname === 'dashboard.shoppex.test'
+        || hostname === 'localhost'
+        || hostname === '127.0.0.1'
+        || hostname === '::1'
+        || hostname === '[::1]'
+        || hostname.endsWith('.localhost')
+      )
+    );
+  } catch {
+    return false;
+  }
+}

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

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'bun:test';
+import {
+  assertSingleInitialDataScript,
+  buildPlainInitialDataScript,
+  countInitialDataScripts,
+  findInitialDataPayload,
+  injectPreviewInitialData,
+  stripAllInitialDataScripts,
+} from './storefront-initial-data-html.ts';
+
+const samplePayload = {
+  shopId: 'shop_1',
+  shopSlug: 'demo-shop',
+  builderSettings: {
+    version: 2 as const,
+    revision: 3,
+    theme: {
+      content: {},
+      layout: {},
+      tokens_override: {},
+      style_slots: {},
+    },
+  },
+  storefrontSeed: {
+    store: { name: 'Demo' },
+    products: [],
+  },
+};
+
+describe('storefront-initial-data-html', () => {
+  it('strips duplicate initial-data scripts and injects one slug', () => {
+    const html = [
+      '<html><head></head><body>',
+      '<script>window.__SHOPPEX_INITIAL__={"store":{"id":"shop_1"}};</script>',
+      '<script>window.__SHOPPEX_INITIAL__={"store":{"slug":"stale"}};</script>',
+      '</body></html>',
+    ].join('');
+
+    const next = injectPreviewInitialData(html, samplePayload);
+    expect(countInitialDataScripts(next)).toBe(1);
+    assertSingleInitialDataScript(next, 'demo-shop');
+    expect(findInitialDataPayload(next)?.store).toMatchObject({
+      id: 'shop_1',
+      slug: 'demo-shop',
+    });
+  });
+
+  it('throws when assert sees zero or multiple scripts', () => {
+    expect(() => assertSingleInitialDataScript('<html></html>', 'demo-shop')).toThrow();
+    const html = [
+      buildPlainInitialDataScript({ store: { slug: 'a' } }),
+      buildPlainInitialDataScript({ store: { slug: 'b' } }),
+    ].join('');
+    expect(() => assertSingleInitialDataScript(html, 'a')).toThrow(/exactly one/);
+  });
+
+  it('stripAllInitialDataScripts removes wrapped and legacy blocks', () => {
+    const wrapped = '<!--shoppex-initial-data:start--><script>window.__SHOPPEX_INITIAL__={};</script><!--shoppex-initial-data:end-->';
+    const legacy = '<script>window.__SHOPPEX_INITIAL__={};</script>';
+    const stripped = stripAllInitialDataScripts(`${wrapped}${legacy}`);
+    expect(stripped).not.toContain('__SHOPPEX_INITIAL__');
+  });
+});

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

@@ -0,0 +1,112 @@
+import type { PreviewBootPayload } from './preview-boot.ts';
+import { mergePreviewBootIntoInitialData } from './preview-boot.ts';
+
+export const HTML_INITIAL_BLOCK_PATTERN =
+  /<!--shoppex-initial-data:start--><script>\(function\(\)\{[\s\S]*?window\.__SHOPPEX_INITIAL__=([\s\S]*?)(?=;\}\)\(\);<\/script><!--shoppex-initial-data:end-->);\}\)\(\);<\/script><!--shoppex-initial-data:end-->/;
+
+export const LEGACY_HTML_INITIAL_PATTERN =
+  /<script>\s*window\.__SHOPPEX_INITIAL__=([\s\S]*?)<\/script>/;
+
+const HTML_INITIAL_BLOCK_GLOBAL_PATTERN = new RegExp(HTML_INITIAL_BLOCK_PATTERN.source, 'g');
+const LEGACY_HTML_INITIAL_GLOBAL_PATTERN = new RegExp(LEGACY_HTML_INITIAL_PATTERN.source, 'g');
+
+const CLOSING_HEAD_PATTERN = /<\/head>/i;
+
+export type InitialDataScriptMatch = {
+  json: string;
+};
+
+export function stripAllInitialDataScripts(html: string): string {
+  return html
+    .replace(HTML_INITIAL_BLOCK_GLOBAL_PATTERN, '')
+    .replace(LEGACY_HTML_INITIAL_GLOBAL_PATTERN, '');
+}
+
+export function findInitialDataScriptJson(html: string): InitialDataScriptMatch | null {
+  const blockMatch = html.match(HTML_INITIAL_BLOCK_PATTERN);
+  if (blockMatch?.[1]) {
+    return { json: blockMatch[1] };
+  }
+
+  const legacyMatch = html.match(LEGACY_HTML_INITIAL_PATTERN);
+  if (legacyMatch?.[1]) {
+    return { json: legacyMatch[1] };
+  }
+
+  return null;
+}
+
+export function findInitialDataPayload(html: string): Record<string, unknown> | null {
+  const match = findInitialDataScriptJson(html);
+  if (!match) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(match.json.replace(/;\s*$/, '')) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+export function countInitialDataScripts(html: string): number {
+  const blockMatches = html.match(HTML_INITIAL_BLOCK_GLOBAL_PATTERN)?.length ?? 0;
+  const stripped = html.replace(HTML_INITIAL_BLOCK_GLOBAL_PATTERN, '');
+  const legacyMatches = stripped.match(LEGACY_HTML_INITIAL_GLOBAL_PATTERN)?.length ?? 0;
+  return blockMatches + legacyMatches;
+}
+
+export function buildPlainInitialDataScript(initialData: Record<string, unknown>): string {
+  return `<script>window.__SHOPPEX_INITIAL__=${safeJson(initialData)};</script>`;
+}
+
+export function buildWrappedStorefrontInitialDataScript(
+  serialized: string,
+  deployedThemeEntryPathPattern: RegExp,
+): string {
+  return [
+    '<!--shoppex-initial-data:start--><script>(function(){',
+    'if(typeof window!=="undefined"){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('');
+}
+
+export function injectPlainInitialDataBeforeHeadClose(html: string, script: string): string {
+  if (CLOSING_HEAD_PATTERN.test(html)) {
+    return html.replace(CLOSING_HEAD_PATTERN, `${script}\n</head>`);
+  }
+  return `${script}\n${html}`;
+}
+
+export function injectPreviewInitialData(html: string, payload: PreviewBootPayload): string {
+  const withoutScripts = stripAllInitialDataScripts(html);
+  const initialData = mergePreviewBootIntoInitialData(payload);
+  const script = buildPlainInitialDataScript(initialData);
+  return injectPlainInitialDataBeforeHeadClose(withoutScripts, script);
+}
+
+export function assertSingleInitialDataScript(html: string, expectedSlug: string): void {
+  const count = countInitialDataScripts(html);
+  if (count !== 1) {
+    throw new Error(`Expected exactly one initial-data script, found ${count}`);
+  }
+
+  const payload = findInitialDataPayload(html);
+  const store = payload?.store;
+  const slug = typeof store === 'object' && store !== null && !Array.isArray(store)
+    ? (store as Record<string, unknown>).slug
+    : null;
+
+  if (typeof slug !== 'string' || slug.trim().length === 0) {
+    throw new Error('Initial-data script is missing store.slug');
+  }
+
+  if (slug.trim() !== expectedSlug) {
+    throw new Error(`Initial-data slug mismatch: expected ${expectedSlug}, got ${slug}`);
+  }
+}
+
+export function safeJson(value: unknown): string {
+  return JSON.stringify(value).replace(/</g, '\\u003c');
+}

package/src/style-slots.ts

@@ -43,7 +43,7 @@ export const FontWeightSchema = z.union([
 ]);
 export type FontWeight = z.infer<typeof FontWeightSchema>;
 
-export const StyleSlotIdSchema = z.enum([
+export const CoreStyleSlotIdSchema = z.enum([
   'button.radius',
   'button.background',
   'button.foreground',
@@ -69,39 +69,104 @@ export const StyleSlotIdSchema = z.enum([
   'typography.heading.weight',
   'typography.body.size',
 ]);
-export type StyleSlotId = z.infer<typeof StyleSlotIdSchema>;
+export type CoreStyleSlotId = z.infer<typeof CoreStyleSlotIdSchema>;
 
-export const CORE_STYLE_SLOT_IDS = StyleSlotIdSchema.options;
+export const ThemeStyleSlotIdSchema = z
+  .string()
+  .regex(/^theme\.[a-z0-9][a-z0-9._-]*$/, 'Expected a theme-scoped style slot id');
+export type ThemeStyleSlotId = `theme.${string}`;
+
+export const StyleSlotIdSchema = z.union([CoreStyleSlotIdSchema, ThemeStyleSlotIdSchema]);
+export type StyleSlotId = CoreStyleSlotId | ThemeStyleSlotId;
+
+export const CORE_STYLE_SLOT_IDS = CoreStyleSlotIdSchema.options;
+
+export const ThemeStyleSlotValueSchema = z.union([
+  ColorSchema,
+  ResponsiveNumberSchema,
+  ResponsiveStringSchema,
+  FontWeightSchema,
+  z.string().min(1),
+  z.number().finite(),
+  z.boolean(),
+]);
+export type ThemeStyleSlotValue = z.infer<typeof ThemeStyleSlotValueSchema>;
+
+export type StyleSlotValue =
+  | Color
+  | ResponsiveNumber
+  | ResponsiveString
+  | FontWeight
+  | string
+  | number
+  | boolean;
+
+const CORE_STYLE_SLOT_SCHEMAS: Record<CoreStyleSlotId, z.ZodType<unknown>> = {
+  'button.radius': ResponsiveNumberSchema,
+  'button.background': ColorSchema,
+  'button.foreground': ColorSchema,
+  'button.border': ColorSchema,
+  'button.font.weight': FontWeightSchema,
+  'input.radius': ResponsiveNumberSchema,
+  'input.height': ResponsiveNumberSchema,
+  'input.border': ColorSchema,
+  'input.background': ColorSchema,
+  'input.foreground': ColorSchema,
+  'card.radius': ResponsiveNumberSchema,
+  'card.background': ColorSchema,
+  'card.border': ColorSchema,
+  'section.padding.y': ResponsiveNumberSchema,
+  'section.padding.x': ResponsiveNumberSchema,
+  'container.width': ResponsiveNumberSchema,
+  'color.primary': ColorSchema,
+  'color.accent': ColorSchema,
+  'color.background': ColorSchema,
+  'color.foreground': ColorSchema,
+  'color.muted': ColorSchema,
+  'link.color': ColorSchema,
+  'typography.heading.weight': FontWeightSchema,
+  'typography.body.size': ResponsiveNumberSchema,
+};
+
+export type StyleSlots = Partial<Record<StyleSlotId, StyleSlotValue>>;
 
 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>;
+  .record(z.string().min(1), z.unknown())
+  .superRefine((slots, ctx) => {
+    for (const [slotId, value] of Object.entries(slots)) {
+      const coreSlotId = CoreStyleSlotIdSchema.safeParse(slotId);
+      if (coreSlotId.success) {
+        const parsedValue = CORE_STYLE_SLOT_SCHEMAS[coreSlotId.data].safeParse(value);
+        if (!parsedValue.success) {
+          ctx.addIssue({
+            code: 'custom',
+            path: [slotId],
+            message: `Invalid value for core style slot "${slotId}"`,
+          });
+        }
+        continue;
+      }
+
+      const themeSlotId = ThemeStyleSlotIdSchema.safeParse(slotId);
+      if (!themeSlotId.success) {
+        ctx.addIssue({
+          code: 'custom',
+          path: [slotId],
+          message: `Unknown style slot "${slotId}"`,
+        });
+        continue;
+      }
+
+      const parsedThemeValue = ThemeStyleSlotValueSchema.safeParse(value);
+      if (!parsedThemeValue.success) {
+        ctx.addIssue({
+          code: 'custom',
+          path: [slotId],
+          message: `Invalid value for theme style slot "${slotId}"`,
+        });
+      }
+    }
+  }) as z.ZodType<StyleSlots>;
 
 export const StyleSlotDefaultsSchema = StyleSlotsSchema;
 export type StyleSlotDefaults = StyleSlots;