@akinon/theme-contract 2.0.35

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @akinon/theme-contract
+
+## 2.0.35
+
+### Patch Changes
+
+- 8dca03f2: ZERO-4663: introduce shared wire contract for theme editor and storefront
+
+  New `@akinon/theme-contract` package: shared wire types, versioned postMessage envelope (`protocolVersion`), runtime validation (`parseThemeMessage`) and origin helpers. `@akinon/pz-theme` now routes all designer postMessage traffic through an origin-guarded `editor-bridge` — inbound designer messages are validated against the editor-origin allowlist (`NEXT_PUBLIC_THEME_EDITOR_ORIGINS`, localhost auto-trusted outside production) and nothing is posted to `'*'` anymore.

package/README.md

@@ -0,0 +1,73 @@
+# @akinon/theme-contract
+
+Shared wire contract between the theme editor (`pz-dynamic-widget`) and the storefront renderer (`@akinon/pz-theme`). Single source of truth for:
+
+- **Theme wire types** — `Theme`, `ThemePlaceholder`, `ThemeSection`, `ThemeBlock`, `ThemeDataSource`, `NativeWidgetConfig`, `PageContextDiscovery`. Structure is typed strictly; `properties`/`styles`/`value` payloads stay open so the two repos can evolve field content without a lockstep release.
+- **postMessage protocol** — the `ThemeMessage` envelope with `protocolVersion`, plus the full directional type unions (`EDITOR_TO_PREVIEW_MESSAGE_TYPES`, `PREVIEW_TO_EDITOR_MESSAGE_TYPES`).
+- **Runtime validation** — `parseThemeMessage(event.data)` separates contract traffic from window noise and surfaces cross-repo drift (unknown types, version mismatches) instead of silently ignoring it. Content-level validation stays in `@akinon/pz-theme`'s zod `theme-schema.ts`.
+- **Origin helpers** — `safeOrigin`, `parseOriginList`, `createOriginGuard` so both sides derive and enforce the trust boundary the same way. Never post to `'*'`; never accept a designer message without checking `event.origin` first.
+
+## Installation
+
+Inside the pz-next monorepo the package resolves through Yarn workspaces. External consumers (the theme editor):
+
+```bash
+pnpm add @akinon/theme-contract
+```
+
+## Usage
+
+Sending (either side):
+
+```ts
+import { stampThemeMessage } from '@akinon/theme-contract';
+
+targetWindow.postMessage(
+  stampThemeMessage({ type: 'UPDATE_THEME', data: { theme } }),
+  targetOrigin
+);
+```
+
+Receiving:
+
+```ts
+import { parseThemeMessage } from '@akinon/theme-contract';
+
+window.addEventListener('message', (event) => {
+  if (!originGuard.isTrusted(event.origin)) return; // trust FIRST
+  const parsed = parseThemeMessage(event.data);
+  if (!parsed.ok) return; // parsed.reason / parsed.type for diagnostics
+  if (parsed.versionMismatch) {
+    console.warn(`theme-contract version mismatch (remote ${parsed.remoteVersion})`);
+  }
+  handle(parsed.message);
+});
+```
+
+Renderer-side origin guard (see `@akinon/pz-theme` `src/editor-bridge.ts` for the wired-up singleton):
+
+```ts
+import { createOriginGuard, parseOriginList } from '@akinon/theme-contract';
+
+const guard = createOriginGuard({
+  allowedOrigins: parseOriginList(process.env.NEXT_PUBLIC_THEME_EDITOR_ORIGINS),
+  allowLocalDev: process.env.NODE_ENV !== 'production'
+});
+```
+
+## Versioning
+
+`THEME_CONTRACT_PROTOCOL_VERSION` bumps ONLY on a breaking change to the envelope or an existing message's data shape. Adding a message type is not breaking — unknown types are reported and skipped. Messages from pre-contract builds (no `protocolVersion` field) are accepted as version 0.
+
+## API Reference
+
+| Export | Kind | Description |
+| --- | --- | --- |
+| `THEME_CONTRACT_PROTOCOL_VERSION` | const | Current protocol version |
+| `stampThemeMessage(message)` | fn | Stamp an outbound envelope, preserving legacy top-level fields |
+| `createThemeMessage(type, data?)` | fn | Build and stamp a `{ type, data }` envelope |
+| `parseThemeMessage(raw)` | fn | Validate inbound `event.data`; never throws |
+| `isKnownThemeMessageType(type)` | fn | Type-union membership check |
+| `safeOrigin(url)` | fn | `scheme://host:port` or `null` |
+| `parseOriginList(raw)` | fn | Comma/whitespace-separated env list → origins |
+| `createOriginGuard(options)` | fn | Allowlist (+ optional localhost dev) origin check |

package/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@akinon/theme-contract",
+  "version": "2.0.35",
+  "description": "Shared wire contract between the theme editor (pz-dynamic-widget) and the storefront renderer (@akinon/pz-theme): theme types, postMessage envelope, runtime validation and origin helpers.",
+  "license": "MIT",
+  "main": "src/index.ts",
+  "devDependencies": {
+    "typescript": "^5.2.2"
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './types';
+export * from './messages';
+export * from './validate';
+export * from './origin';

package/src/messages.ts

@@ -0,0 +1,144 @@
+/**
+ * The postMessage protocol between the theme editor (parent window) and the
+ * preview iframe (storefront). Both sides stamp outbound messages
+ * (`stampThemeMessage`) and validate inbound ones (`parseThemeMessage`, see
+ * validate.ts), so a renamed/removed type or an incompatible protocol
+ * version surfaces as a warning instead of a silently dead feature.
+ */
+
+/**
+ * Bump ONLY on a breaking change to the envelope or to an existing message's
+ * data shape. Adding a new message type is NOT breaking — unknown types are
+ * reported and skipped, never fatal.
+ */
+export const THEME_CONTRACT_PROTOCOL_VERSION = 1;
+
+/**
+ * Version attributed to messages sent by pre-contract builds (no
+ * `protocolVersion` field). They keep working — the field is additive.
+ */
+export const LEGACY_PROTOCOL_VERSION = 0;
+
+/** Messages the editor sends into the preview iframe. */
+export const EDITOR_TO_PREVIEW_MESSAGE_TYPES = [
+  'LOAD_THEME',
+  'UPDATE_THEME',
+  'SELECT_SECTION',
+  'SELECT_BLOCK',
+  'SELECT_BLOCK_FROM_PREVIEW',
+  'CLEAR_SELECTION',
+  'DESELECT',
+  'CHANGE_BREAKPOINT',
+  'SET_THEME_EDITOR_COOKIE',
+  'SET_PREVIEW_INTERACTION_MODE',
+  'SET_BASKET_VIEW_MODE',
+  'OPEN_MINI_BASKET',
+  'SCROLL_TO_SECTION',
+  'SCROLL_TO_BLOCK',
+  'LOCALE_UPDATE',
+  'LOAD_FONT',
+  'LOAD_CUSTOM_FONT',
+  'PRODUCT_PICKER_SEARCH',
+  'PRODUCT_PICKER_RESOLVE_URL',
+  'PRODUCT_PICKER_GET_PRODUCT'
+] as const;
+
+/** Messages the preview iframe sends up to the editor. */
+export const PREVIEW_TO_EDITOR_MESSAGE_TYPES = [
+  'IFRAME_READY',
+  'PLACEHOLDERS_AVAILABLE',
+  'REGISTER_NATIVE_WIDGETS',
+  'UNREGISTER_NATIVE_SECTION',
+  'UPDATE_SECTION_BLOCKS',
+  'SELECT_SECTION',
+  'SELECT_BLOCK',
+  'MOVE_SECTION_UP',
+  'MOVE_SECTION_DOWN',
+  'DUPLICATE_SECTION',
+  'TOGGLE_SECTION_VISIBILITY',
+  'SET_SECTION_VISIBILITY',
+  'DELETE_SECTION',
+  'RENAME_SECTION',
+  'MOVE_BLOCK_UP',
+  'MOVE_BLOCK_DOWN',
+  'DUPLICATE_BLOCK',
+  'TOGGLE_BLOCK_VISIBILITY',
+  'SET_BLOCK_VISIBILITY',
+  'DELETE_BLOCK',
+  'DELETE_BLOCK_FROM_PARENT',
+  'RENAME_BLOCK',
+  'BLOCK_ACTION',
+  'UPDATE_BLOCK_VALUE',
+  'PRODUCT_PICKER_RESPONSE',
+  'PAGE_CONTEXT_DISCOVERY',
+  'PREVIEW_AUTH_STATE',
+  'ROUTE_CHANGE_START',
+  'ROUTE_CHANGE_COMPLETE',
+  // Bidirectional: the preview reports click-selection and its available
+  // locales up to the editor with the same types the editor uses downward.
+  'SELECT_BLOCK_FROM_PREVIEW',
+  'LOCALE_UPDATE'
+] as const;
+
+export type EditorToPreviewMessageType =
+  typeof EDITOR_TO_PREVIEW_MESSAGE_TYPES[number];
+export type PreviewToEditorMessageType =
+  typeof PREVIEW_TO_EDITOR_MESSAGE_TYPES[number];
+export type ThemeMessageType =
+  | EditorToPreviewMessageType
+  | PreviewToEditorMessageType;
+
+const KNOWN_MESSAGE_TYPES: ReadonlySet<string> = new Set([
+  ...EDITOR_TO_PREVIEW_MESSAGE_TYPES,
+  ...PREVIEW_TO_EDITOR_MESSAGE_TYPES
+]);
+
+export function isKnownThemeMessageType(
+  type: string
+): type is ThemeMessageType {
+  return KNOWN_MESSAGE_TYPES.has(type);
+}
+
+/**
+ * The envelope. Kept intentionally backward compatible with the
+ * pre-contract shape `{ type, data }` — `protocolVersion` is additive, so
+ * an old peer simply ignores it.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface ThemeMessage<TData = any> {
+  type: ThemeMessageType;
+  data?: TData;
+  protocolVersion?: number;
+}
+
+/**
+ * Outbound message shape accepted by the send helpers. The index signature
+ * exists because several pre-contract messages carry their payload as extra
+ * TOP-LEVEL fields instead of `data` (ROUTE_CHANGE_*, BLOCK_ACTION, the
+ * preview-click SELECT_SECTION) — senders pass them through unchanged so
+ * older peers keep working. New messages must use `data`.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export interface OutboundThemeMessage<TData = any> {
+  type: ThemeMessageType;
+  data?: TData;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  [legacyField: string]: any;
+}
+
+/** Stamp an outbound message, preserving legacy top-level fields. */
+export function stampThemeMessage<TData>(
+  message: OutboundThemeMessage<TData>
+): OutboundThemeMessage<TData> {
+  return { ...message, protocolVersion: THEME_CONTRACT_PROTOCOL_VERSION };
+}
+
+/** Build and stamp a `{ type, data }` message. */
+export function createThemeMessage<TData>(
+  type: ThemeMessageType,
+  data?: TData
+): ThemeMessage<TData> {
+  return data === undefined
+    ? { type, protocolVersion: THEME_CONTRACT_PROTOCOL_VERSION }
+    : { type, data, protocolVersion: THEME_CONTRACT_PROTOCOL_VERSION };
+}

package/src/origin.ts

@@ -0,0 +1,80 @@
+/**
+ * Origin helpers for both sides of the editor ⇄ preview trust boundary.
+ *
+ * The editor derives the preview's origin from the SAME `previewUrl` it sets
+ * as the iframe `src`. The preview derives the editor's origin from an
+ * explicit allowlist (plus a localhost fallback for development) — NEVER
+ * from whoever happens to be framing it: `document.referrer` alone would
+ * trust any page that embeds the storefront in an iframe.
+ */
+
+/**
+ * The origin (`scheme://host:port`) of a URL, or `null` when the URL is
+ * empty/unparseable. Both sides use this so they can never disagree on how
+ * an origin is derived.
+ */
+export function safeOrigin(url: string | null | undefined): string | null {
+  if (!url) return null;
+  try {
+    return new URL(url).origin;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Parse a comma/whitespace-separated origin list (e.g. the
+ * `NEXT_PUBLIC_THEME_EDITOR_ORIGINS` env var) into normalized origins.
+ * Unparseable entries are dropped.
+ */
+export function parseOriginList(raw: string | null | undefined): string[] {
+  if (!raw) return [];
+  const origins = raw
+    .split(/[\s,]+/)
+    .map((entry) => safeOrigin(entry.trim()))
+    .filter((origin): origin is string => origin !== null);
+  return Array.from(new Set(origins));
+}
+
+const LOCAL_DEV_ORIGIN_PATTERN =
+  /^https?:\/\/(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/;
+
+export function isLocalDevOrigin(origin: string): boolean {
+  return LOCAL_DEV_ORIGIN_PATTERN.test(origin);
+}
+
+export interface OriginGuard {
+  /** Explicitly allowed origins (normalized). */
+  readonly allowedOrigins: readonly string[];
+  isTrusted(origin: string): boolean;
+}
+
+export interface OriginGuardOptions {
+  allowedOrigins: string[];
+  /**
+   * Additionally trust localhost origins — for development, where the
+   * editor runs on an arbitrary local port and no allowlist is configured.
+   * Must be OFF in production.
+   */
+  allowLocalDev?: boolean;
+}
+
+export function createOriginGuard(options: OriginGuardOptions): OriginGuard {
+  const allowedOrigins = Array.from(
+    new Set(
+      options.allowedOrigins
+        .map((entry) => safeOrigin(entry))
+        .filter((origin): origin is string => origin !== null)
+    )
+  );
+  const allowLocalDev = Boolean(options.allowLocalDev);
+
+  return {
+    allowedOrigins,
+    isTrusted(origin: string): boolean {
+      if (!origin) return false;
+      if (allowedOrigins.includes(origin)) return true;
+      return allowLocalDev && isLocalDevOrigin(origin);
+    }
+  };
+}

package/src/types.ts

@@ -0,0 +1,227 @@
+/**
+ * Wire-level theme types shared between the theme editor (pz-dynamic-widget)
+ * and the preview/storefront renderer (@akinon/pz-theme).
+ *
+ * These describe what actually travels over postMessage and what the
+ * renderer consumes — the STRUCTURE is typed strictly (ids, nesting,
+ * placeholders, data sources), while per-section/per-block payloads
+ * (`properties`, `styles`, `value`) stay open so the two sides can evolve
+ * field content without a lockstep release. The editor's stricter internal
+ * types are assignable to these.
+ */
+
+export type ThemeDataSourceType =
+  | 'collection'
+  | 'api'
+  | 'static'
+  | 'page-context';
+
+export interface ThemeDataSource {
+  id: string;
+  name: string;
+  type: ThemeDataSourceType;
+  details: {
+    collection?: {
+      pk: number;
+      slug?: string;
+      productLimit: number;
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      products?: Record<string, any>[];
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      data?: Record<string, any> | Record<string, any>[];
+    };
+    api?: {
+      url: string;
+      method: string;
+      headers: Record<string, string>;
+      body: Record<string, string>;
+    };
+    static?: {
+      name: string;
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      data: Record<string, any>[];
+    };
+    pageContext?: {
+      pageType: string;
+      rootPath: string;
+    };
+  };
+}
+
+export interface ThemeBlock {
+  id: string;
+  type: string;
+  label: string;
+  styleSourceId?: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  value?: any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  properties?: Record<string, any>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  styles?: Record<string, any>;
+  order?: number;
+  hidden?: boolean;
+  locked?: boolean;
+  /** Nested blocks (group/iterator containers). */
+  blocks?: ThemeBlock[];
+  isIterator?: boolean;
+  iteratorDataPath?: string;
+}
+
+export interface ThemeSectionEditorConfig {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  properties?: any[];
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  styles?: any[];
+  blocks?: Record<
+    string,
+    {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      properties?: any[];
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      styles?: any[];
+    }
+  >;
+  hasContent?: boolean;
+}
+
+export interface ThemeSection {
+  id: string;
+  type: string;
+  label: string;
+  name?: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  properties?: Record<string, any>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  styles?: Record<string, any>;
+  blocks: ThemeBlock[];
+  order: number;
+  hidden?: boolean;
+  locked?: boolean;
+  /** Reference to an entry in `Theme.dataSources`. */
+  dataSourceId?: string;
+  /**
+   * Renderer-side convenience: the resolved data source for `dataSourceId`.
+   * Never authored by the editor — the preview wrapper attaches it before
+   * handing sections to section renderers.
+   */
+  dataSource?: ThemeDataSource | null;
+  isNew?: boolean;
+  isModified?: boolean;
+  editorConfig?: ThemeSectionEditorConfig;
+}
+
+export interface ThemePlaceholder {
+  id: string;
+  slug: string;
+  name?: string;
+  sections: ThemeSection[];
+  isModified?: boolean;
+}
+
+export interface ThemeCustomFontSource {
+  dataUrl: string;
+  format: string;
+}
+
+export interface ThemeCustomFont {
+  name: string;
+  sources: ThemeCustomFontSource[];
+}
+
+export interface ThemeTypographyVariant {
+  key: string;
+  label?: string;
+  labelKey?: string;
+  fontFamily: string;
+  fontWeight: string;
+  fontSize: number;
+  color: string;
+  styles: string[];
+}
+
+export interface ThemeSettings {
+  colors?: {
+    primary?: string;
+    secondary?: string;
+  };
+  typography?: ThemeTypographyVariant[];
+  customFonts?: ThemeCustomFont[];
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  [key: string]: any;
+}
+
+/** Breakpoints are editor-defined; the renderer only forwards the key. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ThemeBreakpoint = Record<string, any>;
+
+export interface Theme {
+  name?: string;
+  slug?: string;
+  settings?: ThemeSettings;
+  breakpoints?: ThemeBreakpoint[];
+  placeholders: ThemePlaceholder[];
+  dataSources?: ThemeDataSource[];
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  customPages?: Record<string, any>[];
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  stylePresets?: Record<string, any>[];
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  reusableSectionTemplates?: Record<string, any>[];
+}
+
+// ---------------------------------------------------------------------------
+// Native widget registration (preview → editor)
+// ---------------------------------------------------------------------------
+
+export interface NativeWidgetBlock {
+  id: string;
+  type: string;
+  label: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  value?: any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  properties?: Record<string, any>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  styles?: Record<string, any>;
+  locked?: boolean;
+  blocks?: NativeWidgetBlock[];
+}
+
+export interface NativeWidgetSection {
+  id: string;
+  type: string;
+  label: string;
+  blocks: NativeWidgetBlock[];
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  properties?: Record<string, any>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  styles?: Record<string, any>;
+  locked?: boolean;
+  editorConfig?: ThemeSectionEditorConfig;
+}
+
+export interface NativeWidgetConfig {
+  placeholderId: string;
+  name: string;
+  /** If false, section won't be auto-inserted when registered. Must be added via "Add Section". */
+  autoAdd?: boolean;
+  widgetSlug?: string;
+  section: NativeWidgetSection;
+}
+
+// ---------------------------------------------------------------------------
+// Page context discovery (preview → editor)
+// ---------------------------------------------------------------------------
+
+export interface PageContextDiscoveryEntry {
+  path: string;
+  kind: 'scalar' | 'array';
+  valueType: 'string' | 'number' | 'boolean' | 'null' | 'object' | 'array';
+  sample?: string;
+}
+
+export interface PageContextDiscovery {
+  roots: string[];
+  entries: PageContextDiscoveryEntry[];
+}

package/src/validate.ts

@@ -0,0 +1,90 @@
+import {
+  LEGACY_PROTOCOL_VERSION,
+  THEME_CONTRACT_PROTOCOL_VERSION,
+  ThemeMessage,
+  isKnownThemeMessageType
+} from './messages';
+
+export type ThemeMessageRejection =
+  | 'not-an-object'
+  | 'missing-type'
+  | 'unknown-type'
+  | 'invalid-data';
+
+export interface ParsedThemeMessageOk {
+  ok: true;
+  message: ThemeMessage;
+  /** Version the sender stamped; LEGACY_PROTOCOL_VERSION when absent. */
+  remoteVersion: number;
+  versionMismatch: boolean;
+}
+
+export interface ParsedThemeMessageRejected {
+  ok: false;
+  reason: ThemeMessageRejection;
+  /** Present for 'unknown-type', to make drift diagnosable. */
+  type?: string;
+}
+
+export type ParsedThemeMessage =
+  | ParsedThemeMessageOk
+  | ParsedThemeMessageRejected;
+
+/**
+ * Validate a raw `MessageEvent.data` against the contract. Never throws.
+ *
+ * This is deliberately envelope-level (shape + known type + version), not a
+ * deep per-message schema: `window` receives traffic from devtools,
+ * extensions and unrelated code, so the job here is to cheaply separate
+ * contract messages from noise and to make cross-repo drift (an unknown
+ * type, a version bump) visible to the caller instead of silently ignored.
+ * Content-level validation stays where it is today (`@akinon/pz-theme`'s
+ * zod `theme-schema.ts` on the render side).
+ *
+ * NOTE: origin trust is a separate concern — check `event.origin` FIRST
+ * (see origin.ts), then parse.
+ */
+export function parseThemeMessage(raw: unknown): ParsedThemeMessage {
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+    return { ok: false, reason: 'not-an-object' };
+  }
+
+  const candidate = raw as {
+    type?: unknown;
+    data?: unknown;
+    protocolVersion?: unknown;
+  };
+
+  if (typeof candidate.type !== 'string' || candidate.type.length === 0) {
+    return { ok: false, reason: 'missing-type' };
+  }
+
+  if (!isKnownThemeMessageType(candidate.type)) {
+    return { ok: false, reason: 'unknown-type', type: candidate.type };
+  }
+
+  // `data` is either absent, a payload object, or the legacy boolean used by
+  // SET_THEME_EDITOR_COOKIE. Anything else is a malformed frame.
+  if (
+    candidate.data !== undefined &&
+    candidate.data !== null &&
+    typeof candidate.data !== 'object' &&
+    typeof candidate.data !== 'boolean'
+  ) {
+    return { ok: false, reason: 'invalid-data' };
+  }
+
+  const remoteVersion =
+    typeof candidate.protocolVersion === 'number'
+      ? candidate.protocolVersion
+      : LEGACY_PROTOCOL_VERSION;
+
+  return {
+    ok: true,
+    message: candidate as ThemeMessage,
+    remoteVersion,
+    versionMismatch:
+      remoteVersion !== LEGACY_PROTOCOL_VERSION &&
+      remoteVersion !== THEME_CONTRACT_PROTOCOL_VERSION
+  };
+}