@shoppexio/builder-runtime 0.1.0 → 0.1.2

package/src/layout.ts

@@ -1,4 +1,17 @@
-import type { BlockInstance, BuilderSettings, PageLayout, ThemeManifest } from '@shoppex/builder-contracts';
+import {
+  getThemePageBlockOrderFromManifest as resolveThemePageBlockOrder,
+  type BlockInstance,
+  type BuilderSettings,
+  type PageLayout,
+  type ThemeManifest,
+  type ThemePageBlockOrderPage,
+} from '@shoppex/builder-contracts';
+
+export type ThemePageBlockOrderManifest = {
+  pages?: Record<string, ThemePageBlockOrderPage>;
+};
+
+export { resolveThemePageBlockOrder as getThemePageBlockOrderFromManifest };
 
 export function getPageLayout(settings: BuilderSettings, pageId: string): PageLayout {
   return settings.theme.layout[pageId] ?? { blocks: [] };

package/src/preview-fixtures.ts

@@ -0,0 +1,56 @@
+export type BuilderPreviewReview = {
+  id: string;
+  author: string | null;
+  comment: string | null;
+  rating: number | null;
+  created_at: string;
+  is_automated?: boolean;
+};
+
+export type BuilderPreviewFaqItem = {
+  question: string;
+  answer: string;
+};
+
+export const BUILDER_PREVIEW_REVIEWS: BuilderPreviewReview[] = [
+  {
+    id: 'preview-review-1',
+    author: 'Alex M.',
+    comment: 'Instant delivery and clear instructions. Would buy again.',
+    rating: 5,
+    created_at: '2026-04-12T10:00:00.000Z',
+  },
+  {
+    id: 'preview-review-2',
+    author: 'Jamie R.',
+    comment: 'Support answered quickly when I had a setup question.',
+    rating: 5,
+    created_at: '2026-04-03T14:30:00.000Z',
+  },
+  {
+    id: 'preview-review-3',
+    author: 'Taylor S.',
+    comment: 'Smooth checkout experience and exactly what was advertised.',
+    rating: 4,
+    created_at: '2026-03-22T09:15:00.000Z',
+  },
+];
+
+export function getBuilderPreviewReviewFixtures<T = BuilderPreviewReview>(): T[] {
+  return BUILDER_PREVIEW_REVIEWS as T[];
+}
+
+export const BUILDER_PREVIEW_FAQ_ITEMS: BuilderPreviewFaqItem[] = [
+  {
+    question: 'How fast is delivery?',
+    answer: 'Most digital products are delivered instantly after payment confirmation.',
+  },
+  {
+    question: 'Which payment methods do you accept?',
+    answer: 'Available payment methods depend on your shop configuration and region.',
+  },
+  {
+    question: 'How do I get support?',
+    answer: 'Use the contact page or your customer portal for order-related help.',
+  },
+];

package/src/product-page.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from 'bun:test';
+import { createBlockInstance } from '@shoppex/builder-contracts';
+import {
+  getBuilderBlockSettingText,
+  getLayoutPageBlockAttributes,
+  getProductPageBlockAttributes,
+} from './product-page.js';
+
+describe('product-page helpers', () => {
+  test('getBuilderBlockSettingText trims non-empty strings', () => {
+    const block = createBlockInstance({
+      type: 'buy-box',
+      settings: {
+        variantLabel: '  License Type  ',
+        addonsLabel: '   ',
+      },
+    });
+
+    expect(getBuilderBlockSettingText(block, 'variantLabel')).toBe('License Type');
+    expect(getBuilderBlockSettingText(block, 'addonsLabel')).toBeNull();
+    expect(getBuilderBlockSettingText(block, 'missing')).toBeNull();
+  });
+
+  test('getLayoutPageBlockAttributes includes page id and builder block attrs', () => {
+    const block = createBlockInstance({ id: 'gallery-1', type: 'gallery' });
+    expect(getProductPageBlockAttributes(block)).toEqual({
+      'data-page-id': 'product',
+      'data-builder-block': 'gallery-1',
+      'data-builder-block-type': 'gallery',
+    });
+    expect(getLayoutPageBlockAttributes('reviews-page', block)).toEqual({
+      'data-page-id': 'reviews-page',
+      'data-builder-block': 'gallery-1',
+      'data-builder-block-type': 'gallery',
+    });
+  });
+});

package/src/product-page.ts

@@ -0,0 +1,32 @@
+import type { BlockInstance } from '@shoppex/builder-contracts';
+import { builderBlock } from './attributes.js';
+
+export function getBuilderBlockSettingText(
+  block: Pick<BlockInstance, 'settings'>,
+  key: string,
+): string | null {
+  const value = block.settings[key];
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+
+export function getLayoutPageBlockAttributes(
+  pageId: string,
+  block: Pick<BlockInstance, 'id' | 'type'>,
+) {
+  return {
+    'data-page-id': pageId,
+    ...builderBlock(block.id, block.type),
+  };
+}
+
+export function getProductPageBlockAttributes(
+  block: Pick<BlockInstance, 'id' | 'type'>,
+) {
+  return getLayoutPageBlockAttributes('product', block);
+}
+
+/** @deprecated Use getBuilderBlockSettingText */
+export const getProductBlockText = getBuilderBlockSettingText;
+
+/** @deprecated Use getProductPageBlockAttributes */
+export const getBuilderProductBlockAttributes = getProductPageBlockAttributes;

package/src/react-runtime.test.tsx

@@ -8,8 +8,11 @@ import {
   BuilderBlockProvider,
   BuilderPage,
   BuilderRuntimePreviewProvider,
+  resolvePreviewReloadTarget,
   useBuilderContent,
   useBuilderContentRecord,
+  useThemePageBlocks,
+  useThemePageBlockAttributes,
 } from './react.js';
 
 function createSettings(revision: number, title: string): BuilderSettings {
@@ -96,6 +99,33 @@ function ScopedProbeContent() {
   );
 }
 
+function PageBlocksProbe({ pageId = 'home', defaultOrder = ['hero', 'products'] }: {
+  pageId?: string;
+  defaultOrder?: string[];
+}) {
+  const blocks = useThemePageBlocks(pageId, defaultOrder);
+
+  return (
+    <ol data-testid="page-blocks">
+      {blocks.map((block) => (
+        <li key={block.id}>{block.id}:{block.type}</li>
+      ))}
+    </ol>
+  );
+}
+
+function PageBlockAttributesProbe({
+  pageId = 'contact-page',
+  defaultOrder = ['page-contact-page'],
+}: {
+  pageId?: string;
+  defaultOrder?: string[];
+}) {
+  const attrs = useThemePageBlockAttributes(pageId, defaultOrder);
+
+  return <section data-testid="page-block-attrs" {...attrs} />;
+}
+
 function HeroBlock({ block }: { block: BlockInstance }) {
   const title = useBuilderContent('hero.title', '');
 
@@ -106,6 +136,26 @@ function HeroBlock({ block }: { block: BlockInstance }) {
   );
 }
 
+describe('resolvePreviewReloadTarget', () => {
+  test('reloads through the worker session route when one was injected', () => {
+    expect(
+      resolvePreviewReloadTarget(
+        { search: '?shoppex-preview-mode=theme', hash: '#hero' },
+        '/s/session-1/draft-1/products/example',
+      ),
+    ).toBe('/s/session-1/draft-1/products/example?shoppex-preview-mode=theme#hero');
+  });
+
+  test('keeps normal browser reload behavior outside preview sessions', () => {
+    expect(
+      resolvePreviewReloadTarget(
+        { search: '?shoppex-preview-mode=theme', hash: '' },
+        '/products/example',
+      ),
+    ).toBeNull();
+  });
+});
+
 describe('BuilderRuntimePreviewProvider', () => {
   let dom: JSDOM;
   let root: Root;
@@ -184,10 +234,47 @@ describe('BuilderRuntimePreviewProvider', () => {
       );
     });
 
-    expect(postedMessages).toContainEqual({ type: 'READY', revision: 3 });
+    expect(postedMessages).toContainEqual({
+      type: 'READY',
+      revision: 3,
+      health: {
+        reactMounted: true,
+        builderRuntimeProvider: true,
+        protocolVersion: 2,
+      },
+    });
     expect(dom.window.document.body.textContent).toContain('Initial title');
   });
 
+  test('sends READY when the trusted parent origin is provided explicitly without a referrer', async () => {
+    dom.reconfigure({
+      url: 'https://preview.shoppex.test/?shoppex-preview-mode=theme&shoppex-preview-parent-origin=https%3A%2F%2Fdashboard.shoppex.test',
+    });
+    Object.defineProperty(dom.window.document, 'referrer', {
+      configurable: true,
+      value: '',
+    });
+
+    await act(async () => {
+      root.render(
+        <BuilderRuntimePreviewProvider initialSettings={createSettings(4, 'Explicit origin title')}>
+          <Probe />
+        </BuilderRuntimePreviewProvider>,
+      );
+    });
+
+    expect(postedMessages).toContainEqual({
+      type: 'READY',
+      revision: 4,
+      health: {
+        reactMounted: true,
+        builderRuntimeProvider: true,
+        protocolVersion: 2,
+      },
+    });
+    expect(dom.window.document.body.textContent).toContain('Explicit origin title');
+  });
+
   test('normalizes mixed initial builder settings before strict validation', async () => {
     await act(async () => {
       root.render(
@@ -222,7 +309,15 @@ describe('BuilderRuntimePreviewProvider', () => {
       );
     });
 
-    expect(postedMessages).toContainEqual({ type: 'READY', revision: 9 });
+    expect(postedMessages).toContainEqual({
+      type: 'READY',
+      revision: 9,
+      health: {
+        reactMounted: true,
+        builderRuntimeProvider: true,
+        protocolVersion: 2,
+      },
+    });
     expect(dom.window.document.body.textContent).toContain('Mixed title');
   });
 
@@ -261,7 +356,39 @@ describe('BuilderRuntimePreviewProvider', () => {
       );
     });
 
-    expect(postedMessages).toEqual([{ type: 'READY', revision: 3 }]);
+    expect(postedMessages).toEqual([{
+      type: 'READY',
+      revision: 3,
+      health: {
+        reactMounted: true,
+        builderRuntimeProvider: true,
+        protocolVersion: 2,
+      },
+    }]);
+  });
+
+  test('reports iframe runtime errors to the builder parent', async () => {
+    await act(async () => {
+      root.render(
+        <BuilderRuntimePreviewProvider initialSettings={createSettings(6, 'Initial title')}>
+          <Probe />
+        </BuilderRuntimePreviewProvider>,
+      );
+    });
+
+    postedMessages.length = 0;
+
+    dom.window.dispatchEvent(new dom.window.ErrorEvent('error', {
+      error: new Error('Preview crashed'),
+      message: 'Preview crashed',
+    }));
+
+    expect(postedMessages).toEqual([expect.objectContaining({
+      type: 'PREVIEW_ERROR',
+      revision: 6,
+      message: 'Preview crashed',
+      source: 'error',
+    })]);
   });
 
   test('applies preview state and acknowledges the exact revision', async () => {
@@ -313,6 +440,91 @@ describe('BuilderRuntimePreviewProvider', () => {
     expect(dom.window.document.body.textContent).toContain('Registry title');
   });
 
+  test('returns visible page blocks or manifest default order from the runtime helper', async () => {
+    await act(async () => {
+      root.render(
+        <BuilderRuntimePreviewProvider initialSettings={createEmptyBuilderSettings(1)}>
+          <PageBlocksProbe />
+        </BuilderRuntimePreviewProvider>,
+      );
+    });
+
+    expect(dom.window.document.querySelector('[data-testid="page-blocks"]')?.textContent).toBe('hero:heroproducts:products');
+
+    await act(async () => {
+      dom.window.dispatchEvent(
+        new dom.window.MessageEvent('message', {
+          origin: 'https://dashboard.shoppex.test',
+          source: parentWindow as Window,
+          data: {
+            type: 'APPLY_STATE',
+            revision: 2,
+            state: {
+              ...createEmptyBuilderSettings(2),
+              theme: {
+                ...createEmptyBuilderSettings(2).theme,
+                layout: {
+                  home: {
+                    blocks: [
+                      { id: 'hero-1', type: 'hero', visible: true, settings: {} },
+                      { id: 'faq-1', type: 'faq', visible: false, settings: {} },
+                    ],
+                  },
+                },
+              },
+            },
+          },
+        }),
+      );
+    });
+
+    expect(dom.window.document.querySelector('[data-testid="page-blocks"]')?.textContent).toBe('hero-1:hero');
+  });
+
+  test('useThemePageBlockAttributes exposes page id and first block attrs', async () => {
+    await act(async () => {
+      root.render(
+        <BuilderRuntimePreviewProvider
+          initialSettings={{
+            ...createEmptyBuilderSettings(1),
+            theme: {
+              ...createEmptyBuilderSettings(1).theme,
+              layout: {
+                'contact-page': {
+                  blocks: [
+                    { id: 'contact-1', type: 'page-contact-page', visible: true, settings: {} },
+                  ],
+                },
+              },
+            },
+          }}
+        >
+          <PageBlockAttributesProbe />
+        </BuilderRuntimePreviewProvider>,
+      );
+    });
+
+    const section = dom.window.document.querySelector('[data-testid="page-block-attrs"]');
+    expect(section?.getAttribute('data-page-id')).toBe('contact-page');
+    expect(section?.getAttribute('data-builder-block')).toBe('contact-1');
+    expect(section?.getAttribute('data-builder-block-type')).toBe('page-contact-page');
+  });
+
+  test('shows missing registry blocks inside trusted builder preview', async () => {
+    await act(async () => {
+      root.render(
+        <BuilderRuntimePreviewProvider initialSettings={createSettings(3, 'Registry title')}>
+          <BuilderPage pageId="home" registry={{}} context={{}} />
+        </BuilderRuntimePreviewProvider>,
+      );
+    });
+
+    const missingBlock = dom.window.document.querySelector('[data-builder-runtime-error="missing-block-component"]');
+
+    expect(missingBlock?.getAttribute('data-builder-block')).toBe('hero-1');
+    expect(missingBlock?.textContent).toContain('Missing Builder component for block "hero".');
+  });
+
   test('prefers scoped block settings over global builder content inside a block provider', async () => {
     await act(async () => {
       root.render(